{"id":"1e47d536-aa92-484d-907b-8f6ec8ace0e4","entityType":"agent","slug":"clawhub-zhouchang1988-codebase-to-course-cn","name":"codebase-to-course-cn","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zhouchang1988-codebase-to-course-cn","canonicalPath":"/agent/clawhub-zhouchang1988-codebase-to-course-cn","generatedAt":"2026-10-11T16:01:20.264Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T13:00:04.874Z","emptyReason":null},"description":"将任意代码库转换为精美的交互式课程。默认产品版面向产品经理，聚焦业务逻辑、流程和整体架构；开发版面向程序员，聚焦架构图、数据流动画和技术方案。触发词：'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。 Skill: codebase-to-course-cn Owner: zhouchang1988 Summary: 将任意代码库转换为精美的交互式课程。默认产品版面向产品经理，聚焦业务逻辑、流程和整体架构；开发版面向程序员，聚焦架构图、数据流动画和技术方案。触发词：'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。 Tags: latest:1.2.0 Version history: v1.2.0 | 2026-05-21T09:15:07.115Z | user Release v1.2.0 from GitHub v1.1.4 | 2026-05-19T04:32:06.966Z | user Release v1.1.4 from GitHub v1.1.3 | 2026-05-15T02:27:17.173Z | user Release v1.","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1720bd1njpgkfeygpnhevb7z184dag4:codebase-to-course-cn","sourceUrl":"https://clawhub.ai/zhouchang1988/codebase-to-course-cn","homepage":"https://clawhub.ai/zhouchang1988/skills/codebase-to-course-cn","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zhouchang1988/codebase-to-course-cn","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zhouchang1988/skills/codebase-to-course-cn","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"将任意代码库转换为精美的交互式课程。默认产品版面向产品经理，聚焦业务逻辑、流程和整体架构；开发版面向程序员，聚焦架构图、数据流动画和技术方案。触发词：'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。 Skill: codebase-to-cour"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:00:04.874Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:00:04.874Z","emptyReason":null},"stars":null,"forks":null,"downloads":1061,"packageName":null,"latestVersion":"1.2.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:00:04.810Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T13:00:04.874Z","lastCrawledAt":"2026-10-11T13:00:04.810Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T13:00:04.810Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.0","createdAt":"2026-05-21T09:15:07.115Z","changelog":"Release v1.2.0 from GitHub","fileCount":17,"zipByteSize":59092},{"version":"1.1.4","createdAt":"2026-05-19T04:32:06.966Z","changelog":"Release v1.1.4 from GitHub","fileCount":16,"zipByteSize":57521},{"version":"1.1.3","createdAt":"2026-05-15T02:27:17.173Z","changelog":"Release v1.1.3 from GitHub","fileCount":16,"zipByteSize":56806},{"version":"1.1.2","createdAt":"2026-05-14T10:34:23.197Z","changelog":"Release v1.1.2 from GitHub","fileCount":16,"zipByteSize":56806},{"version":"1.1.1","createdAt":"2026-05-14T08:03:16.869Z","changelog":"Release v1.1.1 from GitHub","fileCount":16,"zipByteSize":56805},{"version":"1.1.0","createdAt":"2026-05-14T07:13:21.255Z","changelog":"Release v1.1.0 from GitHub","fileCount":16,"zipByteSize":56753},{"version":"1.0.0","createdAt":"2026-05-13T09:08:30.363Z","changelog":"Release v1.0.0 from GitHub","fileCount":16,"zipByteSize":58167}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1720bd1njpgkfeygpnhevb7z184dag4:codebase-to-course-cn","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T16:01:20.261Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhouchang1988-codebase-to-course-cn/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T13:00:04.874Z","emptyReason":null},"readme":"Skill: codebase-to-course-cn\n\nOwner: zhouchang1988\n\nSummary: 将任意代码库转换为精美的交互式课程。默认产品版面向产品经理，聚焦业务逻辑、流程和整体架构；开发版面向程序员，聚焦架构图、数据流动画和技术方案。触发词：'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。\n\nTags: latest:1.2.0\n\nVersion history:\n\nv1.2.0 | 2026-05-21T09:15:07.115Z | user\n\nRelease v1.2.0 from GitHub\n\nv1.1.4 | 2026-05-19T04:32:06.966Z | user\n\nRelease v1.1.4 from GitHub\n\nv1.1.3 | 2026-05-15T02:27:17.173Z | user\n\nRelease v1.1.3 from GitHub\n\nv1.1.2 | 2026-05-14T10:34:23.197Z | user\n\nRelease v1.1.2 from GitHub\n\nv1.1.1 | 2026-05-14T08:03:16.869Z | user\n\nRelease v1.1.1 from GitHub\n\nv1.1.0 | 2026-05-14T07:13:21.255Z | user\n\nRelease v1.1.0 from GitHub\n\nv1.0.0 | 2026-05-13T09:08:30.363Z | user\n\nRelease v1.0.0 from GitHub\n\nArchive index:\n\nArchive v1.2.0: 17 files, 59092 bytes\n\nFiles: DESIGN.md (12981b), LICENSE (1070b), README.md (3479b), references/_base.html (2850b), references/_footer.html (61b), references/build.sh (210b), references/content-philosophy-pro.md (9362b), references/content-philosophy.md (5970b), references/design-system.md (12290b), references/gotchas.md (7252b), references/interactive-elements.md (31572b), references/main.js (19539b), references/module-brief-template.md (4815b), references/styles.css (35313b), skill-card.md (2618b), SKILL.md (13246b), _meta.json (140b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: codebase-to-course-cn\ndescription: 将任意代码库转换为精美的交互式课程。默认产品版面向产品经理，聚焦业务逻辑、流程和整体架构；开发版面向程序员，聚焦架构图、数据流动画和技术方案。触发词：'将此转换为课程'、'交互式讲解此代码库'、'技术架构课程'、'代码库入门指南'、'从代码库制作教程'、'教授这段代码'。\n---\n\n# 代码库转课程\n\n将任意代码库转换为精美的交互式课程。输出是一个**目录**，包含预构建的 `styles.css`、`main.js`、每个模块的 HTML 文件以及组装好的 `index.html` — 可直接在浏览器中打开，无需任何设置。\n\n**支持两个版本：**\n- **产品版（默认）**：面向产品经理，聚焦业务逻辑、用户流程和系统架构，不含代码细节\n- **开发版**：面向程序员，包含架构图、数据流动画、技术方案描述\n\n**重要：中国大陆可访问性要求**\n\n此技能面向中国大陆用户，**必须确保生成的课程在中国大陆网络环境下可以完全离线运行**：\n- **禁止使用 Google Fonts** 及任何 Google CDN 资源\n- **禁止使用外部 CDN** 加载字体、样式或脚本\n- **禁止依赖任何需要翻墙才能访问的资源**\n- 所有字体必须使用系统字体或内嵌字体\n- 所有资源必须本地化，确保零网络依赖\n\n## 首次运行互动流程\n\n当技能触发时，按顺序向用户收集以下信息，**全部收集完毕后才开始执行**：\n\n### 第 1 步：选择版本\n\n> 你希望生成哪个版本？\n> 1. **产品版** — 面向产品经理，聚焦业务逻辑、用户流程和整体架构（默认）\n> 2. **开发版** — 面向专业程序员，聚焦架构图、数据流和技术方案\n>\n> 也可以带上版本继续，例如\"将此转换为开发版课程\"。\n\n### 第 2 步：指定关键词\n\n> 请提供一个**中文关键词**和一个**英文关键词**，用于课程命名：\n> - **中文关键词**：用于课程标题和导航显示（例如：\"任务调度\"、\"支付系统\"）\n> - **英文关键词**：用于输出目录名和文件命名（例如：`task-scheduler`、`payment`）\n\n### 输出目录规则\n\n根据用户选择的版本和英文关键词，确定课程的输出目录名：\n- **产品版**：`{英文关键词}-course-pm`（例如：`task-scheduler-course-pm`）\n- **开发版**：`{英文关键词}-course-pro`（例如：`task-scheduler-course-pro`）\n\n**关于测验：**\n- 产品版 **不包含测验**\n- 开发版 **默认不需要测验**，仅当用户明确要求\"增加测验\"时才添加\n\n**关于代码库来源：**\n\n如果用户提供 GitHub 链接，在开始分析之前先克隆仓库（`git clone /tmp/`）。如果他们说\"此代码库\"或类似表述，使用当前工作目录。\n\n**快捷方式：** 用户也可以在一条消息中同时提供所有信息，例如：\n- \"开发版，中文关键词：任务调度，英文关键词：task-scheduler\"\n- \"产品版 / 支付系统 / payment\"\n此时跳过逐步询问，直接开始执行。\n\n---\n\n## 产品版 vs 开发版 对比\n\n| 特性 | 产品版（默认） | 开发版 |\n|---|---|---|\n| **目标受众** | 产品经理、业务人员 | 专业程序员 |\n| **教学方式** | 业务流程图、用户旅程、系统架构概览 | 架构图、数据流动画、技术方案 |\n| **代码展示** | **不展示代码** | 精选10-15行核心代码 + 设计意图 |\n| **测验** | **无** | **默认不需要**（用户要求时才添加） |\n| **视觉元素** | 流程图、业务架构图、用户旅程图、功能模块图 | 架构图、时序图、数据流图 |\n| **语言风格** | 业务语言、产品术语、结构化清晰 | 简洁、信息密度高、技术术语 |\n\n---\n\n## 产品版详细指南\n\n目标学习者是**产品经理和业务人员** —— 需要理解系统做什么、业务逻辑怎么流转、各模块如何协作，但不需要知道代码细节。\n\n**关键原则：**\n- 不展示任何代码\n- 用业务语言解释系统行为，避免技术实现细节\n- 聚焦\"系统做了什么\"而非\"代码怎么写\"\n- 用流程图和架构图可视化业务逻辑\n- 关注用户旅程、数据流转、模块职责\n- 解释清楚各功能模块的输入/输出/边界\n\n**强制交互元素（每个模块必须包含）：**\n- **业务流程图** — 至少一个（展示核心业务逻辑流转）\n- **系统架构概览图** — 整个课程至少2个（模块关系、职责划分）\n- **用户旅程图** — 整个课程至少一个（端到端用户操作路径）\n- **功能模块卡片** — 展示各模块职责、输入输出\n- **数据流转动画** — 整个课程至少一个（业务数据如何在系统中流动）\n\n**禁止包含：**\n- 代码片段（任何形式）\n- 代码翻译块\n- 测验题\n- 技术实现细节（如算法、数据结构、设计模式名称）\n- 词汇表提示（产品经理不需要学习编程术语）\n\n---\n\n## 开发版详细指南\n\n目标学习者是**专业程序员** —— 需要快速理解代码库架构、准备技术分享或代码评审。\n\n**核心原则：图表驱动，代码精简。**\n\n**关键原则：**\n- 信息密度优先，减少\"废话\"\n- 直接使用技术术语，无需解释基础概念\n- **图表和动画优先于代码贴片**\n- 代码仅作为补充（每片段10-15行）\n- 60%+ 图表/动画，25% 简洁文字，15% 精选代码\n\n**测验为可选功能：** 默认不包含。仅当用户明确要求\"增加测验\"或\"需要测验题\"时才添加。\n\n**强制交互元素：**\n- **架构图** — 每个课程至少2个（交互式架构图，点击组件显示描述）\n- **数据流动画** — 每个课程至少2个（请求/响应流转）\n- **时序图/状态图** — 每个课程至少1个\n- **代码分析块** — 整个课程2-3个（不是每个模块都需要）\n\n**内容比例：**\n- 60%+ 图表、动画、交互式可视化\n- 25% 文字描述（技术方案、设计决策）\n- 15% 代码片段（每片段10-15行）\n\n---\n\n## 流程\n\n### 阶段 0：收集参数\n\n在开始前，确认以下三个参数已收集完毕：\n\n| 参数 | 用途 | 示例 |\n|---|---|---|\n| **版本** | 决定内容风格和输出目录后缀 | 产品版 / 开发版 |\n| **中文关键词** | 课程标题和导航显示 | \"任务调度\" |\n| **英文关键词** | 输出目录名和文件命名 | `task-scheduler` |\n\n**输出目录名规则：**\n- 产品版：`{英文关键词}-course-pm`\n- 开发版：`{英文关键词}-course-pro`\n\n如果用户已在首次互动中提供了所有参数，直接记录并继续。如果缺少任何参数，先补充询问。\n\n**记录版本和关键词**，后续所有内容创作都遵循对应版本的规则，输出目录使用规则生成的名称。\n\n### 阶段 1：代码库分析\n\n**产品版分析重点：**\n- 系统整体做了什么（产品定位、核心价值）\n- 主要功能模块及其职责（用业务语言描述）\n- 核心用户旅程（用户怎么用这个系统）\n- 业务数据流转（数据从哪来、到哪去、经过什么处理）\n- 模块间的协作关系（谁调用谁、谁依赖谁）\n- 系统边界（与外部系统的交互点）\n- 关键业务规则和约束\n\n**开发版分析重点：**\n- 架构风格（分层？微服务？单体？事件驱动？）\n- 核心抽象（领域模型、关键接口、主要数据结构）\n- 模块边界（职责划分、依赖关系、通信机制）\n- 数据流路径（从请求到响应的完整链路）\n- 设计决策痕迹（从代码和注释推断\"为什么\"）\n- 技术选型理由（为什么用 X 而不是 Y？）\n- 扩展机制（插件系统？钩子？配置？）\n- 测试策略、部署拓扑\n\n**自己弄清楚应用做什么**，通过阅读 README、主要入口点和核心代码。不要让用户解释产品。\n\n### 阶段 2：课程设计\n\n将课程结构化为 **4-6 个模块**。\n\n**产品版模块结构示例：**\n| 模块 | 目的 |\n|---|---|\n| 1 | 产品全景（系统做什么、解决什么问题、核心价值） |\n| 2 | 功能模块地图（各模块职责与边界） |\n| 3 | 核心用户旅程（端到端操作流程） |\n| 4 | 数据流转（业务数据如何在系统中流动） |\n| 5 | 模块协作（各部分如何配合完成业务） |\n| 6 | 系统边界与扩展（外部集成、未来可扩展方向） |\n\n**开发版模块结构示例：**\n| 模块 | 目的 |\n|---|---|\n| 1 | 架构全景（系统边界、主要组件） |\n| 2 | 核心抽象与领域模型 |\n| 3 | 数据流与请求生命周期 |\n| 4 | 设计模式与实现技巧 |\n| 5 | 扩展点与自定义 |\n| 6 | 技术债务与演进方向 |\n\n**每个模块应包含：**\n- 3-6 个屏幕（模块内流动的子节）\n- **产品版**：至少一个业务流程图或架构概览图、功能模块卡片\n- **开发版**：至少一个架构图或数据流图、至多一个关键代码分析块\n\n**测验要求：**\n- **产品版**：不包含测验\n- **开发版**：默认无测验，仅当用户明确要求\"增加测验\"时才添加\n\n**不要提交课程计划供审批 —— 直接构建它。**\n\n**设计课程计划后，决定使用哪种构建路径：**\n- **简单代码库**（单一用途 CLI、小型库、清晰入口点、5 个或更少模块）→ 直接进入阶段 3 顺序路径\n- **复杂代码库**（全栈应用、多个服务、单体仓库或 6+ 个模块）→ 先进入阶段 2.5，然后阶段 3 并行路径\n\n### 阶段 2.5：模块简报（仅限复杂代码库）\n\n阅读对应版本的参考文件：\n- **产品版**：`references/content-philosophy.md`\n- **开发版**：`references/module-brief-template.md` + `references/content-philosophy-pro.md`\n\n**对于每个模块，将简报写入 `{英文关键词}-course-{pm|pro}/briefs/0N-slug.md`，包含：**\n- 教学目标（学习者应获得什么）\n- 预提取的代码片段\n- 交互元素清单\n- 相关设计决策文档\n\n### 阶段 3：构建课程\n\n课程输出是一个**目录**。\n\n**输出结构：**\n```\n{英文关键词}-course-pm/ （产品版）\n{英文关键词}-course-pro/ （开发版）\n styles.css ← 从 references/styles.css 逐字复制\n main.js ← 从 references/main.js 逐字复制\n _base.html ← 定制的外壳（标题使用中文关键词、强调色、导航点）\n _footer.html ← 从 references/_footer.html 逐字复制\n build.sh ← 从 references/build.sh 逐字复制\n briefs/ ← 模块简报（仅限复杂代码库）\n modules/\n 01-slug.html\n 02-slug.html\n ...\n index.html ← 由 build.sh 组装\n```\n\n**步骤 1：设置** — 读取并复制四个基础文件\n\n**步骤 2：定制 `_base.html`** — 替换标题（使用中文关键词）、强调色、导航点\n\n**GitHub 仓库链接处理：**\n- 如果课程来源于 GitHub 仓库（用户提供了 GitHub URL），保留 `_base.html` 中的 `.nav-repo-link` 元素，将 `REPO_URL` 替换为实际的 GitHub 仓库地址\n- 如果课程来源于本地目录或当前项目（非 GitHub），**删除整个 `.nav-repo-link` 元素**\n\n**步骤 3：编写模块** — 根据版本选择参考文件\n\n选择对应的 content-philosophy 文件：\n- **产品版**：阅读 `references/content-philosophy.md`\n- **开发版**：阅读 `references/content-philosophy-pro.md`\n\n同时阅读：\n- `references/gotchas.md` — 常见失败点\n- `references/interactive-elements.md` — 交互元素实现模式\n- `references/design-system.md` — 视觉约定\n\n对于每个模块，编写 `{英文关键词}-course-{pm|pro}/modules/0N-slug.html`，只包含 `
` 块及其内容。\n\n**步骤 4：组装** — 从课程目录运行 `build.sh`：\n```bash\ncd {英文关键词}-course-{pm|pro} && bash build.sh\n```\n\n### 阶段 4：审查和打开\n\n运行 `build.sh` 后，在浏览器中打开 `index.html`。引导用户浏览构建的内容，并征求反馈。\n\n---\n\n## 设计身份\n\n视觉设计应该像一个**精美的开发者笔记本** —— 温暖、诱人且独特。\n\n- **产品版**：温暖调色板（米白背景、温暖灰色）、大胆强调色（朱红、珊瑚、青色）、充足留白、信息层次清晰\n- **开发版**：简洁调色板（浅灰背景、深色文字）、专业强调色（蓝、绿、橙）、信息密度高\n\n两者使用相同的 CSS/JS 基础，但通过内容组织和视觉元素来实现不同的体验。\n\n---\n\n## 参考文件\n\n`references/` 目录包含详细规范。**只在到达相关阶段时阅读它们**。\n\n**共享参考文件：**\n- `references/design-system.md` — CSS 自定义属性、调色板、排版\n- `references/interactive-elements.md` — 交互元素实现模式\n- `references/gotchas.md` — 常见失败点\n- `references/module-brief-template.md` — 模块简报模板\n\n**版本特定参考文件：**\n- `references/content-philosophy.md` — 产品版内容规则\n- `references/content-philosophy-pro.md` — 开发版内容规则\n\n## 输出语言\n\n本技能的输出内容默认使用中文。除非用户明确要求其他语言，否则：\n- 文档和说明使用中文\n- 技术术语保持原文或使用中英对照\n\nFile v1.2.0:README.md\n\n# codebase-to-course-cn\n\n> 将任意代码库转换为精美的交互式课程，直接在浏览器中打开，无需任何设置。\n\n**灵感来自 [codebase-to-course](https://github.com/zarazhangrui/codebase-to-course)** — 在原项目思路基础上进行了中文本地化适配和功能增强。\n\n## 它是什么\n\n一个 Claude Code 技能（Skill），能够分析任意代码库并生成交互式 HTML 课程。输出是一个完整目录，包含 `styles.css`、`main.js`、模块 HTML 文件和组装好的 `index.html`，双击即可在浏览器中浏览。\n\n## 两个版本\n\n| | 产品版（默认） | 开发版 |\n|---|---|---|\n| **面向谁** | 产品经理、业务人员 | 专业程序员 |\n| **怎么教** | 业务流程图、用户旅程、系统架构概览 | 架构图、数据流动画、技术方案 |\n| **代码展示** | 不展示代码 | 精选 10-15 行核心代码 |\n| **测验** | 无 | 默认不含，按需添加 |\n| **视觉风格** | 温暖亲切，像翻阅教材 | 简洁专业，信息密度高 |\n\n## 交互元素\n\n- **代码↔中文翻译块** — 左侧代码，右侧通俗解释（开发版）\n- **群聊动画** — 组件之间的对话模拟（产品版）\n- **业务流程图** — 核心业务逻辑流转可视化（产品版）\n- **数据流/消息流动画** — 请求从 A 到 B 的可视化\n- **架构图** — 点击组件查看描述（开发版）\n- **时序图/状态图** — 生命周期与状态流转（开发版）\n- **嵌入式测验** — 多选、场景、拖放、找 bug（开发版，按需添加）\n- **词汇表提示** — 技术术语首次出现时自动标注（产品版）\n\n## 使用方式\n\n在 Claude Code 中触发：\n\n```\n将 ./my-project 转换为课程\n```\n\n或指定版本：\n\n```\n将此转换为开发版课程\n```\n\n或从 GitHub 仓库生成：\n\n```\n从 https://github.com/user/repo 制作课程\n```\n\n## 中国大陆适配\n\n本技能面向中国大陆用户，**所有生成的课程均可完全离线运行**：\n\n- 禁止使用 Google Fonts 及任何 Google CDN 资源\n- 禁止使用外部 CDN 加载字体、样式或脚本\n- 字体使用系统字体回退（PingFang SC、Microsoft YaHei）\n- 零网络依赖，断网也能正常浏览\n\n## 生成的课程结构\n\n```\ncourse-name/\n styles.css ← 预构建样式\n main.js ← 交互逻辑\n _base.html ← 页面外壳\n _footer.html ← 页脚\n build.sh ← 组装脚本\n briefs/ ← 模块简报（复杂代码库）\n modules/\n 01-slug.html\n 02-slug.html\n ...\n index.html ← 组装后的完整课程\n```\n\n## 技术细节\n\n- **视觉设计**：教育出版物风格，温暖米白背景（`#FAF7F2`），朱红强调色（`#D94F30`），Catppuccin 语法高亮\n- **布局**：滚动吸附（scroll-snap），逐模块翻页浏览\n- **动画**：滚动触发的淡入效果，渐进式内容揭示\n- **响应式**：支持桌面、平板、手机三种断点\n\n## 与原项目的关系\n\n本项目是 [codebase-to-course](https://github.com/zarazhangrui/codebase-to-course) 的中文本地化衍生版本，主要变更：\n\n- 课程内容默认输出中文\n- 移除所有外部 CDN 依赖，确保中国大陆可访问\n- 字体栈替换为中文系统字体回退\n- 新增产品版和开发版双模式（产品版聚焦业务逻辑，开发版聚焦架构图、数据流动画、技术方案）\n- 交互元素实现模式本地化适配\n\n## 许可证\n\n与原项目保持一致。\n\nFile v1.2.0:_meta.json\n\n{\n \"ownerId\": \"kn7a799d479xj5aftb4bqm6ea984cv4m\",\n \"slug\": \"codebase-to-course-cn\",\n \"version\": \"1.2.0\",\n \"publishedAt\": 1779354907115\n}\n\nFile v1.2.0:references/content-philosophy-pro.md\n\n# 内容哲学 — 专业程序员版\n\n> **何时阅读此文件：** 在阶段 3（编写模块 HTML）期间。这些原则指导每个内容决策。\n\n这些原则是将优秀技术课程与普通教程区分开来的关键。\n\n### 信息密度优先\n\n专业程序员阅读速度快，理解能力强。课程应该信息密度高，减少\"废话\"。\n\n**文字原则：**\n- 每个段落有明确信息增量。如果没有新信息，删掉它。\n- 直接使用技术术语，无需解释基础概念。\n- **图表和动画优先于代码贴片。** 能用架构图、数据流动画、时序图表达的，就用可视化。\n- **代码仅作为补充。** 仅在图表无法替代时才展示代码，且每片段控制在 10-15 行。\n- 60%+ 的屏幕应该是图表、动画或交互元素，25% 是简洁的文字描述，15% 是精选代码。\n\n**将描述转换为可视化（优先级排序）：**\n- \"组件 A 调用组件 B\" → **数据流动画**（首选）或**时序图**\n- \"数据从 X 流向 Y\" → **数据流动画**\n- \"系统架构\" → **交互式架构图**（点击组件显示描述）\n- \"请求处理流程\" → **流程图** + **步骤卡片**\n- \"状态变化\" → **状态图动画**\n- \"这个函数的核心逻辑\" → **精简代码片段（10-15 行）+ 设计意图注释**（仅在可视化不足以表达时使用）\n\n**避免的做法：**\n- 不要贴超过 15 行的代码块 — 如果需要展示更多代码，拆分为多个小片段，每个片段聚焦一个概念\n- 不要连续放置两个代码块而中间没有可视化元素\n- 不要用代码来展示可以用图表表达的关系和流程\n\n### 代码分析块 — 精选且聚焦\n\n面向专业程序员的代码分析，重点不是\"这段代码做什么\"（他们能看懂代码），而是\"为什么要这样设计\"。**一个课程中只需要 2-3 个代码分析块**，每个聚焦最核心的设计决策。\n\n**代码选取原则：**\n- 每片段 **不超过 10-15 行** — 选取最能体现设计意图的核心代码\n- 优先选取：接口定义、核心数据结构、关键算法的核心逻辑\n- 不选取：配置代码、样板代码、工具函数、导入语句\n\n**结构：**\n- 左侧：精选的核心代码（保持格式，允许水平滚动）\n- 右侧：设计意图注释（不是逐行翻译）\n\n**示例：**\n\n```html\n
\n
\n CODE\n 
\nexport class EventBus {\n  private listeners = new Map<string, Set<Function>>();\n\n  subscribe(event: string, fn: Function) {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set());\n    }\n    this.listeners.get(event)!.add(fn);\n  }\n}\n
\n
\n
\n DESIGN INTENT\n
\n

