codebase-to-course

Codebase-to-Course

将任意代码库转化为精美、交互式的单页 HTML 课程。输出是一个独立的 HTML 文件（除 Google Fonts 外无其他依赖），通过随滚动展开的模块、动态可视化图示和通俗易懂的代码解读，讲解代码的工作原理。

首次运行欢迎语

首次触发此技能且用户尚未指定代码库时，请介绍自己并说明你能做什么：

我可以把任意代码库变成一门交互式课程，帮助你了解它的工作原理——无需任何编程知识。

只需告诉我项目在哪里：

• 本地文件夹——例如，“把 ./my-project 制作成课程”
• GitHub 链接——例如，“根据 https://github.com/user/repo 制作一门课程”
• 当前项目——如果你已经在代码库中，只需说“把这个项目制作成课程”

我会通读代码，理清各部分如何协同工作，并生成一门精美的单页 HTML 课程，包含动态示意图和通俗易懂的代码解读。整个课程都可以在浏览器中运行，无需设置。

如果用户提供了 GitHub 链接，请先克隆代码库（git clone <url> /tmp/<repo-name>），再开始分析。如果用户说“这个代码库”或类似的话，请使用当前工作目录。

适合对象

目标学习者是“氛围编程者”——他们通过自然语言指示 AI 编码工具来构建软件，没有接受过传统的计算机科学教育。他们可能亲自构建了这个项目（却没有看过代码），也可能在 GitHub 上发现了一个有趣的开源项目，想了解它是如何构建的。无论哪种情况，他们都还不了解幕后发生了什么。

假设他们没有任何技术背景。 每个计算机科学概念——从变量、API 到数据库——都需要用通俗的语言解释，就像学习者从未接触过这些概念一样。不要使用未加解释的术语。不要说“你可能已经知道”。语气应像一位聪明的朋友在解释问题，而不是教授在讲课。

他们的目标注重实际应用，而非学术研究：

• 掌握足够的技术知识，以便有效地指导 AI 编码工具——做出更好的架构和技术栈决策
• 发现 AI 出错——识别幻觉、发现不良模式，并判断何时出了问题
• 在 AI 陷入困境时介入——摆脱错误循环、调试问题并自行排除障碍
• 构建质量和可靠性达到生产级别的高级软件
• 具备足够的技术表达能力，自信地与工程师讨论决策
• 掌握软件领域的词汇——学习精准的技术术语，以便向 AI 编码 Agent 清晰、准确地描述需求（例如，知道该说“命名空间包”，而不是“共享文件夹那种东西”）

他们并不打算成为软件工程师。 他们希望把编程当作一种超能力，放大自身已有的优势。他们不需要从头编写代码，而需要阅读、理解并指导代码。

这种方法为何有效

这种学习方式颠覆了传统的计算机科学教育。传统模式是：花几年时间记忆概念 → 终于开始动手构建 → 最后才明白这些知识的用处（大多数人在第 3 步之前就放弃了）。这种学习方式则是：先动手构建 → 亲眼看到它运行 → 再理解它的工作原理。

学习者已经拥有传统学生不具备的背景知识——他们用过这个应用，知道它能做什么，甚至可能用自然语言描述过它的功能。这门课程从他们当前的认知出发：“你知道自己会点的那个按钮吗？下面来看看点击它时，底层发生了什么。”

每个模块都会先回答**“这跟我有什么关系？”**，再解释“它是如何工作的？”。对“这跟我有什么关系？”的回答始终很实用：因为这些知识能帮你更好地引导 AI、更快地调试，或做出更明智的架构决策。

单文件限制是有意为之：一个 HTML 文件意味着零配置、可即时分享、离线可用，还能促使设计决策更加精简。

---

流程（4 个阶段）

阶段 1：代码库分析

编写课程 HTML 之前，要深入了解代码库。阅读所有关键文件，追踪数据流，识别“角色阵容”（主要组件/模块），并梳理它们的通信方式。在这一步下足功夫会有回报——你了解得越多，课程质量就越好。

