OCR 提出的通用 Agent 代码审查三大痛点

[Svtter]

背景

alibaba/open-code-review 的 README 对通用 Agent（如 Claude Code + Skills）做代码审查的痛点做了精准总结。这三点对 opencode-actions 同样适用，记录于此作为架构演进的参考。

来源：https://github.com/alibaba/open-code-review#why-open-code-review

---

痛点 1：Incomplete coverage — 覆盖不全

On larger changesets, agents tend to "cut corners," selectively reviewing only some files and missing others.

大 changeset 时 agent 偷懒，选择性审查，漏文件。

opencode-actions 现状：✅ 基本不受此影响。我们走的是 opencode github run 单次调用，agent 拿到完整 diff。但这更多是依赖 OpenCode 自身的 diff 处理能力，没有独立验证"是否每个文件都被覆盖了"。

风险：当 PR 文件数极多时（50+ files），单次 agent 调用是否真的逐一审查了每个文件？目前没有硬性保障。

---

痛点 2：Position drift — 位置漂移

Reported issues frequently don't match the actual code location, with line numbers or file references drifting off target.

报告的行号和文件对不上。

opencode-actions 现状：⚠️ 存在此问题。我们的 review 输出是 PR 评论，但行级定位完全依赖 agent 的输出质量。没有独立模块验证 agent 报告的位置是否正确。

OCR 的解法：独立的 comment-positioning 模块 + comment-reflection 模块，工程代码而非 LLM 保证位置精度。

---

痛点 3：Unstable quality — 质量不稳定

Natural-language-driven Skills are hard to debug, and review quality fluctuates significantly with minor prompt variations.

prompt 微调导致质量波动，难以调试。

opencode-actions 现状：⚠️ 核心问题。我们的 review 完全依赖 prompt + 模型能力：

• 同一个 prompt，不同模型产出差异大
• prompt 微调后效果难以量化验证
• 没有 rule 文件匹配系统来约束 LLM 的关注范围

OCR 的解法：

• 模板引擎驱动的 rule matching（按文件类型匹配内置规则），比纯 prompt 稳定
• 场景调优的专用 toolset（从大规模生产数据中提炼）
• 确定性流水线处理文件选择/分组/定位，LLM 只管理解代码和生成评论

---

OCR 的核心哲学

纯语言驱动架构缺乏对 review 过程的硬约束。

OCR 的方案是 确定性工程 × Agent 混合：必须不出错的步骤（文件选择、分组、规则匹配、位置定位）用工程代码保证；LLM 只负责动态决策（理解代码、生成评论）。

对 opencode-actions 的启示

痛点	我们是否有	短期可改进
覆盖不全	低风险	可加 diff 文件覆盖率检查
位置漂移	存在	需要 post-processing 验证行号
质量不稳定	核心问题	引入 rule matching 或 prompt 版本化管理

这些问题不一定现在解决，但值得在设计 multi-review 和后续架构演进时持续参考。

[Svitter]

OCR 的分析框架对 opencode-actions 的架构讨论很有价值。结合当前代码现状，逐点分析：

痛点 1：覆盖不全

现状：review/ 是单次 opencode github run 调用的流水线，model 能力决定覆盖度，没有确定性验证。multi-review/（正在 openspec/changes/multi-agent-review 中建设）引入了 diff-filter.ts 做 lock 文件过滤控制 diff 体积，coordinator 做跨 reviewer 去重，但同样没有 "是否每个 diff 文件都被引用过" 的检查。

短期可做：在 diff-filter.ts 或 coordinator 层加一个确定性覆盖检查——统计 diff 中的文件列表，验证每个源文件在至少一个 reviewer 的输出中被提及。这是纯工程步骤，不依赖 LLM。

痛点 2：位置漂移

现状：review/ 和 multi-review/ 均没有 post-processing 层验证 agent 输出的行号/文件路径。agent 输出的 PR 评论直接提交，行级定位完全依赖模型输出质量。

短期可做：解析 agent 输出中的文件引用和行号，与 PR diff 做交叉校验。不匹配的引用标记为 [位置待确认] 或降级为文件级评论。这是 OCR 方案中 comment-positioning 模块的轻量替代——不需要 reflection 模块那么重型，但能兜底。

痛点 3：质量不稳定

现状：这是 multi-review/ 重点解决的问题——多个 reviewer persona（security.yaml / architecture.yaml / performance.yaml / quality.yaml）+ coordinator 交叉验证（2+ reviewer 同意 → 已确认）+ 去重，通过结构性冗余降低单模型方差。但 reviewer prompt 仍是自由文本，没有 OCR 那种按文件类型匹配规则（如"检测到 SQL → 加载 SQL 注入规则集"）的确定性层。

短期可做：reviewer persona YAML 中增加 filePatterns 字段，按 glob 匹配规则约束 reviewer 的审查范围，避免 reviewer 面向不相关文件浪费 token。这比 full rule matching engine 轻量，但能提供部分确定性约束。

开放问题

1. 优先级：multi-review/ 仍在建设中，上述改进是并入 multi-review 的 scope 还是独立迭代？
2. 覆盖率检查：是否需要硬阻断（覆盖不到 N% 的 diff 文件 → coordinator 返回 CANNOT MERGE）？还是仅输出 warning？
3. 位置校验：行号偏移多大容忍度？±3 行内算匹配还是必须精确？
4. 规则匹配深度：后续是否需要完整的 rule matching engine（类似 OCR 的模板引擎），还是 reviewer persona + 交叉验证足够？

从架构角度看，OCR 的 "确定性工程 × Agent 混合" 哲学和 multi-review 的 "多 reviewer + coordinator 辩论" 是互补而非对立的方向——前者保证过程可靠，后者提升判断质量。