Files

T

- 无人值守长任务设计定稿,含效率与可观测补遗
- u-relay wire 协议规格与五项评估结论
- 新能力引入评估纪律五项清单
- todo 销账与狗粮短板分析登记

2026-10-04 16:27:32 +08:00

4.8 KiB

Raw Blame History

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 暂缓惯例一致，本设计备勘即可）。

4.8 KiB Raw Blame History Unescape Escape