前言¶

在 DSH 裏看視頻，通常有兩條路：從右側欄的文件系統、聊天文件引用或別的插件的文件樹裏點開一個 .mp4，落到瀏覽器默認播放器；或者把文件複製出去，交給專門的播放器。這兩種做法在處理篩查 Agent 生成的錄屏、逐幀看動畫時都不太順手：瀏覽器默認播放器裏拖動進度條會回彈到上一個關鍵幀，框住畫面時縮放基本沒用，逐幀也做不了。

下面介紹的 dsh-quicktime-player 就是把這兩件事收進右側欄：註冊一個自定義 tab 類型，視頻無論從哪裏被打開都落到同一個播放器裏，支持 Range 流式拖動、滾輪縮放、拖動平移、逐幀步進，以及截幀和按標記導出片段。

這是什麼¶

dsh-quicktime-player 是社區維護的 DSH 插件，維護者 rUrU516，分類爲客戶端。它聲明在當前倉庫的 package.json 裏，版本 0.4.0，許可證 MIT。

一句話定位：DSH 右側欄裏的視頻播放器，解決的是“視頻在 DSH 裏怎麼好好看”的問題——能拖進度、能縮放平移、能逐幀、能截取，而不是簡單地把 <video> 塞進一個 tab。

核心功能¶

視頻來自哪裏都能播¶

插件註冊了自己的右側欄 tab 類型，通過 ctx.sidebarRightTabs.register 認領視頻地址。視頻可以來自 DSH 文件 tab、聊天文件引用、其他插件的文件樹，或者 sidebar_open；無論哪種來源都會落到這個播放器裏，不需要額外安裝或改造別的插件。

進度可以拖，字節不進內存¶

Host 側用一條路由以 HTTP Range 頭返回 206，所以進度條是真正的拖動，而不是跳回最近的關鍵幀。大文件也不會被整個讀進內存：字節留在磁盤上，按 Range 一段段取。

桌面端也支持拖動¶

Electron 殼裏頁面從 dsh-app:// 提供，Chromium 在跨 scheme 時無法對 <video> 做 seek。插件因此改爲從帶 token 的 127.0.0.1 端口拉流；當該端口不可用時，退化回同源路由。

縮放與平移¶

滾輪在指針位置縮放，範圍 1×–8×；縮放狀態下拖動可以平移。平移會停在畫面邊緣，不會出現把視頻拖出畫框外的情況。雙擊切換全屏。

自帶的控制條¶

播放/暫停、時間與幀號切換、速度滑塊（0.2×–5×，0.2 爲步長）、循環、垂直音量彈窗、靜音、畫中畫、全屏，都由播放器自己提供。鼠標靜止時控制條會淡出。

逐幀步進¶

← / → 每次走一幀，幀率由實際送出的幀測量得到，不是寫死的常量。

記住上次播放位置¶

按文件的絕對路徑記錄位置、速度、循環、音量和靜音，最多保留最後 50 個文件，30 天后失效。切換會話再回來，會回到同一個位置。如果文件被重新渲染、時長變了，舊記錄會被丟棄，而不是跳到一個無關的位置。

截幀、剪片段、檢查更新¶

? 旁邊的相機按鈕把當前播放頭的畫面以 PNG 寫入剪貼板，失敗時退化爲下載，完成時彈出提示。

剪刀按鈕在播放頭處打一個標記；同時最多保留兩個標記，中間用虛線連接，懸停剪刀按鈕會出現保存/清除。保存會調用 Host 的 ffmpeg 做流複製（stream copy），因此片段與源字節一致，不重新編碼，切在最近的關鍵幀上。如果 Host 沒有 ffmpeg，按鈕會直接說明，而不是靜默失敗。

? 旁邊的雲按鈕向 Host 查詢當前安裝版本和 registry 上的最新版本，在對話框裏報告結果。只支持手動檢查，沒有輪詢、角標和自動安裝。

跟隨 DSH 主題¶

