git:20260916.ec8be5b to git:20260922.be19ce4

---

name: mr-for-human

---

# MR for Human

让读者理解改动、只决策最重要的事情，并能找到对应源码。默认交付中文 Markdown。

## 三条核心原则

1. **金字塔贯穿始终。**全文、章节和每个重点都先给结论，再给必要解释和证据。第一屏只放最影响需求是否满足、改动范围是否合理及关键取舍的事项；需要人决定时给出建议、影响与具体选择。可查明的事实由 Agent 查明，普通实现细节在下层展开；没有待决事项时明确说明。

2. **目录改动可核对。**用变更目录树建立职责地图，再按功能串起这些目录的协作，落到具体文件改了什么、为什么与本次目标有关。每个变更文件都须有去向，目录摘要和重点选择不能隐藏额外行为。尤其检查混入的清理、重构、默认值调整与共享行为变化；关系无法证明的单独标注。

3. **边界与失败降级讲到底。**说明正常行为在哪些条件下成立，越过边界或中途失败时已完成什么、谁负责收尾、如何降级或恢复，以及用户最终看到什么。按实际代码描述拒绝、抛错、重试、回退或补偿；降级方案也要核实适用条件与剩余保证。

## 1. 固定对象与改动范围

从请求和已确认材料确定目标行为、比较范围与输出位置。业务意图未知时标为假设。

- MR/PR：取得项目、目标分支、base/head SHA 与 diff 完整性；区分平台 diff base、目标分支 tip 和 merge-base。优先使用已认证的平台 CLI/API，以固定 SHA 的源码补足上下文。

- 本地差异：明确 staged、unstaged、untracked 或指定 commits；未提交内容记录快照标识或内容哈希。区分工作区与远端 head。

- 先获取全部变更路径、增删/重命名状态与规模，再读取语义差异；记录 diff 口径与截断情况。用户限定范围时明确该限制，必要的跨范围依赖标作上下文。

- 用变更目录树展示本次涉及的层级，每个展示目录注释其本次实现功能；职责不清的继续查源码或标缺口。展开到能区分责任的子目录，单一路径可压缩，关键文件按需列出。说明生产实现、测试、生成契约、文档与打包的作用；若标文件数，注明统计口径。大树可放附件，正文保留主要职责与入口；单目录小改动可用简短路径加职责表达。

- 建立按目录组织的文件清单：**路径及状态 / 具体变化 / 与目标的关系**。关系分为目标内修改、必要配套、额外改动、待确认；必要配套需说明依赖关系。文件内包含多种目的时分别说明。

- 同类文件可合并一行，但路径必须可枚举并覆盖全部变更；大型清单可放附件。权限、配置与默认值、迁移、协议/IDL、共享工具函数的语义变化单独点出。generated、test、搬移、type-only 等分类须核实，生成来源与测试断言也可能是重点。

完成条件：分析快照和目标明确，目录树与文件清单范围对应，读者能知道各目录在本次改动中的职责，所有已知变更文件均有记录。材料不全时区分“已读但未展开”和“尚未读取/不可见”；只对已读取范围给结论，保留缺口并继续可完成的分析。

## 2. 还原行为与边界

对照旧行为与新行为，追一条“谁触发 → 谁决定 → 状态或外部系统如何变化 → 谁看到结果”的正常路径。纯重构说明应保持的行为与改变的责任。结合输入前提、输出保证、状态归属解释关键抽象隐藏了什么决定，调用者仍需知道什么。

按功能串起来读：从用户场景或关键操作出发，把上述路径映射到真实目录和关键入口，用简短箭头链或文字解释每一步负责什么、向下一步传递什么。多条独立主线分别表达，共用步骤交叉引用；调用、数据传递、构建或生成依赖须分清。核实跨目录连接，将未接线、条件分支与未知标在对应连接处；模块和局部测试存在不等于生产路径已贯通。单文件可给函数内路径，纯文档或配置按真实使用/生效关系说明。

