feat: 四层架构数据分析 Agent

- Layer 1 Planner: 意图规划，将问题转为结构化分析计划 - Layer 2 Explorer: 自适应探索循环，多轮迭代动态生成 SQL - Layer 3 InsightEngine: 异常检测 + 主动洞察 - Layer 4 ContextManager: 多轮对话上下文记忆安全设计：AI 只看 Schema + 聚合结果，不接触原始数据。支持任意 OpenAI 兼容 API（OpenAI / Ollama / DeepSeek / vLLM）
2026-03-19 12:21:04 +08:00
commit 96927a789d
14 changed files with 1683 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,117 @@
+# 数据分析 Agent —— Schema-Only + 四层架构自适应分析
+
+**AI 只看表结构，不碰原始数据。通过四层架构自适应探索，生成深度分析报告。**
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      Agent (编排层)                       │
+│          接收问题 → 调度四层 → 输出报告                    │
+└──────┬──────────┬──────────┬──────────┬─────────────────┘
+       │          │          │          │
+  ┌────▼────┐ ┌──▼─────┐ ┌─▼──────┐ ┌▼─────────┐
+  │ Planner │ │Explorer│ │Insight │ │ Context  │
+  │ 意图规划  │ │探索循环  │ │异常检测  │ │ 上下文记忆 │
+  └─────────┘ └────────┘ └────────┘ └──────────┘
+```
+
+### 四层分工
+
+| 层 | 组件 | 职责 |
+|---|---|---|
+| L1 | **Planner** | 理解用户意图，生成结构化分析计划（类型、维度、指标） |
+| L2 | **Explorer** | 基于计划多轮迭代探索，每轮根据上一轮结果决定下一步 |
+| L3 | **InsightEngine** | 从探索结果中检测异常、趋势、关联，输出主动洞察 |
+| L4 | **ContextManager** | 管理多轮对话历史，后续问题可引用之前的分析 |
+
+### 安全隔离
+
+```
+用户提问 → Agent 看 Schema 生成 SQL → 沙箱执行 → 聚合结果 → Agent 生成报告
+                                      ↑
+                                  原始数据永远留在这里
+```
+
+- **Schema 提取器**：只提取表结构、列类型、行数、枚举值，不碰数据
+- **沙箱执行器**：禁止 SELECT * / DDL / DML，必须聚合函数，小样本抑制（n<5）
+- **AI 的视角**：只有 Schema + 聚合统计结果，从未接触任何一行原始数据
+
+## 快速开始
+
+```bash
+# 1. 安装依赖
+pip install openai
+
+# 2. 配置 LLM（兼容 OpenAI API 格式）
+
+# OpenAI
+export LLM_API_KEY=sk-xxx
+export LLM_BASE_URL=https://api.openai.com/v1
+export LLM_MODEL=gpt-4o
+
+# Ollama（本地部署，隐私优先）
+export LLM_API_KEY=ollama
+export LLM_BASE_URL=http://localhost:11434/v1
+export LLM_MODEL=qwen2.5-coder:7b
+
+# DeepSeek
+export LLM_API_KEY=sk-xxx
+export LLM_BASE_URL=https://api.deepseek.com
+export LLM_MODEL=deepseek-chat
+
+# 3. 运行演示（自动创建 5 万条示例数据 + 3 个分析任务）
+python3 demo.py
+
+# 4. 交互式分析
+python3 cli.py
+
+# 5. 分析你自己的数据库
+python3 cli.py /path/to/your.db
+```
+
+## 文件结构
+
+```
+├── config.py              # 配置（LLM、安全规则、探索轮数）
+├── schema_extractor.py    # Schema 提取器（只提取结构）
+├── sandbox_executor.py    # 沙箱执行器（SQL 验证 + 结果脱敏）
+├── planner.py             # [L1] 意图规划器
+├── explorer.py            # [L2] 自适应探索器
+├── insights.py            # [L3] 洞察引擎（异常检测）
+├── context.py             # [L4] 上下文管理器
+├── reporter.py            # 报告生成器
+├── agent.py               # Agent 编排层
+├── demo.py                # 一键演示
+├── cli.py                 # 交互式 CLI
+├── requirements.txt       # 依赖
+└── README.md
+```
+
+## 对比预制脚本
+
+| | 预制脚本 / 模板 | 本方案（四层架构） |
+|---|---|---|
+| SQL 生成 | 模板拼接 | LLM 动态生成 |
+| 查询数量 | 固定 | 1-6 轮，AI 自适应 |
+| 后续追问 | 无 | AI 看到结果后判断是否深挖 |
+| 异常发现 | 无 | 主动检测 + 主动输出 |
+| 多轮对话 | 无 | 上下文记忆，可引用历史分析 |
+| 适用场景 | 已知分析模式 | 探索性分析、开放性问题 |
+
+## CLI 命令
+
+```
+📊 > 帮我分析各地区的销售表现      # 分析问题
+📊 > rounds=3 最近的趋势怎么样     # 限制探索轮数
+📊 > schema                      # 查看数据库 Schema
+📊 > history                     # 查看分析历史
+📊 > audit                       # 查看 SQL 审计日志
+📊 > clear                       # 清空历史
+📊 > help                        # 帮助
+📊 > quit                        # 退出
+```
+
+## License
+
+MIT