OpenCodeReview 自部署指南｜评审 Agent 降本闭环

代码评审是研发流程里最容易被压缩、也最不该被压缩的一环。我注意到阿里开源了 OpenCodeReview：一个源自内部 AI 代码评审助手的项目，可读全文件、检索代码库并产出深度评审，正好借它把评审 Agent 的降本闭环拆开讲清楚。

一、开篇痛点：评审慢、标准漂、意见没人看

人工评审有三个老毛病。

第一是慢。PR 提上去，评审人正在赶自己的迭代，一挂就是一两天，合并节奏被整体拖住；仓库越大，评审排队越长，紧急修复也要排在长队里等一个空闲的 reviewer。

第二是标准漂移。同一个问题，A 评审人要求必须改，B 评审人觉得可以放行；命名风格、边界检查、错误处理、测试覆盖的口径，全凭个人经验和当天状态。新人入职半年，也未必摸得清这个仓库"什么样的代码算合格"。

第三是意见没人看。当评审意见里混进大量"这个变量名建议再描述性好一点"之类的噪音，真正重要的 blocker 也会一起被淹没。最初两周还有人逐条看，之后评审列表就变成自动归零的待办项——评审 Agent 的信任是一次性消耗品，烧完就没了。

于是很多团队把 diff 直接丢给通用大模型。结果通常很一致：模型只看到 diff，看不到完整文件，更看不到调用方和仓库既有约定，于是把本来正确的代码标成问题，误报一条接一条。token 花了，信任反而更少。

我在搭这类流水线时的第一个原则，是把模型调用从第一天起就收敛到统一入口：密钥、配额、日志与模型切换只管一处，4sapi（https://4sapi.com）承担的就是这个角色，后面教程里的接入方式也基于这一点。

二、评审质量从哪里来：上下文与分层

先给结论：评审质量的上限，几乎完全由两件事决定——上下文够不够全，评审有没有分层。

上下文问题很好理解。diff 只展示改动行和少量前后文，而判断一行代码对不对，往往需要知道整个函数长什么样、这个字段还有谁在用、仓库里是否已经有更成熟的工具函数。把 diff 单独喂给模型，等于让评审人只看高亮行就签字。

分层问题稍隐蔽一些。让一个模型在一次输出里同时回答"有没有违反规范、有没有逻辑缺陷、会不会影响架构"，三件事混在一起，粒度失控，置信度也没法分开校准。拆成明确层次之后，每一层的判断标准、输出格式和过滤阈值都能独立调整、独立回归。

OpenCodeReview 的开源思路正好印证这两点。它源自阿里的内部 AI 代码评审助手，能力设定是读全文件、检索代码库并产出深度评审——上下文的完整度与评审的深度，恰好就是评审质量的两根支柱。

三、原理速览：一条评审流水线

把上面的判断拼成一条完整流水线：

PR diff 到达
      |
      v
确定性预检（lint / 类型检查 / 测试，零 token）
      |   预检拦下的问题直接打回，不进模型
      v
上下文组装（显式字符预算）
  ├─ diff 本体（全量保留）
  ├─ 变更文件的完整内容（读全文件）
  └─ 代码库检索结果（相似实现 / 调用方 / 仓库约定）
      |
      v
分层 LLM 评审
  ├─ 第一层：规则符合性
  ├─ 第二层：逻辑缺陷
  └─ 第三层：架构影响
      |
      v
结构化意见（blocker / suggestion / nit + 置信度）
      |
      v
人工复核与合并确认
      |
      +──误报标记──> 反馈回流（沉淀为检查规则或 prompt 反例）

这条流水线有三个设计要点：

1. 确定性预检放在最前面，机器能判对的事不花 token；
2. 上下文组装显式声明预算，diff、全文件、检索结果各占多少字符写得清清楚楚，超出就按优先级截断并留痕，而不是指望模型"自己再挤一挤"；
3. 意见必须结构化，级别与置信度缺一不可，否则后面的过滤、通知和回流都无从谈起。

四、确定性预检：零 token 的第一道闸

lint、类型检查、单元测试这些手段有三个模型比不了的属性：零 token 成本、秒级出结果、判定确定——同一段代码跑两遍，结论完全一致。LLM 恰恰在这三点上都弱。

所以分层的第一步不是调模型，而是把所有"机器能判对的事"从模型嘴里抢回来：

