SuperAPI AI 工具集

scaffold-exercises

编程与开发

查看项目

更新于 11-07 16:46

技能介绍

用途:scaffold-exercises 用于为课程或教程批量搭建练习目录脚手架。生成的结构需通过 pnpm ai-hero-cli internal 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/、solution/、explainer/ 中的一个子目录。problem/ 是含 TODO 的学生工作区;solution/ 是参考实现;explainer/ 是概念材料,不含 TODO。创建占位内容时,默认使用 explainer/,除非计划另有说明。

必需文件:每个子目录都需要一个 readme.md,内容不能为空(至少有一行标题),且不能有失效链接。占位时可创建最小 readme,例如:

Exercise Title

Description here

如果子目录含代码,还需要 main.ts(超过 1 行);仅创建占位内容时,只有 readme 也可以。

工作流:先解析计划,提取小节名、练习名和变体类型;再用 mkdir -p 创建各路径;然后为每个变体目录创建带标题的 readme.md 占位文件;接着运行 pnpm ai-hero-cli internal lint 校验;最后根据报错反复修改,直到通过。

Lint 规则概要:检查每个练习是否有子目录;problem/、explainer/ 或 explainer.1/ 中至少存在一个;主目录下有非空 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 校验的场景。限制:该技能依赖 pnpm ai-hero-cli internal lint 校验,其余平台支持、收费等信息暂未提供。