16gagent/patterns/design-patterns.md

Design Patterns — 从实际任务提取

来源: reflections/ + 日常开发经验 已验证可跨任务复用的模式 新增: Anti-Patterns (≥2 occurrences → promoted from reflections)

---

Positive Patterns

Pattern 1: Phase Isolation (阶段隔离)

问题: 大任务中分析、设计、实现三阶段互相干扰，导致返工

方案:

Phase 1: Analyze  → 输出物: analysis/*.md (不可变)
Phase 2: Design   → 输出物: plan.md (不可变)
Phase 3: Implement → 输出物: src/*.js (只读 plan.md, 不改)

关键规则: 每阶段输出物一旦完成，即标记为不可变。下一阶段只能读取，不能修改。如果发现设计缺陷，完成当前 Phase 后回头修改 plan.md。

适用场景: 任何需要"理解外部系统 → 设计增强方案 → 编码实现"的任务

反模式: 在分析源码时就开始写代码 → 分析不完整 → 后期返工

---

Pattern 2: Self-Contained Module (自包含模块)

问题: 模块依赖外部库/环境，部署和测试困难

方案: 每个模块满足三个条件:

1. node module.js — CLI 独立运行
2. require('./module') — 库接口可被其他模块调用
3. 零必须依赖（外部依赖标记为 optional，降级到自实现）

模板:

// ... implementation ...

// 库接口
module.exports = { ... };

// CLI 入口
if (require.main === module) {
  main();
}

实例:

• risk-scorer.js: CLI + require() 双接口，零依赖
• toml-parser.js: 自实现，零依赖
• ctx-compress.js: CLI + require()，子模块均自包含

---

Pattern 3: Strategy Dispatch (策略分发)

问题: 同一操作有多种策略，如何选择和扩展

方案:

1. Detect  → 检测特征
2. Analyze → 分析数据
3. Recommend → 推荐策略
4. Plan    → 制定执行计划
5. Execute → 执行
6. Mark    → 标记结果 (CCR hash / metadata)

实例:

• SmartCrusher: 5 种压缩策略 (SmartSample/TopN/ClusterSample/TimeSeries/lossless)
• SessionRouter: 4 种路由策略 (Spawned/ReusedIdle/ReusedActive/Deferred)
• ctx_compress: 4 种压缩器 (json/log/search/diff)

扩展方式: 新增策略只需在策略注册表中加一个条目，不碰分发逻辑

---

Pattern 4: Graceful Degradation (降级优先)

问题: 最优路径可能不可用（环境限制、数据格式不匹配）

方案: 永远提供降级路径

最优路径 → 备选路径 → 通用路径 → passthrough

实例:

• CCR Store: Redis → SQLite → InMemory → (不存, hash 仍生成)
• SmartCrusher: lossless:csv → SmartSample → passthrough:small_array
• CodeGraph 搜索: FTS5 → LIKE → 空结果

关键: 降级时 WARN 日志 + 明确策略名 (如 passthrough:not_json)

---

Pattern 5: Three-Tier Cache (三层缓存)

问题: 内存缓存快但小，持久化慢但大，分布式慢但共享

方案:

L1: InMemory  (500 项, 1min TTL)  ← 热数据
L2: SQLite    (10K 项, 5min TTL)   ← 温数据
L3: Redis     (可选, 分布式共享)    ← 跨进程共享

查询顺序: L1 → (promote to L1) → L2 → (promote) → L3

实例: src/compression/ccr-backends.js — HybridCcrStore

---

Anti-Patterns (from failures, ≥2 occurrences)

AP-1: Operator Coercion Trap (2 occurrences)

问题: JavaScript || 把 0/""/false 当 falsy，导致排序/评分/计数逻辑出错

症状:

• 排序结果反转（healthy=0 排到最后）
• FK 索引计数字段被跳过

方案: 数值/布尔默认值用 ??（nullish coalescing），|| 仅用于字符串默认值。 Grep || in scoring/ranking code.

来源:

• 2026-06-03: Agent Evolution FK 索引 count || 0
• 2026-06-05: PR-30 Cross-Agent Certification order[status] || 6

---

AP-2: Generator Path Assumption (1 occurrence)

问题: Builder/Generator 有硬编码路径假设（如 src/app/），与实际 framework convention 不一致

方案: 生成器完成后立即跑 build smoke test，验证输出目录与 runtime 预期一致

来源:

• 2026-06-05: Domain Benchmark — frontend-builder 输出 src/app/，Next.js 期望 app/

---

AP-3: DDL Flat Mapping (1 occurrence)

问题: SQL DDL CONSTRAINT/KEY 行被解析为数据列

方案: DDL parser 必须有 column / constraint / index 三层分离

来源:

• 2026-06-05: Backend Builder — PRIMARY KEY 行泄露进 TS interface