CLI 参考

命令、参数、输出与退出码。

ocra init

为当前所在的仓库写入 .ocra/config.json(加 --github 时再写入 .github/workflows/ocra.yml),然后打印剩下要做的事。它不调用任何模型或网络服务,不会运行 gh,运行 git 也只是为了找到仓库根目录(git rev-parse --show-toplevel)。

ocra init                          # 按环境里的 key 写 .ocra/config.json
ocra init --github                 # 同时写 GitHub workflow,可安全审查来自 fork 的 PR
ocra init --github --same-repo-only
ocra init --provider anthropic     # 当前 shell 里没有这个供应商的 key 时指定它
参数含义
--github同时写入 .github/workflows/ocra.yml,即 pull_request_target 上的fork 方案:成员和协作者的 PR 每次推送都审查,其他人的 PR 在维护者每次加上 ocra-review 标签时审查;只检出 base 分支,不运行 PR 里的任何东西
--same-repo-only与 --github 一起用,改写普通的 pull_request workflow。它跳过来自 fork 的 PR,它们在那里拿不到 secret
--provider <name>gemini、anthropic、openai 或 openrouter,代替从环境里找到的 key
--force替换已有文件。不加时保留已有文件,并说明保留了

模型。 不加 --provider 时,ocra init 依次查找 GEMINI_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY、OPENROUTER_API_KEY,用第一个已设置的,并列出找到的其他 key;只有没有其他 key 时才选 OpenRouter。它为每一档写一个模型:

供应商topstandardlight运行时
geminigoogle/gemini-3.1-pro-previewgoogle/gemini-3.5-flashgoogle/gemini-flash-lite-latestopencode
anthropicanthropic/claude-opus-5-5anthropic/claude-sonnet-5-5anthropic/claude-haiku-4-5opencode
openaiopenai/gpt-6-solopenai/gpt-6-solopenai/gpt-6-lunaopencode
openrouterrouter/openrouter/free,OpenRouter 在其免费模型之间挑选的路由同左同左direct

对 OpenRouter,它会提示:质量不稳定,免费模型不适合私有代码,账号没有充值时大的审查可能用完每日请求数。

运行时。 只有在 direct 运行时上真实测试过的 OpenRouter 会配置成 direct:配置设置 "runtime": "direct",以价格 0 声明端点,workflow 传 opencode: false,ocra 安装约 11 MB 而不是 175 MB。其他供应商仍用默认运行时 opencode,配置里写的是 OpenCode 目录中的模型,价格由 OpenCode 自己计算;ocra init 会链接到选择运行时。--github 保留了一个没有设置 direct 的已有配置时,workflow 会安装 OpenCode。

以 Gemini 为例,写出的文件是:

{
  "$schema": "https://raw.githubusercontent.com/jma49/Open-CR-Agent/main/docs/schema/config.v1.json",
  "models": {
    "top": "google/gemini-3.1-pro-preview",
    "standard": "google/gemini-3.5-flash",
    "light": "google/gemini-flash-lite-latest"
  }
}

key 本身从不写入文件;OpenCode 从 GEMINI_API_KEY 读取它。模型可以像其他配置一样修改。

workflow 就是 GitHub 页面里的方案:key 作为 secret,每次审查 --max-cost-usd 2,direct 运行时下加 opencode: false,Action 固定到本发布版本的提交(actions/checkout 也按提交固定)。ocra init --github 随后打印:

Wrote .ocra/config.json: Gemini models through GEMINI_API_KEY, on the OpenCode runtime.
  OpenCode makes the install about 175 MB; to switch to the 11 MB direct runtime later, see https://github.com/jma49/Open-CR-Agent/blob/main/docs/manual/en/providers.mdx#choosing-the-runtime
Wrote .github/workflows/ocra.yml: pull requests from members are reviewed on every push, anyone else's once each time a maintainer adds the ocra-review label.

Next:
  1. Store the key as a repository secret (gh asks for its value):
       gh secret set GEMINI_API_KEY
  2. Create the label that starts a review of an outside pull request:
       gh label create ocra-review --description "Review this pull request with ocra"
  3. Commit .ocra/config.json and .github/workflows/ocra.yml, and merge them into the default branch:
       ocra reads its configuration from a pull request's base branch.

