代码库转课程

将任意代码库转换为精美的交互式课程。输出是一个目录，包含预构建的 styles.css、main.js、每个模块的 HTML 文件以及组装好的 index.html — 可直接在浏览器中打开，无需任何设置。

支持两个版本：

• 普通版（默认）：面向"氛围程序员"（非技术人员），包含通俗英语翻译、生活隐喻和嵌入式测验
• 专业版：面向程序员，包含架构图、数据流动画、技术方案描述

重要：中国大陆可访问性要求

此技能面向中国大陆用户，必须确保生成的课程在中国大陆网络环境下可以完全离线运行：

• 禁止使用 Google Fonts 及任何 Google CDN 资源
• 禁止使用外部 CDN 加载字体、样式或脚本
• 禁止依赖任何需要翻墙才能访问的资源
• 所有字体必须使用系统字体或内嵌字体
• 所有资源必须本地化，确保零网络依赖

首次运行欢迎语

当技能首次触发且用户尚未指定代码库时，介绍自己并说明你的功能：

我可以将任意代码库转换为交互式课程，讲解其工作原理。

只需指向一个项目：

• 本地文件夹 — 例如，"将 ./my-project 转换为课程"
• GitHub 链接 — 例如，"从 https://github.com/user/repo 制作课程"
• 当前项目 — 如果你已经在代码库中，只需说"将此转换为课程"

我可以生成两个版本的课程：

• 普通版（默认）：通俗易懂的教程，适合非技术人员
• 专业版：技术架构课程，适合程序员快速上手

询问用户需要哪个版本：

你希望生成哪个版本？

1. 普通版 — 面向非技术人员，包含通俗解释和测验题（默认）
2. 专业版 — 面向专业程序员，聚焦架构图、数据流和技术方案

也可以带上版本继续，例如"将此转换为专业版课程"。

关于测验：

• 普通版 默认需要测验（每个模块至少一个）
• 专业版 默认不需要测验，仅当用户明确要求"增加测验"时才添加

如果用户提供 GitHub 链接，在开始分析之前先克隆仓库（git clone \x3Curl> /tmp/\x3Crepo-name>）。如果他们说"此代码库"或类似表述，使用当前工作目录。

普通版 vs 专业版 对比

普通版详细指南

目标学习者是**"氛围程序员"**—— 通过自然语言指导 AI 编程工具来构建软件的人，没有传统计算机科学教育背景。

关键原则：

• 假设零技术背景
• 用通俗语言解释每个概念
• 每个模块至少一个代码↔英语翻译块
• 每个模块至少一个测验
• 每个技术术语首次出现时用词汇表提示
• 使用生活隐喻（但不要重复使用"餐厅"隐喻）

强制交互元素（每个模块必须包含）：

• 代码↔英语翻译块 — 至少一个
• 测验 — 至少一个（多选、场景、拖放、找bug）
• 群聊动画 — 整个课程至少一个（组件间对话）
• 数据流/消息流动画 — 整个课程至少一个
• 词汇表提示 — 每个技术术语首次出现时

专业版详细指南

目标学习者是专业程序员 —— 需要快速理解代码库架构、准备技术分享或代码评审。

核心原则：图表驱动，代码精简。

关键原则：

• 信息密度优先，减少"废话"
• 直接使用技术术语，无需解释基础概念
• 图表和动画优先于代码贴片
• 代码仅作为补充（每片段10-15行）
• 60%+ 图表/动画，25% 简洁文字，15% 精选代码

测验为可选功能： 默认不包含。仅当用户明确要求"增加测验"或"需要测验题"时才添加。

强制交互元素：

• 架构图 — 每个课程至少2个（交互式架构图，点击组件显示描述）
• 数据流动画 — 每个课程至少2个（请求/响应流转）
• 时序图/状态图 — 每个课程至少1个
• 代码分析块 — 整个课程2-3个（不是每个模块都需要）

内容比例：

• 60%+ 图表、动画、交互式可视化
• 25% 文字描述（技术方案、设计决策）
• 15% 代码片段（每片段10-15行）

流程

阶段 0：选择版本

在开始前，通过询问或用户明确指令确定课程版本：

生成哪个版本？

• 普通版（默认）：通俗教程，适合非技术人员，包含测验
• 专业版：技术架构课程，适合程序员，默认无测验

如果用户说"专业版"、"技术版"、"架构课程"或类似词语，使用专业版。 如果用户说"给小白看的"、"通俗版本"、"带测验的"或没有指定，使用普通版（默认）。

