# context_helpers.rs 拆分备勘（REFACTOR-260619-09 修订）· 设计（2026-10-04）

> 来源：todo.md「REFACTOR-260619-09 [P2 暂缓] — context.rs(1332)等 F-15 压缩链路稳定再拆」。
> **勘误（2026-10-04 现场核实）**：原条目指向的 `crates/df-ai/src/context.rs`（1332 行）**已不存在**——context 已拆为目录模块 `context/{mod.rs(38.5KB), sanitize.rs(64.5KB), manager_tests.rs(51.8KB)}`。**原 REFACTOR-260619-09 事实完成，建议 todo 销账**。
> 但拆分域出现**新超标 God 文件**：`crates/df-ai/src/context_helpers.rs` = **1733 行**（80KB，无测试分离），TokenEstimator/ContextConfig/工具结果压缩/分组/淘汰/公共工具混居。本设计以它为对象。
> 同域现状参考：df-ai/src/ 下平级大文件尚有 coordinator.rs(68.7KB)、intent.rs(66.8KB)、anthropic_compat.rs(69.9KB)、openai_compat.rs(65.4KB)——均超 60KB，属后续拆分候选池，本期不扩scope。

## 1. 拆分对象画像

`context_helpers.rs` 1733 行，混合至少六类职责（已知锚点）：
- **Token 估算**：TokenEstimator 相关（行段待精确，拆时以 read_symbol 逐个锚定）；
- **上下文配置**：ContextConfig 及常量；
- **工具结果压缩**：`:410 TOOL_RESULT_SUMMARIZE_BYTES=2048`、`:425 TOOL_RESULT_JSON_STR_FIELD_MAX=512`、`should_summarize_tool_result(:440)`、extract_key_info 系列（head/tail/array/char/json-str 五种截断）；
- **namespace 引用转发**：`:646-647 NAMESPACE_REF_PREFIX`（仅常量 re-export，薄）；
- **淘汰/分组逻辑**（eviction/grouping，与 context/mod.rs 的 ContextManager 呼应）；
- **杂项公共工具**（is_han `:396` 等纯函数）。

**前置动作（拆分前 0.5 天）**：用 read_symbol 对 1733 行做一次全骨架清点，产出「函数→职责块→行段」映射表落 `docs/05-代码审查/context_helpers骨架-2026-10-XX.md`——本设计给出块划分与迁移策略，具体行号以骨架表为准。

## 2. 目标模块划分（建议）

拆为 `context_helpers/` 目录（与 context/ 同款目录化先例，lib.rs 加 `pub mod` 不动外部路径——`df_ai::context_helpers::X` 引用形态不变）：

| 子模块 | 职责 | 预计行数 | 风险 |
|---|---|---|---|
| `token.rs` | TokenEstimator + 估算纯函数 | ~250 | 低（纯函数，单测易迁） |
| `config.rs` | ContextConfig + 阈值常量（含 TOOL_RESULT_* 六常量） | ~150 | 低 |
| `tool_compress.rs` | should_summarize_tool_result + extract_key_info 系列 | ~350 | **中（压缩热点，殿后）** |
| `eviction.rs` | 淘汰/分组 + namespace 常量转发 | ~400 | **中高（压缩链路高频改动区，殿后）** |
| `misc.rs` | is_han 等纯工具（或就近下沉使用方） | ~100 | 低 |
| `mod.rs` | re-export 保路径 + 少量真公共胶水 | ~50 | — |

**测试**：本文件测试与生产代码混居（无 #[cfg(test)] 分离迹象，拆时确认）——随成员走，`token.rs`/`tool_compress.rs` 各带自己的测试模块；若测试体量大，仿照 context/manager_tests.rs 惯例平级 `helpers_tests.rs`。

## 3. 迁移顺序（四批，压缩热点殿后）

```
批1 低风险:  config.rs + misc.rs        → cargo test -p df-ai 全绿
批2 低风险:  token.rs (+其单测)          → 同上
批3 热点:    tool_compress.rs           → 同上 + 手测长会话压缩路径
批4 热点:    eviction.rs + mod.rs 收口   → 同上 + 手测 eviction 滚动摘要
```

每批验收门：`cargo test -p df-ai`（基线 560+）+ `cargo check --workspace`；批3/4 加：起应用开长会话触发压缩与淘汰各一次，行为无回归。**每批独立提交**，冲突时可安全停在任意批。

## 4. re-export 兼容策略

`context_helpers/mod.rs` 对全部原 pub 项 `pub use` 转发——仓内 grep 显示引用方走 `df_ai::context_helpers::*` 与 `crate::context_helpers::*` 两种路径，目录化后**零调用方改动**。仅 `use df_ai::context_helpers` 整体 use（若有）需 mod.rs 全量 re-export 兜住。

## 5. 与原条目的关系

- todo 销账动作：REFACTOR-260619-09 原 context.rs 拆分 ✅ 完成；**新登记**本设计为 REFACTOR-261004-01（context_helpers.rs 1733 行拆分），优先级维持 P2 暂缓——**触发条件**：上下文管理批（无人值守 P0/P1）合入且稳定 ≥1 周后启动批1/2（低风险先行），批3/4 继续等压缩链路静默期；
- context_helpers.rs 若在触发前因功能开发继续膨胀 >2000 行，优先把「工具结果压缩」块先行拆出（批3 提前），不整文件硬拆。

## 6. 工作量估算

骨架清点 0.5 天 + 批1/2 各 0.5 天 + 批3/4 各 1 天 ≈ 3.5 天（可拆散穿插，非连续占用）。

## 7. 拍板点（1 项）

- 触发时机：上下文管理批稳定后自动启动 vs 等用户指令？建议**等用户指令**（与 REFACTOR 暂缓惯例一致，本设计备勘即可）。