# 任务推进链实施路径

> **日期**: 2026-06-16(状态行 2026-06-20 回填)
> **来源**: [任务执行与推进能力分析-2026-06-16.md](../05-代码审查/任务执行与推进能力分析-2026-06-16.md) 第八章（已核对注入）
> **状态**: 阶段1✅ + 阶段2✅(F-260616-06 工作流联动:workflow.rs 完成回调 + 三模板 `task_workflow_templates.rs` + `run_workflow` task_id/target_status)+ 阶段3 部分(`ai_self_review` gate 已落 `task_workflow_templates.rs:54`;`run_workflow` AI 工具已注册但 High 风险默认拒绝实装待核、AiNode 任务上下文注入待核)。**D-260616-01~04 已决策(2026-06-16)**:①前端对齐7态 ②任务软删(UI缓做) ③advance_task 走 **df-nodes Node** ④阶段1先行。
> **关联决策**: 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 行，报告建议先行）

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

✅ **已落(2026-06-16~17)**：状态机 / advance_task 原子推进 / status 收口 / review_rounds / 前端推进按钮全部实装。

| 任务 | 内容 | 依赖 | 状态 |
|------|------|------|------|
| **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态 | ✅ `crates/df-nodes/src/task_state_machine.rs`(can_transition / regression_target) |
| **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 | ✅ `advance_task_atomic`(CAS SQL) + IPC 瘦入口 |
| **F-260616-03** [P1] | `status` 移出 `update_task` 白名单（推进链唯一收口） | F-02（关联 B-260616-16） | ✅ `settings.rs` tasks 白名单 `status` 不列入(注释 D-260616-04) |
| **F-260616-04** [P2] | `review_rounds` 字段（退回时 +1，任务卡显示「第 N 轮 review」） | F-01 | ✅ `advance_status_atomic` 退回转换原子 +1 |
| **F-260616-05** [P1] | 前端 TaskDetail 推进按钮（手动推进，不接 AI） | F-02, F-03 | ✅ `views/TaskDetail.vue` 推进按钮 |

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

---

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

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

✅ **已落(F-260616-06, 2026-06-16~17)**：实施路径详见 [推进链阶段2实施路径-2026-06-16.md](./推进链阶段2实施路径-2026-06-16.md)。

**F-260616-06** [P1]（聚合）：
1. ✅ `run_workflow` IPC 支持 `task_id` / `target_status` 参数（去硬编码 None，向后兼容 Option）— `workflow.rs` run_workflow / run_workflow_inner
2. ✅ 工作流完成回调 → 检查 task_id + target_status → 推进任务状态(②-3)；失败按 `regression_target` 退回(②-4)
3. ✅ 定义任务推进 DAG 模板（AiNode 执行 + AiNode 自审 + HumanNode 核对）— `crates/df-nodes/src/task_workflow_templates.rs`(三模板 in_progress/testing/done，空 dag + target_status 时 `template_for` 自动选)
4. ⚠️ `advance_task` 触发对应闸门工作流 — 经 run_workflow(task_id,target_status) 间接达成(手动/审批路径)，advance_task 原子推进本身直调状态机不走工作流(设计如此)
5. ⚠️ 前端展示工作流执行进度 — EventBus 事件转发已落(workflow-event)，进度 UI 展示待补

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

---

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

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

🟡 **部分落(F-260616-07)**：`ai_self_review` gate 已落，AI 工具注册/上下文注入部分待核。

**F-260616-07** [P2]（聚合）：
1. ✅ `advance_task` AI 工具（让 AI 经合法路径推进）— `crates/df-mcp/src/tools.rs` advance_task spec + 实现（经 `advance_task_atomic` 走状态机，不走旁路裸改）
2. ⚠️ `run_workflow` AI 工具注册实装（核对：tool_registry.rs **无此工具**，需新建）— **已注册** `df-mcp/tools.rs:120`（High 风险默认拒绝桩 `tools.rs:654`，实装待核：当前返回"默认拒绝请到应用内执行"）
3. ⚠️ AiNode 接入任务上下文（读任务描述 + 项目目录）— 任务上下文注入待核（模板节点级 config 留空，运行时全局 config 注入路径已有，AiNode 是否读 task_id 取描述待核）
4. ✅ AI 自审 verdict 结构化输出 + 解析 — `crates/df-nodes/src/ai_self_review_node.rs`（gate:true，verdict=fail 触发工作流 failed → ②-4 退回；详见 [AiNode自审实施方案-2026-06-16.md](./AiNode自审实施方案-2026-06-16.md)）
5. ✅ 失败路径完整处理（退回/重做/保持）— `regression_target` 收敛状态机，②-4 回调退回 + review_rounds+1

**依赖**：阶段 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 已落 / 阶段 2 已落 / 阶段 3 部分（2026-06-16~17）**：D-01（前端 7 态）/ D-03（df-nodes Node）/ D-04（先行）三决策已定并实施。推进能力实现度已从 0% 推进到「阶段1手动推进闭环 ✅ + 阶段2工作流回写任务 ✅ + 阶段3 ai_self_review gate ✅（AI 工具实装/AiNode 上下文注入待核）」。df-nodes 落点已落实（Node trait 纯接口，已补 `df-storage` 依赖无循环）。

---

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

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

```
### 🗺️ 任务推进链实施路径（2026-06-16 规划·2026-06-20 回填实施状态）

> 详见 [任务推进链实施路径-2026-06-16.md](./任务推进链实施路径-2026-06-16.md)。
> 推进能力实现度：阶段1 ✅ + 阶段2 ✅ + 阶段3 部分（ai_self_review gate ✅，run_workflow AI 工具实装 / AiNode 上下文注入待核）。
> 核对纠正：AI 有 update_task/run_command 工具，advance_task 已补（阶段3），run_workflow 已注册但默认拒绝桩待实装。

- [x] F-260616-01~05 阶段1 推进骨架（状态机+advance_task+收口+rounds+前端按钮）
- [x] F-260616-06 阶段2 工作流联动（task_id+回调+三 DAG 模板，进度 UI 待补）
- [ ] F-260616-07 阶段3 AI 执行闭环（advance_task✅ / run_workflow 默认拒绝桩 / AiNode 上下文注入 / ai_self_review✅）
- [ ] F-260616-08 阶段4 Git 集成（kind+git闸门+worktree）
```