对话式数据分析Chenmo0414/tukey

Tukey

图基 —— 开源版「数据分析师」，直接住进你的编码 Agent。
挂上 CSV 或 Postgres 数据库，自动画像、只读 SQL 提问、图表直接画在对话里。

名字取自 John Tukey：探索性数据分析、箱线图，以及这个画像器正在跑的 1.5×IQR 离群规则，都是他的发明。

English · 中文

一个真实的 DeepSeek Harness 会话——Agent 接入 CSV、生成画像、把图表画成对话节点
（无头 Chrome 对实机界面的截屏，见验证记录）：

它能做什么

data_attach     →  把 CSV / Parquet / JSON / XLSX 文件注册为可查询的表
data_attach_db  →  只读接入 PostgreSQL / MySQL / SQLite 并列出其表
data_profile    →  类型、缺失值、精确基数、离群点、数据质量问题、图表建议
data_query      →  一条只读 SQL（DuckDB 方言），结果为无损 JSON
data_chart      →  bar / line / scatter / histogram / area / heatmap / boxplot（Vega-Lite，
可交互）+ sankey / sunburst / treemap / gauge（ECharts）；
支持 color 分组、stacked/grouped、facet 小倍数；line/scatter 可拖拽缩放
data_report     →  自包含 HTML 报告（画像 + 内嵌 SVG 图表），浏览器可直接打印为 PDF
data_sources    →  当前已接入的数据集

同一个引擎，七个同名工具，服务两类宿主：

| 宿主 | 包名 | 图表交付方式 |
|---|---|---|
| DeepSeek Harness 插件 | tukey | 对话内实时渲染（conversation node + Vega canvas） |
| MCP server（Claude Code / Codex / Cursor / 任意 MCP 客户端） | tukey-mcp-server | SVG 文件 + structuredContent 里的完整 Vega-Lite spec |

在 dsh 的 Code Mode（PTC 模式）下，全部工具也可以在 run_code 程序里以
await tools.data_(args) 链式调用，一段程序内完成 接入 → 画像 → 查询 → 出图。

工作台——会话头部的浮层面板：本会话的数据源、可点击定位的图表库、报告存档：

两个引擎同屏——热力图与箱线图由 Vega-Lite 实时绘制，桑基与矩形树由 ECharts 在宿主端渲染：

更多对话内图型（同一主题，同样从真实会话导出）：

安装

DeepSeek Harness：

dsh plugin --profile web add tukey

Claude Code（或任意 MCP 客户端，stdio）：

claude mcp add tukey -- npx -y tukey-mcp-server

架构

三个决定塑造了这套代码。

引擎对宿主一无所知。 @tukey/core 输入路径和 SQL，输出无损 JSON，
不引用任何 dsh、MCP 或 CLI 类型。这是同一份分析能力能同时进入 dsh 和
Claude Code / Codex / Cursor、而不用维护第二套实现的根本原因。

统计交给 DuckDB。 SUMMARIZE 一趟返回每列的
min/max/avg/std/四分位/基数/空值率，并直接读取 CSV、Parquet、JSON 且做全文件
类型推断。手写的只有 IQR 离群检测、重复行检测和"什么值得告警"的判断。
基数在 ≤200 万行时用精确计数——HyperLogLog 估计会把 4 个类目报成 3，
对分析工具这是错误答案，不是近似。

两个图表引擎，按图型选择——而客户端只打包一个。 Vega-Lite 负责探索性图型：
语法简短，浏览器端实时可交互。ECharts 负责 Vega-Lite 根本没有语法的形状——
流向（桑基）、层级（旭日、矩形树）、单值 KPI（仪表盘）。若把 ECharts 也打进浏览器，
单文件插件包会多约 600 KB，而这个包每个会话都要下载，无论有没有图；所以这些图型
在宿主端渲染成 SVG、以标记形式随事件传输，spec 也一并携带，懂 ECharts 的客户端可以
自己实时渲染。实测浏览器端增重：0 KB。

