Tukey
图基 —— 开源版「数据分析师」，直接住进你的编码 Agent。
挂上 CSV 或 Postgres 数据库，自动画像、只读 SQL 提问、图表直接画在对话里。
名字取自 John Tukey：探索性数据分析、箱线图，以及这个画像器正在跑的 1.5×IQR 离群规则，都是他的发明。
English · 中文
一个真实的 DeepSeek Harness 会话——Agent 接入 CSV、生成画像、把图表画成对话节点
（无头 Chrome 对实机界面的截屏，见[验证记录](docs/VERIFICATION.md)）：
---
## 它能做什么
```
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：
```bash
dsh plugin --profile web add tukey
```
Claude Code（或任意 MCP 客户端，stdio）：
```bash
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
```
## 开发
```bash
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](docs/VERIFICATION.md)。
## 已知限制
- **PTC 模式（Code Mode）预设拒绝直接工具调用**——在该模式下模型需要把调用包进
`run_code` 程序；标准模式下直接调用。已实测，记录在
[docs/VERIFICATION.md](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