余小章 @ 大內殿堂

開發環境

• Orca app 1.4.200（還沒裝的話，官方載點在 onorca.dev/download）
• WSL2（Ubuntu 24.04）
• orca-ide CLI

如果是像我一樣透過 AI 助理（例如 Claude Code）在操作 Orca，還要幫它裝上對應的 skill，不然它看不懂這篇文章裡這些 CLI 語法：

npx skills add https://github.com/stablyai/orca --skill orca-cli computer-use orchestration --global -y -a '*'

1. 判斷該不該用 orchestration

在動手之前，我先卡了一下，因為要「叫別的 agent 做事」這件事，其實有好幾種做法，一開始很容易搞混。最直接的是用 Bash 呼叫 CLI，像 copilot --prompt "現在日期、時間?" 這樣就能跑，但整個過程只有自己這個 session 看得到，做完了要嘛同步等，要嘛自己土法煉鋼包一個背景輸出檔。Agent tool 是 Claude Code 自己的 subagent，只能叫 Claude 自己的分身，碰不到 copilot、antigravity 這種外部廠牌的 agent。至於 OMC 的 ask、omc-teams 這類 skill，一樣可以呼叫不同廠牌 agent，只是沒有專門的存活追蹤跟生命週期管理。

Orca orchestration 的重點其實不是「能不能呼叫」，是呼叫完之後有沒有一個你自己也看得到、能手動接管的 terminal，加上一整套 Run/Task/Dispatch 的狀態追蹤。也就是說，只要是需要監督、等待完成、同時協調好幾個 agent 的場景，才輪得到 orchestration 上場；單純丟一個任務就不管了，用前面幾種方式反而比較輕量。

下圖就是用  subagent 建立的任務，可以把焦點切到 subagetn，任務結束後就沒有辦法接著對話。

 

下圖就是用 orca orchestration，用 antigravity agent 建立 copilot agent，可以看到多了一個頁籤，你可以針對新增的 agent 頁籤，進行對話。

2. 解析 CLI 執行檔

Orca 官方文件寫得很清楚，執行檔要照環境判斷，不要憑印象亂猜：

if [ -n "$ORCA_CLI_COMMAND" ]; then echo "USE:$ORCA_CLI_COMMAND"
elif [ -n "$ORCA_DEV_REPO_ROOT" ]; then echo "USE:orca-dev"
else echo "USE:orca-ide"
fi

3. 認識生命週期模型（Run / Task / Dispatch）

orchestration 的狀態模型分三層。Run 是一次協調工作的容器，負責記錄 coordinator 是誰，訊息收發都在這個範圍內；Task 是具體要做的一件事；Dispatch 則是 Task 的一次實際執行嘗試，每次 worker-start 都會產生一個新的 Dispatch ID。

先建 Run：

orca-ide orchestration run-create --objective "查詢當前日期與時間 - 背景任務" --json

拿到 run.id（像 run_860411c169e9 這種格式）之後，worker-start、worker-list 這些指令都要帶著它；只有 check --wait 是例外，因為它就是在同一個 coordinator terminal 裡執行，那個 terminal 本來就跟這個 Run 綁定，不用再重複帶 --run。

4. 派工給多個 agent（worker-start）

每個 agent 各自呼叫一次 worker-start：

orca-ide orchestration worker-start \
  --run run_860411c169e9 \
  --spec "<任務規格>" \
  --task-title "查詢日期時間 - copilot" \
  --worktree current \
  --agent copilot \
  --json

--spec 裡面規格要寫五要素，不然 worker 拿到的任務會太模糊：

• Target：改動範圍
• Change：要產出的具體結果
• Constraints：不可違反的限制
• Ownership：這個 worker 可以動哪些檔案
• Observable acceptance：怎樣算完成

--agent 換成 antigravity、opencode，同一套 spec 就能一次派給三個不同廠牌的 agent。

