Back to Details

codemermaid

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CodeMermaid

CodeMermaid

Generate a multi-page interactive HTML site that teaches a codebase as scrollable essays — architecture views, default Build-Up walkthroughs, beautiful-mermaid diagrams, typed pedagogical units (concept, quiz, takeaway, diagram, code-walk, code-graph, whoa) carrying the lesson. Zero build tools, zero npm. Each output page links shared CSS, runtime JS, and the beautiful-mermaid browser bundle; diagrams render client-side with Raycast dark theming.
生成一个多页交互式HTML站点，以可滚动的文章形式讲解代码库——包含架构视图、默认的Build-Up导览、美观的Mermaid图表、承载课程内容的多种教学单元（concept、quiz、takeaway、diagram、code-walk、code-graph、whoa）。无需构建工具，无需npm。每个输出页面都会链接共享CSS、运行时JS以及beautiful-mermaid浏览器包；图表采用Raycast深色主题在客户端渲染。

When to Use

适用场景

  • "Generate an interactive course for this codebase"
  • "Create a visual walkthrough of this project's architecture"
  • "Make an interactive module dependency diagram"
  • "Build a tutorial page from this codebase"
  • "为这个代码库生成交互式课程"
  • "创建该项目架构的可视化导览"
  • "制作交互式模块依赖图"
  • "基于这个代码库构建教程页面"

Output

输出内容

Directory: 
docs/codemermaid/
style.css                     <- Copied from assets/style.css
runtime.js                    <- Copied from assets/runtime.js
index.html                    <- Entry page (perspective + module cards)
architecture.html             <- Architecture perspective (essay, always generated)
build-up.html                 <- Build-Up Walkthrough perspective (essay, always generated)
<perspective>.html            <- Other user-requested or auto-inferred perspectives (essays)
module-<name>.html            <- Per-module deep dives (essays, optional module-level Build-Up when useful)
Each HTML page links 
style.css
, 
runtime.js
, 
beautiful-mermaid.bundle.js
, and 
mermaid-bridge.js
via 
<link>
and 
<script src>
. Diagrams use Mermaid.js syntax rendered via the beautiful-mermaid browser bundle. The assembly process copies these assets from 
assets/
to the output directory alongside the HTML files.
目录：
docs/codemermaid/
style.css                     <- 从assets/style.css复制而来
runtime.js                    <- 从assets/runtime.js复制而来
index.html                    <- 入口页面（视角概览 + 模块卡片）
architecture.html             <- 架构视角页面（文章形式，始终生成）
build-up.html                 <- Build-Up导览视角页面（文章形式，始终生成）
<perspective>.html            <- 其他用户请求或自动推断的视角页面（文章形式）
module-<name>.html            <- 逐模块深度解析页面（文章形式，必要时包含模块级Build-Up内容）
每个HTML页面通过
<link>
和
<script src>
链接
style.css
、
runtime.js
、
beautiful-mermaid.bundle.js
和
mermaid-bridge.js
。图表使用Mermaid.js语法，通过beautiful-mermaid浏览器包渲染。生成过程会将这些资源从
assets/
目录复制到输出目录，与HTML文件放在一起。

Parallel Generation Mode

并行生成模式

If subagents are available and the repo has enough independent modules, read 
references/subagent-generation.md
before dispatching work.
The main agent remains coordinator and owns the module registry, filename registry, perspective list, index page, link graph, and final validation. Subagents may only work inside assigned scopes.
如果有子代理可用且代码仓库包含足够多的独立模块，在分配任务前请阅读
references/subagent-generation.md
。
主代理作为协调者，负责模块注册表、文件名注册表、视角列表、索引页面、链接图和最终验证。子代理只能在指定范围内工作。

Phase 1: Scan

阶段1：扫描

Read the codebase exhaustively. The goal is to discover ALL meaningful modules, not just the obvious ones.
全面读取代码库。目标是发现所有有意义的模块，而不仅仅是明显的模块。

Step 1.1: Structural Scan

步骤1.1：结构扫描

  1. Root directory — list all top-level folders and files
  2. Source directories — for each top-level folder, list its contents recursively (2 levels deep)
  3. Entry files — 
    main.*
    , 
    index.*
    , 
    app.*
    , 
    server.*
    , 
    cmd/
    , 
    src/
    , 
    lib/
    , 
    pkg/
  4. Config files — 
    package.json
    , 
    go.mod
    , 
    Cargo.toml
    , 
    pyproject.toml
    , 
    Makefile
    , 
    docker-compose.yml
    , equivalent
  5. Framework detection — language, framework, runtime from config and imports
  6. Test directories — 
    test/
    , 
    tests/
    , 
    spec/
    , 
    __tests__/
    , 
    *_test.*
  1. 根目录 — 列出所有顶级文件夹和文件
  2. 源目录 — 对每个顶级文件夹，递归列出其内容（深度为2层）
  3. 入口文件 — 
    main.*
    、
    index.*
    、
    app.*
    、
    server.*
    、
    cmd/
    、
    src/
    、
    lib/
    、
    pkg/
  4. 配置文件 — 
    package.json
    、
    go.mod
    、
    Cargo.toml
    、
    pyproject.toml
    、
    Makefile
    、
    docker-compose.yml
    及同类文件
  5. 框架检测 — 从配置文件和导入语句中识别语言、框架和运行时
  6. 测试目录 — 
    test/
    、
    tests/
    、
    spec/
    、
    __tests__/
    、
    *_test.*

Step 1.2: Deep Module Discovery

步骤1.2：深度模块发现

For EACH source directory found above, determine if it qualifies as a module:
  • A module is any directory or file that has a clear single responsibility
  • Read the first 30 lines of every entry file to understand purpose
  • Use Grep to find 
    import
    , 
    require
    , 
    use
    , 
    from
    patterns — map dependency edges
  • Check 
    exports
    , 
    module.exports
    , 
    pub
    , 
    public
    — identify public interfaces
What counts as a module:
TypeExamples
Top-level source dir
src/auth/
, 
src/api/
, 
src/models/
Standalone config file
tsconfig.json
, 
docker-compose.yml
, 
.env.example
Utility/helper dir
src/utils/
, 
src/helpers/
, 
src/lib/
Plugin/extension dir
plugins/
, 
extensions/
, 
modules/
Data layer
src/db/
, 
src/store/
, 
src/repositories/
Build/CI config
Makefile
, 
Dockerfile
, 
.github/workflows/
Skill/command dir
.agents/skills/
, 
.opencode/commands/
Single important file
skills-lock.json
, 
CLAUDE.md
, routing config
What to skip:
  • node_modules/
    , 
    vendor/
    , 
    .git/
    , 
    dist/
    , 
    build/
    , cache dirs
  • Generated files, lock files (except 
    skills-lock.json
    if meaningful)
  • Test fixtures, static assets with no logic
对于上述发现的每个源目录，判断其是否符合模块的定义：
  • 模块指任何具有明确单一职责的目录或文件
  • 读取每个入口文件的前30行，了解其用途
  • 使用Grep查找
    import
    、
    require
    、
    use
    、
    from
    等模式——绘制依赖关系边
  • 检查
    exports
    、
    module.exports
    、
    pub
    、
    public
    ——识别公共接口
