data-analysis-agent

mcp
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • eval() — Dynamic code execution via eval() in .github/workflows/ci.yml
  • network request — Outbound network request in frontend/src/components/AuthImage.tsx
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

LLM 数据分析工作台:上传数据集自动完成清洗、统计分析、可视化与报告;受控工具集 + 只读 SQL(SQLite / PostgreSQL)· MCP 数据面 · Plotly + ECharts 双引擎 · FastAPI + React 全流程界面,本地 / Docker / 云端可部署

README.md

Data Analysis Agent

CI Python 3.11–3.13 React 19 FastAPI LangGraph Docker Tests passing MIT License

一个基于 LLM 的数据分析工作台:上传数据集,自动完成数据检查、清洗、统计分析、可视化与报告生成。

后端采用 LangChain + LangGraph 的 Plan-and-Execute + ReAct 混合架构,前端为独立 React 应用,本地通过 HTTP/SSE 通信。可一键本地运行,也可部署到 LangSmith / Render / Docker。

数据分析工作台主界面(浅色主题)
全流程工作台:数据概览 → 分析任务 → 实时执行进度 → 结构化报告

系统架构

flowchart LR
    U[上传数据集] --> W[工作区 DataWorkspace<br/>数据档案 / 清洗 / 产物]
    W --> P[Plan-and-Execute 规划器<br/>生成 2–6 步结构化计划]
    P --> R[ReAct 执行器]
    R --> T[受控工具集]
    T --> T1[数据检查 / 格式修复]
    T --> T2[安全清洗 / 筛选视图]
    T --> T3[统计分析 · 假设检验]
    T --> T4[Plotly / ECharts 图表]
    T --> T5[导出 / Python 沙箱]
    R -->|重规划器<br/>裁剪与补充步骤| P
    R --> F[汇总 · 生成报告]
    F --> G[结构化分析报告]
    F --> C[交互式图表产物]
    G --> Q[多轮追问对话]
    C --> Q

界面预览

起始页 · 拖拽上传与示例数据 分析工作区 · 数据概览与任务
起始页 数据分析工作台主界面(浅色主题)
深色主题 · 全流程工作台 产物中心 · 图表缩略图与下载
深色主题主界面 产物中心
图表预览 · 密度视图与细节图层 数据预览 · 类型识别与列对齐
图表预览模态 数据预览表格

以上截图可用 python scripts/capture_docs_screenshots.py 一键重新生成(本地起服务后逐页抓图)。

