运行机群工作进程

在一台闲置机器上运行 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 生成一个自包含的 bundle。

第 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 覆盖工作树物化缓存目录（默认：系统临时目录下的 cc_worker_cache 目录）。

工作进程通过 fleet.registerWorker 注册，随后每 20 秒发送一次心跳，每 2 秒轮询一次租约。它会一直运行到收到 SIGINT/SIGTERM；请把它交给 systemd 或 launchd 管理，以便在崩溃或重启后重新启动并重新注册。

第 4 步：在机群面板中验证

在桌面应用或 Web 应用中打开可观测性，切换到实时标签页并滚动到底部。工作节点列出每个已注册的工作进程及其平台、核心数、能力键和最近一次心跳；作业列出分发到它们上面的作业。

你的工作进程带着最近的心跳出现在那里，就证明配对与注册已经成功。

在工作进程的卡片中，你可以排空它（完成当前作业，不再接受新租约）、恢复正在排空的工作进程、吊销其凭据，或移除该行。

工作进程和作业的行存放在服务器的 global.db 中——工作进程自身除物化缓存外不向磁盘写入任何内容。

工作进程对外声明的内容

注册时，工作进程会自动检测自身能力，调度器据此匹配作业。这些无需手动配置：

操作系统与架构（macos/linux/windows，arm64/x64）——精确探测，并回退到 uname -m / PROCESSOR_ARCHITECTURE
核心数与内存——精确的核心数；无法探测时内存降级为 0
flutter——能访问到 Flutter SDK 时置位（先找裸 flutter，再找 fvm flutter）；金样渲染作业需要它
sandbox——macOS 上为 native-macos，Linux 上为 native-linux。这是放置提示，而非承诺：工作进程声明其平台_实际拥有_的后端，但不会用它包裹所运行的作业。与 cc_server 不同，cc_worker 会直接启动租约作业
always-on 和 parallel——专用 cc_worker 始终同时声明这两者，因此有资格承接评测批次以及其他一次性的并行容量

检测尽力而为：任何探测不到的内容都会降级为安全的默认值，而不会导致启动失败。

工作进程会执行什么

租约协议承载六种作业类型：

类型	说明
`agentRun`	单次智能体运行（派发）
`pipelineStep`	一次流水线步骤执行
`codeIndex`	一次仓库代码索引构建
`goldenRender`	一次 UI 视觉金样渲染（需要 `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）作为诚实的探测。租约环境中作用域限定到作业的凭据会注入每个子进程，且从不写入日志。

事件会分批处理，每 250ms 或每 32 个事件刷新一次；每个作业都以一个 done 事件和一份完成报告结束。该模型由心跳加上短 TTL 租约构成：如果工作进程失去联系，其租约就会过期，服务器会回收该作业以便重试。工作进程上没有持久状态，工作进程之间也没有共识或工作窃取。