walkthrough git:20260910.4546a3cA

Immutable. This exact content never changes and is served at /api/v1/blob/bbc95d111dcf6c38.

---
name: walkthrough
description: 当用户需要真正理解一个非平凡对象，以便核验、接手或继续作决定时使用。读取需求、计划、设计、代码、diff、分支、评审、故障或成果本身，为没有读过当前对象的读者重建一条连续、可查证的理解路径。用户指定 `--learn`、要求边理解边学习，或明确表示缺少相关技术基础时进入教学模式。需要完整风险审计时交给 `review`；只需解释一个概念、校准一句 Prompt 或简短回答时交给 `teach` 或直接回答。
---

# walkthrough

## 把读者带回能继续判断的位置

先锁定读者真正想理解的对象、实际读取的版本或状态、读者当前认知位置，以及理解之后要作出的判断。默认只假定读者没读过对象，不擅自降低其技术能力；必要概念在首次出现处解释。

写作前先补齐完成当前判断所需的关系面：范围内的 operation、用户与系统入口、权限与公共契约、数据或文件状态、异步过程、下游消费者和最终结果。每一项都要进入连续主线、必要细节或具名未覆盖；公共基础发生变化时，依赖它的既有行为即使外部结果未变也不能省略。

Walkthrough 跟着这些关系走，不按文件、提交或工作阶段复述。先建立理解后续所需的原有情况，再沿入口、关键关系、状态变化和消费者走到结果；没有前后变化的对象，就按目的、组成、约束和待决定处组织。

正文承担理解，链接与证据承担核验。读者不打开源码也应能跟上主线，但每个重要结论都能回到对象、`context.md`、Current Artifacts 或运行证据。

## 在 `--learn` 中让理解可以迁移

普通模式把读者带到能继续判断的位置；`--learn` 还要让读者获得下次可以复用的概念、辨别方法或阅读能力。学习目标服从当前对象和用户接下来要作的判断，不把一次 Walkthrough 扩成完整课程，也不建立长期学习档案。

先直接回答用户最关心的问题，再按“直觉 → 关系形状 → 当前对象中的具体例子 → 真实机制与边界”逐层加深。第一层必须短而准确，给后续细节一个可以挂靠的框架；后一层只补当前目标需要的深度。术语首次出现时用普通语言定义，类比只解释已确认相似的结构，并同时指出类比在哪里失效。

只把用户亲口确认或可靠上下文明确记录的知识当作已掌握前提。用户提到某个术语、贴出一段代码、参与一次 CR，不能证明其掌握对应语言或框架。前置基础不明时，先从完成当前判断所需的最低起点把解释给足；可以在收尾问一个用于调整后续深度的问题，但不能把回答问题、猜谜或自证基础作为获得讲解的前置条件。

至少用一个来自当前对象的真实输入、状态变化、代码片段或前后对照走完关键关系，让抽象概念落回正在理解的系统。明确点出一个最容易混淆的边界，并说明“这次学到哪里已经够用、什么可以暂时不学”。如果用户的 Prompt 用词含混或概念混用会影响理解，同时给出更准确但仍自然的表达，并解释新旧说法会让判断怎样不同。

用户有时间继续时，可以在完整讲解之后给一个轻量检查：让用户预测一个结果、辨别一组近邻概念或用自己的话复述关键因果，三者择一即可。检查用于发现下一处讲解缺口，不设默认考试或通过门槛；用户不回答也不影响本轮已经获得完整解释。

当纯文字会迫使读者在脑中重建形状时，用紧邻正文的最小视觉结构直接承担那段关系：逻辑或算法用伪代码，运行调用用调用树，所有权与嵌套用组件树或浅文件树，多参与方时序与数据流用 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。否则直接在对话中交付，或使用用户指定路径。

完成时，读者能说清对象是什么、关键关系怎样通向结果、证据支持到哪里、哪些部分未覆盖，以及下一步由谁判断。`--learn` 还应让读者获得至少一个能在相邻问题中再次使用的概念或辨别方法，但不以用户当场作答证明完成。Walkthrough 不批准方向、实现或交付，也不借讲解扩大对象范围。