scaffold-exercises

name	scaffold-exercises
description	创建包含章节、题目、答案和讲解的练习目录结构，并确保通过 lint。适用于用户希望搭建练习、创建练习占位结构或设置新课程章节的场景。

搭建练习目录

创建能够通过 pnpm ai-hero-cli internal lint 的练习目录结构，然后使用 git commit 提交。

目录命名

• 章节：位于 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

创建占位结构时，计划没有另行指定的情况下，默认使用 explainer/。

必需文件

每个子目录（problem/、solution/、explainer/）都需要一个 readme.md，并满足：

• 内容非空（必须包含实际内容，即使只有一行标题也可以）
• 不含失效链接

创建占位结构时，写入包含标题和描述的最小 readme：

# 练习标题

在这里填写说明

子目录内含代码时，还需要一个超过一行的 main.ts。占位练习只包含 readme 也可以。

工作流程

1. 解析计划——提取章节名称、练习名称和变体类型
2. 创建目录——为每条路径执行 mkdir -p
3. 创建 readme 占位文件——每个变体目录一个 readme.md，并写入标题
4. 运行 lint——执行 pnpm ai-hero-cli internal lint 进行验证
5. 修复错误——持续修复，直到 lint 通过

Lint 规则摘要

Linter（pnpm ai-hero-cli internal lint）会检查：

• 每个练习包含子目录（problem/、solution/、explainer/）
• 至少存在 problem/、explainer/ 或 explainer.1/ 中的一个
• 主要子目录中存在非空的 readme.md
• 不存在 .gitkeep 文件
• 不存在 speaker-notes.md 文件
• readme 中没有失效链接
• readme 中没有 pnpm run exercise 命令
• 除了只包含 readme 的情况，每个子目录都需要 main.ts

移动或重命名练习

重新编号或移动练习时：

1. 使用 git mv（不要使用 mv）重命名目录，以保留 Git 历史
2. 更新数字前缀，保持顺序连续
3. 移动后重新运行 lint

示例：

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

示例：根据计划创建占位结构

给定如下计划：

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

创建：

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

随后创建 readme 占位文件：

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# 记忆入门"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# 短期记忆"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# 短期记忆"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# 短期记忆"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# 长期记忆"