记录版本选择，后续所有内容创作都遵循对应版本的规则。

阶段 1：代码库分析

普通版分析重点：

• 主要"角色"（组件、服务、模块）及其职责
• 主要用户旅程（端到端使用流程）
• 关键 API、数据流和通信模式
• 巧妙的工程模式（缓存、懒加载、错误处理）
• 真实的 bug 或陷阱
• 技术栈以及为什么选择每个部分

专业版分析重点：

• 架构风格（分层？微服务？单体？事件驱动？）
• 核心抽象（领域模型、关键接口、主要数据结构）
• 模块边界（职责划分、依赖关系、通信机制）
• 数据流路径（从请求到响应的完整链路）
• 设计决策痕迹（从代码和注释推断"为什么"）
• 技术选型理由（为什么用 X 而不是 Y？）
• 扩展机制（插件系统？钩子？配置？）
• 测试策略、部署拓扑

自己弄清楚应用做什么，通过阅读 README、主要入口点和核心代码。不要让用户解释产品。

阶段 2：课程设计

将课程结构化为 4-6 个模块。

普通版模块结构示例：

专业版模块结构示例：

每个模块应包含：

• 3-6 个屏幕（模块内流动的子节）
• 普通版：至少一个代码翻译块、至少一个交互元素、一两种解释技巧
• 专业版：至少一个架构图或数据流图、至多一个关键代码分析块

测验要求：

• 普通版：每个模块至少一个测验（多选、场景、拖放、找bug）
• 专业版：默认无测验，仅当用户明确要求"增加测验"时才添加

不要提交课程计划供审批 —— 直接构建它。

设计课程计划后，决定使用哪种构建路径：

• 简单代码库（单一用途 CLI、小型库、清晰入口点、5 个或更少模块）→ 直接进入阶段 3 顺序路径
• 复杂代码库（全栈应用、多个服务、单体仓库或 6+ 个模块）→ 先进入阶段 2.5，然后阶段 3 并行路径

阶段 2.5：模块简报（仅限复杂代码库）

阅读对应版本的参考文件：

• 普通版：references/content-philosophy.md
• 专业版：references/module-brief-template.md + references/content-philosophy.md

对于每个模块，将简报写入 course-name/briefs/0N-slug.md，包含：

• 教学目标（学习者应获得什么）
• 预提取的代码片段
• 交互元素清单
• 相关设计决策文档

阶段 3：构建课程

课程输出是一个目录。

输出结构：

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-slug.html
    02-slug.html
    ...
  index.html       ← 由 build.sh 组装

步骤 1：设置 — 读取并复制四个基础文件

步骤 2：定制 _base.html — 替换标题、强调色、导航点

步骤 3：编写模块 — 根据版本选择参考文件

选择对应的 content-philosophy 文件：

• 普通版：阅读 references/content-philosophy.md
• 专业版：阅读 references/content-philosophy-pro.md

同时阅读：

• references/gotchas.md — 常见失败点
• references/interactive-elements.md — 交互元素实现模式
• references/design-system.md — 视觉约定

对于每个模块，编写 course-name/modules/0N-slug.html，只包含 \x3Csection class="module" id="module-N"> 块及其内容。

步骤 4：组装 — 从课程目录运行 build.sh：

cd course-name && bash build.sh

阶段 4：审查和打开

运行 build.sh 后，在浏览器中打开 index.html。引导用户浏览构建的内容，并征求反馈。

设计身份

视觉设计应该像一个精美的开发者笔记本 —— 温暖、诱人且独特。

• 普通版：温暖调色板（米白背景、温暖灰色）、大胆强调色（朱红、珊瑚、青色）、充足留白
• 专业版：简洁调色板（浅灰背景、深色文字）、专业强调色（蓝、绿、橙）、信息密度高

两者使用相同的 CSS/JS 基础，但通过内容组织和视觉元素来实现不同的体验。

参考文件

references/ 目录包含详细规范。只在到达相关阶段时阅读它们。

共享参考文件：

• references/design-system.md — CSS 自定义属性、调色板、排版
• references/interactive-elements.md — 交互元素实现模式
• references/gotchas.md — 常见失败点
• references/module-brief-template.md — 模块简报模板

版本特定参考文件：

• references/content-philosophy.md — 普通版内容规则
• references/content-philosophy-pro.md — 专业版内容规则

输出语言

本技能的输出内容默认使用中文。除非用户明确要求其他语言，否则：

• 文档和说明使用中文
• 代码注释保留原有语言（普通版）、或用中文（专业版）
• 技术术语保持原文或使用中英对照