dsh-code-review

审查 DeepSeek-Harness PR

本技能提供指导，并非完整清单。 验证并获取 PR 当前的 base 和精确 head，然后在阅读差异之前运行 pnpm --silent run change-scope --base <verified-base-ref> --head <verified-head-ref>，并阅读足够的上下文代码以理解设计。报告会指出路径和变更涉及的层级，但不能代替语义审查。若 PR 更改了目标分支或完成了合并，请重新确认 base 并再次运行该命令。优先关注正确性、生命周期、安全性和必需行为是否失效，而不是风格；一条有充分依据的阻塞问题，胜过一串细枝末节的意见。

评判差异之前，先阅读需求。 将变更路径对应到下方的文档，打开事实来源中每个相关页面，然后再依据这些需求阅读差异。凭记忆中的规则评判差异，正是违规内容通过审查的原因。

事实来源

• AGENTS.md 和 packages/AGENTS.md：仓库和软件包的常设编写规则。
• docs/defensive-patterns/：变更必须满足的架构要求及其背后的实践原则。每个页面负责一种产物；阅读差异涉及的每个页面：
  • general.md — 时序、异步状态、值的表示、共享所有权、去中心化、重构、迁移、性能证据、释放、回调、子进程。
  • package-surface.md — 导出、软件包结构、构建入口、依赖声明、解析钩子。
  • remote-and-api.md — 远程服务、@Remote 方法、API 分发、packages/api 中的业务所有权。
  • client-components.md — 客户端组件、插槽、存储、钩子、副作用、共享基础软件包。
  • conversation-and-session.md — 投影读取、Session 保留、对话节点、渲染器。
• docs/AGENTS.md：文档归档位置和行文规范。
• dsh-prose-standard：注释、文档、提示词和可见字符串的必需覆盖范围与编辑判断。
• dsh-ci-test-reliability：针对拥有资源、涉及异步操作或不稳定的测试和测试夹具的隔离与回归防护规则。
• dsh-client-ui-ux：面向产品用户的 GUI 变更所涉及的反馈界面选择、覆盖层安全性、平台窗口适配和视觉令牌规范。
• dsh-error-handling：故障分类、处理责任、故障隔离、状态保证和可操作的报告。
• dsh-session-projection：投影所有权、状态大小、历史读取和迁移。
• docs/testing.md 和质量门槛参考：必需的测试层级和门槛。
• Agent Notes：设计原理。若与 Agent Note 意见不一致，应视为设计讨论，而非自动否决。
• 对于双语变更，请阅读 translation-rules.md 和 terminology.md；扩展翻译技能不属于自动审查范围，仅在用户明确调用时运行。

阻塞性要求

1. 新文案须经过语义审查。 使用 dsh-prose-standard 严格审查所有新增或修改的 Markdown 段落、JSDoc、注释、提示词、描述、诊断信息和可见字符串。对照所属代码或行为，核实覆盖范围、准确性、位置和编辑质量；自动化检查无法证明这些属性。
2. 文档须与代码一致。 配置、默认值、错误、线缆字段、事件和公开行为的变更，须在同一差异中更新软件包 README 和 JSDoc。注释说明不明显的契约；对于实现过程叙述、测试演练、审查历史和重复的设计依据，应标记为删除或链接到唯一存放位置。
3. 核心类型文档须保持一致。 对主干或接缝词汇的变更，须更新相应的 subsystems 页面以及任何 type-equiv 条目。内部类型无需添加目录条目。
4. Cordis 所有权与清理。 审查 Cordis 插件代码或其入口可访问的辅助工具时，加载并应用 cordis-styling-nitpicking，检查变更行为及受影响的使用方。核查其三条 P0 规则：单例状态、未撤销的副作用，以及在使用方完成前释放的清理依赖。确认每项新增的注册表贡献都通过 packages/AGENTS.md 要求的处置测试。
5. 须具备所需证据。 核实作者已针对该差异运行相关本地检查，且 CI 覆盖了完整矩阵；审查两者均无法检测的语义缺漏。
6. 客户端 UI 文案须由语言区域管理。 拒绝嵌入 JSX、模板、辅助函数返回值、无障碍属性或原语默认值中的产品文案。要求使用带类型的字典键、标准 t 位置或显式的本地化属性、verify-client-ui-i18n，并提供每个受影响语言区域中的行为证据；用户数据、模型数据、线缆数据和代码标记须原样保留。

手动检查

