# Reflection: Agent Evolution Mode — 四阶段全流程

> Date: 2026-06-03 | Severity: P0/P1 (multiple failures) | Recurrence: see individual patterns

## Context
深度学习 ECC/Headroom/CodeGraph → 提取能力 → 增强 OpenClaw。4 Phase，16 模块，7,000 行，5h（预估 42.5h）。

## Pattern Classes Extracted

### PC-1: SQLite FK Constraint (P0) — Pattern Class: SQL FK/DELETE semantic
- **Root Cause**: INSERT OR REPLACE causes rowid change → FK breaks
- **Fix**: ON CONFLICT DO UPDATE preserves original rowid
- **Future Trigger**: any SQL schema modification, batch inserts with FK

### PC-2: Heuristic False Positive (P1) — Pattern Class: single-signal detection
- **Root Cause**: `[2026-...` prefix triggered JSON detection without valid parse
- **Fix**: require 2+ signals (prefix + valid JSON.parse)
- **Future Trigger**: any heuristic/content-type detection logic

### PC-3: Nested Structure Parsing (P1) — Pattern Class: protocol-level vs structural parsing
- **Root Cause**: parser relied on structured JSON nesting, failed on content arrays
- **Fix**: match "type":"tool_result" byte patterns instead of tree traversal
- **Future Trigger**: any nested data structure parsing

### PC-4: Overly Aggressive Sampling (P2) — Pattern Class: lossy strategy without safety net
- **Root Cause**: TimeSeries strategy kept only anchor points (500→5), dropped errors
- **Fix**: include error/outlier detection alongside anchor selection
- **Future Trigger**: any sampling/compression strategy design

## 成功经验

### 1. "分析→设计→实现"三阶段分离
- 用 sub-agent 并行做源码分析（3 个 agent 同时跑，2-3 分钟完成 2,670 行分析）
- 分析完成后一次性设计 Evolution Plan，不做中间修改
- 实现阶段按优先级分 Phase，每个 Phase 内部模块间无依赖 → 可快速迭代
- **教训**: 不要在分析阶段就开始设计，不要在设计中就开始编码

### 2. 先建 MVP，再扩展
- P0 三件套 (安全+压缩) 1.5h 上线，立即产生价值
- 验证了"Prompt Defense 不改代码"、"SmartCrusher 压缩率 60-95%"
- 后续 Phase 基于已验证的架构扩展
- **教训**: 最小可验证单元 > 大而全的设计

### 3. 自给自足的依赖策略
- `@iarna/toml` 与 Node v26 不兼容 → 自写 230 行 TOML 解析器
- 无 tree-sitter → 自写 8 语言正则解析器
- 无 Redis → SQLite WAL 共享后端
- **教训**: 每个外部依赖都是风险点，自写核心无依赖模块反而更稳定

### 4. 测试驱动: 每个模块写完立即测
- 风险评分器: 7 个边界用例全覆盖
- SmartCrusher: 4 种策略各测一个场景
- Byte Surgery: 验证 SHA-256 前缀不变
- Budget: 验证 3K→9K→11K 的 ALLOW/WARN/BLOCK 阈值
- **教训**: "写完再测" = 返工，"写完即测" = 一次通过

### 5. 演化思维: 模块可替换
- CCR Store: 接口统一，后端 InMemory/SQLite/Redis/Hybrid 可插拔
- CodeGraph: 正则提取器 → 可升级 tree-sitter
- 配置: TOML 解析器独立 → 可换完整 TOML 库
- **教训**: 每个模块留升级路径，不锁死实现

## 失败经验

### 1. FK 约束错误: 32 个文件索引失败
- 原因: `INSERT OR REPLACE` 导致 file_id 变化，节点 FK 断裂
- 修复: `ON CONFLICT DO UPDATE` 保留原有 rowid
- **教训**: SQLite 的 REPLACE = DELETE + INSERT，不是 UPDATE。FK 约束下用 ON CONFLICT

### 2. 内容检测误判: 日志被识别为 JSON
- 原因: `[2026-06-03...` 以 `[` 开头触发了 JSON 检测
- 修复: 要求 `[` 开头 + 有效的 JSON.parse
- **教训**: 启发式检测需要多重信号确认，单信号不可靠

### 3. Byte Surgery block 检测失败 (第一次)
- 原因: 解析器未处理嵌套 content 数组中的 tool_result
- 修复: 直接从字节流中匹配 `"type":"tool_result"` 的 JSON 对象边界
- **教训**: 协议级解析 > 结构化解析（后者依赖特定 JSON 结构）

### 4. TimeSeries 策略过于激进 (500→5)
- 原因: 仅靠锚点选择，未包含错误检测
- 修复: 在 planTimeSeries 中也加入 error/outlier 检测
- **教训**: 每个策略的 fallback 必须先保证关键信息不丢失

## 设计的模式

### Pattern 1: "阶段隔离"模式
分析阶段不写代码 → 设计阶段不改分析 → 实现阶段不改设计
每阶段输出物不可变，下一阶段只读

### Pattern 2: "自包含模块"模式
每个模块：(1) 可独立运行 (2) 零外部依赖或可选依赖 (3) CLI + 库双接口
例子: risk-scorer.js 可 `node risk-scorer.js '...'` 也可 `require('./risk-scorer')`

### Pattern 3: "策略分发"模式
检测 → 分析 → 推荐策略 → Plan → Execute → Mark
SmartCrusher 5 策略、Router 4 策略、压缩 4 类型，都走同一模式

### Pattern 4: "降级优先"模式
每个操作先尝试最优路径 → 失败则降级 → 保证不阻塞
CCR Store: Redis → SQLite → InMemory
压缩: lossless → SmartSample → passthrough
搜索: FTS5 → LIKE → 空结果（不报错）

## 下次改进

1. **预检清单**: 每个 Phase 开始前列出"容易踩的坑"（如 FK、编码、检测误判）
2. **性能基准**: 记录每个模块在大数据集下的性能（10万行 JSON、1万文件索引）
3. **自动回归**: 所有模块跑一次全量测试脚本
