| name | youtube-skill |
| description | YouTube 操作总入口。以 intent-identification 为入口澄清意图，协调 youtube-downloader、youtube-search、use-notebooklm、youtube-to-pdf 四个子 skill 执行。 |
| tier | router |
YouTube Skill
YouTube 相关操作的统一编排入口。intent-identification 是入口，不直接执行搜索/下载/分析。
用户请求 → intent-identification（澄清意图）→ intent_contract_v1 → 路由到子 skill
子 Skill 矩阵
执行流程
⛔ 硬性关卡
0. 认证检查（每次 YouTube 操作前）
- 所有 yt-dlp 操作（搜索/下载/评论）都依赖有效 cookies
- 如果上次提取 cookies 超过 24 小时，或任何操作报认证错误 → 先执行 Quick Auth Recovery
- 搜索失败 = 90% 概率是 cookies 过期，不要重试，直接刷新 cookies
- Quick Auth Recovery 步骤
1. 时间获取（最优先）
- 执行任何任务前，必须先获取当前真实时间
- 时间信息应包含：年月日时分秒，以及时区信息
- 将时间作为系统上下文传递给后续所有步骤
2. 意图澄清
- 任何涉及搜索的请求，严禁跳过 intent-identification 直接执行。
3. 输出目录确认（如有内容产出）
- 如果任务会产生文件/数据输出（如下载视频、保存搜索结果、生成报告等），必须在 intent-identification 阶段与用户确认数据保存的根目录
- 若用户未指定，提供合理的默认路径（如
./output/ 或 ./downloads/）并征求同意
- 确认后的输出目录需写入 intent_contract_v1 的
constraints 中
错误: 用户"找 AI 生产力视频" → 直接搜 "AI productivity" ❌
正确: 用户"找 AI 生产力视频" → intent-identification 澄清 → 合同 → 路由 ✅
标准流程
1. 获取当前真实时间
在执行任何任务前，先获取当前真实时间（年月日时分秒）
将时间信息作为上下文，供后续步骤使用
2. intent-identification
用户请求 → 澄清对话 → 产出 intent_contract_v1
意图不清时返回 NEEDS_CLARIFICATION，继续追问
3. 合同解读
从 intent_contract_v1 中提取：objective, targetSubject, explorationAngles, constraints
若任务涉及内容产出，确认 constraints.outputDir 已明确
4. 路由到子 skill
├─ 搜索类 → youtube-search（关键词由意图校准结果决定，非用户原始表述）
│ └─ 搜索后必须：python E:\projectHome\youtube-vault\backend\dedup_import.py --file <results.json>
│ 自动去重入库，避免下次搜索返回相同视频
├─ 下载类 → youtube-downloader
├─ 分析类 → use-notebooklm
├─ 教程/PDF类 → youtube-to-pdf（视频→NotebookLM→Markdown→PDF）
└─ 混合类 → 串行协调多个子 skill
意图校准的典型对话
用户: "帮我找 AI 生产力方面的视频"
编排者（走 intent-identification）:
"你说的「AI 生产力」，更像哪种？
(a) Notion AI / 自动化工作流搭建 — 实操工具教程
(b) AI 工具横向测评 — 哪个效率工具最好用
(c) 个人效率提升方法 — 怎么用 AI 省时间
(d) 企业级 AI 提效 — 团队/公司怎么落地"
用户选择 → 生成 intent_contract_v1 → 路由到 youtube-search
关键词映射（intent-identification 中完成）
| 用户说的 | 可能实际想要的 | 映射到的搜索词 |
|---|
| "人类学视频" | 部落 Vlog | living with tribes vlog |
| "人类学视频" | 历史纪录片 | ancient civilizations documentary PBS |
| "人类学视频" | 学术入门 | introduction to anthropology lecture |
| "AI 创业" | 赚钱实操 | how to make money with AI |
| "AI 创业" | 创始人故事 | AI startup founder journey |
| "AI 创业" | 工具搭建 | AI automation agency tutorial |
路由决策树
用户请求
│
├─ 1. intent-identification（必须，不可跳过）
│ 产出 intent_contract_v1 { status: READY | NEEDS_CLARIFICATION }
│
├─ 2. 合同 READY → 解读 objective + constraints → 路由
│ │
│ ├─ deliverable 含 "search" / "find" / "videos"
│ │ └─ youtube-search（用校准后的关键词，非原始表述）
│ │
│ ├─ deliverable 含 "download" / "mp4" / "audio"
│ │ └─ youtube-downloader（CDP cookies + yt-dlp）
│ │
│ ├─ deliverable 含 "analyze" / "tutorial" / "podcast" / "deep dive"
│ │ └─ use-notebooklm（CDP auth → source add → progressive asks）
│ │
│ ├─ deliverable 含 "pdf" / "教程" / "书面教程" / "文档"
│ │ └─ youtube-to-pdf（NotebookLM 渐进式提取 → Markdown → md-to-pdf → PDF）
│ │
│ └─ deliverable 含多步骤
│ └─ 串行协调：youtube-search → use-notebooklm → 产出
│
└─ 3. 合同 NEEDS_CLARIFICATION
继续追问，直到 READY
典型链路
链路 A：搜索 → 分析 → 教程
1. intent-identification
"找 AI 创业的高流量视频深挖成教程"
→ 澄清：赚钱实操 or 创始人故事 or 工具教程？
→ 用户选 b → contract READY
2. youtube-search
queries: "AI startup founder journey, how I built AI company"
→ 用户挑选 3 个视频
3. use-notebooklm（对每个选中视频）
cdp_login.py → notebooklm create → source add → 渐进式提问 → chapters/*.md
链路 B：纯搜索
1. intent-identification
"找人类学田野调查的 Vlog"
→ 校准："跟哈扎族打猎" or "PBS 纪录片" or "学术讲座"？
→ 用户选 a → contract READY, explorationAngles: ["tribe vlog", "living with"]
2. youtube-search
queries: "living with tribes vlog, tribe visit documentary"
→ 列出视频 URL + 观看量
链路 C：直接下载
1. intent-identification
"下载这个视频 https://youtube.com/watch?v=xxx"
→ 意图明确，直接 READY
2. youtube-downloader
提取 CDP cookies → yt-dlp 下载
链路 D：视频 → PDF 教程
1. intent-identification
"把这个视频转成详细书面教程，最终要 PDF"
→ 意图明确，直接 READY
2. youtube-to-pdf（4 阶段）
Phase 0: cdp_login.py 刷新 NotebookLM 认证
Phase 1: notebooklm create + source add（YouTube URL）
Phase 2: 渐进式提取（英文提问，逐章保存为 Markdown）
Phase 3: 编排层翻译为中文 Markdown
Phase 4: Python 合并 + md-to-pdf → PDF
与子 Skill 的关系
- intent-identification 是入口：所有请求先过它，不过它不执行
- 不替代任何子 skill
- 不重复实现子 skill 的功能
- 子 skill 保持独立可运行，不依赖本 skill
- intent_contract_v1 是所有子 skill 的共同输入格式
YouTube Vault 集成（搜索去重）
每次搜索完成后，必须自动去重入库：
python E:\projectHome\youtube-vault\backend\dedup_import.py \
--file "F:\youtube_data\ai-money-videos\search_xxx\results.json" \
--output "F:\youtube_data\ai-money-videos\search_xxx\results_new.json"
效果：
- 新视频自动入库，旧视频自动跳过
- 输出
results_new.json 仅包含新视频（可直接用于展示）
- 下次搜索时同一视频不会再出现在"新结果"中
Vault UI 查看：
http://127.0.0.1:8766
（需先启动 python E:\projectHome\youtube-vault\backend\server.py）
前置环境
- Bun、Python 3、yt-dlp
- Chrome（已登录 YouTube/Google）
notebooklm-py CLI + curl_cffi + websocket-client- bgutil PoToken server（下载时需要）
md-to-pdf（npm global，PDF 教程产出时需要）
故障排除
| 症状 | 可能原因 | 解决 |
|---|
search_videos.js 报 JSON Parse error | cookies 过期 | Quick Auth Recovery：Kill Chrome → CDP 启动 → 提取 cookies |
search_videos.js 返回空结果 | 搜索词太窄 / cookies 无效 | 先用宽泛词验证，再精炼；同时检查 cookies |
| 下载被拒 "Sign in to confirm" | bot 检测 | youtube-downloader：bgutil + CDP cookies 双保险 |
| NotebookLM 认证失败 | SID 缺失 | use-notebooklm → cdp_login.py |
NotebookLM ask 返回乱码 | 中文编码不稳定 | 改用英文提问，编排层翻译 |
md-to-pdf 首次运行卡住 | 正在下载 Chromium (~280MB) | 等待，仅首次需要 |
| PDF 章节内容太浅 | ask 提问不够具体 | 用 Round 模板，每章明确列出 3-5 个要点 |
| 意图不清反复追问 | 用户自己也不知道要什么 | 给出 2-3 个具体例子让其选择 |
| bgutil-start 报 "系统找不到指定的文件" | bgutil 项目未构建 | cd E:\projectHome\bgutil-ytdlp-pot-provider\server; npm run build 然后重试 |
