为什么 AI 代码审查在缺乏项目上下文时会失败
Source: Dev.to
请提供您希望翻译的正文内容，我将按照要求保留源链接并进行简体中文翻译。
背景
每一次 AI 代码审查的开始方式都相同。
机器人打开你的 PR，扫描差异，标记缺失的 try/catch，建议使用更具描述性的变量名，并指出你可以对该函数进行记忆化以提升性能。所有这些在技术上都是正确的，但并没有实际帮助。
因为它不知道 fetchUser 是你们团队强制执行的命名约定，错误处理被委托给全局边界，或者正确性比性能更重要。机器人从未了解过你的项目。
这并不是模型的问题，而是 上下文问题。
这正是 pi‑reviewer 所构建的核心——一个 GitHub Action 和 pi TUI 扩展，将你的项目约定带入每一次审查。
在代理看到任何差异行之前，它会先读取：
AGENTS.md或CLAUDE.md– 你的通用项目约定：命名规则、架构决策、要遵循的模式REVIEW.md– 审查特定规则：始终需要标记的内容、明确要跳过的内容
这些文件中的 Markdown 链接会递归地被解析。如果 AGENTS.md 链接到 docs/api-conventions.md，该文件也会被内联。代理能够看到完整的全貌，而不仅仅是摘要。
审查指南
始终标记
fetch调用在.json()之前缺少res.ok检查- API 端点未在
/api/v1/下进行版本化 - 函数命名为
getData、doStuff或其他通用名称
跳过
- 仅格式化的更改
- 对
pi-review.md内的更改
添加项目上下文
之前： 代理标记了内部辅助函数缺少类型注解，建议重命名变量，并指出了一个多余的 console.log。
之后： 它捕获了同一 PR 中添加的未版本化的 API 端点，标记了缺少 res.ok 检查的 fetch 调用——正好符合 REVIEW.md 中的规则，并按照指示跳过了生成文件中仅格式化的更改。
同一模型。同一差异。审查结果却完全不同。
Source: …
严重性过滤
并非每个发现都值得同等重视。pi‑reviewer 允许你按严重性进行过滤，以便专注于重要内容。
uses: zeflq/pi-reviewer@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pi-api-key: ${{ secrets.PI_API_KEY }}
min-severity: warn将 min-severity: warn 设置后，代理会完全跳过 INFO 级别的建议——无论是在生成的内容中，还是在发布到 PR 的内容中。你也可以从 GitHub Actions UI 手动触发审查，并即时选择严重性级别。
三个层级
- 🔴 CRITICAL – 错误和安全问题
- 🟡 WARN – 逻辑和类型错误
- 🔵 INFO – 风格和建议
运行 pi‑reviewer
pi‑reviewer 在 pi 上运行——这是一个基于终端的编码代理，位于 pi mono 平台之上。一个 PI_API_KEY 可在所有受支持的模型和提供商之间通用。你选择模型，pi 会路由请求。这意味着你不必锁定在单一提供商——可以在不更改工作流的情况下切换模型，审查逻辑保持不变。
它也支持通过 SSH 使用。如果你的项目位于远程机器上，--ssh 模式可以让代理直接在远程获取差异并读取你的约定——无需本地副本。
与 Anthropic Code Review 的比较
Anthropic 最近推出了 Code Review，这是一项内置于 Claude Code 的托管 PR 审查服务。它会读取 CLAUDE.md 和 REVIEW.md，并行运行多个专门的代理对你的完整代码库进行检查，然后在代码中内联发布带有严重性标签的发现。它确实令人印象深刻，但也伴随一些限制：
- 在 Anthropic 基础设施上提供的托管服务
- 需要 GitHub App 安装，仅在 Teams 和 Enterprise 计划中可用
- 每次审查大约 $15–25 的费用
- 仅限 Claude 使用，无法控制运行位置
pi‑reviewer 在你的 CI 中运行，只需支付令牌使用费用，通过 pi mono 可使用任何模型，只需要一个密钥和一个工作流文件。无需 GitHub App，也不需要管理员审批流程。
如果你想在本地审查代码而不必提交 PR —— 完全不打开 PR —— pi TUI 扩展在终端中提供 /review 命令。
两者都读取你的 CLAUDE.md 和 REVIEW.md。区别在于 运行地点、成本以及你保留的控制程度。
入门
npx github:zeflq/pi-reviewer init该命令会生成一个工作流文件。添加你的 PI_API_KEY 密钥。从此以后，每个 PR 都会获得一个了解你项目的审查。
上下文文件 — AGENTS.md、REVIEW.md — 位于你的仓库中。它们受版本控制、团队可编辑，并随项目演进。你对约定的文档记录越完善，审查的质量就越高。
结论
洞察点不在于 AI 能够审查代码，而在于 没有项目上下文的 AI 审查 只不过是一个拥有更好文字表达的 linter。真正重要的审查是能够理解 为什么 你的代码库会是现在这个样子——并且将差异与此进行比对，而不是与某种通用的“好代码”概念对照。
上下文决定一切。没有上下文的差异只是噪音。