符合模块定义的类型：
类型示例
顶级源目录
src/auth/
、
src/api/
、
src/models/
独立配置文件
tsconfig.json
、
docker-compose.yml
、
.env.example
工具/辅助目录
src/utils/
、
src/helpers/
、
src/lib/
插件/扩展目录
plugins/
、
extensions/
、
modules/
数据层
src/db/
、
src/store/
、
src/repositories/
构建/CI配置
Makefile
、
Dockerfile
、
.github/workflows/
技能/命令目录
.agents/skills/
、
.opencode/commands/
重要独立文件
skills-lock.json
、
CLAUDE.md
、路由配置
需要跳过的内容：
  • node_modules/
    、
    vendor/
    、
    .git/
    、
    dist/
    、
    build/
    、缓存目录
  • 生成文件、锁文件（除非
    skills-lock.json
    具有重要意义）
  • 测试 fixtures、无逻辑的静态资源

Step 1.3: Dependency Mapping

步骤1.3：依赖关系映射

For every module discovered, trace its imports:
Module A → imports from → Module B, Module C
Module B → imports from → Module D
Module C → imports from → Module D (optional)
This becomes the edge list for Mermaid diagrams. Use Glob and Grep extensively. Read actual code. Do NOT guess.
对于每个发现的模块，追踪其导入关系：
模块A → 导入自 → 模块B、模块C
模块B → 导入自 → 模块D
模块C → 导入自 → 模块D（可选）
这将成为Mermaid图表的边列表。广泛使用Glob和Grep工具，读取实际代码，不要猜测。

Phase 2: Analyze

阶段2：分析

From scan results:
  1. Architecture pattern — MVC, microservices, monolith, event-driven, hexagonal, layered, etc.
  2. Data flow — trace the primary request path entry → response, and secondary flows
  3. Module graph — full dependency graph from Phase 1.3, identify cycles and layers
  4. Key abstractions — interfaces, base classes, core types that define the system's vocabulary
  5. Module categorization — group modules into layers:
LayerTypical Modules
EntryHTTP handlers, CLI commands, main entry points
CoreBusiness logic, domain models, services
DataDatabase, repositories, ORM, state management
InfraConfig, logging, middleware, error handling
OutputTemplates, serializers, API responses
DevXBuild tools, CI/CD, skills, commands
Prioritization: If the codebase has more than 12 modules, organize into sub-graphs.
  1. Default perspective requirements — Architecture and Build-Up are always included. 
    architecture.html
    gives the finished-system map; 
    build-up.html
    gives the gradual learning route from smallest useful capability to complete system.
  2. User perspective requirements — parse user prompt for explicit perspective requests. User-requested perspectives are mandatory.
  3. Auto-infer perspectives — from project characteristics:
    • Has HTTP handlers, WebSocket, or event streams → Data Flow perspective
    • Has database/ORM → Data Model perspective
    • Has state management → State Machine perspective
    • 10+ modules → Module Dependency perspective
    • Has CI/CD config → Build Pipeline perspective
  4. Merge perspective list — default + user-specified + auto-inferred, deduplicated. Recommended index order: Architecture Overview, Build-Up Walkthrough, then user-requested and auto-inferred perspectives. Every discovered module must be reachable from at least one perspective page.
  5. Derive Build-Up route — before drafting 
    build-up.html
    , read 
    references/build-up.md
    and choose a reader-comprehension order from discovered modules and dependency evidence.
从扫描结果中：
  1. 架构模式 — MVC、微服务、单体应用、事件驱动、六边形架构、分层架构等
  2. 数据流 — 追踪主请求路径的入口→响应流程，以及次要流程
  3. 模块图 — 阶段1.3生成的完整依赖图，识别循环和分层
  4. 核心抽象 — 定义系统词汇的接口、基类、核心类型
  5. 模块分类 — 将模块分组为不同层级：
层级典型模块
入口层HTTP处理器、CLI命令、主入口点
核心层业务逻辑、领域模型、服务
数据层数据库、仓库、ORM、状态管理
基础设施层配置、日志、中间件、错误处理
输出层模板、序列化器、API响应
DevX层构建工具、CI/CD、技能、命令
优先级： 如果代码库包含超过12个模块，组织为子图。
  1. 默认视角要求 — 始终包含Architecture和Build-Up视角。
    architecture.html
    展示完整系统的架构图；
    build-up.html
    提供从最小可用功能到完整系统的渐进式学习路径。
  2. 用户视角要求 — 解析用户提示中的明确视角请求。用户指定的视角是必填项。
  3. 自动推断视角 — 根据项目特征推断：
    • 包含HTTP处理器、WebSocket或事件流 → 数据流视角
    • 包含数据库/ORM → 数据模型视角
    • 包含状态管理 → 状态机视角
    • 模块数量≥10 → 模块依赖视角
    • 包含CI/CD配置 → 构建流水线视角
  4. 合并视角列表 — 合并默认、用户指定和自动推断的视角，去重。推荐的索引顺序：架构概览、Build-Up导览，然后是用户请求和自动推断的视角。每个发现的模块必须至少能从一个视角页面访问到。
  5. 推导Build-Up路径 — 在编写
    build-up.html
    之前，阅读
    references/build-up.md
    ，根据发现的模块和依赖证据选择便于读者理解的顺序。

Phase 3: Build Page Data

阶段3：构建页面数据

Each per-module and per-perspective page has a 
learningPromise
, optional 
prereqs
, and a 
units[]
array. Read 
references/units-examples.md
for concrete patterns and 
references/voice-examples.md
for tone.
每个模块页面和视角页面都包含
learningPromise
、可选的
prereqs
和
units[]
数组。请阅读
references/units-examples.md
获取具体模式，阅读
references/voice-examples.md
了解语气要求。

COURSE (per-module page, 
module-<name>.html
)

课程（模块页面，
module-<name>.html
）

javascript
const COURSE = {
  module: "auth",
  learningPromise: "...",
  prereqs: ["..."],
  units: []
};
Module pages may include a module-level Build-Up section when the module has a natural internal progression. This section is optional; read 
references/build-up.md
before adding one.
javascript
const COURSE = {
  module: "auth",
  learningPromise: "...",
  prereqs: ["..."],
  units: []
};
当模块具有自然的内部演进逻辑时，模块页面可包含模块级Build-Up部分。此部分为可选内容；添加前请阅读
references/build-up.md
。

PERSPECTIVE (per-perspective page, e.g. 
architecture.html
)

视角（视角页面，例如
architecture.html
）

javascript
const PERSPECTIVE = {
  perspective: "architecture",
  learningPromise: "...",
  prereqs: ["..."],
  units: []
};
javascript
const PERSPECTIVE = {
  perspective: "architecture",
  learningPromise: "...",
  prereqs: ["..."],
  units: []
};

BUILD_UP (default perspective page, 
build-up.html
)

Build-Up（默认视角页面，
build-up.html
）

Build-Up is a required perspective. Before drafting it, read 
references/build-up.md
for route design, capability increments, examples, module-level Build-Up criteria, and Mermaid/code pairing rules.
Build-Up是必填视角。编写前请阅读
references/build-up.md
，了解路径设计、功能增量、示例、模块级Build-Up标准以及Mermaid/代码配对规则。

INDEX (entry page, 
index.html
)

索引（入口页面，
index.html
）

javascript
const INDEX = {
  project: { name, description, language, framework },
  perspectives: [{ title, description, page, unitCount }],
  modules:      [{ title, description, page, unitCount }]
};
javascript
const INDEX = {
  project: { name, description, language, framework },
  perspectives: [{ title, description, page, unitCount }],
  modules:      [{ title, description, page, unitCount }]
};

Unit kinds (7 types)

单元类型（7种）

