In development the worker handed Claude Code both the tenant's key and the operator's logged-in home. The CLI signs in with the login it finds there, so the gateway saw a subscription credential it does not accept and answered 401 "Invalid API key provided" — the run then waited on provider_error with its work saved. A run that carries a credential of its own now gets an empty home, exactly like a Copilot answer; the operator's login stays for runs that have nothing else to sign in with.
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 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 为每个代次启动。
新增执行器
- 在
packages/runtime/src/providers中实现ProviderAdapter。输出 Claude Code 风格 stream-json 的命令行工具可以直接复用StreamJsonCliAdapter,只需提供参数与凭据变量规则。 - 在
packages/contracts/src/providers.ts的providerCatalog中登记名称、可执行文件变量以及模型代理能否隔离它的凭据。 - 在
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 分钟的无人接手超时。