# 任务推进链实施路径

> **日期**: 2026-06-16
> **来源**: [任务执行与推进能力分析-2026-06-16.md](../05-代码审查/任务执行与推进能力分析-2026-06-16.md) 第八章（已核对注入）
> **状态**: 规划定稿。**D-260616-01~04 已决策(2026-06-16)**:①前端对齐7态 ②任务软删(UI缓做) ③advance_task 走 **df-nodes Node** ④阶段1先行。**阶段1可启动(F-01~05)**。
> **关联决策**: D-260616-01~04（决策结果见 todo.md 待决策区块）

---

## 〇、核对纠正（实施前必读）

经 Explore 代理核对，原分析报告「AI 缺 update_task / run_command 工具」**核实为假**：

| 工具 | 报告称 | 核实 | 证据 |
|------|--------|------|------|
| `update_task` | 缺失 | ❌ **存在** | tool_registry.rs:348，AI 能改任务字段（含 status，经裸 update_field 非状态机收口） |
| `run_command` | 缺失 | ❌ **存在** | tool_registry.rs:468，完整 Shell 执行实现 |
| `run_workflow` | 空壳桩 | ⚠️ **未注册** | tool_registry.rs 无此工具（连空壳都没有） |
| `advance_task` | 缺失 | ✅ 确实缺失 | 全局搜零定义 |

**修正后结论**：AI **能**更新任务状态、**能**运行命令，但仍**不能**：① 触发三闸门推进链（无 advance_task）② 联动工作流（task_id=None + 无完成回调）③ 在对话中触发工作流（无 run_workflow 工具）。

---

## 一、阶段 0 — 基础修复（前置，部分已立）

已在 todo.md 立项 **B-260616-12~18**（状态枚举/路由/try-catch/字段保护/DDL/priority/绕 store）。

✅ **阻塞已解除（2026-06-16 D-01/D-02 决策）**：
- B-260616-12（状态枚举）→ D-260616-01 定**前端对齐后端 7 态**，可直接做
- B-260616-13（软删除）→ D-260616-02 定**加软删除对标 projects（UI 缓做）**，可直接做

---

## 二、阶段 1 — 推进骨架（手动闭环 ~200 行，报告建议先行）

目标：任务状态经「合法路径」推进，而非裸字段修改。

| 任务 | 内容 | 依赖 |
|------|------|------|
| **F-260616-01** [P1] | **状态机定义（df-nodes 新模块 `task_state_machine.rs`）**：7 态合法转换枚举（`todo→in_progress→in_review→testing→done` 闸门链 + `blocked` 退回 + `cancelled`）。独立模块，非挂在 TaskStatus enum 上。 | D-01✅ 前端对齐7态 |
| **F-260616-02** [P1] | **advance_task 推进逻辑（df-nodes `task_advance_node.rs` 实现 Node trait）**：校验转换 + 原子写（下沉 SQL `WHERE status=:expected` 防 TOCTOU）。df-nodes 需补 `df-storage` 依赖读 TaskRecord（核实无循环）。IPC 层 thin 入口调 df-nodes。 | D-03✅ df-nodes, F-01 |
| **F-260616-03** [P1] | `status` 移出 `update_task` 白名单（推进链唯一收口） | F-02（关联 B-260616-16） |
| **F-260616-04** [P2] | `review_rounds` 字段（退回时 +1，任务卡显示「第 N 轮 review」） | F-01 |
| **F-260616-05** [P1] | 前端 TaskDetail 推进按钮（手动推进，不接 AI） | F-02, F-03 |

此阶段不接 AI/工作流，纯人工推进，但状态机保护和收口到位。

---

## 三、阶段 2 — 工作流联动（单向）

目标：工作流执行能回写任务状态。

**F-260616-06** [P1]（聚合）：
1. `run_workflow` IPC 支持 `task_id` 参数（去 workflow.rs:56 None 硬编码）
2. 工作流完成回调 → 检查 task_id → 推进任务状态
3. 定义任务推进 DAG 模板（AiNode 执行 + AiNode 自审 + HumanNode 核对）
4. `advance_task` 触发对应闸门工作流
5. 前端展示工作流执行进度

**依赖**：阶段 1 完成。详见报告 §8 阶段 2。

---

## 四、阶段 3 — AI 执行闭环

目标：AI 能真正执行任务内容。

**F-260616-07** [P2]（聚合）：
1. `advance_task` AI 工具（让 AI 经合法路径推进）
2. `run_workflow` AI 工具注册实装（核对：tool_registry.rs **无此工具**，需新建）
3. AiNode 接入任务上下文（读任务描述 + 项目目录）
4. AI 自审 verdict 结构化输出 + 解析
5. 失败路径完整处理（退回/重做/保持）

**依赖**：阶段 2 完成。详见报告 §8 阶段 3。

---

## 五、阶段 4 — Git 集成（增强）

目标：代码类任务支持 Git 工作流。

**F-260616-08** [P3]（聚合）：
1. 加 `kind` 字段（code/doc/design/generic）
2. code kind 闸门接 git 命令（worktree/commit/merge）
3. BranchRecord 联动（加 worktree_path）
4. `on_task_advanced` 钩子填充（分支联动 + 项目 completed）

**依赖**：阶段 3 完成。详见报告 §8 阶段 4。

---

## 六、依赖关系图

```
D-01 枚举方向 ──▶ F-01 状态机 ──▶ F-02 advance_task ──▶ F-03 收口 ──▶ F-05 前端按钮
                       │                  │
                       └──▶ F-04 rounds   └──▶ 阶段2(F-06) ──▶ 阶段3(F-07) ──▶ 阶段4(F-08)

D-03 架构落点 ──▶ F-02
D-04 路径取舍 ──▶ 阶段1 是否先行
```

**✅ 阶段 1 可启动（2026-06-16）**：D-01（前端 7 态）/ D-03（df-nodes Node）/ D-04（先行）三决策已定。阶段 1 ~200 行，从 0% 推进能力到「手动推进闭环」。df-nodes 落点核实可行（Node trait 纯接口 `df-workflow/src/node.rs:67`，现有 AiNode/HumanNode/ScriptNode，需补 `df-storage` 依赖无循环）。

---

## 七、待合并到 `docs/todo.md` 的指针

> 主文件 todo.md 并发修改频繁（后台代理），以下指针待稍后合并。合并时在「待决策」区块（D-260616-04 后）插入：

```
### 🗺️ 任务推进链实施路径（2026-06-16 规划·供其他会话读取）

> 详见 [任务推进链实施路径-2026-06-16.md](./02-架构设计/任务推进链实施路径-2026-06-16.md)。
> 推进能力实现度 0%。**阶段 1 已解除阻塞（D-01/D-03/D-04 三决策已定 2026-06-16），可启动 F-01~05**。
> 核对纠正：AI 有 update_task/run_command 工具，无 run_workflow/advance_task。

- [ ] F-260616-01~05 阶段1 推进骨架（状态机+advance_task+收口+rounds+前端按钮）
- [ ] F-260616-06 阶段2 工作流联动（task_id+回调+DAG模板）
- [ ] F-260616-07 阶段3 AI 执行闭环（advance_task/run_workflow 工具+AiNode+自审）
- [ ] F-260616-08 阶段4 Git 集成（kind+git闸门+worktree）
```