javascript
{ kind: "concept",     title, body, style? }                          // style: "callout" for surprise-style red border
{ kind: "quiz",        question, options: [{letter, text, correct}], explanation }
{ kind: "takeaway",    body }
{ kind: "diagram",     title, mermaid, caption, zoomable? }               // Mermaid syntax, zoomable defaults true
{ kind: "code-walk",   title, file, startLine?, code, highlights: [{line, note}], layout? }  // layout defaults "split"
{ kind: "code-graph",  title, file, startLine?, code, highlights: [{line, note, graphNode?}], svg }  // left code, right mini graph
{ kind: "whoa",        angle, title, body, evidence? }                    // angle: "code" | "product" | "ux" | "architecture"
javascript
{ kind: "concept",     title, body, style? }                          // style: "callout"表示带红色边框的提示样式
{ kind: "quiz",        question, options: [{letter, text, correct}], explanation }
{ kind: "takeaway",    body }
{ kind: "diagram",     title, mermaid, caption, zoomable? }               // Mermaid语法，zoomable默认值为true
{ kind: "code-walk",   title, file, startLine?, code, highlights: [{line, note}], layout? }  // layout默认值为"split"
{ kind: "code-graph",  title, file, startLine?, code, highlights: [{line, note, graphNode?}], svg }  // 左侧代码，右侧迷你图
{ kind: "whoa",        angle, title, body, evidence? }                    // angle: "code" | "product" | "ux" | "architecture"

Whoa unit rules

Whoa单元规则

Use 
whoa
only for rare design moments with strong evidence that explains why the project is unusually well-designed. Use zero 
whoa
units when there is no strong evidence. When evidence exists, a normal course should stay around 3-5 
whoa
units total across all pages.
Required fields:
  • angle
    : one of 
    code
    , 
    product
    , 
    ux
    , or 
    architecture
    .
  • title
    : a concrete statement of the design win.
  • body
    : explains the constraint, why the design is strong, and what would be worse without it.
Optional 
evidence
fields:
javascript
{
  files?: string[],
  modules?: string[],
  interactions?: string[],
  constraints?: string[]
}
Use one visual treatment for every angle. 
angle
changes the label and placement, not the color palette.
仅当存在充分证据表明项目设计异常出色时，才使用
whoa
单元。若无充分证据，则不使用
whoa
单元。当存在证据时，一个标准课程在所有页面中总共应包含3-5个
whoa
单元。
必填字段：
  • angle
    ：取值为
    code
    、
    product
    、
    ux
    或
    architecture
    之一。
  • title
    ：明确说明设计亮点的具体陈述。
  • body
    ：解释约束条件、设计优势以及如果没有该设计会带来的问题。
可选
evidence
字段：
javascript
{
  files?: string[],
  modules?: string[],
  interactions?: string[],
  constraints?: string[]
}
每个
angle
使用一种视觉样式。
angle
会改变标签和位置，但不会改变调色板。

Voice rules

语气规则

Before writing generated prose, read 
references/voice-examples.md
. Follow that file for voice, signposts, anti-patterns, and rewrite recipes.
在编写生成的文本之前，请阅读
references/voice-examples.md
。遵循该文件中的语气、提示语、反模式和改写规则。

Code explanation depth (mandatory — do not skimp)

代码解释深度（必填 — 切勿简化）

Every piece of code shown to the reader MUST be thoroughly explained. This is the core value of the course — the reader is here to understand code they couldn't read on their own.
concept units before a code-walk must explain:
  • What the module/function does and why it exists (its role in the system)
  • What pattern or tradeoff is at play (why this approach over alternatives)
  • Any non-obvious context the reader needs before seeing the code
code-walk highlights[].note must explain:
  • What the highlighted line does (not just restate the code — explain the why)
  • How it connects to the surrounding logic (data flow, control flow, side effects)
  • Any implicit behavior not visible in the code (e.g., "this returns null because the upstream function hasn't resolved yet")
  • Non-trivial API usage (e.g., "Array.from creates a shallow copy — we do this because the NodeList returned by querySelectorAll is live, meaning it updates when the DOM changes")
diagram captions must explain:
  • What the diagram shows and why that flow/structure matters
  • Where the interesting part is (not just "this is the architecture")
quiz explanations must explain:
  • Why the correct answer is correct (with specific code evidence)
  • Why each wrong answer is wrong (briefly)
ANTI-PATTERN: Lazy notes. The following are banned:
  • Notes that restate the code: 
    note: "Calls verify() on line 3"
    when the code says 
    const user = await verify(token)
  • Notes that say "see above" or "as mentioned earlier" without re-explaining
  • Concept bodies that say "this module handles X" without explaining how or why
  • Captions that say "Module dependency diagram" without saying what's interesting about the dependencies
GOOD example:
{ line: 5, note: "verify() is async because it makes a network call to the JWT issuer's .well-known/jwks.json endpoint. The await here means the middleware pauses — no downstream handler runs until this resolves. That's fine for auth, but it means every request pays this latency cost, even for public endpoints that don't need auth." }
BAD example:
{ line: 5, note: "Calls verify() to validate the JWT token." }
展示给读者的每一段代码都必须进行详尽解释。这是课程的核心价值——读者来此是为了理解他们自己无法读懂的代码。
code-walk之前的concept单元必须解释：
  • 模块/函数的功能及其存在的原因（在系统中的角色）
  • 所采用的模式或权衡（为什么选择这种方法而非其他）
  • 读者在查看代码前需要了解的任何非显而易见的上下文
code-walk的highlights[].note必须解释：
  • 高亮行的作用（不仅仅是重述代码——要解释背后的原因）
  • 它与周围逻辑的关联（数据流、控制流、副作用）
  • 代码中不可见的隐式行为（例如："这会返回null，因为上游函数尚未解析完成"）
  • 非平凡的API用法（例如："Array.from创建浅拷贝——我们这样做是因为querySelectorAll返回的NodeList是动态的，意味着DOM变化时它会更新"）
图表说明必须解释：
  • 图表展示的内容以及该流程/结构的重要性
  • 有趣的部分在哪里（不仅仅是"这是架构图"）
测验解释必须解释：
  • 正确答案为何正确（附带具体代码证据）
  • 每个错误答案为何错误（简要说明）
反模式：敷衍的注释。以下内容被禁止：
  • 重述代码的注释：当代码为
    const user = await verify(token)
    时，注释写
    note: "第3行调用verify()"
  • 写"见上文"或"如前所述"但不重新解释的注释
  • 仅说明"此模块处理X"但不解释如何处理或为什么处理的concept内容
  • 仅写"模块依赖图"但不说明依赖关系有趣之处的说明
良好示例：
{ line: 5, note: "verify()是异步函数，因为它会向JWT发行方的.well-known/jwks.json端点发起网络请求。这里的await意味着中间件会暂停——直到该请求解析完成，下游处理器才会运行。这对于认证来说没问题，但意味着每个请求都会产生此延迟成本，即使是不需要认证的公共端点也是如此。" }
糟糕示例：
{ line: 5, note: "调用verify()验证JWT令牌。" }

Unit quality guidelines (soft limits)

单元质量指南（软限制）

