将任意代码库转换为精美的交互式课程。默认产品版面向产品经理,聚焦业务逻辑、流程和整体架构;开发版面向程序员,聚焦架构图、数据流动画和技术方案。触发词:'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。
---
name: codebase-to-course-cn
description: 将任意代码库转换为精美的交互式课程。默认产品版面向产品经理,聚焦业务逻辑、流程和整体架构;开发版面向程序员,聚焦架构图、数据流动画和技术方案。触发词:'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。
---
# 代码库转课程
将任意代码库转换为精美的交互式课程。输出是一个**目录**,包含预构建的 `styles.css`、`main.js`、每个模块的 HTML 文件以及组装好的 `index.html` — 可直接在浏览器中打开,无需任何设置。
**支持两个版本:**
- **产品版(默认)**:面向产品经理,聚焦业务逻辑、用户流程和系统架构,不含代码细节
- **开发版**:面向程序员,包含架构图、数据流动画、技术方案描述
**重要:中国大陆可访问性要求**
此技能面向中国大陆用户,**必须确保生成的课程在中国大陆网络环境下可以完全离线运行**:
- **禁止使用 Google Fonts** 及任何 Google CDN 资源
- **禁止使用外部 CDN** 加载字体、样式或脚本
- **禁止依赖任何需要翻墙才能访问的资源**
- 所有字体必须使用系统字体或内嵌字体
- 所有资源必须本地化,确保零网络依赖
## 首次运行互动流程
当技能触发时,按顺序向用户收集以下信息,**全部收集完毕后才开始执行**:
### 第 1 步:选择版本
> 你希望生成哪个版本?
> 1. **产品版** — 面向产品经理,聚焦业务逻辑、用户流程和整体架构(默认)
> 2. **开发版** — 面向专业程序员,聚焦架构图、数据流和技术方案
>
> 也可以带上版本继续,例如"将此转换为开发版课程"。
### 第 2 步:指定关键词
> 请提供一个**中文关键词**和一个**英文关键词**,用于课程命名:
> - **中文关键词**:用于课程标题和导航显示(例如:"任务调度"、"支付系统")
> - **英文关键词**:用于输出目录名和文件命名(例如:`task-scheduler`、`payment`)
### 输出目录规则
根据用户选择的版本和英文关键词,确定课程的输出目录名:
- **产品版**:`{英文关键词}-course-pm`(例如:`task-scheduler-course-pm`)
- **开发版**:`{英文关键词}-course-pro`(例如:`task-scheduler-course-pro`)
**关于测验:**
- 产品版 **不包含测验**
- 开发版 **默认不需要测验**,仅当用户明确要求"增加测验"时才添加
**关于代码库来源:**
如果用户提供 GitHub 链接,在开始分析之前先克隆仓库(`git clone <url> /tmp/<repo-name>`)。如果他们说"此代码库"或类似表述,使用当前工作目录。
**快捷方式:** 用户也可以在一条消息中同时提供所有信息,例如:
- "开发版,中文关键词:任务调度,英文关键词:task-scheduler"
- "产品版 / 支付系统 / payment"
此时跳过逐步询问,直接开始执行。
---
## 产品版 vs 开发版 对比
| 特性 | 产品版(默认) | 开发版 |
|---|---|---|
| **目标受众** | 产品经理、业务人员 | 专业程序员 |
| **教学方式** | 业务流程图、用户旅程、系统架构概览 | 架构图、数据流动画、技术方案 |
| **代码展示** | **不展示代码** | 精选10-15行核心代码 + 设计意图 |
| **测验** | **无** | **默认不需要**(用户要求时才添加) |
| **视觉元素** | 流程图、业务架构图、用户旅程图、功能模块图 | 架构图、时序图、数据流图 |
| **语言风格** | 业务语言、产品术语、结构化清晰 | 简洁、信息密度高、技术术语 |
---
## 产品版详细指南
目标学习者是**产品经理和业务人员** —— 需要理解系统做什么、业务逻辑怎么流转、各模块如何协作,但不需要知道代码细节。
**关键原则:**
- 不展示任何代码
- 用业务语言解释系统行为,避免技术实现细节
- 聚焦"系统做了什么"而非"代码怎么写"
- 用流程图和架构图可视化业务逻辑
- 关注用户旅程、数据流转、模块职责
- 解释清楚各功能模块的输入/输出/边界
**强制交互元素(每个模块必须包含):**
- **业务流程图** — 至少一个(展示核心业务逻辑流转)
- **系统架构概览图** — 整个课程至少2个(模块关系、职责划分)
- **用户旅程图** — 整个课程至少一个(端到端用户操作路径)
- **功能模块卡片** — 展示各模块职责、输入输出
- **数据流转动画** — 整个课程至少一个(业务数据如何在系统中流动)
**禁止包含:**
- 代码片段(任何形式)
- 代码翻译块
- 测验题
- 技术实现细节(如算法、数据结构、设计模式名称)
- 词汇表提示(产品经理不需要学习编程术语)
---
## 开发版详细指南
目标学习者是**专业程序员** —— 需要快速理解代码库架构、准备技术分享或代码评审。
**核心原则:图表驱动,代码精简。**
**关键原则:**
- 信息密度优先,减少"废话"
- 直接使用技术术语,无需解释基础概念
- **图表和动画优先于代码贴片**
- 代码仅作为补充(每片段10-15行)
- 60%+ 图表/动画,25% 简洁文字,15% 精选代码
**测验为可选功能:** 默认不包含。仅当用户明确要求"增加测验"或"需要测验题"时才添加。
**强制交互元素:**
- **架构图** — 每个课程至少2个(交互式架构图,点击组件显示描述)
- **数据流动画** — 每个课程至少2个(请求/响应流转)
- **时序图/状态图** — 每个课程至少1个
- **代码分析块** — 整个课程2-3个(不是每个模块都需要)
**内容比例:**
- 60%+ 图表、动画、交互式可视化
- 25% 文字描述(技术方案、设计决策)
- 15% 代码片段(每片段10-15行)
---
## 流程
### 阶段 0:收集参数
在开始前,确认以下三个参数已收集完毕:
| 参数 | 用途 | 示例 |
|---|---|---|
| **版本** | 决定内容风格和输出目录后缀 | 产品版 / 开发版 |
| **中文关键词** | 课程标题和导航显示 | "任务调度" |
| **英文关键词** | 输出目录名和文件命名 | `task-scheduler` |
**输出目录名规则:**
- 产品版:`{英文关键词}-course-pm`
- 开发版:`{英文关键词}-course-pro`
如果用户已在首次互动中提供了所有参数,直接记录并继续。如果缺少任何参数,先补充询问。
**记录版本和关键词**,后续所有内容创作都遵循对应版本的规则,输出目录使用规则生成的名称。
### 阶段 1:代码库分析
**产品版分析重点:**
- 系统整体做了什么(产品定位、核心价值)
- 主要功能模块及其职责(用业务语言描述)
- 核心用户旅程(用户怎么用这个系统)
- 业务数据流转(数据从哪来、到哪去、经过什么处理)
- 模块间的协作关系(谁调用谁、谁依赖谁)
- 系统边界(与外部系统的交互点)
- 关键业务规则和约束
**开发版分析重点:**
- 架构风格(分层?微服务?单体?事件驱动?)
- 核心抽象(领域模型、关键接口、主要数据结构)
- 模块边界(职责划分、依赖关系、通信机制)
- 数据流路径(从请求到响应的完整链路)
- 设计决策痕迹(从代码和注释推断"为什么")
- 技术选型理由(为什么用 X 而不是 Y?)
- 扩展机制(插件系统?钩子?配置?)
- 测试策略、部署拓扑
**自己弄清楚应用做什么**,通过阅读 README、主要入口点和核心代码。不要让用户解释产品。
### 阶段 2:课程设计
将课程结构化为 **4-6 个模块**。
**产品版模块结构示例:**
| 模块 | 目的 |
|---|---|
| 1 | 产品全景(系统做什么、解决什么问题、核心价值) |
| 2 | 功能模块地图(各模块职责与边界) |
| 3 | 核心用户旅程(端到端操作流程) |
| 4 | 数据流转(业务数据如何在系统中流动) |
| 5 | 模块协作(各部分如何配合完成业务) |
| 6 | 系统边界与扩展(外部集成、未来可扩展方向) |
**开发版模块结构示例:**
| 模块 | 目的 |
|---|---|
| 1 | 架构全景(系统边界、主要组件) |
| 2 | 核心抽象与领域模型 |
| 3 | 数据流与请求生命周期 |
| 4 | 设计模式与实现技巧 |
| 5 | 扩展点与自定义 |
| 6 | 技术债务与演进方向 |
**每个模块应包含:**
- 3-6 个屏幕(模块内流动的子节)
- **产品版**:至少一个业务流程图或架构概览图、功能模块卡片
- **开发版**:至少一个架构图或数据流图、至多一个关键代码分析块
**测验要求:**
- **产品版**:不包含测验
- **开发版**:默认无测验,仅当用户明确要求"增加测验"时才添加
**不要提交课程计划供审批 —— 直接构建它。**
**设计课程计划后,决定使用哪种构建路径:**
- **简单代码库**(单一用途 CLI、小型库、清晰入口点、5 个或更少模块)→ 直接进入阶段 3 顺序路径
- **复杂代码库**(全栈应用、多个服务、单体仓库或 6+ 个模块)→ 先进入阶段 2.5,然后阶段 3 并行路径
### 阶段 2.5:模块简报(仅限复杂代码库)
阅读对应版本的参考文件:
- **产品版**:`references/content-philosophy.md`
- **开发版**:`references/module-brief-template.md` + `references/content-philosophy-pro.md`
**对于每个模块,将简报写入 `{英文关键词}-course-{pm|pro}/briefs/0N-slug.md`,包含:**
- 教学目标(学习者应获得什么)
- 预提取的代码片段
- 交互元素清单
- 相关设计决策文档
### 阶段 3:构建课程
课程输出是一个**目录**。
**输出结构:**
```
{英文关键词}-course-pm/ (产品版)
{英文关键词}-course-pro/ (开发版)
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`** — 替换标题(使用中文关键词)、强调色、导航点
**GitHub 仓库链接处理:**
- 如果课程来源于 GitHub 仓库(用户提供了 GitHub URL),保留 `_base.html` 中的 `.nav-repo-link` 元素,将 `REPO_URL` 替换为实际的 GitHub 仓库地址
- 如果课程来源于本地目录或当前项目(非 GitHub),**删除整个 `.nav-repo-link` 元素**
**步骤 3:编写模块** — 根据版本选择参考文件
选择对应的 content-philosophy 文件:
- **产品版**:阅读 `references/content-philosophy.md`
- **开发版**:阅读 `references/content-philosophy-pro.md`
同时阅读:
- `references/gotchas.md` — 常见失败点
- `references/interactive-elements.md` — 交互元素实现模式
- `references/design-system.md` — 视觉约定
对于每个模块,编写 `{英文关键词}-course-{pm|pro}/modules/0N-slug.html`,只包含 `<section class="module" id="module-N">` 块及其内容。
**步骤 4:组装** — 从课程目录运行 `build.sh`:
```bash
cd {英文关键词}-course-{pm|pro} && 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` — 开发版内容规则
## 输出语言
本技能的输出内容默认使用中文。除非用户明确要求其他语言,否则:
- 文档和说明使用中文
- 技术术语保持原文或使用中英对照
don't have the plugin yet? install it then click "run inline in claude" again.