NOTE：--worktree current 不會自動幫你建新的 Git worktree，是沿用目前這個 workspace，只是開一個新的 agent terminal。這點一開始我以為每個任務都會各自切一份獨立的 worktree，結果查了文件才發現預設行為完全相反，官方寫得很白：「A fresh worker means a fresh agent terminal, not a new Git worktree.」真的要隔離，才需要另外指定 --worktree new-child 或 new-top-level。

5. 背景等待完成通知（check --wait）

check --wait 是阻塞式的，會一直卡著直到有訊息或逾時：

orca-ide orchestration check --wait --types "worker_done,escalation,question" --timeout-ms 600000 --json

這裡我是請旁邊的 AI 助理（Claude Code）幫我丟到背景執行去跑，逾時或收到訊息會自動結束並跳通知，不需要自己一直手動 poll。三個 agent 同時在跑，前景就可以繼續做別的事，等通知回來再處理就好。

6. 判讀 liveness 狀態（unverifiable / live / exited）

worker-list 可以查每個 worker 目前的狀態：

orca-ide orchestration worker-list --run run_860411c169e9 --include-remote --json

projection.liveness.verdict 只有三種值：unverifiable、live、exited；另外還有一個 stage.activity 欄位會顯示 working、done 這類值，是跟 verdict 分開的另一個欄位，兩個不要搞混。重點是 unverifiable 不能拿來當作失敗的證據，只是「查不到而已」，不代表真的掛了，貿然拿它去 worker-stop 或 worker-abandon 是不對的。

7. 收尾釋放資源（worker-release / terminal close）

任務正常結束後，依狀態三選一：重用、worker-retain 保留、或 worker-release 釋放。如果 worker 是卡住、liveness 又判不清楚死活，就不算這三選一的情境，要用上一節提到的 worker-stop（terminal 沒被接管時直接關掉）或 worker-abandon（terminal 被接管、或不想動它時，只解除 orchestration 追蹤）來處理。這次遇到一個狀況是 worker-release 直接被拒絕：

{
  "state": "retained",
  "reason": "identity_unproven",
  "processAction": "none"
}

identity_unproven 代表 orchestration 這邊已經沒辦法確認這個 terminal 的身分是不是還是原本那個 Dispatch 開出來的，所以拒絕動它，狀態維持 retained。這種情況只能退一步，直接對 terminal handle 下 terminal close：

orca-ide terminal close --terminal term_2ffc8a6a-d87b-4818-b533-8df6c2f58e7f --tab --json

結果回傳 terminal_handle_stale，意思是這個 terminal 其實早就已經被關掉了，我這個關閉動作只是多此一舉。最後用：

orca-ide orchestration worker-list --run run_860411c169e9 --terminal-state reclaimable --json

確認回傳空陣列，才算真的收乾淨，沒有留下還欠決定的資源。

8. Prompt 怎麼寫：幾個實際場景範例

CLI 指令本身都差不多，真正決定這次派工好不好用的是要怎麼把一整條「派工 → 審查 → 修正 → 合併」的流程講清楚。同一份 prompt 派給所有 agent 可以當健康檢查用，這篇前面查日期時間就是這種用法，內容簡單，重點只是確認每個 agent 都活著。真正在做事的時候，通常是把整條流程一次寫給 coordinator，讓它自己去拆成好幾個 Dispatch，底下記幾個自己會用的寫法。

第一種是最基本的「實作 → 審查 → 修正 → 合併」四段式：

/orchestration
建立任務1
1. 沿用目前 worktree
2. antigravity agent 依計畫書第一階段實作
3. copilot agent 審查（code review + 資安掃描）
4. antigravity agent 依審查意見修正
5. 跑一次自動測試確認修正有效
6. 合併 main，推上 GitHub

出手改東西的跟審查的不是同一個 agent，等於自動排了一次同儕審查，比較不會球員兼裁判；修正完不直接合併，中間補一道測試，免得改壞了自己沒發現。

NOTE：orca orchestration 沒有支援直接用 copilot agegnt 指定模型，改用 terminal → copilot → /model，

- 改用 copilot 自己的互動式 `/model` 選單：
  `terminal create --command "copilot"` → `wait --for tui-idle` →
  `send --text "/model" --enter` → `send --text "<關鍵字>"` →
  `send --text "" --enter` 選取 → `dispatch --inject`。

 

