命令行（reviewctl）
reviewctl 用来登录平台、运行本地测试机、在你们自己的机器上跑测试、上传运行，以及接入编码 AI。本页列出它的命令和选项。
安装
要 Node.js 22.5 或更新的版本。平台自己在 https://<平台地址>/downloads/ 提供带版本号的安装包：
curl -fsS https://<平台地址>/downloads/latest.json
# {"version": "0.1.20260930120509", "file": "reviewctl-0.1.20260930120509.tgz", "sha256": "…", "size": …, "node": ">=22.5", "built_at": "…"}
curl -fsSO https://<平台地址>/downloads/reviewctl-<版本>.tgz
curl -fsSO https://<平台地址>/downloads/reviewctl-<版本>.tgz.sha256
shasum -a 256 -c reviewctl-<版本>.tgz.sha256 # Linux 上：sha256sum -c …
npm install -g ./reviewctl-<版本>.tgz
reviewctl --version # 例如 0.1.20260930120509+2e690ddnpm 会从它的仓库取 CLI 用到的开源依赖。平台每次发版都带一个新版本，最后一段数字是构建时间。有新版本时，目标 →「测试机」里这台测试机的那一行会提示，并给出升级命令。
reviewctl 的文件放在 ~/.reviewctl/，设 REVIEWCTL_HOME 可以换位置。里面有 login 存的 credentials.json、runner register 存的 runners/<项目编号>.json 和 dev connect 按仓库存的 dev-links/<仓库>-<哈希>.json，都只有你自己能读。
每条命令运行前，它先加载 --config 旁边的 .env，没有就加载当前目录的。shell 里已经设了的变量优先。
语言
系统语言（LC_ALL、LC_MESSAGES 或 LANG，取第一个设了的）是中文时，reviewctl 说中文，否则说英文。要自己选，在 shell 里或 .env 里设 REVIEWCTL_LANG=zh 或 REVIEWCTL_LANG=en。变的只是给人看的文字：JSON 输出、错误码和退出码都不变。
输出和退出码
- 加
--json时，命令在标准输出上只输出一个 JSON 对象。 - 出错时，标准错误上是一行（
错误：…）；加--json时是一个 JSON 对象{"error": {"code": "…", "message": "…"}}，在标准错误的最后一行。两种情况退出码都是 3。
| 退出码 | 测试命令（review --wait、report、retest --wait、eval） | doctor |
|---|---|---|
| 0 | 通过（包括只检查了回复的通过） | 全部就绪 |
| 1 | 不通过（eval：还包括低于 --min-pass-rate） | |
| 2 | 没跑完，还不能下结论 | 有检查项有缺口 |
| 3 | 出错：没有有效的报告 | review.yaml 无效 |
登录
reviewctl login --api https://<平台地址>它会显示一个地址和一个代码，形如 ABCD-EFGH。打开地址并登录，用 GitHub 或 Google 登录的会直接回到填代码的地方。在「批准命令行登录」里填代码，点「批准」。代码 10 分钟内有效。之后 CLI 保存一个 CLI 令牌。--label <名称> 设它在列表里的名称（默认 reviewctl@<主机名>）。
CLI 令牌只属于你，只能进一个组织。90 天不用、或登录满一年就失效，也可以在「组织 → 我的 CLI 令牌」里撤销。它能读取和上传运行，也能运行 reviewctl connect --ai，在你自己的测试机上预跑检查。在平台上确认测试和开始测试，仍然要由人在浏览器里做。
reviewctl logout # 在平台上撤销这台机器的 CLI 令牌，再删掉本机保存的文件在 CI 里，设 REVIEWCTL_API_URL 和 REVIEWCTL_TOKEN（reviewctl login 得到的 CLI 令牌），代替保存的登录。
准备项目
reviewctl init --project <项目编号> --domain <业务领域>
reviewctl doctor| 命令 | 选项 |
|---|---|
init | --project <编号>：网页上的项目编号（prj_…），runner register 要用；不填就生成一个新的。--domain <名称>：orders-refunds（默认，带自带的模拟后端）、expense、generic 或任意小写名。--backend fixture|own。--dir <路径>（默认 .）。--with-templates：拷贝这个领域的示例场景。--force：覆盖已有的 review.yaml。--answers <json>：不提问，直接用给的答案。--json。 |
doctor | 检查接入能做到什么：重置、工具观测、故障注入、读取结果、评审模型和 Agent 不是同一个、场景和通过标准。--config <路径>（默认 review.yaml）。--probe：真跑一个没有副作用的任务（工具代理拒绝所有写操作），证明看得到工具调用。--json。 |
init 查看项目（框架、MCP 配置、模型密钥的变量名、提示词文件），写出 review.yaml 和 .review/ 目录。字段见 review.yaml 参考。
运行测试机
reviewctl runner register --api https://<平台地址> --code ABCD-EFGH --config review.yaml
reviewctl runner start --config review.yaml| 命令 | 选项 |
|---|---|
runner register | --api <地址> 和 --code <配对码> 必填；配对码在目标下「本地测试机」的向导里点「生成配对码」得到，10 分钟内有效，只能用一次。--config <路径>（默认 review.yaml）：它的 project.id 必须是这个项目的。--label <名称>（默认 runner@<主机名>）。--json。它会上报 Agent 的工具名、数据查询名和身份变量名，从不上报内容和值。 |
runner start | --config <路径>。--once：有任务就领一个跑完，没有就退出。--poll-ms <n>：空闲时两次领取的间隔（默认 5000）。--allow-auth-ref <名称...>：平台来的测试额外可以用的身份变量（env:NAME）。--no-collect-files：不把仓库里的测试文件拷进场景目录。--self-update：网页上点「更新并重启」时，先从平台下载最新的安装包、核对 SHA-256、用 npm install -g 装上再重启（见让「重启」顺便更新）。 |
runner start 一直运行，每隔几秒向平台要任务，并上报心跳。按一次 Ctrl-C 在当前这次执行结束后停下并上传部分报告，按两次立即退出。在网页上这台测试机那一行点「重启」，它会用磁盘上现在的 reviewctl 重新启动。用 systemd 或 launchd 托管它，机器重启后也能接着跑。runner start 的 --job、--bootstrap-file、--api 和 --work-dir 只给沙盒用。
让 AI 补全并检查
reviewctl connect --ai --project <项目编号> [--code ABCD-EFGH]先 reviewctl login，再在 Agent 的仓库里运行。平台的模型会读仓库，写好 .reviewctl/ 下的测试接入文件，然后在这台机器上预跑检查；没通过就改了再查，最多检查 10 次。它读什么、发什么、怎么写文件，见本地测试机：让 AI 补全并检查。
读仓库、发送、用配对码注册之前，命令先问平台能不能开始：项目连的是 GitHub 仓库或自带镜像时，到这里就停，这台机器不注册、配对码不用掉。这个项目已经有一次在跑时，命令说是哪台机器、多久前还在回应，问你要不要取消那次重新开始（--yes 不替你取消）。发送前列出这台机器上要先准备好的（仓库自己的依赖、Agent 调模型的密钥；评审模型平台提供、按用量收费）；检查和测试在仓库的临时副本里跑。平台有更新的 reviewctl 时，开始时说一句怎么装。
| 选项 | 说明 |
|---|---|
--ai | 必填：用平台的模型写测试接入文件并检查（调用算进助手的每日用量）。 |
--project <编号> | 必填：网页上的项目编号（prj_…）。 |
--code <配对码> | 这台机器还不是项目的测试机时要带上，用来注册它（网页「本地测试机」里点「生成配对码」）。 |
--dir <路径> | 仓库根目录；不写就是当前目录往上最近的有 .git 的目录。 |
--yes | 不问：直接发送、写文件、检查。 |
--timeout <分钟> | 最多等多久（默认 120）。 |
--json | 最后只输出一个 JSON 对象（过程照样打印在标准错误上）。 |
退出码：0 接入跑通了；1 停下了，原因写在输出里（缺密钥、要确认测试、没法这样测、Agent 自己的问题、10 次检查都没通过）；2 没做完（你拒绝、取消或超时）；3 出错。
在自己的机器上跑测试
这些命令在这台机器上，用 review.yaml 里的 gate，拿 scenarios.dir 里的场景测你们的 Agent。不上传就不会进平台。
| 命令 | 选项 |
|---|---|
review | 在后台开始一次运行，输出它的编号。--wait：等跑完输出报告，退出码见上。--json：完整的 report.json。--summary：精简的 JSON 摘要（结论、数字、问题、报告路径）。--repeats <n>。--scenarios <编号> 和 --conditions <编号，或 normal,fault,attack>，逗号分隔。--label <文字>：版本标签。--estimate：只估算计划的执行次数和模型调用上限，什么都不跑。--config <路径>。 |
report | --run <编号> 必填。--format markdown|detail|json|summary（默认 markdown）。--finding <编号>：一个问题的 JSON，带证据和修法。 |
retest | --run <基线编号> 必填。用那次运行的场景重测现在的 Agent 并对比。--wait、--json、--summary、--repeats <n>（默认 3）、--label <文字>、--config <路径>。 |
cancel | --run <编号> 必填。在当前这次执行结束后停下，仍然出报告。--reason <文字>、--json。 |
scenarios validate <目录> | 对照 state_queries.yaml 检查目录里的每个场景。--json。 |
scenarios confirm <文件> | --by <名字> 必填。把场景标为已确认；之后再改内容，检查就不通过。 |
scenarios draft | --template <编号> --id <短名> --task <文字> 必填；--order <编号>、--actor <用户编号>、--no-record、--config <路径>、--json。用模板和一次录制起草一个场景。 |
每次本地运行的文件放在 review.yaml 旁边的 .review/runs/<运行编号>/ 里，其中有 report.json、report.md 和 fixes.md（可以交给编码 AI 的修改意见）。
上传运行
reviewctl push --run <运行编号>把一次本地运行上传到平台，并把报告链接写回本地报告。同一次运行再传一次不会有变化。要先 reviewctl login（或者设 REVIEWCTL_API_URL 和 REVIEWCTL_TOKEN）。地址按 --api <地址>、review.yaml 的 cloud.api_url、登录时的地址的顺序取。--config <路径>、--json。设 cloud.auto_push: true 可以让每次本地运行结束就上传。
在 CI 里评估测试集
reviewctl eval --set support-faq.yaml --target target.yaml --min-pass-rate 90% -o results.xml -o summary.md在这台机器上，用一个测试集测一个对话 AI，适合放在 CI 里。有两个选项必填。--set <文件> 是测试集，平台上的测试集可以导出成这个文件。--target <文件> 是被测 AI 的连接：kind、base_url、model、system_prompt 或 system_prompt_file，以及放密钥的变量名 key_env。
| 选项 | 作用 |
|---|---|
--gate <文件> | 通过标准；不给的话每道题都要通过，或者按 --min-pass-rate。 |
--min-pass-rate <比例> | 正常提问的通过率至少多少：0.9 或 90%。也可以用 REVIEWCTL_PASS_RATE_THRESHOLD。 |
--repeats <n> | 每道题问几次。 |
-o, --output <路径> | 写出结果，格式看扩展名：.json、.jsonl、.csv、.html、.md，.xml 是 JUnit。可以给多次。 |
--baseline <引用> | 和谁比：一个 report.json、平台上的运行编号，或者 latest（要 --project）。 |
--project <编号>、--push | 把运行上传到平台上的这个项目。 |
--label <文字>、--title <文字> | 版本标签，以及摘要的标题。 |
--judge <模型> | 评审模型；默认用 JUDGE_MODEL，没有就是 openai:gpt-4.1-mini。没有它的密钥时只跑规则判定。 |
--json | 以 JSON 输出结论、通过率、退出码和写出的文件。 |
设 REVIEWCTL_STRIP_OUTPUT=1，eval 写出的文件里就不带被测 AI 的回复。
发起项目的测试，等发布门槛
REVIEWCTL_API_URL=https://<平台地址> REVIEWCTL_TOKEN=pj_你的令牌 \
reviewctl eval --launch --project prj_01J8ZK3Q9MXYZ0000000000000 --commit "$GIT_SHA" --wait 60 -o summary.md--launch 在平台上发起项目全部已确认的测试（POST /v1/projects/<编号>/jobs，用项目的 API 令牌），等这一轮变成的实验的发布门槛，打印它的表格，退出码 0（通过）、1（未通过）、2（未判定：没设规则、没跑完，或 --wait 之内没定下来）或 3（出错）。它收 --project（必填）、--commit、--image、--scope all|functional|security|failed、--repeats、--wait <分钟>（默认 60）、--idempotency-key、--title、-o <文件.md|文件.json> 和 --json；--set、--target、--gate、--baseline、--push 和 --min-pass-rate 不能和它一起用。见 CI 与 GitHub Action。
SDK 有自己的命令 preworld eval，跑 *.eval.ts 和 eval_*.py 文件：见 SDK。
接入开发机 AI
reviewctl dev 把开发者电脑上的编码 AI 接到一个项目上，让它走完整个流程：取提示词、交测试、改测试接入、预跑、发起正式测试、看报告和修改意见。它能做到哪一步，看网页上给这个连接勾的权限：确认测试、发起正式测试、改测试接入和通过标准这些，没给权限的仍然由人在网页上做。怎么建连接、每个权限做什么、每天的费用上限，见从编码 AI 用平台。
reviewctl dev connect <配对码> --api https://<平台地址> --register claude配对码在网页的「设置 → 开发机 AI」里点「生成连接命令」得到，10 分钟内有效，只能用一次；页面上点「换一个配对码」换掉的那个会被拒，并说它已经作废了。连接按仓库存在 ~/.reviewctl/dev-links/ 下，30 天有效：一台机器可以同时连几个项目，命令用当前目录所在仓库的连接（旧版本存的 ~/.reviewctl/dev-link.json 在没有自己连接的仓库里照样用）。
dev connect 的选项 | 作用 |
|---|---|
--api <地址> | 必填：平台地址，网页给的命令里有。 |
--register <工具> | 把 MCP 服务 reviewctl-dev（reviewctl dev mcp）注册到哪个编码工具：claude（有 claude 命令时用 claude mcp add，没有就写仓库的 .mcp.json）、cursor（写 .cursor/mcp.json）、codex（有 codex 命令时用 codex mcp add，没有就只给出 config.toml 要加的几行）或 none。不写时在终端里问；不是终端就只给出手动注册的命令。已有不一样的 reviewctl-dev 时，只在终端里问过、回答 y 才换。 |
--yes | 不问：没写 --register 时用默认的（装了 claude 就是它）。已有不一样的 reviewctl-dev 照样不改。 |
--runner | 注册的 MCP 服务带 --runner，见下面的 dev mcp。 |
--json | 只输出一个 JSON 对象。 |
| 命令 | 作用 | 要的权限 |
|---|---|---|
dev status | 草稿、还缺的测试文件、todo、测试机在不在线、这个连接能做什么，以及下一步。 | |
dev prompt | 平台给这个仓库写的提示词：要写哪些测试、文件和 todo，怎么交。项目有以前批准过的测试计划时带着它。 | |
dev submit <文件> | 交上写好的 JSON（- 表示从标准输入读）；没通过时列出问题，退出码 1。 | 写测试草稿和上传文件 |
dev upload <仓库里的路径> | 上传草稿还缺的一份测试文件。--name <名称>：它在测试里的名字。 | 写测试草稿和上传文件 |
dev wiring | 平台上这个项目的测试接入文件：每个的大小、哈希、最后是谁存的。--show 连内容一起打印。 | |
dev push <文件...> | 把仓库 .reviewctl/ 下的文件存到平台上，按网页保存时的规则核对。 | 改测试接入文件 |
dev assist | 让平台的 AI 补全测试接入并检查（连 GitHub 仓库或自带镜像的项目；本地测试机的项目会告诉你在仓库里运行 reviewctl connect --ai）。--status 只看它做到哪了。 | 让平台的 AI 补全接入（发起时） |
dev tests | 测试和草稿：id、AI 审批结果、上次的结果，以及通过标准。 | |
dev test <id> | 一个测试的完整规则（YAML）：给测试 id 是它的草稿（没有草稿就是最新确认的版本），给版本编号就是那个版本。 | |
dev review | 让平台的 AI 再审草稿：每个审到哪了、没通过的理由、哪些在等人确认。 | 写测试草稿和上传文件 |
dev confirm <id> | 确认一个测试的草稿，和人在网页上确认一样核对。 | 确认测试 |
dev setup | 最近一次预跑：测试能不能进到 Agent，没通过时给出修改意见；没通过时退出码 1。 | |
dev retry | 修好后再预跑一次并等结果：0 通过，1 没通过，2 还没跑完。--no-wait，--timeout <秒>（默认 600）。 | 预跑 |
dev run | 发起正式测试，和网页上「开始测试」一样：先预跑，通过后开始；受这个连接每天的费用上限约束（不限每天的花费的，受组织剩下的额度约束）。--scenario <id...>（不写就是全部已确认的测试）、--condition <id...>（要和 --scenario 一起写；只选故障情况、没有正常情况也没有攻击时，要有点名它们的通过标准）、--repeats <n>、--wait（0 跑完、1 没跑成、2 还没跑完）、--timeout <秒>（默认 600）。 | 发起正式测试 |
dev job [任务编号] | 任务现在怎样：状态、预跑结果、每次执行的结果和下一步；不写编号就是这个连接最近发起的正式测试。--wait、--timeout <秒>。 | |
dev cancel <任务编号> | 取消这个连接发起的一个任务（当前这次执行结束后停下）。 | |
dev runs | 最近的正式测试：run_id、结论、问题数和报告链接。--limit <n>（默认 10）。 | |
dev report [运行编号] | 一次正式测试的结论（给 AI 看的 Markdown；--json 是数据）；不写就是最近一次。 | |
dev diagnosis [运行编号] | 平台 AI 的诊断：没通过或判断不了的，原因在 Agent、测试接入还是测试本身，以及怎么办。 | |
dev fixes | 最近一份报告里给 AI 的修改意见，或用 --run <编号> 指定。 | |
dev gate <文件> | 把文件里的通过标准存成项目的（JSON 或 YAML，和 dev tests --json 里的 gate 同一个格式）。 | 改通过标准 |
dev tasks | 经 API 派给它的活。 | |
dev done <任务编号> | 告诉平台一件活做完了；--failed --note <文字> 表示做不了、交回。 | |
dev pull | 把这个项目在平台上改过的测试接入文件（.reviewctl/）取回仓库，列出新增、有改动、没变的；只写文件不提交，由你看过后自己提交。--dir <路径>。 | |
dev disconnect | 断开这个仓库的连接：平台上这个连接作废（已经断了或过期了也照样清），本机为这个仓库存的连接删掉，别的仓库的不动。注册过的 MCP 服务要自己删，命令会告诉你怎么删。 | |
dev mcp | 以 MCP stdio 服务提供全部 40 个工具（上面这些命令对应的，加上测试计划的 6 个（做计划的 5 个已去掉，只说明这一点）和实验、日志和发布门槛的 9 个），见流程和工具。--runner：接本地测试机的项目，服务起来后在后台启动这个项目的测试机（reviewctl runner start；这台机器要已经注册成测试机，平台上还没有在线的），服务退出时停掉，日志在 ~/.reviewctl/logs/runner-<项目编号>.log。--config <路径>：--runner 用的 review.yaml，不写就是当前目录的，没有就用 .reviewctl/review.yaml。 |
这些命令都可以加 --json。没有权限的步骤不做，并说请人在网页「设置 → 开发机 AI」里给这个连接「改权限」。
接本地测试机的项目，dev retry（MCP 里的 try_run）和 dev run 都在测试机上跑，要测试机在线；不在线时平台不发起，dev status 会说怎么办。
MCP 服务和 Skill
有两个 MCP 服务，用途不一样：
| 服务 | 怎么起 | 做什么 |
|---|---|---|
reviewctl-dev | reviewctl dev mcp（先 reviewctl dev connect），或者不装 reviewctl、用平台上的 MCP over HTTP：https://<平台地址>/v1/dev/mcp | 连上平台上的一个项目，走完接入、写测试、审核、预跑、正式测试、看报告的流程，还能读实验、日志和发布门槛，共 40 个工具（HTTP 上少了读本机文件的 upload_file）。注册方法见从编码 AI 用平台。 |
| 本地测试 | reviewctl mcp --config review.yaml | 不经过平台，在这台机器上按 review.yaml 跑测试：check_capabilities、review_project、get_report、retest 和 cancel_run。 |
reviewctl skill install --host claude-code|codex 把 product-review skill 装进编码助手（--project 装到这个项目的 .claude/skills/，--dest <目录> 装到别的目录）。reviewctl skill where 显示各个宿主放 skill 的位置。
环境变量
| 变量 | 作用 |
|---|---|
REVIEWCTL_LANG | zh 或 en：提示文字的语言。 |
REVIEWCTL_HOME | reviewctl 放文件的目录（默认 ~/.reviewctl）。 |
REVIEWCTL_API_URL、REVIEWCTL_TOKEN | 平台地址和一个 CLI 令牌，代替保存的登录（CI 用）；eval --launch 用项目的 API 令牌 pj_…。 |
REVIEWCTL_PASS_RATE_THRESHOLD | eval 的 --min-pass-rate。 |
REVIEWCTL_STRIP_OUTPUT | eval 写出的文件里去掉回复。 |
JUDGE_MODEL | eval 默认的评审模型。 |
JUDGE_SECOND_MODEL | eval 的第二个评审模型：第一个判断不了的回复，请它用同样的提示词再判一次。这台机器上要有它的密钥，和第一个评审模型相同时不用。不设就不复核，结果里会写明。两个判得不一样时按更强的算，强弱按平台的模型目录排，目录外的排在后面；两个都在目录外时不下结论（见第二个评审模型）。 |
REVIEWCTL_GIT | 读代码版本时用的 git。 |
下一步
- 本地测试机：一步步安装、注册、启动。
- review.yaml 参考：
init写了什么，doctor查什么。 - API 与令牌：不用 CLI，从 CI 发起运行。