rightmodeler

rightmodeler TypeScript CLI 运行手册

**当前路径：**使用已安装的 TypeScript CLI，该工具已发布到 npm，包名为 rightmodeler（工作区包 @rightmodeler/cli），可执行文件为 rightmodeler。 旧版 Python 引擎已停用；CLI 是唯一的引擎。

CLI 支持断点续跑。它会在目标仓库的 .rightmodeler/ 中保存检查点和报告， 除非使用 --store 指定其他位置。满足指定输入或预算边界后，重新运行相同的 命令即可。不要删除存储目录来重新开始。

已安装的 CLI 附带自己的文档；第 3 节介绍如何阅读这些文档。

0. 参考文件

• reference/harnesses/index.md：准备 Mode B 运行前阅读。此文件会根据框架 结构指引到各流水线对应的文件，说明模型 ID 的绑定位置、是否转发关联标头、 是否支持覆盖基础 URL 以及承载该 URL 的变量、如何模拟有副作用的工具、 入口点，以及如何检测下游耦合。
• reference/evidence.md：在第 8 节展示结果前阅读。此文件定义证据层级、 最低要求、所有弃答原因、所有证据排除原因、发布门槛 ID，以及评判者的选择方式。

1. 明确范围和目标

仅询问尚未明确的信息：

• 仓库根目录。
• 轨迹文件路径。交互式 init 和 estimate 可以发现受支持的本地文件、 Claude Code 文件和 Codex 文件，但 Agent 和其他非交互式运行应始终显式传入 --traces，以确保操作具有确定性。
• 目标和停止阶段。要获得完整的建议运行结果，请使用 report。
• 如何调用模型。默认使用 API 路由：兼容 OpenAI 的提供方基础 URL，以及已包含 API 密钥的环境变量名称。计划路由通过用户自己的 claude 或 codex CLI 运行 候选模型或评判者，且用户须已在此机器上登录（见第 5 节）；只有在用户同意后 才能使用，具体如下。
• 使用 API 路由时，如果操作者需要设置上限，则询问允许用于重放的最高支出金额 （美元）。使用计划路由时，除非用户主动要求，否则绝不询问、建议或设置支出上限。
• 会影响运行的模型、提供方、质量或所有权约束。
• 用户想尝试的模型（如有）。默认情况下，rightmodeler 只尝试成本低于记录中 模型且在最近 90 天内发布的模型。只有用户提出要求时，才使用 --candidate 指定模型，或使用 --released-since 或 --released-until 调整时间范围。

绝不询问、读取、复述或存储 API 密钥或登录令牌，也绝不打开 ~/.claude、 Keychain 或 ~/.codex/auth.json。用户应在自己的 shell 中设置指定的环境变量。 绝不将密钥值直接写入命令，也绝不把密钥放入基础 URL 或标头中。

选择计划路由前，应说明每个角色所用的路由，告知用户计划路由的含义，并征得 用户同意：

• 它使用计划的用量额度，限制与用户自己的 Claude Code 或 Codex 会话相同 （若此 Agent 使用同一计划，则也受其限制）。它不限制调用次数或支出： 运行会按需发起调用，唯一的停止条件是计划的用量限制。
• 轨迹中的提示词会根据计划账户的数据设置发送给 Anthropic 或 OpenAI。
• CLI 会在每次调用中添加自己的上下文（claude 会添加已登录账户的电子邮件 地址和日期；codex 会添加用户的全局指令文件），且无法设置 temperature 或 输出上限，因此结果衡量的是模型在编码 CLI 中的表现。详情请参阅 rightmodeler docs model-routes。

使用计划路由时，rightmodeler 会自行检查登录状态。绝不要在 CI 中提供计划路由： 如果设置了 CI，rightmodeler 会拒绝使用计划路由，因此 CI 中应使用 API 路由。 Mode B 确认（--modeb-config）的两个角色都必须使用 API 路由。

2. 检测入门状态

可从任意目录运行，但始终传入绝对仓库路径：

REPO=/absolute/path/to/repository
if [ -d "$REPO/.rightmodeler" ]; then
  echo "Existing rightmodeler state found. Resume from checkpoints."
else
  echo "No rightmodeler state found. Start onboarding."
fi

