yasyf/orca

Orca 工作者

先載入版本相符的指南：orca skills get orca-cli 和 orca skills get orchestration。此技能定義了工作者進入點和原始碼回傳契約。

此處的每個 orca orchestration 指令都會傳遞 --full：自 Orca 1.4.246 起，若不加此參數則會印出精簡檢視，而該檢視會省略這些步驟所需的欄位。orca-worker-launch.sh 和 orca-reclaim.py（位於此插件的 bin/ 目錄中，並已加入 PATH）本身就會傳遞 --full --json。請從專案檢出的根目錄執行這兩個腳本。

儲存庫設定值

啟動工作者的儲存庫必須在其根目錄中檢入 .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	local
baseBranch	WORKER_BASE_BRANCH，本地工作目錄的起始分支	local
sparse	引導 WORKER_SPARSE，即本地工作目錄的稀疏錐體設定	local

已設定的環境變數優先於對應的設定檔鍵值，而 WORKER_SPARSE 會在檔案指定的錐體目錄之後額外加入目錄。每個鍵都是選填的；如果儲存庫沒有 .orca.json，則需自行傳遞這些變數。

啟動工作者

實作與測試工作者預設會使用一個未使用的預先安裝 Sprite agents 工作區。啟動器會獨佔式地宣告該工作區使用權，淺層更新請求的參照（ref），準備代理，並以一次調用附加原生 Task。當沒有相容的未使用工作區可用時，會為此 Lane 建立新的工作區。每次分配都會在背景啟動一個有限的填充任務，目標是達到設定檔中 orca.pool.ready 指定的數量，因此連續啟動可以取得「暖的」（warm）工作區。被宣告的工作區在完成後會保持被宣告狀態；重複使用保留的代理需要一個明確的新的原生 Dispatch。

Sprite Lane 名稱最多 55 個小寫字母、數字和連字號，且必須以字母或數字開頭：

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

請從已經擁有該命名原生 Run 的終端機執行此指令。腳本會在分配前檢查該綁定，調用 cc-remote orca prepare --warm 一次，然後透過在 Sprite 的 Orca 伺服器上執行一次原生 worker-start 來啟動已準備就緒的空閒工作者，並重複使用已準備好的終端機和工作目錄。Prepare 會將完整的簡報（brief）複製到虛擬機器中，並記錄其雜湊值、長度和實際的檢出 HEAD。第一個 Task 是指標，告訴工作者讀取並驗證該檔案。

Prepare 會透過 Sprite 的 orca CLI 啟動其 Orca 執行時期，而 Orca 1.4.224 則會在其受管理的伺服器 orcad 上提供服務。準備好的 Task 會將該伺服器的建置版本記錄為 managedServer，此資訊來自於 orca serve --json 印出的就緒事件。當此欄位遺失時，腳本不會啟動任何東西，這表示 Orca 已回退到 Electron 模式。Orca 的原因記錄在 Sprite 上的 ~/.cc-remote/orca/serve.log 檔案中的 [serve] 行。

啟動器會使用 WORKER_CC_REMOTE 或 ccRemote 指定的 CLI，以及 CC_REMOTE_CONFIG 或 ccRemoteConfig 指定的設定檔。如果兩者都沒有設定 CLI，則會執行 PATH 中的 cc-remote，這可能導致長時間運行的 session 或較新的 Homebrew 安裝持有不同的版本。因此，需要固定其版本的儲存庫應在 ccRemote 中指定其包裝腳本。缺少設定檔的 Sprite 啟動會在分配前拒絕執行。

cc-remote 僅在 CLI 版本與設定檔中 orca.bootstrap_helper 的版本完全相符時，才能準備 Sprite；較新或較舊的修補版本都會失敗。因此，CLI 的固定版本與 helper 的版本必須同步更新。在分配前，啟動器會比較所選 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 路由上設定此變數會導致在嘗試或分配前就拒絕。啟動器不會將本地 repo ID 映射到遠端儲存庫。

可以提供另一組二進位檔案/設定檔配對，例如一個 runner 在其檢出目錄移動時仍保留一個版本：

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 指定遠端分支或標籤，並會原封不動地傳遞；如果省略，則設定檔會提供其參照。WORKER_BASE_BRANCH 屬於明確的本地工作目錄路由。請勿將其作為遠端分支傳遞、剝離任意前綴，或將請求的參照取代為來自本地預查詢的提交 ID。準備好的記錄中的 baseCommit 是實際的 VM 基礎。在遠端路由上設定 WORKER_BASE_BRANCH 會導致拒絕；WORKER_REF 和 WORKER_EXPECT_BASE 在本地路由上也會被拒絕。

