wishforge-ide/wiki/modules/worker-pipeline.md

4.6 KiB
Raw Permalink Blame History

模块: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 验证器行为

修改时的检查清单

  1. 新增 activity:必须考虑「结果未知」的恢复路径,不能不设上限重试。
  2. 改任务队列命名:provisioner 与 worker 必须同步,否则运行会停在 worker_unavailable。
  3. 改等待原因:同步 packages/contracts 与 apps/web/src/lib/waiting.ts。
  4. 改修复轮语义:同步 docs/requirements.md FR-E4/E5 与 tests/run-lifecycle.test.ts。