relay-dispatch

输入

• 环境：可选的 RELAY_SKILL_ROOT，默认为 skills。
• 文件：调度提示词（--prompt-file 或 --prompt）、必需的评分标准文件（通过 --rubric-file 指定）、可选的 Done Criteria 文件，以及可选的仓库相对路径文件副本。
• 同级脚本：${RELAY_SKILL_ROOT:-skills}/relay-dispatch/scripts/dispatch.js。

Relay Dispatch

公开的 /relay 源门控必须先选择路由，才能运行此命令。它要求使用 Git 检出目录；在本地 Reviewed Result 交付时，允许未配置远程仓库；GitHub 路由仅接受完全匹配的受支持 GitHub 远程仓库格式。调度本身不会初始化 Git，也不会选择代码托管平台。

适用场景

• 通过工作树隔离，将实现任务委派给执行器（codex、claude、opencode、pi、antigravity、cursor、cline）
• 在收到 changes_requested 审查结果后，继续同一轮运行
• 为独立任务运行后台或并行调度

不适用场景

• 编写评分标准或制定计划——使用 relay-plan
• 审查执行器的输出——使用 relay-review
• 任务缺少冻结的 Done Criteria——先通过 relay-ready 确定

用法

# Foreground (blocking — simple tasks, default executor: codex)
node "${RELAY_SKILL_ROOT:-skills}/relay-dispatch/scripts/dispatch.js" . -b feature-auth -p "..." --rubric-file rubric.yaml

# Detached (recommended for long/background work; survives caller shell exit)
node "${RELAY_SKILL_ROOT:-skills}/relay-dispatch/scripts/dispatch.js" . -b feature-auth -p "..." --rubric-file rubric.yaml --detach --json

# Same-run resume after a changes-requested review
node "${RELAY_SKILL_ROOT:-skills}/relay-dispatch/scripts/dispatch.js" . --run-id issue-42-20260403120000000 --prompt-file review-round-2-redispatch.md

# With explicit executor
node "${RELAY_SKILL_ROOT:-skills}/relay-dispatch/scripts/dispatch.js" . -e codex -b feature-auth -p "..." --rubric-file rubric.yaml

有关后台和并行调度，请参阅 ../relay/SKILL.md § Batch Mode（并行分支流程的唯一事实来源）。

支持的执行器：codex、claude、opencode、pi、antigravity、cursor 和 cline。使用 --executor 选择执行器；使用 --model 明确选择模型，或省略该选项以使用适配器提供商的默认模型。

默认超时时间为 codex: 2400 和 claude/opencode/pi/antigravity/cursor/cline: 1800。能力协商和适配器契约见 references/agent-adapter-platform.md。

选项

CLI 采用封闭的选项契约。不支持的标志会直接报错。

必要标志：

• --branch, -b 会启动一个新的保留运行；--base <ref> 用于选择发布基准（默认为 origin/HEAD；如果缺少 origin/HEAD，则为必填项）。--run-id 会请求在同一运行中重新分派。
• --prompt, -p 或 --prompt-file 用于提供执行器提示词。
• 新分派必须指定 --rubric-file。--done-criteria-file 会冻结一个独立的评审依据；否则，评分标准会被冻结为完成标准。
• --executor, -e 和 --model, -m 用于选择执行方式。指定 --run-id 时，省略 --executor 即可使用 run.json 中绑定的不可变执行器；如果显式指定了不同的执行器，则会在读取提示词或写入尝试记录前失败。--model 仍按每次尝试单独指定。
• --network-access、--timeout、--reasoning 和 --copy 用于配置此次尝试。复制的输入必须是仓库内的常规文件。
• 受信任的 CLI 始终可以使用提供商控制平面传输。受信任的本地分派默认启用工具网络；显式请求 --network-access disabled 属于高级选项，需要适配器原生拒绝网络访问能力；无法强制执行该限制的适配器会安全失败。已弃用的公开 --sandbox 标志会作为未知选项报错；分派始终采用可写工作树语义，适配器和阶段各自负责申请真实的原生文件系统权限。
• CLI 身份验证、HOME、XDG 配置和受支持的令牌变量均来自操作员当前的本地环境。凭据选择器标志已移除，作为未知选项报错；Relay 不会复制身份验证文件，也不会记录其路径。
• 适配器保留实际调用工具及其原生能力声明。提示词措辞不会控制分派准入，也不会选择其他结果或验证契约。
• --fleet-id 必须搭配类型化的 --ownership-json，且其中必须恰好包含 sprint、track 和 component；父级和所有权摘要均不可变。
• --detach 会启动分离运行的分派监督程序，打印回执，并在执行器完成前返回。
• --dry-run 会对输入、分支、能力、注册支持和调用形式进行零写入预检。其 argv 仅用于诊断，绝不能原样启动：生产环境始终使用主机监督程序。
• 分派由自身准入。不存在写入方代际、切换标志或迁移覆盖层：新运行通过对其运行目录执行非递归 mkdir 来认领；如果目录已存在，则会安全失败。
• --json 会为编排返回结构化输出。