一般性的分支移動是允許的。僅當任務需要精確的基礎時，才設定 WORKER_EXPECT_BASE。請提供一個完整的 40 或 64 字元小寫提交 ID。啟動器會在準備後進行比對；如果比對失敗，將保留空閒的已準備工作者，並在執行 worker-start 之前停止。此比對不會影響檢出的選擇。Prepare 沒有單獨的精確提交檢出選項；即使分支或標籤名稱看起來像十六進位數字，它仍然會被視為一個參照。

請保留所選的模型和努力程度。WORKER_SERVICE_TIER 會原封不動地傳遞一個明確的 Codex 服務層級；如果與 Claude 模型一起使用則會拒絕。快速（fast）層級僅供事件 Lane 使用：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 中對同一個 Lane 的第二次啟動會恢復其現有的工作目錄；如果之前嘗試建立的工作目錄已經消失，則啟動會拒絕，因為名稱絕不會被建立兩次。

新的本地工作目錄會根據 sparse 設定進行稀疏檢出，接著是 WORKER_SPARSE 指定的目錄（以空格分隔）；如果兩者皆為空，則為完整檢出。啟動器會印出 widen 指令。稀疏 Lane 的簡報會包含「此 Lane 是稀疏的：在讀取外部檔案前，請使用 git sparse-checkout add <dir> 來擴展範圍」。

如果 WORKER_LOCAL 未設定或為空，則選擇 Sprite；任何其他非空值都會被拒絕。本地路由只會啟動 Claude，並拒絕 Codex 模型。遠端 Fable 會在準備前被拒絕；它絕不會變成本地啟動或使用不同的模型。本地的 Claude 會保留機器上現有的互動式驗證和任務範圍內的略過行為。它會在 lane_env 和 lane_settings 下以精簡模式啟動，沒有自動更新、原生 ~/.claude 監視器、動畫、遙測或狀態列，並且 lane_denied_tools 會阻止其暫停等待人類操作。互動式 session 和 claude plugin update 仍會更新外掛快取。設定 CLAUDE_LANE_SETTINGS 為一個 JSON 物件以加入本機設定。

僅啟動任務允許清單中指定的 Model Context Protocol 伺服器。在 Sprite 上，WORKER_MCP_CONFIG 會傳遞一個內聯的 JSON 物件（給 Claude）或內聯的 TOML 表格（給 Codex）作為 --mcp-config 參數傳給 prepare；它並非本機檔案路徑。在本機路由上，該值遵循 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 及其原生 hooks 會保留 API 呼叫所需的環境。這些排除項目在繞過模式下不提供程序或檔案系統隔離。

請將 API 憑證保留在遠端 actor 及其允許的子程序中。Actor 局部的 hook 求值器可以將選定的金鑰傳遞給短命的推理子程序。請勿將金鑰放入常駐的 hook daemon、映像檔、工件、日誌、共用檔案和全域設定中。請勿全域設定 API 金鑰變數、取代本機互動式驗證，或將 OAuth 重新整理令牌或完整的驗證快取複製到工作者。

每個簡報會在其旁邊宣告一個 <brief-stem>.worker 檔案。對於 /briefs/lane-a.md，該檔案是 /briefs/lane-a.worker。已存在的目錄、連結、失敗的嘗試，或舊版的 <brief-stem>.dispatch.json 都會拒絕重播。該目錄會記錄 request.json，其中包含請求的路由、模型、努力程度、層級、參照、可選的預期基礎，以及本機簡報的雜湊值/位元組數。

遠端路由會保留原始的 allocation.json、prepare.err 和 prepare.status。它會驗證請求的 Lane、實際工作區、請求的參照、分配類型、Task HEAD、代理、簡報、環境、終端機和 <repoId>::<projectRoot> 工作目錄，然後將 Task 提取到 prepared.json 中。接著，它會使用 --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，即 VM 上的檢出路徑。請使用該實際工作區進行後續的 cc-remote orca collect 呼叫。失敗或未經驗證的啟動不會印出成功 JSON，且會保留嘗試記錄，但不會重試或清理。

