插件

用插件为 ocra 扩展代码托管平台、运行时、审查员、规则、工具和事件监听。

ocra 自己的适配器、运行时、审查员和会话记录都是内置插件;你写的插件使用同一套接口。

编写插件

插件是一个模块,以 default(或 plugin)导出一个对象:

// tools/ocra-team-rules.mjs
export default {
  name: "team-rules",
  configure(ctx) {
    ctx.registerRules([
      {
        path: "services/**",
        rule: `Owned by ${ctx.settings.team}: check idempotency keys on every write.`,
      },
    ]);
  },
};

在 .ocra/config.json 里注册:

{
  "plugins": ["./tools/ocra-team-rules.mjs"],
  "pluginSettings": { "team-rules": { "team": "payments" } }
}

插件从仓库的依赖(按包名)或相对仓库根目录的路径(可以指向仓库之外)解析。包按 import 的方式解析,因此 exports 只为 import 指定入口的包也能加载;只指定 require 入口的包则退回到该入口。插件会执行代码,所以只在本地审查时加载;审查 PR 或 Merge Request、或使用 --no-repo-config 时都不加载。

来自 ocra Cloud 账户的插件

登录后,你的 ocra Cloud 设置可以按 npm 包名列出插件及其 pluginSettings。账户只能列出名字:只有你在某台机器上用 ocra plugins allow 允许后,插件才会在这台机器上加载。

ocra plugins allow ocra-plugin-team-rules@1.4.0   # 显示这个包及其发布者,然后安装
ocra plugins list
ocra plugins deny ocra-plugin-team-rules

allow 只接受精确版本,不接受范围或标签。它显示 registry 中的名称、版本、发布者、维护者和 integrity,在关闭安装脚本的情况下安装(细节见 ocra plugins),并把名称、版本和 integrity 记录在 plugins.json 中(只有你可读)。npm 在该目录中运行,所以你项目的 npm 配置不生效;没有列出 integrity 的包会被拒绝。integrity 只覆盖包本身的 tarball,不覆盖依赖,依赖由 npm 在安装时解析。允许一个插件是供应链决定,就像添加一个依赖。

审查只在以下条件下加载账户列出的插件:

  • 这台机器允许了它:只从上述目录加载,从不从被审查代码的 node_modules 加载,并且已安装的包仍然是允许时记录的版本和 integrity;
  • 仓库的插件也能加载的场合:本地审查;--pr、--mr 和 --no-repo-config 时从不加载。

这台机器没有允许的账户插件会被跳过,并给出一条警告,写明 ocra plugins allow <name>@<version>。仓库已经列出的按仓库的插件加载;插件名已被占用的被跳过;加载失败的被跳过并给出警告,不会让审查失败。

账户的 pluginSettings 按 npm 包名对应(@acme/ocra-team-rules,而不是它导出的插件名 team-rules),只作用于账户列出且已加载的插件,插件按自己的插件名收到它们。配置的 pluginSettings 优先,仓库插件的设置只来自仓库。

生命周期

阶段执行方式失败时
bootstrap(ctx)所有插件并发执行只打印警告,审查继续
configure(ctx)按加载顺序执行审查停止,并指出是哪个插件
postConfigure(ctx)所有注册完成后并发执行审查停止

bootstrap 适合做失败了也无妨的事,比如拉取远程设置。

插件可以注册什么

方法提供的能力
registerVcs(name, factory)代码托管平台适配器,仅用于嵌入:ocra 命令只审查本地 git、GitHub 和 GitLab,不会按名字选用插件注册的适配器
registerRuntime(name, factory)agent 运行时
registerReviewer(definition)有自己提示词和模型层级的审查员
registerRules(rules)按路径生效的审查规则
registerTool(tool)审查员可以调用的工具,输入用 Zod schema 定义
onEvent(listener)审查过程中每个事件的监听器(遥测、通知)。监听器抛出异常时会被停用,并给出一次警告,审查继续进行

每个插件只能拿到自己的设置(ctx.settings),并由可选的 settingsSchema 校验。同一个名字重复注册、使用保留的工具名,或在 configure 之后再注册,都会报错并指出是哪个插件。

编写运行时

  • 工厂输入: 模型链、环境变量、声明的供应商,配置了的话还有 sampling(temperature、seed),以及 agentModels:按 agent id 列出每个 agent 自己的模型链,供需要在第一次调用前准备供应商的运行时使用。这样的 agent 也会在任务 spec 和补全请求的 models 中带上它;两者都忽略的运行时使用层级的模型链。
  • 采样: 运行时的 sampling 属性说明它实际发送什么,notApplied 列出没法传下去的设置;没有这个属性的运行时报告为一项都没应用。
  • 推理强度: 任务 spec 带有审查员要求的推理强度 effort;补全请求带有 agent(计划调用对应的审查员,或 verifier、judge、helper)和 effort;没有配置时两者都不存在。发送推理强度的运行时实现 appliedTo(agent):这个 agent 的每次调用是否都发送了它,unsupported 列出不接受该级别的模型(每个 agent 警告一次),unsentBecause 说明因其他原因无法发送任何级别时的原因(警告里会给出),notApplied 列出没发送的采样设置。没有实现它的运行时报告为不发送推理强度,并警告一次。@open-cr-agent/core 的 effortCapability(model) 给出 ocra 关于模型参数形式和级别的表。
  • 故障切换: @open-cr-agent/core 的 ChainRunner 可以实现 runTask 和 complete,两个内置运行时都是这样。它为每次调用选择模型链(agent 自己的,否则是层级的),对没有模型的层级给出 CONFIG_INVALID,在整次运行中记录每个模型的健康状况(短时限流会等待,配额用尽的模型不再使用,熔断器),并在一次尝试失败时换下一个模型。你提供 ModelAttempts:task 和 complete 在一个模型上执行一次尝试,返回 AttemptOutcome(发现、步数、工具调用、文本、用量,以及说明换模型是否可能成功的 error,带 QuotaError 时说明要等多久;被中止信号打断的尝试要返回 error,因为没有 error 的结果算作已完成);可选的 refuse 在任何请求之前说明一条链为什么无法使用,可选的 ready 启动尝试需要的东西。每个运行时实例创建一个 runner,健康状况才能覆盖整次运行。
  • 辅助工具,都在 @open-cr-agent/core 中,让你的运行时按内置运行时的方式审查:reviewTools,和 RuntimeOptions.tools 一起提供给 agent 的只读审查工具,以及 REVIEW_TOOLS,它们的名字(一次尝试的发现就是 agent 传给 report_finding 的内容;task_done 结束尝试);MAX_AGENT_STEPS,每次审查尝试的模型请求上限;RESUME_MESSAGE,agent 在还有步数、没有回答也没有调用 task_done 时停下,会收到一次这条消息;parseModel(model),拆分 provider/model,其他写法抛出 CONFIG_INVALID;parseQuotaError(message, status?),把供应商的限流或配额错误读成 QuotaError;withoutSecrets(text, secrets),在引用供应商的错误之前去掉其中的密钥;emptyUsage() 和 addUsage();EFFORT_LEVELS 和 thinkingBudget(capability, level, outputLimit?),ocra 为某个级别推算的思考预算;以及 proxiedFetch(env),按给定环境中的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 走代理的 fetch。

安全

插件会执行代码,只从你信任的仓库加载插件,并且只在确认发布者之后才允许账户列出的插件;审查别人的分支时,请使用 ocra review --no-repo-config,它会忽略仓库的配置和插件。在 CI 中,配置应当从受保护的 base 分支读取,绝不能从被审查的 PR 里读取。

在 GitHub 上编辑

本页目录