執行機群工作節點

在一部備用機器上執行 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：建置二進位檔

cd apps/cc_worker
fvm dart build cli

這會在 ./build/cli/<os_arch>/bundle/bin/cc_worker 產生一個自成一體的套件組合。

步驟 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：啟動工作節點

連接已配對的伺服器時：

./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 會覆寫 worktree 具體化快取目錄（預設：系統暫存目錄下的一個 cc_worker_cache 目錄）。

工作節點會以 fleet.registerWorker 註冊，然後每 20 秒發出一次心跳，並每 2 秒輪詢一次租約。它會一直執行，直到收到 SIGINT/SIGTERM；請把它置於 systemd 或 launchd 之下，讓它在當機或重新啟動後重新啟動並重新註冊。

步驟 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`	一次介面視覺 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 租約：若工作節點失去聯繫，它的租約就會到期，伺服器會回收該工作以便重試。工作節點上沒有任何持久狀態，工作節點之間也沒有共識或工作竊取。