图表是承载在会话事件上的 spec。 dsh 的工具卡片种类是封闭集合
（generic、terminal、diff、search、web），没有图表成员，所以真正的图
只能来自 conversation node*——由插件的浏览器半边注册。而 conversation node
要求视图是持久事件的纯函数（无时钟、无随机、无活状态），数据内联的
Vega-Lite spec 恰好就是可逐字节重放的一段纯 JSON。选 Vega-Lite 是因为它满足
重放规则，而不是因为它流行。

@tukey/core            引擎、画像、数据库连接、图表 spec   （宿主无关）
├── @tukey/report    Vega-Lite → SVG（纯 JS）+ 自包含 HTML 报告
├── tukey            dsh 宿主半边：7 个工具 + 图表事件
│     └── ./client         dsh 浏览器半边：conversation node + Vega canvas
└── tukey-mcp-server stdio MCP server：同样 7 个工具，图表输出 SVG

开发

pnpm install
pnpm -r run build
pnpm -r run test

89 个测试：core 58 个（SQL 安全策略、JSON 转换、精确基数画像、图表，以及
无 Docker 环境自动跳过的 PostgreSQL/MySQL 实连测试），report 5 个，dsh 插件
14 个（端到端驱动真实工具与 DuckDB，含按 agent 隔离），MCP 9 个（走 SDK 内存
传输的协议级往返，另有 stdio 进程冒烟脚本）。针对运行中 dsh web 的实机验证脚本在
scripts/mock-llm-scripted.mjs + scripts/verify-live.patch.yml——见
docs/VERIFICATION.md。

已知限制

- PTC 模式（Code Mode）预设拒绝直接工具调用——在该模式下模型需要把调用包进
run_code 程序；标准模式下直接调用。已实测，记录在
docs/VERIFICATION.md。
- dsh 的按 agent 引擎有上限而无生命周期跟踪。每个 dsh 会话有独立引擎（别名
不再冲突），但 harness 不通知插件 agent 销毁，因此最多持有 32 个引擎、按 LRU
淘汰——被淘汰的会话下次调用时透明地重新 attach。
- dsh 客户端 bundle 约 860 kB。Vega 被内联，因为 harness 每个插件只服务一个
文件、没有 sibling chunk 路由；无图会话也要付这份体积。
- data_attach 接受宿主进程可读的任意路径，尚无工作区围栏，继承 harness
沙箱的边界。
- XLSX 依赖 DuckDB 的 read_xlsx，首次使用可能需要下载扩展。CSV、Parquet、
JSON 有测试覆盖；XLSX 没有。

写给 dsh 插件开发者的备注

两件事在这里耗了时间，值得记录：

- npm 的 latest 标签指向一条坏掉的旧版本线。 npm view @deepseek-ai/dsh-tools
version 报 0.0.1-rc.1，但当前线是 0.1.0-rc.8。若干 0.0.1-rc.1 包完全装不上
（依赖了未发布的 dsh-compact、dsh-type-meta）。锁定 0.1.0-rc.8。
- 浏览器半边不是 ESM。 dsh 的浏览器运行时是懒 CJS 模块表：插件 bundle 必须执行
window.__ModuleLoader__.load({ id, factory: (require) => {...} })，react 等共享
单例通过注入的 require 获取。裸 import "react" 会直接失败——页面没有
import map。本仓库的 packages/dsh/scripts/bundle-client.mjs 复刻了官方
tsdown.client.ts 的 banner/footer 契约。

路线图

| | |
|---|---|
| M1 | Core + dsh 插件，对话内出图 — 已完成并实机验证 |
| M2 | MCP server：同样能力进入 Claude Code / Codex / Cursor — 已完成 |
| M3 | HTML 报告导出（可打印 PDF）、PostgreSQL / MySQL / SQLite、按 agent 隔离 — 已完成 |
| M4 | 工作台面板：数据源、可点击定位的图表库、报告存档 — 已完成并实机验证 |

许可证

MIT