reviewing-code

代码审查

理念

代码审查有助于维护健康的代码库，同时帮助贡献者取得成功。举证责任在 PR 一方：需要证明它能带来价值。你的职责是通过可执行的反馈，帮助 PR 达到这一目标。

重要：即使 PR 写得尽善尽美，只要添加了不需要的功能，也必须拒绝。代码必须推动代码库朝预期方向发展。拒绝时，请明确说明如何才能符合项目目标。

保持友好、热情，同时坚持高标准。指出哪些地方做得好。如果代码需要改进，请具体说明原因和修复方法。

关注重点

是否正确地推动了代码库发展？

即使代码完美，只要功能不需要，也应该拒绝。

依赖版本兼容性

当 PR 为适配依赖的新版本而调整代码时（例如，移除上游已删除的参数、使用新的 API）：

• pyproject.toml 中的版本固定必须相符。 如果变更会破坏对先前固定的最低版本的兼容性，就必须提高最低版本。否则，使用旧版本的用户就会遇到回归问题。
• 如果需要向后兼容旧版本，代码必须同时处理两个版本（例如，使用 try/except 或版本检查）。只删除对旧 API 的调用而不提高版本固定，一定是错误的——这会悄无声息地破坏旧版本用户的使用。
• 锁定文件（uv.lock）的变更应限于 PR 的目的。 修复 ty 兼容性问题的 PR，不应在运行 uv sync --upgrade 后还包含无关的依赖版本升级（anthropic、google-auth 等）。这些变更会制造噪音，让差异更难审查。

API 设计与命名

识别容易造成困惑或不符合惯例的代码模式：

• 与默认值相矛盾的参数值
• 可变的默认参数
• 会让未来读者困惑的不明确命名
• 与代码库其他部分不一致的模式

具体改进

提供可执行的反馈，不要只泛泛而谈。

用户体验

从用户角度思考 API。它是否直观？学习成本如何？

面向 Agent 审查者

1. 阅读完整上下文：审查前先查看相关文件、测试和文档
2. 对照既定模式：检查是否符合代码库惯例
3. 核实功能声明：理解代码实际做了什么，而不只是它声称做了什么
4. 考虑边缘情况：仔细考虑错误条件和边界场景

应避免的做法

• 不具体的泛泛反馈
• 不太可能发生的假设性问题
• 没有充分理由地挑剔组织安排
• 概述 PR 已经说明的内容
• 星级评分或过多的表情符号
• 功能正确时纠缠于风格偏好
• 提出修改要求却不建议解决方案
• 相比项目惯例，更关注个人编码风格

语气

• 肯定好的决策：“这个 API 设计很简洁”
• 直接但尊重他人
• 说明影响：“这会让用户困惑，因为……”
• 请记住：这段代码会由其他人长期维护

决策框架

批准前，请自问：

1. 这个 PR 是否实现了其声明的目的？
2. 这个目的是否符合代码库的发展方向？
3. 我是否愿意维护这段代码？
4. 我是否真正理解了它的作用，而不只是它声称做了什么？
5. 这项变更是否引入了技术债？

如果有需要改进的地方，你的审查应通过具体、可执行的反馈帮助其完善。如果它解决的是错误的问题，请明确指出。

评论示例

好的评论：

不妨写成	写成
“添加更多测试”	“handle_timeout 方法需要针对 timeout=0 这一边界情况编写测试”
“这个 API 令人困惑”	“参数名 data 含义模糊——建议使用 message_content，以符合 MCP 规范”
“这还可以做得更好”	“这种方法可行，但会造成循环依赖。建议将验证逻辑移至 utils/validators.py”

检查清单

批准前，请确认：

• 已完成所有必需的开发工作流步骤（uv sync、prek、pytest）
• 更改符合仓库的模式和约定
• API 更改已记录，并在可能的情况下保持向后兼容
• 错误处理遵循项目模式（使用具体的异常类型）
• 测试覆盖了新功能和边界情况
• 此更改推动代码库朝预期方向发展