智能问数 yimeng99/dsh-data-agent

English ·

dsh-data-agent

面向 DeepSeek Harness 的企业级 AI 数据分析插件套件：自然语言 → Text-to-SQL → 数据库 → 结构化结果 → ECharts。

基于 DeepSeek Harness 的 Cordis 插件体系，采用官方推荐的 Service Definition / Provider / Consumer 三层模式：数据库能力被抽象为可替换的 Service，Agent 通过 Tool 消费它，更换数据库 Provider 完全不需要改动 Tool 代码。

DeepSeek Harness
│
▼
AI Agent
│
┌──────────┴───────────┐
▼ ▼
data_query generate_chart
│ │
▼ ▼
DataQueryService ECharts option
│
┌──────┼──────────┐
▼ ▼ ▼
MySQL Postgres ClickHouse... (Provider 可替换) │ ▼ Schema Discovery ──→ Text-to-SQL ──→ SQL Validator ──→ Read-only Executor

功能特性

- 自然语言 → SQL：Agent 把业务问题翻译成只读 SQL，且复用会话同一条 LLM 路由（Text-to-SQL 与对话使用同一个模型）。
- 多数据源路由：任意数量的数据库可同时生效——每个 Provider 实例按 sourceId 注册（如 mysql、demo2、postgresql），data_query 工具通过 source 参数路由。
- Schema 自动发现：从 information_schema 读取表、列、注释、外键（带 TTL 缓存）并喂给模型。
- 安全默认：仅允许 SELECT / WITH；写操作 / DDL 关键字一律拒绝；LIMIT 自动钳制；每次执行有超时预算并全程透传 AbortSignal。
- Provider 可替换：MySQL、PostgreSQL 已实现——新增 ClickHouse / Doris 只需照抄一个 Provider 包。
- 图表：generate_chart 把查询结果转成可直接渲染的 ECharts option （line / bar / pie / scatter）。

包结构

| 包 | 层 | 职责 |
| packages/dsh-data-query | Service Definition + 门面 | 定义 dataQuery 能力（请求/结果/错误类型 + 共享 SQL 安全工具），并挂载路由门面 ctx.dataQuery，Provider 在它上面注册后端 |
| packages/dsh-data-query-config | 管理（设置） | 注册 data-query-sources settings namespace——Web UI 设置页以表单渲染；按配置实例化对应方言后端，每次修改实时生效 |
| packages/dsh-data-query-mysql | Provider | MySQL 后端：information_schema 自动发现 → LLM Text-to-SQL → SQL 安全校验 → 只读执行（每个 sourceId 一个实例） |
| packages/dsh-data-query-postgres | Provider | PostgreSQL 后端（V0.2，接口与 MySQL 完全一致） |
| packages/dsh-tool-data-query | Consumer / Tool | 注册 data_query 工具（带 source 参数），把自然语言问题转发给 ctx.dataQuery |
| packages/dsh-tool-echarts | Consumer / Tool | 注册 generate_chart 工具：表格数据 → ECharts option + 自包含 HTML 页面（浏览器可直接渲染真图表） |
| packages/dsh-client-ui-chart | 客户端插件 | 把 generate_chart 结果内嵌渲染成聊天里的 ECharts 图表（tool.call.toolview 键控座位，读取工具的 presentationMeta） |

环境要求

- Node.js ≥ 20，pnpm
- DeepSeek Harness 0.1.0-rc.6（任意带 dsh-base bundle 的 profile，如 web）
- 一个 MySQL 8 实例（示例数据：examples/mysql/schema.sql）

安装方法

1. 克隆并构建

git clone https://github.com/yimeng99/dsh-data-agent.git
cd dsh-data-agent
pnpm install
pnpm build

2.（可选）加载演示数据库

mysql -u root -p < examples/mysql/schema.sql # 创建 demo 库

3. 把插件注册进你的 DSH profile