• 格式与风格：formatter 和 lint 能覆盖的，一律不进模型；
• 类型与签名：类型检查器报的错误，比模型的猜测可靠得多；
• 行为回归：测试结果就是最硬的评审意见，门禁以测试为准。

预检同时充当漏斗。预检都过不了的 PR，没有理由再花 token 做深度评审；预检通过的干净 diff，进入模型的上下文也更小、更聚焦。这一步做得越彻底，后面每一层就都越便宜。很多团队评审 Agent 的账单偏高，根因往往是跳过了这一层，把 lint 该拦的格式问题也拿去问模型。

五、上下文组装：读全文件与检索代码库

这一层对误报率的影响最大。

最小可用版本是"diff + 变更文件的完整内容"。全文件解决的是"改动行脱离上下文"的问题：一个看起来可疑的空值检查，放进完整函数里，可能发现上层早已做过保护；一段看似重复的逻辑，可能是在等一次后续 PR 收敛。只看 diff 行的评审，误报大部分来自这里。

进阶版本加入代码库检索：相似实现、调用方、既有工具函数、相关历史提交。检索的目的不是炫技，而是把"这个仓库自己的约定"递给模型——约定写不成 lint 规则，却是评审里最常被违反的东西。OpenCodeReview 强调检索代码库，价值就在这里。

组装时必须显式做预算管理。我的做法是给整个上下文定一个字符预算：diff 全量保留，它本来就是评审对象；剩余预算按文件重要性分给全文件；超出部分明确标注"已截断"，而不是静默丢弃。静默截断是"模型漏评"最常见的根源之一——漏了哪个文件、截了多少行，日志里必须能查到，否则排障时两眼一抹黑。

六、分层评审与意见分级

评审 prompt 里至少要固化两件事：分层职责与意见分级。

分层职责参考：

• 第一层：规则符合性——命名、注释、测试覆盖是否与仓库约定一致，最好附上仓库里的对照例子；
• 第二层：逻辑缺陷——边界条件、并发与资源释放、错误处理路径、隐式类型转换；
• 第三层：架构影响——模块耦合、接口兼容性、迁移与回滚成本。这层意见天然低频，出现时值得在 PR 里单开一段。

意见分级固定为三档，并强制要求置信度：

这里的关键判断是：宁可少报，不可滥报。一条被认真对待的 suggestion 的价值，远高于十条噪音堆出来的"覆盖率"。模型对置信度的自评并不精确，但配合阈值过滤与人工反馈校准，足够先把最明显的噪音挡在门外。

七、接入教程：一个最小可跑的评审脚本

下面是一个可以直接落地的最小脚本：读取 diff 文件，组装带截断预算的上下文，调用 OpenAI 兼容接口输出 JSON 结构化意见，再按级别与置信度过滤。脚本按 Python 3.10+ 编写。

接口侧我走的是 4sapi 的 OpenAI 兼容端点，密钥与模型名放在环境变量里，CI 与本地共用同一套代码：

# -*- coding: utf-8 -*-
"""最小评审脚本：读取 diff、组装上下文、调用 OpenAI 兼容接口、按级别过滤输出。"""

import json
import os
import re
import sys
from pathlib import Path

from openai import OpenAI

BASE_URL = os.environ.get("REVIEW_BASE_URL", "https://4sapi.com")
MODEL = os.environ.get("REVIEW_MODEL", "deepseek-chat")
MAX_CONTEXT_CHARS = 60_000   # 上下文字符预算，超出时按优先级截断
MIN_LEVEL = 2                # 输出阈值：只保留 suggestion(2) 与 blocker(3)
MIN_CONFIDENCE = 0.6         # 置信度阈值，低于此值的意见直接丢弃

LEVELS = {1: "nit", 2: "suggestion", 3: "blocker"}

SYSTEM_PROMPT = (
    "代码评审助手。只基于给出的上下文评审，不臆测仓库中不存在的内容。"
    '输出严格 JSON：{"opinions": [{"file": str, "line": int, "level": 1|2|3, '
    '"confidence": float, "title": str, "detail": str}]}。'
    "level 含义：3=blocker（缺陷或明确错误），2=suggestion（改进建议），1=nit（风格细节）。"
    "判断不确定时降低 confidence，宁缺毋滥。"
)

DIFF_FILE_RE = re.compile(r"^\+\+\+ b/(.+)$", re.MULTILINE)


