前言¶
DeepSeek Harness (DSH) 的插件生态允许开发者扩展本地智能体的能力。现有的视频转笔记工具大多只能生成通用的摘要，无法捕捉观看者的个人视角。dsh-youtube-study-notes 插件解决了这个问题：它不仅提取视频自带字幕，还通过视觉模型读取屏幕内容，并在处理过程中暂停，询问观察者的所见所想，最终将这三者合并为一份文档。
插件定位¶
这是一个 DSH 插件，旨在将 YouTube 视频链接转化为结构化的学习笔记。插件由 jagathsrujan 维护，遵循 MIT 许可证。它本质是一个 Skill，通过驱动本地工具（如 yt-dlp、ffmpeg）来执行工作流，而非包含运行时代码。
核心功能¶
插件的工作流包含以下步骤：
- 字幕获取：使用
yt-dlp获取字幕。优先使用人工字幕，自动生成的字幕作为备选。不使用第三方语音识别服务。 - 大纲生成：读取带有时间戳的字幕全文，生成章节大纲。
- 视觉通过（可选）：使用
ffmpeg进行场景检测并采样帧，让视觉模型读取屏幕上的文字、代码、公式或图表。 - 交互提问：在处理过程中暂停，询问观察者个人的观察内容。
- 内容合并：将字幕、视觉证据和用户笔记合并为一个 Markdown 文件。
- 保存与清理：生成
notes.md，并删除临时文件（帧截图和视频文件），仅保留证据文件。
输出文件¶
插件会在当前目录下保留以下文件作为证据：
* transcript.md / transcript.txt
* meta.json
* notes.md
安装与启用¶
通过 CLI 安装插件：
dsh plugin --profile <your-profile> add dsh-youtube-study-notes
安装完成后需要重启配置文件，以使 bundle 更改生效。在桌面客户端中，请通过 Plugins → Add plugin 流程操作。
典型用法¶
触发插件有两种方式：
- 直接指令：
/youtube-study-notes https://youtu.be/VIDEO_ID
- 自然语言：
在对话中输入类似 “get me notes from this video: …” 的请求，并附带链接。
环境依赖¶
插件本身不包含运行时代码，其核心是驱动本地工具的 Skill。安装前请确保系统中已安装以下工具：
| 工具 | 用途 | 安装建议 |
|---|---|---|
python3 |
运行脚本 | brew install python3 |
ffmpeg / ffprobe |
音视频探测、场景检测、帧提取 | brew install ffmpeg |
yt-dlp |
字幕列表与下载 | brew install yt-dlp |
插件会检测缺失的工具，并在确认后等待安装。
启用视觉通过¶
视觉通过功能需要模型配置声明支持图像输入。默认情况下，许多模型配置仅允许文本输入。如果未正确配置，插件会提示错误并询问使用哪个支持图像的模型。
在 cordis.patch.yml 中为模型添加 input 配置：
- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:
providers:
your-provider:
# ...existing provider config...
models:
- id: "your-vision-model"
name: "Your Vision Model"
contextWindow: 200000
input:
- text
- image
注意：仅当端点实际支持图像时才声明此配置。如果声明了但服务端拒绝，会导致消息持久化失败。
限制与注意事项¶
- 无字幕视频会终止运行：如果视频没有字幕（包括自动生成的），插件会停止并报错，不会生成任何内容。
- 自动字幕质量有限：自动生成的字幕通常没有标点符号，且可能听错专有名词。插件会明确告知使用了哪种字幕。
- 视觉识别的字符级误差：视觉模型在识别字符时可能出现错误（例如将句号识别为连字符，数字 1 识别为字母 l）。对于代码和公式，需要人工校对。
- 帧采样的局限性：
ffmpeg场景检测采样的是镜头，而非运动。一个连续的镜头内的动态变化可能无法被捕捉。 - 仅限个人学习：字幕、截图和笔记均来自他人的作品，请勿公开发布。
结语¶
dsh-youtube-study-notes 提供了一种从被动观看转向主动学习的机制。它通过合并外部内容与个人观察，生成了更具个人色彩的学习资料。更多详情可参考插件目录页或 GitHub 仓库。