需要提取的信息：

• 主要“参与者”（组件、服务、模块）及其职责
• 主要用户操作流程（用户从头到尾使用应用时会发生什么）
• 关键 API、数据流和通信模式
• 巧妙的工程模式（缓存、延迟加载、错误处理等）
• 真实的错误或易踩的坑（如果能从 git 历史记录或注释中看到）
• 技术栈，以及选择各项技术的原因

**通过阅读 README、主要入口文件和 UI 代码，自己弄清楚应用的功能。**不要让用户解释产品——他们可能也不熟悉它。课程一开始就应该用通俗的语言说明应用的功能（简要介绍“这个东西能做什么，以及它为什么有意思”），然后再深入讲解其工作原理。第一个模块应该从具体的用户操作开始——“假设你粘贴一个 YouTube URL 并点击 Analyze——下面来看看底层发生了什么。”

第 2 阶段：课程设计

将课程安排为 5-8 个模块。课程脉络始终从学习者已有的认知（面向用户的行为）出发，逐步深入他们尚不了解的内容（底层代码）。可以把它想象成逐步放大：先从整体体验入手，再一层层揭开内部结构。

模块位置	目的	这对氛围编程者的重要性
1	“这个应用能做什么——使用时会发生什么”	从产品入手（它能做什么、为什么有意思），然后追踪一项核心用户操作，深入代码。这能让所有内容都扎根于具体实例。
2	认识各个参与者	了解有哪些组件，这样你就能告诉 AI“把这段逻辑放进 X，而不是 Y”
3	各部分如何通信	理解数据流，以便排查“没有显示出来”这类问题
4	外部世界（API、数据库）	了解哪些内容属于外部依赖，以便评估成本、速率限制和故障模式
5	巧妙的技巧	学习各种模式（缓存、分块、错误处理），这样你就能向 AI 提出相应要求
6	出故障时	培养调试直觉，从 AI 的错误循环中脱身
7	全局概览	看清完整架构，从而更好地决定接下来要构建什么

并非每个代码库都需要全部 7 个模块。简单的 CLI 工具可能只需要 4-5 个模块。微服务应用可能需要 8 个。根据代码库的复杂程度调整课程脉络——判断哪些模块确实有助于学习者更好地引导 AI 和调试。

核心原则： 每个模块都应与一项实用技能相关联——引导 AI、调试或做决策。如果某个模块不能帮助学习者把某件事做得更好，就删掉它，或者重新设计，直到它能发挥作用。

每个模块应包含：

• 3-6 个屏幕（模块内连贯的小节）
• 至少一个代码与英文的对照翻译
• 至少一个交互元素（可视化或动画）
• 一到两个包含通用计算机科学见解的“恍然大悟！”提示框
• 一个将技术概念与日常生活联系起来的比喻——但绝不能在不同模块中重复使用同一个比喻，也绝不能默认采用“餐厅”比喻（这个比喻已经用得太多）。选择自然契合具体概念的比喻。最好的比喻会让人觉得与概念浑然天成，而不是生搬硬套。

必须包含的交互元素（每门课程都必须包含以下所有元素）：

• 群聊动画——整个课程中至少出现一次。这类动画展示组件之间类似 iMessage/微信风格的对话。它们最能吸引人，因此必须始终出现；即使需要发挥创意，把某个模块的概念设计成参与者之间的对话也要包含。
• 消息流 / 数据流动画——整个课程中至少出现一次。动画逐步展示参与者之间传递的数据包。如果代码库中存在任何类型的请求/响应、数据管道或多步骤流程，就把它制作成动画。每个代码库中都有数据流动——找到它。
• 代码 ↔ 英文翻译块——每个模块至少一个（上文已要求，但这里再次强调：这项要求不可妥协）。
• 术语表提示——每个模块中，技术术语首次出现时都要添加提示。

这五类元素是每门课程的基础。其他交互元素（架构图、图层切换、模式卡片等）可按需添加。但以上五类元素必须始终包含——无一例外。

