前言¶
在 DeepSeek Harness（DSH）里做资料整理、离线观看或备份时，经常需要把 YouTube、哔哩哔哩、X 等链接落到本机文件。直接在终端拼 yt-dlp 参数、自己处理 ffmpeg 和队列，对日常使用者成本偏高；纯 Web 下载站又往往不经过本机、也难以和 Harness 对话联动。
dsh-video-downloader（维护者 Raymond-Hear）是 DSH 社区目录中的联网工具类插件：侧栏提供「视频下载」页面，贴链接后由本机 yt-dlp 解析并下载视频、音频、字幕或封面，并在同一界面管理队列与进度。它本质是 yt-dlp 的图形前端，解析与落盘仍在你的电脑上完成。
这是什么¶
- 名称：dsh-video-downloader（界面显示「视频下载器」）
- 仓库：https://github.com/Raymond-Hear/dsh-video-downloader
- 当前版本（package.json）：1.3.0，许可证 MIT
- 定位：贴链接 → 解析预览 → 选模式与画质 → 入队下载；支持 YouTube、哔哩哔哩、X、TikTok 及 yt-dlp 覆盖的上千站点（完整列表可用
yt-dlp --list-extractors查看）
README 明确说明：仅供个人学习与备份；项目不托管、不分发内容，请遵守当地法律与平台服务条款。
核心功能¶
本机依赖与一键安装¶
插件会按顺序探测 yt-dlp：插件 bin/ 单文件 → 系统 yt-dlp → python3 -m yt_dlp 等，一般无需手动配 PATH。未安装时可在页面一键安装对应系统的官方单文件版（Windows / macOS / Linux）；GitHub 超时会尝试镜像，再不行退回 pip install。
ffmpeg 用于高清合并、MP3、字幕转 srt、内嵌字幕、封面转 jpg。缺 ffmpeg 时不会整页报错，会降级到可下载形态并在任务行说明；也可从 PyPI 的 imageio-ffmpeg 静态构建一键装进插件 bin/，无需 Homebrew 或 sudo。
默认保存目录为 ~/Downloads/YT-DLP，可在页面底部修改。Cookies 支持上传 cookies.txt，或读取 Edge / Firefox 的 Cookie（会员、年龄/地区限制等场景常用）。
面板用法¶
界面为单列卡片（链接 → 解析 → 模式/画质 → 开始）加下载队列表格。解析后可看标题、UP 主、时长、播放量、封面、可选清晰度与字幕数量；封面支持页面内试播（临时直链，不落盘）。
四种下载模式：视频（最佳及 2160p～360p）、仅音频（MP3）、仅字幕（srt）、仅封面（jpg）。高级选项包括时间片段、播放列表范围、跳过已下载、代理、限速、并发 1–3、完成后自动打开等；队列支持暂停/继续（断点续传）、取消、失败重试，进度含速度与剩余时间。
对话中的 Agent 工具¶
除面板外，插件向 Agent 注册 4 个工具，与面板共用同一队列：
| 工具 | 作用 |
|---|---|
video_probe |
解析链接：标题、作者、时长、清晰度、字幕数、是否直播 |
video_download |
加入队列（video / audio / subs / thumb），立即返回任务编号 |
video_jobs |
查询进度、成品路径、错误原因 |
video_control |
cancel / pause / resume |
示例说法（README 原文）：
帮我把这个视频的字幕下下来，然后读一遍整理成中文要点：https://www.youtube.com/watch?v=…
把这个视频下成 720p，下完告诉我文件在哪。
设计要点：video_download 只返回「任务已创建」，避免长下载导致工具超时；cookies 不走工具参数，使用本机已存凭据。
安装与启用¶
安装需要 Harness 的 danger-full-access 权限，按提示批准一次即可。
方式一（推荐）：在 DSH 对话里发送：
帮我安装这个插件：https://github.com/Raymond-Hear/dsh-video-downloader
Agent 会调用 plugin_manager 的 install_bundle，将仓库作为安装源装入当前 profile 并默认启用。也可使用 github:Raymond-Hear/dsh-video-downloader。装好后侧栏点「视频下载」；在 设置 → 插件 中应能看到「视频下载器」。
方式二：若当前 Harness 不接受 git 地址安装，需先克隆仓库到本地，再让 Agent 对克隆目录的绝对路径执行 install_bundle，或在插件管理页选择该目录安装（README 给出的克隆命令见仓库说明）。
npm 包：维护者发布并去掉 package.json 中 "private": true 后，可安装包名 dsh-video-downloader（以仓库发布状态为准）。
首次打开：无 yt-dlp 时顶部有一键安装；无 ffmpeg 时有黄色提示与一键安装。更新可点页脚版本号比对 GitHub Release；卸载在插件管理器移除 bundle，已下载文件与 %LOCALAPPDATA%\dsh-ytdlp\（macOS/Linux：~/.local/share/dsh-ytdlp/）中的记录不会自动删除。
典型用法¶
- 侧栏打开「视频下载」，粘贴公开视频链接，等待解析。
- 选择模式（如 1080p 视频、仅 MP3、仅 srt 字幕）与是否需要播放列表、内嵌字幕等，点击开始下载。
- 在队列表格查看进度；需要时在对话中说「暂停刚才的任务」或调用
video_jobs查路径。
公开内容在 README 已验证场景中，YouTube、X、哔哩哔哩在无 cookie 下可解析；仅字幕连续测试可能触发 YouTube 429，宜间隔重试。macOS / Linux 的完整回归以 README「已验证的环境与场景」为准，勿把未验证组合当作支持承诺。
适用场景与注意¶
适合：已在用 DSH、希望在本机用 yt-dlp 统一下载多平台视频/音频/字幕，并希望在对话里让 Agent _probe、入队、查进度的人。
注意：
- 插件以当前 DSH 进程权限运行，安装前请自行查看源码与 MIT 许可证，确认可接受其读写本机下载目录、cookies 与
dsh-ytdlp状态目录等行为。 - 下载能力来自 yt-dlp（Unlicense）；站点解析问题更适合向 yt-dlp 反馈。勿称本插件为 yt-dlp「官方」产品。
- DSH 社区插件目录（SkillHub 条目）为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-video-downloader 把 yt-dlp 的常用参数和队列收进 DSH 侧栏与 Agent 工具，减少在本机反复敲命令的成本，同时保留「数据不出本机、凭据不进对话参数」的边界。需要安装或细节时，以仓库 README 为准。