• **意图和接口契约：**追踪每个变更接口的双方。确认实现符合 PR 和任何 Agent Note，包括错误、取消、所有权和释放。
• **错误处理：**对变更的失败路径应用 dsh-error-handling，包括其状态保证和最终面向用户的报告。除非状态所有者能确保后续工作的前置条件成立（包括恢复之后），否则拒绝捕获错误后继续执行。
• **生命周期和并发：**对于异步设置、回调、进程或拆除，应用 defensive-patterns/general.md。检查发布前的竞态、等待期间的取消、独立错误报告、回调隔离、重入前的所有权、完整的分离清理，以及静止状态下的释放。
• **范围、所有权和必要性：**首先识别每项新区别、字段、适配器、状态机、选项、防御性副本和兼容路径背后所需的行为。PR 引入的要求、检查或 Agent Note 是需要评估的设计选择，而非证明必要性的独立证据。接受另一种表示前，先比较现有源字段、判别值及其使用方；区分删除概念和迁移其声明位置。把不必要的概念移到更靠近其所有者的位置，并不算简化。依据根规则审视无关功能和推测性的通用性。
• **能力与使用方契合度：**追踪每个当前使用方，然后依据包规则指出泄漏到接口中的、特定于使用方的行为。对于所需行为，如果本地实现复杂度不高，应优先选择靠近其生产方或使用方的现有扩展点，并遵循所有权规则；比较由生产方拥有的声明合并与对远端核心或共享类型声明所做的更改。也要指出反向问题：泛型服务（注册表、会话、Agent）上的新公共方法，如果只有一个内部使用方调用，就是不必要的 API 扩张——应要求改为在构造时交给该使用方的私有能力闭包。
• **配置和公开选项：**接受新的 CLI 或配置透传之前，先追踪权威读取位置和优先级；转发的值可能会在使用前被覆盖。询问有哪些当前使用方证据或先例支持每项默认值、公开操作集、格式或导入的外部概念。缺少此类证据时，要求明确作出选择或暂缓决定。
• **模型视角：**检查受影响模式下模型实际收到的提示词、工具架构、结果和诊断信息。指出模型任务之外的概念，然后通过快照或端到端覆盖验证稳定文本是否完全一致，以及动态行为是否正确。
• **执行约束：**沿每条拒绝路径追踪到执行拒绝的操作；测试可能绕过架构、提示词、门面、包装器或监听器顺序的直接及其他调用方。
• **借用和派生状态：**依据包契约确定每个保留值是借用的还是自有的，然后追踪通知及每个缓存、提示词、UI 回显、重放和查询视图，直到文档规定的成功点和权威来源。
• **边界必须涵盖最终操作：**找出完整发出或保留结果（包括包装器和元数据）的所有者。针对字节数限制，测试极小值、精确边界、超大单块内容和多字节文本。
• **真实入口路径：**在相关情况下，测试应经过实际发布的 Loader、bin、worker、ACP 桥接或子进程。手动挂载的插件无法捕获无效的 Loader 导出；函数插件必须以命名导出形式导出其命名空间，且不能有默认导出。
• **测试强度：**断言应能因预期回归而失败，并验证外部状态、日志、事件或释放情况，而不是复述实现或盲信 Agent 的报告。覆盖是必要的，但不能证明场景正确。
• **测试可靠性：**对于拥有资源、异步、依赖平台或容易不稳定的测试，针对真实 worker/job 拓扑、资源分配、全局状态恢复、同步、超时预算和静止状态下的拆除，应用 dsh-ci-test-reliability。
• **负向对照：**针对每项变更的验收规则，验证一个刻意构造的无效案例能通过真实运行器测试并失败。
• **已实现的 Agent Note 与发布后的实际情况相符：**PR 实现了提议的 Agent Note 时，应在同一 diff 中将其移至恰当位置，并改写为描述已发布状态的现在时，然后对照实现核实路径、名称和机制。
• **对话记录变更：**编辑器可见或模型可见的变更应更新快照，或说明为何不适用快照。审查预期输出的 diff 时，应将其视为行为变更，而非格式噪声。
• **双语变更：**比较两种语言的含义和术语；配对哈希通过并不能证明翻译质量。

报告发现

说明缺陷、位置、影响和证据。对于局部缺陷，在最相关的精简差异范围内直接评论；对于涉及整体架构、范围或全局审查综合意见的问题，使用 PR 级评论。将阻塞项与建议分开，并省略已通过绿色检查强制执行的问题。回复时使用现有的 GitHub 审查讨论串。收到审查意见后，逐条核实每项主张，并基于技术依据修复或反驳，避免敷衍附和。