前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，純文本模型無法直接「看見」用戶上傳的圖片；即便切換到支持視覺的模型，對話流裏的圖像描述也往往散落在消息歷史中，不便回看和複製。視頻場景更麻煩：需要轉碼、抽幀、再交給模型逐段理解，單靠 DSH 原生界面通常不夠順手。
dsh-visual-plugin 是社區維護者 jyh20030112 爲 DSH Web 端開發的視覺媒體插件。它不單獨配置或調用私有視覺端點，而是走 DSH 原生的附件與模型路徑，並在右側 Web UI 面板裏集中展示圖像縮略圖、可複製的模型回答，以及經過規範化處理的視頻與關鍵幀分析結果。
這是什麼¶
dsh-visual-plugin（npm 包名 dsh-visual-plugin，當前版本 0.3.0）是 DeepSeek Harness 的 Web 平臺插件，採用 MIT 許可證，運行時零額外 npm 依賴。插件在 SkillHub 社區目錄中歸類爲「聯網工具」。
一句話定位：讓 DSH 當前選中的圖像能力模型原生理解用戶圖片，並對視頻做場景感知的關鍵幀抽取與分析，結果統一呈現在右側面板。
核心功能¶
原生圖像理解¶
用戶上傳的圖片走 DSH 原生附件通道，由當前選中的、具備圖像能力的模型直接作答。插件不重寫模型消息，也不調用獨立的視覺 API；模型提供商、端點與憑證均由 DSH 統一管理。
可複製的圖像歷史¶
右側面板爲每張圖片記錄縮略圖與當前模型的最終回答，支持展開歷史記錄和一鍵複製，方便把描述粘貼到別處使用。
視頻上傳與校驗¶
插件自行處理視頻上傳，僅在接受擴展名、文件簽名與 FFprobe 探測結果一致時放行，支持格式包括 MP4、M4V、MOV、AVI、MPG/MPEG、MKV、WebM。
場景感知的視頻分析¶
視頻經規範化轉爲 H.264/yuv420p MP4，再用 PySceneDetect 提取有序、帶時間戳的關鍵幀，作爲 DSH 原生圖像附件發送給當前視覺模型逐幀理解。
右側面板與高級設置¶
面板可在圖像/視頻視圖間切換，直接播放規範化後的視頻，並通過「Ask in chat」將選中視頻暫存到聊天草稿（不會自動提交）。在 Settings → Plugins → Plugin configuration 的 Visual Media 卡片中，可控制側邊欄顯隱，並調整上傳大小、存儲配額、時長、輸出尺寸、FPS、CRF、關鍵幀數量等視頻處理參數。
工作原理¶
image → DSH native attachment → current image-capable model → final answer
→ /vision-bridge/recent → panel thumbnail + copyable description
video → container validation → H.264/yuv420p normalization → PySceneDetect
→ timestamped keyframes → DSH native image attachments → current model answers
使用前須在 DSH 中先選中支持圖像的模型；插件本身不提供單獨的視覺模型配置項。
安裝與啓用¶
視頻依賴（可選）¶
圖像功能不依賴下列工具；視頻功能需要宿主機預先安裝 FFmpeg/FFprobe（>= 6.1，同一主版本，且含 libx264）和 PySceneDetect（>= 0.7.1 < 0.8）。插件不會自動下載或安裝它們，缺失時設置卡片會報告具體依賴問題。
ffmpeg -version
ffprobe -version
python -m pip install 'scenedetect[opencv]>=0.7.1,<0.8'
scenedetect version
安裝插件¶
dsh plugin --profile web add dsh-visual-plugin
也可指定 GitHub 源：
dsh plugin --profile web add github:jyh20030112/dsh-visual-plugin
安裝後重啓 dsh web。
卸載¶
dsh plugin --profile web remove dsh-visual-plugin
重啓 dsh web 後生效。
典型用法¶
經過上面的安裝步驟，按以下順序操作：
- 打開 Settings → Plugins → Plugin configuration，展開 Visual Media 卡片。用 Sidebar 控制右側面板顯隱，按需調整高級視頻參數。
- 在 DSH 模型選擇器裏選中具備圖像能力的模型。
- 發送一張圖片。模型原生作答後，右側面板會顯示縮略圖與可複製的最終回答。
- 在輸入框旁點擊 Upload video 上傳視頻。處理完成後，在右側面板切換到 Videos 視圖播放；點擊 Ask in chat 可將視頻上下文寫入聊天草稿，由你手動發送。
本地開發該插件源碼時，可先執行 npm run bootstrap，再以 link 方式安裝：
cd /absolute/path/to/dsh-visual-plugin
npm run bootstrap
dsh plugin --profile web add link:/absolute/path/to/dsh-visual-plugin
bootstrap 會自動查找同級或上級目錄中的 Harness 源碼；目錄佈局不同時可顯式指定：
HARNESS=/absolute/path/to/deepseek-harness npm run bootstrap
適用場景與注意¶
適合誰
- 已在 DSH Web 端使用支持視覺的模型，希望集中管理圖像描述歷史的使用者。
- 需要把本地視頻規範化、抽關鍵幀後交給當前 DSH 視覺模型分析的場景。
- 希望在右側面板直接預覽視頻、再把分析請求寫入聊天草稿的工作流。
使用注意
- 圖像與關鍵幀理解完全依賴 DSH 當前選中的模型；切換模型前請確認其具備圖像能力。
- 未安裝 FFmpeg 或 PySceneDetect 時，圖像功能仍可用，視頻相關能力會受限並在設置頁提示。
- 插件以當前
dsh進程的權限在宿主機上運行，視頻轉碼與文件讀寫發生在本地。安裝前應閱讀 源碼 與 MIT 許可證，確認符合你的安全與合規要求。 - SkillHub 社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件列表由社區維護，安裝前自行甄別。
結語¶
dsh-visual-plugin 把 DSH 原生的圖像理解能力與場景感知的視頻關鍵幀分析接到統一的 Web 右側面板，減少在對話歷史裏翻找描述、手動處理視頻的步驟。若你已在 DSH Web 端配置好視覺模型，可按本文命令安裝試用。