为什么用 Map + Set？

\n

Map 提供 O(1) 事件查找，Set 自动去重，防止同一监听器被多次注册。这是比数组更高效的选择。

\n

扩展点：可替换为 WeakMap 避免内存泄漏，或添加优先级支持。

\n
\n
\n
\n```\n\n**关键：**\n- 代码保持原始格式，**允许水平滚动**（与 cn 版本不同）\n- 右侧解释\"为什么\"，不是\"什么\"\n- 指出设计权衡、扩展点、潜在陷阱\n\n### 架构图 — 课程的核心视觉元素\n\n架构图是课程中**最重要的元素**。每个课程必须包含至少 2 个架构图。使用交互式架构图（点击组件显示描述）。\n\n**架构图类型：**\n- **组件图** — 展示模块边界和依赖关系\n- **层次图** — 展示分层架构（表现层、业务层、数据层）\n- **部署图** — 展示服务拓扑和数据流\n\n**设计原则：**\n- 清晰的边界和箭头方向\n- 使用颜色区分不同类型的组件\n- 标注关键数据流路径\n- 包含图例\n- **每个组件可点击**，显示职责描述和关键接口\n\n### 数据流动画 — 追踪请求生命周期\n\n数据流动画是仅次于架构图的第二重要元素。每个课程至少 2 个。展示请求从入口到响应的完整旅程。\n\n**内容：**\n- 入口点（路由、控制器）\n- 中间件链\n- 业务逻辑层\n- 数据访问层\n- 外部服务调用\n- 响应返回路径\n\n**动画化：** 使用 `data-steps` 属性创建分步动画，让学习者逐步追踪数据流。\n\n### 技术方案描述 — 简洁文字替代大段代码\n\n对于技术方案和实现细节，优先使用**简洁的文字描述 + 可视化**，而不是贴大段代码。\n\n**描述模式：**\n- **方案概述** — 用 2-3 句话说明技术方案的核心思路\n- **关键决策** — 用提示框（callout）标注为什么选择这种方案\n- **实现要点** — 用编号步骤卡片（step-cards）列出关键实现步骤\n- **核心代码** — 仅在上述方式无法充分表达时，展示 10-15 行最核心的代码\n\n**示例（好的方式）：**\n> 认证系统采用 JWT + Refresh Token 双 token 方案。Access Token 有效期 15 分钟，存储在内存中；Refresh Token 有效期 7 天，存储在 HttpOnly Cookie 中。Token 验证通过中间件统一处理，失败后自动尝试刷新。\n>\n> [数据流动画：用户请求 → 中间件验证 → Token 过期 → 刷新流程 → 重新请求]\n\n**示例（差的方式）：**\n> [贴 50 行 auth middleware 代码]\n> [贴 30 行 token refresh 代码]\n> [贴 20 行 cookie 设置代码]\n\n### 测验（可选功能）\n\n**重要：测验默认不包含。** 仅当用户明确要求\"增加测验\"或\"需要测验题\"时才添加。\n\n测验应该测试学习者能否**应用**知识解决新问题，而不是回忆事实。\n\n**测验类型（按价值排序）：**\n\n1. **设计决策题** — \"如果要添加 X 功能，你会选择哪种方式？为什么？\"\n ```\n 题目：团队决定添加一个批量导出功能，预期数据量可能达到 100 万条。\n 你会选择哪种实现方式？\n\n A. 同步导出，直接在内存中处理后返回文件\n B. 异步任务队列，处理完成后发送邮件通知\n C. 流式处理，边读边写，不占用太多内存\n\n 正确答案：C 或 B（取决于具体需求）\n 解释：同步导出会超时；异步适合大规模但需要用户等待通知；\n 流式处理内存效率最高，但需要实现复杂的流控逻辑...\n ```\n\n2. **架构修改题** — \"如果要将单体拆分为微服务，你会如何划分边界？\"\n\n3. **问题诊断题** — \"用户报告 X 功能变慢，根据你学的架构，可能是什么原因？\"\n\n4. **代码定位题** — \"如果要修改 Y 行为，你需要修改哪些文件？\"\n\n**不测验的内容：**\n- 文件名记忆\n- 语法细节\n- 可以通过 Ctrl+F 找到的事实\n\n### 设计笔记提示框\n\n使用提示框标注重要的设计决策和权衡：\n\n```html\n
\n
设计笔记
\n

