walkthrough

代码库导览生成器

生成带有可点击 Mermaid 图表的交互式 HTML 文件，帮助新开发者快速建立某个功能或系统的心智模型。目标是帮助开发者快速上手——提供一份概念及其关联的粗略地图，而不是代码参考。每份导览都应能在 2 分钟内读完。

重要：触发此技能时，必须生成一个 walkthrough-*.html 文件。绝不能只回复文本——始终要生成交互式 HTML 输出。

始终使用深色模式。 每份导览都必须使用纯黑背景（#000000）、白色文字和紫色点缀。绝不要生成浅色模式导览。<html> 标签必须包含 style="color-scheme: dark"。

工作流

步骤 1：了解范围

明确用户想要了解什么：

• 某个特定功能流程（例如：“画布绘图是如何工作的”）
• 某个数据流（例如：“状态如何从组合式函数流向组件”）
• 架构概览（例如：“功能是如何组织的”）
• 请求生命周期（例如：“用户点击绘制后会发生什么”）
• 数据库架构（例如：“说明这些表及其关系”）
• 数据模型（例如：“用户数据是如何组织的”）

如果提示词是没有主题的 $walkthrough，则生成整个项目的概览导览——展示主要模块、模块之间的关联以及整体架构。

将导览设计成面向新手的心智模型。思考：“5-12 个关键概念是什么？它们如何关联？”

如果请求含糊不清（且不是单独的 $walkthrough），请提出一个澄清问题。否则继续。

步骤 2：使用并行子 Agent 探索代码库

生成内容前，务必先阅读实际源文件。 绝不要编造代码路径。

使用 Task 工具委派子 Agent 进行探索。 这样可以让主上下文专注于生成 HTML，并通过并行处理加快调研阶段。

2a. 确定探索范围

自己快速使用 Glob/Grep（最多调用 1-2 次），确定相关目录和文件组。然后将探索拆分为 2-4 个相互独立的调研任务。

2b. 并行启动 Explore 子 Agent

在一条消息中使用 Task 和 subagent_type: "Explore" 启动多个 Agent（并行）。每个 Agent 应调查一个领域，并汇报每个部分的用途和关联，而不是大段粘贴代码。

为每个子 Agent 提供聚焦的提示，要求其按结构化格式返回报告，内容包括：

• 该部分的作用（用途）以及它存在的原因（在系统中的角色）
• 它与其他部分的关联方式（导入、调用、数据流）
• 建议的节点 ID（camelCase）和通俗易懂的标签（例如“绘图交互”，而不是“useDrawingInteraction()”）
• 主要文件路径
• 一段代码片段（必需，1-5 行）

要求每个子 Agent 按以下格式将报告整理为节点列表：

NODE: drawingInteraction
  label: Drawing Interaction
  file: app/features/tools/useDrawingInteraction.ts
  purpose: Converts pointer events into shape data. This is the bridge between raw mouse input and the element model.
  connects_to: canvasRenderer (feeds shape data), toolState (reads active tool)
  key_snippet:
    const element = createElement(tool, startPoint, currentPoint)
    lang: typescript

每个节点都必须包含代码片段。 选取最有用的一段——关键函数调用、类型定义、配置行或核心算法（1-5 行）。这能为开发者提供具体的依据，与概念说明相辅相成。

将“绘图工具”导览拆分给子 Agent 的示例：

Subagent 1: "Explore user input handling"
→ Read tool selection, pointer event handling
→ Report: purpose of each piece, how they connect

Subagent 2: "Explore rendering pipeline"
→ Read canvas rendering, scene management
→ Report: what renders elements, how it gets triggered

Subagent 3: "Explore element model and state"
→ Read element types, state management
→ Report: how elements are stored, what shape they have

不要自己阅读文件——交由子 Agent 阅读。你的工作是协调探索，并将其结果综合整理为 HTML。

2c. 综合子 Agent 的结果（不再读取文件）