功能特性

  • 计划-执行式分析流程:每次分析先生成 2–6 个结构化步骤,每个步骤由 ReAct 执行器调用受控工具完成;重规划器根据真实工具结果删除无用步骤、补充后续分析,证据充分时提前结束,达到步骤上限时强制汇总,避免无限循环。
  • 受控数据工具集(11 个内置工具):数据检查、格式修复、安全清洗、非破坏性筛选视图、跨源合并、数据库查询、登记指标计算、统计分析、图表生成、数据导出、受限 Python 沙箱。
  • MCP 数据面服务:把会话发现、数据集载入、结构探查与只读 SQL 以 MCP 标准开放给其他 Agent,护栏同源、传输 stdio(详见"快速开始")。
    • 跨源合并带连接键校验与行数膨胀护栏:键不存在、键类型不一致导致一行都匹配不上、键不唯一导致行数被放大数倍,三种情况一律拒绝执行并说明原因;结果同时给出未匹配键数量与一对多放大警告,避免把扇出后的行数当作原始记录数。合并结果会成为新的活动数据集,行数基线同步重置。
    • 数据库查询面向两类数据源:上传的 SQLite 文件,以及环境变量 DATA_AGENT_DATABASE_URL 配置的 PostgreSQL(驱动按需安装:pip install ".[postgres]")。只读(SQLite 以 mode=ro 打开、Postgres 在服务端设置 default_transaction_read_only,写入在驱动/服务端即被拒绝),只接受 SELECT / WITH 语句;单条查询默认 30 秒墙钟预算(DATA_AGENT_SQL_TIMEOUT_SECONDS,1–120;SQLite 用 progress handler 中断、Postgres 用服务端 statement_timeout),结果上限 5000 行、500 列。空 sql 调用可一次拿到可用数据源与全库表结构;传 adopt=true 可把查询结果接管为活动数据集,后续统计与图表直接在其上工作。
    • 清洗带安全护栏:缺失值删除比例超过 50% 会拒绝执行,主数据行数始终不低于原始行数的 20%。
    • 统计方法覆盖描述统计、相关分析(含 Pearson p 值)、分组聚合、独立/配对 t 检验、ANOVA、卡方检验、线性回归(R² / RMSE / MAE)。
  • 指标口径登记(可选):在会话目录放置 metrics.json,或用 DATA_AGENT_METRICS_PATH 指定一份全局定义,登记指标的标准名称、别名、口径说明、算式与已验证问法(examples:业务确认过的问题样例,随口径一起注入,让模型把口语问题对齐到标准指标,对标 Power BI verified answers 的人工策展思路);规划阶段会把相关定义注入提示词,避免同一指标在不同会话被各自定义为不同口径。未提供定义文件时该特性完全不生效,行为与原来一致。
  • 双图表引擎(Plotly + ECharts):共享同一套数据准备逻辑,支持折线、柱状、面积图、散点(含 3D)、直方图、箱线图、小提琴图、饼图、热力图、相关热力图、散点矩阵、旭日图、矩形树图;自动选图、散点图自动叠加 OLS 趋势线(标注 r 值)与双轴均值象限参考线、极端值自动检测与主体尺度/全量视图切换、暗色主题联动、PNG 导出、数据驱动的白话解读。
  • 大数据图表的可读性:几十万行时"每点一个标记"的散点会因 alpha 饱和糊成一团(实测 30 万点全是同色噪点)。散点 ≥ 2 万行自动切换为密度视图:服务端聚合成网格(单格约 7px)、用分档颜色表达每格记录数(档位图例直接给出"1 / 2–4 / 5–9 …"的记录数区间)、零记录格完全透明,并在有分组时按分组拆成共享色标的分面面板(类别用分面表达、颜色只表达密度);无分组时补顶部/右侧边缘直方图(jointplot 布局)、趋势线、均值参考线与最外围原始点。判定"是否真有聚集"会先扣掉均匀随机点云的统计涨落,没有聚集就直说。放大后想看具体记录:图上带一层默认隐藏的分层抽样原始点,Plotly 用右上角按钮、ECharts 用图例开关一键叠加(名字与解读都写明是抽样、条数,完整数据在同名 JSON)。直方图 ≥ 5 万行改为服务端分箱(纵轴仍是真实记录数)、箱线图改为服务端五数概括、小提琴图与 3D 散点分层抽样(3D 会把"已抽样 N/M 点"写在副标题上)——同一批图表 HTML 体积从 312MB 降到 20200KB,密度视图是精确聚合而非抽样,完整数据始终保留在同名 JSON 产物里。折线/面积按 LTTB(Largest-Triangle-Three-Buckets)保峰降采样(数值轴与类目轴都覆盖),短促尖峰不会被等距抽样抹掉。
  • 可访问性:全站文字对比度按 WCAG AA 校准并用浏览器计算样式实测(浅/暗两主题 × 起始页/工作台/产物/历史/命令面板/预览模态),三级文字阶梯与"实心强调色"分令牌管理(白字压底专用 --accent-solid,避免暗色下提亮的品牌色当背景时只有 3.5:1);滑块、按钮、卡片均带 hover/active 反馈与键盘焦点环。
  • 多格式数据接入:CSV / TSV / Excel / JSON / JSONL / Parquet、SQLite(.db / .sqlite / .sqlite3,上传后默认载入行数最多的表,其余表由数据库查询工具访问),以及 PDF 表格提取、TXT、Word 表格;自动探测编码(UTF-8 / GB18030)与分隔符,大文件分块流式读取,数值列自动降级数据类型以节省内存。
  • 全流程 Web 工作台:文件上传(含进度与取消)、数据概览指标、分析任务与预设模板、计划审阅/批准、实时步骤与工具调用进度(SSE + 15 秒心跳)、随时取消分析、报告生成后的多轮追问、产物中心(预览/对比/PNG/批量下载)、历史会话(重命名/删除/导出 ZIP/导入)、命令面板与快捷键、深浅主题、移动端适配。
  • 断点续跑与自动恢复:分析中断后可从已完成的步骤继续,无需重跑;前端支持 SSE 断线自动恢复与一键重试。
  • 安全与访问控制:可选访问令牌(APP_ACCESS_TOKEN)、滑动窗口速率限制、CORS / GZip / 安全响应头;API Key 通过操作系统凭据库(keyring)保存,不落明文文件。
  • 会话持久化:本地或 S3 兼容对象存储(如 Cloudflare R2)双后端,会话按 session id 自动归档/恢复,带路径穿越防护。
  • 可观测与部署:LangSmith 全链路 Trace(规划、每次工具调用、重规划、汇总);LangGraph Agent Server 部署;Dockerfile(非 root 用户 + 健康检查);Render Blueprint 一键部署;GitHub Actions 自动 CI。
  • 可复核的分析溯源与逐结论核验:每次分析在会话目录生成哈希链,覆盖任务元信息、数据集、逐条工具调用、产物文件与报告正文;finalize/replay 另将正文数字逐项判为 verified / conflict / unsupported,在报告追加结论核验表并生成可下载的 report-verification.json,按 trace 序号和 JSON Pointer 定位证据。见 docs/analysis-provenance.md。
  • 发布前质量闸门(可选):data-agent-eval compare 对同一套用例的基线与候选结果做配对 McNemar 精确检验,同时检查成本与延迟回归,给出接受 / 拒绝 / 证据不足三态裁决,并写入可校验的哈希链 ledger。见 docs/agent-eval.md。

