插件
用插件为 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-rulesallow 只接受精确版本,不接受范围或标签。它显示 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 里读取。