私有仓库请按 workflow 里的注释删掉 persist-credentials: false。在任何子目录运行,ocra init 都写到仓库根目录,且从不经由符号链接写入。不在 Git 仓库里,或没找到 key 又没给 --provider 时,它以退出码 2 结束,什么也不写。

ocra review

审查当前 Git 仓库里的代码改动。

ocra review [options]
参数含义
(不带参数)审查未提交的改动:已暂存、未暂存和未跟踪的文件
--from <ref>审查 --to 从 <ref> 分叉以来的改动(基于 merge base)
--to <ref>区间终点,默认 HEAD,必须配合 --from 使用
--commit <sha>审查单个 commit 相对其父 commit 的改动
--format text|json|sarif输出格式,默认 text。sarif 输出 SARIF 2.1.0
--output <file>把结果写入文件,而不是输出到 stdout。文件整体替换;如果该路径本身,或仓库内途经的某个目录,是符号链接,则拒绝写入(退出码 2,在调用任何模型之前);已存在但不是普通文件的路径同样拒绝。因此 /dev/stdout、命名管道和进程替换(>(…))都不可用:要输出到 stdout,不加 --output 即可
--pr <number>审查一个 GitHub PR,见 GitHub Pull Request
--repo <owner/name>--pr 所在的仓库(默认取 GITHUB_REPOSITORY 或 origin)
--mr <iid>审查一个 GitLab Merge Request,见 GitLab Merge Request
--project <id|路径>--mr 所在的项目(默认取 CI_PROJECT_ID 或 origin)
--publish配合 --pr 或 --mr:把评审发布到 PR 或 Merge Request
--full配合 --pr 或 --mr:审查所有文件,而不是只审查上次评审之后改动过的文件
--max-cost-usd <n>本次运行的花费上限。达到 80% 时仍在运行的审查任务停止,已找到的问题保留;这些任务的文件算作未审查(退出码 3),已经审完的任务除外。剩下的部分留给核查和裁决;再用完时,剩余问题标为未核查,不会拦下改动。任务大约每 10 秒报告一次花费,所以每个任务最多超出这段时间的花费加上正在进行的一步。任务按分组逐个运行,所以受限的运行会审完一部分文件;使用 --pr 时,下一次审查接着审剩下的
--plan免费,不调用模型:显示会审查和排除的文件、分组、审查任务和每个首轮提示词的大小(含 --ultra 下或 5 个文件以上的分组所做的规划调用)。任务的模型链已知时,按链上第一个模型的价格估算这些提示词的输入花费,逐个任务并给出总计:自行声明的供应商用声明的价格,价格为 0 或经由 ocra Cloud 时显示 input unpriced,其余显示 input price unknown。输出、后续轮次、核查和裁决不做估算。跳过 light 模型分组,所以较大的改动按每个文件一组显示(超过 20 个文件时按目录)。和 --pr 或 --mr 一起用时,按审查实际会覆盖的范围规划:能判断时只规划自上次审查以来改动的部分,和审查本身一样,并会说明(--full 则规划全部)。不写会话日志
--import-sarif <文件>把分析工具(Semgrep、CodeQL 等)的 SARIF 2.1.0 日志里的结果加入审查,可以重复使用。见 SARIF 输入。不能和 --plan 一起用
--ultra以成本换召回率,见模式
--reviewers <ids>只运行这些审查员,用逗号分隔(例如 security)
--temperature <n>采样温度,0 到 2;覆盖 sampling.temperature(配置)
--seed <n>采样种子,运行时和供应商支持时才生效(opencode 不支持);覆盖 sampling.seed
--resume <run-id>重试同一审查的一次早先运行,已经完成的部分不再付费:输入没变(同样的提交、配置、提示词、ocra 版本和采样)的已完成任务直接复用,只运行剩下的;失败的任务和中途被截断(部分审查)的任务会重新运行。读取会话 .ocra/sessions/<run-id>,且只读取本机 ocra 写下的内容:来自另一台机器或另一个用户的会话,或随改动一起带来的会话,都会被拒绝(退出码 2),会话里后加的行会被忽略并给出警告。不能复用的任务照常运行,并有一条警告说明数量。复用的任务不产生花费,所以花费上限不会把它们挡在外面;它们在 JSON 输出里带 reusedFrom,本次运行的 usage 只算本次实际花费。不能和 --plan 一起用
--config <文件>用这个配置文件代替 .ocra/config.json(与 --pr 或 --mr 一起用时代替 base 分支的那份);和 --no-repo-config 一起用也生效。见配置
--no-repo-config用于不信任的代码:忽略 .ocra/config.json 及其插件(与 --pr 一起用时,base 分支的也忽略);模型从 OCRA_MODEL_* 或 --config 读取;memory、rules 和 AGENTS.md 从 --from 所在的提交读取,否则不使用
-h, --help显示帮助