技术栈

  • 后端:Python 3.11–3.13、FastAPI、Uvicorn、LangChain、LangGraph、LangSmith
  • 模型接入:DeepSeek(默认,支持 thinking mode)/ OpenAI 及任意 OpenAI 兼容服务
  • 数据分析:pandas、NumPy、SciPy、scikit-learn、Plotly、Kaleido、openpyxl、PyArrow、pdfplumber、python-docx
  • 存储:本地文件系统 / boto3(S3 / R2)
  • 前端:TypeScript、React 19、Vite、Zustand、lucide-react、motion、react-markdown(Vitest)
  • CLI:Typer + Rich

快速开始

环境要求

  • Python 3.11–3.13
  • Node.js 22 或更高版本
  • 一个 LLM API Key(默认 DeepSeek,也兼容 OpenAI)

一键启动(Windows)

双击 run.bat。首次运行会自动创建虚拟环境、安装后端依赖并 npm install,随后分别启动:

手动启动

# 后端
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env   # 编辑填入 DEEPSEEK_API_KEY
.\.venv\Scripts\python.exe -m uvicorn data_agent.api:app --host 127.0.0.1 --port 8000

# 前端(另开终端)
cd frontend
npm install
npm run dev

命令行分析

pip install -e ".[dev]"
export DEEPSEEK_API_KEY=<your-key>        # Windows PowerShell: $env:DEEPSEEK_API_KEY="<your-key>"
data-agent analyze examples/sample_sales.csv --task "分析各区域销售趋势"

输出为 Markdown 格式分析报告,产物路径一并打印。

MCP 数据面服务(供其他 Agent 调用)

把受控的数据访问能力以 MCP(Model Context Protocol)标准开放给 Claude Desktop、
WorkBuddy 等任意 MCP 客户端:其他 Agent 拿到的是"安全的数据访问",而不是一个
无限制的代码沙箱——这是本项目差异化的直接延伸。

pip install ".[mcp]"        # 或开发环境 pip install -e ".[dev]"
data-agent-mcp              # stdio 传输,供本地 MCP 客户端拉起

客户端配置示例(Claude Desktop / 通用 MCP 客户端):

{
  "mcpServers": {
    "data-analysis-agent": {
      "command": "data-agent-mcp",
      "env": { "DATA_AGENT_RUNS_DIR": "./runs" }
    }
  }
}

