{title="📊 页面导航】

    适用角色与上手难度

    角色推荐度上手难度
    🛠️ 开发★★★★★★☆☆☆☆
    🧪 测试★★★★☆★☆☆☆☆
    📦 产品★☆☆☆☆★★☆☆☆

    🎯 学习产出： 掌握练习目录脚手架方法，能按计划批量创建合规的练习结构

    🚀 AI 能力提升： 内容组织

    scaffold-exercises

    预计阅读时间: 3 分钟

    练习脚手架。创建能通过 pnpm ai-hero-cli internal lint 的练习目录结构：节、练习、问题、解决方案和讲解，然后 git commit。

    概述

    面向课程内容作者的批量建目录工具：从计划里解析出节和练习，按规范命名、创建目录和 readme stub、跑 lint 验证。

    日常使用

    > 按这个计划搭一节练习：05 记忆技能构建，三个练习

    实战

    目录规范

    • 节：exercises/XX-section-name/（如 01-retrieval-skill-building）
    • 练习：节内 XX.YY-exercise-name/（如 01.03-retrieval-with-bm25）
    • 节号 = XX，练习号 = XX.YY
    • 名字 dash-case（小写 + 连字符）

    练习变体

    每个练习至少一个子文件夹：

    子文件夹内容
    problem/学生工作区，带 TODO
    solution/参考实现
    explainer/概念材料，无 TODO（stub 默认此类型）

    每个子文件夹需要一个非空 readme.md（标题就行）且无坏链。有代码还需要 main.ts（>1 行）；纯 readme 练习也行。

    # Exercise Title

Description here

    工作流

    1. 解析计划：提取节名、练习名、变体类型
    2. 建目录：mkdir -p 每个路径
    3. 建 readme stub：每个变体文件夹一个带标题的 readme.md
    4. 跑 lint：pnpm ai-hero-cli internal lint 验证
    5. 修错迭代：直到 lint 通过

    lint 规则要点

    每个练习有子文件夹；至少存在 problem/、explainer/ 或 explainer.1/ 之一；主子文件夹 readme.md 存在且非空；无 .gitkeep；无 speaker-notes.md；readme 无坏链；readme 里无 pnpm run exercise 命令；除 readme-only 外每个子文件夹要 main.ts。

    移动/重命名

    用 git mv（保留 git 历史）而非 mv；更新数字前缀保持顺序；移动后重跑 lint。

    git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

    从计划 stub 的示例

    计划：Section 05: Memory Skill Building — 05.01 Introduction / 05.02 Short-term (explainer+problem+solution) / 05.03 Long-term

    mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer

    与其它技能的关系

    • 同类：teach 生成教学课程；scaffold-exercises 只搭目录结构
    • 配套：setup-pre-commit 的 lint-staged 会在提交时跑格式化