--commit 不能和 --from、--to 同时使用。

进度

进度输出到 stderr,所以用 --format json 时 stdout 上的内容仍可直接给程序解析:

[ocra] Reviewing: Working tree changes
[ocra] 4 file(s) selected, 1 excluded · risk tier: lite
[ocra] 2 bundle(s) (grouped)
[ocra] 2 review task(s)
[ocra] correctness-1 started: auth session handling (2 file(s))
[ocra] correctness-1 reviewing with google/gemini-3.5-flash
[ocra] correctness-1 google/gemini-3.5-flash: 3 step(s), 3 tool call(s) (read_file 2, task_done 1), 19558 in / 118 out / 0 reasoning tokens, $0.0062
[ocra] correctness-1 completed in 5.9s · 0 finding(s)

模型超过 30 秒没有新输出时,ocra 会打印 Model is thinking...。

退出码

退出码含义
0审查完成,结论为 approved、approved_with_comments 或 minor_issues
1结论为 significant_concerns:至少有一个经核查确认的 critical 问题(未经确认的只会得到 minor_issues 和 0)。结论只是参考意见,可能受被审查改动的影响,见工作原理。配合 --pr 时,维护者针对 head commit 的 /ocra override 会把它变成 0(GitHub)
2参数、Git 或配置错误,或者没有任何审查任务完成。错误行会写出错误代码,例如 ocra [VCS_REF_UNKNOWN]: Unknown commit: nope(代码列表)
3审查不完整:有选中的文件没有被审查(任务失败、超时、触及花费或任务数上限,或者没有审查员覆盖它),或只审查了一部分(审查员在调用完成工具之前用完了全部 30 步,或自己停了下来;提示信息会说明该怎么做),或者有 critical 没能核查。它优先于 1,CI 不会放行不完整的审查
130被 Ctrl-C 或 SIGTERM 中断;仍会打印部分报告,不会发布任何内容

JSON 输出

--format json 输出完整报告,格式与会话里的 report.json 相同:

  • 变更信息、风险档位、结论、总结;
  • 每个改动文件的覆盖情况:已审查、失败、未审查(没有启动任务)、不完整(任务没有调用完成工具就结束;ended 为 step_cap 或 stopped_early)、自上次评审后未改动,或被排除及原因;审查 PR 时,本次是增量还是全量及原因(scope);
  • 分组、各任务结果、被 Matrix 跳过的(审查员,分组)组合;
  • refuted(被核查丢弃的问题及原因)、unverifiedCriticals(核查没能检查的 critical 数量)、judgement(Judge 合并、丢弃或重新定级的记录);
  • 问题列表,以及 rereview:已修复、未再报告、未重新检查、未改动或已驳回的旧问题,记录了报告者时各带 reviewer;
  • remembered:被 memory 接受的问题,带来源 source(repository 表示 .ocra/memory.json,account 表示你的 ocra Cloud memory);维护者的放行在 changeRequest.override;
  • token 用量与花费;设置了花费上限时的 spendLimit(reached 为 review 表示审查任务因此停止,total 表示整个上限用完);警告信息。

这个格式是一份约定("version": 1):后续版本只会新增可选字段和取值集合里的新值,否则就会改版本号。遇到不认识的覆盖状态时,当作没有审查。