def read_diff(path: str) -> str:
    return Path(path).read_text(encoding="utf-8", errors="replace")


def changed_files(diff_text: str) -> list[str]:
    """从 diff 中提取发生变更的文件路径。"""
    names = []
    for match in DIFF_FILE_RE.finditer(diff_text):
        name = match.group(1).strip()
        if name and name != "/dev/null" and name not in names:
            names.append(name)
    return names


def read_full_files(names: list[str], repo_root: Path) -> dict[str, str]:
    """读取变更文件的完整内容；只看 diff 行是误报的主要根源，全文件才能支撑可靠判断。"""
    full = {}
    for name in names:
        path = repo_root / name
        if path.is_file():
            full[name] = path.read_text(encoding="utf-8", errors="replace")
    return full


def assemble(diff_text: str, full_files: dict[str, str], budget: int) -> str:
    """组装上下文：diff 全量保留，剩余预算分给全文件，超出部分明确标注已截断。"""
    parts = ["<diff>\n" + diff_text + "\n</diff>"]
    used = len(parts[0])
    for name, content in full_files.items():
        remain = budget - used
        if remain <= 500:
            parts.append(f"[全文件 {name}：超出预算，已截断]")
            continue
        piece = content[:remain]
        parts.append(f'<file path="{name}">\n{piece}\n</file>')
        used += len(piece)
    return "\n\n".join(parts)


def parse_opinions(raw: str) -> list[dict]:
    """解析模型输出，兼容被代码围栏包裹的 JSON；解析失败返回空列表并告警。"""
    fence = "`" * 3
    raw = raw.strip().replace(fence + "json", "").replace(fence, "")
    start, end = raw.find("{"), raw.rfind("}")
    if start == -1 or end == -1:
        print("[warn] 模型输出未找到 JSON 结构，放弃本轮意见")
        return []
    data = json.loads(raw[start : end + 1])
    return data.get("opinions", [])


def request_review(context: str) -> list[dict]:
    client = OpenAI(base_url=BASE_URL, api_key=os.environ["REVIEW_API_KEY"])
    resp = client.chat.completions.create(
        model=MODEL,
        temperature=0.2,
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": context},
        ],
    )
    return parse_opinions(resp.choices[0].message.content or "")


def main() -> None:
    if len(sys.argv) < 3:
        print("用法：python review_agent.py <diff文件路径> <仓库根目录>")
        sys.exit(1)
    diff_text = read_diff(sys.argv[1])
    names = changed_files(diff_text)
    full_files = read_full_files(names, Path(sys.argv[2]))
    context = assemble(diff_text, full_files, MAX_CONTEXT_CHARS)
    for op in request_review(context):
        level = op.get("level", 0)
        confidence = op.get("confidence", 0)
        if level >= MIN_LEVEL and confidence >= MIN_CONFIDENCE:
            print(f"[{LEVELS.get(level, '?')}] {op.get('file')}:{op.get('line')} {op.get('title')}")
            print(f"  {op.get('detail')}\n")


if __name__ == "__main__":
    main()

几点实现说明：

• MAX_CONTEXT_CHARS 是显式预算：diff 全量保留，剩余额度分给全文件，截断行为全部留痕，方便事后审计"模型当时看到了什么"；
• MIN_LEVEL 与 MIN_CONFIDENCE 构成输出的第一道过滤：nit 一律不出现在 PR 里，低置信度意见直接丢弃，这是把误报挡在门外的第一道闸；
• 模型输出严格要求 JSON，解析失败就放弃本轮意见并告警，绝不让半截 JSON 变成 PR 评论里的乱码；
• REVIEW_API_KEY 未配置时脚本直接报错退出，这是故意的失败设计：缺密钥就停，而不是带着空凭证继续跑。

对照 OpenCodeReview 的开源路线：脚本里的"读全文件"对应它读全文件的能力，"代码库检索"对应它检索代码库的能力，"结构化深度意见"对应它的深度评审产出。自部署时，把仓库检索与规则沉淀两块补齐，就能得到一条与开源方案同构的评审闭环；而评审调用的出口收敛到自有中转，配额、审计与成本归集都只看一处，密钥不必散落在各个脚本里。

八、误报治理：让意见重新被认真对待

上线后的前两周，工作重心基本都在治理误报。手段就四条：