Prefer depth over brevity. These are upper bounds, not targets — write as much as needed to truly explain the code.
UnitSuggested scope
concept
80–200 words — must explain why, not just what
quiz
question ≤ 2 sentences, 4 options, explanation ≤ 100 words — must reference specific code
takeaway
3–5 sentences — must synthesize, not just repeat
diagram
≤ 8 nodes, caption 20–50 words — must say what's interesting, not just what it shows
code-walk
8–20 lines code + 3–6 annotations — each note must explain the reasoning, not just restate what the code says
code-graph
8–15 lines code + mini SVG (4–6 nodes) — same depth as code-walk for annotations
Rule of thumb: If you can remove an annotation note and the reader loses no understanding, the note wasn't detailed enough — rewrite it, don't remove it.
There is no fixed unit budget. A module page should include as many units as needed to teach its content thoroughly. If a page exceeds ~15 units, consider splitting into sub-modules.
优先考虑深度而非简洁。这些是上限，而非目标——为了真正解释清楚代码，需要写多少就写多少。
单元类型建议范围
concept
80–200字 — 必须解释原因，而非仅仅说明内容
quiz
问题≤2句话，4个选项，解释≤100字 — 必须引用具体代码
takeaway
3–5句话 — 必须进行总结，而非仅仅重复内容
diagram
≤8个节点，说明20–50字 — 必须说明有趣之处，而非仅仅说明展示内容
code-walk
8–20行代码 + 3–6条注释 — 每条注释必须解释背后的逻辑，而非仅仅重述代码内容
code-graph
8–15行代码 + 迷你SVG（4–6个节点） — 注释深度与code-walk相同
经验法则： 如果移除一条注释后读者不会失去任何理解，说明该注释不够详细——请重写，不要删除。
没有固定的单元数量限制。模块页面应包含足够多的单元，以彻底讲解其内容。如果页面超过约15个单元，考虑拆分为子模块。

Pedagogy enforcement (mandatory)

教学规则（必填）

Every generated page MUST satisfy these rules:
  • Every module MUST have a non-empty 
    learningPromise
    .
  • Every module's 
    units[]
    MUST contain ≥ 1 
    quiz
    .
  • Every module's 
    units[]
    MUST end with a 
    takeaway
    .
  • Every perspective's 
    units[]
    MUST start with a 
    concept
    and end with a 
    takeaway
    .
  • There is no hard cap on unit count; quality of explanation determines the length.
每个生成的页面必须满足以下规则：
  • 每个模块必须包含非空的
    learningPromise
    。
  • 每个模块的
    units[]
    必须包含至少1个
    quiz
    。
  • 每个模块的
    units[]
    必须以
    takeaway
    结尾。
  • 每个视角的
    units[]
    必须以
    concept
    开头，以
    takeaway
    结尾。
  • 单元数量没有硬性上限；解释质量决定长度。

Real code only

仅使用真实代码

All 
code
values must be exact, unmodified copies from real source files. This includes:
  • code-walk.code
  • code-graph.code
Prohibited:
  • Inventing code that does not exist in the source
  • Simplifying logic (e.g., removing a ternary, reordering statements)
  • Changing prop names, variable names, or function signatures
  • Adding comments that don't exist in the source
  • Using 
    ...
    ellipsis to hide lines inside a snippet (use 
    // ...
    comment only at the top level to mark elision)
Allowed:
  • Extracting a contiguous slice of a function with 
    // ...
    at top/bottom to show it's truncated
  • Removing import statements and surrounding boilerplate to focus on the logic
  • Normalizing indentation to match the snippet's context
所有
code
值必须是真实源文件的精确、未修改副本。包括：
  • code-walk.code
  • code-graph.code
禁止：
  • 发明源文件中不存在的代码
  • 简化逻辑（例如：移除三元运算符、重新排序语句）
  • 更改属性名、变量名或函数签名
  • 添加源文件中不存在的注释
  • 使用
    ...
    省略号隐藏代码片段内部的行（仅在顶层使用
    // ...
    注释标记省略部分）
允许：
  • 提取函数的连续片段，并在顶部/底部使用
    // ...
    标记为截断内容
  • 移除导入语句和周围的样板代码，聚焦于核心逻辑
  • 调整缩进以匹配代码片段的上下文

Code presentation rules

代码展示规则

Keep teaching snippets tight:
  • Trim leading and trailing blank lines from every 
    code
    value.
  • Collapse repeated interior blank lines to one blank line.
  • Prefer 
    // ...
    or 
    # ...
    elision comments over airy blank rows when skipping irrelevant source.
  • startLine
    is the original source file line used for editor/file actions only; 
    highlights[].line
    remains snippet-local after trimming.
  • Highlight numbers are 1-based and must match the visible line numbers within the extracted snippet after trimming.
  • Verification rule: Before finalizing a page, manually count lines in every 
    code
    value. Ensure every 
    highlights[].line
    points to a line that actually exists in that snippet and contains meaningful code.
  • Common pitfall: When extracting a 15-line function from a 200-line file, the highlights must reference line numbers 1–15 (the snippet), NOT the original file's line numbers 186–200.
  • Do not highlight blank separator lines; move highlights to the nearest meaningful source line.
  • Annotation-note alignment: The note text must describe what happens on the highlighted line(s). If the note says "mergeMessage dedupes by id" but the highlighted line is 
    ...state,
    , the highlight is on the wrong line.
保持教学代码片段简洁：
  • 移除每个
    code
    值开头和结尾的空白行。
  • 将内部重复的空白行合并为一行。
  • 跳过无关代码时，优先使用
    // ...
    或
    # ...
    省略注释，而非空行。
  • startLine
    仅用于编辑器/文件操作的原始源文件行号；修剪后，
    highlights[].line
    为代码片段内的行号。
  • 高亮行号是基于1的，必须与修剪后提取的代码片段中的可见行号匹配。
  • 验证规则： 在最终确定页面之前，手动统计每个
    code
    值的行数。确保每个
    highlights[].line
    指向该片段中实际存在且包含有意义代码的行。
  • 常见陷阱： 从200行文件中提取15行函数时，高亮行号必须引用1–15（代码片段的行号），而非原始文件的186–200行。
  • 不要高亮空白分隔行；将高亮移动到最近的有意义代码行。
  • 注释与高亮对齐： 注释文本必须描述高亮行的行为。如果注释写"mergeMessage按id去重"但高亮行是
    ...state,
    ，则高亮行选择错误。

Code file action controls

代码文件操作控件

When a 
code-walk
or 
code-graph
unit has a real source file path, render file actions in the 
.codewalk-head
next to the file label.
Use an absolute file path in 
data-copy-path
when the source repository path is known. Append 
:{startLine}
when the unit provides 
startLine
; otherwise append 
:1
.
Required HTML shape:
html
<div class="codewalk-head">
  <span class="codewalk-file">{FILE}</span>
  <span class="file-actions">
    <span class="editor-menu" data-editor-menu data-editor="cursor">
      <button class="file-action-select editor-menu-trigger" type="button" aria-haspopup="listbox" aria-expanded="false" data-editor-trigger>
        <span data-editor-current>Cursor</span>
        <span class="gg-chevron-down" aria-hidden="true"></span>
      </button>
      <span class="editor-menu-list" role="listbox" hidden data-editor-list>
        <button class="editor-menu-item" type="button" role="option" aria-selected="true" data-editor-option="cursor">Cursor</button>
        <button class="editor-menu-item" type="button" role="option" aria-selected="false" data-editor-option="vscode">VS Code</button>
      </span>
    </span>
    <button class="file-action" type="button" data-copy-path="{ABSOLUTE_FILE_PATH}:{START_LINE}">Copy path</button>
  </span>
