新增: 并行多轮设计文档+审查回填+待决策更新

Plan-driven子流并行Phase1-3/CR-260620-01~03审查回填/④必须做+②已完成
2026-06-20 15:54:51 +08:00
parent 126bee5b24
commit 44ecdf825e
4 changed files with 408 additions and 15 deletions
--- a/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md
+++ b/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md
@@ -0,0 +1,133 @@
+# 单对话并行多轮推理 — 设计文档
+
+> 2026-06-20 · aichat B 路线(决策能力)· 用户决策:场景常见,**必须做**
+
+## 一、目标
+
+单对话内 AI 把复杂任务拆**子流并行跑**,加速(多文件/多方案/多模块对比)。
+
+## 二、当前限制
+
+- `run_agentic_loop`(`src-tauri/src/commands/ai/agentic/mod.rs:331-1206`)单链 ReAct:一轮一轮串行,每轮依赖前轮
+- 已有并行:工具级 `join_all`(Low risk)+ 主辅 2 路并发(`per_conv permits=2`,state.rs:121)
+- 缺:**主推理链分叉子流**(一轮一轮无法拆并行多轮)
+- `coordinator.rs`(crates/df-ai/,30 行空壳)多 Agent 协作占位
+
+## 三、架构:Plan-driven 子流并行
+
+延伸 intent 三层链路:
+
+```
+intent(识别,纯函数✅) 
+  → plan_hint(轻规划,纯函数:工具编排/可并行组/顺序) 
+  → planning(重规划,LLM:任务分解为 Plan DAG) 
+  → execution(调度:可并行组 spawn 子 ReAct loop → join → 汇总)
+```
+
+### Plan 数据结构
+
+```rust
+struct Plan {
+    subtasks: Vec<SubTask>,        // 子任务列表
+    parallel_groups: Vec<Vec<Id>>, // 可并行组(DAG 同层)
+}
+struct SubTask {
+    id: String,
+    goal: String,           // 子任务目标(LLM 规划产出)
+    tools: Vec<String>,     // 子任务可用工具(intent/plan_hint 提示)
+    deps: Vec<String>,      // 依赖子任务(DAG 前驱)
+}
+```
+
+## 四、关键设计决策
+
+| 维度 | 决策 | 理由 |
+|---|---|---|
+| 触发 | LLM 规划为主 + plan_hint 启发式辅助 | 灵活 + 可控 |
+| 粒度 | 子任务级(独立 ReAct 子链) | 每子流独立工具序列 |
+| 状态隔离 | PerSubFlowState(扩展 F-09 PerConvState) | 子流独立 messages/工具上下文,共享 conv 元数据 |
+| 资源 | sub_permit ≤3(默认)+ token 限额 + 用户可见 cost | 防 cost 爆炸 |
+| 失败 | 部分子流失败 → 降级(汇总成功 + 标注失败) | 不全挂 |
+| UX | 子流折叠/进度,事件按 sub_flow_id 路由(扩展 conv_id) | 多流不混乱 |
+| 与 F-09 协调 | 两层并发:conv 级(permits)+ sub_flow 级(sub_permit),全局限额协调 | 分层资源池 |
+
+## 五、渐进实施路径
+
+### Phase 1:plan_hint 轻规划(低风险,独立有价值)
+
+- **改**:`crates/df-ai/src/intent.rs` 扩 `tool_subset_for` → 输出 `plan_hint`(工具编排:可并行组/顺序依赖)
+- **接入**:主 loop 据 plan_hint 编排工具调用顺序/并行(跑题 P0 filter_tool_defs 延伸)
+- **纯函数零延迟**(intent 已纯函数,plan_hint 同),单测覆盖
+- **收益**:工具调用更智能(顺序/并行组),**但不真正多轮并行**
+- **风险**:低(纯函数,可回退,常量开关)
+- **工作量**:小(intent 扩展 + 单测)
+
+### Phase 2:planning 层 + Plan 结构(中)
+
+- **改**:`coordinator.rs` 空壳 → 消费 intent + plan_hint + 用户请求 → LLM 规划 → Plan DAG
+- Plan 数据结构 + planning LLM prompt(分解任务为子任务 + 依赖)
+- **execution 仍串行跑 Plan**(按 DAG 顺序,不并行)— 先验证规划质量
+- **收益**:任务分解能力(Phase 3 前验证 LLM 规划可靠性)
+- **风险**:中(LLM 规划质量:拆错/漏依赖)
+- **工作量**:中
+
+### Phase 3:并行 execution(大)
+
+- **改**:execution 按 Plan `parallel_groups` spawn 子 ReAct loop(tokio task)→ join → 汇总 LLM
+- PerSubFlowState 状态隔离 + sub_flow_id 事件路由
+- sub_permit 资源控制 + 失败降级 + 前端多流 UX
+- **收益**:真正并行加速
+- **风险**:**高**(并发状态/资源/UX/错误边界多)
+- **工作量**:大
+
+## 六、风险与回退
+
+- 每 Phase 独立可回退(常量开关:plan_hint_enabled / planning_enabled / parallel_execution_enabled)
+- Phase 1 纯函数,零回归风险
+- Phase 2/3 验证质量/ROI 再推进(Phase 2 验证规划质量 → 决定 Phase 3)
+
+## 七、关联
+
+- intent.rs(跑题 P0 已接入,CR-08)/ coordinator.rs 空壳(SMELL-P2-4)/ conditions(T-260614-11)
+- F-09 真并发(PerConvState,CR-07)/ per_conv permits=2(state.rs:121)
+- memory [[aichat-arch-extensibility]] / [[aichat-roadmap-ab-split]](B 路线)
+
+## 八、决策记录
+
+- **2026-06-20 用户**:场景常见,**必须做**。B 路线启动。
+- 实施:Phase 1(plan_hint,低风险独立)→ Phase 2(planning,验证质量)→ Phase 3(并行 execution)。不跳 Phase。
+
+## 九、核心功能定位(用户 2026-06-20 提升)
+
+并行多轮是 DevFlow **核心功能**(未来核心卖点),非边缘增强。**战略级投入**,按核心功能标准设计/打磨/测试,非凑合。
+
+## 十、全局平衡设计原则(并行多轮不孤立设计)
+
+核心功能须与 DevFlow 全局协调:
+
+| 全局维度 | 协调点 |
+|---|---|
+| **F-09 真并发** | 两层并发:conv 级(permits)+ sub_flow 级(sub_permit),共享全局限额池,防资源争抢 |
+| **A 路线(跑题改进)** | plan_hint 延伸 intent(已接入),不冲突;跑题收敛工具 + 并行编排互补 |
+| **资源全局** | cost/并发/性能:sub_permit≤3 + token 限额 + 用户可见 cost;与 llm_concurrency 全局协调 |
+| **工具/授权/审批** | 子流工具调用经同样授权白名单(本轮权限批)+ 审批(High risk);子流不绕过 |
+| **前端 UX 全局** | 多流展示与现有 conv/消息 UI 协调(子流折叠/进度,不破坏现有消息流) |
+| **架构演进** | coordinator/intent/per_conv/conditions 全局一致(Plan 数据结构贯穿,非各层各搞) |
+
+## 十一、打磨标准(三原则,核心功能级)
+
+对齐 memory [[ai-improvement-principles]]:
+
+- **优雅**:机制 > prompt 说教(Plan-driven 显式数据结构调度,非 LLM 硬控并行;Plan 可审查/可中断/可恢复)
+- **可靠**:每改进配兜底(规划质量校验 / 失败降级 / 资源限额 / sub_flow 超时)
+- **易迭代**:分阶段常量开关(`plan_hint_enabled` / `planning_enabled` / `parallel_execution_enabled`),每 Phase 可独立回退
+
+## 十二、规划调整(核心功能级 → 全局设计优先)
+
+核心功能 + 打磨 + 全局平衡 → **不草率 Phase 1**。调整:
+
+1. **全局架构设计优先**(下一步):多维度调研并行多轮与全局各层(intent/agentic/per_conv/coordinator/前端/资源/授权)的协调点 → 全局设计方案(数据流/状态机/资源池/UX 统一)
+2. **Phase 1 实施等全局设计成熟**(Plan 数据结构贯穿全局后,plan_hint 才有根基)
+3. **每 Phase 核心功能级测试**(单测 + 集成 + 边界 + 并发竞态),非跑通即止
+
+> 全局设计可能需多代理并行调研各维度(架构/资源/UX/并发/授权),汇总全局方案。