每条问题包含 fingerprint(多次运行间保持稳定;ocra memory add 接受它的前缀)、reviewer、category、severity、verification(confirmed、uncertain 或 unchecked)、file、lines({ start, end },没能对应到行时不存在)、inDiff、status(new,或之前报过时为 unfixed)、title、body、可选的 suggestion、可选的 fix({ startLine, endLine, replacement },作为可提交的建议给出;目前还没有审查员会产生它)、evidence、code(引用的代码)、--ultra 下的 lowConfidence,以及 provenance(它的 task,已知时还有 model)。tasks 里的每个任务带有 usage(token 和花费;一条问题的花费就是其任务的花费);没有调用完成工具就结束的任务还带有 ended:它的文件只算审查了一部分。

报告的 provenance 记录:

  • ocraVersion;
  • promptHash:这份配置会发出的系统提示词的哈希(审查员和辅助阶段的;从不包含改动);
  • configHash:实际生效的配置加上 --reviewers、--ultra 和 --max-cost-usd 的哈希;不含采样设置和密钥(key 只以变量名出现);
  • sampling:实际应用的 temperature 和 seed,notApplied 列出没能应用的;
  • agents:每个启用的审查员和 verifier、judge、helper 三个角色的 tier、models 中的模型链(自己的或所在层级的)、设置了时的推理强度 effort、applied(没有发出调用时不存在),以及 notApplied 的采样设置;
  • rules:每条路径规则的 path、rule 和 source(repository 表示 .ocra/rules.json,shared、account 或 plugin);
  • accountSettings:登录时所用账户设置的 version。

报告的 JSON Schema(draft 2020-12)由代码生成并经测试核对;@open-cr-agent/core 的 reportJsonSchema() 返回它。

--plan 的 JSON 同样带版本号,有自己的 JSON Schema:变更信息、风险档位、有上次审查时的 scope(incremental 带 since,或 full 带 reason,和报告中的一样)、选中和排除的文件、分组、各任务(估算的提示词大小、models、设置了时的 effort、模型链已知时的 inputCost:model 为链上第一个模型,status 为带 usd 的 priced、unpriced 或 unknown)、被跳过的组合、groupingSkipped、promptTokens(总计)、有任务带估算时的 inputCost(已定价任务的 usd 之和及各状态的任务数)、警告信息、settings(每项的 key、value(默认值时不存在)和 source),以及读取了账户设置时的 accountSettings。

SARIF 输出

--format sarif 把审查结果写成 SARIF 2.1.0 日志,代码扫描和安全看板读取的就是这种格式。上传到 GitHub 的方法见代码扫描。

  • 规则和结果。 每个审查员类别(correctness、security 等)一条规则,每个问题一条结果:
    • 级别来自严重程度:critical 为 error,warning 为 warning,suggestion 为 note;
    • 消息是标题、正文和修改建议;区域是问题所在的行;
    • partialFingerprints 里是它的指纹(ocra/v1);
    • 问题的 fix 放在 fixes 里,替换那几整行;
    • 审查员、严重程度、核查结果、状态、任务,以及已知时的模型放在属性里。
  • 没有行号的问题作用于整个文件:没有区域。
  • 沿用的问题。 审查 PR 时,之前的审查报告过、仍然打开、所在文件这次没有重新审查的问题,作为规则 ocra-carried-over 下的结果写出,标为 unchanged,没有行号。
  • 不完整的审查。 退出码为 3 的审查标为执行不成功;没审到的文件数和警告写成通知;结论、风险档位、没审到的文件和花费写在运行属性里。

来自改动和模型的文字只作为文字:方括号和反斜杠会被转义,花括号写成两个,网址插入零宽空格。--plan 不能输出 SARIF。

SARIF 输入