分別進行準備與附加

當需要分別檢查準備和第一個 Task 的附加過程時，請使用上述所選的 CLI 和設定檔。此明確的「全新 Sprite agents」範例會回傳一個純粹已準備的 Task：

"<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 會啟動所選的代理並停留在原生的空閒狀態，不會發送其 Task。在附加之前，要求指令退出碼為零、prepared:true、請求的 model/effort、實際的 baseCommit，以及確切的 brief 雜湊值和長度。對於 Codex 任務，請保留其請求的代理類型、模型、努力程度和明確的服務層級。將 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>"

這會重複使用已準備的終端機和工作目錄，並建立一個指向完整簡報的原生 Task。請勿傳遞 agent、model、effort 或 service tier，以便已準備的程序保留其自身的設定。就緒回執會包含 Task 和 Dispatch 的名稱。現有的收件匣所有者會處理它們的訊息；請勿發送第二個 Task 指標或啟動另一個消費者。接受完成後，保留該 session 並使用原始碼回傳與收集契約。在所有情況下都應保留回執。全新建立失敗時，可以執行正常的 CLI 回滾；報告實際的剩餘資源，切勿重播任何結果不明確的嘗試。

在已記錄的工作區上啟動第一個工作者

版本 0.15.0 為第一個工作在已記錄的精確工作區和保留的檢出上新增了 --existing 僅準備選項：

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort high --ref "<same-ref>" \
  --brief-file "<complete-brief.md>"

僅在準備前該工作區的狀態與記錄完全相符時，此指令才會成功。它會跳過工作區分配和代理安裝步驟，直接附加到現有的閒置程序。使用方式與上述「分別進行準備與附加」相同。

回傳原始碼供根檢閱

工作者完成後，orca-reclaim.py 會回傳原始碼。它會收集下列內容：

• 工作目錄中的完整原始碼樹
• brief.worker 目錄中的所有工件
• orca orchestration session-get --full --json 的輸出
• 每個 Task 的最終狀態和結果

從專案根目錄執行：

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

這會建立一個以 Lane 和時間戳記命名的壓縮包，並將其放置在 reclaims/ 目錄中。壓縮包包含一個 manifest.json，其中列出所有檔案、Task 結果和會話資料。根檢閱者可以解壓縮此包來審查工作者的完整輸出和狀態。

收集與清理

使用 cc-remote orca collect 從 Sprite 工作區收集工件：

"<selected-cc-remote>" orca collect "<workspace>" --output-dir "<output-dir>"

這會將工作區的工件複製到指定的輸出目錄。收集完成後，可以使用下列指令釋放工作區：

"<selected-cc-remote>" orca release "<workspace>"

對於本地工作目錄，只需刪除工作目錄即可：

rm -rf "<lane>-<run-id-hash>"

故障排除

工作者啟動失敗

檢查 prepare.err 和 worker-start.err 以了解失敗原因。常見問題包括：

• CLI 版本與 bootstrapHelper.version 不符
• 無法驗證 Mac 上的 Gatekeeper 問題
• 無可用空間或不夠的資源
• API 金鑰遺失或無效

API 金鑰隔離

請務必遵循上述 API 金鑰隔離規則。常見的錯誤包括：

• 在全域設定 API 金鑰，導致它們洩漏到工作者外的程序
• 將 API 金鑰包含在工件或日誌中
• 複製 OAuth 重新整理令牌到工作者

網路問題

Sprite 工作者需要存取 Orca 伺服器和 Git 遠端。確保網路安全群組允許必要的流量。對於本地工作者，確保本機網路允許存取必要的服務。

安全性考量

此技能定義了處理敏感資料和 API 憑證的工作者啟動協議。主要的安全風險包括：

• 將 API 金鑰洩漏給未經授權的程序
• 未經授權存取工作者工作區
• 處理敏感簡報時不足的資料隔離

始終遵循此處定義的隔離規則。對於極度敏感的工作，使用 WORKER_LOCAL=1 和 Fable 模型，確保資料不會離開本機。

版本注意事項

• Orca 1.4.224：在 Sprite 上引入了 orcad 受管理伺服器
• Orca 1.4.246：變更了 orca orchestration 的預設輸出為精簡模式，需要 --full
• cc-remote 0.15.0：引入了 --existing 僅準備選項

在升級各個元件時，請務必檢查版本相容性。