现有的 .rightmodeler/ 表示继续运行，而不是覆盖。花费资金之前， 请说明这是新运行还是续接运行，并重述已商定的范围。

3. 定位 CLI

优先使用已安装的 bin。其次使用依赖项本地捆绑的 bin。 如果都没有，则通过 npx 使用已发布的软件包：

if command -v rightmodeler >/dev/null 2>&1; then
  RIGHTMODELER=(rightmodeler)
elif [ -x ./node_modules/.bin/rightmodeler ]; then
  RIGHTMODELER=(./node_modules/.bin/rightmodeler)
else
  RIGHTMODELER=(npx --yes rightmodeler)
fi

"${RIGHTMODELER[@]}" --help
"${RIGHTMODELER[@]}" init --help
"${RIGHTMODELER[@]}" docs
# Replace <name> with a name from the list above, for example getting-started, commands,
# exit-codes, evaluators, modeb, gateways, model-routes, github, or github-actions.
"${RIGHTMODELER[@]}" docs <name>

两个帮助命令都必须以 0 退出。如果任一命令以 10 或更大的代码退出，请停止并报告 安装或命令行故障。没有备用引擎。 随附文档描述的是实际安装的版本；如果版本不同，应以文档为准，而不是本运行手册。如果 init --help 未列出 --route，则说明安装的 CLI 早于计划路由功能；请使用 API 路由。如果未列出 --candidate，则说明安装的 CLI 早于候选项选择功能；将 CANDIDATE_ARGS 留空。

Windows PowerShell

本运行手册中的示例使用 bash。如果你的 shell 工具运行的是 Windows PowerShell，请按如下方式定位 CLI：

$env:NoDefaultCurrentDirectoryInExePath = "1"
$cli = Get-Command rightmodeler.cmd -ErrorAction SilentlyContinue
if ($cli) { rightmodeler.cmd --help } else { npx.cmd --yes rightmodeler --help }
exit $LASTEXITCODE

然后使用相同参数，将每条命令写在一行上，并遵守以下规则：

• 调用 npx.cmd 或 rightmodeler.cmd，不要调用 npx 或 rightmodeler：对于裸名称， Windows PowerShell 5.1 会运行 npm 安装的 .ps1 脚本，而默认 执行策略会阻止这些脚本。
• 每次调用都以 $env:NoDefaultCurrentDirectoryInExePath = "1"; 开头，这样仓库中放置的 程序就无法取代 CLI 运行。
• 每次调用都以 ; exit $LASTEXITCODE 结束，让 shell 返回 CLI 的退出 代码。若不这样做，powershell -Command 会将所有非零退出代码转换为 1， 而代码 2 和 3 另有含义。
• 从工具结果中读取输出，不要用 > 重定向，因为在 Windows PowerShell 5.1 中， 这会写入 UTF-16。
• 使用 $env:NAME = "value" 设置变量，并用双引号括起路径，且双引号前不能是反斜杠。

4. 预览计划

预览为只读操作，无需跟踪记录或提供商凭据：

"${RIGHTMODELER[@]}" init --plan --output json --repo "$REPO"

要求退出代码为 0。将 stdout 解析为一个 JSON 对象。其中的 stages 数组列出各个阶段， 并将其标记为 pending、stale 或 complete；executedStages 必须为空。 开始运行前，先展示阶段计划。解析失败属于运行时故障，而不是空计划。

5. 运行至商定阶段

设置商定的输入。THROUGH=report 会运行完整流水线。使用 API 路由时， API 密钥必须已存在于 API_KEY_ENV 指定的环境变量中。