ocra 不运行任何分析工具:你自己运行 Semgrep、CodeQL 或其他工具,再用 --import-sarif <文件> 交给 ocra 它的 SARIF 2.1.0 日志(可以重复使用,每个最大 20 MB)。日志里的每个 run 成为一个任务 sarif-<工具>-<n>,审查员是工具名,没有花费;它的问题在 provenance.task 里指向这个任务。

  • 只保留落在改动上的结果:文件在审查范围内,行号落在 diff 的某个 hunk 里。其余结果,以及没有文件和行号、路径在仓库之外或没有消息的结果,计入一条警告。每个 run 最多取 200 条。
  • 严重程度来自结果的 level,没有时取规则的默认值:error 为 critical,warning 为 warning,note 和 none 为 suggestion。标题:规则的简短描述、名字或 id。正文:消息、规则的说明,以及工具、版本、规则和帮助链接。
  • 引用的代码决定行号。 结果里的代码片段(没有时取文件对应的行)和审查员引用的代码走同一套定位;对不上的会让问题变成文件级。
  • 之后它就是一条普通的问题:memory 和驳回照样生效,核查会检查它,Judge 会把它和审查员的重复问题合并,它也计入结论。

已用 Semgrep 1.178.0 写出的日志测试过;其他工具的日志遵循同一标准。

会话记录

每次审查(--plan 除外)都会写入 .ocra/sessions/<id>/events.jsonl(运行过程中逐行写入事件)和 report.json。运行 id <id> 出现在第一行进度输出、JSON 报告(runId)、摘要评论("覆盖范围和花费")和 SARIF 日志(automationDetails.id,ocra/<id>)里。每次任务尝试的事件在 attempt 里记录审查员读过的文件、搜索过的内容和最后的文字(有长度上限),以便分清一个文件是没打开过,还是读过但没发现问题;这些都不会写进报告。这个目录自带 .gitignore。

events.jsonl 的每一行末尾都有一个 seal:用你自己的密钥计算的 HMAC。这个密钥由 ocra 在首次使用时生成,存放在 ~/.config/ocra/session-key($XDG_CONFIG_HOME/ocra/,Windows 上是 %APPDATA%\ocra\),只有你能读取。--resume 只读取 seal 有效的行,因此一个会话只能在写下它的那台机器、那个账户上恢复;删除这个密钥只会让之前的会话无法恢复,不影响其他功能。如果 ocra 无法生成或读取密钥,审查会给出警告,这次的会话不能恢复;读不了的密钥文件(例如 sudo ocra 之后属于另一个用户)保持原样,不会被替换。

ocra metrics

对 .ocra/sessions/ 下已完成的审查做统计,数据来自每个会话的 report.json,不调用任何模型:

ocra metrics                       # 文本表格
ocra metrics --format json         # 给看板或脚本用;带 "version": 1
ocra metrics --since 2026-10-01    # 只统计在该日期及之后开始的运行
ocra metrics --sessions /srv/ocra  # 另一个会话目录,比如 CI runner 上的

它报告运行次数(按结论分;不完整的运行次数,即留下了没审完的文件或未核查的 critical、退出码为 3 的运行;没有可读报告的会话数)、花费(总计、每次运行、token 数)、问题数(报告条数、按指纹去重数、按严重程度和核查状态分)、早先问题的去向(fixed:后来代码已不在;dismissed:被审查者驳回;两者之比即接受率),以及每个审查员各自的任务数、失败任务数、花费和同样的统计。--resume 复用的任务在复用它的那次运行里不计花费:它的花费只计一次,记在实际付费的那次运行里。已修复或被驳回的问题归于上次审查记录的审查员,没有记录时归于最先报告该指纹的审查员。只统计版本 1 的报告;JSON 输出和报告一样是带版本号的约定。

ocra --version

打印版本号。

ocra memory

有些问题本身没错,但已被接受:风险在别处处理了,或者团队决定接受它。把它们记下来,ocra 就不会再报告:

ocra review                                  # 每条问题都会显示一个 id,例如 #1a2b3c4d
ocra memory add 1a2b3c4d --reason "重试次数由网关限制。"
ocra memory list

ocra memory add 在 .ocra/sessions/ 下最新的会话里查找这个 id(--session <dir> 可指定别的会话),写入 .ocra/memory.json;提交它即可共享。被记住的问题(审查员、文件和引用的代码都相同)不会出现在报告里,只会计数;审查员也会看到自己所审文件里已被接受的问题。审查 PR 时这个文件从 base 提交读取,所以 PR 无法压掉针对自己的问题。文件无效时审查会报错停止。

ocra Cloud 账户里的 memory