沿路径检查本次相关的边界：空值/缺失与极值、权限与租户、重复/并发、超时/取消、版本兼容。对关键失败点追到可见结果：

- 触发条件；失败前哪些写入或副作用已完成。

- 实际处理：拒绝、传播错误、重试、降级、补偿或清理；由谁执行、何时结束。

- 降级后保留和失去的保证，是否使用过期/部分结果，是否保持权限隔离，是否可能重复副作用。

- 调用方或用户看到的状态，恢复入口及相应证据。没有降级时说明实际失败行为，是否需要增加降级依据契约判断。

内部核对六项运行维度：资源生命周期、规模与容量、并发一致性、部分失败、信任边界、可观测与恢复。只展开影响理解或判断的结果；适用但未查明的关键保证保留为缺口。涉及具体机制时读取 [design-lenses.md](references/design-lenses.md) 的相关条目。

依赖内部不可见时写清需要它提供的保证。调用次数固定仅能证明入口调用次数有界；约束、清理或日志未出现在入口，不能据此认定整个系统没有它们。

完成条件：主要功能能沿目录职责追到入口与结果，关键连接、行为与失败后果有源码或契约依据；无法补足的链路明确停在证据边界，可继续形成有限指南。

## 3. 按重要性解释

先选择支撑核心行为、划定责任边界或改变共享语义的决定，再突出会改变用户判断的缺陷、风险与额外改动。排序综合对目标的影响、影响范围、触发可能性和可恢复性；阅读顺序与缺陷严重等级分别表达。

- 第一屏通常保留 3–5 条，少则按实际数量。每条给结论、重要影响和证据入口；仅对真实业务取舍、范围选择等提出决策。重大缺陷和重要范围偏离在第一屏可见，其余发现按主题下钻，相关问题可汇总链接。

- 每个重点集中解释一次：实现选择、相关前提、正常/失败结果和证据。功能、抽象与运行约束围绕同一行为展开；有实质取舍时再比较替代方案，并优先核实现有能力。

- 复杂逻辑才给核心伪代码或图。保留真实标识符、条件、顺序、事务范围、等待、取消、清理、权限及返回/抛错行为；显示部分成功窗口。未知被调函数标注所需保证，建议方案与当前实现分开。

- 重要主张区分代码事实、已确认需求、推断与未知；验证状态另写静态核实、有测试未运行、已运行及结果或未验证。已证明的问题需有具体触发条件、违反的契约与后果；潜在风险写明尚未证实的依赖条件。

- 重点与伪代码附文件、符号和可定位链接，定位到一致快照；新增引用 head、删除引用 base、重命名保留两侧路径，未改调用方标作上下文。长文需要交叉引用时再使用编号和映射表。引入提交仅在已查历史时填写。

完成条件：读者先获得重要结论，只有必要事项需要其决策，其余内容能沿解释和链接下钻。

## 4. 交付与核验

使用 [output-template.md](references/output-template.md) 的轻量骨架，按规模合并章节。需要学习失败窗口保真，或如何写简短的正常实现指南时，读取 [worked-example.md](references/worked-example.md) 对应示例。

交付前核对：

- 按已知变更清单逐文件对账，确认目录树、职责说明与功能路线相互对应；额外改动和待确认项没有被“必要配套”掩盖。

- 正常路径、关键边界和失败降级的解释与源码一致；源文件、链接及伪代码属于同一快照。

- 内部自检：读者能解释关键取舍、预测一次相关失败，并找到对应代码；缺失依据在正文补足或标为未知。

- 给出简短源码阅读路线；排查请求再补观察字段、日志、断点及已核实的命令。测试存在、断言相关与执行通过分别说明。

- MR/PR 声称最新前回读 head；变化后标为旧快照，更新分析后才称最新。只收到离线材料时注明无法回读。

默认执行读取与文档生成。运行测试、修改实现、发布评论、批准或合并等动作沿用用户当前授权。交付指南与验证边界。