1. 意见分级：nit 永远不进通知，suggestion 折叠展示，只有 blocker 打标提醒。通知条数是稀缺资源，要花在刀刃上；
2. 置信度阈值：低于阈值的意见直接丢弃。阈值从保守值起步，观察一两周采纳率后再逐步放宽，宁可起步阶段漏报，也不要开局就把信任烧完；
3. 反馈回流：人工标记的误报不能只是被顺手删掉——要么沉淀成确定性检查规则，让同类问题从此不进模型；要么作为反例进入评审 prompt 的示例区，让模型在后续轮次里有现成的对照；
4. 指标监控：每周看采纳率与误报率两条曲线。采纳率连续两周下滑，就是阈值或 prompt 该调整的信号；两条曲线一起恶化，就该停下来复盘，而不是继续放量。

误报治理的本质，是把模型的不确定性关进分级与阈值的笼子里。笼子没建好就放量上线，评审 Agent 的死法基本只有一种：被当作噪音插件静音，此后所有投入归零。

九、评审 Agent 上线自查清单

放量前逐项过一遍：

• [ ] 确定性检查前置：lint、类型检查与测试先跑，模型只负责规则之外的评审；
• [ ] 上下文窗口预算：字符预算显式声明，截断有日志，能追溯模型漏看了哪个文件；
• [ ] 意见分级与阈值：三级分级上线，nit 不进通知，置信度阈值可配置、可回滚；
• [ ] 误报率监控：采纳率与误报率按周出曲线，恶化时有告警；
• [ ] 密钥与脱敏：API key 只在环境变量与密钥管理服务里流转，代码送外部接口前有敏感信息扫描；
• [ ] 审计留存：每次调用的模型名、输入摘要、意见列表与人工反馈都能按 PR 追溯；
• [ ] 失败降级：模型超时或解析失败时，评审退化为确定性检查结果，不阻塞合并流程；
• [ ] 权限最小化：评审服务对仓库只读，写操作仅限于发表评审意见本身。

十、成本对比：三种评审模式的估算账

以下数字为工程估算口径，用于说明结构性差异，实际值随模型价格与 PR 规模变化：

三个结构性结论：

• 分层方案比全量 LLM 方案更省 token：大部分变更被确定性检查直接消化，只有剩余部分进模型，同样一笔预算能覆盖更多 PR；
• 人工分钟数不会降到零，也不应该降到零——模型意见与最终合并之间，永远隔着一次人工确认，这段时间买的是质量责任的归属；
• 成本闭环的核心变量是误报率：误报每降一档，人工复核时间随之下降，同一笔 token 花费换回的信任更多。"降本闭环"的完整含义不是模型便宜，而是"误报下降—人工时间下降—愿意扩大覆盖—单位成本再下降"这个正循环。

十一、风险与合规提示

• 评审意见不等于验收：Agent 意见只是参考输入，合并门禁仍以测试与人工确认为准，不要把合并按钮交给模型。自动化越顺手的环节，越要守住"人签字"这条线；
• 代码出域的合规边界：代码送外部接口前先过敏感信息扫描，密钥、凭证与业务敏感信息一律脱敏；对信息边界有硬性要求的团队，走自有中转统一留存审计日志，更敏感的仓库考虑私有化部署评审模型，让代码不出内网；
• 模型切换的意见漂移：升级或更换模型时，同一份 diff 的意见风格会变。切换前后用固定样本回归一遍，确认 blocker 的召回没有塌方再放量；
• 误报疲劳：最容易被低估的失效模式。意见被静音的那一天起，整套评审投入等于归零，而且信任很难二次建立。

十二、总结

把整条链路收拢一遍：确定性预检拦下机器能判对的事，上下文组装用全文件与代码库检索把模型喂饱，分层评审输出带级别与置信度的结构化意见，误报治理用分级、阈值与反馈回流把信任一点点攒回来，成本上以"确定性为主、模型为辅"的结构拿到一个可以长期运行的账。OpenCodeReview 把内部评审助手开源出来，读全文件、检索代码库、深度评审这条路线值得直接借力；自部署时把调用出口收敛到自有中转，审计与配额都省心——我在搭这类系统时用的入口一直是 4sapi（https://4sapi.com），密钥、日志与模型切换集中在一处管理。评审 Agent 不替代人，它替代的是"没人看"。

评审 Agent 落地时的取舍，或者误报治理里踩过的坑，欢迎在评论区聊聊。