scaffold-exercises

1# 搭建练习
2 
3创建能通过 `pnpm ai-hero-cli internal lint` 的 exercise directory structures，然后用 `git commit` 提交。
4 
5## 目录命名
6 
7- **Sections**：`exercises/` 下的 `XX-section-name/`（例如 `01-retrieval-skill-building`）
8- **Exercises**：section 下的 `XX.YY-exercise-name/`（例如 `01.03-retrieval-with-bm25`）
9- Section number = `XX`，exercise number = `XX.YY`
10- Names 使用 dash-case（小写、连字符）
11 
12## Exercise 变体
13 
14每个 exercise 至少需要这些 subfolders 中的一个：
15 
16- `problem/` - student workspace，包含 TODOs
17- `solution/` - reference implementation
18- `explainer/` - conceptual material，不含 TODOs
19 
20创建 stub 时，除非 plan 指定其他 variant，否则默认使用 `explainer/`。
21 
22## 必需文件
23 
24每个 subfolder（`problem/`、`solution/`、`explainer/`）都需要一个 `readme.md`，要求：
25 
26- **非空**（必须有真实内容，即使只有一行 title 也可以）
27- 没有 broken links
28 
29创建 stub 时，生成带 title 和 description 的最小 readme：
30 
31```md
32# Exercise Title
33 
34Description here
35```
36 
37如果 subfolder 有 code，还需要 `main.ts`（>1 行）。但对 stubs 来说，readme-only exercise 可以接受。
38 
39## 工作流
40 
411. **Parse the plan** - 提取 section names、exercise names 和 variant types
422. **Create directories** - 对每个 path 执行 `mkdir -p`
433. **Create stub readmes** - 每个 variant folder 一个带 title 的 `readme.md`
444. **Run lint** - 执行 `pnpm ai-hero-cli internal lint` 验证
455. **Fix any errors** - 迭代直到 lint 通过
46 
47## Lint 规则摘要
48 
49linter（`pnpm ai-hero-cli internal lint`）检查：
50 
51- 每个 exercise 有 subfolders（`problem/`、`solution/`、`explainer/`）
52- 至少存在 `problem/`、`explainer/` 或 `explainer.1/` 之一
53- primary subfolder 中存在非空 `readme.md`
54- 没有 `.gitkeep` files
55- 没有 `speaker-notes.md` files
56- readmes 中没有 broken links
57…