不要把课程大纲交给用户审批——直接制作即可。 用户想要的是一门课程，而不是规划文档。请在内部设计课程大纲，然后直接生成 HTML。如果他们想要修改，会在看到结果后告诉你。

第 3 阶段：构建课程

生成一个包含内嵌 CSS 和 JavaScript 的 HTML 文件。阅读 references/design-system.md，了解完整的 CSS 设计令牌、排版和配色系统。阅读 references/interactive-elements.md，了解各类交互元素的实现模式。

构建顺序（逐项完成）：

1. 先搭建基础结构 — 创建包含所有模块区块（留空）的 HTML 框架、完整的 CSS 设计系统、带进度跟踪的导航栏、滚动吸附行为、键盘导航和滚动触发动画。完成此步骤后，你应当能获得一个可滚动浏览的可用框架。

2. 一次构建一个模块 — 填充每个模块的内容、代码翻译和交互元素。不要试图一次性编写全部 8 个模块——这样会降低质量。先构建模块 1，确认运行正常，再构建模块 2，以此类推。

3. 润色 — 构建完所有模块后，最后检查过渡效果、移动端适配和视觉一致性。

关键实现规则：

• 文件必须完全自包含（唯一的外部依赖：Google Fonts CDN）
• 使用 CSS scroll-snap-type: y proximity（不要使用 mandatory——它会让用户困在较长的模块中）
• 区块使用 min-height: 100dvh，并提供 100vh 回退值
• 为确保 GPU 性能，只为 transform 和 opacity 添加动画
• 将所有 JS 包装在 IIFE 中；滚动监听器使用 passive: true，并通过 requestAnimationFrame 进行节流
• 支持触摸拖放、键盘导航（方向键）和 ARIA 属性

第 4 阶段：审核并打开

生成课程 HTML 文件后，在浏览器中打开，供用户审核。向他们介绍已构建的内容，并征求他们对内容、设计和交互性的反馈。

---

内容理念

这些原则能让优秀课程区别于普通教程。每一项内容决策都应以此为指导：

展示，而非讲述——尽可能采用视觉呈现

人们很容易对大段文字感到厌倦。课程应更像信息图，而不是教科书。请严格遵循以下规则：

文本限制：

• 每个文本块最多 2-3 句话。如果你要写第 4 句话，请停下来，改用视觉形式呈现。
• 文本块的宽度不得超过内容区域的宽度，高度不得超过约 4 行。如果超出，请用视觉元素拆分。
• 每个屏幕至少有 50% 的内容以视觉形式呈现（图表、代码块、卡片、动画、徽章——任何非段落内容）。

将文本转化为视觉内容：

• 3 项或更多内容的列表 → 带图标的卡片（模式卡片、功能卡片）
• 一系列步骤 → 带箭头的流程图或编号步骤卡片
• “组件 A 与组件 B 通信” → 动态数据流或群聊可视化
• “这个文件执行 X，那个文件执行 Y” → 带注释的可视化文件树或图标 + 单行说明徽章
• 解释代码的作用 → 代码↔英文对照块（而不是一段关于代码的文字）
• 比较两种方法 → 并排栏，并通过视觉效果形成对比

留出视觉呼吸空间：

• 元素之间留出充足间距（区块之间使用 --space-8 到 --space-12）
• 在全宽视觉内容和窄文本块之间交替布局，营造节奏感
• 每个模块都应至少有一个“主视觉”——占据屏幕主要位置的图表、动画或交互元素，让用户一眼就能理解核心概念

代码 ↔ 英文翻译

每个代码片段旁边都要附上通俗易懂的英文翻译。左侧面板：项目中的真实代码，并带有语法高亮。右侧面板：逐行用通俗易懂的英文解释每行代码的作用。这是对非技术学习者最有价值的教学工具。

重要：代码不能出现水平滚动条。 所有代码都必须使用 white-space: pre-wrap，让代码自动换行，而不是滚动。这是面向非技术人士的课程，不是 IDE——可读性比保留缩进结构更重要。

