# Worker Temporal worker,按 `WF_WORKER_ROLE` 运行四种角色之一: | 角色 | 任务队列 | 注册的内容 | 身份 | |---|---|---|---| | `coordinator` | `wishforge-runs` | 工作流 `runWorkflow`;activity `inspectRunState`、`prepareRepair`、`recordWaiting` | 静态 `WF_WORKER_TOKEN`(只能读状态、记录等待、请求修复) | | `deployer` | `wishforge-deliveries` | `requestRelease` | 静态 `WF_DEPLOYER_TOKEN` | | `executor` | `wishforge-executor-<租户>-<运行>-<代次>` | `executeRun` | 本代次的运行级令牌 | | `verifier` | `wishforge-verifier-<租户>-<运行>-<代次>` | `verifyRun` | 本代次的运行级令牌 | executor 与 verifier 由 provisioner 按执行代次启动,必须设置 `WF_SANDBOX_MODE`(`kata`,或仅限开发的 `host`)以及与队列一致的 `WF_SANDBOX_TENANT_ID`、`WF_SANDBOX_RUN_ID`、`WF_SANDBOX_GENERATION`;不一致时不会执行任何项目代码,运行进入 `sandbox_provisioner` 等待。用户继续运行会产生新的代次,旧代次的令牌随之失效。 ## 一个代次内的流程 ``` executeRun → verifyRun → (repair → executeRun → verifyRun)* → 成功 | requestRelease | 等待 ``` - **executeRun**: - **准备工作区**:从目标分支(或愿望指定的起点分支)或最近的检查点准备工作区;修复轮在合并冲突后先合并最新目标分支。 - **安装依赖**:执行项目的安装命令或 `wishforge.yaml` 的 `dev.install`。 - **启动执行器**:以 Agent 配置组装提示词(目标、验收标准、项目经验、起点分支、修复轮的失败命令与输出)并启动执行器;把消息、命令、文件变更、计划与用量作为事件上报。 - **结束**:导出检查点并进入 verify。第一轮实现中执行器没有改动文件、而是在回复末尾用 `QUESTIONS:` 提了问题时,运行进入 `clarification` 等待。执行器失败时仍保存检查点,运行进入 `provider_error` 等待。 - **verifyRun**:在自己的目录恢复检查点,导出不含 `.git` 的目录,安装依赖后按顺序运行受保护命令(`kata` 下经 bubblewrap 隔离,验证命令无网络),提交带输出尾部的证据。失败时返回 `repair`;依赖安装失败、沙箱不可用等基础设施问题进入 `infrastructure` 等待。合入时合并结果失败、而目标分支自己就通不过(运行起点能通过)时进入 `target_broken` 等待,不交给执行器修复。通过后取得项目集成租约并合入(见 [docs/architecture.md](../../docs/architecture.md) 4.3);项目没有交付配置时提交集成证据即完成,否则构建镜像并交给 deployer。 - **prepareRepair**:协调器请求控制面把运行送回 implement;是否还有修复轮数由控制面决定,用尽时运行进入 `repair_exhausted` 或 `integration_conflict` 等待。 - **requestRelease**:以「运行、代次、构建证据、环境」为幂等键请求发布,运行进入 `approval` 或 `deployment` 等待。 继续运行时,executor 先看持久化的状态:已有检查点且处于 verify 之后的阶段时直接交给验证器;已有构建证据时直接请求发布;已有进行中的发布时等待它结束,不会重复构建或发布。 ## 租约与失败 - 租约 60 秒,每 10 秒心跳;心跳因网络失败时持续重试,直到租约可能已过期(45 秒)才放弃。控制面拒绝心跳(暂停、取消、预算用尽、代次更替)时立即停止执行器与所有命令。 - 模型、验证、构建与发布 activity 只尝试一次,5 分钟内没有 worker 接手记为 `worker_unavailable`,已开始但没有确认结果记为 `ambiguous_execution`;工作流持久等待用户继续。只有 `recordWaiting` 这类幂等的状态同步会自动重试。 - 控制面已经记录了等待原因(例如预算用尽)时,worker 不会覆盖它。 ## 配置 | 变量 | 说明 | |---|---| | `WF_DEPLOYMENT_MODE` | 必填;`host` 沙箱模式只允许 `development` | | `WF_WORKER_ROLE` | `coordinator`(默认)、`deployer`、`executor`、`verifier` | | `WF_WORKER_TOKEN` / `WF_VERIFIER_TOKEN` / `WF_DEPLOYER_TOKEN` | 对应角色的令牌 | | `WF_CONTROL_PLANE_URL` | 默认 `http://127.0.0.1:4000`;非本机地址必须是 HTTPS | | `TEMPORAL_ADDRESS`、`TEMPORAL_NAMESPACE` | 默认 `localhost:7233`、`default` | | `TEMPORAL_NAMESPACE_PREFIX`、`WF_DISPATCH_TENANTS` | 每个租户一个命名空间 `<前缀><租户>`。coordinator 与 deployer 轮询列表中每个租户的命名空间;沙箱只轮询自己租户的命名空间 | | `TEMPORAL_TLS_CERT`、`TEMPORAL_TLS_KEY`、`TEMPORAL_TLS_CA`、`TEMPORAL_TLS_SERVER_NAME` | Temporal 的 mTLS。生产中没有客户端证书时拒绝启动 | | `WF_INSTALL_PROXY` | 依赖安装使用的出站代理,以 `HTTP(S)_PROXY` 只传给安装命令(在 bubblewrap 中也一样),验证命令拿不到 | | `WF_DOCKER_HOST`、`WF_DOCKER_TLS_DIR` | verifier 的远程构建器(`tcp://主机:端口`)与其 TLS 文件目录,不能与 `WF_DOCKER_CONTEXT` 同时使用 | | `WF_WORKSPACE_ROOT`、`WF_PROVIDER_HOME_ROOT` | executor/verifier 必填:工作区目录与执行器的隔离 HOME | | `WF_SANDBOX_MODE`、`WF_SANDBOX_*` | 见上文 | | `WF_VERIFIER_BWRAP` | bubblewrap 路径,默认 `/usr/bin/bwrap` | | `WF_CODEBUDDY_BIN`、`WF_CLAUDE_BIN` | CodeBuddy 与 Claude Code CLI 的路径 | | `WF_DOCKER_CONFIG`、`WF_DOCKER_CONTEXT` | verifier 构建镜像使用的仓库凭据目录与 Docker context(运维配置) | | `WF_EXECUTION_*_LIMIT` | provisioner 给出的资源上限,用于校验 `wishforge.yaml` 的资源请求 | | `WF_GIT_ALLOW_LOCAL_HTTP` | 开发中允许本机 HTTP 的 Git 地址 | 本地开发中 coordinator 与 deployer 由 `npm run dev:all` 启动,executor 与 verifier 由本地 provisioner 为每个代次启动。 ## 新增执行器 1. 在 `packages/runtime/src/providers` 中实现 `ProviderAdapter`。输出 Claude Code 风格 stream-json 的命令行工具可以直接复用 `StreamJsonCliAdapter`,只需提供参数与凭据变量规则。 2. 在 `packages/contracts/src/providers.ts` 的 `providerCatalog` 中登记名称、可执行文件变量以及模型代理能否隔离它的凭据。 3. 在 `apps/worker/src/providers.ts` 的 `providerRegistry` 中登记启动方式。 API 的可用性判断、工作台的选项与 MCP 的 `submit_wish` 都读取这份目录。`tests/providers.test.ts` 会检查每个目录项都已在 worker 中登记。 ## 测试 - `apps/worker/test/recovery.test.ts`:沙箱绑定、恢复路径、修复交给控制面、等待记录不覆盖、失败分类。 - `tests/local-loop.test.ts`:用真实 Git 与进程内控制面跑完整流程。 - `WF_TEMPORAL_INTEGRATION=1 npx vitest run tests/integration/temporal.test.ts`:在真实 Temporal 上验证持久等待、worker 重启、代次更替与发布不重复(使用独立的 `wishforge-contract-tests` 命名空间,需要串行运行);加上 `WF_TEMPORAL_TIMEOUT_ACCEPTANCE=1` 会实际等待 5 分钟的无人接手超时。