这里使用策略模式而不是 if-else，是为了支持未来添加新的支付方式而不修改核心逻辑。这是开闭原则的应用。

\n
\n```\n\n**类型：**\n- **设计决策** — \"为什么这样设计\"\n- **权衡说明** — \"选择了 A 而不是 B，因为...\"\n- **陷阱警告** — \"注意：这里容易出错\"\n- **扩展点** — \"如果要添加 X，可以在这里扩展\"\n\n### 技术术语处理\n\n专业程序员了解基础术语，但可能不熟悉：\n- 项目特定的术语和缩写\n- 特定框架/库的概念\n- 公司内部约定\n\n**处理方式：**\n- 项目特定术语：首次出现时用词汇表提示\n- 通用技术术语：直接使用，不解释\n- 框架特定概念：简要说明与项目的关联\n\n### 模块间的技术深度递进\n\n模块之间的深度应该递进，可视化复杂度也应递进：\n\n1. **模块 1-2**：架构层面 — 交互式架构图、组件关系图、层次图，用文字描述整体设计思路\n2. **模块 3-4**：实现层面 — 数据流动画、时序图、精选核心代码片段（2-3 个），用步骤卡片描述关键流程\n3. **模块 5-6**：进阶层面 — 状态图、场景对比图，用提示框讨论扩展策略和技术债务\n\n不要在早期模块深入代码细节，也不要在后期模块重复架构概念。\n\n### 实用性导向\n\n每个模块都应该回答一个实用问题：\n- \"我在哪里添加新功能？\"\n- \"我如何定位 bug？\"\n- \"我如何理解这个错误？\"\n- \"我如何扩展这个系统？\"\n\n如果模块不能帮助学习者解决实际问题，重新设计它。\n\nFile v1.2.0:references/content-philosophy.md\n\n# 内容哲学 — 产品经理版\n\n> **何时阅读此文件：** 在阶段 2.5（编写模块简报）和阶段 3（编写模块 HTML）期间。这些原则指导每个内容决策 —— 展示什么、如何解释以及用什么方式呈现。\n\n这些原则是让产品经理真正看懂系统的关键。\n\n### 核心原则：业务语言，零代码\n\n产品经理需要理解\"系统做了什么\"和\"业务逻辑怎么流转\"，不需要知道\"代码怎么写\"。\n\n**绝对禁止：**\n- 任何代码片段（不论长短）\n- 代码翻译块\n- 技术实现细节（算法名称、数据结构、设计模式术语）\n- 编程术语的词汇表提示\n- 测验题\n\n**语言规范：**\n- 用业务语言描述系统行为：\"用户提交订单后，系统自动校验库存\"而非\"调用 checkInventory() 方法\"\n- 用\"模块\"、\"服务\"、\"功能\"等产品经理熟悉的词汇\n- 避免\"类\"、\"函数\"、\"接口\"、\"中间件\"等编程术语\n- 可以提及技术组件的名字（如\"数据库\"、\"缓存\"、\"消息队列\"），但只解释它在业务中的角色\n\n### 展示，不要讲述 —— 极致视觉化\n\n产品经理习惯看流程图和架构图。课程应该更像产品文档而不是技术文档。\n\n**文字限制：**\n- 每个文字块最多 **3-4 个句子**。如果你在写第五句，停下来把它转换为视觉元素。\n- 每个屏幕必须 **至少 60% 是视觉内容**（流程图、架构图、卡片、模块关系图）。\n\n**将文字转换为视觉元素：**\n- 步骤描述 → **流程图**（带清晰的开始/结束/分支）\n- \"模块 A 和模块 B 协作\" → **系统架构图**（带箭头和标注）\n- \"这个功能包含 X、Y、Z\" → **功能模块卡片**（图标 + 一句话描述）\n- \"用户先做 A，再做 B\" → **用户旅程图**（带步骤编号）\n- \"数据从 X 流到 Y\" → **数据流转动画**\n- 列表描述 → **带图标的卡片网格**\n- 条件逻辑 → **决策树/分支流程图**\n\n**视觉呼吸空间：**\n- 在元素之间使用充足的间距\n- 在全宽视觉元素和窄文字块之间交替，创造节奏\n- 每个模块应该至少有一个\"英雄视觉\" —— 一个主导屏幕的图表或交互元素\n\n### 业务流程图 — 课程的核心\n\n业务流程图是产品版课程中**最重要的元素**。每个模块至少一个。\n\n**流程图类型：**\n- **用户操作流程** — 用户从开始到完成某个目标的完整路径\n- **业务逻辑流程** — 系统内部业务规则的执行顺序和分支\n- **审批/状态流程** — 数据或实体的状态变迁\n- **异常处理流程** — 出错时系统的应对策略\n\n**设计原则：**\n- 用业务语言标注每个节点（\"校验用户身份\"而非\"auth middleware\"）\n- 分支条件用业务条件表述（\"库存充足？\"而非\"inventory > 0\"）\n- 标注关键的输入和输出\n- 使用颜色区分正常路径和异常路径\n\n### 系统架构概览 — 让PM看到全景\n\n用简化的架构图展示系统的\"大图\"。不需要技术细节，只需要模块边界和职责。\n\n**展示内容：**\n- 各功能模块的名称和一句话职责\n- 模块之间的调用/依赖关系（用箭头和简短标注）\n- 外部系统的集成点\n- 数据存储的位置和用途\n\n**不展示：**\n- 具体的技术实现（框架名、库名）\n- 代码层面的依赖关系\n- 部署细节\n\n### 用户旅程图 — 端到端的产品体验\n\n从用户的视角描述使用系统的完整流程。\n\n**结构：**\n- 明确的起点（用户意图）和终点（目标达成）\n- 每一步标注：用户做了什么 → 系统做了什么 → 用户看到什么\n- 标注关键的决策点和分支路径\n- 标注可能出错的地方和系统的应对\n\n### 功能模块卡片 — 职责一目了然\n\n每个模块用一张卡片展示其核心信息。\n\n**卡片包含：**\n- 模块名称（业务名称，不是代码文件名）\n- 一句话职责描述\n- 核心功能列表（3-5 条）\n- 与其他模块的关系（谁给它数据、它给谁数据）\n\n### 数据流转 — 讲清楚\"数据去哪了\"\n\n产品经理最关心的问题之一：数据从哪来、怎么处理、到哪去。\n\n**展示方式：**\n- 用动画展示数据在系统中的流动路径\n- 每个节点标注\"对数据做了什么\"（而非\"用什么技术做的\"）\n- 标注数据格式的变化（如\"用户填的表单\" → \"存储的订单记录\"）\n- 标注数据持久化的位置\n\n### 每个屏幕一个概念\n\n不要堆砌信息。模块内的每个屏幕讲清楚一件事。\n\n**好的屏幕主题：**\n- \"订单创建的完整流程\"\n- \"支付模块和库存模块如何配合\"\n- \"系统如何处理退款请求\"\n\n**差的屏幕主题：**\n- \"后端架构和所有API\" — 太大了，拆分\n- \"技术栈介绍\" — 产品经理不需要这个\n\n### 业务规则可视化\n\n系统中的业务规则是产品经理最需要理解的部分。\n\n**展示方式：**\n- 用决策树展示条件逻辑（\"如果 VIP 用户 → 免运费；如果新用户 → 首单折扣\"）\n- 用状态图展示实体的生命周期（订单：待支付 → 已支付 → 已发货 → 已完成）\n- 用表格对比不同场景的处理方式\n\n### 模块间内容递进\n\n模块之间应该从宏观到微观递进：\n\n1. **模块 1-2**：全景层 — 系统做什么、有哪些大模块、核心价值\n2. **模块 3-4**：流程层 — 核心业务流程、用户旅程、数据流转\n3. **模块 5-6**：细节层 — 模块协作细节、边界情况、扩展方向\n\n### 实用性导向\n\n每个模块都应该回答产品经理关心的问题：\n- \"这个系统的核心业务逻辑是什么？\"\n- \"用户操作后系统内部发生了什么？\"\n- \"各模块之间是怎么配合的？\"\n- \"数据是怎么流转和存储的？\"\n- \"如果要加新功能，会影响哪些模块？\"\n- \"系统的边界在哪里？和哪些外部系统有交互？\"\n\n如果模块不能帮助产品经理理解业务逻辑或做出产品决策，重新设计它。\n\nFile v1.2.0:references/design-system.md\n\n# 设计系统参考\n\n课程的完整 CSS 设计 token。将整个 `:root` 块复制到课程 HTML 中，并调整强调色以适应项目的个性。\n\n## 目录\n1. [调色板](#调色板)\n2. [排版](#排版)\n3. [间距与布局](#间距与布局)\n4. [阴影与深度](#阴影与深度)\n5. [动画与过渡](#动画与过渡)\n6. [导航与进度](#导航与进度)\n7. [模块结构](#模块结构)\n8. [响应式断点](#响应式断点)\n9. [滚动条与背景](#滚动条与背景)\n\n---\n\n## 调色板\n\n```css\n:root {\n /* --- 背景 --- */\n --color-bg: #FAF7F2; /* 温暖的米白色，像旧纸张 */\n --color-bg-warm: #F5F0E8; /* 稍微更温暖，用于交替模块 */\n --color-bg-code: #1E1E2E; /* 深靛蓝炭黑，用于代码块 */\n --color-text: #2C2A28; /* 深炭黑，对眼睛友好 */\n --color-text-secondary: #6B6560; /* 温暖的灰色，用于次要文本 */\n --color-text-muted: #9E9790; /* 柔和的，用于时间戳、标签 */\n --color-border: #E5DFD6; /* 微妙的温暖边框 */\n --color-border-light: #EEEBE5; /* 更浅的边框 */\n --color-surface: #FFFFFF; /* 卡片表面 */\n --color-surface-warm: #FDF9F3; /* 温暖的卡片表面 */\n\n /* --- 强调色（根据项目调整 — 选择一个大胆的颜色）---\n 默认：朱红色。替代方案：珊瑚色 (#E06B56)、青色 (#2A7B9B)、\n 琥珀色 (#D4A843)、森林色 (#2D8B55)。避免紫色渐变。 */\n --color-accent: #D94F30;\n --color-accent-hover: #C4432A;\n --color-accent-light: #FDEEE9;\n --color-accent-muted: #E8836C;\n\n /* --- 语义色 --- */\n --color-success: #2D8B55;\n --color-success-light: #E8F5EE;\n --color-error: #C93B3B;\n --color-error-light: #FDE8E8;\n --color-info: #2A7B9B;\n --color-info-light: #E4F2F7;\n\n /* --- 角色颜色（分配给主要组件）---\n 代码库中的每个主要\"角色\"获得一个独特的颜色\n 用于聊天气泡、图表和高亮 */\n --color-actor-1: #D94F30; /* 朱红色 */\n --color-actor-2: #2A7B9B; /* 青色 */\n --color-actor-3: #7B6DAA; /* 柔和的梅红色 */\n --color-actor-4: #D4A843; /* 金色 */\n --color-actor-5: #2D8B55; /* 森林色 */\n}\n```\n\n**规则：**\n- 偶数模块使用 `--color-bg`，奇数模块使用 `--color-bg-warm`（交替背景创造视觉节奏）\n- 角色颜色应该在视觉上彼此区分并与强调色区分\n- 代码块始终使用 `--color-bg-code` 配浅色文本\n\n---\n\n## 排版\n\n```css\n:root {\n /* --- 字体 ---\n 使用系统字体回退，确保中国大陆用户无需翻墙即可正常显示。\n 展示/正文字体：中文优先系统字体\n 等宽字体：开发者友好的等宽系统字体回退链 */\n --font-display: 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif;\n --font-body: 'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif;\n --font-mono: 'JetBrains Mono', 'Fira Code', 'Source Code Pro', 'SF Mono', Consolas, 'Liberation Mono', Menlo, monospace;\n\n /* --- 类型比例（1.25 比例）--- */\n --text-xs: 0.75rem; /* 12px — 标签、徽章 */\n --text-sm: 0.875rem; /* 14px — 次要文本、代码 */\n --text-base: 1rem; /* 16px — 正文文本 */\n --text-lg: 1.125rem; /* 18px — 引导段落 */\n --text-xl: 1.25rem; /* 20px — 屏幕标题 */\n --text-2xl: 1.5rem; /* 24px — 子模块标题 */\n --text-3xl: 1.875rem; /* 30px — 模块副标题 */\n --text-4xl: 2.25rem; /* 36px — 模块标题 */\n --text-5xl: 3rem; /* 48px — 英雄文本 */\n --text-6xl: 3.75rem; /* 60px — 模块编号 */\n\n /* --- 行高 --- */\n --leading-tight: 1.15; /* 标题 */\n --leading-snug: 1.3; /* 小标题 */\n --leading-normal: 1.6; /* 正文文本 */\n --leading-loose: 1.8; /* 轻松阅读 */\n}\n```\n\n**注意：使用系统字体，无需外部字体链接**\n本技能面向中国大陆用户，所有字体使用系统字体回退链，无需加载 Google Fonts 或任何外部 CDN。\n\n**规则：**\n- 模块编号：`--text-6xl`、font-display、weight 800、`--color-accent` 配 15% 不透明度\n- 模块标题：`--text-4xl`、font-display、weight 700\n- 屏幕标题：`--text-xl` 或 `--text-2xl`、font-display、weight 600\n- 正文文本：`--text-base` 或 `--text-lg`、font-body、`--leading-normal`\n- 代码：`--text-sm`、font-mono\n- 标签/徽章：`--text-xs`、font-mono、大写、letter-spacing 0.05em\n\n---\n\n## 间距与布局\n\n```css\n:root {\n --space-1: 0.25rem; /* 4px */\n --space-2: 0.5rem; /* 8px */\n --space-3: 0.75rem; /* 12px */\n --space-4: 1rem; /* 16px */\n --space-5: 1.25rem; /* 20px */\n --space-6: 1.5rem; /* 24px */\n --space-8: 2rem; /* 32px */\n --space-10: 2.5rem; /* 40px */\n --space-12: 3rem; /* 48px */\n --space-16: 4rem; /* 64px */\n --space-20: 5rem; /* 80px */\n --space-24: 6rem; /* 96px */\n\n --content-width: 800px; /* 标准阅读宽度 */\n --content-width-wide: 1000px; /* 用于并排布局 */\n --nav-height: 50px;\n --radius-sm: 8px;\n --radius-md: 12px;\n --radius-lg: 16px;\n --radius-full: 9999px;\n}\n```\n\n**模块布局：**\n```css\n.module {\n min-height: 100dvh; /* 回退：100vh */\n scroll-snap-align: start;\n padding: var(--space-16) var(--space-6);\n padding-top: calc(var(--nav-height) + var(--space-12));\n}\n.module-content {\n max-width: var(--content-width);\n margin: 0 auto;\n}\n```\n\n---\n\n## 阴影与深度\n\n```css\n:root {\n --shadow-sm: 0 1px 2px rgba(44, 42, 40, 0.05);\n --shadow-md: 0 4px 12px rgba(44, 42, 40, 0.08);\n --shadow-lg: 0 8px 24px rgba(44, 42, 40, 0.1);\n --shadow-xl: 0 16px 48px rgba(44, 42, 40, 0.12);\n}\n```\n\n使用温暖色调的 RGBA（44, 42, 40）— 绝不使用纯黑色阴影。\n\n---\n\n## 动画与过渡\n\n```css\n:root {\n --ease-out: cubic-bezier(0.16, 1, 0.3, 1);\n --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);\n --duration-fast: 150ms;\n --duration-normal: 300ms;\n --duration-slow: 500ms;\n --stagger-delay: 120ms;\n}\n```\n\n**滚动触发显示模式：**\n```css\n.animate-in {\n opacity: 0;\n transform: translateY(20px);\n transition: opacity var(--duration-slow) var(--ease-out),\n transform var(--duration-slow) var(--ease-out);\n}\n.animate-in.visible {\n opacity: 1;\n transform: translateY(0);\n}\n\n/* 子元素交错显示 */\n.stagger-children > .animate-in {\n transition-delay: calc(var(--stagger-index, 0) * var(--stagger-delay));\n}\n```\n\n**交错的 JS 设置：**\n```javascript\ndocument.querySelectorAll('.stagger-children').forEach(parent => {\n Array.from(parent.children).forEach((child, i) => {\n child.style.setProperty('--stagger-index', i);\n });\n});\n```\n\n**Intersection Observer（触发显示）：**\n```javascript\nconst observer = new IntersectionObserver((entries) => {\n entries.forEach(entry => {\n if (entry.isIntersecting) {\n entry.target.classList.add('visible');\n observer.unobserve(entry.target); // 只动画一次\n }\n });\n}, { rootMargin: '0px 0px -10% 0px', threshold: 0.1 });\n\ndocument.querySelectorAll('.animate-in').forEach(el => observer.observe(el));\n```\n\n---\n\n## 导航与进度\n\n**HTML 结构：**\n```html\n\n```\n\n**进度条（尽可能只用 CSS，JS 回退）：**\n```javascript\nfunction updateProgressBar() {\n const scrollTop = window.scrollY;\n const scrollHeight = document.documentElement.scrollHeight - window.innerHeight;\n const progress = (scrollTop / scrollHeight) * 100;\n progressBar.style.width = progress + '%';\n}\nwindow.addEventListener('scroll', () => {\n requestAnimationFrame(updateProgressBar);\n}, { passive: true });\n```\n\n**导航点状态：**\n- 默认：`border: 2px solid var(--color-text-muted)`，空心\n- 当前：`border-color: var(--color-accent)`，实心中心，微妙发光阴影\n- 已访问：`background: var(--color-accent)`，实心填充\n\n**键盘导航：**\n```javascript\ndocument.addEventListener('keydown', (e) => {\n if (['INPUT', 'TEXTAREA'].includes(e.target.tagName)) return;\n if (e.key === 'ArrowDown' || e.key === 'ArrowRight') { nextModule(); e.preventDefault(); }\n if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') { prevModule(); e.preventDefault(); }\n});\n```\n\n---\n\n## 模块结构\n\n**每个模块的 HTML 模板：**\n```html\n
\n
\n
\n 0N\n

模块标题

\n

此模块教授内容的一句话描述

\n
\n\n
\n
\n

屏幕标题

\n

内容...

\n \n
\n\n
\n \n
\n
\n
\n
\n```\n\n---\n\n## 响应式断点\n\n```css\n/* 平板 */\n@media (max-width: 768px) {\n :root {\n --text-4xl: 1.875rem;\n --text-5xl: 2.25rem;\n --text-6xl: 3rem;\n }\n .translation-block { grid-template-columns: 1fr; } /* 堆叠代码/英语 */\n .pattern-cards { grid-template-columns: 1fr 1fr; }\n}\n\n/* 手机 */\n@media (max-width: 480px) {\n :root {\n --text-4xl: 1.5rem;\n --text-5xl: 1.875rem;\n --text-6xl: 2.25rem;\n }\n .module { padding: var(--space-8) var(--space-4); }\n .pattern-cards { grid-template-columns: 1fr; }\n .flow-steps { flex-direction: column; }\n .flow-arrow { transform: rotate(90deg); }\n}\n```\n\n---\n\n## 滚动条与背景\n\n```css\n/* 自定义滚动条 */\n::-webkit-scrollbar { width: 6px; }\n::-webkit-scrollbar-track { background: transparent; }\n::-webkit-scrollbar-thumb {\n background: var(--color-border);\n border-radius: var(--radius-full);\n}\n\n/* 微妙的氛围背景 */\nbody {\n background: var(--color-bg);\n background-image: radial-gradient(\n ellipse at 20% 50%,\n rgba(217, 79, 48, 0.03) 0%,\n transparent 50%\n );\n}\n\n/* 页面滚动设置 */\nhtml {\n scroll-snap-type: y proximity;\n scroll-behavior: smooth;\n}\n```\n\n---\n\n## 代码块全局设置\n\n课程中的所有代码块 —— 无论是在翻译块内、独立片段还是测验挑战中 —— 必须换行文本，绝不显示水平滚动条。这是教学工具，不是 IDE。\n\n```css\npre, code {\n white-space: pre-wrap; /* 换行长行 */\n word-break: break-word; /* 绝对需要时在单词中间断开 */\n overflow-x: hidden; /* 绝不出现水平滚动条 */\n}\n/* 隐藏代码容器上的滚动条 */\n.translation-code::-webkit-scrollbar,\npre::-webkit-scrollbar {\n display: none;\n}\n```\n\n代码片段必须是来自真实代码库的**精确副本** — 绝不修改、修剪或简化。相反，从代码中选择自然简短（5-10 行）的部分来很好地说明概念。如果需要更长的块，全部显示 —— 换行 CSS 会处理可读性。\n\n---\n\n## 语法高亮（Catppuccin 风格）\n\n用于深色 `--color-bg-code` 背景上的代码块：\n\n```css\n.code-keyword { color: #CBA6F7; } /* 紫色 — if、else、return、function */\n.code-string { color: #A6E3A1; } /* 绿色 — \"字符串\" */\n.code-function { color: #89B4FA; } /* 蓝色 — 函数名 */\n.code-comment { color: #6C7086; } /* 柔和灰色 — // 注释 */\n.code-number { color: #FAB387; } /* 桃色 — 数字 */\n.code-property { color: #F9E2AF; } /* 黄色 — 对象键 */\n.code-operator { color: #94E2D5; } /* 青色 — =、=>、+ 等 */\n.code-tag { color: #F38BA8; } /* 粉色 — HTML 标签 */\n.code-attr { color: #F9E2AF; } /* 黄色 — HTML 属性 */\n.code-value { color: #A6E3A1; } /* 绿色 — 属性值 */\n```\n\nFile v1.2.0:references/gotchas.md\n\n# 常见陷阱 —— 常见失败点\n\n> **何时阅读此文件：** 在阶段 3（编写模块 HTML）和阶段 4（审查）期间。在认为课程完成之前，检查以下每一项。\n\n根据你生成的课程版本（产品版或开发版），关注对应的检查项：\n\n---\n\n## 产品版特有问题\n\n### 提示框不足\n\n最常见的失败是提示框太少。非技术学习者不知道 REPL、JSON、标志、入口点、PATH、pip、命名空间、函数、类、模块、PR、E2E 等术语，甚至 Blender/GIMP 等软件名称。**经验法则：** 如果一个术语不会在与非技术朋友的日常对话中出现，就给它加提示框。大量倾向于太多。但是：不要给用户已经很熟悉的专业术语加提示框（例如，AI/ML 领域的人对 AI/ML 概念）。\n\n### 重复使用隐喻\n\n对所有内容使用\"餐厅\"或\"厨房\"。每个模块需要自己的隐喻，对该特定概念来说是必然的。如果你发现自己两次使用同一个隐喻，停下来找一个自然适合该概念的隐喻。\n\n### 测验数量不足\n\n**产品版要求每个模块至少一个测验。** 如果模块缺少测验，必须添加。\n\n---\n\n## 开发版特有问题\n\n### 过度解释基础概念\n\n专业程序员了解什么是 API、什么是回调、什么是数据库。不需要解释这些基础概念。\n\n**错误示例：** \"API（应用程序编程接口）是一种允许不同软件系统相互通信的方式...\"\n\n**正确示例：** \"项目使用 REST API 与支付服务通信，API 基址配置在 `config/api.ts`...\"\n\n### 缺少设计意图说明\n\n展示代码但不解释\"为什么要这样设计\"。专业程序员能看懂代码逻辑，他们想知道的是设计决策背后的原因。每个代码块都应该包含设计意图注释：权衡、替代方案、扩展点。\n\n### 架构图缺失或过于简化\n\n没有架构图，或者架构图只是简单的方框图。专业程序员需要看到：\n- 清晰的模块边界\n- 依赖方向\n- 数据流路径\n- 关键接口\n\n### 测验太简单\n\n**注意：测验在开发版中是可选功能，仅在用户明确要求时添加。**\n\n如果用户要求测验，测验问题不应该只测试表面理解，比如\"哪个文件处理 X？\"。专业程序员需要更有挑战性的问题：\n- 设计决策题（\"为什么要用策略模式而不是简单的 if-else？\"）\n- 场景题（\"如果要添加批量导出功能，你会如何实现？\"）\n- 问题诊断题（\"如果出现 Y 症状，可能是什么原因？\"）\n\n### 信息密度太低\n\n大量重复性描述，每句话信息量少。专业程序员阅读速度快，希望快速获取信息。每个段落都应该有明确的信息增量。\n\n### 代码示例不完整或被修改\n\n代码片段被过度简化，丢失了上下文信息。或者代码被\"清理\"过，不再是项目中的真实代码。\n\n**原则：** 使用真实代码，但精选最核心的 10-15 行，保留必要的上下文（导入、类型注解、注释）。\n\n### 代码过多，图表过少\n\n这是最常见的问题。课程贴了大量代码块，但缺少架构图、数据流动画和时序图。\n\n**检查标准：**\n- 每个模块是否至少有一个可视化元素（架构图、数据流动画、时序图、流程图）？\n- 单个代码块是否超过了 15 行？如果是，考虑拆分或用图表替代。\n- 是否有连续两个代码块之间没有可视化元素？\n- 课程整体的可视化元素占比是否达到 60%？\n- 是否有可以用数据流动画或步骤卡片替代代码的地方？\n\n**修复方法：** 回顾每个代码块，问自己：\"这段代码要传递的核心信息能否用图表或动画更好地表达？\" 如果能，用可视化替代。仅保留那些不可替代的核心代码片段。\n\n### 上下文耗尽导致后续模块质量下降\n\n分析大型代码库时，前面的模块占用了大量上下文，导致后面的模块信息不足、质量下降。\n\n**预防方法：**\n- 在阶段 2.5 为每个模块编写简报，后续编写时从简报读取而非重新分析代码库\n- 每完成 2 个模块后检查上下文使用情况\n- 必要时主动压缩上下文：将已提取的信息写入简报文件，释放空间\n\n### 缺少技术栈说明\n\n没有说明项目使用的技术栈以及选型理由。专业程序员关心：\n- 为什么选择 React 而不是 Vue？\n- 为什么用 PostgreSQL 而不是 MySQL？\n- 为什么选择 gRPC 而不是 REST？\n\n### 缺少扩展点和自定义机制说明\n\n专业学习者想知道\"如何添加新功能\"。课程应该明确指出：\n- 插件系统在哪里\n- 如何注册新的处理器\n- 配置扩展机制\n\n### 缺少实际应用指导\n\n课程讲清楚了\"是什么\"，但没有讲清楚\"怎么用\"。每个模块应该回答：\n- \"我在哪里添加新功能？\"\n- \"我如何定位特定类型的 bug？\"\n- \"我如何理解这个错误信息？\"\n\n---\n\n## 通用问题（两个版本都需注意）\n\n### 提示框被裁剪\n\n翻译块使用 `overflow: hidden` 来处理代码换行。如果提示框在术语元素内部使用 `position: absolute`，它们会被容器裁剪。\n\n**修复方法：** 提示框必须使用 `position: fixed` 并附加到 `document.body`。从 `getBoundingClientRect()` 计算位置。这已由 `main.js` 处理，但这是每次构建都会出现的 #1 bug。\n\n### 文字墙\n\n课程看起来像教科书而不是信息图。当你连续写超过 2-3 个句子而没有视觉中断时，就会发生这种情况。\n\n**产品版：** 每个屏幕必须至少 50% 是视觉内容（图表、代码块、问卷、动画）。\n**开发版：** 注重信息密度，可以文字占比更高，但必须有足够的图表和动画。\n\n将任何 3+ 项的列表转换为卡片，任何序列转换为步骤卡片或流程图，任何代码解释转换为代码↔英语翻译块。\n\n### 代码修改\n\n从代码库修剪、简化或\"清理\"代码片段。\n\n**产品版：** 学习者应该能够打开真实文件并看到完全相同的代码。不要通过编辑代码来使其更短，而是从代码库中*选择*自然简短（5-10 行）的片段来说明要点。\n**开发版：** 使用真实代码，仅保留必要的上下文（导入、类型注解），但保持核心逻辑完整。\n\n### 测试记忆的测验问题\n\n问\"API 代表什么？\"或\"哪个文件处理 X？\" —— 这些测试回忆，而不是理解。每个测验问题应该呈现学习者没见过的新场景，并要求他们*应用*所学内容。\n\n### 滚动捕捉强制模式\n\n使用 `scroll-snap-type: y mandatory` 会将用户困在长模块中。**始终使用 `proximity`。**\n\n### 模块质量下降\n\n尝试一次性编写所有模块会导致后面的模块变得单薄和仓促。一次构建一个模块，在继续之前验证每个模块。对于复杂代码库，使用带有模块简报的并行路径。\n\n### 缺少交互元素\n\n只有文本和代码块的模块，没有交互性。每个模块都需要交互元素。\n\n**产品版每个模块至少：** 测验、数据流动画、群聊、架构图、拖放之一\n**开发版每个模块至少：** 架构图、数据流动画、时序图之一\n\n这些不是装饰 —— 学习者是实际处理信息的方式。\n\nFile v1.2.0:references/interactive-elements.md\n\n# 交互元素参考\n\n课程中使用的每种交互元素类型的实现模式。选择最适合每个模块教学目标的元素。\n\n> **架构说明：** 这些元素的所有 CSS 和 JavaScript 都在 `references/styles.css` 和 `references/main.js` 中，它们被逐字复制到每个课程目录中。编写模块 HTML 文件时，只使用下面的 HTML 模式 — 不要为这些元素内联 `