執行機群工作程序
在備用機器上執行 cc_worker，即可為你的機群增添執行容量。它是一個純 Dart
二進位檔——不含 Flutter 引擎——會與一個 cc_server 配對、宣告主機的能力、
傳送心跳、拉取租約作業、執行這些作業，並把處理程序事件串流回傳。它不保存任何
持久狀態：監督程式將它重新啟動後，它會重新註冊。
你需要先有一個執行中的 cc_server——請參閱執行無介面伺服器。
已配對的工作程序會註冊、傳送心跳，並等待租約作業。請以 fleet.submitJob
提交工作。這台伺服器上的代理派送不會經過機群；本指南的成功訊號，是工作程序
帶著最新的心跳出現在機群面板中。開機時註冊的行程內工作程序，其執行器對應表
是空的，因此放到它上面的作業會傳回 No local runner for job kind …。
先決條件
標題為「先決條件」的章節- Dart SDK。這個儲存庫以 fvm 固定其 SDK 版本，因此指令請加上
fvm前綴。 - 在工作程序機器上檢出這個儲存庫。
- 一個可觸及的
cc_server（開發時用回送，正式環境用區域網路或遠端）。 PATH中有git——工作程序會具體化儲存庫並執行git探測。
步驟 1：建置二進位檔
標題為「步驟 1：建置二進位檔」的章節cd apps/cc_workerfvm dart build cli這會在 ./build/cli/<os_arch>/bundle/bin/cc_worker 產生一個自足的套件組合。
步驟 2：簽發工作程序的憑證
標題為「步驟 2：簽發工作程序的憑證」的章節cc_server 只接受出示已配對裝置 ID 與預先共用金鑰的工作程序——回送伺服器也
不例外。請在伺服器機器上簽發它們（伺服器運作時也能執行 pair；新的裝置
不必重新啟動就會被納入）：
cc_server pair --data-dir <dir> --device my-worker --label "Build box"它會印出 Device id 與 Pairing key——這些就是 --device-id 以及
--psk / --psk-file / CC_WORKER_PSK 所接受的值。
步驟 3：啟動工作程序
標題為「步驟 3：啟動工作程序」的章節對已配對的伺服器：
./build/cli/<os_arch>/bundle/bin/cc_worker \ --server wss://host:9030 --device-id my-worker --psk-file /path/to/worker.psk對回送伺服器（仍然需要配對——cc_server 一律執行 PSK 交握）：
fvm dart run cc_worker --server ws://localhost:9030 \ --device-id my-worker --psk-file /path/to/worker.psk| 旗標 | 說明 | 預設值 |
|---|---|---|
--server <url> |
cc_server URL（ws:///wss://；http(s) 與缺少的 /rpc 路徑會被強制轉換）。必填。 |
— |
--name <name> |
操作人員看到的工作程序名稱。 | 主機名稱 |
--device-id <id> |
穩定的已配對裝置 ID，同時用作工作程序 ID。 | cc-worker |
--psk-file <path> |
其第一個非空白行即為配對金鑰的檔案。優先於 --psk。 |
— |
--psk <key> |
直接寫在命令列上的配對金鑰。會出現在 ps 與 shell 歷史紀錄中——二進位檔會提出警告。 |
— |
--max-jobs <n> |
此處理程序可同時執行的作業數上限（正整數）。 | 4 |
金鑰的解析順序為 --psk-file → CC_WORKER_PSK → --psk。若省略所有來源，
就會跳過工作程序的驗證交握；如此一來，真正的 cc_server 會拒絕該工作階段
（auth_denied），而不是接受未經驗證的工作程序。未知旗標會造成用法錯誤
（exit 64）——與 cc_server 不同，這個二進位檔使用 package:args，不會
忽略打錯的旗標。
CC_WORKER_CACHE 會覆寫工作樹具體化快取目錄（預設：系統暫存目錄下的
cc_worker_cache 目錄）。
工作程序會以 fleet.registerWorker 註冊，接著每 20 秒傳送一次心跳，並每 2 秒
輪詢一次租約。它會一直執行到收到 SIGINT/SIGTERM；請將它置於 systemd 或
launchd 之下，讓它在當機或重新開機後重新啟動並重新註冊。
步驟 4：在機群面板中驗證
標題為「步驟 4：在機群面板中驗證」的章節在桌面版或網頁版應用程式中開啟 可觀測性，切換到 即時 分頁並捲動到 底部。工作節點 會列出每一個已註冊的工作程序，以及其平台、核心、能力鍵與 最後一次心跳；作業 則列出分散到這些節點上的作業。
你的工作程序帶著最新的心跳出現在其中，就是配對與註冊成功的確認。
在工作程序的磚上，你可以清空它（完成目前的作業、不接受新的租約）、 恢復正在清空的工作程序、撤銷其憑證，或移除該列。
工作程序與作業的資料列位於伺服器的 global.db 中——工作程序本身除了具體化
快取之外，不會寫入任何內容到磁碟。
工作程序宣告的內容
標題為「工作程序宣告的內容」的章節註冊時，工作程序會自動偵測自身能力，排程器則依這些能力來媒合作業。你不需要 手動設定它們：
- 作業系統與架構（
macos/linux/windows、arm64/x64）——精確探測，並退回uname -m/PROCESSOR_ARCHITECTURE - 核心與 RAM——精確的核心數；RAM 無法探測時會退化為
0 flutter——當可觸及 Flutter SDK 時會設定（先找單純的flutter，再找fvm flutter）；golden 渲染作業需要它sandbox——macOS 上為native-macos，Linux 上為native-linux。這是配置提示，不是承諾：工作程序宣告的是其平台_確實具備_的後端，但它不會把自己執行的作業包在其中。與cc_server不同，cc_worker會直接啟動租約作業always-on與parallel——專用的cc_worker一律會宣告這兩者，因此符合評測批次與其他用完即丟的平行運算容量
偵測採盡力而為：任何無法探測到的項目都會退化為安全的預設值，而不會讓啟動失敗。
工作程序會執行的內容
標題為「工作程序會執行的內容」的章節租約通訊協定帶有六種作業類型：
| 類型 | 內容 |
|---|---|
agentRun |
單次代理執行（派送） |
pipelineStep |
管線步驟的執行 |
codeIndex |
儲存庫程式碼索引的建置 |
goldenRender |
UI 視覺 golden 渲染（需要 flutter） |
benchmark |
效能基準測試的執行 |
evalBatch |
評測批次（偏好 parallel 容量） |
執行是真正的子處理程序串流實作，而不是完整的內嵌代理執行環境。當租約帶有
repoRemote 時，工作程序會把 git clone --depth 1 執行到以遠端與 SHA 為鍵的
快取目錄，然後執行 git fetch 與 git checkout。對於 agentRun，它會在工作
目錄中執行租約環境之 CC_JOB_COMMAND 所指的命令，並把 stdout 與 stderr 以
事件形式串流回傳；若沒有 CC_JOB_COMMAND，它會回顯提示詞，讓傳輸路徑仍能被
端到端演練。其他類型則執行小型但真實的命令（git rev-parse HEAD、
git --version）作為誠實的探測。租約環境中屬於作業範圍的憑證會注入每個子
處理程序，且永遠不會寫入日誌。
事件會分批處理，每 250 毫秒或每 32 個事件沖刷一次；每個作業都以一個完成事件 與一份完成報告作結。這個模型是心跳加上短 TTL 的租約：如果工作程序失去聯繫， 其租約就會過期，伺服器便會回收該作業以進行重試。工作程序上沒有持久狀態， 工作程序之間也沒有共識或工作竊取。