支出上限为可选项。将 MAX_COST_USD 留空即可不限额运行：每个用例和评审单元格都会 运行至完成；当完整性和证据质量比成本更重要时，这是正确的选择。仅当操作人员希望 设置硬性停止条件时才设置上限；达到上限时，运行会停止并给出明确的解决办法，调高上限后即可 继续。使用计划路由时，除非用户要求设置上限，否则将 MAX_COST_USD 留空：计划路由不限额， 唯一的停止条件是计划的使用限额。如果用户要求在此处设置上限，该上限按标价折算值 计算，而非实际账单金额；并且它只是软上限，因为编码 CLI 不会设置输出限额。 使用 --policy <path> 指定发布策略 JSON，涵盖质量底线、候选列表大小以及模型允许和拒绝列表；使用 --pricing-file <path> 指定目录未提供时的每 token 定价；使用 --catalog-reference <url-or-path> 指定上游模型列表，以补充目录缺少的信息；在计划路由中，该列表就是价格列表（默认使用 Vercel AI Gateway 的公开列表）；对于按请求标头路由的网关，可重复使用 --header 'name: value'，绝不可用于机密；使用 --max-concurrency <n> 指定提供商请求的最大并发数；在计划路由中，它指定同时运行的 CLI 进程上限，而非调用次数上限；使用 --matchers <path> 指定声明式匹配器定义 JSON 文件；可重复使用 --candidate <id>，精确重放用户指定的模型；对每个更便宜且适用于每个调用位置的模型系列中的模型，无论其发布日期如何，均纳入重放；使用 --released-since <date-or-days>（日期，例如 2026-01-01，或 365d）和 --released-until <date>，将发布日期范围从默认的计划候选列表前 90 天调整为指定范围；使用 --modeb-config <path> 选择容器镜像、应用规范、步骤映射和 backend；默认值为 docker，远程沙箱则使用 cloud。运行 Mode B 时，请先阅读 reference/harnesses/index.md，并遵循该文件指引的文件。

API 路由请将 ROUTE_ARGS 留空。只有在用户同意使用计划路由（第 1 节）后才设置它，并且始终指定两种角色：计划 --route 未指定 --judge-route 时会被拒绝；裁判模型必须来自不同于候选模型和记录模型的提供商。

• 计划路由的两种角色均使用 PROVIDER_BASE_URL 留空的配置：对于记录了 Anthropic 模型的轨迹，使用 ROUTE_ARGS=(--route claude-login --judge-route codex-login)；对于 OpenAI 模型，使用 ROUTE_ARGS=(--route codex-login --judge-route claude-login)。
• 通过多供应商网关评判计划候选模型，并保留 PROVIDER_BASE_URL 和 API_KEY_ENV：例如 ROUTE_ARGS=(--route claude-login --judge-route api)。
• 通过计划路由评判 API 候选模型，并保留 PROVIDER_BASE_URL 和 API_KEY_ENV：例如 ROUTE_ARGS=(--route api --judge-route claude-login)。不纳入来自裁判模型所属供应商的候选模型。直接使用 OpenAI 或 Anthropic 密钥时，只能使用一个供应商，且没有价格列表：请通过另一家供应商的 CLI 进行评判，并将 --catalog-reference https://ai-gateway.vercel.sh/v1/models 添加到 ROUTE_ARGS。

本次运行绝不会读取通过交互式 init 或 estimate 保存的路由。若要复用路由，请向用户索取该命令打印的标志。

除非用户指定了要尝试的模型，或要求使用较早或特定发布日期的模型，否则将 CANDIDATE_ARGS 留空。例如：CANDIDATE_ARGS=(--candidate openai/gpt-6-luna) 或 CANDIDATE_ARGS=(--released-since 365d)。--candidate 不能与发布日期选项同时使用。针对同一存储，后续每条命令都传入相同的 CANDIDATE_ARGS：不传这些参数的命令会恢复使用默认候选列表。

TRACES=/absolute/path/to/traces.json
THROUGH=report
PROVIDER_BASE_URL=https://provider.example/v1
API_KEY_ENV=RIGHTMODELER_API_KEY
ROUTE_ARGS=()
CANDIDATE_ARGS=()
MAX_COST_USD=
RUN_LOG=$(mktemp)
ERROR_LOG=$(mktemp)

API_ARGS=()
if [ -n "$PROVIDER_BASE_URL" ]; then
  API_ARGS=(--base-url "$PROVIDER_BASE_URL" --api-key-env "$API_KEY_ENV")
fi

CAP_ARGS=()
if [ -n "$MAX_COST_USD" ]; then
  CAP_ARGS=(--max-cost-usd "$MAX_COST_USD")
fi

