tech-learning-roadmap

name	tech-learning-roadmap
description	技术学习路线图生成器。用户输入学习主题和目标后，结合用户基础和 Exa 全网搜索结果，生成可执行的分阶段学习路线图。 触发词：「学习路线」「学习路线图」「学习计划」「roadmap」「帮我学」「我想学」「学习路径」「技术学习」「生成学习路线」「制定学习计划」。 支持任意技术主题：编程语言、框架、工具、DevOps、AI/ML、前端、后端、数据库等。 输出包括：分阶段路线图、推荐视频、知识作业、实战作业、Mermaid 可视化、项目文件夹结构。

技术学习路线图生成器

工作流程

步骤 0：检查环境变量

• 确认 EXA_API_KEY 环境变量已设置。若未设置，提示用户配置。
• EXA_API_KEY 获取地址 ：!(https://dashboard.exa.ai/api-keys)[https://dashboard.exa.ai/api-keys]
• API Key设置方法:
  • Windows: setx EXA_API_KEY "your_secret_here"
  • MacOS: 在 ~/.zshrc 末尾追加 export EXA_API_KEY='your_secret_here'
• API Key 设置完成以后，需要提示用户重启当前Agent软件.
• 确认 Python 环境已安装 exa-py。若未安装，执行 pip install exa-py。

步骤 1：收集用户信息

用户只提供学习主题时，必须先询问以下三个问题（使用 ask_user_question 工具）：

1. 当前水平：零基础 / 有编程基础 / 有相关经验
2. 学习目标：入门了解 / 能做项目 / 求职就业 / 作品集 / 商业化
3. 时间投入：每周可投入小时数 + 预计学习周数

用户已提供完整信息时跳过此步。

步骤 2：Exa 搜索

读取 references/exa_api.md 了解 Exa API 用法，然后运行搜索脚本。

搜索策略（必须多轮搜索，覆盖不同难度和内容类型）：

python scripts/exa_search.py --query "<主题> tutorial for beginners" --num 10 --highlights
python scripts/exa_search.py --query "<主题> 实战项目 教程" --num 10 --highlights
python scripts/exa_search.py --query "<主题> advanced concepts deep dive" --num 10 --highlights
python scripts/exa_search.py --query "<主题> 面试题 求职" --num 5 --highlights

对每个学习阶段都要执行搜索，确保推荐内容基于真实搜索结果。

步骤 3：分析搜索结果

从搜索结果中提取：

• 视频标题、URL、发布日期
• 高亮摘要（内容概要）
• 内容难度层级（基础/中级/高级）
• 实战 vs 理论的比例

根据用户水平和目标，过滤和排序搜索结果：

• 零基础用户：优先入门教程、基础概念讲解
• 有基础用户：跳过入门，聚焦进阶和实战
• 求职用户：增加面试题、行业实践内容
• 作品集用户：增加项目实战、完整案例

步骤 4：生成分阶段路线图

根据搜索结果和用户目标，规划 N 个阶段（通常 4-8 个）。每个阶段包含：

阶段名称：第N阶段 - <名称>
学习目标：1-3 句话描述本阶段目标
预计时长：X 周（基于用户时间投入）
推荐视频：
  1. 「视频标题」- URL - 推荐理由（1句话）
  2. ...
知识作业：
  选择题：
    1. <题目>
    2. <题目>
    ...
  问答题：
    1. <题目>
    2. <题目>
    ...
实战作业：
  1. <任务描述>（难度：⭐~⭐⭐⭐）
  2. <任务描述>（难度：⭐⭐~⭐⭐⭐）

阶段划分原则：

• 零基础用户：第一阶段必须是前置基础（如环境搭建、基础语法）
• 阶段难度递增，前一阶段的输出是后一阶段的输入
• 每个阶段都有明确的"完成标志"（能做出实战作业）
• 最后一个阶段应贴近用户最终目标（求职/项目/作品集）

步骤 5：创建项目文件夹

在工作目录下创建学习路线图根文件夹，然后为每个阶段创建子文件夹：

<主题>_学习路线图/
├── 学习路线图.md          # 总览文档（含 Mermaid 图）
├── 第1阶段_<名称>/
│   ├── 学习指南.md
│   ├── 知识作业.md
│   └── 实战作业.md
├── 第2阶段_<名称>/
│   ├── 学习指南.md
│   ├── 知识作业.md
│   └── 实战作业.md
└── ...

文件内容规范：

学习路线图.md（总览）：

• 用户信息（水平、目标、时间投入）
• 阶段总览表
• Mermaid 路线图（使用 graph TD 格式）
• 每阶段简要说明

学习指南.md（每阶段）：

• 阶段目标
• 推荐视频列表（含 URL、标题、推荐理由）
• 学习顺序建议
• 关键知识点清单

知识作业.md（每阶段）：

• 选择题（5-8 题，不附答案）
• 问答题（3-5 题，不附答案）

实战作业.md（每阶段）：

• 2-4 个实战任务
• 每个任务包含：任务描述、难度评级、验收标准
• 难度从基础到进阶递增

步骤 6：输出 Mermaid 路线图

在总览文档中包含 Mermaid 格式的可视化路线图：

graph TD
    A[起点：用户当前水平] --> B[第1阶段：基础]
    B --> C[第2阶段：核心概念]
    C --> D[第3阶段：进阶实战]
    D --> E[第4阶段：项目落地]
    E --> F[终点：学习目标]

    style A fill:#e1f5fe
    style F fill:#c8e6c9

关键规则

1. 不编造内容：所有推荐视频必须来自 Exa 搜索结果，包含真实 URL。若搜索结果不足，明确告知用户并建议调整搜索关键词。
2. 作业必须具体：选择题和问答题要针对该阶段的实际知识点，不能是泛泛的"你学到了什么"。
3. 实战作业可执行：每个实战任务要有明确的验收标准，用户能判断自己是否完成。
4. 文件名用中文：所有输出文件名使用中文。
5. 尊重用户时间：阶段时长基于用户声明的每周投入时间计算。
6. 编码规范：所有文件使用 UTF-8 编码写入（遵循 qclaw-rules）。

文件结构

tech-learning-roadmap/
├── SKILL.md                    # 本文件
├── scripts/
│   └── exa_search.py           # Exa 搜索脚本
└── references/
    └── exa_api.md              # Exa API 参考文档