yasyf/orca

Orca workers

首先加载版本匹配的指南：orca skills get orca-cli 和 orca skills get orchestration。此技能定义了 worker 入口点和源码返回契约。

此处的每个 orca orchestration 命令都传递 --full：自 Orca 1.4.246 起，没有该标志时会打印简洁视图，这会丢弃这些步骤读取的字段。orca-worker-launch.sh 和 orca-reclaim.py 位于此插件的 bin/ 目录中，位于 PATH 上，它们本身会传递 --full --json。从检出根目录运行两者。

仓库值

启动 worker 的仓库会在其根目录中检入 .orca.json，两个工具都从工作目录读取它：

{
  "ccRemote": "tools/cc-remote/bin/cc-remote",
  "ccRemoteConfig": "tools/cc-remote/config.yaml",
  "repo": "<orca-repository-id>",
  "baseBranch": "origin/main",
  "sparse": [".agents", ".claude"]
}

键	它填充的环境变量	路由
ccRemote	WORKER_CC_REMOTE，cc-remote CLI，从检出根目录或 PATH 名称的路径	Sprite，和 orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG，cc-remote 配置，从检出根目录	Sprite，和 orca-reclaim.py
repo	WORKER_REPO，Orca 仓库 ID	本地
baseBranch	WORKER_BASE_BRANCH，本地工作树起始的分支	本地
sparse	引领 WORKER_SPARSE，本地工作树的稀疏锥	本地

已设置的环境变量优先于其键，而 WORKER_SPARSE 在文件锥之后添加目录。每个键都是可选的，没有 .orca.json 的仓库会自行传递变量。

启动一个 worker

实现和测试 worker 默认使用未使用的预安装 Sprite agents 工作空间。启动器独占性地声明它，浅层刷新请求的 ref，准备 agent，并一次性附加原生 Task。当没有兼容的未使用工作空间可用时，它会创建通道的工作空间。每次分配都会启动一个有限的后台填充，直到达到配置的 orca.pool.ready，因此连续启动会声明为热启动。已声明的 worker 在完成后保持声明状态；重用保留的 agent 需要显式的全新原生 Dispatch。

Sprite 通道名称最多包含 55 个小写字母、数字和破折号，并以字母或数字开头：

WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" "<model>" "<effort>" "<brief.md>"

从已拥有命名原生 Run 的终端运行此命令。脚本在分配前检查该绑定，调用 cc-remote orca prepare --warm 一次，然后通过一次原生 worker-start 在 Sprite 的 Orca 服务器上启动准备好的空闲 worker，重用其准备好的终端和工作树。Prepare 将完整的 brief 复制到虚拟机并记录其哈希、长度和实际检出 HEAD。第一个任务是一个指针，告诉 worker 读取并验证该文件。

Prepare 通过其 orca CLI 启动 Sprite 的 Orca 运行时，Orca 1.4.224 在其托管的服务器 orcad 上提供服务。准备好的任务将该服务器的构建记录为 managedServer，从就绪事件 orca serve --json 打印的内容中读取。当该字段缺失时，脚本不会启动任何内容，这意味着 Orca 回退到了 Electron。Orca 的原因在 Sprite 上的 ~/.cc-remote/orca/serve.log 中的 [serve] 行。

启动器运行 CLI WORKER_CC_REMOTE 或 ccRemote 命名的命令，针对配置 CC_REMOTE_CONFIG 或 ccRemoteConfig 命名的配置。如果两者都没有设置 CLI，则运行 PATH 上的 cc-remote，其中长期会话的 PATH 或更新的 Homebrew 安装可能包含另一个版本，因此固定其版本的仓库在 ccRemote 中命名其包装器。没有配置的 Sprite 启动在分配前拒绝。

只有当 CLI 是配置的 orca.bootstrap_helper 的确切版本时，cc-remote 才会准备一个 Sprite；较新的补丁版本会像较旧的一样失败，因此 CLI 固定和帮助程序在一次固定更改中一起移动。在分配之前，启动器将所选 CLI 打印的 version 与配置旁边的 agents-payload.json 的 bootstrapHelper.version 进行比较，解析链接，并拒绝差异，同时命名两者。cc-remote 本身也进行相同的检查，但热声明在备用的空间被声明后才到达它，然后该备用空间保持声明为失败状态。如果配置旁边没有 agents-payload.json，则检查留给 cc-remote。