第二種是把 TDD 的紅燈確認也寫進流程裡，不是改完就算數：

/orchestration
建立任務2
1. 開新的 worktree
2. antigravity agent 重現 Bug，補一支會失敗的 BDD 測試，確認紅燈
3. opencode agent 依測試修復 Bug，確認轉綠燈
4. copilot agent 做最後一次 review
5. 沒過就退回步驟 3
6. 合併 main，推上 GitHub

這樣 agent 要自己證明有先看到測試失敗、再看到測試通過，跟平常寫測試該走的流程一樣，沒有偷跳步。

第三種是遇到動到共用資源、後悔不了的操作，中間硬塞一個人工關卡：

/orchestration
建立任務3
1. 沿用目前 worktree
2. claude 產生 migration script
3. decision gate：暫停，等我看過 SQL 才繼續
4. 核准後 copilot 套用到測試環境
5. 驗證通過才推 main

像改資料庫結構這種操作，就是不能放給 agent 自己看著辦，卡一個 decision gate 逼自己一定要看過才放行。這種「什麼時候該停下來問人」的邊界，最好寫進 prompt 裡，而不是留給 agent 自己判斷，不然出事了要收拾的還是自己。

第四種是把 UI 規劃跟 E2E 驗收測試也拆進不同階段，不是實作完自己說了算：

/orchestration
建立任務4
1. 沿用目前 worktree
2. antigravity 規劃 UI 版面與元件結構
3. copilot 依規劃實作前端頁面
4. opencode 撰寫 Reqnroll + Playwright 的 E2E 驗收測試
5. E2E 全部通過才算完成，沒過退回步驟 3
6. 合併 main，推上 GitHub

規劃版面跟寫程式碼分開派給不同 agent，是因為兩者要用的判斷不一樣，各自專注會做得比較好；驗收也不是實作的人自己說一句「應該可以了」，是拿專案本來就規定的 Reqnroll BDD 搭配 Playwright，跑一次真正的瀏覽器操作，過了才算數。

第五種是先求有再求好，測試案例分兩階段產出：

/orchestration
建立任務5
1. 沿用目前 worktree
2. antigravity 依需求產生第一版 .feature 測試案例
3. copilot 檢視案例覆蓋度，列出遺漏的邊界情況
4. antigravity 依意見補齊案例、精煉 Given/When/Then 敘述
5. 產出的 .feature 給我人工過目，確認案例夠不夠貼近需求

第一版測試案例通常只顧得到主要情境，邊界案例、例外流程都還沒想到，與其要求一次寫到位，不如先讓一個 agent 快速產出骨架，再換一個角度去挑漏洞，把案例補齊、敘述寫精確，最後才交給人看一眼，這樣比自己從零盯著寫案例輕鬆很多。

最後一種，把各個角色、職責定義清楚

/orchestration
建立以下 ai agent，負責接收 main session 的任務
Worker1. 用來實作程式碼，copilot agent + 'Claude Sonnet 5' model。
Worker2. 用來審核文件、審核程式碼，copilot agent + 'GPT-5.5' model。
Worker3. 用來寫文件，copilot agent + 'GPT-5.6 Luna' model。
注意：
1. 當前 session 是主要任務
 - 負責命令派送給 agent。 
 - 提交、推上版控。
 - 問題互動。
2. agetn 開起來等待任務派送，不要隨便關閉 agent。

心得

• orchestration 的價值不在「能不能呼叫外部 CLI」，這件事 Bash 也做得到，重點是它把每個 agent 跑起來的過程變成可稽核的狀態，你隨時能查、也能手動介入。
• worktree 預設不會幫你隔離，共用同一份 workspace 讓多個 agent 同時跑，真的要注意會不會互相改到同一個檔案

 

若有謬誤，煩請告知，新手發帖請多包涵

Microsoft MVP Award 2010~2017 C# 第四季
Microsoft MVP Award 2018~2025 .NET