Scaffold Exercises - 课程练习目录脚手架生成

技能概述

Scaffold Exercises 用于按统一规范批量创建课程练习目录结构，自动生成 problem、solution、explainer 等练习变体与 readme 存根，并确保结果能通过 pnpm ai-hero-cli internal lint 校验。

适用场景

1. 从零搭建一门新课程章节：拿到章节规划后，一次性创建 XX-section-name/ 章节目录和其下所有 XX.YY-exercise-name/ 练习目录，不用手动一个个 mkdir。
2. 为已有课程补充练习或存根：批量生成练习的 explainer 或 problem/solution 子目录，并写好最小可用的 readme，先把结构定下来，内容后续再填。
3. 课程改版时重新编号、移动练习：章节顺序调整或插入新练习后，用 git mv 批量重命名目录、修正数字前缀，保持顺序正确且不丢提交历史，改完再跑一遍 lint 确认无误。

核心功能

1. 规范化的目录命名：章节使用 XX-section-name/ 放在 exercises/ 下，练习使用 XX.YY-exercise-name/，章节号为 XX、练习号为 XX.YY，名称统一为小写短横线格式（dash-case），保证排序和可读性一致。
2. 练习变体与 readme 存根生成：每个练习至少创建 problem/（学员工作区，含 TODO）、solution/（参考实现）、explainer/（概念讲解，无 TODO）中的一个，默认生成 explainer/；每个子目录都会写入带标题和描述的 readme.md，存根阶段可以只建 readme、不写 main.ts。
3. lint 校验与迭代修复：生成后运行 pnpm ai-hero-cli internal lint 验证，检查内容覆盖子目录存在性、readme 非空、无失效链接、无 .gitkeep、无 speaker-notes.md、readme 中不出现 pnpm run exercise 命令、有代码时 main.ts 需超过一行等规则，报错则继续调整直到通过。
4. 安全的重命名与移动：调整练习编号时使用 git mv 而非 mv，在保持目录顺序的同时保留 git 历史，移动后重新跑 lint 复核。

常见问题

Scaffold Exercises 是什么？能做什么？

它是一个面向 AI Hero 课程体系的练习目录脚手架技能。你给出章节和练习规划，它负责创建目录、生成练习变体和 readme 存根、跑 lint 校验，并在需要重新编号时用 git mv 安全地移动目录。它负责的是"结构和规范"，练习的具体讲解内容和代码实现仍需要你自己写。

生成的练习目录能通过 lint 校验吗？

可以，这正是该技能的目标之一。它内置了 lint 规则清单，生成的结构默认满足主要约束。不过如果你的课程仓库有自己的额外规则，或者后续手动改动引入了失效链接、空 readme，仍可能报错——按提示逐条修复再重新运行即可。

problem、solution、explainer 三个子目录有什么区别？

problem/ 是给学员的工作区，里面留有待完成的 TODO；solution/ 是参考实现，供学员对照；explainer/ 是纯概念讲解材料，不包含 TODO。每个练习至少要有其中一个，如果不确定用哪种，默认用 explainer/。当练习带代码时，每个子目录还需要一个不止一行的 main.ts。

建好的练习怎么改名或重新编号？

用 git mv 重命名目录，不要用 mv，这样能保留 git 提交历史。例如把 01.03-embeddings 调成 01.04-embeddings，移动后要检查数字前缀是否仍保持正确顺序，然后重新运行 lint 验证。

只创建 readme、不写代码可以吗？

可以。存根阶段 readme-only 的练习是允许的，readme 只要有真实内容即可，哪怕只有一行标题也算通过。等到真正往子目录里加代码时，再补上满足长度要求的 main.ts。

为什么不允许有 .gitkeep 和 speaker-notes.md？

这是课程仓库的约定：空目录用 readme 占位而不是 .gitkeep，讲师备注不随练习目录一起提交。因此脚手架生成时不会创建这两类文件，lint 也会把它们判为错误。

lint 报错该怎么修？

先看报错指向哪条规则：缺子目录就补 problem/、solution/ 或 explainer/；readme 为空就补标题和描述；有失效链接就修正或删除链接；出现 .gitkeep、speaker-notes.md 就移除；readme 里写了 pnpm run exercise 就换一种表达。修完重跑 pnpm ai-hero-cli internal lint，直到全部通过再提交。