嵌入 ocra

在你自己的程序里用 @open-cr-agent/core 的 review() 运行审查流水线。

ocra 命令只是 @open-cr-agent/core 里 review() 的一个调用方;你的机器人、CI 步骤或定时审查服务也可以调用它,阶段、信任规则、花费上限和报告都一样。

一次完整的调用

import {
  correctnessReviewerPlugin,
  isBlocking,
  isIncompleteReview,
  review,
  securityReviewerPlugin,
  sessionJsonlPlugin,
  startPlugins,
  toReportOutput,
} from "@open-cr-agent/core";
import { opencodeRuntimePlugin } from "@open-cr-agent/runtime-opencode";
import { localGitPlugin } from "@open-cr-agent/vcs-local";

// 1. 插件注册适配器、运行时、审查员、规则、工具和事件监听。
const registry = await startPlugins(
  [localGitPlugin, opencodeRuntimePlugin, correctnessReviewerPlugin, securityReviewerPlugin, sessionJsonlPlugin],
  {
    env: process.env,
    settings: { "session-jsonl": { dir: ".ocra/sessions", id: "my-run" } },
    warn: (message) => console.warn(message),
  },
);

// 2. 改动从哪里来,agent 由什么运行。
const vcs = registry.createVcs("local", {
  cwd: process.cwd(),
  target: { mode: "range", from: "main", to: "HEAD" },
});
const runtime = registry.createRuntime("opencode", {
  models: {
    top: ["google/gemini-3.1-pro-preview"],
    standard: ["google/gemini-3.5-flash", "google/gemini-flash-lite-latest"],
    light: ["google/gemini-flash-lite-latest"],
  },
  env: process.env,
});

// 3. 审查。
try {
  const report = await review({
    vcs,
    runtime,
    reviewers: registry.reviewers,
    rules: registry.rules,
    limits: { maxCostUsd: 2 },
    onEvent: (event) => registry.emit(event),
  });
  console.log(JSON.stringify(toReportOutput(report)));
  if (isIncompleteReview(report)) process.exitCode = 3;
  else if (isBlocking(report)) process.exitCode = 1;
} finally {
  await runtime.dispose?.();
}

startPlugins 执行插件的生命周期(插件)并返回一个冻结的注册表;createVcs 和 createRuntime 按名字构造已注册的适配器和运行时;registry.emit 把事件交给监听者(这里是会话日志)。这些就是 CLI 用的插件;.ocra/config.json 是 CLI 的便利功能,不属于库。

review() 接受什么

下面这些 ReviewOptions 字段是遵循 0.x 规则的约定:次版本可能改变它们,变更日志会说明如何适配。

选项含义
vcs这次改动的 VcsAdapter:diff 和文件从哪里来,publish 把审查发到哪里
runtime每次运行一个隔离审查任务的 AgentRuntime
reviewers要运行的审查员(默认只有 correctness);可以用注册表里的,也可以是你自己的 ReviewerDefinition
reviewerOverrides按审查员设置 enabled、minTier,以及它自己的 effort 和 models 模型链(按 agent 指定模型)
roles按角色(verifier、judge、helper)设置它自己的 effort 和 models 模型链
effort按模型层级设置的推理强度(推理强度)
models运行时拿到的层级模型链(运行时通过 RuntimeOptions.models 接收),让 provenance.agents 能记录每个 agent 的模型链
rules按路径生效的规则,注册表里的加上你自己的(SourcedRule[]:带可选来源 source 的 RepoRule,取值 repository、shared、account 或 plugin);provenance.rules 会列出它们,.ocra/rules.json 的记为 repository
readTrusted从哪里读取 AGENTS.md、.ocra/rules.json 和 .ocra/memory.json,默认是被审查的版本。审查 PR 时传入读取可信 base 的函数
selection审查哪些文件:include、exclude、maxPatchChars(200,000);没给的字段保持默认值
limits.concurrency、limits.taskTimeoutMs、limits.runTimeoutMs并行任务数(4)、单个任务的超时(10 分钟)和整次运行的超时(25 分钟);超过 2^31 - 1 毫秒(约 24.8 天)的超时(包括 Infinity)会被截到这个值。并行任务数不是不小于 1 的整数、超时不是正数时,review() 在开始前以 CONFIG_INVALID 拒绝
stages.verify、stages.judge对照 diff 核查问题,以及跨审查员合并、过滤和重新定级(默认都开启)
limits.maxCostUsd、limits.maxTasks花费上限(--max-cost-usd)和任务数上限;负数或 NaN 的上限、不是整数的任务数上限以 CONFIG_INVALID 拒绝
mode.full即使平台报告了上次审查以来的改动,也审查所有文件
mode.ultra以成本换召回率(模式)
sarif解析好的 SARIF 日志(parseSarifLog),其中落在改动上的结果加入审查(SARIF 输入)
signal一个 AbortSignal:运行会停下,保留已发现的问题并写出部分报告
onEvent在运行过程中接收每个 ReviewEvent
identity.runId在报告、事件和发布的内容里标识这次运行;不传则自动生成。CLI 传入它的会话 id
identity.provenance{ ocraVersion, configHash, sampling?, accountSettings? }:传入后,报告的 provenance 会加上系统提示词的哈希和实际应用的采样设置(sampling 是你要求的设置;stableHash() 可以给你的配置算哈希)
resume一个 ResumedRun:早先一次运行的 id、分组和已完成的任务(每个带它的键和它报告的问题),即该运行会话里 task_reported 和 task_finished 事件给出的内容。键相同的任务直接复用,不产生花费,它的结果带 reusedFrom。CLI 的 --resume 从会话读取它,且只读取用本机密钥封存过的行(session-jsonl 的可选设置 sealKey,64 位十六进制,用来封存它写下的每一行)。键包含基准提交和头部提交,以及 identity.provenance 里的版本和采样设置;不传后两者时,其他 ocra 版本或采样设置下的任务也可能被复用。复用的任务不产生花费,所以在检查花费上限之前就会被取用

