walkthrough · diff
git:20260727.106aa2e to git:20260814.8b558f7
5 added, 1 removed. Audit A to A.
---
name: walkthrough
description: 当用户需要真正理解一个非平凡对象，以便核验、接手或继续作决定时使用。读取需求、计划、设计、代码、diff、分支、评审、故障或成果本身，为没有读过当前对象的读者重建一条连续、可查证的理解路径。需要完整风险审计时交给 `review`；只需简短回答时不触发。
---
# walkthrough
## 把读者带回能继续判断的位置
先锁定读者真正想理解的对象、实际读取的版本或状态、读者当前认知位置，以及理解之后要作出的判断。默认只假定读者没读过对象，不擅自降低其技术能力；必要概念在首次出现处解释。
写作前先补齐完成当前判断所需的关系面：范围内的 operation、用户与系统入口、权限与公共契约、数据或文件状态、异步过程、下游消费者和最终结果。每一项都要进入连续主线、必要细节或具名未覆盖；公共基础发生变化时，依赖它的既有行为即使外部结果未变也不能省略。
Walkthrough 跟着这些关系走，不按文件、提交或工作阶段复述。先建立理解后续所需的原有情况，再沿入口、关键关系、状态变化和消费者走到结果；没有前后变化的对象，就按目的、组成、约束和待决定处组织。
- 正文承担理解，链接与证据承担核验。读者不打开源码也应能跟上主线，但每个重要结论都能回到对象、`context.md`、Current Artifacts 或运行证据。图、表、代码块和截图只在明显降低关系、时序或契约的理解成本时使用。
+ 正文承担理解，链接与证据承担核验。读者不打开源码也应能跟上主线，但每个重要结论都能回到对象、`context.md`、Current Artifacts 或运行证据。
+
+ 当纯文字会迫使读者在脑中重建形状时，用紧邻正文的最小视觉结构直接承担那段关系：逻辑或算法用伪代码，运行调用用调用树，所有权与嵌套用组件树或浅文件树，多参与方时序与数据流用 Mermaid，已有形状上的变化用对应结构的 diff，多数内容全新或需要复制时展示完整代码块。只有界面布局、状态对照或概念密度超出这些表达能力，且可交互或持久产物确实有助于当前判断时，才创建一个聚焦的 HTML 图解。图、表和截图遵循同一门槛，不作装饰，也不重复正文已经说清的内容。
+
+ 每个视觉只保留当前判断需要的调用、文件、属性、状态和边界，使用真实名称、路径和方向；多种表达都可用时选择最小的一种。把视觉放在它所支持的短说明旁，让正文负责因果与边界，视觉负责结构、映射或时序。需要使用视觉结构时，先读 [visual-forms.md](references/visual-forms.md)，选择与当前关系同形的示例，不照搬示例中的领域细节。
## 让表达边界和证据一致
只展开到读者完成当前判断所需的范围，不把 Walkthrough 做成完整审计。完整关系面保证讲解不遗漏，是否构成交付风险的独立裁决归 Review。未读取、无证据或刻意排除的部分明确说明，不能因未出现在 diff 里就假定不受影响。
尚未实现、验证不足、存在争议或仍在探索的内容保留真实状态。叙述与现实冲突时修正叙述；需要新调查、用户裁决、实现、测试或独立审查才能成立的结论，交回相应能力，不用确定语气填平。
当前任务有 `context.md`，且讲解需要保存或交接时，写 `<task-workspace>/walkthrough/walkthrough.md`，以 [walkthrough.demo.md](references/templates/walkthrough.demo.md) 为唯一结构来源，并更新 Current Artifacts。否则直接在对话中交付，或使用用户指定路径。
完成时，读者能说清对象是什么、关键关系怎样通向结果、证据支持到哪里、哪些部分未覆盖，以及下一步由谁判断。Walkthrough 不批准方向、实现或交付，也不借讲解扩大对象范围。