</div>
The selected editor option opens immediately. Selecting the already-active option still opens the file, because the menu uses buttons instead of a native 
<select>
.
当
code-walk
或
code-graph
单元包含真实源文件路径时，在
.codewalk-head
中文件标签旁边渲染文件操作按钮。
当已知源仓库路径时，在
data-copy-path
中使用绝对文件路径。如果单元提供
startLine
，则追加
:startLine
；否则追加
:1
。
必填HTML结构：
html
<div class="codewalk-head">
  <span class="codewalk-file">{FILE}</span>
  <span class="file-actions">
    <span class="editor-menu" data-editor-menu data-editor="cursor">
      <button class="file-action-select editor-menu-trigger" type="button" aria-haspopup="listbox" aria-expanded="false" data-editor-trigger>
        <span data-editor-current>Cursor</span>
        <span class="gg-chevron-down" aria-hidden="true"></span>
      </button>
      <span class="editor-menu-list" role="listbox" hidden data-editor-list>
        <button class="editor-menu-item" type="button" role="option" aria-selected="true" data-editor-option="cursor">Cursor</button>
        <button class="editor-menu-item" type="button" role="option" aria-selected="false" data-editor-option="vscode">VS Code</button>
      </span>
    </span>
    <button class="file-action" type="button" data-copy-path="{ABSOLUTE_FILE_PATH}:{START_LINE}">Copy path</button>
  </span>
</div>
选中的编辑器选项会立即打开。选择已激活的选项仍会打开文件，因为菜单使用按钮而非原生
<select>
。

Unit examples

单元示例

Before drafting unit data, read 
references/units-examples.md
for concrete object shapes, unit-specific options, defaults, and interaction bindings.
Keep the unit-level traps in mind: callout concepts use 
style: "callout"
, quizzes need exactly one correct answer, code-walk line numbers are snippet-local, and code-graph bindings must match SVG 
data-node-id
values.
在编写单元数据之前，请阅读
references/units-examples.md
获取具体对象结构、单元特定选项、默认值和交互绑定。
牢记单元级注意事项：提示性concept使用
style: "callout"
，测验需要恰好一个正确答案，code-walk行号是代码片段内的行号，code-graph绑定必须匹配SVG的
data-node-id
值。

Phase 4: Build Mermaid Diagrams

阶段4：构建Mermaid图表

Before writing diagrams, read 
references/svg-patterns.md
.
Use Mermaid for 
diagram
units and raw inline SVG only for 
code-graph
mini-graphs that need 
data-node-id
click-sync. Keep node IDs consistent across pages, use descriptive labels, and do not inline theme overrides; the Raycast dark theme is configured in 
mermaid-bridge.js
.
在编写图表之前，请阅读
references/svg-patterns.md
。
diagram
单元使用Mermaid，
code-graph
迷你图仅使用原始内联SVG以实现
data-node-id
点击同步。在所有页面中保持节点ID一致，使用描述性标签，不要内联主题覆盖；Raycast深色主题在
mermaid-bridge.js
中配置。

Phase 5: Generate Page List

阶段5：生成页面列表

FileSkeletonCondition
index.html
skeleton-index.html
Always
architecture.html
skeleton-essay.html
Always
build-up.html
skeleton-essay.html
Always
<perspective>.html
skeleton-essay.html
One per non-default perspective
module-<name>.html
skeleton-essay.html
One per discovered module
All generated course files go in 
docs/codemermaid/
. Filenames are kebab-case except the fixed 
index.html
.
Before generating HTML pages, copy shared assets to the output directory:
  1. Copy 
    assets/style.css
    → 
    docs/codemermaid/style.css
  2. Copy 
    assets/runtime.js
    → 
    docs/codemermaid/runtime.js
  3. Copy 
    assets/beautiful-mermaid.bundle.js
    → 
    docs/codemermaid/beautiful-mermaid.bundle.js
  4. Copy 
    assets/mermaid-bridge.js
    → 
    docs/codemermaid/mermaid-bridge.js
These are linked by every generated HTML page.
文件骨架模板生成条件
index.html
skeleton-index.html
始终生成
architecture.html
skeleton-essay.html
始终生成
build-up.html
skeleton-essay.html
始终生成
<perspective>.html
skeleton-essay.html
每个非默认视角生成一个
module-<name>.html
skeleton-essay.html
每个发现的模块生成一个
所有生成的课程文件都放在
docs/codemermaid/
目录中。文件名使用短横线分隔式（kebab-case），固定文件名
index.html
除外。
在生成HTML页面之前，将共享资源复制到输出目录：
  1. 复制
    assets/style.css
    → 
    docs/codemermaid/style.css
  2. 复制
    assets/runtime.js
    → 
    docs/codemermaid/runtime.js
  3. 复制
    assets/beautiful-mermaid.bundle.js
    → 
    docs/codemermaid/beautiful-mermaid.bundle.js
  4. 复制
    assets/mermaid-bridge.js
    → 
    docs/codemermaid/mermaid-bridge.js
这些资源会被每个生成的HTML页面链接。

Phase 6: Write HTML Pages

阶段6：编写HTML页面

For each page in the file list (Phase 5):
对于阶段5中的每个页面：

Assembly process

组装流程

  1. Read the skeleton template: 
    assets/skeleton-essay.html
    or 
    assets/skeleton-index.html
  2. Generate content HTML for each 
    <!-- SLOT:... -->
    marker (see below)
  3. Replace all slots with their content HTML
  4. Pre-flight verification (mandatory — do not skip):
    • Every 
      highlights[].line
      points to an existing, non-blank line in its snippet
    • Every code snippet is an exact copy from source (no invented lines, no reordered statements)
    • No 
      href="#"
      placeholders — all back/next links point to real files
    • No 
      **bold**
      markdown — use 
      <strong></strong>
      instead
    • Inside 
      <pre class="code-block">
      , 
      .line
      spans are adjacent with NO whitespace between them
    • Quiz has exactly 1 option with 
      data-correct="true"
    • No double HTML entity escaping — scan for 
      &amp;#
      or 
      &amp;lt;
      or 
      &amp;gt;
      patterns and fix them
    • Mermaid syntax is valid — no unclosed brackets, no missing quotes in edge labels
    • index.html
      links to 
      build-up.html
      in the Perspectives section
    • build-up.html
      exists, starts with a 
      concept
      , contains at least one 
      quiz
      , and ends with a 
      takeaway
    • Build-Up copy describes a learning order, not an unverified implementation chronology
    • Every Build-Up step explains a capability change; it is not only a module inventory
    • Every 
      whoa
      unit has 
      angle
      , 
      title
      , and 
      body
    • Every 
      whoa.angle
      is 
      code
      , 
      product
      , 
      ux
      , or 
      architecture
    • whoa
      units use one visual treatment; no angle-specific color classes
    • Every rendered file action with 
      data-copy-path
      points to a real source file path and includes a line number
  5. Dispatch a subagent reviewer to validate the generated HTML
  6. Write the completed HTML to 
    docs/codemermaid/<filename>.html
  1. 读取骨架模板：
    assets/skeleton-essay.html
    或
    assets/skeleton-index.html
  2. 为每个
    <!-- SLOT:... -->
    标记生成内容HTML    （见下文）
  3. 将所有插槽替换为对应的内容HTML
  4. 预飞验证（必填 — 切勿跳过）：
    • 每个
      highlights[].line
      指向其代码片段中存在的非空白行
    • 每个代码片段都是源文件的精确副本（无虚构行，无重新排序的语句）
    • 无
      href="#"
      占位符 — 所有上一页/下一页链接都指向真实文件
    • 无
      **bold**
      格式的markdown — 使用
      <strong></strong>
      替代
    • 在
      <pre class="code-block">
      内，
      .line
      元素必须相邻，之间无空白
    • 测验恰好有一个选项带有
      data-correct="true"
    • 无双重HTML实体转义 — 扫描
      &amp;#
      、
      &amp;lt;
      或
      &amp;gt;
      模式并修复
    • Mermaid语法有效 — 无未闭合的括号，无缺失引号的边标签
    • index.html
      在Perspectives部分链接到
      build-up.html
    • build-up.html
      存在，以
      concept
      开头，包含至少一个
      quiz
      ，并以
      takeaway
      结尾
    • Build-Up内容描述学习顺序，而非未经验证的实现时间线
    • 每个Build-Up步骤解释功能变化；不仅仅是模块清单
    • 每个
      whoa
      单元包含
      angle
      、
      title
      和
      body
    • 每个
      whoa.angle
      取值为
      code
      、
      product
      、
      ux
      或
      architecture
    • whoa
      单元使用一种视觉样式；无特定角度的颜色类
    • 每个带有
      data-copy-path
      的渲染文件操作指向真实源文件路径并包含行号
  5. 分配子代理审核员验证生成的HTML
  6. 写入完成的HTML到
    docs/codemermaid/<filename>.html