它返回什么

一个 ReviewReport,内容与 JSON 报告相同。

  • 对外发布的是 toReportOutput(report),不是报告本身:它是 CLI 写出的带版本号的 JSON,类型为 ReportOutput,由 reportOutputSchema(类型即由它推导)和 JSON Schema 校验。内部报告的字段可能会变。
  • 不完整的审查不算通过。 审查留下了没审完的选中文件,或有没人能核查的 critical 时,isIncompleteReview(report) 为真,这正是 CLI 以 3 退出的情形;结论让运行失败(退出码 1)时,即 significant_concerns 且没人推翻,isBlocking(report) 为真。像 CLI 的退出码那样用它们做门禁,永远不要只看 verdict。要看细节:coverageGaps(report) 给出有多少选中的文件没被审查、是否什么都没审到,并在 incomplete 里按任务的结束方式(step_cap、stopped_early)给出只审查了一部分的文件数;report.unverifiedCriticals 是没人能核查的 critical 数量。

vcs.publish(report) 像 --publish 一样按平台的信任规则发布审查,没能发出去的部分以警告返回。

事件(onEvent)的形状不是约定:监听者应当容忍新的类型和字段。

错误

review() 只在运行无法开始时 reject:没有审查员、.ocra/rules.json 或 .ocra/memory.json 无效,或者 VCS 适配器读不到改动。此后,任务和辅助调用失败、配额用尽和触及花费上限都记录在报告里,而不是抛出。

ocra 的各个包抛出带 code 的 OcraError(或其子类):isOcraError(error, code?) 用来判断,OCRA_ERROR_CODES 列出全部代码,底层错误(JSON 解析错误、读取失败)是 cause。请按代码分支,不要按可能改写的消息。插件的适配器或运行时可能抛出其他错误;errorMessage(error) 能取出任何被抛出值的消息。

代码含义
CONFIG_INVALID无法使用的配置:选项、.ocra/config.json 及其 extends、.ocra/rules.json、.ocra/memory.json、模型名、没有审查员、某个档位没有模型
CONFIG_CREDENTIALS_MISSING运行需要的令牌或模型密钥没有设置
INPUT_USAGEocra 无法执行的命令行(CLI 的用法错误)
INPUT_INVALID交给 ocra 却无法读取的输入,例如 SARIF 日志或一组 commit id
ACCESS_DENIED访问策略拒绝了某个路径:密钥文件、git 内部文件、ocra 写入处的符号链接
PLUGIN_INVALID无法加载的插件、重复注册或在启动后注册,或者没有任何插件注册过的名字
VCS_GIT_FAILEDgit 命令失败
VCS_API_FAILEDGitHub 或 GitLab API 失败或返回了意外的内容;GitHubApiError 和 GitLabApiError 带有 HTTP status
VCS_REF_UNKNOWN仓库里没有、也无法拉取的 commit 或 ref
VCS_NOT_READY平台还没准备好这次改动,例如还没有 diff 的 Merge Request;稍后重试
CLOUD_API_FAILEDCLI 在 ocra login 或 ocra whoami 时无法连上 ocra Cloud,或者 ocra Cloud 返回了无法使用的内容
RUNTIME_START_FAILEDagent 运行时无法启动(没有 OpenCode 可执行文件、服务没有起来)
RUNTIME_FAILED一次模型调用在它链上的每个模型都失败了(CompletionError,带有这些尝试花掉的 usage)
RUNTIME_INVALID_OUTPUT模型的回答不符合预期的 schema
BUDGET_EXHAUSTED达到了花费上限(SpendLimitReached,即正在运行的任务被停止的原因)
INTERNAL不变量被破坏或对象被误用,例如一个 OpenCode 运行时被用于两次运行:ocra 或其调用方的 bug