if "${RIGHTMODELER[@]}" init \
  --yes \
  --through "$THROUGH" \
  --traces "$TRACES" \
  "${ROUTE_ARGS[@]}" \
  "${CANDIDATE_ARGS[@]}" \
  "${API_ARGS[@]}" \
  "${CAP_ARGS[@]}" \
  --output jsonl \
  --repo "$REPO" \
  >"$RUN_LOG" 2>"$ERROR_LOG"; then
  EXIT_CODE=0
else
  EXIT_CODE=$?
fi

将每一条非空标准输出行解析为一个 JSON 对象。若任何一行无效，请报告行号并明确报错。事件包括 stage_started、stage_completed、stage_skipped、warning 和最终的 result。保留事件顺序。不要根据是否有输出推断成功；请先根据 EXIT_CODE 分支处理。

此解析器可直接复制粘贴，用于验证数据流并打印每个事件：

node - "$RUN_LOG" <<'NODE'
const fs = require("node:fs");
const path = process.argv[2];
const lines = fs.readFileSync(path, "utf8").split(/\r?\n/);
for (let index = 0; index < lines.length; index += 1) {
  if (lines[index].trim() === "") continue;
  try {
    console.log(JSON.stringify(JSON.parse(lines[index])));
  } catch (error) {
    throw new Error(`Invalid JSONL at line ${index + 1}: ${error.message}`);
  }
}
NODE

已完成的阶段会保存检查点。恢复运行时，当前阶段出现 stage_skipped 属正常情况。保留现有 .rightmodeler/ 目录并重新运行相同命令，以便从第一个边界处恢复过期或未完成的工作。

6. 解读管道退出代码

使用 rightmodeler docs exit-codes 中的管道约定：

• 0：成功，且没有可执行的建议。成功的规划和部分 --through 运行也会返回 0。
• 1：完整的 init 或 report 发现了可执行的建议。
• 2：运行需要在可恢复的边界处输入，或者计划已达到用量上限。
• 3：在可恢复的边界处达到成本预算。
• 10 或更高：命令行或运行时错误。

对于退出代码 0 或 1，要求包含最终的 JSONL result 事件。对于退出代码 1，还要求 result.recommendationExists 为 true。对于完整的退出代码为 0 的运行，要求该值为 false。部分运行可以在没有建议的情况下以 0 退出。

对于退出代码 2 或 3，将 stderr 解析为恰好包含一个 JSON 对象，其中含有 code、message 和 remedy。stdout 可能包含在到达边界之前已完成阶段的有效事件。

7. 在可恢复的边界处暂停

退出码为 2 时，从 message 中指出缺少的输入，给出确切的 remedy，并等待用户或仓库所有者提供该输入。常见的补救方法包括添加 --traces、添加 --base-url、通过 --api-key-env 指定 API 密钥环境变量，或提供必需的确认配置。切勿猜测缺失的值。 输入可用后，使用同一存储恢复运行。

missing_traces_path 补救方法最多可附上最新发现的三个路径，以及其他候选路径的数量，随后给出 Pass --traces <path>. 这些路径仅作为建议。在运行手册命令中，仍须显式传入经操作员批准的跟踪路径。

模型路由还会新增以下退出码为 2 的情况。报告 message 和 remedy，然后：

• plan_usage_limit：套餐已达到使用上限。告知用户 message 中引用的重置时间；如果服务商未提供重置时间，也要告知用户，然后停止。仅在重置后且用户明确指示时，才用同一命令重新运行；已完成的调用会保留。切勿循环重试，也切勿未经询问就切换路由。
• plan_login_required：CLI 未登录套餐账户、将使用 API 密钥，或已丢失登录状态。请用户在自己的终端中按照补救方法操作：使用其中指定的命令登录，或移除其中指定的 API 密钥设置。切勿自行读取或编辑该设置。然后重新运行。
• plan_cli_unavailable：CLI 缺失、版本过旧，或发生了 rightmodeler 不接受的更改，或者设置了 CI。转达补救方法。切勿自行取消设置 CI；在 CI 中，请使用 API 路由。
• judge_family_unknown：模型 ID 未注明供应商，因此无法核验评审模型的供应商。Replay 会在调用任何模型前检查这一点。转达补救方法，并询问用户要采用哪种修复方式。
• no_neutral_judge：没有可用的评审模型来自候选模型和已记录模型之外的其他供应商。Replay 会在调用任何模型前检查这一点。转达补救方法，并询问用户是要提供第三方供应商目录、使用其他评审路由（仅在用户同意后才使用套餐路由），还是使用评估器。