两种方式任选其一。$REPO 为 clone 下来的仓库绝对路径。

方式 A —— 用 dsh plugin（纳入 profile 依赖管理）：

dsh plugin --profile web add \
file:$REPO/packages/dsh-data-query \
file:$REPO/packages/dsh-data-query-mysql \
file:$REPO/packages/dsh-tool-data-query \
file:$REPO/packages/dsh-tool-echarts

方式 B —— 链接进共享库（不改动 profile 的依赖清单）：

Windows（junction）：

$store = "$env:USERPROFILE\.dsh\profiles\node_modules"
foreach ($pkg in 'dsh-data-query','dsh-data-query-mysql','dsh-tool-data-query','dsh-tool-echarts') {
New-Item -ItemType Junction -Path "$store\$pkg" -Target "$REPO\packages\$pkg"
}

macOS / Linux（symlink）：

store="$HOME/.dsh/profiles/node_modules"
for pkg in dsh-data-query dsh-data-query-mysql dsh-tool-data-query dsh-tool-echarts; do
ln -s "$REPO/packages/$pkg" "$store/$pkg"
done

dsh-data-query 不需要单独的加载行——Provider 直接 import 它，与官方 dsh-fs 包的做法一致。

4. 应用 overlay 并启动

dsh web --patch ./cordis.patch.yml

cordis.patch.yml 挂载 dsh-data-query-config（设置驱动的数据源管理器）以及 data_query、generate_chart 两个工具。若 HMR 未自动生效，重启 dsh web。

5. 在设置页配置数据库连接（Web UI）

不需要改任何 YAML——设置页会把 data-query-sources namespace 渲染成表单，每个数据库添加一条：

| 字段 | 含义 |
| sourceId | 唯一标识，data_query 工具的 source 参数用它（如 mysql、demo2、postgres） |
| dialect | mysql 或 postgresql |
| host / port / user / password / database | 连接信息（密码只存不回显） |
| isDefault | 未指定 source 时的默认数据源 |
| llmProvider / llmModel | Text-to-SQL 路由（默认跟随会话模型） |
| maxRows / timeoutMs | 安全上限 |

修改实时生效（后端自动重建，无需重启）。同一配置以 data-query-sources: 段存储在 $DSH_HOME/settings.yaml。

6. 试试

在 Web UI 新开一个会话，直接问：

- 「统计一下最近 30 天订单数量」
- 「查询产品销量前 10」
- 「帮我分析最近 12 个月订单趋势，并画一个折线图」
- 「用 demo2 数据源统计订单数量」

图表展示

两条互补路径：

1. 聊天内嵌（客户端插件）。 generate_chart 发布 presentationMeta
（{ kind: 'echarts', option }），随工具结果落地；dsh-client-ui-chart
客户端插件把它渲染成聊天流里的实时 ECharts 图表（注册在开放的 tool.call.toolview 键控座位，不影响其他工具）。
2. 可打开的 HTML 交付物。 工具同时返回自包含 HTML 页面（CDN 引入 ECharts）；Agent 用 write 工具存成 .html 文件（如 charts/trend.html），出现在聊天交付物行，任何浏览器可打开——适合分享或嵌入。

多数据源

任意数量的数据库可同时生效。在设置页添加即可（见上文）——每条配置按 sourceId 注册一个后端：

$DSH_HOME/settings.yaml —— 由设置页写入 data-query-sources: sources:
- { sourceId: mysql, dialect: mysql, database: demo, isDefault: true }
- { sourceId: demo2, dialect: mysql, database: demo2, isDefault: false }
- { sourceId: postgresql, dialect: postgresql, database: demo, isDefault: false }

data_query 工具的 source 参数选择后端；省略时用默认源。新增方言（ClickHouse / Doris / SQLServer…）只需照抄 dsh-data-query-mysql 实现一个 Provider 包，并在 dsh-data-query-config 的 instantiateBackend 里接入。

