企业官网建设流程全解析

Wegent 是一个开源、可自托管的 AI 工作空间（AI workspace），核心能力包括 AI 编码、团队协作与自动化交付。本文面向新手，带你读懂 Wegent 的任务状态机（Task State Machine）源码：一个 AI 编码任务从创建（PENDING）到执行（RUNNING），再到**交付（COMPLETED）**或异常分支（FAILED / CANCELLED）的完整生命周期。你将理解 8 种任务状态的流转规则、Pipeline 多 Agent 流水线中的确认机制，以及"卡死"任务如何被自动恢复。

任务状态机总览：8种状态一览 🧭

Wegent 用一张清晰的状态枚举表定义了任务的全部生命周期节点。它定义在后端 schemas/task.py 中：

其中COMPLETED、FAILED、CANCELLED、DELETE四个状态被 chat/operations/cancel.py 中的_TASK_FINAL_STATES声明为终态——一旦进入，任务不会再"醒来"。

Wegent 桌面端界面：任务从左侧列表发起，底部终端实时展示执行过程

阶段一：创建与初始化（PENDING）

任务创建时，后端不会直接让它跑起来，而是先落库为PENDING。核心流程在 chat/storage/task_manager.py：

• 创建时写入的初始 CRD 里，status.status就是"PENDING"，progress为 0；
• 状态并不是独立的数据库字段，而是整体存放在任务的CRD JSON（类 Kubernetes 风格的自定义资源文档）的status块中，progress、errorMessage、completedAt、updatedAt都与之同居。

统一的状态写入工具函数集中在 services/task_status.py，例如mark_task_pending（重置进度为 0、清空错误信息）、mark_task_failed（记录错误信息并写入completedAt）、mark_task_completed（进度置 100%）。这套"payload 先算好再写回"的设计，保证了任何分支修改状态时行为一致。

Wegent 项目空间：任务在这里创建并被分配给 AI 团队

阶段二：调度执行（RUNNING）

任务被分配到 Bot 后进入RUNNING。执行期间有两个值得新手注意的细节：

1. 流式结果实时落库。在 chat/storage/db.py 的save_partial_response中，Bot 的响应以"部分内容 + streaming 标志"的形式持续写入子任务（Subtask），前端因此能逐字看到 AI 输出。

2. 子任务与任务是两层状态机。schemas/subtask.py 中的SubtaskStatus与任务状态几乎同构（PENDING / RUNNING / COMPLETED / FAILED / CANCELLED）。任务的状态其实是由子任务状态聚合推导出来的——子任务完成了，策略层才会决定任务该进入哪个状态。

阶段三：完成判定与协作策略

这是状态机最精巧的部分。子任务完成后，任务并不会无脑变成COMPLETED，而是要经过 chat/storage/db.py 中的状态聚合逻辑：

new_status, progress = strategy.get_task_status_on_subtask_complete( db, task_id, last_subtask.id, subtask_status_str )

即由CollaborationStrategy（协作策略）根据团队模式计算新状态。随后：

• 若新状态是COMPLETED、CANCELLED或PENDING_CONFIRMATION，写入completedAt时间戳；
• 若子任务是FAILED，则把error_message透传到任务级，用户能在界面看到失败原因。

单 Bot 任务通常一步到位走向COMPLETED；而多 Bot 团队任务，就要走下面的流水线分支了。

Pipeline 流水线：多Agent接力与"待确认"分支 🤖

当团队以Pipeline 模式组建时（如"规划 Bot → 编码 Bot → 审查 Bot"），任务生命周期中会插入一种特殊状态——PENDING_CONFIRMATION。

Wegent 团队管理界面：Pipeline 模式下多个 Bot 首尾相连，逐个接力完成任务

整个流水线机制由 adapters/pipeline_stage.py 的PipelineStageService管理，关键规则有三条：

