---
name: walkthrough
description: 用户想弄懂一段代码、diff、分支、MR、设计或一次故障，以便核对、接手或做决定时使用，例如"讲讲这个改动""带我过一遍这个模块""这个 PR 做了什么"。只问一个概念、一句话能答清时直接回答；要判断能不能合并时用 review。
---

# walkthrough

给没读过这个对象的人讲清它：一条从入口到结果的连续主线，读者不用自己翻代码补跳步；每个关键结论都能核对。

## 先定对象和读者

- **对象**：哪个版本，分支、提交、diff 还是某个运行时刻。
- **读者要拿它做什么**：接手就讲结构和约束，批准变更就讲行为变化和影响范围。这决定讲多深。
- **读者已经知道什么**：默认没读过这段代码，但不默认技术弱；术语第一次出现时就地解释。

## 查全关系，按关系讲

动笔前先查全相关的关系：入口（用户操作、API、定时任务）、权限、公共接口、数据和状态、异步过程、下游消费者、最终结果。每一项要么进主线，要么作为补充，要么标明没覆盖。改到公共基础时，依赖它的既有行为即使结果没变也要讲。

先讲读懂后文需要的背景和原有情况，再从入口出发，走过关键调用、状态变化和消费者，直到结果。不按文件或提交顺序复述，那是 diff 已经给出的东西。没有前后变化的对象，按目的、组成、约束和待决问题来讲。

顺序跟着读者的理解路径走，不必结论先行。重要的多写，次要的少写，补充说明不抢主线。名称和术语与代码保持一致。类比用来跨过理解门槛，同时说明它在哪里不成立。

## 用最小的图

文字会迫使读者在脑子里重建结构时，在旁边放一个最小的图。只画当前判断用得上的节点，用真实的名称和路径；多种形式都行时选最小的。图负责结构，旁边的文字负责因果和边界。下面的例子只示范形式：

- **逻辑和分支**：伪代码。

  ```text
  on(save)
    if content unchanged
      return cached
    write content
  ```

- **单一入口的调用**：调用树。多方来回的时序不要用它。

  ```text
  submitForm
    createSession
      persistPrompt
    navigateToSession
  ```

- **所有权和嵌套**：组件树讲运行时组合，浅文件树讲静态职责，只展开相关的分支。

  ```text
  src/
  ├── commands/   # 解析用户动作
  ├── sessions/   # 持有会话状态
  └── transport/  # 发送请求
  ```

- **多方时序或数据流**：Mermaid。

  ```mermaid
  sequenceDiagram
      User->>UI: 选择命令
      UI->>Daemon: 发送 prompt
      Daemon-->>UI: 流式返回结果
  ```

- **已有结构的变化**：和结构同形的 diff，调用变化用调用树 diff，组件变化用组件树 diff。

  ```diff
   on(save)
  -  write content
  +  if content unchanged
  +    return cached
  +  write content
  ```

- **完整的目标形态**：读者需要看全或要复制时，给完整代码块，并在旁边说明它被谁调用、放在哪里。
- **文字图画不出来的**：界面布局、状态对照这类，做一个聚焦的 HTML 图并打开给用户。

## 注明依据和边界

关键结论附上依据：代码位置、命令输出、日志或文档。没读到、没证据或有意不讲的部分，直接说出来；没出现在 diff 里，不代表不受影响。没实现、没验证或有争议的内容，照实写它的状态。讲清楚就够了，有没有问题、能不能合并交给 `review`。

写完从读者的位置读一遍：哪里要猜，哪里跳了步，哪里强调错了，回去改。

## --learn

用户加 `--learn`，或者说想边看边学、缺相关基础时，还要让读者带走一个下次能用在类似问题上的概念或看法：先给直觉，再用当前对象里的真实例子，最后讲机制和适用边界。点出最容易混淆的地方，以及学到哪里就够了。直接讲，不用考试或反问代替讲解。

## 保存

默认在对话里讲。用户要求保存，或当前任务已有 `.agents/tasks/<任务>/` 目录时，写成那里的 `walkthrough.md`：开头写对象、版本和要支持的判断，结尾写依据和没覆盖的部分。