Essay page slots

文章页面插槽

<!-- SLOT:HERO -->
:
html
<section class="hero">
  <div class="eyebrow">{PROJECT_NAME}</div>
  <h1>{PAGE_TITLE}</h1>
  <p class="learning-promise">{LEARNING_PROMISE}</p>
  <ul class="prereqs">{PREREQ_CHIPS}</ul>
</section>
<!-- SLOT:TOC -->
:
html
<nav class="toc">
  <div class="toc-label">On this page</div>
  <ol class="toc-list">
    <li><a class="toc-item" href="#unit-0"><span class="toc-num">1</span>{TITLE}<span class="toc-kind">{KIND}</span></a></li>
    <!-- one per unit -->
  </ol>
</nav>
<!-- SLOT:UNITS -->
: One 
<section>
per unit:
html
<section class="unit unit-{KIND}" id="unit-{INDEX}">
  <!-- unit content HTML -->
</section>
For 
whoa
units, render:
html
<section class="unit unit-whoa" id="unit-{INDEX}" data-angle="{ANGLE}">
  <div class="whoa-label">whoa · {ANGLE}</div>
  <h2>{TITLE}</h2>
  <p>{BODY}</p>
  <div class="whoa-evidence">
    <span>{EVIDENCE_ITEM}</span>
  </div>
</section>
Render 
.whoa-evidence
only when evidence exists. Flatten evidence in this order: files, modules, interactions, constraints. Keep evidence text short enough to fit in a pill; use file basenames or repo-relative paths rather than long absolute paths inside evidence chips. For evidence chips, repeat one 
<span>{EVIDENCE_ITEM}</span>
per flattened evidence item.
<!-- SLOT:FOOTER -->
:
html
<footer class="page-footer">
  <a class="next-link" href="{NEXT_LINK}">{NEXT_LABEL} →</a>
  <p class="recap">{LEARNING_PROMISE_RECAP}</p>
</footer>
<!-- SLOT:HERO -->
:
html
<section class="hero">
  <div class="eyebrow">{PROJECT_NAME}</div>
  <h1>{PAGE_TITLE}</h1>
  <p class="learning-promise">{LEARNING_PROMISE}</p>
  <ul class="prereqs">{PREREQ_CHIPS}</ul>
</section>
<!-- SLOT:TOC -->
:
html
<nav class="toc">
  <div class="toc-label">本页内容</div>
  <ol class="toc-list">
    <li><a class="toc-item" href="#unit-0"><span class="toc-num">1</span>{TITLE}<span class="toc-kind">{KIND}</span></a></li>
    <!-- 每个单元对应一个 -->
  </ol>
</nav>
<!-- SLOT:UNITS -->
: 每个单元对应一个
<section>
：
html
<section class="unit unit-{KIND}" id="unit-{INDEX}">
  <!-- 单元内容HTML -->
</section>
对于
whoa
单元，渲染：
html
<section class="unit unit-whoa" id="unit-{INDEX}" data-angle="{ANGLE}">
  <div class="whoa-label">whoa · {ANGLE}</div>
  <h2>{TITLE}</h2>
  <p>{BODY}</p>
  <div class="whoa-evidence">
    <span>{EVIDENCE_ITEM}</span>
  </div>
</section>
仅当存在证据时才渲染
.whoa-evidence
。按以下顺序展平证据：文件、模块、交互、约束。保持证据文本足够短以适应标签；在证据标签中使用文件名或仓库相对路径，而非长绝对路径。对于证据标签，每个展平的证据项对应一个
<span>{EVIDENCE_ITEM}</span>
。
<!-- SLOT:FOOTER -->
:
html
<footer class="page-footer">
  <a class="next-link" href="{NEXT_LINK}">{NEXT_LABEL} →</a>
  <p class="recap">{LEARNING_PROMISE_RECAP}</p>
</footer>

Unit HTML templates

单元HTML模板

concept (normal):
html
<span class="unit-kind">concept</span>
<h2>{TITLE}</h2>
<p>{BODY}</p>
concept (callout/surprise style):
html
<div class="unit-surprise">
<span class="unit-kind">concept</span>
<h2>{TITLE}</h2>
<p>{BODY}</p>
</div>
quiz:
html
<div class="quiz">
  <div class="quiz-question">{QUESTION}</div>
  <div class="quiz-options">
    <div class="quiz-option" data-correct="true"><span class="quiz-option-letter">A</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">B</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">C</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">D</span><span>{TEXT}</span></div>
  </div>
  <div class="quiz-explanation"><strong>Correct: {LETTER}</strong> — {EXPLANATION}</div>
</div>
takeaway:
html
<div class="unit-takeaway">
<span class="unit-kind">takeaway</span>
<p>{BODY}</p>
</div>
diagram:
html
<figure class="figure">
  {ZOOMABLE ? '<button class="zoom-btn" data-zoom-trigger>Zoom</button>' : ''}
  <div class="figure-diagram"><pre class="mermaid">{MERMAID_CODE}</pre></div>
  <figcaption>{CAPTION}</figcaption>
</figure>
code-walk (split layout):
html
<div class="codewalk-split">
  <!-- Use the Code file action controls header from above when a real source path exists. Otherwise render a simple header with <span class="codewalk-file">{FILE}</span>. -->
  <div class="codewalk-head"><span class="codewalk-file">{FILE}</span><span>{LANG}</span></div>
  <div class="codewalk-split-body">
    <pre class="code-block">{LINES}</pre>
    <div class="codewalk-annotations">{ANNOTATIONS}</div>
  </div>
</div>
Each line: 
<span class="line{? line-hl}" data-line="{N}"><span class="ln">{N}</span><span class="code-text">{CODE}</span></span>
CRITICAL: 
.line
spans inside 
<pre>
MUST be adjacent with NO whitespace (newlines, spaces) between them.
Each annotation: 
<div class="codewalk-annotation" data-note-lines="{LINES}"><span class="annotation-line">L{N}</span><p>{NOTE}</p></div>
code-graph:
html
<div class="codegraph-split">
  <!-- Use the Code file action controls header from above when a real source path exists. Otherwise render a simple header with <span class="codewalk-file">{FILE}</span>. -->
  <div class="codewalk-head"><span class="codewalk-file">{FILE}</span><span>{LANG}</span></div>
  <div class="codegraph-split-body">
    <pre class="code-block">{LINES with data-graph-node}</pre>
    <div class="codegraph-graph">{SVG}</div>
  </div>
