structured-learning-planner — 结构化学习方案生成器

> 边界声明：本 Skill 只生成学习计划，不执行学习动作、不生成教学内容、不替代课程

快速上手

1. 用户说"我想学 XX" → 用下方「输入模板」收集信息（一句话也能开工）
2. 产出「起点诊断」两块清单 → 用户确认后铺路线
3. 按下方「输出模板」成文，资源从「资源库」取（1主1备）
4. 对照「完整示例」检查结构是否齐全
5. 生成可勾选 .md 文件，跑「校验脚本」检查质量

触发条件

不适用：用户已有完整计划只需课程内容 / 只想要"推荐一本书" / 目标过于模糊且无法澄清

核心设计原则

1. 分阶段递进：W0 摸底 → 地基 → 核心 → 前沿，不做跳跃式规划
2. 学练绑定：每阶段理论必须对接已有或新建项目，杜绝"学完用不上"
3. 资源精简：每阶段 1 主 + 1 备资源封顶，防松鼠症
4. 可跟踪溯源：输出可勾选 Markdown 文件，兼容自动化读取 - [ ] 进度
5. 真实日期：里程碑日历基于用户当前日期推算，不用"第N周"占位符

输入模板（用户怎么给信息）

方式 A：一句话触发（Skill 自动补全）

我想系统学习 <主题>，已经有 <相关基础>，每天能投入 <时间>。

示例：我想系统学习 AI，已经有工程基础（做过记忆系统、多智能体），每天能投入 2 小时。

用户未提供时的推断规则（需在输出中标注"已假设"）：

方式 B：完整信息（推荐）

【学习目标】我想达到什么程度？
  示例：能独立训练并微调一个 LLM / 能用 Rust 写一个 CLI 工具

【现有基础】我已经会什么？（逐条列，别谦虚也别夸大）
  1. ...

【时间预算】每天 / 每周能投入多少？
  示例：工作日 1.5h，周末 4h

【周期预期】想用多久？
  示例：3 个月

【偏好方式】看书 / 视频课 / 项目驱动 / 混合？
  示例：混合，喜欢项目驱动

【硬件或工具约束】（可选）
  示例：只有 6GB VRAM 的显卡，跑不动大模型训练

【最终产出】（可选，会直接变成学练绑定目标）
  示例：学完做一个"每日跑步数据自动分析"工具

诊断输出（Skill 必须产出，给用户确认后才开始规划）

## 起点诊断

### 已有基础（不需要重学）
- ✅ <能力1> —— 证据：<做过什么>
- ✅ <能力2> —— 证据：<做过什么>

### 靶点清单（要补的）
- 🎯 <靶点1> —— 为什么是靶点：<一句理由>
- 🎯 <靶点2> —— 为什么是靶点：<一句理由>

> 请确认：以上诊断是否准确？确认后我才开始铺路线。

> 硬约束：禁止跳过诊断直接出计划。诊断产出的"靶点清单"是路线设计的唯一依据。

输出模板（完整可勾选 Markdown 骨架）

> 照此骨架填充，<占位符> 全部替换后即可交付。

# [主题] 学习方案 · YYYY

> 生成日期：YYYY/MM/DD | 方案版本 v1.0 | 复盘节奏：每周日
> 时间预算：<X>h/天 | 路线模式：<轻度8周/标准12周/深度16周>

---

## 一、起点诊断

### 已有基础（不需要重学）
- ✅ <能力1> —— 证据：<做过什么>
- ✅ <能力2> —— 证据：<做过什么>

### 靶点清单（要补的）
| # | 靶点 | 为什么是靶点 |
|---|------|-------------|
| 1 | <靶点> | <一句话理由> |

---

## 二、总体路线

W0 摸底 → 阶段1(<主题>基础) → 阶段2(<主题>进阶) → [阶段3] → 持续

| 阶段 | 内容 | 预计耗时 | 依赖 |
|------|------|---------|------|
| W0 摸底 | 自测 + 定向 | 2-3 天 | — |
| 阶段1 | <内容> | <X>周 | W0 |
| 阶段2 | <内容> | <X>周 | 阶段1 |

---

## 三、W0 摸底（YYYY/MM/DD - YYYY/MM/DD）

**目标**：3-5 题快速定位弱项，决定各阶段时间权重。

- [ ] 知识自测：<列出 3-5 道定位题>（结果标记 会/模糊/不会）
- [ ] 技能自测：<1 个最小实操验证基础>
- [ ] 方向确认：<明确最终产出或里程碑>
- [ ] 产出自测结果表，标注各阶段时间分配权重

