前言¶
在 Harness 裏做智能體或本地工具鏈時，經常會遇到「手頭有一條視頻/直播回放鏈接，想落到本地再處理」：瀏覽器裏另存爲往往沒有畫質可選，命令行自己拼 yt-dlp 又要記代理、Cookie 和輸出目錄。社區插件 dsh-yt-downloader（維護者 chen-bi，分類：聯網工具）把這一套收進 DSH 左側欄：粘貼鏈接 → 解析 → 選畫質或只抽音頻 → 看隊列進度，底層調用自帶的 yt-dlp（README 寫明隨插件版本爲 2026.10.26），覆蓋 README 所列的 YouTube、B 站、X/Twitter、直鏈等 1000+ 站點能力（具體能否解析取決於 yt-dlp 與站點策略）。
這是什麼¶
dsh-yt-downloader 是 DeepSeek Harness 的視頻下載器插件：package.json 版本 1.0.0，MIT 許可證，peer 依賴 @deepseek-ai/cordis ^4.0.1 與 react ^18.3.1。Host 側 index.js 暴露 /api/ytdl/* 與 youtube_download 工具；客戶端 client.js 提供側邊欄圖標與下載面板。vendor/ 內自帶 yt-dlp，通過 python -m yt_dlp 調用，避免污染全局 Python 環境。
核心功能¶
面板內操作流程¶
README 給出的步驟如下：
- 左邊欄點 視頻下載器（在「命運牌桌」下面）。
- 把鏈接粘進輸入框，按 解析（或回車）。
- 解析成功後顯示封面、標題、來源站點、時長，再選一個畫質點 下載。
- 隊列裏實時顯示進度、速度、剩餘時間；完成後可「打開文件」或「打開文件夾」。
視頻：按分辨率分檔，優先 H.264；站點只提供「畫面+聲音一體」格式時直接下載該條；對無分辨率信息的直鏈提供「最佳」選項。僅音頻：取最優音軌並轉 MP3。播放列表或頻道鏈接 只取第一條，不會整表拉取。
代理與 Cookie¶
YouTube、X 等站點在國內常需代理。插件默認 跟隨 Windows 系統代理（讀註冊表 Internet Settings）；面板「設置」也可手寫代理（例如 127.0.0.1:7897，留空表示自動）。設置頁會探測代理是否在監聽；代理未開啓時解析會提示「代理沒在監聽」，而不是長時間超時。
遇到登錄牆或地區/會員限制時，README 建議：換代理節點重試，或在 設置 → 瀏覽器 Cookie 中選擇已在該站登錄過的瀏覽器（Chrome / Edge / Firefox）。選用前需 完全退出對應瀏覽器（Cookie 庫被佔用時 yt-dlp 無法讀取）；Firefox 相對最穩，部分新版 Chrome/Edge 的 App-Bound 加密仍可能無法解密。站點根本不受支持時，會明確返回 yt-dlp 不認識這個鏈接。
存儲與安全邊界¶
默認下載目錄爲 C:\Users\<你>\Downloads，可在設置中修改。文件名格式：<標題> [<id>].<ext>。插件 只接受 http(s) 鏈接，拒絕 file://、本地路徑及其他協議。下載任務在內存中維護，DSH 重啓後隊列清空（已下載文件仍保留）。付費/會員/DRM 等內容能否下載取決於站點與 yt-dlp，README 明確受限內容可能無法下載。
安裝與依賴¶
官方 README 的安裝路徑是本地 bundle，而非 dsh plugin add 一類拼接命令。按順序執行：
# 1. 克隆（vendor/ 裏的 yt-dlp 不進倉庫，克隆後要單獨裝一次）
git clone https://github.com/chen-bi/dsh-yt-downloader.git
cd dsh-yt-downloader
# 2. 裝 yt-dlp 到 vendor/
node scripts/setup-ytdlp.mjs
# 3. 裝插件（在 DSH 裏讓助手裝）：plugin_manager → install_bundle，target 指向本目錄
# 4. 卸
plugin_manager → remove_bundle → dsh-yt-downloader
裝完後 刷新頁面（新客戶端包需重新加載）。package.json 中也可通過 npm run setup 等價執行 node scripts/setup-ytdlp.mjs。
運行期依賴（來自 README）：
- Python 3：優先使用 uv 安裝路徑（
%APPDATA%\uv\python\…），否則退回 PATH 中的python。 - yt-dlp：位於
vendor/，隨插件分發。 - ffmpeg：合併畫面與音軌、轉 MP3 時使用；自動查找
~\.pyffmpeg\bin\ffmpeg.exe。
自檢腳本：node smoke.mjs [--probe]、node client-smoke.mjs；真下載測試爲 download-test.mjs（臨時目錄，跑完清理）。
典型用法與調試接口¶
日常用法即上文「面板內操作流程」。若要從腳本或調試側調用，README 列出 Host API：
| 方法 | 路徑 | 用途 |
|---|---|---|
| GET | /api/ytdl/state |
引擎狀態、代理、下載目錄、隊列 |
| POST | /api/ytdl/probe |
{url} → 標題/封面/站點 + 畫質列表 |
| POST | /api/ytdl/download |
{url, mode, formatId, merge, …} → 建任務 |
| GET | /api/ytdl/jobs |
隊列與進度 |
| POST | /api/ytdl/cancel |
{id} 取消 |
| POST | /api/ytdl/remove |
{id} 從隊列移除 |
| POST | /api/ytdl/open |
{path, reveal} 打開文件 / 定位文件夾 |
| POST | /api/ytdl/settings |
{proxy, downloadDir, cookiesFrom} 保存設置 |
解析一步對應 POST /api/ytdl/probe，body 爲 { "url": "<你的 https 鏈接>" }，返回可供面板展示的畫質列表後再 POST /api/ytdl/download 建任務，並用 GET /api/ytdl/jobs 輪詢進度。
適用場景與注意¶
適合需要在 Windows 上的 DSH 客戶端裏快速試鏈、選畫質、本地化素材的開發者或個人使用（代理與 Cookie 邏輯按 README 面向 Windows 系統代理與本地瀏覽器）。社區目錄 SkillHub 插件頁 與 GitHub 倉庫當前星標爲 0，介紹頁另見 https://chen-bi.github.io/dsh-yt-downloader/。
安裝前宜自行查看源碼與 MIT 許可證；插件以 當前 DSH 進程權限運行，會讀取系統代理、瀏覽器 Cookie 路徑並寫入你配置的下載目錄。README 提醒：個人觀看與存檔無妨，二次分發他人內容須遵守平臺條款與版權。DSH 生態強調「一切皆插件」；SkillHub 等爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-yt-downloader 把 yt-dlp 的站點能力與 Harness 側邊欄 UI 合在一起：解析、選檔、隊列進度和代理/Cookie 設置都在面板內完成，減少反覆開終端。進一步瞭解可訪問目錄頁 https://www.skillhub.cn/plugins/chen-bi/dsh-yt-downloader 與倉庫 https://github.com/chen-bi/dsh-yt-downloader。
