代码审查报告
📌 前置声明
-
审查范围 ：本报告基于提供的程序文本做静态结构化排查，可覆盖95%以上能通过代码文本定位的结构、函数、命令、参数、数值边界类问题。
-
方案性质：所有参考方案为通用工程实践建议，实际落地需结合项目具体的业务约束、上下游模块依赖、特殊硬件适配要求、未在代码文本内体现的隐藏边界条件做适配调整。
-
局限性说明：若存在本程序文本外的隐藏约束、运行时动态注入逻辑、上下游模块私有约定，可能存在未覆盖的边界场景，审查结果需结合实际运行环境验证。
-
使用声明：本报告仅供技术参考，不构成对审查对象的整体性评价。报告结论基于当前提供的代码文本快照，不代表对项目历史版本或未来版本的判断。
审查对象 ：基于 AtomCode 的 StubCompaction / OverflowCompaction 模块（约420行）的程序文本分析
审查方式：六轮递进式静态结构审查（第零轮至第五轮）
问题总计：8项（致命0项 / 严重2项 / 一般6项）
严重度定义
| 等级 | 标识 | 定义 |
|---|---|---|
| 致命 | 🔴 | 极高概率触发崩溃/内存泄漏/死锁/数据损坏，建议优先处理 |
| 严重 | 🟠 | 特定场景下高概率触发异常（大流量/长会话/极端输入/并发竞争） |
| 一般 | 🟡 | 代码质量问题，不影响核心功能正确性，属于技术债务 |
问题总览
| 编号 | 位置 | 所在函数/区域 | 严重度 | 问题类型 | 预估工作量 |
|---|---|---|---|---|---|
| 1 | plan→aggressive_stub_rewrites→truncate_rewrites |
OverflowCompaction |
🟠 | 结构 | 1天 |
| 2 | overflow_plan |
OverflowCompaction |
🟠 | 结构 | 0.5天 |
| 3 | summarize |
OverflowCompaction |
🟡 | 结构 | 0.5天 |
| 4 | build_compact_stub |
全局 | 🟡 | 数值边界 | 0.3天 |
| 5 | active_turn_start |
全局 | 🟡 | 结构 | 0.3天 |
| 6 | call_id_to_tool |
全局 | 🟡 | 结构 | 0.3天 |
| 7 | will_summarize |
OverflowCompaction |
🟡 | 结构 | 0.3天 |
| 8 | truncate_rewrites |
OverflowCompaction |
🟡 | 结构 | 0.3天 |
详细问题清单
问题1 | plan→aggressive_stub_rewrites→truncate_rewrites | OverflowCompaction | 🟠 | 结构
定位 ：OverflowCompaction::plan 调用链：overflow_plan → aggressive_stub_rewrites / truncate_rewrites / summarize
问题描述 ：一个 plan 调用链跨越了三个不同物理性质的操作------纯文本替换（rewrites）、消息截断（truncate_rewrites）、LLM 总结（summarize）。这三种操作的性质截然不同：前者是确定性的文本替换（刚体），中者是基于字符预算的截断（流态），后者是依赖外部 LLM 的生成（外部流态）。三者被混在同一个函数内通过 attempt 参数分支调度，违反了"一机一池一操作"的机床纯净原则。
参考方案 ：将三种操作拆分为三个独立的机床函数，由外层 plan 调度器根据 attempt 选择调用。每个机床只做一种物理操作，内部不包含其他性质的调用。
问题2 | overflow_plan | OverflowCompaction | 🟠 | 结构
定位 ：overflow_plan 函数内部 match attempt 三个分支
问题描述 ：overflow_plan 使用 match attempt 做三分支选择------0=激进截断、1=硬截断、2=LLM 总结。三分支的判定逻辑（match）与三种操作的执行代码混合在同一个函数内。调度决策（选哪个策略）和执行（具体操作）没有分离。应外提为独立的策略选择器。
参考方案 ：将 attempt 的分发逻辑上提到 plan 层，overflow_plan 退化为接收确定的分支参数，不再做 match 选择。或改为策略注册表（[Box<dyn OverflowTier>]），用查表替代 match。
问题3 | summarize | OverflowCompaction | 🟡 | 结构
定位 ：summarize 函数内部逻辑
问题描述 ：一个函数混合了三种操作------渲染历史消息为文本（render_transcript，纯计算）、构建 prompt（字符串拼接，纯计算）、调用外部 LLM（provider.chat_stream，流态 I/O）。前两者是刚体机床，最后一个是流态外部依赖，三者混在一个函数内。render_transcript 和 prompt 构建应外提为独立的纯函数。
参考方案 ：拆为三个机床------render_span（纯渲染）、build_summary_prompt（纯拼接）、call_summarizer（纯 LLM 调用）。调度器 summarize 串联三者。
问题4 | build_compact_stub | 全局 | 🟡 | 数值边界
定位 ：build_compact_stub 函数对 first_line 的截断逻辑
问题描述 ：chosen.chars().take(80).collect() 对输出首行做 80 字符硬截断。当首行恰好是有效的长信息时，硬截断可能切断关键内容。当前采用字节截断而非 CJK 安全的字符截断，但已使用 .chars() 正确迭代，无 UTF-8 截断风险。问题在于 80 字符的上限是硬编码常量，未参数化。
参考方案 ：将 80 提升为 const FIRST_LINE_CHAR_LIMIT: usize = 80，或通过配置传入，增加可调性。这不是功能性缺陷，但硬编码常数在未文档化时属于技术债务。
问题5 | active_turn_start | 全局 | 🟡 | 结构
定位 ：active_turn_start 函数内部逻辑
问题描述 ：一个函数同时包含三个操作------收集所有非合成 User 消息的索引（纯过滤）、判断是否小于 keep_recent_turns（纯比较）、返回边界索引（纯输出）。过滤和判定可以分离为两个独立机床，但当前代码量较小，混合态的严重度较低。
参考方案 ：外提 collect_turn_starts(msgs) -> Vec<usize> 为独立的纯过滤函数。active_turn_start 接收该列表做判定。过滤逻辑可独立测试。
问题6 | call_id_to_tool | 全局 | 🟡 | 结构
定位 ：call_id_to_tool 函数内部逻辑
问题描述 ：遍历所有消息，对 Role::Assistant 消息提取 tool_calls 并插入 HashMap。遍历和插入两个操作混合。虽然代码简单，但遍历逻辑和 HashMap 构建属于不同性质的操作------遍历是数据流读取，HashMap 是状态构建。
参考方案 ：保持当前实现，但标注为"轻度混合态，可接受"。如果 HashMap 需要复用，可外提为接收 &[ToolCall] 而非 &[Message] 的接口，将消息遍历和工具映射解耦。
问题7 | will_summarize | OverflowCompaction | 🟡 | 结构
定位 ：will_summarize 函数内部逻辑
问题描述 ：函数先计算 drains（判断是否有可排出的旧轮次），再做 match trigger 三分支判定。判定逻辑与 overflow_plan 中的 match attempt 重复。两处都有相同的 match 结构，如果未来增加新的压缩层级，需要同步修改两处。
参考方案 ：将 match trigger 的判定逻辑外提为 should_drain(trigger, has_old_turns) -> bool 纯函数，will_summarize 和 overflow_plan 都调用它，消除重复。
问题8 | truncate_rewrites | OverflowCompaction | 🟡 | 结构
定位 ：truncate_rewrites 函数内部逻辑
问题描述 ：函数包含三个性质不同的操作------遍历消息检查 TRUNCATE_MARKER（纯过滤）、对超长消息做字符截断（纯计算）、构建截断后的字符串（纯格式化）。虽然都是纯计算，但"检查是否已截断"和"执行截断"是两个不同的职责。当前已截断的消息直接跳过，未截断的消息执行截断------这两步的性质不同（判定 vs 操作）。
参考方案 ：外提 needs_truncation(msg, budget) -> bool 为独立的纯判定函数。truncate_rewrites 只对判定为 true 的消息执行截断操作。判定逻辑可独立测试边界条件。
历史补丁处置建议
| 补丁位置 | 原始用途 | 关联问题编号 | 处置建议 |
|---|---|---|---|
| 无 | --- | --- | 本模块无可识别历史补丁代码 |
问题归因分析
以上所有审查发现的问题，均基于当前提供的程序文本分析得出，属于审查模块自身的代码逻辑问题，与硬件平台（芯片型号、GPU类型）无直接关联。运行环境的差异可能放大这些问题的表现，但并非问题的根源。
本模块的核心归因是：压缩策略的分层设计采用了"按触发条件分支"而非"按物理操作性质分层"的组织方式 。OverflowCompaction::plan 将三种性质截然不同的操作（文本替换、消息截断、LLM 总结）通过 match attempt 分支混在同一个调用链中。这三种操作分别属于刚体机床（确定性文本处理）、流态机床（预算驱动的截断）、外部流态依赖（LLM 调用），应由独立的机床分别实现，由调度器统一编排。will_summarize 与 overflow_plan 中存在重复的 match 判定逻辑，是"按分支组织"导致的必然重复。
build_compact_stub 和 truncate_rewrites 内部存在"判定与操作混合"的轻度违规------检查是否已截断和实际执行截断两个操作未分离。summarize 将纯文本渲染、prompt 构建、LLM 调用三种操作混在一起，LLM 调用是流态外部依赖，应与纯计算逻辑隔离。
整体上，本模块的功能正确性没有问题，所有测试通过。当前的问题属于架构纯度层面------操作按功能需求组织，而非按物理性质分层。在调度密集型模块中，这种组织方式会导致重复的判定逻辑和难以独立测试的混合函数。
📌 特别说明
本报告所有结论均基于当前提供的程序文本静态分析得出，所有参考方案为通用工程实践，实际落地需结合项目具体的业务约束、上下游依赖、特殊硬件适配要求做适配调整。报告不构成对审查对象或其所属项目的整体性评价。
审查完成日期：2026年
审查工具：结构化代码静态排查