---

## 四、阶段 1：<阶段名>（YYYY/MM/DD - YYYY/MM/DD）

### 1. 内容清单
| 学什么 | 为什么学 |
|--------|---------|
| <知识点> | <与目标/后续阶段的关联> |

### 2. 资源推荐（1主1备封顶）
| 角色 | 资源 | 平台/语言 | 难度 | 选它的理由 |
|------|------|----------|------|-----------|
| 主 | <资源> | <平台> | <初/中/高> | <为什么是这个而不是别的> |
| 备 | <资源> | <平台> | <初/中/高> | <何时切到备选> |

**资源备选池**（不进主计划，防松鼠症）：<资源A>、<资源B>

### 3. 学练绑定（≥2 项）
- [ ] <动作1> → 产出：<文件名或验收动作>（关联：<与已有项目的关联>）
- [ ] <动作2> → 产出：<文件名或验收动作>（关联：<与已有项目的关联>）

### 4. 验收标准
- [ ] <客观可判断的完成条件，如"能跑通并输出X">
- [ ] <客观可判断的完成条件>

### 5. 预计耗时
<X>h/天 × <N>周 ≈ <Y>h 总投入

### 6. 依赖关系
前置：<W0 / 阶段N-1> | 后置：<阶段N+1>

---

## 五、阶段 2：<阶段名>（YYYY/MM/DD - YYYY/MM/DD）
<!-- 结构与阶段 1 相同，6 要素缺一不可 -->

---

## 里程碑日历

| 阶段 | 起止日期 | 完成标准 | 状态 |
|------|---------|---------|------|
| W0 摸底 | YYYY/MM/DD - YYYY/MM/DD | 自测表 + 方向确认 | ⬜ |
| 阶段1 | YYYY/MM/DD - YYYY/MM/DD | <完成标准> | ⬜ |
| 阶段2 | YYYY/MM/DD - YYYY/MM/DD | <完成标准> | ⬜ |

---

## 风险管理

| # | 风险 | 等级 | 应对 |
|---|------|------|------|
| R1 | <风险> | 🟠 P1 | <应对策略> |
| R2 | <风险> | ... | ... |
| R3 | <风险> | ... | ... |

---

## 待确认决策点

- [ ] <需要用户拍板的事项1>（如：时间预算是否按 2h/天？）
- [ ] <需要用户拍板的事项2>（如：产出形式是否接受？）

---

*方案版本 v1.0 | 复盘节奏：每周日 | 下次复盘：YYYY/MM/DD*

填充要点速查

资源库（多领域，1主1备封顶）

> 生成计划时直接从此取资源。库外领域按此格式现场补充。
> 标注 [中文] = 中文讲解可用；难度：初/中/高。

AI / 机器学习

编程语言

系统设计 / 架构

数据分析 / 数据科学

前端 / 后端 / DevOps

通用补位

完整示例：AI 系统学习方案（标准 12 周）

> 以下为可直接套用的完整成文示例。替换主题和细节即可复用。

# AI 系统学习方案 · 2026

> 生成日期：2026/08/20 | 方案版本 v1.0 | 复盘节奏：每周日
> 时间预算：2h/天（工作日）+ 4h/天（周末） | 路线模式：标准 12 周

---

## 一、起点诊断

### 已有基础（不需要重学）
- ✅ 工程实战：做过记忆系统（BM25 + embedding）、多智能体系统、Agent 平台
- ✅ Python 熟练：numpy/pandas 日常使用无压力
- ✅ 概念接触：知道 Transformer/注意力机制"是什么"，但没系统学过

### 靶点清单（要补的）
| # | 靶点 | 为什么是靶点 |
|---|------|-------------|
| 1 | 数学语言（线性代数/概率） | 读论文和源码推导全靠它，现在说不出为什么 |
| 2 | Transformer 机理 | 会用 API 但不知道内部怎么算——限制调优和排错 |
| 3 | 训练侧全链路 | 只会推理不会训练，无法做微调和评估 |
| 4 | 理论地图 | 知识碎片化，没有"哪些概念属于同一体系"的全局观 |

---

## 二、总体路线

W0 摸底 → 阶段1(数学+ML 4周) → 阶段2(DL+Transformer 4周) → 阶段3(LLM+Agent 4周) → 前沿追踪

---

## 三、W0 摸底（2026/08/24 - 2026/08/26）