登录后,也可以在 ocra Cloud 网页上的某次审查里记住一个问题("Remember",并填写理由)。每次审查前(本地、--pr 或 --mr),ocra 按仓库哈希读取你的账户为这个仓库保存的条目(GET /api/memory),与 .ocra/memory.json 一起生效:任一方列出的问题都不报告,两边都列出的计为仓库的。报告写明每个被隐藏问题的来源 source(repository 或 account);终端打印 N finding(s) hidden by your ocra Cloud memory,PR 的总结评论也会给出数量。

  • 未登录或设置了 OCRA_CLOUD=off 时从不读取;--no-upload 不影响它(读取不会发送任何关于本次审查的内容)。
  • 读取失败时会给出警告,只使用仓库的文件。
  • 只在账户共享问题时生效,因为它按账户的盐计算的哈希保存;否则审查会提示一次:只应用仓库自己的 memory。
  • ocra memory add 只写入 .ocra/memory.json。

ocra login、ocra logout、ocra whoami

开发中。 ocra Cloud(ADR-0024)的地址是 https://app.ocracloud.com;`OCRA_CLOUD_URL` 可以指定其他服务器。不登录也能审查;设置 OCRA_CLOUD=off 后这几个命令拒绝运行。

ocra login                                    # 显示一个验证码,并打开浏览器确认
ocra whoami                                   # 当前登录的 GitHub 账号,以及本机是否发送问题
ocra logout                                   # 在服务器上结束会话,并删除本地保存的会话

ocra login 使用 OAuth 设备授权流程(RFC 8628):打印一个验证码(如 BCDF-GHJK),打开服务器上的确认页(加 --no-browser 只打印链接;不在当前服务器上、或不是 https 或本机 http 的页面只打印),然后等待你在已用 GitHub 登录的浏览器里批准。只批准你自己刚刚发起的验证码。这个会话可以用服务器上保存的 key 调用模型、上传结果,但不能读取这些 key,也不能修改账号;可在服务器的会话页面撤销。

会话保存在 ~/.config/ocra/credentials.json($XDG_CONFIG_HOME/ocra/,Windows 上为 %APPDATA%\ocra\),只有你本人可读。

  • 它和旁边的盐都以原子方式写入(先写临时文件再改名)。文件里没有会话时按未登录处理:审查会警告一次并指出该文件,然后不连接 ocra Cloud 继续;ocra logout 会删除它。
  • 访问令牌有效期一小时;刷新令牌每次使用后都会更换。同时运行的进程共用会话:同一时刻只有一个进程在 credentials.json.lock 下续期,其他进程等待它(最多两分半钟,等待超过五秒时打印 Waiting for another ocra process to renew the ocra Cloud session...;超过 90 秒的锁,或其进程在本机已退出的锁,视为已退出的进程留下的,会被打破),然后使用它保存的结果。ocra login 和 ocra logout 也取同一把锁,续期也不会覆盖期间另存的会话。有效令牌收到 401 时续期并重试一次。
  • 服务器拒绝续期即会话结束:审查会警告 your ocra Cloud session ended: run ocra login;ocra whoami 以 1 退出。
  • 连不上 ocra Cloud(网络错误、5xx、429)时会话保留;审查只警告一次,然后在没有你账户的规则、限额(含 maxCostUsd)、模型和 memory 的情况下运行,也不上传;指定了 ocra- 模型的审查则以错误停止,ocra whoami 以 2 退出。账户设置返回 404 视为没有设置,不警告。
  • ocra login 拿到令牌却读不到你的登录名时,仍保存会话,并说明登录名未知。

经由 ocra Cloud 的模型。 登录后,ocra-<provider>/<model> 会经由 ocra Cloud、使用服务器上为 <provider> 保存的 key 调用(服务器列出的 OpenAI 兼容对话接口):

