eust-w b201fd04a9 ✨ Wait for people when commits pushed to the target branch broke it
When a run's change passed its checks but failed one once merged onto
a target branch that moved meanwhile, the agent got a repair round for
it, even when the failure came from commits other people had pushed:
it would change their code, and spend rounds and tokens doing so.

The verifier now runs that check, recording no evidence, on the target
branch alone. If the branch passes, combining the two caused the
failure, and the agent repairs it as before. If the branch fails too
while the commit the run started from passes, the commits pushed since
broke the branch: the run waits on the new reason target_broken, uses
no repair round, and has its own verified change as its checkpoint
again. A run that started from a commit already failing the check may
be its fix, and is repaired as before.

Continuing merges the verified change onto the repaired branch and
checks the merge. An integration that continues reuses the change's own
verification under the same policy instead of repeating the checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 18:14:19 +08:00

73 lines
7.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 分钟的无人接手超时。