绝尘
4b5da38e28
Phase0十维方案(锁分片/三层Semaphore/sub_react_loop/审批sub_flow/压缩协调/UX事件schema/规划校验/planner+plan_hint/全局协调/测试矩阵)+路线图(DAG/关键路径115人时/0a-0b-0c三子阶段独立可回退);4agent共识P0机制缺失须先Phase0
240 lines
13 KiB
Markdown
240 lines
13 KiB
Markdown
# 单对话并行多轮推理 — 设计文档
|
||
|
||
> 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/并发/授权),汇总全局方案。
|
||
|
||
## 十三、4 Agent 多角度论证共识(2026-06-20 架构/并发/UX/全局平衡)
|
||
|
||
4 agent 独立核验源码(非信文档自述)后**一致结论**:方向站得住,但 P0 机制缺失,**不可直接进 Phase 1**,须先 Phase 0 全局设计补机制。
|
||
|
||
### 🔴 致命(物理不可并行,必须先解决)
|
||
|
||
| # | 风险 | 证据 | 影响 |
|
||
|---|---|---|---|
|
||
| P0-1 | **AiSession 单 Mutex 全锁**:`process_tool_calls(&mut AiSession)` 持全锁,多子流并发必串行化 | audit/mod.rs:206 签名 / mod.rs:271 单 Arc<Mutex> | 并行多轮物理上不并行(伪命题) |
|
||
| P0-2 | **三层 Semaphore 配额冲突**:global=3 硬天花板,3conv×3sub=9 路抢 3 permit → 6 阻塞 | state.rs:526 LlmConcurrency::new(3,2) 无 sub 层 | 并行收益归零 |
|
||
| P0-3 | **子 loop 复用 run_agentic_loop 不可行**:14 参 + GeneratingGuard + per_conv permit + 审批全绑单 conv | agentic/mod.rs:308-322 | 子流复用必互相复位/抢占/路由错乱 |
|
||
|
||
### 🔴 安全
|
||
|
||
| # | 风险 | 证据 |
|
||
|---|---|---|
|
||
| P0-4 | **审批无 sub_flow 路由**:PendingApproval 无 sub_flow_id,审批恢复子流 context 路由不明 | mod.rs:556 struct |
|
||
| P0-5 | **session_trust 并发信任污染**:子流 A 批准目录 → 子流 B 自动放行,绕过独立审批 | audit/mod.rs:356 trust 命中 / PerConvState.session_trust 会话级共享 |
|
||
|
||
### 🔴 Phase 3 失败前置
|
||
|
||
| # | 风险 | 证据 |
|
||
|---|---|---|
|
||
| P0-6 | **coordinator 语义漂移**:多 Agent 协作空壳 → Plan 调度,未推翻既有"B 路线多 agent 占位"决策(4 处文档) | coordinator.rs:1-3 / 功能决策记录 L427-429 |
|
||
| P0-7 | **规划质量校验机制空**:Plan 无 validate()(环/粒度/依赖完整性),Phase 2 无 go/no-go 量化判据 | coordinator.rs 空壳 + Plan 结构 |
|
||
| P0-8 | **上下文压缩协调缺失**:子流 messages 压缩/丢弃策略空 → token 爆炸 | compress_via_llm agentic/mod.rs:725 |
|
||
|
||
### 🟡 重要(Phase 1/3 前补)
|
||
|
||
- PerSubFlowState 字段共享/独立边界未定义(messages/stop/iteration 独立;trust/language/model 共享)
|
||
- UX 事件 schema 无 sub_flow_id(G1-G7:currentText 单累加器/AiMessage 无字段/无生命周期事件/streaming 单布尔/pending 单值)
|
||
- intent 与 plan 语义错位(filter 按主消息单 intent 收敛,子流跨多 intent 工具被滤)
|
||
- 失败降级边界未定义(全子流失败/汇总 LLM 失败/sub_flow 超时回滚)
|
||
- plan_hint 塞 intent.rs 职责模糊 → 独立 plan_hint.rs
|
||
- Plan deps 与 parallel_groups 冗余 → 删 parallel_groups 只存 deps(Kahn 分层)
|
||
- 标题生成/知识提炼/记忆审计 sub_flow_id 协调缺失
|
||
|
||
## 十四、Phase 0 全局设计(实施前置,整合 4 agent 解决方案)
|
||
|
||
**目标**:补 P0 机制,使并行多轮物理可行 + 安全 + 全局协调。**Phase 1 实施的硬前置**。
|
||
|
||
### 0.1 锁分片模型(P0-1)
|
||
- `AiSession.per_conv: HashMap<conv_id, Arc<Mutex<PerConvState>>>`(每 conv 独立锁)
|
||
- PerConvState 内 `sub_flows: HashMap<sub_flow_id, Arc<Mutex<SubFlowState>>>`(每子流独立锁)
|
||
- `process_tool_calls` 改按 sub_flow_id 取局部锁,不持全 AiSession 锁
|
||
- pending_approvals 独立 Arc<Mutex<HashMap>>,与 per_conv 锁不嵌套
|
||
- **锁顺序约定**(文档化):allowed_dirs(R) → release → per_conv Mutex → release → pending Mutex
|
||
|
||
### 0.2 三层 Semaphore 协议(P0-2)
|
||
- `global`(全应用 LLM 硬上限,上调如 8) > `per_conv`(单 conv 总并发=主+辅+sub,上调如 6) > `per_sub_flow`(单 conv 内 sub 并发,默认 3)
|
||
- 公式:`sum(sub_permit across convs) ≤ global`,超限降级串行(回退 Phase 2 串行 execution)
|
||
- 新增 `acquire_per_sub_flow(conv_id)` + 全局硬上限 `max_total_sub_flows`(如 8)
|
||
- per_conv permits 上调(主1 + 辅2 + sub3 = 6),否则子流饿死
|
||
|
||
### 0.3 sub_react_loop(P0-3)
|
||
- 抽 run_agentic_loop 核心 ReAct 内核(stream→tool_calls→tool_result→loop),**无 guard/无 per_conv permit/不写 pending_approvals**
|
||
- 主 loop 改 Plan 调度器:planning → spawn sub_react_loop(parallel_groups)→ join → 汇总
|
||
- GeneratingGuard 升级 sub_flow 级或共享 conv 级
|
||
|
||
### 0.4 审批 sub_flow 路由(P0-4/5)
|
||
- PendingApproval 加 `sub_flow_id: Option<String>`
|
||
- ai_approve/try_continue 按 (conv_id, sub_flow_id) 路由
|
||
- session_trust 并发隔离:子流不走 trust 自动放行(或 per-sub_flow trust)
|
||
- 高危去重缓存加 sub_flow_id 维度
|
||
|
||
### 0.5 上下文压缩协调(P0-8)
|
||
- PerSubFlowState.messages 独立压缩(子流级 budget)
|
||
- 子流结果回主后,子流 messages 标 archived(释放 token,防会话膨胀)
|
||
|
||
### 0.6 UX 事件 schema(G1-G7)
|
||
- AiChatEvent 加 `sub_flow_id?: string`(undefined=主链/单流,向后兼容)
|
||
- 新增 AiSubFlowStarted/Completed/Cancelled 三事件
|
||
- AiMessage 加 sub_flow_id/sub_flow_goal
|
||
- currentText 分流:planning→sub_flows_running(Map<sub_flow_id,text>)→summarizing(复用单源)→completed
|
||
- streaming 分层:streaming(整轮布尔)+ subFlowsStreaming(计数)
|
||
- 子流 UI 模型:每子流=可折叠 assistant 卡片(标题=goal+进度),汇总=主链气泡
|
||
- 中断两级:整轮 stopChat(已有)+ sub_flow ai_cancel_sub_flow(新 IPC)
|
||
|
||
### 0.7 规划校验 + Phase 2 go/no-go(P0-7)
|
||
- `Plan::validate()` 枚举 PlanError {CycleDetected/UnknownDep/OrphanSubtask/SubtaskWithoutTools}
|
||
- Plan 删 parallel_groups,只存 deps,运行时 Kahn 分层(单一真相源)
|
||
- Phase 2 验收:人工抽检 N 任务,规划合法率 ≥ 80% 才进 Phase 3
|
||
- 规划失败/校验不过 → 回退单链 ReAct(planning_fallback_to_react)
|
||
|
||
### 0.8 planner.rs + plan_hint.rs(P0-6 + 职责)
|
||
- 新建 `crates/df-ai/src/planner.rs`(Plan 调度,纵向拆解)
|
||
- coordinator.rs **保留**多 Agent 协作占位(横向角色),不挪用
|
||
- plan_hint 独立 `plan_hint.rs`(纯函数),不塞 intent.rs
|
||
- 显式推翻功能决策记录 L427-429(coordinator 语义收窄)+ 更新 4 处文档
|
||
|
||
### 0.9 全局协调补(标题/提炼/记忆)
|
||
- 标题生成:子流 LLM 与标题争 per_conv permit 协调
|
||
- 知识提炼:"对话完成"= 所有子流 join 完成;提炼输入主 messages
|
||
- 记忆/审计:audit_tool_call 加 sub_flow_id 维度(回溯)
|
||
|
||
### 0.10 测试矩阵(核心功能级)
|
||
- 并发竞态:同文件并发写 / sub_flow 审批与 stop 竞态 / Plan 五类非法形态 / 全子流失败 / 汇总 LLM 失败 / global 耗尽降级 / trust 并发污染 / 高危缓存并发未命中
|
||
- 对齐 intent.rs 苛刻测密度
|
||
|
||
## 十五、决策记录(更新)
|
||
|
||
- **2026-06-20 用户**:场景常见,**必须做,核心功能,打磨漂亮,全局平衡**。B 路线启动。
|
||
- **2026-06-20 4 agent 论证**:P0 机制缺失,**Phase 0 全局设计优先**(十四章 10 维度),Phase 1 等全局设计成熟。
|
||
- 实施:Phase 0(全局设计补机制)→ Phase 1(plan_hint)→ Phase 2(planning 验证)→ Phase 3(并行 execution)。不跳 Phase。
|
||
- **待用户确认**:Phase 0 十维方案(0.1-0.10)是否认同 → 启动 Phase 0 设计落地。
|