所有子 Agent 返回结果后，所需信息就已齐全。请勿再读取任何文件或启动更多子 Agent。 直接进入步骤 3-4。

将子 Agent 的发现整理为：

1. 节点列表 — ID、通俗易懂的标签、主要文件、1-2 句描述、代码片段 + 语言
2. 边列表 — 节点之间的连接，以及简单的动词标签（“触发”“传入”“生成”）
3. 子图分组 — 2-4 个分组，使用通俗易懂的标签（“用户输入”“处理”“输出”）

节点总数保持在 5-12 个（严格要求至少 5 个——绝不能少于 5 个）。 每个节点代表一个概念，而不是一个函数。将相关函数归为一个节点。如果节点超过 12 个，请合并相关节点。如果子 Agent 的结果不足 5 个节点，请扩展相关概念，或将宽泛的节点拆分为更细的节点，直到至少达到 5 个。

如果子 Agent 的报告缺少某节点的信息，请移除该节点，不要自行读取文件——但仍须满足至少 5 个节点的要求。

步骤 3：选择图表类型

根据主题选择 Mermaid 图表类型：

主题	图表类型	Mermaid 语法
功能流程、请求生命周期、架构	流程图	graph TD / graph LR
数据库架构、表关系、数据模型	ER 图	erDiagram
混合（API 流程 + DB 架构）	两者 — 并排或上下排列绘制两个图表	流程图 + ER

图表尺寸：节点保持在 5-12 个，并分为 2-4 个子图。这样图表一目了然，易于浏览。

流程图（graph TD / graph LR）

方向：层级流程使用 graph TD（自上而下），顺序流水线使用 graph LR（从左到右）。

节点类型（按类别设置样式）：

类型	样式	用途
component	Purple-500	Vue 组件、页面
composable	Purple-600	Composable、钩子
utility	Purple-700	工具、辅助项、纯函数
external	Gray-600	库、浏览器 API、外部服务
event	Purple-200	事件、用户操作、触发器
data	Purple-600	存储、状态、数据结构

子图：将相关节点归为 2-4 个子图，并使用通俗易懂的心智模型标签（例如，“用户输入”“核心逻辑”“视觉输出”），而不是技术层级名称。

节点 ID：使用描述性的 camelCase ID，与详细数据相对应（例如，drawingInteraction、canvasRenderer）。

Mermaid 中的节点标签：使用通俗易懂的英文标签，例如“Drawing Interaction”“Canvas Rendering”，而不是函数名或文件名。

边：使用简单的动词标注，例如“触发”“传入”“读取”“生成”“监视”。不要使用 API 方法名。

ER 图（erDiagram）

用于数据库相关的讲解：架构设计、表关系、迁移、数据模型。

语法：