候选模型选择还会新增以下退出码为 2 的情况。每种情况都会在调用任何模型前触发。报告 message 和 remedy，并在扩大时间窗口或指定模型前询问用户，因为这两种做法都会改变 Replay 的开销：

• no_recent_candidates：发布窗口内没有比已记录模型更便宜的新模型。提供补救方法中的选项：使用更早的 --released-since、通过 --candidate 指定模型，或在目录中的日期为占位值时使用 --catalog-reference。
• release_dates_unavailable：传入了发布日期选项，但目录中没有可用的发布日期。提供 --catalog-reference、--candidate 或移除日期选项。
• unknown_candidate：--candidate 指定的模型不在提供方目录中，或匹配了多个模型。询问用户指的是哪个目录 ID。
• named_candidates_ineligible：没有任何指定模型能在任何调用位置尝试；消息会说明每个模型不符合条件的原因。转达这些原因，并询问用户要改为指定哪些模型。

退出码为 3 时，报告已达到配置的预算边界，运行因此停止。提供错误 message 和 remedy、配置的 --max-cost-usd，以及 stdout 中最后完成的阶段。未经用户明确授权，切勿提高预算。

退出码为 10 或更高时，报告 stderr 并停止。恢复运行前，先修复命令或运行时故障。切勿将其重新解释为建议或弃答。

8. 呈现结果

对于退出码为 0 或 1 的情况，读取最终的结果事件，并为 familyOutcomes 中的每个条目呈现一行。总结前，请阅读 reference/evidence.md，了解每种弃权原因和门禁 ID 的含义。请包含：

• 系列标识符。
• 决策及其是否为有效推荐。
• 所选候选项（如有）。
• 评估器通过率、可用性和最坏情况界限。
• 确认状态及任何阻碍因素。
• 弃权原因（如有）。

同时报告 reportPath。一次完整运行会写入 .rightmodeler/project/reports/report.md。JSON 报告保存在版本化存储中，而不是作为普通文件写入，因此请从最终的 result 事件中获取机器可读结果，而不是从路径读取。

如果运行了计划路由，请指出回放候选项的路由和进行判定的路由，转述报告中的 ## Model routes 部分，并说明计划路由上的支出是从计划额度中扣除的标价等值金额，而不是账单。报告每个 warning 事件的 code 和 message；计划路由上的警告包括 plan_route_key_withheld、plan_usage_warning、codex_global_instructions、judge_vendor_candidates_dropped 和 plan_route_cases_left_out。候选项选择还可能产生 release_window_skipped、shortlist_no_recent_candidates 和 shortlist_candidate_left_out。

以系列判定作为决策单位。不要把单个成功案例提升为系列推荐。退出码为 0 时仍可能包含有价值的拒绝和弃权；请呈现这些结果，而不是说什么都没发生。

9. 应用并监控已验证的替换方案

只有在完整结果包含有效推荐时，才继续操作。apply 会运行机器门禁并创建草稿拉取请求，但不会合并。

下面的 GITHUB_TOKEN_ENV 指的是保存 GitHub 令牌的环境变量； 切勿传入令牌本身。GitHub App 安装令牌或具有 repo 作用域的经典令牌可完整支持 apply 和 watch。细粒度个人访问令牌支持 apply；使用此令牌运行 watch 时无法读取检查运行，只能使用提交状态，并会输出 github_checks_unavailable 警告。这是预期行为，并非失败。在 GitHub Actions 中，只要作业授予了所需权限，作业的 GITHUB_TOKEN 也可使用。 "${RIGHTMODELER[@]}" docs github 会列出这些权限、其他令牌详情以及 GitHub App 权限。

首先运行机器门禁试运行：

GITHUB_OWNER=example-org
GITHUB_REPO=example-repository
GITHUB_API_URL=https://api.github.com
GITHUB_TOKEN_ENV=GITHUB_TOKEN

"${RIGHTMODELER[@]}" apply \
  --owner "$GITHUB_OWNER" \
  --github-repo "$GITHUB_REPO" \
  --github-base-url "$GITHUB_API_URL" \
  --github-token-env "$GITHUB_TOKEN_ENV" \
  --dry-run \
  --output jsonl \
  --repo "$REPO"