开放 4 个工具:list_sessions(发现会话)、open_dataset(载入本地数据文件并建会话)、
inspect_data(结构与预览)、sql_query(只读 SQL,支持会话内 SQLite 与
DATA_AGENT_DATABASE_URL 配置的 PostgreSQL)。护栏与工作区内工具同源:只接受
SELECT/WITH,写入在驱动或服务端被拒绝,结果上限 5000 行。

边界说明:完整分析流程(LLM 规划-执行-报告)是分钟级长任务,仍走 HTTP API,
不在 MCP 数据面内。传输为 stdio、由本地受信客户端拉起,不要把该服务挂到
网络上对外提供;远程访问请使用带令牌与限流的 HTTP API。

配置

复制 .env.example 为 .env 并填写(所有密钥均为占位符):

MODEL_PROVIDER=deepseek
DEEPSEEK_API_KEY=<your-deepseek-api-key>
DEEPSEEK_MODEL=deepseek-flash
DEEPSEEK_THINKING=true
DEEPSEEK_REASONING_EFFORT=high

# 或使用 OpenAI 兼容服务
OPENAI_API_KEY=<your-api-key>
OPENAI_MODEL=gpt-4.1-mini

# 前端构建产物目录(源码树内运行可省略;Docker / Render / wheel 安装必须显式指定)
DATA_AGENT_STATIC_DIR=frontend/dist

# 线上访问保护(绑定 0.0.0.0 等非环回地址时必填,否则拒绝启动)
APP_ACCESS_TOKEN=<your-access-token>

# 可选:指标口径登记文件(登记后规划阶段会注入口径定义,防止跨会话口径漂移)
DATA_AGENT_METRICS_PATH=<path-to-metrics.json>

# 可选:PostgreSQL 数据源(配置后 query_database 可只读查询该库;驱动 pip install ".[postgres]")
DATA_AGENT_DATABASE_URL=postgresql://user:password@host:5432/dbname

# 可选:Cloudflare R2 / S3 兼容持久化
DATA_AGENT_STORAGE_BACKEND=s3
DATA_AGENT_STORAGE_BUCKET=<bucket-name>
DATA_AGENT_STORAGE_ENDPOINT_URL=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
AWS_ACCESS_KEY_ID=<your-access-key-id>
AWS_SECRET_ACCESS_KEY=<your-secret-access-key>

完整变量清单见 .env.example。

用于实践时请先知道

  • 本进程是一个信任域。 单一 APP_ACCESS_TOKEN 能列出并打开 runs/ 下全部会话。团队共用一台机器时必须设令牌,也不要把不同客户的数据放进同一个服务。
  • 默认先审阅计划。 ⌘/Ctrl+Enter 与主按钮「生成计划」只出步骤;确认后再批准执行。「跳过审阅」才会直接跑。
  • 指标要登记才会按同一口径算。 工作台「业务口径」或 DATA_AGENT_METRICS_PATH 写入 metrics.json,表达式必须使用真实列名(如 sales - returns)。分析时会调用 compute_registered_metrics,报告里的「核验附录」默认收起。
  • 经营简报可以独立复算。 工作台「简报核验」读取原始订单 CSV,核对销售额、销量和订单数,提供核验版简报及证据下载。见 参赛演示说明。
  • SQLite 大表不会整表进内存。 超过 10 万行只载入前 10 万行;全量请用 query_database 聚合后再 adopt。CSV 也可用该工具,表名为 data。
  • 换新数据重跑: 报告上的「按配方重跑」读取 analysis_recipe.json,按上次工具参数执行,不重新规划。
  • 给业务的文件: 导出菜单可下载 Word / PPT;「分析溯源 (.json)」给出报告对应的数据集、工具调用与产物哈希链及复核结果。
  • 样例行在发给模型前会脱敏手机号、邮箱、身份证号;不要依赖它代替完整的数据治理。

项目结构