{ "runtime": "direct", "models": { "standard": "ocra-openrouter/qwen/qwen3.8-27b:free" } }
  • 没有价格:报告中的费用和 --max-cost-usd 不计入它们,并给出警告。
  • 提示词及其中引用的代码经过 ocra Cloud,它只记录每次调用的模型、状态码、token 数和耗时,从不记录内容。
  • 没有使用 ocra- 模型的审查不读取会话,也不连接 ocra Cloud;配置中以 ocra- 名称自行声明的 provider 保持原有声明。
  • 推理强度按 ocra Cloud 为该 provider 列出的方式发送(openai:reasoning_effort;openrouter:reasoning.effort),没有列出时用 openai;不认识的方式会被忽略并给出警告。回答不是 provider 列表时审查停止。
  • 使用 "runtime": "direct" 时,ocra 在整个运行期间于令牌过期前五分钟续期。续期失败时警告一次并重试:先隔一分钟,之后间隔逐渐拉长(最长五分钟),令牌过期后也继续,直到运行结束。opencode 只在启动时读取一次令牌,所以 ocra 给它一个比 runTimeoutMinutes 多十分钟仍有效的令牌;运行可能比任何令牌都长时会警告:大约一小时后,经由 ocra Cloud 的调用会失败。只有新令牌会更持久时,ocra 才为此续期已保存的令牌;已保存的令牌几乎同样新时不续期。

账户设置。 登录后,ocra review 会把账户设置放在配置之下应用(见账户设置)。账户还可以开启 ultra,效果如同传了 --ultra;命令行上的 --ultra 始终生效。账户补充了哪些会打印出来(From your ocra Cloud settings: …)。--plan 也会读取它们,并在末尾列出 Settings,标明每项设置的来源:shared(extends 的共享配置)、file、env(OCRA_MODEL_*、OCRA_EFFORT_*)、account(含 ultra)、会合并的列表(include、exclude、规则)用 + 连接来源(例如 shared+account;账户的 exclude 只在配置没有设置时生效),或 default。连不上 ocra Cloud 时会给出警告,计划只显示配置本身。

审查会上传什么。 每次审查后,已登录的 CLI 会发送统计:结论、是否审完所有文件、各级别问题数、文件数、任务数、token、费用、耗时、来源(本地、GitHub、GitLab)和 ocra 版本;每个审查员的任务数、失败任务数、各级别问题数、费用(不含 --resume 复用的任务,本次运行没有为它们付费),以及它早先的问题已修复或被驳回的数量;已确认、不确定和未检查的问题数;早先的问题一共有多少已修复或被驳回(计入记录的审查员;记录审查员之前的问题,只有本次审查仍有同一指纹时才计入)。除非账户开启了共享问题,从不发送路径、标题、指纹、问题描述或代码。

  • 仓库以其规范化地址 https://host/owner/repo 加盐后的 SHA-256 发送(去掉用户名、凭据、端口、末尾的 / 和 .git,统一大小写,因此 git@host:owner/repo.git 和 ssh://git@host:22/owner/repo 得到同一个值)。使用 --pr 或 --mr 时是平台上的仓库;本地审查用 origin(本地路径形式的远程按原样使用;没有 origin 时用目录)。服务器可以把同一仓库的审查归在一起,却不知道是哪个仓库。自建 GitLab 部署在子路径下(https://host/gitlab/…)或由另一台主机提供 SSH 时,SSH 克隆的地址与合并请求的不同,因此对该克隆的本地审查与 --mr 审查算作不同的仓库;HTTPS 克隆则一致。
  • 远程是 SSH 形式、或带端口或末尾 / 的仓库,在 0.5.0 之后得到过一次新的哈希(0.5.0 按原样计算):旧的审查和 memory 要重新记录后才能对上。
  • 盐是随机值,保存在凭据旁的 upload-salt,所以每台机器的哈希不同。账户开启共享问题时,盐是账户的:登录时和每次审查前读取,保存在 account-salt(只有你可读),所以你的所有机器哈希一致。审查需要本机的盐却读不了 upload-salt(例如 sudo ocra 之后属于另一个用户),或无法创建它(目录只读)时,文件保持原样,审查给出警告,不向 ocra Cloud 发送任何内容。无法把账户的盐保存到 account-salt 时,审查给出警告,并使用刚收到的盐。
  • --no-upload 跳过单次上传,OCRA_CLOUD=off 关闭 ocra Cloud;上传失败只会给出警告。