1. 当前阶段是唯一的"事实来源"。任务 JSON 的spec.currentStage记录当前进行到第几个 Bot，get_current_stage_index会读取它（并做越界保护），所有界面展示、阶段推进都只认这一个字段。

2. 阶段完成 ≠ 任务完成。should_set_pending_confirmation_on_complete会检查：当前阶段是否配置了requireConfirmation？如果是，且不是最后一个阶段，那么子任务完成后，任务状态被置为PENDING_CONFIRMATION而非继续执行——把方向盘交还给人类。

3. 用户确认后推进或收官。点击"确认"后，pipeline_confirm校验任务确实处于PENDING_CONFIRMATION（否则拒绝），然后：

• 若是最后一个阶段：任务直接进入COMPLETED，progress置 100，写入completedAt；
• 否则：把currentStage加 1，状态回落到PENDING，并通过build_pipeline_context_prompt生成"交接信息"（handoff message），让下一个 Bot 带着上一阶段的成果继续干活。

此外还有pipeline_auto_advance：未要求确认的阶段完成后自动接力，无需人工点击。

任务执行完毕进入交付环节：变更统计、提交推送与"待确认"状态一目了然

失败与取消：如何优雅地"刹车" 🚨

失败分支：子任务FAILED时，错误信息被聚合到任务级，任务标记为FAILED并记录completedAt。用户可以在界面上查看失败原因，并借助 chat/operations/retry.py 发起重试。

取消分支：取消不是一步到位，而是一个两阶段状态机：

1. 用户点击取消 → 任务进入CANCELLING，表示"正在通知执行器、等待收尾"；
2. 执行器确认停止后，chat/operations/cancel.py 把未完结的 assistant 子任务统一标记为CANCELLED，任务随之变为CANCELLED并发布TaskCompletedEvent(CANCELLED)事件通知前端。

还有一个贴心的兜底：如果任务在CANCELLING状态卡住（比如执行器失联），CANCELLING_STUCK_TIMEOUT_SECONDS超时机制会在空闲超时后强制将其就地终结，避免任务永远卡在"取消中"。

状态守护：防止乱序更新

状态机之所以可靠，靠的是"守卫条件"。例如在 chat/storage/task_manager.py 中：

• check_task_status：当任务处于RUNNING或PENDING时，拒绝某些变更操作（"Task is still running"）；
• 恢复/兜底逻辑会检查任务 JSON 里的实际状态，防止执行器已经跑完、状态却仍停留在PENDING/RUNNING的"僵尸任务"。

配合 WebSocket 事件推送，前端列表页能实时看到任务状态的每一次合法迁移。

一图总结：任务生命周期状态流转

┌────────────────────────────────────────┐ │ Pipeline 模式（多Bot接力） │ │ │ 创建 ──▶ PENDING ──▶ RUNNING ──▶ PENDING_CONFIRMATION ──▶ 下一阶段 PENDING │ │ │ │ │ │ └──(最后阶段)──▶ COMPLETED ◀┘ │ └──▶ COMPLETED（单Bot/普通任务直接完成） │ ├──▶ FAILED（执行出错，可重试） │ ├──▶ CANCELLING ──▶ CANCELLED（含卡死超时兜底） │ └──▶ DELETE（软删除）

写在最后

Wegent 的任务状态机看似只是 8 个枚举值，实则是一套完整的设计：

• CRD JSON 承载状态，currentStage作为流水线单一事实来源；
• 子任务 → 任务两级聚合，协作策略决定终态；
• PENDING_CONFIRMATION把人类留在决策回路里；
• 两阶段取消 + 超时兜底，保证状态机永远能"走到头"。

如果你想动手阅读源码，建议按这条路径走：schemas/task.py（状态定义）→ services/task_status.py（状态写入工具）→ adapters/pipeline_stage.py（流水线推进）→ chat/operations/cancel.py（取消收尾），基本就能串起整个生命周期。

更多背景资料可参考 backend/README.md 与 docs/README.md，以及流水线推进逻辑 chat/pipeline_advance.py。