供 instanceof 使用的子类:CompletionError、SpendLimitReached、AccessDeniedError、SarifError 和 PluginError(@open-cr-agent/core),GitError(@open-cr-agent/vcs-local),GitHubApiError 和 GitLabApiError(平台适配器)。错误消息里不会有令牌或模型密钥;两种运行时引用供应商回答前也会去掉它们。

这些代码是遵循 0.x 规则的约定:次版本可能新增代码,重命名或删除时变更日志会说明。以退出码 2 结束运行时,CLI 会打印错误代码,例如 ocra [CONFIG_INVALID]: .ocra/config.json is invalid: …。

PR 与 Merge Request

githubPlugin(@open-cr-agent/vcs-github)和 gitlabPlugin(@open-cr-agent/vcs-gitlab)注册 github 和 gitlab 适配器。

resolveGitHubTarget 和 resolveGitLabTarget 像 --pr 和 --mr 一样找到 PR 或 Merge Request。它们接收 ref(编号,以及你指定时的仓库或项目)、env(CLI 的令牌、仓库和 API 变量)、origin()(检出目录的 origin,只在需要时读取)、warn 和可选的 fetch,返回 base 和 head commit、拉取 head 的 refspec、变更请求的网页地址,以及 createVcs(registry, local, settings):commit 进入你的克隆后用它创建适配器,local 提供代码和历史,settings 是 GitHubSettings(botLogin、requestChanges)或 GitLabSettings(暂无设置)。拉取 commit、从 base 读取配置、指南和规则(readTrusted)由你负责,做法见 packages/cli/src/commands/review/target.ts。适配器自己的 createVcs 选项不是约定,请通过这两个函数使用。

信任

你的程序就是信任边界。只加载你信任的插件,绝不加载被审查的代码树指定的插件;模型密钥通过 env 传入,运行时只转发配置的供应商需要的部分(安全);审查 PR 时通过 readTrusted 从 base 读取指南、规则和 memory。无论谁调用 review(),agent 都只有只读工具,没有 shell。

公开 API

每个包的主入口就是它的公开 API,是一份遵循 0.x 规则的约定:

  • @open-cr-agent/core:review() 和 ReviewOptions;它返回的内容(ReviewReport、Finding 以及组成它们的类型)、coverageGaps()、isIncompleteReview()、isBlocking()、toReportOutput() 及 ReportOutput、reportOutputSchema、reportJsonSchema() 和 REPORT_VERSION;parseSarifLog();插件接口(OcraPlugin 及其上下文、startPlugins()、PluginRegistry、内置的审查者插件和 sessionJsonlPlugin);插件实现的约定(VcsAdapter、AgentRuntime 及它们用到的类型、ToolDefinition、ReviewerDefinition、RepoRule);运行时可以基于的部分(ChainRunner 及 ModelAttempts、AttemptOutcome、QuotaError,审查工具、步数上限以及插件列出的其他辅助内容);以及错误模型。
  • @open-cr-agent/vcs-local:localGitPlugin、LocalTarget、LocalGitOptions 和 GitError。vcs-github 和 vcs-gitlab:githubPlugin 和 gitlabPlugin,resolveGitHubTarget 和 resolveGitLabTarget 及 GitHubSettings 和 GitLabSettings,以及它们的 API 错误。runtime-opencode 和 runtime-direct:opencodeRuntimePlugin 和 directRuntimePlugin。
  • @open-cr-agent/cli:run(argv),即带参数(不含 node 和脚本路径)运行 ocra 命令,输出写到 stdout 和 stderr,返回值是退出码。
  • @open-cr-agent/vcs-platform 是 ocra 各平台适配器共用的部分,还不是约定。

每个名字和类型的形状都在该包位于 etc/ 的 API 报告里;入口变了而报告没变时,CI 会失败。

/internal 入口(@open-cr-agent/core/internal 等)供 ocra 各包之间共用,不是约定:任何版本(包括补丁版本)都可能修改它们。请只依赖主入口。

在 GitHub 上编辑

本页目录