src/data_agent/
  api.py             FastAPI 应用装配与前端静态资源托管
  agent.py           DataAnalysisAgent:Plan-and-Execute + ReAct
  cli.py             Typer 命令行入口
  config.py          环境变量驱动的运行时配置
  nodes/             LangGraph 节点(validate/plan/execute/replan/finalize)
  tools/             ReAct 工具集(检查/清洗/转换/合并/数据库/统计/可视化/导出/沙箱)
  metrics.py         指标口径登记(可选,规划阶段注入)
  provenance.py      分析溯源哈希链(数据集 / 工具 / 产物 / 报告)
  verification.py    逐结论确定性核验与 JSON 报告(verified/conflict/unsupported)
  evalkit/           发布前评测闸门(McNemar / Wilson / ledger / CLI)
  sqlite_source.py   只读 SQLite 数据源(表发现 / 结构描述 / 受限查询)
  postgres_source.py 只读 PostgreSQL 数据源(服务端只读 + statement_timeout)
  sql_guard.py       驱动无关的只读 SQL 护栏(两个数据源共用)
  mcp_server.py      MCP 数据面服务(stdio,供其他 Agent 调用)
  echarts_engine.py  ECharts 图表引擎(与 Plotly 引擎并列)
  deployment.py      LangSmith Agent Server 图入口
  storage.py         本地 / S3 兼容对象存储后端
  middleware.py      CORS / GZip / 访问令牌 / 速率限制
  routers/           会话 / 分析 / 产物 / 设置路由
frontend/            React + Vite 前端(构建产物 frontend/dist 由 `npm run build` 生成,不入 git)
examples/            示例数据
tests/               pytest 测试

部署

  • Docker:根目录 Dockerfile 两阶段构建(Node 构建前端 + Python 运行时),以非 root 用户运行并带健康检查。容器监听 0.0.0.0,必须设置 APP_ACCESS_TOKEN,否则进程启动即报错退出。
  • 访问令牌:监听非环回地址(如 Docker / Render 的 0.0.0.0)时必须设置 APP_ACCESS_TOKEN;本地 127.0.0.1 开发可留空。
  • LangSmith:langgraph.json 导出 data_analysis_agent 图,可直接创建 LangSmith Deployment;数据集通过 dataset_id 或受控 dataset_path 提供。
  • Render:根目录 render.yaml 提供 Blueprint 一键部署(Free 档可直接同步成功)。首次创建 Blueprint 需在 Render 控制台批准首次同步——状态为 Created 时 autoSync 不生效,批准后推送才会自动同步;文件内注释含 Starter 及以上档位启用持久磁盘的完整配置。Free 实例休眠后容器存储会清空,长期保存数据请启用 S3/R2 后端。
  • CI:.github/workflows/ci.yml 在 push / PR 时自动执行 ruff、pytest(含 240s 单测超时保护与 --cov-fail-under=97 覆盖率门禁)与前端类型检查、测试及生产构建。

质量检查

.\.venv\Scripts\python.exe -m pytest -n 4   # 后端测试(默认并行 4 路;不调用真实 LLM,不产生费用)
.\.venv\Scripts\python.exe -m ruff check .  # 后端代码检查
cd frontend && npm run typecheck            # 前端 TypeScript 类型检查
cd frontend && npm test                     # 前端单元/组件测试
cd frontend && npm run build                # 前端生产构建

后端测试覆盖 src/data_agent 全部核心路径(节点、工具、路由、注册表、存储、
CLI、部署),含异常分支与降级路径;CI 中以 DATA_AGENT_SKIP_KALEIDO=1 跳过
偶发挂起的无头 PNG 渲染(503/500 降级分支仍被覆盖)。

深入文档

  • docs/engineering-notes.md — 工程笔记:已验证的工程事实与踩坑记录(大数据图表可读性方案、可访问性校准方法、性能与体积预算、沙箱/隐私/指标模块设计要点、平台差异实证)。
  • docs/competitive-analysis.md — 竞品分析:与同类数据分析 Agent 产品的定位与能力对比(2026-09 初查 + 2026-11 官方一手页实地复核,含抓取矩阵与可达性负证据)。
  • docs/agent-eval.md — 发布前评测:配对结果格式、McNemar 精确检验、成本/延迟护栏、ledger 校验与 CI 接法。
  • docs/analysis-provenance.md — 分析溯源:哈希链格式、API 与离线复核方法、信任边界。

Reviews (0)

No results found