当新安装的签名版本在 Mac 上首次启动时停滞不前，请自行恢复。这是安装恢复，绝不是向所有者提出的问题。验证所选可执行文件是签名版本，从该文件中删除 com.apple.quarantine，然后重试其版本命令：

exe="$(readlink -f "<selected-executable>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<selected-cc-remote>" version

当属性已经消失时，xattr 会打印 No such xattr。切勿传递 -r、命名目录或更改 Gatekeeper 的系统策略。

启动器不传递 --config。它将 CC_REMOTE_CONFIG 导出为绝对路径给 cc-remote，相对值从调用者的目录解析。所选配置命名 Sprite 检出的仓库。WORKER_REPO 仅选择本地 Orca 仓库；在 Sprite 路由上设置它会在尝试或分配之前拒绝。启动器不将本地仓库 ID 映射到远程仓库。

提供另一个二进制文件/配置对，例如一个保持一个版本而检出移动的运行器，如下所示：

WORKER_CC_REMOTE=/absolute/path/to/cc-remote \
CC_REMOTE_CONFIG=/absolute/path/to/config.yaml \
WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

WORKER_REF 命名一个远程分支或标签并原样传递；省略时，配置提供其 ref。WORKER_BASE_BRANCH 属于显式本地工作树路由。不要将其作为远程分支传递，不要去除任意前缀，也不要用来自本地预查找的提交 ID 替换请求的 ref。准备好的记录的 baseCommit 是实际的 VM 基础。在远程路由上设置 WORKER_BASE_BRANCH 会拒绝；WORKER_REF 和 WORKER_EXPECT_BASE 在本地路由上会拒绝。

普通分支移动是有效的。仅当任务需要确切的基础时才设置 WORKER_EXPECT_BASE。提供一个完整的 40 或 64 字符小写提交 ID。启动器在准备后比较它；不匹配会保留空闲的准备好的 worker 并在 worker-start 之前停止。此比较不选择检出。Prepare 没有单独的确切提交检出选项，并且即使其拼写看起来是十六进制，分支或标签名称仍然是 ref。

保留选定的模型和努力级别。WORKER_SERVICE_TIER 原样传递显式的 Codex 服务层；它会在使用 Claude 模型时拒绝。快速层仅用于事件通道：WORKER_SERVICE_TIER=fast 除非设置了 WORKER_INCIDENT=1，否则拒绝。没有层时，启动器不传递服务层标志，codex 在标准层运行。

将 WORKER_LOCAL=1 用于本地根任务，该任务运行 Opus，或用于根授权的极端敏感工作，这是使用 Fable 的唯一情况：

WORKER_RUN="<owned-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

如果没有仓库和基础分支，从 WORKER_REPO 和 WORKER_BASE_BRANCH 或 repo 和 baseBranch 中获取，本地路由会拒绝。

本地工作树命名为 <lane>-<Run ID 的 SHA-256 的前 8 个十六进制字符>，因此两个 Run 永远不会使用同一个名称。在同一 Run 中为该通道第二次启动会恢复其活动的工作树；当较早尝试创建的工作树消失时，启动会拒绝，因为名称永远不会被创建两次。

新的本地工作树在 sparse 上稀疏，后跟 WORKER_SPARSE 命名的目录（空格分隔），当两者都为空时是完整检出。启动器会打印 widen 命令。稀疏通道的 brief 带有“此通道是稀疏的：在外部读取之前使用 git sparse-checkout add <dir> 扩大范围”。

未设置或为空的 WORKER_LOCAL 选择 Sprite；任何其他非空值都会拒绝。本地路由仅启动 Claude 并拒绝 Codex 模型。远程 Fable 在准备前拒绝；它永远不会变成本地启动或不同的模型。本地 Claude 保留机器的现有交互式身份验证和任务作用域绕过行为。它在 lane_env 和 lane_settings 下以剥离方式启动，没有自动更新、原生 ~/.claude 监视器、动画、遥测或状态行，lane_denied_tools 阻止它停车在人工上。交互式会话和 claude plugin update 仍然会更新插件缓存。设置 CLAUDE_LANE_SETTINGS 为 JSON 对象以添加本地设置。