重要：必须原样使用原始代码。 绝不能修改、简化或删减代码库中的代码片段。学习者应该能够打开真实文件，看到与所学内容完全相同的代码——这有助于建立信任。不要编辑代码来缩短片段，而应从代码库中挑选自然简短、直截了当的代码片段（5-10 行），用来清晰说明概念。每个代码库中都有简洁、独立的小段代码——找到它们，而不是把较长的函数拆得面目全非。

每个屏幕只讲一个概念

不要堆砌大段文字。每个模块中的每个屏幕只讲一个概念。如果需要更多空间，就增加一个屏幕——不要硬塞内容。

先讲比喻，再讲实际内容

每次介绍新概念时，都先用日常生活中的比喻来说明。然后立即联系实际：“在我们的代码中，它是这样的……”比喻能帮助建立直觉；代码则让概念落到实处。

重要：不要重复使用比喻。 不要凡事都用“餐厅”来打比方——这是最常见的偷懒做法。每个概念都值得拥有一个自然贴切、契合该概念本身的比喻。数据库像一座有卡片目录的图书馆。身份验证像检查证件的门卫。事件循环像一位空中交通管制员。消息传递像邮政系统。API 速率限制像有容量上限的夜店。选择能让人理解概念的比喻，而不是最容易想到的那个。如果你发现自己在一门课程中不止一次用“餐厅”或“厨房”打比方，就停下来重新想。

通过追踪来学习

追踪学习者在应用中执行某个日常操作时实际发生的过程——从头到尾跟踪数据流。“你知道自己会点击的那个按钮吗？来看看点击之后，你的数据经历了怎样的过程……”这种方式很有效，因为学习者已经体验过结果，现在可以看到背后的运作机制。这就像观看一部自己喜欢的电影的幕后纪录片。

让内容令人难忘

用“啊哈！”提示框介绍普适的计算机科学见解。适时加入幽默（不要生硬）。赋予组件个性——让它们成为故事中的“角色”，而不是图表上的抽象方框。

术语表提示框——不遗漏任何术语

每个技术术语（API、DOM、回调、中间件等）在每个模块中首次出现时，都会带有虚线下划线的提示框。桌面端悬停或移动端轻触即可查看 1–2 句话的通俗英文释义。学习者不应该为了查一个术语而离开页面去 Google 搜索。这就是一门“声称”面向非技术人士的课程与一门真正面向非技术人士的课程之间的区别。

提示框的使用要尽可能积极。 只要有 1% 的可能性让非技术人士不认识某个词，就为它添加提示框。这包括：

• 他们可能不认识的软件名称（Blender、GIMP、Audacity 等）
• 开发者日常术语（REPL、JSON、flag、CLI、API、SDK 等）
• 编程概念（函数、变量、字典、类、模块等）
• 基础设施术语（PATH、pip、命名空间、入口点等）
• 缩略词——首次出现时务必添加提示框

词汇本身就是学习内容。 学习者掌握与 AI 编码 Agent 沟通所需的精确技术词汇，是课程的核心目标之一。每个提示框都应以帮助学习者在自己的指令中使用该术语的方式进行讲解，例如：“flag 是添加到命令中的选项，用于改变命令的行为——比如添加 --json，以获取结构化数据而不是纯文本。与 AI 沟通时，你可以说‘添加一个用于输出详细信息的 flag’。”

Cursor： 对术语使用 cursor: pointer（不要用 cursor: help）。问号光标显得生硬，而指针光标会让人觉得可以点击，也更亲切。

解决提示框溢出问题： 翻译块和其他设置了 overflow: hidden 的容器会裁切提示框。解决方法是让提示框 JS 使用 position: fixed，并通过 getBoundingClientRect() 计算坐标，而不是依赖容器内 CSS 的 position: absolute。将提示框添加到 document.body，不要放在术语元素内部。这样就能确保提示框不会被任何祖先元素的溢出裁切。

设计风格