apply 的退出码因命令而异：0 表示试运行无误或更改已应用，1 表示机器门禁拒绝了更改，2 表示存储中没有已完成的运行，10 或更高表示运行时失败。退出码为 2 时，请读取标准错误中的 JSON 错误，例如 stage_not_completed，并按照第 7 节的说明处理。如果试运行退出码为 0，请使用相同命令但不带 --dry-run，以创建草稿拉取请求，并请求已解析的负责人进行评审。

命令返回拉取请求编号后，监控一轮协调：

PR_NUMBER=123
"${RIGHTMODELER[@]}" watch \
  --owner "$GITHUB_OWNER" \
  --github-repo "$GITHUB_REPO" \
  --pr "$PR_NUMBER" \
  --github-base-url "$GITHUB_API_URL" \
  --github-token-env "$GITHUB_TOKEN_ENV" \
  --output jsonl \
  --repo "$REPO"

无需采取操作时，watch 以 0 退出；执行了评审或持续集成操作时，以 1 退出；发生运行时失败时，以 10 或更高退出。退出码 2 有两种含义。一种情况是另一个监控进程持有锁，且标准输出以一个 result 事件结束，其结果包含 "status":"lock_held"；请稍后重试。另一种情况是存储中没有已完成的运行，标准错误中会出现类似 stage_not_completed 的 JSON 错误；请按照第 7 节的说明处理。向用户报告任何 {"event":"warning"} 行的 code 和 message，然后继续。在仓库事件发生时或按照项目计划重复运行 watch。已解析的负责人会评审草稿拉取请求，并决定是否合并。CLI 绝不能合并该请求。

若要在 GitHub Actions 中运行此循环，请通过 "${RIGHTMODELER[@]}" docs github-actions 打印已测试的工作流，并遵循其 Setup 部分。

10. 提议发送反馈

rightmodeler 不会收集遥测数据，因此只有用户选择反馈时，团队才能了解出了什么问题或缺少什么。运行结束后，或者 CLI 因阻塞问题而停止，且其 message 和 remedy 未能说明原因时，你可以主动提出代用户向 rightmodeler 团队发送一次反馈。用户提出要求时，也要发送。没有用户可询问时（例如在 CI 中），不要发送。

发送前，向用户展示完整的 JSON 正文，并征得用户同意。切勿自行发送，也绝不要重复发送同一条反馈。

正文可以包含对发生的问题或缺少内容的通俗描述、你所使用的编码 Agent、CLI 版本、命令、退出代码和错误 code。正文绝不能包含跟踪内容、提示词、模型输出、源代码、文件内容、密钥或令牌。除非用户提供电子邮件地址以便回复，否则不要填写用户的电子邮件地址。

curl -sS --max-time 30 -X POST https://www.rightmodeler.com/api/feedback/agent \
  -H 'Content-Type: application/json' \
  -w '\n%{http_code}\n' \
  --data-binary @- <<'JSON'
{
  "message": "What happened or what is missing, in plain language.",
  "agent": "claude-code",
  "version": "<cli version>",
  "context": "rightmodeler init --through report; exit 2; plan_login_required"
}
JSON

只有 message 是必填项，长度最多为 5,000 个字符。agent 用于标明发送反馈的编码 Agent，version 则是运行 "${RIGHTMODELER[@]}" --version 后打印的内容，两者长度均最多为 100 个字符；context 可填写一两行，长度最多为 1,000 个字符。只有用户提供了用于接收回复的电子邮件地址时，才添加 "contact": "<email>"。正文必须是有效的 JSON，因此字符串中的换行符应写作 \n。

命令会先打印响应正文，然后在单独一行打印 HTTP 状态码：

• {"ok":true} 和 200：反馈已发送。告知用户。
• 其他任何结果均表示失败。请求被拒绝时，{"error":"<reason>"} 会与 400 一同返回；电子邮件无法发送时，会与 500 或 502 一同返回。curl 错误和 000 表示请求未完成。告知用户一次，引用原因，然后继续。不要循环重试；只有用户再次提出要求时才重新发送。