控制條（標題欄、引導卡、對話框、通知）使用 DSH 的 --dsw-alias-* 變量繪製，所以在淺色主題下播放器是淺色的；視頻畫面區域保持深色。如果變量不存在，會退化回一直使用的深色配色。

內置引導¶

角落裏的 ? 會蓋一層可點擊的引導卡，每個功能一行，圖標與工具欄一致。它是純文本，不需要額外維護箭頭對齊。

鍵盤不被搶佔¶

只要焦點在播放器內部，即使焦點落在滑塊上，Space 和方向鍵都留給播放器本身。

安裝與啓用¶

先確認宿主 DSH 使用 profile bundles（插件聲明瞭 dsh.bundle.patch），然後執行：

dsh plugin --profile <profile> add dsh-quicktime-player

安裝後需要重開一次窗口，讓客戶端 bundle 被重新加載。

前置要求¶

• DSH 支持 profile bundles。
• 只有在導出片段時才需要 Host 上有 ffmpeg。查找順序爲 /opt/homebrew/bin/ffmpeg、/usr/local/bin/ffmpeg，最後是 PATH 上的 ffmpeg。沒有它的前提下，播放、截幀等其他功能正常，保存按鈕會提示 Host 上沒有 ffmpeg。

插件不需要任何配置項：路由前綴、4 GiB 上限、迴環媒體服務端口以及工作目錄限制都是寫死的。

典型用法¶

用快捷鍵操作¶

鍵盤操作一覽：

導出一段片段¶

1、把播放頭移到片段起點，點擊剪刀按鈕，打第一個標記。
2、把播放頭移到終點，再點一次剪刀按鈕，打第二個標記；兩點之間會出現虛線。
3、懸停剪刀按鈕，選擇保存。Host 會執行類似下面的邏輯：用 ffmpeg 以 -ss、-t、-c copy 處理，音頻和視頻流直接複製，不重新編碼；臨時文件在發送完成後刪除。

沒有 ffmpeg 時，保存按鈕會提示“宿主上沒有 ffmpeg”，這時可以從 ~/.dsh/quicktime-player.log 裏確認解碼和導出過程中的報錯。該日誌文件按播放器事件逐行寫入 JSON，包含 source 解析、元數據和解碼錯誤。

確認客戶端 bundle 是否已加載¶

如果改完窗口發現還是舊界面，可以發一個請求看客戶端 bundle 是否進入了模塊圖：

GET /quicktime/_graph

這是一個開發期探針，返回模塊圖的檢查結果。

適用場景與注意¶

適合需要在 DSH 裏審查視頻的開發者，尤其是 Agent 生成錄屏後想直接逐幀看、想截取某一幀或剪一小段的情況。由於它把視頻播放和導出能力掛到 DSH 進程上，安裝前應先打開源碼和 LICENSE 看過：插件以當前 DSH 進程的權限運行，路由路徑被限制在會話工作目錄內，4 GiB 以上的文件走的是固定的 Range 上限。

環境與依賴¶

• 播放、縮放、逐幀、截幀都不依賴 ffmpeg，只有導出片段會調用。
• .mkv、.avi、.wmv、.flv 會被接受，但 Chromium 無法解碼，播放器會如實報告，而不是假裝在播放。
• 更新檢查依賴 Host 能訪問 registry.npmjs.org；離線、代理或 DNS 問題時，對話框會顯示“檢查失敗”。
• 社區目錄頁顯示該插件 0 星，但功能自足，不依賴其他插件，核心就是“一個 tab 類型加一條路由”。

結尾¶

dsh-quicktime-player 的定位很簡單：把視頻播放收進 DSH 右側欄，並保證拖動、縮放、逐幀和導出的幾個關鍵動作都可用。如果你的痛點是瀏覽器默認播放器拖不動進度、無法對着幀看，它是目前結構上比較對路的方案。

• 目錄頁：https://www.skillhub.cn/plugins/rUrU516/dsh-quicktime-player
• 倉庫：https://github.com/rUrU516/dsh-quicktime-player