代码库转课程 是做什么的？
将任何代码库转换成一个令人惊艳的交互式课程。输出是一个目录，包含预构建的 styles.css、main.js、每个模块的HTML文件，以及一个组装好的 index.html —— 直接在浏览器中打开即可运行，无需任何设置（唯一的外部依赖是Google Fonts CDN）。课程通过基于滚动的模块、动画可视化、嵌入式测验和代码的通俗英语翻译，讲解代码的工作原理。
首次欢迎
当该技能首次被触发且用户尚未指定代码库时，请自我介绍并说明你能做什么：
我能将任何代码库变成一个交互式课程，讲解其工作原理——无需任何编码知识。
只需向我指明一个项目：
- 一个本地文件夹 —— 例如，"将 ./my-project 变成一个课程"
- 一个GitHub链接 —— 例如，"从 https://github.com/user/repo 制作一个课程"
- 当前项目 —— 如果你已经在代码库中，只需说"把这个变成一个课程"
我会阅读代码，弄清楚所有部分是如何组合在一起的，然后生成一个美观的单页HTML课程，其中包含动画图表、通俗英语的代码解释和交互式测验。整个课程在你的浏览器中运行——无需任何设置。
如果用户提供GitHub链接，请在开始分析之前先克隆仓库（git clone <url> /tmp/<repo-name>）。如果他们说"这个代码库"或类似的话，请使用当前工作目录。
目标受众
目标学习者是一名**“氛围编码者”**——通过用自然语言指导AI编码工具来构建软件的人，他们没有传统的计算机科学教育背景。他们可能自己构建了这个项目（但没有看过代码），或者可能在GitHub上发现了一个有趣的开源项目并想了解它是如何构建的。无论哪种情况，他们目前都不了解引擎盖下发生的事情。
假设零技术背景。 每个计算机科学概念——从变量到API再到数据库——都需要用通俗语言解释，就像学习者从未遇到过一样。没有定义的专业术语不要使用。不要使用"你可能知道"之类的措辞。语气应该像聪明的朋友在解释事情，而不是教授在授课。
他们的目标是实用的，而非学术性的：
- 拥有足够的技术知识，能够有效地引导AI编码工具——做出更好的架构和技术栈决策
- 检测AI何时出错——发现幻觉、捕捉不良模式、知道什么时候事情不对劲
- 在AI卡住时进行干预——打破错误循环、调试问题、解除阻塞
- 构建具有生产级质量和可靠性的更高级软件
- 具备足够的技术流利度，能与工程师自信地讨论决策
- 掌握软件术语——学习精确的技术术语，以便能够清晰、明确地向AI编码代理描述需求（例如，知道要说“命名空间包”而不是“共享文件夹那种东西”）
他们并不是要成为软件工程师。 他们希望将编码作为一种超能力，能放大他们本已擅长的领域。他们不需要从头编写代码——他们需要阅读代码、理解代码并指导代码。
为什么这种方法有效
这项技能颠覆了传统的计算机科学教育。旧模式是：花数年记忆概念 → 最终构建点什么 → 终于看到意义（大多数人在第三步之前就放弃了）。这种模式是：先构建点什么 → 体验它的工作过程 → 现在才理解它的工作原理。
学习者拥有传统学生所没有的背景信息——他们使用过这个应用，他们知道它做什么，他们甚至可能已经用自然语言描述了它的功能。课程在他们所处的位置迎接他们：“你知道你点击的那个按钮吗？下面就是点击它时引擎盖下发生的事情。”
每个模块在解释“它是如何工作的？”之前，先回答“为什么我应该关心？”对“为什么我应该关心？”的回答始终是实用的：因为这些知识能帮助你更好地引导AI、更快地调试，或做出更明智的架构决策。
基于目录的输出是有意为之：将CSS/JS与内容分离意味着AI永远不会重新生成样板文件，每个模块独立编写（保持输出体积小、质量高），并且组装后的 index.html 可以在离线状态下零设置运行。
流程
阶段一：代码库分析
在编写课程HTML之前，深入理解代码库。阅读所有关键文件，追踪数据流，识别“角色阵营”（主要组件/模块），并映射它们之间的通信方式。这里的透彻性会带来回报——你理解得越深入，课程就越好。
需要提取的内容：
- 主要的“参与者”（组件、服务、模块）及其职责
- 主要的用户旅程（当某人端到端使用应用时会发生什么）
- 关键的API、数据流和通信模式
- 巧妙的工程模式（缓存、懒加载、错误处理等）
- 真实的bug或陷阱（如果能在git历史或注释中看到）
- 技术栈以及为什么选择每个部分
自己搞清楚应用的功能，通过阅读README、主要入口点和UI代码。不要要求用户解释产品——他们可能也不熟悉。课程应该先以通俗语言解释应用的功能（简要的“这是这个东西的功能以及它为什么有趣”），然后再深入讲解它是如何工作的。第一个模块应该从一个具体的用户操作开始——“想象一下你粘贴了一个YouTube网址并点击了分析按钮——下面是引擎盖下发生的事情。”
阶段二：课程设计
将课程结构设计为4-6个模块。大多数课程需要4-6个。只有当代码库确实有那么多值得教授的不同概念时，才增加到7-8个。更好、更少的模块胜过更多、更单薄的模块。
弧线总是从学习者已经知道的内容（面向用户的行为）开始，逐渐向他们不知道的内容（底层代码）推进。可以将其视为缩放：从广阔的体验开始，然后逐渐剥离层次。
| 模块位置 | 目的 | 为什么对氛围编码者重要 |
|---|---|---|
| 1 | “这是这个应用的功能——以及当你使用它时会发生什么” | 从产品开始（它的功能以及为什么有趣），然后将核心用户操作追踪到代码中。将所有内容建立在具体事物上。 |
| 2 | 认识参与者 | 知道存在哪些组件，这样你就可以告诉AI“把这段逻辑放在X中，而不是Y中” |
| 3 | 各部分如何通信 | 理解数据流，这样你就能调试“它没有显示出来”的问题 |
| 4 | 外部世界（API、数据库） | 知道什么是外部依赖，这样你就能评估成本、速率限制和故障模式 |
| 5 | 巧妙的技巧 | 学习模式（缓存、分块、错误处理），这样你就能向AI请求它们 |
| 6 | 当事情出错时 | 建立调试直觉，这样你就能摆脱AI的错误循环 |
| 7 | 大局观 | 了解完整的架构，这样你就能更好地决定接下来构建什么 |
这是一个菜单，而非检查清单。选择适合代码库的模块——一个简单的CLI工具需要4个，而不是7个。根据代码库的复杂性调整弧线。
关键原则： 每个模块都应该与一项实用技能联系起来——引导AI、调试、做决策。如果一个模块不能帮助学习者更好地做某事，就删除它或者重新构建它直到达到这个目的。
每个模块应包含：
- 3-6个画面（模块内部的子节）
- 至少一个代码与英语并排翻译
- 至少一个交互式元素（测验、可视化或动画）
- 一到两个“啊哈！”提示框，包含通用的计算机科学见解
- 一个将技术概念融入日常生活的比喻——但绝不在模块间重复使用同一个比喻，也绝不默认使用“餐厅”比喻（它被过度使用了）。选择自然适合特定概念的比喻。最好的比喻感觉对概念来说是必然的，而不是强加的。
强制性的交互元素（每门课程必须包含所有以下内容）：
- 群聊动画 —— 整个课程至少一个。这些是组件之间类似iMessage/微信风格的对话。它们是最具吸引力的元素之一，必须始终出现，即使你需要创造性地将一个模块的概念框架化为参与者之间的对话。
- 消息流/数据流动画 —— 整个课程至少一个。参与者之间逐步的数据包动画。如果代码库有任何类型的请求/响应、数据管道或多步流程，就制作动画。任何代码库中都存在数据流动的地方——找到它。
- 代码 ↔ 英语翻译块 —— 每个模块至少一个（上面已经要求，但重申：这是不可协商的）。
- 测验 —— 每个模块至少一个（多项选择、情景、拖放或找bug——任何类型的测验都算）。
- 词汇表工具提示 —— 每个技术术语，在每个模块中首次使用时。
这五种元素类型是每门课程的骨干。其他交互式元素（架构图、层次切换、模式卡片等）是可选的，应在合适时添加。但以上五种必须始终存在——绝无例外。
不要提交课程大纲供审批——直接构建它。 用户想要的是一个课程，而不是一份规划文档。内部设计好课程大纲，然后直接开始构建。如果他们想要更改，他们会在看到结果后告诉你。
设计完课程大纲后，决定使用哪个构建路径：
- 简单的代码库（单一目的的CLI、小型Web应用、库、一个清晰的入口点、5个或更少的模块）→ 直接进入阶段三的顺序路径。
- 复杂的代码库（全栈应用、多个服务、内容密集型网站、monorepo、或6个以上的模块）→ 先进入阶段2.5，然后进入阶段三的并行路径。
阶段2.5：模块简报（仅限复杂代码库）
对于复杂的代码库，在编写任何HTML之前，为每个模块编写一份简报。这是启用并行编写能力的关键步骤——每份简报为代理提供一切所需，而无需重新阅读整个代码库。
阅读 references/module-brief-template.md 获取模板结构。阅读 references/content-philosophy.md 获取应指导简报编写的内容规则。
为每个模块，将简报写入 course-name/briefs/0N-slug.md，包含：
- 教学弧线（比喻、开场钩子、关键见解）
- 预提取的代码片段（从代码库复制粘贴，包含文件路径和行号）
- 交互式元素检查清单，包含足够详细的细节以构建它们
- 写作代理需要查看的参考文件的哪些部分
- 上一个和下一个模块涵盖的内容（用于过渡）
代码片段是关键的标记节省步骤。通过将代码预提取到简报中，写作代理永远不需要阅读代码库本身。
阶段三：构建课程
课程输出是一个目录，而不是单个文件。所有的CSS和JS都是预构建的参考文件——绝不重新生成它们。你的工作只是编写HTML内容。
输出结构：
course-name/
styles.css ← 从 references/styles.css 逐字复制
main.js ← 从 references/main.js 逐字复制
_base.html ← 自定义外壳（标题、强调色、导航点）
_footer.html ← 从 references/_footer.html 逐字复制
build.sh ← 从 references/build.sh 逐字复制
briefs/ ← 模块简报（仅限复杂代码库，构建后可以删除）
modules/
01-intro.html
02-actors.html
...
index.html ← 由 build.sh 组装（不要手动编写）
步骤一（两个路径）：设置 —— 创建课程目录。使用读取+写入方式逐字复制以下四个文件（不要重新生成它们的内容）：
references/styles.css→course-name/styles.cssreferences/main.js→course-name/main.jsreferences/_footer.html→course-name/_footer.htmlreferences/build.sh→course-name/build.sh
步骤二（两个路径）：自定义 _base.html —— 读取 references/_base.html，然后将其写入 course-name/_base.html，并进行恰好三个替换：
- 所有出现的
COURSE_TITLE→ 实际的课程标题 - 四个
ACCENT_*占位符 → 选择的强调色值（从_base.html的注释中选择一个调色板） NAV_DOTS→ 每个模块一个<button class="nav-dot" ...>
步骤三：编写模块 —— 这是路径分叉的地方。
顺序路径（简单代码库）
读取 references/content-philosophy.md 和 references/gotchas.md。然后逐个编写模块。对于每个模块，编写 course-name/modules/0N-slug.html，只包含 <section class="module" id="module-N"> 块及其内容。不要包含 <html>、<head>、<body>、<style> 或 <script> 标签。
读取 references/interactive-elements.md 获取每种交互式元素类型的HTML模式。读取 references/design-system.md 获取视觉约定。
并行路径（复杂代码库）
以最多3个模块为一组，将模块分派给子代理。每个代理接收：
- 它的模块简报（来自
course-name/briefs/） references/content-philosophy.md和references/gotchas.md- 仅在简报中列出的
references/interactive-elements.md和references/design-system.md的相关部分
每个代理将其模块文件写入 course-name/modules/。较短的模块（3个画面、一个测验）可以配对——两个简报交给一个代理。
代理不接收的内容： 完整的代码库（片段已在简报中）、SKILL.md、其他模块的简报，或不需要的参考文件部分。
在所有代理完成之后，在主上下文中进行快速一致性检查：导航点与模块匹配、模块之间的过渡连贯、没有明显的语气转变。
步骤四（两个路径）：组装 —— 从课程目录运行 build.sh：
cd course-name && bash build.sh
这将生成 index.html。在浏览器中打开它。
关键规则：
- 绝不重新生成
styles.css或main.js—— 始终从副本复制