From 4b5da38e28ce88587faf7678c9379d064cbdbd3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BB=9D=E5=B0=98?= <237809796@qq.com> Date: Sat, 20 Jun 2026 16:34:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E:=20=E5=B9=B6=E8=A1=8C?= =?UTF-8?q?=E5=A4=9A=E8=BD=AEPhase0=E8=90=BD=E5=9C=B0=E8=B7=AF=E7=BA=BF?= =?UTF-8?q?=E5=9B=BE+4agent=E8=AE=BA=E8=AF=81=E6=95=B4=E5=90=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase0十维方案(锁分片/三层Semaphore/sub_react_loop/审批sub_flow/压缩协调/UX事件schema/规划校验/planner+plan_hint/全局协调/测试矩阵)+路线图(DAG/关键路径115人时/0a-0b-0c三子阶段独立可回退);4agent共识P0机制缺失须先Phase0 --- .../单对话并行多轮-Phase0落地路线图-2026-06-20.md | 276 ++++++++++++++++++ .../单对话并行多轮-设计-2026-06-20.md | 106 +++++++ 2 files changed, 382 insertions(+) create mode 100644 docs/02-架构设计/单对话并行多轮-Phase0落地路线图-2026-06-20.md diff --git a/docs/02-架构设计/单对话并行多轮-Phase0落地路线图-2026-06-20.md b/docs/02-架构设计/单对话并行多轮-Phase0落地路线图-2026-06-20.md new file mode 100644 index 0000000..4a5ea04 --- /dev/null +++ b/docs/02-架构设计/单对话并行多轮-Phase0落地路线图-2026-06-20.md @@ -0,0 +1,276 @@ +# 单对话并行多轮 — Phase 0 落地路线图 + +> 2026-06-20 · aichat B 路线 · Phase 0(机制补齐)十维度评估落地 +> +> 上游设计:`单对话并行多轮-设计-2026-06-20.md`(三 Phase 框架)。 +> 本文档承接设计的「Phase 1/2/3 实施前必须先补齐的机制」,即 **Phase 0 = 物理可行性地基**。 + +--- + +## 一、定位:Phase 0 是什么 + +设计的 Phase 1/2/3 落地前,有**十项机制性前置**未补齐:锁分片、Semaphore 协议、子流 ReAct 内核、审批路由、压缩协调、UX 事件 schema、规划校验、planner 骨架、全局协调、测试矩阵。不补齐这些,Phase 1(plan_hint)可独立跑,**但 Phase 2/3 一动就串行化/死锁/污染**。 + +Phase 0 = 把这十项从「评估」推到「可独立验证落地」,为 Phase 2/3 铺路。**Phase 1 不阻塞 Phase 0**(plan_hint 是纯函数,可并行先做)。 + +--- + +## 二、十维度工作量与定位总览 + +| 维度 | 简称 | 工作量 | 性质 | 关键产出 | +|---|---|---|---|---| +| 0.1 | 锁分片模型 | 大(16h+,~85 调用点) | 结构性重构(地基) | per_conv/sub_flow 局部锁 + pending_approvals 独立锁 | +| 0.2 | 三层 Semaphore 协议 | 中(8-14h) | 新增资源池层 | global(8)/per_conv(6)/per_sub(3) + acquire_per_sub_flow + 耗尽降级 | +| 0.3 | sub_react_loop 抽离 | 大(16h+,900 行重构) | 核心内核解耦 | 纯 ReAct 内核 + 主 loop Plan 调度入口 | +| 0.4 | 审批 sub_flow 路由 | 中(8-12h) | 既有链路改造 | PendingApproval.sub_flow_id + trust 隔离 + DB 迁移 | +| 0.5 | 上下文压缩协调 | 中(4-16h) | 复用既有机制 | 子流独立 budget + join 后归档 + Semaphore 协调 | +| 0.6 | UX 事件 schema | 中-大(16-24h) | 跨前后端协议+UI | sub_flow_id 透传 + currentText Map + 子流卡片 + 两级中断 | +| 0.7 | 规划校验 | 中(4-16h) | 纯函数新增 | Plan::validate + Kahn 分层 + go/no-go 80% | +| 0.8 | planner + plan_hint | 中(4-8h) | 新文件零回归 | Plan/SubTask 结构 + plan_hint 纯函数 + 文档推翻 | +| 0.9 | 全局协调补 | 中(8-16h) | 跨模块收口 | 标题/提炼/审计 sub_flow_id 维度 + 完成判定 | +| 0.10 | 测试矩阵 | 中(8-16h) | 验证型新增 | 并发竞态 checklist(30-50 case) | + +**工作量总计**:约 **92-142 人时**(中位估 ~115 人时 ≈ 14-18 工作日单人,或 4-5 周含 review/联调)。 + +--- + +## 三、依赖图(DAG) + +> 箭头 A → B 表示「A 阻塞 B」(B 需要 A 先完成)。**粗体**=硬阻塞,普通=软依赖。 + +``` + ┌──────────────────────────────────────────────┐ + │ ▼ +┌──────┐ 强 ┌──────┐│ ┌──────┐ 强 ┌──────┐ 强 ┌──────┐ 强 ┌──────┐ +│ 0.1 │──────▶│ 0.3 │┴────▶│ 0.4 │─────▶│ 0.6 │─────▶│ 0.9 │───▶│ 0.10 │ +│锁分片│ │内核 │ │审批 │ │UX │ │协调补│ │测试 │ +└──┬───┘ └──┬───┘ └──────┘ └──────┘ └──────┘ └──────┘ + │ 强 │ 强 ▲ + │ ┌─────────┘ ┌──────────┘ + ▼ ▼ ▼ +┌──────┐ 强 ┌──────┐ 强 +│ 0.2 │◀────│ 0.5 │ (0.5 强依赖 0.2/0.3/0.1/0.6) +│Semaph│ │压缩 │ +└──┬───┘ └──────┘ + │ 强 + ▼ + (0.2 强阻塞 0.3, 0.5, 0.9) + +┌──────┐ 先 ┌──────┐ +│ 0.8 │─────▶│ 0.7 │ (0.8 定 Plan 结构 → 0.7 挂 validate/Kahn) +│plnr │ │校验 │ +└──┬───┘ └──┬───┘ + │ │ 0.7 阻塞 Phase 2/3,且 Kahn 输出喂 0.3 execution 调度 + │ ▼ + │ (0.3 execution 按 Kahn 层 spawn) + │ + └─ Phase 1(plan_hint 接入主 loop)的硬前置 +``` + +### 依赖关系明细(按维度) + +| 维度 | 硬前置(deps) | 软依赖 | 阻塞(blocks) | +|---|---|---|---| +| 0.1 锁分片 | — | — | 0.2, 0.3, 0.4, 0.5, 0.6, 0.9 | +| 0.2 Semaphore | 0.1, 0.3 | — | 0.3(子流 permit), 0.5, 0.9, Phase 1/2/3 | +| 0.3 sub_react_loop | 0.1(强) | 0.6(事件路由部分前置) | 0.2, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9 | +| 0.4 审批路由 | 0.1, 0.3 | 0.2 | 0.6, 0.9, Phase 3 | +| 0.5 压缩协调 | 0.1, 0.2, 0.3 | 0.6 | Phase 3, 0.9, 0.10 | +| 0.6 UX schema | 0.1, 0.3, 0.4 | — | Phase 3, 0.9 | +| 0.7 规划校验 | 0.8 | 0.6(plan_hint) | Phase 2, Phase 3, 0.3(execution 调度), 0.10 | +| 0.8 planner+plan_hint | 0.1, 0.2(软) | — | 0.7, Phase 1, Phase 2, 0.9 | +| 0.9 全局协调补 | 0.1, 0.2, 0.3, 0.6, 0.8 | — | 0.5(部分), 0.10, Phase 3 收尾 | +| 0.10 测试矩阵 | 0.1, 0.2, 0.4, 0.6, 0.7 | 0.9 | — (验证型,被测对象须先在) | + +### 循环依赖警示(需破环) + +**0.2 ⇄ 0.3 存在循环**:0.2 deps 列 0.3(sub_react_loop),0.3 deps 列 0.2(子流需 per_sub permit)。 + +**破环策略**(评估 seq 已隐含):0.2 的 `acquire_per_sub_flow` 接口与三层结构**可不依赖 0.3 内核实现**先落地(纯资源池层 + hook),0.3 子流 spawn 时消费该 hook。即: +- **0.2 先做到「接口就位、hook 待接」**(Semaphore 三层 + 公式 + 降级返回值),**不必等 0.3 内核**; +- 0.3 内核完成后接入 hook。 +- 这样 0.2 与 0.3 在**批2 内可并行**,破除循环。 + +同理 0.1 ⇄ 0.3(0.1 的 sub_flows HashMap 需 0.3 的 SubFlowState 定义):**0.1 分两小步** — 小步A(per_conv→Arc + pending 独立锁,纯结构,85 调用点机械迁移)先独立落地;小步B(sub_flows HashMap,等 0.3 SubFlowState)。 + +--- + +## 四、拓扑排序后的实施批次 + +### 批1:基础地基(机制层) + +> 目标:建立锁与资源的物理地基,无任何子流语义依赖。 + +| 顺序 | 维度 | 内容 | 独立验证 | +|---|---|---|---| +| 1.1 | **0.8** planner+plan_hint | 新文件,Plan/SubTask 结构 + plan_hint 纯函数 + 4-6 处文档推翻 | cargo check + 单测(对齐 intent.rs 52 测密度) | +| 1.2 | **0.7** 规划校验(纯函数部分) | Plan::validate + Kahn to_layers + 五类非法 + 回退开关占位 | 纯函数单测,go/no-go 验收留 Phase 2 | +| 1.3 | **0.1 小步A** per_conv→Arc + pending 独立锁 | 85 调用点机械迁移 + pending_approvals 独立 Arc | cargo check 全量 + F-09 单测重写绿 + 修复 chat.rs:380 自死锁 | +| 1.4 | **0.2(接口部分)** 三层 Semaphore 结构 + 公式 + 降级返回值 + per_conv 2→6 / global 3→8 上调 | 资源池层就位,hook 待接 | 三层独立单测 + 热改软收敛 + CAS 竞态 | + +**批1 出口判据**:①0.8/0.7 纯函数全测绿;②0.1 小步A 编译过 + 旧单测全绿 + 自死锁修复;③0.2 三层 Semaphore 可独立 acquire/drop,per_conv 上调后现有 5 调用点不回归。 + +### 批2:协调层(子流语义建立) + +> 目标:子流 ReAct 内核 + 审批路由 + 压缩协调,**子流真正可跑**(串行)。 + +| 顺序 | 维度 | 内容 | 独立验证 | +|---|---|---|---| +| 2.1 | **0.1 小步B** sub_flows HashMap(配合 0.3 SubFlowState) | PerConvState.sub_flows + 局部锁取锁接口 | 两 sub_flow 并发不互斥单测 | +| 2.2 | **0.3a** 抽纯 ReAct 内核 | run_agentic_loop 900 行解耦,主链先复用内核,**行为零变更** | 重构前后同输入消息序列/tool_result/DB 落库 byte 对比 | +| 2.3 | **0.3b** 主 loop Plan 调度入口 + sub_flow spawn(串行) | planning→spawn sub_react_loop→join→汇总,Phase 2 串行 execution 先跑通 | Plan DAG 顺序跑子流 + 汇总 LLM 消费正确 | +| 2.4 | **0.2(接入部分)** acquire_per_sub_flow hook 接入 0.3 spawn 处 | 子流 spawn 持 per_sub permit | global 耗尽降级返回 None,子流退串行不 panic | +| 2.5 | **0.4** 审批 sub_flow 路由 | PendingApproval.sub_flow_id + trust 隔离 + 高危缓存隔离 + DB 迁移 | 两子流同目录审批隔离 + try_continue 按 (conv,sub) 双键 | +| 2.6 | **0.5** 上下文压缩协调 | 子流独立 ContextManager + join 后归档 + Semaphore 协调 | 子流 token 独立 budget + 归档释放 + 不死锁 | + +**批2 出口判据**:①单 conv 多子流**串行**跑通(Plan→sub_flow→join→汇总);②子流审批按 sub_flow_id 路由,无信任/缓存污染;③子流 token 独立压缩,归档后主链 budget 正确。 + +### 批3:UX + 收口 + 验证 + +> 目标:前端可观测子流 + 全局协调收口 + 并发竞态测试。 + +| 顺序 | 维度 | 内容 | 独立验证 | +|---|---|---|---| +| 3.1 | **0.6** UX 事件 schema(协议层可提前到批2 末) | sub_flow_id 透传 + currentText Map + 子流卡片 + 两级中断 | 单链 sub_flow_id=None 100% 回归 + 双子流交错不串 | +| 3.2 | **0.9** 全局协调补 | 标题/提炼/审计 sub_flow_id 维度 + 完成 join barrier + permit 协调 | 提炼 barrier 到 join 后 + 审计按 sub_flow 回溯 + 标题去重 gate | +| 3.3 | **0.7** go/no-go 验收(配套) | N 任务抽检 ≥80% 合法率判据文档化 | 验收报告模板 | +| 3.4 | **0.10** 测试矩阵 | 并发竞态 checklist(30-50 case) + 核心 0 测文件拉到苛刻 | write_file 无 path 锁等缺陷暴露回流 0.1/0.3 | + +**批3 出口判据**:①前端双子流并发可见不混乱;②标题/提炼/审计跨子流正确;③并发竞态测试全绿(暴露的缺陷已回流修复)。 + +> **波1 可提前**:0.10 评估 seq 建议把「audit/mod.rs + agentic.rs 现有路径单测」提前到批2 收尾并行启动(被测对象是既有逻辑,不等子流)。 + +--- + +## 五、关键路径(决定 Phase 0 总工期) + +最长依赖链(取硬阻塞): + +``` +0.8(planner骨架,4-8h) + → 0.7(validate+Kahn,4-16h) [Kahn 输出喂 0.3 execution 调度] + → 0.1 小步A(锁分片结构,8-12h) [0.1 是 0.3 硬前置] + → 0.3(内核抽离+调度,16h+) [Phase 0 最大单点] + → 0.4(审批路由,8-12h) + → 0.6(UX schema,16-24h) + → 0.9(全局协调,8-16h) + → 0.10(测试矩阵,8-16h) +``` + +**关键路径长度(串行累加)**:4-8 + 4-16 + 8-12 + 16+ + 8-12 + 16-24 + 8-16 + 8-16 ≈ **72-120 人时**(约 9-15 工作日单人)。 + +**实际工期可压缩**:批2 内 0.3/0.4/0.5/0.6 部分可并行(0.4 等 0.3,但 0.6 协议层可与 0.4 并行;0.5 等 0.2/0.3 但可与 0.6 后半并行)。**假设 2 人并行**,Phase 0 实际工期约 **6-9 周**(含 review/联调/缺陷修复回流)。 + +**最大单点风险**:**0.3(run_agentic_loop 900 行重构)** — 它在关键路径中段,且阻塞下游 5 个维度。0.3 拆 a/b 两小步(先抽内核零变更验证,再改调度)是降低此风险的核心策略。 + +--- + +## 六、风险排序(按严重度) + +| # | 风险 | 维度 | 严重度 | 缓解 | +|---|---|---|---|---| +| R1 | **0.3 内核抽离回归面极大**(900 行耦合 8+ 横切关注点:guard/permit/审批/主题标记/意图收敛/候选 fallback/自动压缩/tool_result 摘要/reasoning_content 透传 BUG-260617-12) | 0.3 | 极高 | 0.3a 先抽内核主链复用零变更验证(byte 对比)→ 0.3b 再改调度;每剥离一项独立回归 | +| R2 | **锁顺序无运行时强制**(allowed_dirs R → per_conv → pending 跨函数跨模块,任一逆序即死锁,Rust 无 lock-ordering 检查) | 0.1 | 极高 | 文档化锁顺序约定 + 竞态测试(0.10)兜底 + review checklist | +| R3 | **返回类型变更级联**(conv()/conv_read() 改 Arc 后 85+ 调用点 .lock().await,部分非 async 上下文无法 .await) | 0.1 | 高 | 拆同步读视图 + async 访问器双轨;小步A 先做机械迁移验证编译 | +| R4 | **chat.rs:380 自死锁**(ai_approve path_auth 持外层锁重入 session.lock(),tokio::Mutex 非可重入) | 0.1/0.4 | 高 | pending_approvals 独立锁可绕开,但须验证路径不再触发(0.10 回归测) | +| R5 | **全局硬上限公式非 Semaphore 原生能力**(三层独立 Semaphore 无法自动保证 sum≤global,需 CAS 计数器,多子流并发 acquire 可能短暂超 max) | 0.2 | 高 | AtomicUsize 计数器 + CAS 容忍上限 + 单测验证不超卖 | +| R6 | **UX currentText Map 分流竞态**(flushCurrentText「末尾 assistant」启发式在多子流并行时回填目标错) | 0.6 | 高 | 改按 sub_flow_id 定位消息,非末尾启发式 | +| R7 | **提炼「完成」漏 join**(OnComplete 单点 spawn,并行多轮后主 loop converged 但子流未 join → 提炼读残缺 messages) | 0.9 | 中-高 | 引入 join barrier,提炼延迟到 join 后 | +| R8 | **write_file/patch_file 无 per-path 文件锁**(并发子流写同路径丢失更新,0.10 会暴露) | 0.10→回流 0.1/0.3 | 中-高 | 0.10 暴露后回流新增 DashMap(缺陷修复回功能维度,非 0.10 内) | +| R9 | **session_trust 信任污染**(PerConvState.session_trust 按 conv 共享,子流 A 审批目录 → 子流 B 自动放行) | 0.4 | 中 | trust 下沉 sub_flow state 或子流不走 trust 自动放行 | +| R10 | **i18n 特殊字符 prod runtime 报错**(vue-tsc 捕获不到,新子流卡片文案) | 0.6 | 中 | 改动 i18n 手动 grep message 值特殊字符(memory i18n-blindspot) | +| R11 | **PerConvState.sub_flows HashMap 无限膨胀**(子流未清理致内存泄漏) | 0.1 | 中 | 对齐 release_conv 模式,子流完成/失败/中断时 remove | +| R12 | **80% go/no-go 判据主观**(N 任务抽样规模/「合法」定义需先固化) | 0.7 | 中 | Phase 2 前产出验收 checklist 模板 | + +--- + +## 七、分批建议:Phase 0 拆三子阶段 + +> 评估 seq 已隐含三批结构,此处显式化为可独立验收的子阶段。 + +### Phase 0a:锁与资源地基(批1 全部) + +- **含**:0.8, 0.7(纯函数), 0.1 小步A, 0.2(接口部分) +- **独立价值**:①plan_hint/Plan 结构就位(Phase 1 可立即接入);②per_conv 上调 2→6 / global 3→8(单对话内标题+压缩+提炼+主loop 并发放宽,即时收益);③修复 chat.rs:380 自死锁(既有 bug 顺手清) +- **可独立验证**:cargo check + 单测,不改运行时行为(除 permit 上调) +- **预估**:24-48 人时 + +### Phase 0b:子流可跑(批2 全部) + +- **含**:0.1 小步B, 0.3(a+b), 0.2(接入), 0.4, 0.5 +- **独立价值**:单 conv 多子流**串行**跑通(Plan→sub_flow→join→汇总),验证 LLM 规划质量 + 子流隔离/审批/压缩正确 +- **可独立验证**:串行 execution 端到端(Phase 2 形态) +- **预估**:48-80 人时 +- **此阶段后可决策 Phase 3**:规划质量 ≥80% 合法率 + 子流机制稳定 → 推进 Phase 3 真并行;<80% 则回退优化 prompt/规划 + +### Phase 0c:UX 可观测 + 收口验证(批3 全部) + +- **含**:0.6, 0.9, 0.7(go/no-go), 0.10 +- **独立价值**:前端双子流可见 + 全局协调跨子流正确 + 并发竞态测试全绿 +- **可独立验证**:并行 execution 端到端(Phase 3 形态)可观测不混乱 +- **预估**:40-72 人时 + +**三子阶段均独立可回退**(常量开关:plan_hint_enabled / planning_enabled / parallel_execution_enabled / sub_flow_compress_enabled)。任一阶段验收不过,不影响前一阶段已落地价值。 + +--- + +## 八、Phase 1(plan_hint)硬前置 + +Phase 1 = 设计文档定义的「plan_hint 轻规划接入主 loop」。 + +| 硬前置维度 | 原因 | +|---|---| +| **0.8 plan_hint.rs** | Phase 1 接入的对象就是 0.8 产出的 plan_hint 纯函数。无 0.8 则 Phase 1 无代码可接。 | +| **0.8 Plan/SubTask 结构** | Phase 1 plan_hint 输出需对齐 Plan 结构(可并行组/顺序依赖字段)。 | + +**Phase 1 不阻塞项**:0.1/0.2/0.3/0.4/0.5/0.6/0.7/0.9/0.10 均非 Phase 1 硬前置(plan_hint 是纯函数,接入主 loop filter_tool_defs 延伸,不涉及子流/锁/并发)。 + +**结论**:**Phase 1 可在 Phase 0a 完成后立即启动**(仅需 0.8),与 Phase 0b/0c 并行推进。这与设计文档「Phase 1 低风险独立有价值,不跳 Phase」一致。 + +--- + +## 九、Phase 2/3 硬前置清单 + +| Phase | 硬前置维度 | 缺一则 | +|---|---|---| +| **Phase 2**(planning LLM 调度,串行 execution) | 0.8, 0.7(validate), 0.1, 0.3(内核+调度) | 无 validate 无 go/no-go;无 0.3 内核主 loop 无法改 Plan 调度器 | +| **Phase 3**(并行 execution) | 上述全部 + 0.2(三层 Semaphore), 0.4(审批路由), 0.5(压缩协调), 0.6(UX schema), 0.9(全局协调) | 缺任一则并行死锁/污染/前端混乱/资源爆炸 | + +**Phase 3 是十维度全部落地的最终验收点**。Phase 0c(0.10 测试矩阵)是 Phase 3 的并发竞态防线。 + +--- + +## 十、并行策略(2 人假设) + +| 阶段 | 人 A | 人 B | +|---|---|---| +| 0a | 0.8 planner+plan_hint → 0.7 纯函数 | 0.1 小步A 锁分片结构 → 0.2 Semaphore 接口 | +| 0b | 0.3a 内核抽离 → 0.3b 调度 | 0.4 审批路由 → 0.5 压缩协调(等 A 的 0.3) | +| 0c | 0.6 UX schema(协议层提前) → 0.9 全局协调 | 0.7 go/no-go 文档 → 0.10 测试矩阵 | + +**瓶颈**:0.3(人 A 串行承担,最大单点);0.4/0.5 依赖 0.3 完成后人 B 才能启动后半(0b 中段人 B 有空窗,可做 0.6 协议层或 0.10 波1 单测填补)。 + +--- + +## 十一、决策点(需用户确认) + +1. **是否接受 Phase 0 三子阶段拆分**(0a 锁资源地基 / 0b 子流可跑 / 0c UX 收口)?每子阶段独立可验收可回退。 +2. **0.3 是否接受 a/b 两小步**(先抽内核零变更验证 → 再改调度)?降低 900 行重构风险。 +3. **per_conv permits 2→6 / global 3→8 上调**是否在 0a 即部署(即时收益:单对话内标题+压缩+提炼+主loop 并发放宽)?需评估 provider 429 风险。 +4. **0.10 暴露的 write_file 无 path 锁等缺陷**,确认回流 0.1/0.3 修复(非 0.10 内就地改产品逻辑)? +5. **80% go/no-go 判据**:Phase 2 前产出验收 checklist(N 任务抽样规模/「合法」定义),是否接受人工抽检(无自动化)? + +--- + +## 十二、关联 + +- 上游设计:`单对话并行多轮-设计-2026-06-20.md`(三 Phase 框架) +- 十维度评估:本文档来源(已内化) +- 关联 memory:[[aichat-arch-extensibility]] / [[aichat-roadmap-ab-split]] / [[code-review-anti-contamination]] / [[i18n-message-compile-blindspot]] / [[dead-code-reserve-keep]] / [[workflow-cargo-timeout-wrap]] / [[review-batching-worktree-transient]] +- 关联代码:`run_agentic_loop`(agentic/mod.rs:308-1227)/ `process_tool_calls`(audit/mod.rs:205)/ `LlmConcurrency`(state.rs)/ `coordinator.rs`(df-ai 空壳)/ `PerConvState`(mod.rs) + +--- + +## 十三、决策记录 + +- **2026-06-20 规划师**:Phase 0 拆 0a/0b/0c 三子阶段,每子阶段独立可验收可回退;关键路径 72-120 人时(单人)/ 6-9 周(2 人并行);最大单点风险 0.3 内核重构(拆 a/b 两小步缓解)。Phase 1 仅硬前置 0.8,可在 0a 后立即启动与 0b/0c 并行。待用户确认五决策点后启动实施。 diff --git a/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md b/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md index f75e452..1097bdb 100644 --- a/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md +++ b/docs/02-架构设计/单对话并行多轮-设计-2026-06-20.md @@ -131,3 +131,109 @@ struct SubTask { 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 | 并行多轮物理上不并行(伪命题) | +| 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 独立锁) +- PerConvState 内 `sub_flows: HashMap>>`(每子流独立锁) +- `process_tool_calls` 改按 sub_flow_id 取局部锁,不持全 AiSession 锁 +- pending_approvals 独立 Arc>,与 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` +- 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)→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 设计落地。