共享问题。 在账户的 Settings 里打开"Send findings and the code they quote to ocra Cloud"(默认关闭)后,上传还会带上每个问题的指纹、审查员、级别、类别、核查结果、文件、行范围、标题、描述、建议和引用的代码,让网页可以完整展示这次审查。

  • 发送前,ocra 会把路径、类别、标题、描述、建议和代码中看起来像密钥的内容替换为 [redacted],并把问题标记为已脱敏:PEM 和 PGP 私钥块、AWS key id(AKIA…、ASIA…)、GitHub token(ghp_、gho_、ghs_、ghu_、ghr_、github_pat_)、GitLab token(glpat-)、sk- 开头的 key(包括 sk-ant-、sk-or-、sk-proj-)、Slack token(xoxb- 等)、Google API key(AIza…)、npm token(npm_…)、Slack 和 Discord 的 webhook URL、URL 中的密码(postgres://user:…@)、curl -u user:…、--user user:… 和 mysql -p… 中的密码、Bearer 或 Basic 之后(同一行或下一行)的凭据(之后若是普通单词,如在行文中,则保持不变;小写形式,如 HTTP/2 头中的,只在其后是 16 个字符以上且含数字的凭据时才算),以及赋给 password、passphrase、secret、secret_key、token、api_key 这类名字的值:带引号的(password = "…",包括在 JSON 字符串中引号被转义的),不带引号、写成 NAME=…(.env、命令行参数、查询字符串)或位于行尾的(YAML 中的 password: …),YAML 块标量的各行(password: |),或 --password …、--api-key "…" 这类参数之后的值(路径除外)。不带引号的值如果只有字母(changeme、string),或看起来是代码(函数调用、process.env.TOKEN 这类带点的名字、${…}、以 , 或 ; 结尾的行),则保持不变;但在 NAME= 或参数之后,结尾的 ;、,(参数之后还有 ))表示 shell 命令结束,前面的值仍会被替换。此外还有 32 个字符以上的十六进制串(包括 dop_v1_ 这类前缀之后的),以及 32 个字符以上、含数字且看起来随机的 base64 串(路径不受影响)。这只能识别模式,不能识别所有密钥;服务器会再做一遍同样的处理。
  • 最多 200 个问题、256 KB 文本,每个字段先截断到 4 KB 再脱敏(标记为已截断;截断处所在的 token 会整体脱敏)。终端打印 Sent this review's counts and N finding(s) to ocra Cloud。
  • 只有服务器返回账户的盐(它只在开关打开时返回)、并且本机同意时才发送问题:ocra login 发现开关打开时会说明这一点,并在凭据旁的 share-findings(只有你可读)中记下本机的同意;审查发现开关关闭时会删除它。打开开关后,或关闭再打开后,请在每台机器上重新运行 ocra login;在此之前,这台机器的审查会给出警告,只发送统计。因此 ocra Cloud 不能自己开启共享。审查前连不上 ocra Cloud 时,审查会警告,用 account-salt 里的盐(没有时用本机的)计算哈希,不发送问题,也不应用账户的 memory。
  • --no-upload 和 OCRA_CLOUD=off 仍然什么都不发送。

ocra plugins

在这台机器上允许你的 ocra Cloud 设置所列出的插件(见来自 ocra Cloud 账户的插件)。这些命令不连接 ocra Cloud;allow 和 deny 会运行 npm。

ocra plugins allow <name>@<version>   # 精确版本:先显示这个包,再安装
ocra plugins deny <name>              # 移除它:之后不再加载
ocra plugins list                     # 已允许的插件及其 integrity

allow 运行 npm view <name>@<version> --json,显示包的名称、版本、发布者、维护者和 integrity,然后运行 npm install --ignore-scripts --no-audit --no-fund --save-exact --prefix <dir> <name>@<version>,安装到 ~/.config/ocra/plugins/($XDG_CONFIG_HOME/ocra/plugins/,Windows 上为 %APPDATA%\ocra\plugins\)。只有 npm 安装的正是这个版本、且 integrity 与 registry 一致时,才记录到该目录的 plugins.json。npm 以参数列表运行,从不经过 shell,使用你的 npm 配置中的 registry 和凭据。不是 npm 包名的名称、或者是范围或标签的版本,会在运行 npm 之前被拒绝(退出码 2)。

在 GitHub 上编辑

本页目录