# 上下文管理演进 — 执行计划 > 关联: `上下文管理演进-任务技术设计-2026-07-20.md` | 状态: 待执行 --- ## Wave 划分 3 个 Wave，每个 Wave 内 agent 可并行，Wave 间串行 gate。 ```mermaid graph LR subgraph "Wave 1 (4 agent 并行)" A1["Agent 1: T1 动态阈值"] A2["Agent 2: T2 命名空间存储"] A3["Agent 3: 接口契约定义"] end A3 -.->|"定义 downstream 接口"| A2 A1 --> G1["Gate 1: cargo check + 单测"] A2 --> G1 G1 --> subgraph "Wave 2 (3 agent 并行)" B1["Agent 4: T3 结构化摘要"] B2["Agent 5: T4 工作流 DAG"] end B1 --> G2["Gate 2: cargo check + 集成验证"] B2 --> G2 G2 --> subgraph "Wave 3 (2 agent 串行)" C1["Agent 6: T5 WorkingContext"] end ``` --- ## Wave 1：基础改造（4 agent 并行） ### Agent 1：T1 动态压缩阈值 **改动清单**：精确到行 | 文件 | 行 | 操作 | |------|----|------| | `src-tauri/src/commands/ai/agentic/context_lifecycle.rs` | 64 签名 | `maybe_auto_compress` 加 `sys_tokens: u32` 参数 | | 同上 | 88-92 触发条件 | `let budget` → `let available = budget.saturating_sub(sys_tokens)`；比较用 `available` 替代 `budget` | | `src-tauri/src/commands/ai/agentic/mod.rs` | ~1117 调用处 | `maybe_auto_compress(...)` 加 `sys_tokens` 实参（同作用域 line 964 已定义） | **接口契约**：`maybe_auto_compress` 签名变更——调用方需传入 `sys_tokens`。不影响其他模块。 **验证**：`cargo check -p devflow`；观察日志 `available` 值在 system prompt 大时显著小于 `budget`。 **回退**：删参数 + 恢复 `budget` 变量，2 行。 --- ### Agent 2：T2 工具命名空间存储 **接口契约**（Wave 1 必须先执行）： ```rust // crates/df-ai/src/namespace_store.rs — 新增，其他 agent 依赖此接口 pub struct NamespaceStore { .. } impl NamespaceStore { pub fn new(max_bytes: usize) -> Self; pub fn store(&mut self, key: &str, tool_name: &str, args: &Value, content: &str) -> String; pub fn read(&mut self, full_path: &str) -> Option<&str>; pub fn read_summary(&self, full_path: &str) -> Option<&str>; } pub fn should_use_namespace(content: &str, tool_name: &str) -> bool; pub const NAMESPACE_REF_PREFIX: &str = "namespace://"; pub const NAMESPACE_BYTE_THRESHOLD: usize = 2048; ``` **接线改动**： | 文件 | 行 | 操作 | |------|----|------| | `crates/df-ai/src/namespace_store.rs` | 新增 | 完整实现 + 单元测试 | | `crates/df-ai/src/lib.rs` | — | `pub mod namespace_store;` + `pub use` 重导出 | | `crates/df-ai/src/context_helpers.rs` | — | 新增 `NAMESPACE_REF_PREFIX`、`should_use_namespace`、`is_namespace_ref` | | `src-tauri/src/commands/ai/audit/mod.rs` | `process_tool_calls` ~380 行 | tool 执行完成后：`if should_use_namespace` → `ns.store(...)` → push 引用；else → push 原文 | | `src-tauri/src/commands/ai/mod.rs` 或 `state.rs` | `AiSession` struct | 新增 `namespace_store: NamespaceStore` 字段 | | `src-tauri/src/commands/ai/conversation.rs` | `save_conversation` | namespace 引用展开为原文再写 DB | **验证**： 1. `cargo test -p df-ai` — `namespace_store` 单元测试（store → read → LRU 淘汰） 2. 手动：`read_file("large.txt")` → DB 中 `tool_result` 内容为原文（引用已展开） 3. `history_tokens` 统计应显著下降（大工具结果只计引用 token） **与 Agent 3 的边界**：`namespace_store.rs` 实现不依赖 AiSession，纯数据结构的 `HashMap` 操作，零耦合，可独立开发和测试。接线到 AiSession 和 process_tool_calls 由本 agent 完成。 --- ### Agent 3：接口契约定义（跨 Wave 共享） 定义 Wave 2/Wave 3 依赖的数据结构，**仅定义不实现**，确保下游 agent 可独立编码。 ```rust // ── Wave 2 共享契约 ── /// 压缩摘要双格式（T3 输出，T5 消费） pub struct CompressedSummary { pub json_card: String, // JSON 卡片（主题/决策/待办） pub nl_summary: String, // 自然语言摘要（向前兼容） } // ── Wave 3 共享契约 ── /// 工作流 DAG 上下文块（T4 输出 → 注入 system prompt） pub struct WorkflowContextBlock { pub workflow_id: String, pub workflow_name: String, pub current_node: Option, pub completed: usize, pub total: usize, pub next_steps: Vec, } /// WorkingContext 常驻上下文（T5 实现） pub struct WorkingContext { pub goals: Vec, pub decisions: Vec, pub unresolved: Vec, pub current_step: Option, pub version: WorkingContextVersion, } pub enum GoalStatus { Active, Completed, Cancelled } pub struct GoalItem { pub id: String, pub text: String, pub status: GoalStatus } pub struct DecisionItem { pub question: String, pub decision: String, pub reason: String } pub struct StepInfo { pub step_name: String, pub status: StepStatus } pub enum StepStatus { Pending, InProgress, Done, Blocked } pub struct WorkingContextVersion { pub goals_changed_at: u32, pub decisions_changed_at: u32, pub unresolved_changed_at: u32, pub step_changed_at: u32, pub current_turn: u32, } ``` **验证**：`cargo check` — 编译器验证所有 use 路径和类型引用正确，无需运行时测试。 **简化**：Agent 3 先把上述结构体定义放进 `crates/df-ai/src/context_helpers.rs`，`pub use` 重导出。Wave 2/3 的 agent 直接引用，不用等。 --- ## Gate 1（Wave 1 → Wave 2） ``` 条件: □ cargo check --workspace 全部通过 □ cargo test -p df-ai 全部通过 □ cargo test -p devflow 全部通过（已有测试不受影响） 验证项: □ 日志: compress 触发时 available 减去 sys_tokens（T1） □ 手动: 大工具结果 DB 存原文（T2） □ 手动: namespace 引用格式正确（T2） 回滚: 单文件回退: T1 删参数,T2 删 `namespace_store.rs` + 恢复 process_tool_calls 原文 push ``` --- ## Wave 2：结构化改进（3 agent 并行） ### Agent 4：T3 L3 结构化摘要 **前置依赖**：Agent 3 定义了 `CompressedSummary` 结构 **改动清单**： | 文件 | 行 | 操作 | |------|----|------| | `src-tauri/src/commands/ai/compress.rs` | 45-52 签名 | `compress_via_llm` 返回类型 `Result` → `Result` | | 同上 | 82-86 prompt 构造 | 改 `compress_prompt` 模板要求输出 JSON+NL 双格式 | | 同上 | 114-119 clean + 返回 | `clean_summary` 适配双格式：提取 JSON 段 + NL 段，分别验证退化 | | 同上 | 新增 | `extract_between` 辅助函数（提取 `<<>>...<<>>` 之间的内容） | | `src-tauri/src/commands/ai/prompt.rs` | 240-290 | `compress_prompt` 模板新增 JSON+NL 双格式输出要求 | | `src-tauri/src/commands/ai/agentic/context_lifecycle.rs` | 145-155 消费处 | `Ok(Some(summary))` 分支中 `insert_at` 内容改为双格式嵌入 | | 同上 178-210 兜底 | 关键词摘要降级 | 关键词降级不改，仍是纯文本（`keyword_fallback` 无 JSON） | **验证**： 1. `cargo test -p devflow` — compress 单测通过 2. 手动：触发压缩 → DB 中 system 消息含 `<<>>` 标记 3. 手动：关键词摘要降级路径仍为纯文本（不受影响） **与 Agent 5 无依赖**：T3 只改 compress 路径，T4 只改 system prompt 注入，零耦合。 --- ### Agent 5：T4 工作流 DAG 注入 **前置依赖**：Agent 3 定义了 `WorkflowContextBlock`，Agent 2 的 namespace 接口已就绪（弱依赖——仅用于产出关联） **改动清单**： | 文件 | 行 | 操作 | |------|----|------| | `src-tauri/src/commands/ai/workflow_context.rs` | 新增 | `load_dag()`, `build_active_path()`, `summarize_node()` | | `src-tauri/src/commands/ai/agentic/mod.rs` | ~1110-1128 | `build_for_request` 之前：检测 `conv.workflow_id` → 加载 DAG → 构建 context block → 注入 system prompt | | `crates/df-ai/src/context_helpers.rs` | 新增常量 | `WORKFLOW_DAG_MARKER` | **核心逻辑**： ```rust // workflow_context.rs pub fn build_active_path(dag: &Dag, current_node_id: &str) -> WorkflowContextBlock { let path = dag.path_to_root(current_node_id); // 到根路径 let next = dag.children(current_node_id, 2); // 后续 2 层 WorkflowContextBlock { workflow_id: dag.id.clone(), workflow_name: dag.name.clone(), total_nodes: dag.nodes.len(), completed_nodes: dag.nodes.iter().filter(|n| n.status == "completed").count(), current_node: summarize_node(dag.get_node(current_node_id)), next_nodes: next.into_iter().map(|n| summarize_node(n)).collect(), } } ``` **关键安全**： ```rust // mod.rs: system_prompt 注入处 if let Some(wf_id) = &conv.workflow_id { if let Ok(dag) = df_workflow::Dag::load(&db, wf_id) { let block = build_active_path(&dag, &conv.current_node_id); system_prompt = format!("[工作流] {}\n{}", block.to_system_text(), system_prompt); } // Dag::load 失败 → 静默跳过 } // workflow_id == None → 行为完全不变 ``` **验证**： 1. `cargo check -p devflow` — 依赖 `df-workflow` crate 的 `Dag::load` 接口 2. 手动：创建带工作流的对话 → system prompt 含 `[工作流]` 块 3. 手动：自由对话（无 workflow）→ system prompt 不变 --- ## Gate 2（Wave 2 → Wave 3） ``` 条件: □ cargo check --workspace 全部通过 □ cargo test --workspace 全部通过 □ 前端 vue-tsc --noEmit 通过 验证项: □ 手动: 压缩后 DB system 消息含 JSON 标记（T3） □ 手动: 工作流对话注入 DAG 块（T4） □ 手动: 自由对话不受影响（T4 安全） □ 全量: history_tokens 在 T2 基础上再次下降（T3 摘要更精简） 回滚: T3: 回退 compress.rs 签名 + prompt.rs 模板 T4: 删 workflow_context.rs + 恢复 mod.rs system_prompt 拼接 ``` --- ## Wave 3：常驻上下文（1 agent 串行） ### Agent 6：T5 WorkingContext 分层注入 **前置依赖**： - Agent 3 的 `WorkingContext` 结构定义需在 `context_helpers.rs` 中（已在 Wave 1 Gate 前到位） - Agent 4 的 `CompressedSummary` 用于 `reset_all_with_summary`（弱依赖——无 NL 摘要时可跳过） **改动清单**： | 文件 | 行 | 操作 | |------|----|------| | `crates/df-ai/src/context_helpers.rs` | 已有定义 | `WorkingContext` / `WorkingContextVersion` 等已由 Agent 3 定义 | | `crates/df-ai/src/context/mod.rs` | `ContextManager` struct | 新增字段 `pub working_context: Option` | | `src-tauri/src/commands/ai/agentic/mod.rs` | ~960 system_prompt 拼接处 | 在 `build_for_request` 之前调 `WorkingContext::build_injection()` 注入 L1a+L1b | | 同上 | tool_registry 注册 | 注册 `read_context` 工具（L1c） | | `src-tauri/src/commands/ai/agentic/context_lifecycle.rs` | ~145-155 压缩成功后 | 调 `ctx.version.reset_all_with_summary(&summary)` | | `src-tauri/src/commands/ai/commands/chat.rs` | `ai_chat_clear_context` | 归档后 reset WorkingContext（归档 = 上下文状态变更） | **脏标记核心逻辑**： ```rust impl WorkingContext { pub fn build_injection(&self, recent_turns: u32) -> String { let mut parts = vec![]; // L1a: 当前步骤（每轮必带，~200 tokens） if let Some(step) = &self.current_step { parts.push(format!("当前步骤: {}", step.step_name)); } // L1b: 过去 recent_turns 轮内有变更才注入 let threshold = self.version.current_turn.saturating_sub(recent_turns); let has_active = self.goals.iter().any(|g| g.status == GoalStatus::Active); if has_active && self.version.goals_changed_at >= threshold { let active: Vec<_> = self.goals.iter() .filter(|g| g.status == GoalStatus::Active) .collect(); parts.push(format!("目标({}): {}", active.len(), active.iter().map(|g| g.text.as_str()).collect::>().join("; "))); } if self.version.unresolved_changed_at >= threshold && !self.unresolved.is_empty() { parts.push(format!("待解: {}", self.unresolved.join("; "))); } parts.join("\n") } } ``` **验证**： 1. `cargo test -p df-ai` — `WorkingContext::build_injection` 单元测试（脏标记正确跳过/注入） 2. 手动：观察 system prompt 含 L1a（当前步骤）和条件性的 L1b（有变更时） 3. 手动：压缩触发后，下轮 L1b 正常注入（`reset_all` 生效） 4. 开关：`GOAL_PIN_ENABLED=false`（或等价的 workincontext 开关）→ 行为恢复到改动前 --- ## 汇总：执行序列 ``` Week 1: Day 1: Agent 3 定义契约（30 分钟） → 其余 3 agent 拿到接口开始编码 Day 1-2: Agent 1 T1 + Agent 2 T2 并行编码 Day 3: Gate 1 验证 + 修复 Week 2: Day 4-5: Agent 4 T3 + Agent 5 T4 并行编码 Day 6: Gate 2 验证 + 修复 Week 3: Day 7-9: Agent 6 T5 编码（由于串行依赖，此阶段无并行） Day 10: 最终验证 + 全量回归测试 ``` ## 回滚总策略 | 场景 | 操作 | |------|------| | T1 有问题 | 删 `sys_tokens` 参数 + 恢复 `budget` 变量 → 2 行回退 | | T2 有问题 | 删 `namespace_store.rs` + 恢复 `process_tool_calls` push 原文 → 1 文件回退 | | T3 有问题 | 回退 `compress.rs` + `prompt.rs` 到 `Result` → 2 文件回退 | | T4 有问题 | 删 `workflow_context.rs` + 恢复 mod.rs system_prompt 拼接 → 1 文件回退 | | T5 有问题 | `GOAL_PIN_ENABLED=false` 等效开关 → 配置回退，不改代码 | | 全量回退 | `git revert ` |