用途
scaffold-exercises 用于创建练习目录结构,生成包含章节(sections)、题目(problems)、解答(solutions)和讲解(explainers)的目录,并确保这些结构能通过 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。
在创建存根(stubbing)时,除非计划另有说明,默认使用 explainer/。
必需文件
每个子文件夹(problem/、solution/、explainer/)都需要一个 readme.md,要求:
- 非空(必须有真实内容,即使只有一行标题也可以)。
- 没有失效链接。
创建存根时,生成一个包含标题和描述的最小 readme:
# Exercise Title
Description here
如果子文件夹包含代码,还需要 main.ts(超过 1 行)。但对于存根,仅含 readme 的练习是可以的。
工作流程
- 解析计划 —— 提取章节名称、练习名称和变体类型。
- 创建目录 —— 对每个路径使用 mkdir -p。
- 创建存根 readme —— 每个变体文件夹一个 readme.md,包含标题。
- 运行 lint —— 使用 pnpm ai-hero-cli internal lint 进行校验。
- 修复错误 —— 迭代直到 lint 通过。
Lint 规则摘要
linter(pnpm ai-hero-cli internal lint)检查以下内容:
- 每个练习都有子文件夹(problem/、solution/、explainer/)。
- 至少存在 problem/、explainer/ 或 explainer.1/ 之一。
- 主(primary)子文件夹中存在 readme.md 且非空。
- 没有 .gitkeep 文件。
- 没有 speaker-notes.md 文件。
- readme 中没有失效链接。
- readme 中没有 pnpm run exercise 命令。
- 每个子文件夹需要 main.ts,除非是仅含 readme 的练习。
移动/重命名练习
当重新编号或移动练习时:
- 使用 git mv(而非 mv)重命名目录 —— 保留 git 历史。
- 更新数字前缀以保持顺序。
- 移动后重新运行 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 -> "# 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"
适用场景
适用于需要批量搭建练习目录、按计划生成练习脚手架、维护练习仓库结构并确保通过 lint 校验的场景。
限制
资料未提供关于收费、价格、平台支持范围、具体效果或性能的说明,这些信息暂未提供。