walkthrough

name	walkthrough
description	在用户需要真正理解任何非平凡对象时使用，包括需求、计划、设计、代码、diff、分支、评审结论、测试结果、故障、进行中的方向或已完成成果。读取对象本身和必要上下文，为没有读过当前对象的读者写成连续、自包含、能检查证据并继续判断的 Walkthrough；它可以发生在工作前、中、后任何位置，不用摘要、文件清单或术语堆叠冒充理解。

walkthrough

让读者能接着往下判断

Walkthrough 不是交付阶段，而是一份让读者独立理解对象、并接着作判断的讲解。可以用来理解尚未批准的方向、正在形成的设计、一次评审发现、复杂实现或已经完成的成果。

默认只假定读者没读过当前对象，不推断其技术能力。按当前对话、AGENTS.md 或其他明确提供的用户偏好调整语言和解释深度；没有相应上下文时，在首次出现处解释理解当前对象所需的局部概念、缩写和项目术语。用户读完后应明白：对象实际是什么、各部分怎么联系、什么发生了变化、哪些关系仍然成立、证据支持到哪里、还有什么没看清。

叙述跟着对象走，不跟着工作走

锁定用户真正想理解的对象、当前 Active Task 的 revision（若有）、实际 source/working/target 和 inspected state，以及读完之后需要作出的判断。同一个对象可以服务不同决定，讲解重点也应随之改变。对象会动时，以用户授权的最新状态为准；旧 scope、旧 Task Operating Envelope、旧设计、旧分支、先前结论和过程记录只能作为历史材料，不能因为叙述更完整就取代现在。

叙述不能跑在证据前面。尚未实现、缺失验证、存在争议或仍在探索的部分保留真实状态；需要调查、实现、测试、评审或用户决定才能查明的内容，交回相应能力，不在 Walkthrough 里用确定语气填平。

写作前先确认没有遗漏

先画出对象的完整受影响面，而不是只列 diff：范围内的全部 operation、用户与系统入口、API 与权限检查、数据或文件状态、异步过程、下游消费者和最终结果。逐项确认它是新增、变动、删除，还是外部行为未变但内部依赖被重写，并让每一项进入连续主线、展开细节或明确的未覆盖说明。

权限、文件、公共模型或基础组件发生变化时，依赖它们的既有行为即使表面结果不变，也属于 Walkthrough；不写它们，读者就无法审核兼容性和传播范围。真正与对象及其传播链无关的内容可以排除，但要能说明边界，不是因为文件没直接出现在 diff 里就省略。

重建一条完整的理解路径

Walkthrough 按人的理解顺序讲解，不按文件、提交或阶段顺序复述工作。先说明读者必须知道的原有情况，再解释关键变化，随后走通完整的前因后果。内部受到影响但外部表现保持不变的行为，也要出现在这条链路中。

对象不包含前后变化时，不强行套用变更叙事。先讲清它的目的、组成、关系、约束和需要决定的地方，再按读者容易理解的顺序组织。

连续阅读部分必须自包含。读者不打开编辑器、源码、其他标签页或证据附件，也能理解系统如何从入口走到结果、变化在哪里发生、谁受到影响以及风险在哪里。主线使用一条可连续滚动的叙述；目录和侧栏只能导航，不能隐藏内容。不要用标签页分割 operation、权限、数据、文件和下游关系；需要控制篇幅时使用就地展开，但关闭状态也要保留结论与联系。

具体材料能实质降低理解成本时再使用：关系与时序可以用图，DDL、请求响应、权限条件、状态枚举和关键契约可以用代码块或表格，界面变化可以用真实截图或图示。每份材料都在正文中解释它与上下游的关系；不要让读者去源码里补全正文，也不要让一个方便展示的例子冒充完整行为。

非平凡 Walkthrough 读取 comprehension-structure.md，按对象和读者需要作出的判断组织内容。Markdown 产物遵循 Walkthrough Markdown demo；选择自包含 HTML 时，再读取 html-artifact.md，并遵循 Walkthrough HTML demo。两个 Demo 分别是对应媒介产物结构的唯一来源；中间叙述仍服从对象和理解效果，不套固定章节数量或视觉风格。

让证据和路径成为理解的一部分

每个重要结论都应能回到对象本身、task.md、任务产物或可检查证据。路径不是附录礼节，而是用户继续审查、复现和探索的入口。完成 Walkthrough 后，先告诉用户它讲清了什么，再给可打开路径、关键证据、真实限制、未覆盖范围、任务边界冲突和仍需介入的决定。

不要倾倒内部日志来证明努力，也不要只给一个路径让用户自己猜发生了什么。正文承担理解，证据承担核验；两者互相连接，但不能互相替代。

当前 Session 有 Active Task 且需要保存或交接时，先用 longrein task work start 建立工作单元，再写入 <task-workspace>/walkthrough/。主文件默认使用 walkthrough.md；只有选择自包含网页作为更合适媒介时才使用 walkthrough.html。其他证据与附件没有固定文件契约，只保留稳定名称并从主产物解释用途。落盘后用 task artifact 登记，并以 task work finish 收束；Task Command 失败时不直接编辑 Runtime 核心文件。没有 Active Task 时在对话中交付，或只写用户指定的路径；持久产物都告诉用户绝对路径。

理解也是完成状态

当 Walkthrough 将支撑高代价决定时，用短而实质的理解检查确认用户掌握了最容易误判的关系。理解检查不是记忆题，也不是固定仪式；它衡量用户能否预测行为、风险和边界。用户可以明确跳过，但不能被默认成已经理解。

边界

Walkthrough 不替作者、实现者、测试者或评审者给自己盖章，也不借讲解扩大对象范围。它发现叙述与现实冲突时，先修正理解状态或交回责任能力；发现反复出现的讲解问题时，由 evolution 判断是否应改变长期规则或工具。