github-deep-review

GitHub 深度评审

像 Peter 一样评审：高置信度、以证据为先、了解代码，并在证据链薄弱时愿意直言“尚未证实”。目标不是泛泛总结，而是理解 bug 类型；尽可能找出真正原因；充分阅读代码后确定最佳修复方案；并指出更大范围的重构是否能改善设计。

开始

对于 GitHub 引用，使用 gh，不要浏览网页：

gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch

对于 PR，默认收集作者背景信息，除非作者是 Peter（steipete 或明显由 Peter 所有的账户）。使用 ~/Projects/agent-scripts/skills/github-author-context/SKILL.md 中的本地工作流；如果作者不是 Peter，请在评审靠前位置加入简短的 作者背景： 区块。 合并、拒绝、关闭或评审之后，使用同一作者背景工作流，仅当此次互动产生了对未来评审有长期价值的信息时，才追加贡献者备注。

对于仓库本地评审，还要检查：

git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"

如果仓库有本地说明、issue/PR 技能、文档列表、测试指南或维护者操作手册，请先阅读，再作判断。

评审约定

务必明确回答以下问题：

• URL/引用：issue 或 PR 编号，以及受影响的范围。
• 正在修复的 bug 或行为是什么？
• 能否确定根本原因？如果可以，指出代码位置和原因；如果不可以，说明缺少哪些证据。
• 对于回归问题，是谁/什么在何时引入的？如果能通过有限范围的历史记录追溯，请提供 commit/PR 来源；无法确定时请说明未知，不要猜测。
• 阅读相关代码后，当前/提议的修复是否是最佳方案？
• 更大范围的重构能否改善正确性、清晰度或未来的可维护性？
• 有哪些证据：测试、实际复现、CI 检查、文档、依赖项文档/源码、已发布/当前行为。
• 还有哪些风险或尚未验证的事项？

代码阅读深度

不要只看第一个改动文件。沿着实际调用路径深入阅读：

• 入口点 -> 验证/解析 -> 路由/分发 -> 所属模块 -> 共享辅助工具 -> 持久化/网络/运行时边界
• 配置/架构/文档 -> 运行时用法 -> doctor/迁移/修复路径
• provider/channel/plugin 所属代码 -> 通用核心接口，仅在多个所属模块都需要时
• 改动范围内的测试，以及相邻的回归测试

如果行为取决于某个依赖项，请先阅读上游文档/源码/类型定义或当前软件包约定，再作假设。

优先采用当前源码和可执行证据，而不是 issue 评论。过时的注释、旧 CI 和旧版发布行为只能作为线索，需重新核实后再采信。

溯源

审查 Bug／回归时，在可行的情况下加入简洁的 Provenance: 回答：

• 使用 git log -S/-G、git blame 和关联的 PR／Issue 定位候选记录，而非据此证明问题何时引入。在声称“由……引入”之前，检查原始父提交：运行 git --no-replace-objects cat-file -p <sha>，并确认 git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path> 确实改变了相关行为；可行时使用测试／复现验证。要认定是真正的根提交，必须有原始头信息证明它没有父提交。
• 单独依赖 ^sha、porcelain 格式的 blame、boundary 和浅克隆／嫁接历史，不能证明问题何时引入。--root 可能隐藏边界标记；git show 和 rev-list --parents 可能把浅克隆边界伪装成根提交。即使位于浅克隆边界，只要有可用的原始父提交，就能进行明确比较；如果缺少父提交或补丁无法验证，应说明缺失的信息并标记为 unknown，不能根据主题、日期或作者推断。
• 区分代码作者、引入问题的 PR 作者、合并者、提交者、自动化触发者和当前 PR 作者。通过明确的元数据／事件核实身份和触发者；角色本身不能证明因果关系，未经核实的身份应标记为未知。
• 只有在触发者已核实的情况下，才使用 made visible by；只有在既有行为已核实的情况下，才使用 carried forward by。摘要和责任方提示也应遵循同样的证据标准，不仅限于 Provenance: 字段。注明置信度：clear、likely 或 unknown。
• 对功能、文档和重构，写 N/A；对于无法追溯的 Bug，说明缺少哪些证据并标记为 unknown。缺少溯源信息，不会使经过独立验证的 Bug 失去效力。

修复质量标准

好的修复通常会：

• 在 Bug 所属的职责边界处处理
• 保留公开行为和向后兼容性，除非问题本身涉及弃用
• 在最小且有意义的接缝处添加回归测试
• 避免宽泛的特殊处理、隐藏迁移、语义哨兵，以及在通用核心代码中使用提供方／渠道 ID
• 在用户可见行为发生变化时更新文档／变更日志
• 在运行时路径中明确失败，并在这属于既定约定时通过 doctor／迁移路径修复

指出仅停留在症状层面的修复。如果稍大一些的重构能让不变量一目了然并减少未来的 Bug，请提出建议。如果重构扩大了风险，却没有改善这类 Bug，则应明确说明。

PR 审查格式

审查 PR 时，先列出审查发现。审查发现必须包含文件／行／符号引用和具体的失败方式。避免含糊的“可以考虑”式评论。

如果没有阻塞性问题：

• 说明未发现阻塞性正确性问题
• 列出已核查的最有力证据
• 说明残余风险／测试缺口
• 回答该设计是否是现有最佳方案

除非用户要求，否则不要批准、评论、关闭、合并、推送或落地更改。

Issue 审查格式

针对 Bug／Issue：

1. 还原报告者的场景及受影响的版本／界面。
2. 检查当前 main 是否已修复。
3. 可行时进行复现，或创建最小的本地／线上验证。
4. 如果结论明确，指出根因和建议的修复方案。
5. 如果 main 已解决问题，只有在用户要求时才评论／关闭；附上证据以及已知的规范提交／PR。

如果无法复现，应准确说明阻碍因素，以及哪些证据能让判断更加可靠。

输出模板

当用户询问“这是关于什么的”“这是最佳修复方案吗”或“我们修复了什么”时，使用以下格式：

Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>

Bug: <one or two sentences>
Cause: <code path + confidence>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <what should change and why>
Refactor: <yes/no, specific shape>
Proof: <tests/live/CI/source/dependency docs>
Risk: <remaining uncertainty>

保持简洁，但不要省略关于原因／修复／重构／证据的判断。