- [ ] 知识自测（结果标记 会/模糊/不会）：
  1. 矩阵乘法的几何意义？为什么 Transformer 用矩阵乘法？
  2. 贝叶斯公式是什么？dropout 和它有什么关系？
  3. 简述 Transformer 的 attention 计算流程（Q/K/V 各是什么）？
  4. 什么是反向传播？梯度消失怎么发生？
  5. 什么是 LoRA？为什么能省显存？
- [ ] 技能自测：用 numpy 手写矩阵乘法 + 最小线性回归
- [ ] 方向确认：3 个月后能独立微调一个 7B 模型并做评估
- [ ] 产出自测结果表 → 决定阶段 1/2/3 的时间分配权重

---

## 四、阶段 1：数学 + ML 基础（2026/08/27 - 2026/09/23）

### 1. 内容清单
| 学什么 | 为什么学 |
|--------|---------|
| 线性代数（向量/矩阵/特征值） | 理解 embedding、attention 的矩阵运算 |
| 概率统计（分布/贝叶斯/最大似然） | 理解 loss 函数、正则化、采样 |
| 微积分（导数/梯度/链式法则） | 反向传播的唯一数学基础 |
| ML 基础（损失函数/过拟合/评估指标） | 建立"模型怎么学"的直觉 |

### 2. 资源推荐
| 角色 | 资源 | 平台 | 难度 | 选它的理由 |
|------|------|------|------|-----------|
| 主 | 3Blue1Brown《线性代数的本质》+《微积分的本质》 | B站 | 初 | 几何直觉优先，治公式恐惧症 |
| 备 | 李航《统计学习方法》 | 书 | 中 | 数学功底扎实时切入 |

**资源备选池**：吴恩达 ML 课、Khan Academy、花书《深度学习》

### 3. 学练绑定
- [ ] numpy 手写线性回归 + 逻辑回归 → 产出：`ml_from_scratch.py`
- [ ] 用 numpy 实现 3 种常用 loss（MSE/交叉熵/正则项）→ 产出：`losses.py`

### 4. 验收标准
- [ ] 不看笔记能解释特征值分解的几何意义
- [ ] `ml_from_scratch.py` 在 iris 数据上跑通，准确率 > 90%

### 5. 预计耗时
2h/天 × 5天 + 4h/天 × 2天 ≈ 18h/周，4 周 ≈ 72h

### 6. 依赖关系
前置：W0 摸底 | 后置：阶段 2

---

## 五、阶段 2：DL 基础 + Transformer 机理（2026/09/24 - 2026/10/21）

### 1. 内容清单
| 学什么 | 为什么学 |
|--------|---------|
| 神经网络基础（前向/反向/优化器） | 从"手写 ML"升级到"理解深度学习训练" |
| Transformer 完整机理（Q/K/V、多头、位置编码） | 核心靶点——LLM 的地基 |
| 训练技巧（正则/学习率/梯度问题） | 直接服务阶段 3 的微调实操 |

### 2. 资源推荐
| 角色 | 资源 | 平台 | 难度 | 选它的理由 |
|------|------|------|------|-----------|
| 主 | Karpathy《Zero to Hero》(micrograd + nanoGPT) | YouTube | 中 | 从零手写反向传播和 GPT |
| 备 | 李沐《动手学深度学习》 | B站 | 中 | 中文 + 代码全，卡住时兜底 |

### 3. 学练绑定
- [ ] 手写 micrograd（自动微分）→ 产出：`micrograd.py`
- [ ] 手搓 nanoGPT → 产出：`nano_gpt.py`
- [ ] 用 numpy 实现单头 attention → 产出：`attention_numpy.py`

### 4. 验收标准
- [ ] 不看源码能画出 Transformer 结构图并解释每层数据形状变化
- [ ] `nano_gpt.py` 训练出可生成连贯句子的最小模型

### 5. 预计耗时
18h/周 × 4 周 ≈ 72h

### 6. 依赖关系
前置：阶段 1 | 后置：阶段 3

---

## 六、阶段 3：LLM 工程 + Agent + 微调（2026/10/22 - 2026/11/18）

### 1. 内容清单
| 学什么 | 为什么学 |
|--------|---------|
| LLM 推理与 API 工程 | 系统化补全盲区 |
| Agent 架构（ReAct/规划/记忆/工具） | 把已有 Agent Loop 经验上升到方法论 |
| 微调（LoRA/QLoRA/评估） | 核心靶点——从"用模型"到"改模型" |
| 评估体系（指标/基准/人工评测） | 微调没有评估等于瞎调 |

