企业官网建设流程全解析

如何选对 open-code-review 的 --format 与 --audience：输出形式完全指南

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review

open-code-review（ocr）是阿里巴巴开源的 AI 代码评审工具，混合架构（确定性流水线 + LLM Agent）在阿里规模下经过实战检验。跑一次ocr review之后，评审结果以什么形式输出，直接决定了它是给人看的、还是给脚本和 CI 流水线消费的。本文用最短的路径讲清两个关键参数——--format和--audience的作用、区别与组合方式，帮你一次选对输出形式。

📖 完整参数说明可查阅官方中文文档：cli-reference.md

一张表看懂：--format 与 --audience 各管什么

一个最易踩的坑先说在前面：--audience agent并不隐含--format json。两者控制的是不同的事——前者管"屏蔽 UI"，后者管"结构化载荷"。需要 JSON 时请显式加上--format json。

三种 --format 输出形式详解

1. text：人类可读（默认）

默认形式。评审运行时流式打印进度行（文件读取、code_search、Plan 完成等），随后每条评论一个分块：

ocr review --commit abc123

─── src/foo.go:42-47 ─── Concurrent map access without a lock — wrap with sync.RWMutex. - m[k] = v + mu.Lock(); defer mu.Unlock(); m[k] = v

结尾附一份摘要：评审文件数、评论数、token 用量与耗时。适合自己在终端里跑评审。

2. json：机器可读

ocr review --format json > result.json # 进度仍显示在终端上 ocr review --format json | jq .summary # stdout 是单个 JSON 文档

JSON 文档始终独占 stdout，顶层字段包括status、llm、summary、comments（含path、start_line、end_line、suggestion_code）、可选的warnings与session_id（可用于--resume恢复中断的评审）。这是写脚本、做自动化、接入其他工具时的首选形式。

3. sarif：接入平台代码扫描

ocr review --format sarif > report.sarif

输出 SARIF 2.1.0 报告，专为 GitHub Code Scanning 等平台代码扫描入口设计。注意两点：

• --preview与--format sarif不能同时使用（预览没有已完成的发现可供输出）；
• delegate 模式仅支持text与json。

实现见 sarif.go。

两种 --audience：human 还是 agent？

• human（默认）：流式打印进度行。当--format为json或sarif时，进度行会自动改道 stderr，保证 stdout 是一份干净的、可被解析器直接消费的结构化文档——这解决了"边看进度边管道解析"的经典冲突。
• agent：完全抑制所有进度行，只输出最终摘要 / 结果文档。适合 CI / 流水线中把结果交给另一个 agent 消费的场景。

底层逻辑非常清晰：--audience agent时进度直接丢弃；human+ 结构化格式时进度重定向到 stderr。参见 shared.go 中的newQuietHandle实现。

快速决策清单：怎么选？

几个实用提示 💡

• 退出码：0表示评审完成（可能零评论、可能带警告）；1表示致命错误（参数错误、端点无法解析等），错误文本打印到 stderr——CI 里直接用它判断成败。
• 区分"无变更"与"无发现"：没有可评审文件时，JSON 模式会输出status: "skipped"的空外壳，调用方据此区分两种情况。
• 重试报告：想看每次尝试的细节，用--format json（retry_report字段）。
• delegate 模式：--format只接受text或json，不支持sarif。
• 传了非法值会直接报错并提示合法取值，如invalid --audience value "robot": must be 'human' or 'agent'。

相关源码与文档

• 参数定义与校验：shared_flags.go
• 进度静默/重定向机制：shared.go
• SARIF 生成：sarif.go
• 结果渲染与重试报告：output.go
• 完整 CLI 参考（中文）：cli-reference.md

一句话总结：--format决定"输出长什么样"，--audience决定"过程显不显示"。本地看结果用默认组合，脚本消费加--format json，流水线静默再加--audience agent，接代码扫描用--format sarif。

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review