SuperAPI AI 工具集

scaffold-exercises

编程与开发

查看项目

更新于 10-18 16:15

技能介绍

用途

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 的练习是可以的。

工作流程

  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/ 之一。
  • 主(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 校验的场景。

限制

资料未提供关于收费、价格、平台支持范围、具体效果或性能的说明,这些信息暂未提供。