安全设计（V0.1 已内置）

- 只读校验：仅允许 SELECT / WITH；DROP / DELETE / UPDATE / INSERT / TRUNCATE / ALTER / CREATE / GRANT / REVOKE / REPLACE / RENAME / LOCK / UNLOCK 一律拒绝（正则层，V0.3 升级为 SQL AST 校验）。
- LIMIT 钳制：自动追加 / 收敛 LIMIT 到安全上限，防止全表拉取。
- 超时 + 取消：每次执行有超时预算，工具调用的 AbortSignal 全程透传。
- 大数安全：BIGINT / DECIMAL 保持精确（安全整数范围内返回数字，超出返回字符串）。

测试（本仓库自带）

node scripts/smoke.mjs # 无库冒烟：Cordis 接线 + 工具注册 + 图表 builder + SQL 校验器
node scripts/load-schema.mjs # 把 examples/mysql/schema.sql 灌进本地 MySQL（demo 库）
node scripts/e2e.mjs # 真库端到端：schema 发现 + Text-to-SQL + LIMIT 钳制 + 拒绝/中止

e2e.mjs 里 LLM 阶段用 stub 代替（不消耗真实模型调用），其余全部走真实 MySQL。
连接参数可用 DSH_DB_HOST / DSH_DB_PORT / DSH_DB_USER / DSH_DB_PASSWORD 环境变量覆盖，默认 127.0.0.1:3306 root / demo。

真实 DeepSeek 端到端（已验证 ✅）

已用真实 DeepSeek（生成 SQL）+ 真实 MySQL 端到端验证，例如：

$ dsh --profile headless --patch ./cordis.patch.yml "统计最近 30 天订单数量"
最近 30 天订单数量：30 单 SQL: SELECT COUNT(*) FROM orders WHERE created_at >= NOW() - INTERVAL 30 DAY

以及双工具协作（data_query + generate_chart）产出 12 个月订单趋势折线图。

多数据源路由（真实 LLM）：两个 MySQL 数据源（mysql → demo、demo2 → demo2）并存，Agent 按 source 路由——「统计 demo2 数据源订单总数」返回 361，而默认数据源返回 360，证明注册表按问题选中了正确的库。

路线图

| 版本 | 内容 | 状态 |
| V0.1 | MySQL + data_query + Text-to-SQL + 基础 SQL 校验 | ✅ |
| V0.2 | PostgreSQL Provider；Schema 缓存与注释增强 | ✅ 已实现，真库验证待补 |
| V0.2.5 | 多数据源路由：dataQuery 门面 + 按实例 sourceId 注册表 | ✅ |
| V0.3 | 设置页配置数据源（data-query-sources，实时生效）+ 自包含图表 HTML 交付物 | ✅ |
| V0.4 | SQL AST 校验器；maxRows/timeout 精细化；审计日志 | — |
| V0.5 | 聊天内嵌图表卡片（客户端插件）+ Permission-aware Text-to-SQL：RBAC / Tenant / Data Scope | 内嵌图表 ✅，RBAC — |

设计说明

- 为什么 Tool 不直接连库：data_query 只依赖抽象的 ctx.dataQuery，方言、 Schema、安全策略都在 Provider 里，与官方 dsh-shell → dsh-bash-local → dsh-tool-bash 的分层一致。
- 权限上下文：DataQueryRequest 已携带 userId / roleIds / tenantId / departmentId；V0.5 增加 Policy Engine，对生成的 SQL 做权限改写（如自动追加 AND tenant_id = ?）。
- ECharts 呈现：当前 generate_chart 返回 option JSON 供模型/UI 阅读；真正的图表卡片需要注册自定义客户端模块（ClientModuleRegistry），属于 Web UI 侧的独立工作。
- 发布 npm 前：把包名换成 scoped 名（如 @yourname/dsh-data-query），并把内部 file:../ 依赖换成版本号。

许可证

MIT