</div>
Code lines with graph binding: 
<span class="line{? line-hl}" data-line="{N}" data-graph-node="{NODE_ID}"><span class="ln">{N}</span><span class="code-text">{CODE}</span></span>
concept（普通样式）：
html
<span class="unit-kind">concept</span>
<h2>{TITLE}</h2>
<p>{BODY}</p>
concept（提示/惊喜样式）：
html
<div class="unit-surprise">
<span class="unit-kind">concept</span>
<h2>{TITLE}</h2>
<p>{BODY}</p>
</div>
quiz：
html
<div class="quiz">
  <div class="quiz-question">{QUESTION}</div>
  <div class="quiz-options">
    <div class="quiz-option" data-correct="true"><span class="quiz-option-letter">A</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">B</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">C</span><span>{TEXT}</span></div>
    <div class="quiz-option" data-correct="false"><span class="quiz-option-letter">D</span><span>{TEXT}</span></div>
  </div>
  <div class="quiz-explanation"><strong>正确答案：{LETTER}</strong> — {EXPLANATION}</div>
</div>
takeaway：
html
<div class="unit-takeaway">
<span class="unit-kind">takeaway</span>
<p>{BODY}</p>
</div>
diagram：
html
<figure class="figure">
  {ZOOMABLE ? '<button class="zoom-btn" data-zoom-trigger>放大</button>' : ''}
  <div class="figure-diagram"><pre class="mermaid">{MERMAID_CODE}</pre></div>
  <figcaption>{CAPTION}</figcaption>
</figure>
code-walk（拆分布局）：
html
<div class="codewalk-split">
  <!-- 当存在真实源路径时，使用上述代码文件操作控件头部。否则渲染简单头部：<span class="codewalk-file">{FILE}</span>。 -->
  <div class="codewalk-head"><span class="codewalk-file">{FILE}</span><span>{LANG}</span></div>
  <div class="codewalk-split-body">
    <pre class="code-block">{LINES}</pre>
    <div class="codewalk-annotations">{ANNOTATIONS}</div>
  </div>
</div>
每行代码：
<span class="line{? line-hl}" data-line="{N}"><span class="ln">{N}</span><span class="code-text">{CODE}</span></span>
关键注意事项： 
<pre>
内的
.line
元素必须相邻，之间无空白（换行符、空格）。
每个注释：
<div class="codewalk-annotation" data-note-lines="{LINES}"><span class="annotation-line">第{N}行</span><p>{NOTE}</p></div>
code-graph：
html
<div class="codegraph-split">
  <!-- 当存在真实源路径时，使用上述代码文件操作控件头部。否则渲染简单头部：<span class="codewalk-file">{FILE}</span>。 -->
  <div class="codewalk-head"><span class="codewalk-file">{FILE}</span><span>{LANG}</span></div>
  <div class="codegraph-split-body">
    <pre class="code-block">{LINES with data-graph-node}</pre>
    <div class="codegraph-graph">{SVG}</div>
  </div>
</div>
带有图绑定的代码行：
<span class="line{? line-hl}" data-line="{N}" data-graph-node="{NODE_ID}"><span class="ln">{N}</span><span class="code-text">{CODE}</span></span>

Index page slots

索引页面插槽

<!-- SLOT:INDEX_HEADER -->
:
html
<div class="project-header">
  <h1>{PROJECT_NAME}</h1>
  <p>{PROJECT_DESCRIPTION}</p>
  <div class="badges">
    <span class="badge">{LANGUAGE}</span>
    {FRAMEWORK_BADGE}
  </div>
</div>
<!-- SLOT:ARCHITECTURE_DIAGRAM -->
:
html
<div class="section">
  <div class="section-title">Architecture</div>
  <figure class="figure">
    <div class="figure-diagram"><pre class="mermaid">{MERMAID_CODE}</pre></div>
    <figcaption>{CAPTION}</figcaption>
  </figure>
</div>
<!-- SLOT:PERSPECTIVE_CARDS -->
:
html
<div class="section">
  <div class="section-title">Perspectives</div>
  <div class="card-grid">
    <a class="card" href="{PAGE}"><span class="card-type">perspective</span><h3>{TITLE}</h3><p>{DESCRIPTION}</p><div class="card-meta">{N} units</div></a>
  </div>
</div>
Perspective cards should list default perspectives first: Architecture Overview, then Build-Up Walkthrough, followed by user-requested and auto-inferred perspectives. The Build-Up card must link to 
build-up.html
and describe the gradual route from smallest useful capability to complete system.
<!-- SLOT:MODULE_CARDS -->
:
html
<div class="section">
  <div class="section-title">Module Deep Dives</div>
  <div class="card-grid">
    <a class="card" href="module-{NAME}.html"><span class="card-type">module</span><h3>{TITLE}</h3><p>{DESCRIPTION}</p><div class="card-meta">{N} units</div></a>
  </div>
</div>
<!-- SLOT:INDEX_HEADER -->
:
html
<div class="project-header">
  <h1>{PROJECT_NAME}</h1>
  <p>{PROJECT_DESCRIPTION}</p>
  <div class="badges">
    <span class="badge">{LANGUAGE}</span>
    {FRAMEWORK_BADGE}
  </div>
</div>
<!-- SLOT:ARCHITECTURE_DIAGRAM -->
:
html
<div class="section">
  <div class="section-title">架构</div>
  <figure class="figure">
    <div class="figure-diagram"><pre class="mermaid">{MERMAID_CODE}</pre></div>
    <figcaption>{CAPTION}</figcaption>
  </figure>
</div>
<!-- SLOT:PERSPECTIVE_CARDS -->
:
html
<div class="section">
  <div class="section-title">视角</div>
  <div class="card-grid">
    <a class="card" href="{PAGE}"><span class="card-type">perspective</span><h3>{TITLE}</h3><p>{DESCRIPTION}</p><div class="card-meta">{N}个单元</div></a>
  </div>
</div>
视角卡片应先列出默认视角：架构概览，然后是Build-Up导览，接着是用户请求和自动推断的视角。Build-Up卡片必须链接到
build-up.html
，并描述从最小可用功能到完整系统的渐进式学习路径。
<!-- SLOT:MODULE_CARDS -->
:
html
<div class="section">
  <div class="section-title">模块深度解析</div>
  <div class="card-grid">
    <a class="card" href="module-{NAME}.html"><span class="card-type">module</span><h3>{TITLE}</h3><p>{DESCRIPTION}</p><div class="card-meta">{N}个单元</div></a>
  </div>
</div>

Design System

设计系统

Use the bundled Raycast-inspired dark theme in 
assets/style.css
. For visual rationale and token guidance, read 
DESIGN.md
and 
references/design-system.md
.
使用
assets/style.css
中捆绑的Raycast风格深色主题。如需了解视觉原理和令牌指南，请阅读
DESIGN.md
和
references/design-system.md
。

Important Rules

