🎉 init: 小龙的工作空间

patterns/design-patterns.md

@@ -0,0 +1,154 @@
+# 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，降级到自实现）
+
+**模板**:
+```javascript
+// ... 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