### 2. 资源推荐
| 角色 | 资源 | 平台 | 难度 | 选它的理由 |
|------|------|------|------|-----------|
| 主 | HuggingFace PEFT + TRL 官方文档 | 文档 | 中 | 微调实操唯一权威入口 |
| 备 | 吴恩达《Building Systems with the ChatGPT API》 | 视频 | 初 | Agent 工程化轻量补位 |

### 3. 学练绑定
- [ ] 用 QLoRA 微调 7B 模型 → 产出：微调模型 + 训练日志
- [ ] 为微调模型设计 5 项评估指标 → 产出：`eval_report.md`
- [ ] 把 Agent Loop 升级为带记忆的 ReAct → 产出：`agent_loop_v2.py`

### 4. 验收标准
- [ ] 微调前后模型在自建评测集上指标可量化对比
- [ ] `agent_loop_v2.py` 通过端到端测试，记忆召回率可复现

### 5. 预计耗时
18h/周 × 4 周 ≈ 72h

### 6. 依赖关系
前置：阶段 2 | 后置：前沿追踪（持续）

---

## 里程碑日历

| 阶段 | 起止日期 | 完成标准 | 状态 |
|------|---------|---------|------|
| W0 摸底 | 2026/08/24 - 2026/08/26 | 自测表 + 方向确认 | ⬜ |
| 阶段1 数学+ML | 2026/08/27 - 2026/09/23 | `ml_from_scratch.py` 跑通 iris > 90% | ⬜ |
| 阶段2 DL+Transformer | 2026/09/24 - 2026/10/21 | `nano_gpt.py` 生成连贯文本 | ⬜ |
| 阶段3 LLM+Agent | 2026/10/22 - 2026/11/18 | 微调模型 + 可量化评估报告 | ⬜ |

---

## 风险管理

| # | 风险 | 等级 | 应对 |
|---|------|------|------|
| R1 | 数学劝退（阶段1最容易放弃） | 🟠 P1 | 3Blue1Brown 几何直觉优先；只补自测标"模糊/不会"的；连续卡 2 天降级为"看懂结论即可" |
| R2 | 学习与工作抢时间 | 🟠 P1 | 学练绑定内建——产出直接复用工作数据，学习即项目升级 |
| R3 | 资源松鼠症 | 🟡 P2 | 1主1备硬约束；备选池只登记不展开 |
| R4 | 显存不够（6GB VRAM 训不动 7B） | 🟡 P2 | 阶段3 预设 QLoRA + 4bit 量化；不行降级到 3B |
| R5 | 精力断档（4 周无正反馈） | 🟡 P2 | 每周日复盘强制检查；每阶段产出物即正反馈 |

---

## 待确认决策点

- [ ] 时间预算：是否按 2h/天 + 4h/周末执行？（可调）
- [ ] 微调目标：用 7B 还是降级 3B？（受显存影响，阶段 3 前拍板）
- [ ] 前沿追踪：是否纳入正式计划，还是只保持"关注"？

---

*方案版本 v1.0 | 复盘节奏：每周日 | 下次复盘：2026/08/30*

> 第二个示例（Rust 轻度 8 周）：用户输入 我想学 Rust，有 Python 5 年经验，每天能投入 1 小时。结构与上方相同但只 2 个阶段（语法+所有权 4周 → 实战项目 4周），资源用 The Book + Rustlings，学练绑定用 Rustlings 练习 + "用 Rust 重写 Python 工具"作为验收。完整版见 references/EXAMPLE_RUST.md。

校验脚本（交付前必跑）

> 将以下代码保存为 validate_plan.py，生成方案后运行检查质量。

#!/usr/bin/env python3
"""validate_plan.py — 结构化学习方案输出质量校验

用法:
    python validate_plan.py <plan.md>
    python validate_plan.py <plan.md> --strict   # 严格模式: 失败返回非零退出码

校验项:
    C1  可勾选: 任务全部使用 - [ ] 格式 (≥8个)
    C2  日期真实: 里程碑含具体日期 YYYY/MM/DD, 无"第N周"占位符
    C3  资源不超: 每阶段主资源 ≤ 2 (1主1备封顶)
    C4  风险登记: ≥ 3 条风险 + 应对方案
    C5  验收明确: 无"理解了/掌握了/学会了"等模糊验收词
    C6  W0 摸底: 包含起点诊断章节
    C7  决策点: 包含待确认决策点章节
"""
import re
import sys