仅启动任务允许列表中命名的 Model Context Protocol 服务器。在 Sprite 上，WORKER_MCP_CONFIG 将内联 JSON 对象传递给 Claude 或内联 TOML 表传递给 Codex 作为 prepare 的 --mcp-config；它不是本地文件路径。在本地路由上，该值遵循 Claude 的 --mcp-config 语法。

远程 Claude 和 Codex 使用来自 cc-remote 配置的回调的专用 API 密钥。Claude 使用正常的 API 环境身份验证；其普通工具进程可能继承这些密钥。对于 Codex，固定的 CLI 从内置 shell 工具中排除 OPENAI_API_KEY、CODEX_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 CLAUDE_CODE_OAUTH_TOKEN。actor 及其原生钩子保留 API 调用所需的环境。这些排除在绕过模式下不提供进程或文件系统隔离。

将 API 凭据保留在远程 actor 及其允许的后代中。Actor 本地钩子评估器可以将选定的密钥传递给短期的推理子进程。将密钥保留在驻留的钩子守护进程、映像、工件、日志、共享文件和全局配置之外。不要全局设置 API 密钥变量，不要替换本地交互式身份验证，也不要将 OAuth 刷新令牌或整个身份验证缓存复制到 worker。

每个 brief 都会在 brief 旁边声明 <brief-stem>.worker。对于 /briefs/lane-a.md，那是 /briefs/lane-a.worker。现有的目录、链接、失败的尝试或遗留的 <brief-stem>.dispatch.json 会拒绝重放。该目录记录了 request.json，其中包含请求的路由、模型、努力级别、层、ref、可选预期基础以及本地 brief 哈希/字节。

远程路由保留原始的 allocation.json、prepare.err 和 prepare.status。在将任务提取到 prepared.json 之前，它会验证请求的通道、实际工作空间、请求的 ref、分配类型、任务 HEAD、agent、brief、环境、终端和 <repoId>::<projectRoot> 工作树。然后它使用 --on 准备好的环境、--worktree id:<worktreeId> 和 --terminal 准备好的终端运行 worker-start。两条路由都保留 worker-start.json、worker-start.err 和 worker-start.status。在每种结果下都保留这些文件。

成功要求 worker-start 退出码为零，并且收据显示 ok、状态 ready、拥有的 Run 以及可打印的 Task 和 Dispatch ID。失败收据中的 ID 不会使其就绪。成功会打印一行 JSON，其中包含字段 state、task、dispatch、terminal 和 worktree。

在 Sprite 上，JSON 还命名了 lane、实际的 workspace 和 allocation（warm 或 created）。terminal 是 prepared.terminal，worktree 是 prepared.projectRoot，即虚拟机上的检出。将该实际工作空间用于后续的 cc-remote orca collect 调用。失败或未经证实的启动不会打印成功 JSON，并保留尝试而不重试或清理。

分别准备和附加

当需要单独检查准备和第一个任务附加时，使用上述选定的 CLI 和配置。此显式的全新 Sprite agents 示例返回一个简单的准备好的任务：

"<selected-cc-remote>" orca prepare "<lane>" --config "<configured-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Prepare 启动选定的 agent 并在原生空闲状态停止，而不发送其任务。在附加之前，要求命令退出码为零、prepared:true、请求的模型/努力级别、实际的 baseCommit 以及确切的 brief 哈希和长度。对于 Codex 分配，保留其请求的 agent 类型、模型、努力级别和显式服务层。将 API 凭据保留在配置的仅进程回调中。

从已经拥有 Run 的协调器，使用准备好的记录的字段和一个新的收据文件附加一次：

orca orchestration worker-start --run "<owned-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane>: read the whole brief at <brief.path>, verify its SHA-256 is <brief.sha256> and its size is <brief.bytes> bytes, then follow it exactly." \
  --full --json >"<new-receipt.json>"

