walkthrough · diff
git:20260910.4546a3c to git:20260923.8eb4b09
66 added, 19 removed. Audit A to A.
---
name: walkthrough
- description: 当用户需要真正理解一个非平凡对象，以便核验、接手或继续作决定时使用。读取需求、计划、设计、代码、diff、分支、评审、故障或成果本身，为没有读过当前对象的读者重建一条连续、可查证的理解路径。用户指定 `--learn`、要求边理解边学习，或明确表示缺少相关技术基础时进入教学模式。需要完整风险审计时交给 `review`；只需解释一个概念、校准一句 Prompt 或简短回答时交给 `teach` 或直接回答。
+ description: 用户想弄懂一段代码、diff、分支、MR、设计或一次故障，以便核对、接手或做决定时使用，例如"讲讲这个改动""带我过一遍这个模块""这个 PR 做了什么"。只问一个概念、一句话能答清时直接回答；要判断能不能合并时用 review。
---
# walkthrough
- ## 把读者带回能继续判断的位置
+ 给没读过这个对象的人讲清它：一条从入口到结果的连续主线，读者不用自己翻代码补跳步；每个关键结论都能核对。
- 先锁定读者真正想理解的对象、实际读取的版本或状态、读者当前认知位置，以及理解之后要作出的判断。默认只假定读者没读过对象，不擅自降低其技术能力；必要概念在首次出现处解释。
+ ## 先定对象和读者
- 写作前先补齐完成当前判断所需的关系面：范围内的 operation、用户与系统入口、权限与公共契约、数据或文件状态、异步过程、下游消费者和最终结果。每一项都要进入连续主线、必要细节或具名未覆盖；公共基础发生变化时，依赖它的既有行为即使外部结果未变也不能省略。
+ - **对象**：哪个版本，分支、提交、diff 还是某个运行时刻。
+ - **读者要拿它做什么**：接手就讲结构和约束，批准变更就讲行为变化和影响范围。这决定讲多深。
+ - **读者已经知道什么**：默认没读过这段代码，但不默认技术弱；术语第一次出现时就地解释。
- Walkthrough 跟着这些关系走，不按文件、提交或工作阶段复述。先建立理解后续所需的原有情况，再沿入口、关键关系、状态变化和消费者走到结果；没有前后变化的对象，就按目的、组成、约束和待决定处组织。
+ ## 查全关系，按关系讲
- 正文承担理解，链接与证据承担核验。读者不打开源码也应能跟上主线，但每个重要结论都能回到对象、`context.md`、Current Artifacts 或运行证据。
+ 动笔前先查全相关的关系：入口（用户操作、API、定时任务）、权限、公共接口、数据和状态、异步过程、下游消费者、最终结果。每一项要么进主线，要么作为补充，要么标明没覆盖。改到公共基础时，依赖它的既有行为即使结果没变也要讲。
- ## 在 `--learn` 中让理解可以迁移
+ 先讲读懂后文需要的背景和原有情况，再从入口出发，走过关键调用、状态变化和消费者，直到结果。不按文件或提交顺序复述，那是 diff 已经给出的东西。没有前后变化的对象，按目的、组成、约束和待决问题来讲。
- 普通模式把读者带到能继续判断的位置；`--learn` 还要让读者获得下次可以复用的概念、辨别方法或阅读能力。学习目标服从当前对象和用户接下来要作的判断，不把一次 Walkthrough 扩成完整课程，也不建立长期学习档案。
+ 顺序跟着读者的理解路径走，不必结论先行。重要的多写，次要的少写，补充说明不抢主线。名称和术语与代码保持一致。类比用来跨过理解门槛，同时说明它在哪里不成立。
- 先直接回答用户最关心的问题，再按“直觉 → 关系形状 → 当前对象中的具体例子 → 真实机制与边界”逐层加深。第一层必须短而准确，给后续细节一个可以挂靠的框架；后一层只补当前目标需要的深度。术语首次出现时用普通语言定义，类比只解释已确认相似的结构，并同时指出类比在哪里失效。
+ ## 用最小的图
- 只把用户亲口确认或可靠上下文明确记录的知识当作已掌握前提。用户提到某个术语、贴出一段代码、参与一次 CR，不能证明其掌握对应语言或框架。前置基础不明时，先从完成当前判断所需的最低起点把解释给足；可以在收尾问一个用于调整后续深度的问题，但不能把回答问题、猜谜或自证基础作为获得讲解的前置条件。
+ 文字会迫使读者在脑子里重建结构时，在旁边放一个最小的图。只画当前判断用得上的节点，用真实的名称和路径；多种形式都行时选最小的。图负责结构，旁边的文字负责因果和边界。下面的例子只示范形式：
- 至少用一个来自当前对象的真实输入、状态变化、代码片段或前后对照走完关键关系，让抽象概念落回正在理解的系统。明确点出一个最容易混淆的边界，并说明“这次学到哪里已经够用、什么可以暂时不学”。如果用户的 Prompt 用词含混或概念混用会影响理解，同时给出更准确但仍自然的表达，并解释新旧说法会让判断怎样不同。
+ - **逻辑和分支**：伪代码。
- 用户有时间继续时，可以在完整讲解之后给一个轻量检查：让用户预测一个结果、辨别一组近邻概念或用自己的话复述关键因果，三者择一即可。检查用于发现下一处讲解缺口，不设默认考试或通过门槛；用户不回答也不影响本轮已经获得完整解释。
+ ```text
+ on(save)
+ if content unchanged
+ return cached
+ write content
+ ```
- 当纯文字会迫使读者在脑中重建形状时，用紧邻正文的最小视觉结构直接承担那段关系：逻辑或算法用伪代码，运行调用用调用树，所有权与嵌套用组件树或浅文件树，多参与方时序与数据流用 Mermaid，已有形状上的变化用对应结构的 diff，多数内容全新或需要复制时展示完整代码块。只有界面布局、状态对照或概念密度超出这些表达能力，且可交互或持久产物确实有助于当前判断时，才创建一个聚焦的 HTML 图解。图、表和截图遵循同一门槛，不作装饰，也不重复正文已经说清的内容。
+ - **单一入口的调用**：调用树。多方来回的时序不要用它。
- 每个视觉只保留当前判断需要的调用、文件、属性、状态和边界，使用真实名称、路径和方向；多种表达都可用时选择最小的一种。把视觉放在它所支持的短说明旁，让正文负责因果与边界，视觉负责结构、映射或时序。需要使用视觉结构时，先读 [visual-forms.md](references/visual-forms.md)，选择与当前关系同形的示例，不照搬示例中的领域细节。
+ ```text
+ submitForm
+ createSession
+ persistPrompt
+ navigateToSession
+ ```
- ## 让表达边界和证据一致
+ - **所有权和嵌套**：组件树讲运行时组合，浅文件树讲静态职责，只展开相关的分支。
- 只展开到读者完成当前判断所需的范围，不把 Walkthrough 做成完整审计。完整关系面保证讲解不遗漏，是否构成交付风险的独立裁决归 Review。未读取、无证据或刻意排除的部分明确说明，不能因未出现在 diff 里就假定不受影响。
+ ```text
+ src/
+ ├── commands/ # 解析用户动作
+ ├── sessions/ # 持有会话状态
+ └── transport/ # 发送请求
+ ```
- 尚未实现、验证不足、存在争议或仍在探索的内容保留真实状态。叙述与现实冲突时修正叙述；需要新调查、用户裁决、实现、测试或独立审查才能成立的结论，交回相应能力，不用确定语气填平。
+ - **多方时序或数据流**：Mermaid。
- 当前任务有 `context.md`，且讲解需要保存或交接时，写 `<task-workspace>/walkthrough/walkthrough.md`，以 [walkthrough.demo.md](references/templates/walkthrough.demo.md) 为唯一结构来源，并更新 Current Artifacts。否则直接在对话中交付，或使用用户指定路径。
+ ```mermaid
+ sequenceDiagram
+ User->>UI: 选择命令
+ UI->>Daemon: 发送 prompt
+ Daemon-->>UI: 流式返回结果
+ ```
- 完成时，读者能说清对象是什么、关键关系怎样通向结果、证据支持到哪里、哪些部分未覆盖，以及下一步由谁判断。`--learn` 还应让读者获得至少一个能在相邻问题中再次使用的概念或辨别方法，但不以用户当场作答证明完成。Walkthrough 不批准方向、实现或交付，也不借讲解扩大对象范围。
+ - **已有结构的变化**：和结构同形的 diff，调用变化用调用树 diff，组件变化用组件树 diff。
+
+ ```diff
+ on(save)
+ - write content
+ + if content unchanged
+ + return cached
+ + write content
+ ```
+
+ - **完整的目标形态**：读者需要看全或要复制时，给完整代码块，并在旁边说明它被谁调用、放在哪里。
+ - **文字图画不出来的**：界面布局、状态对照这类，做一个聚焦的 HTML 图并打开给用户。
+
+ ## 注明依据和边界
+
+ 关键结论附上依据：代码位置、命令输出、日志或文档。没读到、没证据或有意不讲的部分，直接说出来；没出现在 diff 里，不代表不受影响。没实现、没验证或有争议的内容，照实写它的状态。讲清楚就够了，有没有问题、能不能合并交给 `review`。
+
+ 写完从读者的位置读一遍：哪里要猜，哪里跳了步，哪里强调错了，回去改。
+
+ ## --learn
+
+ 用户加 `--learn`，或者说想边看边学、缺相关基础时，还要让读者带走一个下次能用在类似问题上的概念或看法：先给直觉，再用当前对象里的真实例子，最后讲机制和适用边界。点出最容易混淆的地方，以及学到哪里就够了。直接讲，不用考试或反问代替讲解。
+
+ ## 保存
+
+ 默认在对话里讲。用户要求保存，或当前任务已有 `.agents/tasks/<任务>/` 目录时，写成那里的 `walkthrough.md`：开头写对象、版本和要支持的判断，结尾写依据和没覆盖的部分。