| name | tech-learning-roadmap |
| description | 技术学习路线图生成器。用户输入想学习的主题和目标后，结合用户基础和 YouTube 搜索结果， 生成一条可执行的视频学习路线图。触发词：「学习路线」「学习路线图」「帮我规划学习」 「学习路径」「技术学习」「roadmap」「学习计划」「给我一个学习方案」「我想学」「从零学」 「入门到」「学习规划」+ 任何技术主题。当用户想制定技术学习计划、需要视频资源推荐、 或需要分阶段学习方案时触发此 Skill。
|
技术学习路线图生成器
YouTube CLI
使用本 Skill 自带的轻量 CLI，不需要启动 FastAPI 服务。
脚本路径：scripts/youtube_cli.py（相对于本 SKILL.md）
执行下列命令时，将工作目录设置为本 Skill 目录。
配置 API Key
默认配置文件：config.json（与本 SKILL.md 同目录）。
打开该文件，将获取到的 Key 填入 youtube_api_key：
{
"youtube_api_key": "AIzaSy...你的实际Key"
}
注意：
- Key 前后必须保留英文双引号，文件必须是合法 JSON。
- 不要把填写了真实 Key 的配置文件分享到公开仓库、聊天记录或截图中。
- CLI 会自动定位 Skill 目录中的配置文件，不受当前工作目录影响。
- 也可用
--config C:\path\to\config.json 指定其他配置文件。
API Key 读取优先级：--api-key → YOUTUBE_API_KEY → GOOGLE_API_KEY → config.json。
如需使用环境变量：
$env:YOUTUBE_API_KEY = "你的 API Key"
获取 YouTube Data API Key
- 登录 Google Cloud Console；没有 Google Cloud 项目时，先在顶部项目选择器中新建项目。
- 打开 YouTube Data API v3 页面，确认当前选中的是刚才的项目，然后点击“启用”。
- 打开 API 和服务 → 凭据，点击“创建凭据” → “API 密钥”。
- 复制生成的 Key，填写到本 Skill 的
config.json。
- 建议立即点击“编辑 API 密钥”进行限制：
- “API 限制”选择“限制密钥”，只允许 YouTube Data API v3。
- “应用限制”应根据实际运行环境设置。仅在自己电脑使用且没有稳定公网 IP 时，可暂不设置应用限制，但必须妥善保管 Key；部署到固定服务器时建议限制服务器公网 IP。
- 保存后运行下方搜索示例进行验证。Google Cloud 的设置偶尔需要等待几分钟才会生效。
本 CLI 只读取 YouTube 公开数据，不需要 OAuth 客户端 ID；普通 API Key 即可。API 请求会消耗项目的 YouTube Data API 配额。
CLI 使用
可用命令：
python scripts/youtube_cli.py search --q "{关键词}" --max-results {数量} --order {排序} --video-duration {short|medium|long} — 关键词搜索视频python scripts/youtube_cli.py video {video_id} — 查询单个视频详情（含时长、播放量、标签等）python scripts/youtube_cli.py videos {id1} {id2} — 批量查询视频详情（最多 50 个）python scripts/youtube_cli.py channel-videos {channel_id} --max-results {数量} --days-back {天数} — 查询频道近期视频
所有成功结果以 JSON 输出到 stdout；错误以 JSON 输出到 stderr 并返回非零退出码。
搜索参数说明：
order: relevance（默认）| date | viewCount | rating--video-duration: short（<4min）| medium（4-20min）| long（>20min）--published-after/--published-before: RFC 3339 时间过滤--region-code: 国家码，如 US、CN
调用示例：
python scripts/youtube_cli.py search --q "react tutorial beginner" --max-results 20 --order viewCount --video-duration long --with-details
工作流程
第一步：收集用户信息
如果用户只给了学习主题，没有说明基础和目标，必须先反问以下问题（一次性问完）：
- 你现在是什么水平？有没有编程基础？（比如：零基础 / 有其他语言基础 / 有相关经验）
- 你想达到什么目标？（入门了解 / 能做项目 / 就业准备 / 作品集 / 商业化）
- 每周准备投入多少时间？预计学习多少周？
如果用户已经提供了足够信息（主题 + 基础 + 目标 + 时间），直接进入第二步。
第二步：多轮 YouTube 搜索
搜索策略（必须执行多轮搜索，不能只搜一次）：
- 补基础搜索（如果用户基础不足）：搜索
{主题} basics / {主题} fundamentals / {主题} 入门
- 核心概念搜索：搜索
{主题} tutorial / {主题} course / {主题} explained
- 进阶搜索：搜索
{主题} advanced / {主题} deep dive / {主题} best practices
- 实战搜索：搜索
{主题} project / {主题} build / {主题}实战 / {主题} hands on
- 每个阶段的内容都要单独搜索，不能一个关键词覆盖所有阶段
搜索时注意：
- 使用
order=viewCount 获取高播放量优质视频
- 使用
video_duration=long 获取教程类长视频（通常质量更高）
- 使用
video_duration=medium 获取概念讲解类视频
- 每次搜索取 15-20 条结果
- 对搜索结果中的高相关性视频，用
video {id} 或 videos {id1} {id2} 获取详情（时长、播放量、标签）；也可在搜索时加 --with-details
视频筛选标准：
- 优先选择播放量高、时长合理（教程类 >10 分钟）的视频
- 优先选择近 2 年内发布的视频（技术更新快）
- 剔除明显不相关的视频（标题与学习主题无关）
- 如果搜索结果中有知名教育频道（如 freeCodeCamp、Traversy Media 等），优先选择
第三步：生成分阶段路线图
根据搜索结果和用户基础，规划 N 个阶段（通常 4-8 个阶段，取决于学习目标和时间）。
每个阶段必须包含：
### 阶段 X：{阶段名称}
- **学习目标**：本阶段要掌握的核心能力（1-3 句话）
- **预计时间**：X 周
- **推荐视频**：
1. 「视频标题」- 频道名 (时长) - https://youtube.com/watch?v=xxxxx
推荐理由：一句话说明为什么选这个视频
2. ...
- **知识作业**（不附答案）：
- 选择题 2-3 道
- 问答题 2-3 道
- **实战作业**：
1 个动手项目或练习，具体描述要做什么
阶段划分原则：
- 如果用户零基础，第一阶段必须是「前置基础」
- 阶段难度递进：基础 → 核心 → 进阶 → 实战 → 项目
- 每阶段视频数 3-5 个，不宜过多
- 最后一个阶段应该是一个综合项目
第四步：输出交付物
- 分阶段学习路线：在对话中直接输出完整路线图
- 项目文件夹：在用户工作空间下创建学习项目目录结构：
{workspace}/learning-roadmap-{主题}/
├── 路线图总览.md # 含 Mermaid 路线图
├── 阶段1_{名称}/
│ ├── 学习指南.md
│ ├── 知识作业.md
│ └── 实战作业.md
├── 阶段2_{名称}/
│ ├── 学习指南.md
│ ├── 知识作业.md
│ └── 实战作业.md
└── ...
- Mermaid 路线图：在「路线图总览.md」中包含 Mermaid 格式的可视化路线图
文件内容规范：
- 文件名用中文
- 学习指南.md：阶段目标 + 推荐视频清单（含链接和推荐理由）
- 知识作业.md：选择题 + 问答题（不附答案）
- 实战作业.md：实战项目描述 + 要求 + 验收标准
Mermaid 路线图格式
使用以下格式生成路线图：
graph LR
A[阶段1: 基础] --> B[阶段2: 核心概念]
B --> C[阶段3: 进阶]
C --> D[阶段4: 实战项目]
D --> E[阶段5: 综合项目]
style A fill:#4CAF50,color:#fff
style B fill:#2196F3,color:#fff
style C fill:#FF9800,color:#fff
style D fill:#FF5722,color:#fff
style E fill:#9C27B0,color:#fff
关键约束
- 不编造视频：所有推荐视频必须来自 YouTube 搜索结果，包含真实的 video_id 和链接
- 必须有作业：每个阶段都要有知识作业和实战作业
- 搜索要充分：不能只搜一次就生成路线图，必须多轮搜索覆盖不同难度和类型
- 输出要具体：视频链接、时长、推荐理由都要写清楚
- 尊重用户基础：零基础用户从前置基础开始，有基础的用户跳过基础阶段