erDiagram
    USERS {
        string id PK
        string email UK
        string name
        timestamp created_at
    }
    TEAMS {
        string id PK
        string name
        string owner_id FK
    }
    TEAM_MEMBERS {
        string team_id FK
        string user_id FK
        string role
    }
    USERS ||--o{ TEAM_MEMBERS : "joins"
    TEAMS ||--o{ TEAM_MEMBERS : "has"
    USERS ||--o{ TEAMS : "owns"

关系基数：

语法	含义
||--o{	一对多
||--||	一对一
}o--o{	多对多
||--o|	一对零或一

列标记：PK（主键）、FK（外键）、UK（唯一）。

ER 图上的点击处理器：ER 图中的实体原生不支持 Mermaid click 回调。请改为在渲染后通过 querySelectorAll('.entityLabel') 手动添加点击监听器——参见 html-patterns.md 中的实现模式。

步骤 4：生成 HTML 文件

按照 references/html-patterns.md 中的模式，创建一个独立的 HTML 文件。

文件位置：将文件写入项目根目录，命名为 walkthrough-{topic}.html（例如，walkthrough-canvas-drawing.html）。主题 slug 使用 kebab-case。

架构：HTML 使用 <script type="module">（原生 ES 模块）——不使用 Babel。这意味着：

• 模板字面量（反引号）可正常使用——可直接用于多行字符串
• Shiki 通过 ESM 导入，并在启动时高亮代码
• React/ReactDOM 以 UMD 全局变量的形式加载，通过 window.React / window.ReactDOM 访问
• 不使用 JSX——所有组件渲染均使用 React.createElement()

必需元素：

1. 标题和副标题，描述演示的范围
2. TL;DR 摘要——用 2-3 句话说明，并以可见卡片的形式显示在图示上方。新开发者会先阅读摘要，然后再查看图示。
3. 带可点击节点的 Mermaid 流程图（5-12 个节点）
4. 显示以下内容的节点详情面板：1-2 句话的描述、文件路径、代码片段
5. 显示节点类型颜色编码的图例

节点详情数据——为每个节点提供：

nodeId: {
  title: "Drawing Interaction",
  description: "Converts pointer events into shape data. This is the bridge between raw mouse input and the element model.",
  files: ["app/features/tools/useDrawingInteraction.ts"],
  code: `const element = createElement(tool, startPoint, currentPoint)`,
  lang: "typescript",
}

要点：

• description = 1-2 句纯文本。回答“这是什么？”和“它为什么存在？”，而不是“它内部如何工作？”
• code = 必填（1-5 行）。选择最有用的代码片段（参见上文步骤 2b 中的代码片段指南）。
• lang = 每个节点都必须设置——必须显式指定（例如，"typescript"、"javascript"、"vue"、"json"、"css"）。默认使用 "typescript"。绝不能省略 lang 字段。
• files = 由 "path" 或 "path:lines" 字符串组成的数组。

写入文件后，在用户的浏览器中打开它：

open walkthrough-{topic}.html    # macOS

Mermaid 约定

点击绑定

使用 Mermaid 的回调语法让节点可交互：

click nodeId nodeClickHandler "View details"

其中，nodeClickHandler 是在 HTML 中定义的全局 JS 函数。

子图命名

使用易于理解的心智模型标签：

subgraph user_input["User Input"]
subgraph core_logic["Core Logic"]
subgraph visual_output["Visual Output"]

边标签

使用简单动词：

A -->|"triggers"| B
A -.->|"watches"| C
A ==>|"produces"| D

直接调用使用 -->，响应式/监听关系使用 -.->，事件/发射使用 ==>。

质量检查清单

完成前，请确认：

• 图示包含 5-12 个节点（至少 5 个是硬性要求——请计数）
• 每个节点标签均为通俗英文（不含函数签名或文件名）
• 每个节点的描述不超过 2 句话
• 每个节点都有代码片段（1-5 行）——不能有任何节点缺少代码片段
• 每个节点都显式设置了 lang（例如，lang: "typescript"）——没有例外
• 存在 TL;DR 摘要，且不超过 3 句话
• 每个节点都对应代码库中的实际文件
• 代码片段均为实际代码，不得编造
• 文件路径正确，且相对于项目根目录
• 流程图准确呈现实际代码流程
• 点击任意节点都会显示其详情面板
• 图示能够渲染，且没有 Mermaid 语法错误
• HTML 文件能在浏览器中正确打开
• 子图标签通俗易懂（“用户输入”），而非技术性标签（“组合式层”）
• 边标签使用简单动词（“触发”），而非方法名（handlePointerDown()）
• <html> 标签包含 style="color-scheme: dark"
• 对于流程图：图示中的每个节点都有 click nodeId nodeClickHandler "View details" 绑定
• 对于 ER 图：在渲染后附加 .entityLabel 点击处理程序（Mermaid 的 click 语法不适用于 ER 图）

参考资料

• references/html-patterns.md — 完整的 HTML 模板、CSS 和 JavaScript 模式