这会重用准备好的终端和工作树，并创建带有指向完整 brief 的指针的原生 Task。不要传递 agent、模型、努力级别或服务层，以便准备好的进程保留自己的。就绪收据命名 Task 和 Dispatch。现有的收件箱所有者处理它们的消息；不要发送第二个任务指针或启动另一个消费者。在接受完成后，保留会话并使用源码返回和收集契约。在每种结果下都保留收据。全新创建失败可以运行正常的 CLI 回滚；报告实际剩余资源，并且永远不要重放模糊的尝试。

第一个 worker 在记录的工作空间上

版本 0.15.0 添加了仅准备的 --existing，用于在确切的记录工作空间和保留的检出上的第一个 worker：

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --brief-file "<complete-brief.md>" \
  --ref "<branch-or-tag>" >"<reuse-prepared.json>"

此变体不分配或创建工作空间；它验证现有工作空间具有相同的配置 profile，使用其保留的检出而不获取，仅启动 agent 并记录状态。当没有剩余的新工作空间且记录的工作空间存在时使用它。在附加之前，验证 prepared:true、模型、努力级别、baseCommit 和 brief 完整性。导出 WORKER_WORKSPACE 为记录的名称以隔离此路径。当记录的工作空间缺少预期的 agent、模型或检出时，准备拒绝。

从 --existing 准备返回的 JSON 包含 workspace（记录的名称）和 allocation: "existing"，而不是 warm 或 created。将 allocation 传递给 worker-start 以避免在服务器端进行双重记录。

Worker 回收

此部分定义了 orca-reclaim.py 的行为，在 bin/ 中可用。

orca-reclaim.py 从已结算的派遣中回收资源。它在 orca orchestration dispatch 后运行，并清理与该派遣关联的 worker 和任务。脚本使用与启动器相同的 .orca.json 配置和命令行界面。

orca-reclaim.py --run "<run-id>" --dispatch "<dispatch-id>"

脚本执行以下操作：

1. 验证派遣已结算（状态为 completed、failed 或 cancelled）。
2. 如果派遣是 Sprite 路由，则调用 cc-remote orca collect 来释放工作空间。
3. 如果派遣是本地路由，则删除工作树（worktree remove）。
4. 清理与派遣关联的 .worker 目录。
5. 记录回收结果到日志。

不要在正在进行的派遣上调用回收。仅对已结算的派遣使用。永远不要使用收据中的未打印 ID 调用回收。

源码返回以供根审查

当 worker 完成其任务时，它会将结果源码返回到一个由根审查的指定位置。此契约由 worker 和协调器使用。

对于 Sprite 路由，worker 通过 orca orchestration source-return 命令返回源码，该命令将结果打包并传输到源仓库。对于本地路由，worker 只是保留其在本地工作树中的更改，协调器可以从中检入。

两种路由都记录返回的源码的提交哈希。根审查者可以使用此哈希来验证任务的输出。

Worker 完成信令

worker 通过以下方式发出完成信号：

• 写出一个包含结果摘要的 <brief-stem>.result.json 文件。
• 向协调器的收件箱发送一条包含任务 ID 的完成消息。

协调器会轮询这些信号，并在收到后触发回收序列。

故障排除

常见错误

错误	原因	解决方案
prepare failed: version mismatch	CLI 版本与 bootstrapHelper.version 不匹配	使用 orca skills get orca-cli 更新 CLI
worker-start failed: lane not found	通道名称不存在于 Orca 中	验证通道名称
reclaim failed: dispatch not settled	在派遣完成前调用回收	等待派遣结算
local route refused: no repo	缺少 WORKER_REPO 或 .orca.json 中的 repo	设置仓库 ID

日志

所有日志都写入启动器的 ~/.orca/logs/ 目录。日志文件按时间戳命名，并包含启动、worker-start 和回收操作的详细信息。在调试问题时，检查这些日志。

安全注意事项

• 切勿在 worker 之间共享 API 密钥。
• 仅将 API 密钥传递给授权的钩子子进程。
• 不要将 API 密钥存储在工件或日志中。
• 在启动 worker 之前验证通道名称和运行 ID。
• 对敏感任务使用本地路由以避免网络暴露。
• 对最敏感的工作使用 Fable 模型。

另请参阅

• orca skills get orca-cli - Orca CLI 参考
• orca skills get orchestration - Orca orchestration API 参考
• cc-remote --help - cc-remote 命令参考