SQLite 持久连接 — sandbox 不再每次查询开关连接，改为 __init__ 时建连、close() 时释放

Explorer 的 system prompt 明确告知 sandbox 规则 — "每条 SQL 必须包含聚合函数或 LIMIT"，减少 LLM 生成违规 SQL 浪费轮次
LLM 客户端单例 — 所有组件共享一个 openai.OpenAI 实例，不再各建各的
sanitize 顺序修复 — 小样本抑制放在 float round 之前，避免被 round 干扰
quick_detect 从 O(n²) 改为 O(n) — 按列聚合一次，加去重，不再对每行重复算整列统计
历史上下文实际生效 — get_context_for 的结果现在会注入到 Explorer 的初始 prompt 里，多轮分析时 LLM 能看到之前的发现

README.md

@@ -8,20 +8,21 @@
 ┌─────────────────────────────────────────────────────────┐
 │                      Agent (编排层)                       │
 │          接收问题 → 调度四层 → 输出报告                    │
-└──────┬──────────┬──────────┬──────────┬─────────────────┘
-       │          │          │          │
-  ┌────▼────┐ ┌──▼─────┐ ┌─▼──────┐ ┌▼─────────┐
-  │ Planner │ │Explorer│ │Insight │ │ Context  │
-  │ 意图规划  │ │探索循环  │ │异常检测  │ │ 上下文记忆 │
-  └─────────┘ └────────┘ └────────┘ └──────────┘
+└──┬──────────┬──────────┬──────────┬──────────┬──────────┘
+   │          │          │          │          │
+┌──▼───┐ ┌───▼────┐ ┌───▼───┐ ┌───▼────┐ ┌───▼─────┐
+│Planner│ │Playbook│ │Explorer│ │Insight │ │ Context │
+│意图规划│ │预设匹配 │ │探索循环 │ │异常检测 │ │上下文记忆│
+└──────┘ └────────┘ └───────┘ └────────┘ └─────────┘
 ```
 
-### 四层分工
+### 分层分工
 
 | 层 | 组件 | 职责 |
 |---|---|---|
 | L1 | **Planner** | 理解用户意图，生成结构化分析计划（类型、维度、指标） |
-| L2 | **Explorer** | 基于计划多轮迭代探索，每轮根据上一轮结果决定下一步 |
+| L1.5 | **Playbook** | 匹配预设分析剧本，提供确定性查询保底 |
+| L2 | **Explorer** | 先执行预设查询（如有），再基于结果多轮迭代发散探索 |
 | L3 | **InsightEngine** | 从探索结果中检测异常、趋势、关联，输出主动洞察 |
 | L4 | **ContextManager** | 管理多轮对话历史，后续问题可引用之前的分析 |
 
@@ -77,34 +78,78 @@ python3 cli.py /path/to/your.db
 ├── schema_extractor.py    # Schema 提取器（只提取结构）
 ├── sandbox_executor.py    # 沙箱执行器（SQL 验证 + 结果脱敏）
 ├── planner.py             # [L1] 意图规划器
-├── explorer.py            # [L2] 自适应探索器
+├── playbook.py            # [L1.5] 预设分析剧本匹配
+├── explorer.py            # [L2] 自适应探索器（预设 + 发散）
 ├── insights.py            # [L3] 洞察引擎（异常检测）
 ├── context.py             # [L4] 上下文管理器
 ├── reporter.py            # 报告生成器
 ├── agent.py               # Agent 编排层
 ├── demo.py                # 一键演示
 ├── cli.py                 # 交互式 CLI
+├── playbooks/             # 预设分析剧本
+│   ├── regional_sales.json    # 地区销售分析
+│   ├── category_analysis.json # 商品类别分析
+│   └── order_health.json      # 订单健康度分析
 ├── requirements.txt       # 依赖
 └── README.md
 ```
 
-## 对比预制脚本
+## 预设分析剧本（Playbook）
 
-| | 预制脚本 / 模板 | 本方案（四层架构） |
-|---|---|---|
-| SQL 生成 | 模板拼接 | LLM 动态生成 |
-| 查询数量 | 固定 | 1-6 轮，AI 自适应 |
-| 后续追问 | 无 | AI 看到结果后判断是否深挖 |
-| 异常发现 | 无 | 主动检测 + 主动输出 |
-| 多轮对话 | 无 | 上下文记忆，可引用历史分析 |
-| 适用场景 | 已知分析模式 | 探索性分析、开放性问题 |
+Playbook 是"确定性保底 + AI 自由发散"的结合：
+
+- 为常见分析场景预定义一组确定性 SQL 查询
+- Planner 生成计划后，LLM 自动判断是否匹配某个 Playbook
+- 匹配到：先执行预设 SQL（结果可控），再让 Explorer 基于结果自由发散
+- 没匹配到：走纯自适应路径（和之前一样）
+
+### 创建 Playbook
+
+在 `playbooks/` 目录下创建 `.json` 文件：
+
+```json
+{
+  "name": "地区销售分析",
+  "description": "按地区维度分析销售额、订单量、客单价",
+  "tags": ["地区", "区域", "销售"],
+  "preset_queries": [
+    {
+      "purpose": "各地区销售总额",
+      "sql": "SELECT {{region_column}} AS region, ROUND(SUM({{amount_column}}), 2) AS total FROM {{table}} GROUP BY {{region_column}} ORDER BY total DESC"
+    }
+  ],
+  "exploration_hints": "请关注地区间的增长差异和客单价异常",
+  "placeholders": {
+    "table": "orders",
+    "region_column": "region",
+    "amount_column": "amount"
+  }
+}
+```
+
+- `preset_queries`: 确定性 SQL，用 `{{占位符}}` 标记可变部分
+- `placeholders`: 默认值，LLM 匹配时会根据实际 Schema 自动替换
+- `exploration_hints`: 给 Explorer 的提示，引导发散方向
+- `tags`: 帮助 LLM 判断是否匹配
+
+## 对比
+
+| | 预制脚本 / 模板 | 纯自适应 | 本方案（Playbook + 自适应） |
+|---|---|---|---|
+| SQL 生成 | 模板拼接 | LLM 动态生成 | 预设保底 + LLM 发散 |
+| 结果可控性 | 高 | 低 | 核心数据确定，发散部分灵活 |
+| 查询数量 | 固定 | 1-6 轮 | 预设 N 条 + 自适应 M 轮 |
+| 后续追问 | 无 | AI 自主判断 | 基于预设结果深挖 |
+| 异常发现 | 无 | 主动检测 | 预设结果 + 主动检测 |
+| 适用场景 | 已知分析模式 | 开放性问题 | 两者兼顾 |
 
 ## CLI 命令
 
 ```
-📊 > 帮我分析各地区的销售表现      # 分析问题
+📊 > 帮我分析各地区的销售表现      # 分析问题（自动匹配 Playbook）
 📊 > rounds=3 最近的趋势怎么样     # 限制探索轮数
 📊 > schema                      # 查看数据库 Schema
+📊 > playbooks                   # 查看已加载的预设剧本
 📊 > history                     # 查看分析历史
 📊 > audit                       # 查看 SQL 审计日志
 📊 > clear                       # 清空历史