ylxmf2005/longrein/walkthrough

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：开头写对象、版本和要支持的判断，结尾写依据和没覆盖的部分。