- Skills: per-project know-how the platform proposes from each succeeded run (in the background, or on request from a run), people confirm, edit, disable, delete or write; active ones enter later prompts - Export one skill as SKILL.md, or all as a zip with a directory per skill, as .claude/skills/ expects - A wish's report: every run, its stage timeline, the agent's plan, replies, commands, changed files and model usage, the change, the checks, failures, reviews and releases, and the full event log, as Markdown, or laid out for printing to PDF Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 分钟的无人接手超时。