持久化目录布局为 ~/.relay/runs/<repo-slug>/<run-id>/：包含不可变的 run.json、done-criteria.md 和 rubric.yaml，仅追加写入的 events.jsonl，以及每次尝试各自的提示词、日志和结果文件。已弃用的路由提示和就绪身份标志不会参与分派。

Relay 直接运行在受信任的本地主机上；它没有文件系统准入机制或配置档编译器。分派始终采用可写工作树语义，并由各适配器和阶段申请各自真实的原生文件系统隔离（Codex 请求 workspace-write，Cursor 请求 enabled，Claude 启用其文档说明的 Bash 沙箱，Antigravity 保留其已声明的标志）。Pi、OpenCode 和 Cline 直接运行。前台模式和 dry-run JSON 会返回非持久化的 filesystem_isolation 请求/有效诊断；缺少隔离或仅有声明的隔离不会拒绝分派。对于不可信工作进程威胁模型，请使用外部容器或 VM。

执行器尝试会保留不可变的输入暂存、可执行程序绑定、超时/取消、继承作用域清理和持久化事实。Relay 本身不会提交、更不会通过 GitHub 路由发布，也不会记录验证或关闭本地结果；这些生命周期操作由规范的 relay-recover recover 负责。 JSON 使用 snake_case。前台输出包含 status、run_id、run_dir、worktree、attempt_id、host_handle、host_status、outcome、inspection，以及非持久化的 filesystem_isolation 和 loopback_listen。分离式启动回执包含 status: "dispatched"、上述持久化标识、dispatcher_pid 和初始 inspection。每次尝试的日志路径会记录在 attempt_started 中。

超时指导

简单任务使用默认值；实现和验证需要更多时间时使用 --timeout 3600；仅在复杂的多文件任务需要较长的最终检查时使用 --timeout 5400。

验证成功状态

将 inspection.recommended_action 作为后续步骤的依据。completed 表示持久化主机和适配器均已成功；failed 表示任一方失败。cancelled 表示已取消或超时。终态结果未成功时，进程会以非零状态码退出。

成功派发会保留工作树。--run-id 调用会先执行只读检查，且仅当折叠后的操作和建议均完全为 redispatch 时才会继续。获取运行锁后，它会再次执行该检查，并要求操作键保持一致，然后才会写入提示词或尝试事实；对于终态、过期、审核、发布、合并和需要操作员处理的操作，系统会拒绝继续。

发布不属于派发流程。派发会记录执行器尝试并返回派生出的操作。若选择了该路径，请先使用 relay-recover inspect，再使用幂等操作 relay-recover recover，以提交并发布确切的 GitHub PR 修订，或关闭已审核的本地结果。

Claude、Codex、OpenCode、Pi 和 Cursor 提示词使用绑定的 stdin 传输方式。Antigravity 和 Cline 是明确的例外，会通过 argv 显示提示词，且提示词上限为 256 KiB，并会暴露在本地进程列表中。主要审核与派发一样，会继承操作员当前的 HOME/XDG CLI 会话；Relay 不会查找或复制身份验证文件。

处理失败

失败	操作
超时或取消	检查保留的工作树和类型化建议；切勿将其视为已完成
执行器或输出解析错误	查看尝试日志/结果，并遵循类型化建议
恢复遭拒	遵循 inspection.recommended_action；派发仅接受完全匹配的 redispatch
发布/本地关闭失败	使用规范的 relay-recover inspect 和幂等的 recover；派发不会发布或关闭
分支冲突	在工作树中解决，或从更新后的 main 创建新的工作树
网络/暂时性错误	等待 30s 后重试一次。若再次失败，请升级给用户处理

恢复和操作员工具

• 任何已中断或被外部更改的运行 → 使用规范的 relay-recover.js inspect 进行检查，然后仅应用其类型化建议：relay-recover.js recover --reason ...；参见 references/recovery-playbook.md。
• 已中断或被外部更改的运行 → references/operator-utilities.md。

注意事项

• dispatch.js 失败时会以非零状态码退出；审核前请先检查。
• 默认情况下，成功派发会保留工作树。
• 如果并行 PR 涉及相同文件，请一次合并一个，并对另一个执行变基。