稳定性与支持
哪些部分可以依赖、会怎样变化,以及如何校验一个发布版本。
ocra 目前是早期的 0.x 版本。本页列出脚本、CI 和插件可以依赖的约定、它们可能怎样变化,以及能得到什么支持。
版本
ocra 遵循 1.0 之前适用的语义化版本:
- 补丁版本(0.1.x)只修复问题,从不改变约定;唯一的例外是不改就无法修复的安全问题,这时发布说明会写明。
- 次版本(0.x.0)可能改变约定,并列在变更日志里。能做到时,旧写法会带着警告至少再保留一个次版本,之后才移除。
所有包共用同一个版本号,一起发布。
下文的“0.x 规则”指:次版本可能改变它,变更日志会说明如何适配。
约定
| 约定 | 说明在哪里 |
|---|---|
| 命令、选项和退出码 | CLI 参考 |
.ocra/config.json、.ocra/rules.json、.ocra/memory.json 和 OCRA_* 环境变量 | 配置、审查规则 |
JSON 报告(--format json、report.json)和 --plan 的 JSON | CLI 参考。两者都带 "version": 1;同一版本只会增加可选字段和取值集合里的新值,其他改动都会换新版本。JSON Schema:报告、plan。plan 的契约是这个 JSON Schema 文件,没有哪个包导出它的 schema |
SARIF 输出(--format sarif) | CLI 参考。SARIF 2.1.0;规则 id、ocra/v1 指纹键和属性名都包括在内 |
| GitHub Action 的输入 | GitHub Pull Request |
| ocra 保存在 PR 总结评论里的状态 | 内部格式(目前是 v1),但之后的版本会继续读取。万一读不了,下一次审查从头开始:审查所有文件,评论可能重复 |
插件接口(OcraPlugin) | 插件;0.x 规则 |
库的入口:review() 和嵌入页列出的 ReviewOptions 字段、startPlugins()、注册表的 createVcs、createRuntime、reviewers、rules 和 emit、toReportOutput()、coverageGaps()、isIncompleteReview()、isBlocking() 和 parseSarifLog() | 嵌入 ocra;0.x 规则 |
每个包的主入口:@open-cr-agent/core、各适配器和运行时导出的内容 | 嵌入 ocra 和 etc/ 中每个包的 API 报告;0.x 规则。/internal 入口和 @open-cr-agent/vcs-platform 不是约定 |
错误模型:OcraError、它的 code 取值、isOcraError(),以及 review() 抛出什么 | 嵌入 ocra;0.x 规则(可能新增代码;重命名和删除见变更日志)。错误消息不是约定 |
不属于约定的:文本输出、错误消息、进度行和 PR 评论的措辞;会话事件(events.jsonl);提示词;模型报告哪些问题;费用。请解析 JSON 报告,而不是文本。
支持
- 修复(包括安全修复)只进入最新版本,不回移。报告漏洞见 SECURITY.md。
- Node.js 22.19 或更新(
engines)。CI 在 Linux 上用 Node.js 22 跑测试,并在 Linux、macOS 和 Windows 上安装并启动 Action。 - Git:用 GitHub 托管 runner 上的版本测试过;目前没有最低版本要求。
- 只有一位维护者;issue 和 PR 尽力回复,没有付费支持。
校验发布版本
发布由本仓库的发布 workflow 通过 npm trusted publishing 完成;禁止用 token 发布,手动发布需要维护者的第二重验证。从 0.1.1 起,每个包都带有 provenance,把它和本仓库、该 workflow 以及打了标签的 commit 绑定。检查你装的是什么:
npm audit signatures --include-attestations容器镜像同样带有构建 provenance:gh attestation verify oci://ghcr.io/jma49/ocra:<版本> --repo jma49/Open-CR-Agent。
GitHub Action 安装已发布的 CLI 及测试过的依赖版本,校验签名和 ocra 的 provenance;版本不在 npm 上或缺少 provenance 时从源码构建(GitHub Pull Request)。