dsh-code-review

这是 .agents/skills/dsh-code-review/SKILL.md 的中文精读。它把一个 reviewer（人或 agent）定位到这套代码库自己的标准上，并且列出了那些光看代码 diff 看不出来的检查。

什么时候触发

在 deepseek-harness 仓库 review 一个 PR 时使用。原文开宗明义：「这份 skill 是引导，不是一份完整清单。」

动手前先核实并拉取 PR 的 live base 和精确 head，然后：

$ pnpm --silent run change-scope --base <verified-base-ref> --head <verified-head-ref>

报告负责圈出路径和脏层，但替代不了语义 review。retarget 或合 base 之后要重建 base 并重跑。优先级：正确性、生命周期、安全、被破坏的必需行为，都排在风格之前——一篇带一个有实据 blocker 的短 review，好过一列挑刺。

事实来源

• AGENTS.md / packages/AGENTS.md：仓库与包层面的长期规则；
• docs/defensive-patterns.md：子进程、回调、异步状态、disposal 的 bug 类别；
• docs/AGENTS.md：文档位置与散文纪律；
• dsh-prose-standard：注释、文档、prompt、可见字符串的必备覆盖与编辑判断；
• docs/testing.md 与 quality-gates 决策记录：必备的测试层级与门禁；
• Agent Notes：设计理由。与某篇 Agent Note 意见相左，是一场设计讨论，不是自动否决。
• 双语改动另读 docs/i18n/translation-rules.md 与 terminology.md；扩展翻译 skill 不属于自动 review，只在用户显式调用时运行。

阻塞项（Blocking requirements）

1. 新散文必须过语义 review。用 dsh-prose-standard 逐段审每个新增或改动的 Markdown、JSDoc、注释、prompt、描述、诊断和可见字符串；自动检查证明不了覆盖率、准确性、位置和编辑质量。
2. 文档与代码同改。配置、默认值、错误、线上字段、事件、公开行为，要在同一个 diff 里更新包 README 和 JSDoc。注释陈述非显而易见的契约；复述实现、测试走读、review 历史、重复的理由，都应删掉或换成链接。
3. 核心类型文档同步。主干或 seam 词汇的变化要更新对应的 subsystems 页面和 type-equiv 条目；内部类型不需要进目录。
4. 注册要能清理。每个新的注册表贡献都要通过 packages/AGENTS.md 要求的 disposal 测试。
5. 不变量伴生物是语义的。每个动过的 ./invariant，都要在它所在包能观察到的位置，断言一个属主的事件流或可变数据关系；「服务或方法存在」「插件元数据」「固定纯例子」属于类型、加载或单元测试。包特定理由能确立「不存在可信的运行时关系」时，接受一个空的 installer，不要为消灭空白而硬造检查。
6. 必备证据存在。确认作者跑过与 diff 相关的本地检查、CI 覆盖穷尽矩阵；两者都查不出的语义空洞，才是 review 的主战场。

人工检查清单

• 意图与接口契约：每个改动的接口，两侧都要追。实现要与 PR 和任何 Agent Note 一致——包括错误、取消、所有权、disposal。
• 生命周期与并发：异步 setup、回调、进程、拆卸，套用 defensive-patterns.md：发布前的竞态、await 期间的取消、错误独立上报、回调围堵、重入前的所有权、detach 清理完整、dispose 到静默。
• 能力与消费者的匹配：追每一个现存消费者，标记漏进接口的消费者特定行为。反过来也要标记：一个通用服务（注册表、session、agent）上新增的公开方法，如果唯一调用方是某个内部消费者，那就是不必要的 API 扩张——应改成构造时递给那个消费者的私有能力闭包。
• 范围、所有权与必要性：把每个抽象、状态机、选项、防御性拷贝、兼容路径，映射到它当前的契约、生产消费者和归属插件；挑战无关特性和投机性通用化。
• 配置与公开选择：每个默认值、公开操作集、格式、引入的外部概念，问一句「有什么现存消费者证据或先例支撑」。没有就要求显式做出选择或显式推迟。
• 模型视角：检查模型在各受影响模式下实际收到的 prompt、工具 schema、结果和诊断。标记超出模型任务的概念；稳定文本逐字核对，动态行为靠快照或 e2e 覆盖。
• 强制执行：沿每条拒绝路径走到真正执行它的操作；试试能绕过 schema、prompt、门面、包装器或监听器顺序的直接调用方和替代调用方。
• 借用与派生状态：每个被保留的值，按包契约判断是借用还是自有；再把通知和每个缓存、prompt、UI 回显、回放、查询视图，追到文档记载的成功点和权威来源。
• 边界覆盖最终操作：找到完整产出或保留结果（含包装器和元数据）的属主。探测极小值、精确边界、超大单块、字节限制下的多字节文本。
• 真实入口路径：相关时，测试要走 shipped Loader、bin、worker、ACP 桥或子进程。手工挂载的插件抓不到非法的 Loader 导出；函数式插件必须具名导出它的命名空间、且没有 default export。
• 测试强度：断言要在预期回归上真的变红，要验证外部状态、日志、事件或 disposal，而不是复述实现或轻信 agent 的自述。覆盖率高是必要的，但不能证明场景本身正确。
• 不变量生命周期与阴性对照：候选观察尽可能在发布前被拒绝；session 支撑的检查在迟加载或 HMR 之后能重建耐久历史；一个故意构造的非法用例，要能通过真实 runner 在预期规则上失败。
• implemented 状态的 Agent Note 要与 shipped 现实一致：PR 实现了一篇 proposed note 时，在同一个 diff 里把它移动并改写成现在时的已落地状态，再对照实现核对路径、名字和机制。
• transcript 变化：编辑器可见或模型可见的变化要更新快照，或解释为什么没有快照适用。review 期望输出的 diff 时把它当行为变化看，不是格式噪音。
• 双语变化：两侧对照含义和术语；配对 hash 变绿证明不了翻译质量。

怎么写 review 结论

每条发现写清：缺陷、位置、影响、证据。局部缺陷放在最紧的相关 diff 行内；跨切面的架构、范围或整篇综述用 PR 级评论。blocker 与建议分开；已被绿色门禁覆盖的问题不要再提。回复走已有的 GitHub review 线程。被 review 时，逐条核实每个论断，基于技术理由修复或反驳——不做表演性的同意。