7节点 DataAgent — 自然语言驱动 SQL 生成、Python 深度分析、结构化报告，全链路结果审计。
面向企业内部 BI 场景的自然语言数据分析 Agent。用中文提问，系统自动完成意图识别、知识检索、SQL 生成、执行、Python 深度分析、结构化报告生成、结果审计。全过程 SSE 流式推送到前端。
核心能力：
| 能力 | 说明 |
|---|---|
| 简单查询 | 自然语言 → SQL → 表格结果（轻量路径，15-30s） |
| 复杂分析 | 多步计划 → SQL + Python → Markdown 报告 + ECharts 图表（40-80s） |
| 结果审计 | 报告 vs SQL 结果自动对比，防止数据编造 |
| 人工审核 | 执行计划审批（通过/修改/拒绝），支持反馈修改 |
| 知识召回 | 智能 wiki 检索 + 表匹配 + 枚举提取 |
| SQL 安全 | 语法校验 + 枚举值验证 + 时间边界检查 + DuckDB 方言修正 |
| MCP 集成 | 支持 Claude Code 直接调用 query / analyze 两个工具 |
简单查询: Intent → WikiRecall → Guard → DirectSQL → ResultsReview → END
复杂分析: Intent → WikiRecall → Guard → Planner → [HumanReview]
→ SQL/Python循环 → ReportGenerator → ResultsReview → END
详见 docs/architecture.md 和 docs/graph-diagram.md。
# 1. 安装依赖
pip install -e ".[dev]"
# 2. 准备数据
python scripts/setup_data.py
# 3. 配置密钥
cp .env.example .env # 编辑 .env 填入 DEEPSEEK_API_KEY
# 4. 启动后端 (端口 8014)
python scripts/start_backend.py
# 5. 启动前端
cd web && npm install && npm run dev
# 6. 打开 http://localhost:5173# Claude Code 中直接使用
> 用 query 查一下 2017 年有多少订单
> 用 analyze 分析各州销售额和运费排名.mcp.json 在项目根目录，自动加载。
| 表 | 行数 | 说明 |
|---|---|---|
| orders | 99,441 | 订单（时间/状态/交付） |
| order_items | 112,650 | 订单明细（价格/运费/商品/卖家） |
| order_payments | 103,886 | 支付（类型/分期/金额） |
| order_reviews | 99,224 | 评论（评分/内容） |
| customers | 99,441 | 客户（城市/州） |
| products | 32,951 | 商品（品类/重量/尺寸） |
| sellers | 3,095 | 卖家（城市/州） |
| geolocation | 1,000,163 | 地理坐标 |
| category_translation | 71 | 品类翻译 |
| 层 | 技术 |
|---|---|
| 前端 | React + TypeScript + Vite + ECharts |
| 后端 | FastAPI + SSE + WebSocket |
| Agent | LangGraph (7 节点 + 辅助) |
| LLM | DeepSeek / Qwen / GLM |
| 数据仓库 | DuckDB (read-only) |
| 知识检索 | Markdown wiki + 正则匹配 |
| Prompt | 6 个 Jinja2 模板 |
ask-data-agent/
├── agent/
│ ├── graph.py # LangGraph 状态机
│ ├── state.py # AgentState
│ ├── wiki.py # 知识库检索
│ ├── schema_ddl.py # DuckDB DDL 生成
│ ├── stream_helper.py # SSE 流式工具
│ └── nodes/
│ ├── preprocess.py # Intent / WikiRecall / Guard
│ ├── planner.py # 执行计划生成
│ ├── plan_executor.py # 步骤分发
│ ├── direct_sql.py # 简单查询路径
│ ├── sql_generate.py # SQL 生成 + 执行
│ ├── python_nodes.py # Python 生成/执行/分析
│ ├── report_generator.py # 报告生成
│ └── review.py # 结果审计
├── api/
│ ├── main.py # FastAPI 入口
│ ├── dependencies.py # 依赖注入（单例）
│ ├── sse.py # SSE 发射器
│ ├── mcp_server.py # MCP Server
│ └── routes/
│ ├── chat.py # WebSocket 聊天
│ ├── stream.py # GET /api/stream/search (SSE)
│ └── report.py # 报告下载
├── prompts/
│ └── templates/ # 6 个 Prompt 模板
├── connectors/
│ ├── llm/ # DeepSeek / Qwen / GLM Provider
│ └── dw/ # DuckDB Connector
├── wiki/ # 知识库源文件与编译产物
├── web/ # React 前端
├── scripts/ # 数据准备、后端启动
├── docs/ # 架构文档
├── config/ # 应用配置
└── data/ # DuckDB 数据文件 + 日志
MIT