视觉设计应让人感觉像一本精美的开发者笔记本——温暖、亲切且别具一格。完整的设计 token 系统请阅读 references/design-system.md，以下是不可妥协的原则：

• 温暖的配色： 米白色背景（如泛黄的纸张）、暖灰色，禁止使用冷白色或蓝色
• 醒目的强调色： 选择一种有力的强调色（朱红、珊瑚色、蓝绿色——不要用紫色渐变）
• 别具一格的字体： 标题使用有个性的展示字体（Bricolage Grotesque 或类似的粗体几何字体——绝不使用 Inter、Roboto、Arial 或 Space Grotesk）。正文使用清爽的无衬线字体（DM Sans 或类似字体）。代码使用 JetBrains Mono。
• 宽敞留白： 模块应有呼吸感。每个屏幕最多放置 3–4 个简短段落。
• 交替背景： 奇数和偶数模块交替使用两种暖色调背景，形成视觉韵律
• 深色代码块： IDE 风格，采用 Catppuccin 风格的语法高亮，背景为深靛蓝炭灰色（#1E1E2E）
• 柔和的层次感： 使用微妙的暖色阴影，绝不使用黑色投影

---

易错点——常见失败原因

构建课程时遇到过以下实际问题。完成课程前，请逐项检查。

提示框被裁切

翻译块会使用 overflow: hidden 来实现代码换行。如果在术语元素内部使用 position: absolute，提示框就会被容器裁切。解决方法： 提示框必须使用 position: fixed 并添加到 document.body。使用 getBoundingClientRect() 计算位置。参考文件中已经说明了这一点，但这是每次构建中最常见的错误。

工具提示不足

最常见的问题是工具提示不足。非技术背景的学习者不了解 REPL、JSON、标志、入口点、PATH、pip、命名空间、函数、类、模块、PR、E2E 等术语，甚至不了解 Blender/GIMP 之类的软件名称。**经验法则：**如果某个术语不会出现在与非技术背景朋友的日常对话中，就为它添加工具提示。宁可多加，也不要少加。不过，不要为用户在其领域内已经熟悉的术语添加工具提示（例如，为 AI 领域的人解释 AI/ML 概念）。

大段文字

课程看起来像教科书，而不是信息图。这种情况通常发生在连续写了超过 2-3 句话，却没有视觉间隔时。每个屏幕至少有 50% 的内容应为视觉元素。将任何包含 3 项或更多内容的列表转换为卡片，将任何顺序流程转换为步骤卡片或流程图，将任何代码说明转换为代码↔英语对照块。

重复使用隐喻

什么都用“餐厅”或“厨房”来打比方。每个模块都需要一个独特的隐喻，并且要让人觉得它天然适合该概念。如果发现自己第二次想用同一个隐喻，就停下来，找一个更贴合该概念的隐喻。

代码修改

不要删减、简化或“清理”代码库中的代码片段。学习者应该能够打开真实文件，看到完全相同的代码。不要为了缩短代码而编辑代码，而应从代码库中选择自然简短、能够说明问题的片段（5-10 行）。

必须使用滚动吸附

使用 scroll-snap-type: y mandatory 会把用户困在较长的模块中。始终使用 proximity。

模块质量下降

试图一次性编写所有模块，会导致后面的模块内容单薄、仓促。一次构建一个模块，并在继续之前逐一验证。

缺少交互元素

模块只有文字和代码块，没有交互内容。每个模块至少需要包含以下一种元素：数据流动画、群聊、架构图、拖放交互。这些不是装饰，而是非技术背景的学习者实际理解信息的方式。

---

参考文件

references/ 目录包含详细的实现规范。进入相关阶段时，请阅读这些文件：

• references/design-system.md — 完整的 CSS 自定义属性、调色板、字体排版比例、间距系统、阴影、动画和滚动条样式。在编写任何 CSS 之前阅读此文件。
• references/interactive-elements.md — 所有交互元素的实现模式：代码↔英语对照、群聊动画、消息流可视化、架构图、模式卡片、提示框。在构建任何交互元素之前阅读此文件。