搭建练习结构 (Scaffold Exercises)

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

目录命名 (Directory naming)

• 章节 (Sections): 位于 exercises/ 目录内，命名为 XX-section-name/（例如 01-retrieval-skill-building）
• 练习 (Exercises): 位于章节目录内，命名为 XX.YY-exercise-name/（例如 01.03-retrieval-with-bm25）
• 章节编号 = XX，练习编号 = XX.YY
• 名称使用短横线命名法（小写，连字符）

练习变体 (Exercise variants)

每个练习至少需要以下子文件夹之一：

• problem/ – 学生工作区，包含待办事项 (TODO)
• solution/ – 参考实现 (reference implementation)
• explainer/ – 概念材料，不包含待办事项 (conceptual material, no TODOs)

在创建骨架时，除非计划中另有说明，否则默认使用 explainer/。

必需文件 (Required files)

每个子文件夹（problem/、solution/、explainer/）都需要一个 readme.md，该文件：

• 不能为空（必须有实际内容，即使只有一个标题行也可以）
• 没有损坏的链接

在创建骨架时，创建一个包含标题和描述的最小化 readme：

# 练习标题 (Exercise Title)

此处为描述 (Description here)

如果子文件夹包含代码，则还需要一个 main.ts（超过 1 行）。但对于骨架来说，仅包含 readme 的练习也是可以的。

工作流程 (Workflow)

1. 解析计划 (Parse the plan) – 提取章节名称、练习名称和变体类型
2. 创建目录 (Create directories) – 为每个路径执行 mkdir -p
3. 创建 readme 骨架 (Create stub readmes) – 每个变体文件夹一个包含标题的 readme.md
4. 运行 lint (Run lint) – pnpm ai-hero-cli internal lint 进行验证
5. 修复任何错误 (Fix any errors) – 迭代直至 lint 检查通过

Lint 规则摘要 (Lint rules summary)

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

移动/重命名练习 (Moving/renaming exercises)

在对练习进行重新编号或移动时：

1. 使用 git mv（而不是 mv）来重命名目录——这样可以保留 Git 历史记录
2. 更新数字前缀以保持顺序
3. 移动后重新运行 lint

示例：

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

示例：根据计划创建骨架 (Example: stubbing from a plan)

给定如下计划：

章节 05：记忆技能构建 (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 -> "# 记忆简介 (Introduction to Memory)"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# 短期记忆 (Short-term Memory)"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# 短期记忆 (Short-term Memory)"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# 短期记忆 (Short-term Memory)"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# 长期记忆 (Long-term Memory)"