重要规则

  1. Read Build-Up reference — before creating 
    build-up.html
    or a module-level Build-Up section, read 
    references/build-up.md
    .
  2. Default perspectives — always generate 
    architecture.html
    and 
    build-up.html
    .
  3. Real code only — never invent, simplify, or modify code snippets.
  4. Cover every module — every module discovered in Phase 1 must appear in at least one perspective page AND have its own 
    module-<name>.html
    .
  5. Linked shared assets — copy 
    style.css
    , 
    runtime.js
    , 
    beautiful-mermaid.bundle.js
    , and 
    mermaid-bridge.js
    to the output directory. Each HTML links them via 
    <link>
    and 
    <script src>
    .
  6. Vanilla JS only — no React, no build tools.
  7. beautiful-mermaid via browser bundle — all 
    diagram
    units use Mermaid syntax rendered by the beautiful-mermaid browser bundle + 
    mermaid-bridge.js
    . 
    code-graph
    mini-graphs use raw SVG for 
    data-node-id
    click-sync.
  8. Build-Up is learning order — describe capability increments in the order that teaches the system, not unverified git or implementation history.
  9. Module-level Build-Up is optional — include it only when the module has a natural internal progression. Do not force it into every module page.
  10. Pre whitespace rule — inside 
    <pre class="code-block">
    , 
    .line
    spans must be adjacent with NO whitespace between them.
  11. Quiz correctness — every quiz must have exactly 1 option with 
    data-correct="true"
    .
  12. Consistent node IDs — same module = same node ID across all pages.
  13. User perspective overrides — user-specified perspectives are mandatory; auto-inferred are supplementary.
  14. Annotation alignment — the runtime's 
    alignAnnotations()
    handles vertical positioning. CSS 
    gap
    on 
    .codewalk-annotations
    must be 
    0
    .
  1. 阅读Build-Up参考文档 — 在创建
    build-up.html
    或模块级Build-Up部分之前，请阅读
    references/build-up.md
    。
  2. 默认视角 — 始终生成
    architecture.html
    和
    build-up.html
    。
  3. 仅使用真实代码 — 切勿发明、简化或修改代码片段。
  4. 覆盖所有模块 — 阶段1中发现的每个模块必须至少出现在一个视角页面中，并且拥有自己的
    module-<name>.html
    页面。
  5. 链接共享资源 — 将
    style.css
    、
    runtime.js
    、
    beautiful-mermaid.bundle.js
    和
    mermaid-bridge.js
    复制到输出目录。每个HTML页面通过
    <link>
    和
    <script src>
    链接它们。
  6. 仅使用原生JS — 不使用React，不使用构建工具。
  7. 通过浏览器包使用beautiful-mermaid — 所有
    diagram
    单元使用Mermaid语法，由beautiful-mermaid浏览器包 + 
    mermaid-bridge.js
    渲染。
    code-graph
    迷你图使用原始SVG实现
    data-node-id
    点击同步。
  8. Build-Up是学习顺序 — 按便于读者学习系统的顺序描述功能增量，而非未经验证的git或实现历史。
  9. 模块级Build-Up是可选的 — 仅当模块具有自然的内部演进逻辑时才包含。不要强行添加到每个模块页面。
  10. 预空白规则 — 在
    <pre class="code-block">
    内，
    .line
    元素必须相邻，之间无空白。
  11. 测验正确性 — 每个测验必须恰好有一个选项带有
    data-correct="true"
    。
  12. 一致的节点ID — 同一模块在所有页面中使用相同的节点ID。
  13. 用户视角优先 — 用户指定的视角是必填项；自动推断的视角是补充项。
  14. 注释对齐 — 运行时的
    alignAnnotations()
    处理垂直定位。
    .codewalk-annotations
    的CSS 
    gap
    必须为
    0
    。

Common Mistakes

常见错误

MistakeFix
Missing 
build-up.html
Always generate the required Build-Up Walkthrough perspective and link it from 
index.html
.
Build-Up reads like git historyReframe it as reader learning order unless git history was explicitly inspected and cited.
Build-Up is just a module listRewrite each step around a capability change and name the code that makes the change possible.
Forced module-level Build-UpRemove it when a normal code-walk teaches the module more clearly.
Blank lines between code lines
.line
spans inside 
<pre>
must be adjacent — no newlines or spaces between them.
Highlight points to wrong lineCount lines within the extracted snippet, not the original source file.
Code snippet has invented linesPaste the snippet back into a temp file and run the type checker.
href="#"
in links		Replace with actual relative paths. Never leave placeholder links.
Side-by-side code looks crampedEnsure 
grid-template-columns: minmax(0, 1fr) 300px
is applied.
Quiz has no correct answerExactly 1 option must have 
data-correct="true"
.
Double HTML entity escapingScan output for 
&amp;#
, 
&amp;lt;
, 
&amp;gt;
— these are wrong. The correct forms are 
&#39;
, 
&lt;
, 
&gt;
.
Mermaid edge label missing quotesUse pipe syntax: `A -->
Annotations not aligned with codeConfirm CSS 
.codewalk-annotations { gap: 0 }
and runtime.js 
alignAnnotations()
runs on DOMContentLoaded.
beautiful-mermaid not renderingEnsure 
beautiful-mermaid.bundle.js
and 
mermaid-bridge.js
are copied to output dir and linked in correct order (bundle in 
<head>
, bridge before 
runtime.js
).
错误修复方案
缺失
build-up.html
始终生成必填的Build-Up导览视角，并从
index.html
链接到它。
Build-Up内容读起来像git历史将其重构为读者学习顺序，除非明确检查并引用了git历史。
Build-Up只是模块列表围绕功能重写每个步骤，并说明实现该功能的代码。
强行添加模块级Build-Up当普通code-walk能更清晰地讲解模块时，移除该部分。
代码行之间存在空白行
<pre>
内的
.line
元素必须相邻——它们之间不能有换行符或空格。
高亮指向错误行统计提取的代码片段内的行号，而非原始源文件的行号。
代码片段包含虚构行将片段粘贴到临时文件并运行类型检查器。
链接中存在
href="#"
替换为实际相对路径。切勿保留占位符链接。
并排代码看起来拥挤确保应用了
grid-template-columns: minmax(0, 1fr) 300px
。
测验没有正确答案必须恰好有一个选项带有
data-correct="true"
。
双重HTML实体转义扫描输出中的
&amp;#
、
&amp;lt;
、
&amp;gt;
——这些是错误的。正确形式为
&#39;
、
&lt;
、
&gt;
。
Mermaid边标签缺失引号使用管道语法：`A -->
注释与代码未对齐确认CSS 
.codewalk-annotations { gap: 0 }
，且runtime.js的
alignAnnotations()
在DOMContentLoaded时运行。
beautiful-mermaid未渲染确保
beautiful-mermaid.bundle.js
和
mermaid-bridge.js
已复制到输出目录，并按正确顺序链接（bundle放在
<head>
中，bridge放在
runtime.js
之前）。

File Organization

文件组织

skills/codemermaid/
  SKILL.md
  DESIGN.md
  references/
    design-system.md
    svg-patterns.md
    subagent-generation.md
    units-examples.md
    voice-examples.md
  assets/
    skeleton-essay.html
    skeleton-index.html
    style.css
    runtime.js
    beautiful-mermaid.bundle.js
    mermaid-bridge.js
skills/codemermaid/
  SKILL.md
  DESIGN.md
  references/
    design-system.md
    svg-patterns.md
    subagent-generation.md
    units-examples.md
    voice-examples.md
  assets/
    skeleton-essay.html
    skeleton-index.html
    style.css
    runtime.js
    beautiful-mermaid.bundle.js
    mermaid-bridge.js

Relationship to Other Skills

与其他技能的关系

  • presentation — Slidev-based slides (slide deck). Use 
    codemermaid
    for interactive exploration, 
    presentation
    for linear slide-based talks.
  • codebase-to-course — single-page HTML course. Use 
    codemermaid
    for multi-page interactive sites, 
    codebase-to-course
    for single-page courses.
  • presentation — 基于Slidev的幻灯片（演示文稿）。使用
    codemermaid
    进行交互式探索，使用
    presentation
    进行线性幻灯片演示。
  • codebase-to-course — 单页HTML课程。使用
    codemermaid
    生成多页交互式站点，使用
    codebase-to-course
    生成单页课程。