def check_plan(path):
    """返回 (检查项id, 是否通过, 说明) 列表"""
    try:
        with open(path, encoding="utf-8") as f:
            text = f.read()
    except OSError as e:
        print(f"错误: 无法读取文件 {path}: {e}")
        sys.exit(2)

    results = []

    # C1 可勾选: - [ ] 任务数量充足(>=8), 不混入已完成标记
    checkbox_open = re.findall(r"^\s*-\s*\[ \]", text, re.MULTILINE)
    checkbox_done = re.findall(r"^\s*-\s*\[[xX]\]", text, re.MULTILINE)
    ok_c1 = len(checkbox_open) >= 8 and len(checkbox_done) == 0
    results.append(("C1 可勾选格式", ok_c1,
                    f"- [ ] 任务 {len(checkbox_open)} 个, 已完成标记 {len(checkbox_done)} 个"))

    # C2 日期真实
    has_dates = bool(re.search(r"20\d{2}/\d{2}/\d{2}", text))
    week_placeholder = bool(re.search(r"第\s*[0-9N一二三四五六七八九十]+\s*周", text))
    results.append(("C2 真实日期", has_dates and not week_placeholder,
                    f"含真实日期: {has_dates}; 含'第N周'占位符: {week_placeholder}"))

    # C3 资源不超
    main_resources = re.findall(r"^\|\s*主\s*\|", text, re.MULTILINE)
    stage_blocks = re.findall(r"^#{2,4}\s*(阶段\s*\d|四、|五、|六、|七、)", text, re.MULTILINE)
    results.append(("C3 资源1主1备", len(main_resources) <= max(len(stage_blocks) * 2, 2),
                    f"主资源 {len(main_resources)} 个 / 阶段区块 {len(stage_blocks)} 个"))

    # C4 风险登记 >= 3
    risk_rows = re.findall(r"^\|\s*R\d+\s*\|", text, re.MULTILINE)
    results.append(("C4 风险≥3条", len(risk_rows) >= 3, f"风险条目 {len(risk_rows)} 条"))

    # C5 验收明确: 无模糊词
    fuzzy_words = ["理解了", "掌握了", "学会了", "大概明白", "差不多会"]
    found_fuzzy = [w for w in fuzzy_words if w in text]
    results.append(("C5 验收明确", not found_fuzzy,
                    f"模糊词: {found_fuzzy if found_fuzzy else '无'}"))

    # C6 W0 摸底
    has_w0 = bool(re.search(r"W0|起点诊断", text))
    results.append(("C6 起点诊断", has_w0, f"含W0/起点诊断: {has_w0}"))

    # C7 决策点
    has_dec = bool(re.search(r"待确认决策点|决策点", text))
    results.append(("C7 决策点", has_dec, f"含待确认决策点: {has_dec}"))

    return results


def main():
    if len(sys.argv) < 2:
        print("用法: python validate_plan.py <plan.md> [--strict]")
        sys.exit(2)
    path = sys.argv[1]
    strict = "--strict" in sys.argv

    results = check_plan(path)

    print(f"校验文件: {path}\n")
    passed = 0
    for cid, ok, desc in results:
        mark = "✅" if ok else "❌"
        print(f"  {mark} {cid:<14s} {desc}")
        passed += 1 if ok else 0

    score = passed / len(results) * 100
    print(f"\n得分: {score:.0f}/100 ({passed}/{len(results)} 项通过)")
    if passed == len(results):
        print("结论: 通过, 方案符合输出质量标准")
        return 0
    print("结论: 存在失败项, 按上述 ❌ 项修正后重新校验")
    return 1 if strict else 0


if __name__ == "__main__":
    sys.exit(main())

七项检查：C1 可勾选格式 / C2 真实日期 / C3 资源1主1备 / C4 风险≥3条 / C5 验收无模糊词 / C6 含起点诊断 / C7 含决策点。任何 ❌ 项修正后重新校验，全绿才交付。

输出质量标准

注意事项

1. 先诊断再规划：不知道用户现有基础绝不开始输出方案
2. 防松鼠症：1主1备是硬约束，不能因为"这个也不错"多塞一个资源
3. 学练绑定是底线：没有绑定项目的学习计划等于没用，每阶段至少 2 个绑定点
4. 复盘钩子必留：输出文件必须 - [ ] 格式，可被自动化读取进度
5. 日期推算：里程碑使用真实日期推算，不许用占位符
6. 不替代课程：本 Skill 只规划"学什么、怎么学、何时验收"，不生成教学内容
7. 模板优先：成文用上方输出模板，资源从资源库取，不每次现场即兴

扩展文件（可选，本文件已自包含）

本 SKILL.md 已内联全部核心内容。以下文件为扩展版本，有更详细的内容但非必需：

版本 1.2.0 | 创建 2026-07-30 | 更新 2026-08-20（全部核心内容内联，单文件自包含）