4.6 KiB
模块:Temporal 执行流水线(apps/worker)
职责
apps/worker 承载长时间运行的分布式状态机:把一次愿望拆成 executor → verifier → (可选)release 的 activity 序列,并在外部故障、进程重启、人工等待后从精确断点继续。它不拥有业务数据库,所有状态写入都通过 /internal 接口回到控制面。
代码地图
| 文件 | 行数 | 职责 |
|---|---|---|
apps/worker/src/workflows.ts |
141 | 工作流主体、resume 信号、执行代次(generation) |
apps/worker/src/activities.ts |
97 | activity 注册:inspect、execute、verify、requestRelease、prepareRepair、recordWaiting |
apps/worker/src/executor.ts |
486 | 拉取工作区、准备依赖、调用编码 Agent、产出检查点 |
apps/worker/src/verifier.ts |
903 | 独立验证、验收配置、失败分类、修复证据 |
apps/worker/src/common.ts |
237 | RunInput、WorkerConfig、内部 API 客户端 |
apps/worker/src/lease.ts |
99 | activity 上下文与租约令牌传递 |
apps/worker/src/github-delivery.ts |
123 | GitHub 分支/PR 交付路径 |
apps/worker/src/host-checks.ts |
121 | 本机 host 模式的安全检查 |
apps/worker/src/providers.ts |
134 | 执行器适配选择 |
apps/worker/src/main.ts |
130 | worker 进程启动、任务队列 |
apps/worker/src/workflow-failures.ts |
19 | 失败到等待原因的分类 |
工作流的关键设计
1. 每次尝试都有独立任务队列
apps/worker/src/workflows.ts:63-76:
taskQueue: `wishforge-executor-${tenantId}-${runId}-${generation}`
taskQueue: `wishforge-verifier-${tenantId}-${runId}-${generation}`
按代次隔离队列,意味着一次卡死的执行不会阻塞其他运行;进程重启后,只有同一代次的 worker 会接单。
2. 外部副作用不自动重试
模型调用、构建、部署类 activity 的 retry: { maximumAttempts: 1 }(workflows.ts:66-76)。失败后由 waitingForFailure(error, phase) 转成结构化等待原因,而不是盲目重放。这是「未知结果必须由人确认」的代码表达。
3. resume 信号与代次防回退
workflows.ts:45-53:
- 收到新代次信号时取消当前
CancellationScope。 seenGenerations记录已见代次,晚到的重复信号不能恢复旧身份。- 循环顶部先
inspectRunState,若运行已结束则直接返回,避免对已完成运行继续调用模型。
4. 等待记录的一条硬约束
apps/worker/src/activities.ts 的 recordWaiting:
- 先读状态;代次不匹配返回
superseded,不写。 - 已有租约未过期时抛
EXECUTION_LEASE_HELD,要求等待租约过期,不允许两个执行者同时写等待原因。 - 只有确认后才
POST /internal/runs/:id/wait,detail 截断到 2000 字符。
5. 发布请求的幂等键
requestRelease 用 release:${runId}:${generation}:${buildEvidenceId}:${environmentId} 作为幂等键(apps/worker/src/activities.ts)。重试不会产生两个发布单;继续一个失败的发布则会因为代次变化产生新键。
验证器的失败分类
verifier.ts 负责把失败分成「测试失败 / 基础设施失败 / 范围失败」,决定是否消耗修复轮:
- 测试失败:回灌 executor。
- 安装失败、沙箱启动失败:
infrastructure,不消耗轮次。 - 前端专用愿望改到后端文件:
scope,先恢复文件再重做。 - 合并冲突:
integration_conflict。
这些分类与 docs/requirements.md FR-E5、packages/contracts/src/index.ts:256 的证据类型一致。
启动与配置
apps/worker/src/main.ts:10 读取 WorkerConfig,连接 Temporal 与内部 API。开发时由 apps/provisioner 的 local 后端按代次启动 worker 进程;生产由 Kubernetes Job 启动。
测试集
| 测试 | 覆盖 |
|---|---|
tests/run-lifecycle.test.ts |
阶段推进、失败分类、修复 |
tests/execution-generation.test.ts |
代次与旧信号 |
tests/dispatcher.test.ts |
Outbox 派发与多副本 |
tests/verification-profile.test.ts |
验收配置执行与失效 |
tests/local-loop.test.ts |
本地端到端 |
packages/runtime/test/verify.test.ts |
验证器行为 |
修改时的检查清单
- 新增 activity:必须考虑「结果未知」的恢复路径,不能不设上限重试。
- 改任务队列命名:provisioner 与 worker 必须同步,否则运行会停在
worker_unavailable。 - 改等待原因:同步
packages/contracts与apps/web/src/lib/waiting.ts。 - 改修复轮语义:同步
docs/requirements.mdFR-E4/E5 与tests/run-lifecycle.test.ts。