前言¶
在 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。
