Back to Details

scaffold-exercises

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scaffold Exercises

搭建练习框架

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

Directory naming

目录命名规则

  • Sections：
    exercises/
    下的 
    XX-section-name/
    （例如 
    01-retrieval-skill-building
    ）
  • Exercises：section 下的 
    XX.YY-exercise-name/
    （例如 
    01.03-retrieval-with-bm25
    ）
  • Section number = 
    XX
    ，exercise number = 
    XX.YY
  • Names 使用 dash-case（小写、连字符）
  • 章节（Sections）：
    exercises/
    目录下的
    XX-section-name/
    （例如
    01-retrieval-skill-building
    ）
  • 练习（Exercises）：章节下的
    XX.YY-exercise-name/
    （例如
    01.03-retrieval-with-bm25
    ）
  • 章节编号 = 
    XX
    ，练习编号 = 
    XX.YY
  • 名称采用dash-case格式（小写、连字符分隔）

Exercise variants

练习变体

每个 exercise 至少需要这些 subfolders 中的一个：
  • problem/
    — student workspace，包含 TODOs
  • solution/
    — reference implementation
  • explainer/
    — conceptual material，不含 TODOs
创建 stub 时，除非 plan 指定其他 variant，否则默认使用 
explainer/
。
每个练习至少需要以下子文件夹中的一个：
  • problem/
    — 学生工作区，包含待完成项（TODOs）
  • solution/
    — 参考实现方案
  • explainer/
    — 概念性资料，不含待完成项（TODOs）
创建stub时，除非计划中指定了其他变体，否则默认使用
explainer/
。

Required files

必填文件

每个 subfolder（
problem/
、
solution/
、
explainer/
）都需要一个 
readme.md
，要求：
  • 非空（必须有真实内容，即使只有一行 title 也可以）
  • 没有 broken links
创建 stub 时，生成带 title 和 description 的最小 readme：
md
undefined
每个子文件夹（
problem/
、
solution/
、
explainer/
）都需要一个
readme.md
文件，要求：
  • 非空（必须包含真实内容，哪怕只有一行标题也可以）
  • 无无效链接（broken links）
创建stub时，生成包含标题和描述的最简readme：
md
undefined

Exercise Title

练习标题

Description here

如果 subfolder 有 code，还需要 `main.ts`（>1 行）。但对 stubs 来说，readme-only exercise 可以接受。
描述内容

如果子文件夹包含代码，还需要`main.ts`文件（内容超过1行）。但对于stub来说，仅含readme的练习是可接受的。

Workflow

工作流程

  1. Parse the plan — 提取 section names、exercise names 和 variant types
  2. Create directories — 对每个 path 执行 
    mkdir -p
  3. Create stub readmes — 每个 variant folder 一个带 title 的 
    readme.md
  4. Run lint — 执行 
    pnpm ai-hero-cli internal lint
    验证
  5. Fix any errors — 迭代直到 lint 通过
  1. 解析计划 — 提取章节名称、练习名称和变体类型
  2. 创建目录 — 对每个路径执行
    mkdir -p
    命令
  3. 创建Stub说明文档 — 为每个变体文件夹生成带标题的
    readme.md
  4. 运行检查 — 执行
    pnpm ai-hero-cli internal lint
    进行验证
  5. 修复错误 — 迭代调整直到检查通过

Lint rules summary

Lint规则摘要

linter（
pnpm ai-hero-cli internal lint
）检查：
  • 每个 exercise 有 subfolders（
    problem/
    、
    solution/
    、
    explainer/
    ）
  • 至少存在 
    problem/
    、
    explainer/
    或 
    explainer.1/
    之一
  • primary subfolder 中存在非空 
    readme.md
  • 没有 
    .gitkeep
    files
  • 没有 
    speaker-notes.md
    files
  • readmes 中没有 broken links
  • readmes 中没有 
    pnpm run exercise
    commands
  • 除非是 readme-only，否则每个 subfolder 都需要 
    main.ts
检查工具（
pnpm ai-hero-cli internal lint
）会验证以下内容：
  • 每个练习都有子文件夹（
    problem/
    、
    solution/
    、
    explainer/
    ）
  • 至少存在
    problem/
    、
    explainer/
    或
    explainer.1/
    中的一个
  • 主文件夹中存在非空的
    readme.md
  • 不存在
    .gitkeep
    文件
  • 不存在
    speaker-notes.md
    文件
  • 说明文档中无无效链接
  • 说明文档中无
    pnpm run exercise
    命令
  • 除非是仅含readme的练习，否则每个子文件夹都需要
    main.ts
    文件

Moving/renaming exercises

移动/重命名练习

重新编号或移动 exercises 时：
  1. 使用 
    git mv
    （不是 
    mv
    ）重命名 directories，保留 git history
  2. 更新 numeric prefix 以维持顺序
  3. 移动后重新运行 lint
Example:
bash
git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
重新编号或移动练习时：
  1. 使用
    git mv
    （而非
    mv
    ）重命名目录，保留git历史记录
  2. 更新数字前缀以维持顺序
  3. 移动后重新运行检查
示例：
bash
git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

Example: stubbing from a plan

示例：根据计划创建Stub

给定这样的 plan：
Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory
创建：
bash
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 stubs：
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"
给定如下计划：
Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory
创建目录：
bash
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
然后创建Stub说明文档：
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"