tomowang/dsh-data-agent

dsh-data-agent

npm version
CI status
license

一个 DeepSeek Harness（dsh）插件，用于管理数据库连接并运行 SQL，既支持对话方式，也支持从 Web UI 的设置页面操作。

功能特性

- 数据源管理 — 注册 MySQL、PostgreSQL、SQLite 或 ClickHouse 连接（da_add_data_source/da_edit_data_source/da_remove_data_source/da_list_data_sources），或从设置 → 数据源中管理它们。
- 连接检查与 schema 浏览 — da_test_connection 和 da_get_schema（数据库概览或单张表的完整列详情），在聊天中渲染为 Markdown 表格，并在聊天卡片和设置 schema 查看器中渲染为可展开的丰富浏览器。
- 表/列注释 — 从聊天中使用 da_set_comment，或在设置 schema 查看器中点击内联编辑；两者写入同一存储。
- 带只读开关的 SQL 执行 — da_run_sql，经过 AST 校验（而非字符串匹配），在只读数据源上拒绝写语句，并始终拒绝语句堆叠。可随时用 da_set_read_only（或设置中的复选框）切换数据源的只读标志。
- 图表 — da_render_chart 从 data（内联行）或 resultId（先前 da_run_sql 调用的结果，通过 id 引用而非重新发送 — 按对话缓存在内存中 30 分钟）渲染 chart.js 柱状图/堆叠柱状图/折线图/饼图。除了交互式 Web UI 图表外，它还会在服务端栅格化生成静态 PNG（通过 skia-canvas）并返回其 URL，因此图表可以作为 Markdown 图片嵌入到模型自己的回复中。

密钥从不直接存储：连接引用 passwordEnv（一个环境变量名称），在挂载时通过 harness 的 ctx.credentials 接缝在连接时解析，否则使用 process.env。

演示

https://github.com/user-attachments/assets/fa149214-cdd0-4820-9711-8e7451bb462f

连接、schema 和只读切换也可以直接从设置 → Data Agent 中管理：

设置 → Data Agent 面板

安装

需要已至少启动过一次的 web profile（dsh --profile web）。

1. 安装 dsh 启动器
npm install -g @deepseek-ai/dsh

2. 将此 bundle 安装到 web profile
dsh plugin --profile web add @tomowang/dsh-data-agent

3. 批准 skia-canvas 的原生构建脚本（da_render_chart 的 PNG 输出需要）
dsh plugin --profile web approve-builds
dsh 会自动协调 profile manifest 中的 dsh.profile.bundles 列表（本包声明了 dsh.bundle.patch），拉取已发布的 npm 包——无需本地检出或构建步骤。重启 web profile 进程即可使其生效。

从 dsh-market 安装

或者，你可以在 Web UI 中从 dsh-market 安装 @tomowang/dsh-data-agent。
搜索 tomowang/dsh-data-agent，然后在结果上点击 Install。

从 dsh-market 安装 dsh-data-agent

开发

pnpm install
pnpm run typecheck
pnpm run test

脚本：

- pnpm run typecheck — 对 Host（tsconfig.json）和 Client（tsconfig.client.json）源码进行类型检查
- pnpm run test — 运行测试（vitest）；tests/ 覆盖进程内 SQLite（无需服务器）以及 SQL 分类器、持久化和注册表逻辑——若要测试 MySQL/PostgreSQL/ClickHouse 适配器，请针对一个可访问的实例注册数据源（本地 Docker 容器即可），然后从那里运行 da_test_connection/da_get_schema/da_run_sql
- pnpm run build — 将两部分都构建到 lib/（build:host + build:client）
- pnpm run build:host / build:client（或 watch:host / watch:client，或直接使用 watch 同时构建两者）— 仅构建其中一部分
- pnpm run dev — 构建两部分并将此插件链接到本地 web profile（见下文）

架构

dsh-data-agent 架构图

项目结构

src/
index.ts                composition root: Config, apply() — mounts the registry, tools, the Settings-API routes, and the chart-image route
data-source/
types.ts, errors.ts   shared vocabulary and stable error codes
registry.ts           DataSourceRegistry (ctx.dataAgent): the Map-based connection registry
credential.ts         passwordEnv resolution (soft ctx.get('credentials'), else process.env)
schema-comments.ts    merges comments.json into a raw schema result (shared by the tool and the Settings route)
persistence/          sources.json / comments.json (atomic, cross-process-safe)
adapters/              one DataSourceAdapter implementation per engine (mysql2, pg, node:sqlite, @clickhouse/client)
sql/classify.ts         node-sql-parser-based read-only + single-statement enforcement
tools/                  the ten model-facing tools (one file each), plus QueryResultCache (ctx.queryResultCache),
chart-config.ts (shared chart.js config builder), and the chart-image render/store/route
backing da_render_chart's static PNG output (ctx.chartImageStore)
settings-api/           raw ctx.webServer routes + Origin trust check backing the Settings panel
src/client/                the browser bundle (see below)
index.ts                client plugin entry: registers the three chat toolviews + the Settings section
tool/                   da_run_sql / da_get_schema / da_render_chart 聊天卡片（卡片模型 + 组件 + toolview 注册）
settings/               Data Sources 设置面板及其 fetch() API 客户端
shared/SchemaTree.tsx   聊天卡片和设置面板共用的表/列浏览器
scripts/build-client.mjs 针对 src/client -> lib/client.js 的 esbuild 构建
cordis.patch.yml          当某个 profile 列出此包时应用的 bundle 层

针对 web profile 进行开发

仅限本地开发——这会将你的工作副本链接到某个 profile 中，以替代已发布的包，这样你无需发布版本即可迭代。它假定已全局安装 dsh CLI（npm i -g @deepseek-ai/dsh，或任何可在 PATH 上解析到的 dsh），并且某个 web profile 已至少启动过一次（dsh --profile web）。

将此检出链接到 web profile 并将其注册为一个 bundle：

pnpm run dev
等同于：pnpm run build && dsh plugin --profile web add .

这是一次性操作（或在更改 package.json 依赖后重新运行）：pnpm 会将此目录 link: 到该 profile 的 node_modules 中，并将 @tomowang/dsh-data-agent 追加到该 profile 的 dsh.profile.bundles。验证该层，然后启动：

dsh --profile web --dump-config   # 确认 "# == @tomowang/dsh-data-agent" 层
dsh --profile web

由于它是符号链接，编辑后无需重新运行 add——但该 profile 加载的是 lib/，从不直接加载 src/，对_两半_都是如此：在下一次启动拾取编辑之前，请先用 pnpm run build（或上文更细粒度的脚本）重新构建。两半都没有热重载（已核实：@deepseek-ai/cordis-plugin-hmr 明确排除了任何通过 node_modules 解析的内容，而链接的 profile 正是这样加载此插件的）——正在运行的 dsh --profile web 进程需要重启才能拾取重新构建的 bundle，仅重新加载页面是不够的（插件 bundle 列表在进程启动时即已固定）。dsh plugin --profile web remove @tomowang/dsh-data-agent 可撤销安装。

若要进行快速的仅 Host 的一次性测试，而不触碰任何 profile（同样仅限本地开发；会跳过客户端 bundle，因此没有 Web UI 卡片/设置——如需这些，请使用上文的链接 profile 流程），可直接将源文件覆盖到 deepseek-harness 源码检出上：

cd /path/to/deepseek-harness   # 你的本地检出
pnpm dsh web --patch <(cat <<EOF
- insert:
- id: data-agent
name: '/path/to/dsh-data-agent/src/index.ts'
config:
defaultMaxRows: 500
EOF
)

有关完整的插件/bundle 模型，请参阅 deepseek-harness 的插件教程和打包指南。

已知的 v1 限制
- SQL 占位符语法在不同引擎之间并不统一：MySQL/SQLite 使用 ?，PostgreSQL 使用 $1, $2, ...，ClickHouse 使用 {p1:Type}, {p2:Type}, ...（其 HTTP 接口仅支持命名参数；params 会按位置绑定到它们，即 p1、p2、……）。
- da_run_sql 的安全检查会拒绝任何解析器无法归类的语句（例如 SQLite 的 PRAGMA、某些 PostgreSQL 的 EXPLAIN 形式、ClickHouse 的 FORMAT 子句），而不是进行猜测——请使用 da_get_schema 进行内省，而不是使用原始 PRAGMA，并省略 FORMAT（ClickHouse 适配器自身始终会请求 FORMAT JSON）。
- node-sql-parser（基于 AST 的安全检查）没有专门的 ClickHouse 方言；ClickHouse 源会按其 PostgreSQL 语法进行分类，对于常见的 SELECT/DDL/DML 来说已经足够接近，但会将某些 ClickHouse 特有的语法拒绝为无法解析，而不是将其错误分类。
- Settings 面板的原始 HTTP 路由带有一个手工编写的 Origin 检查，而不是 harness 自身的 /api 信任围栏（后者特定于 ctx.remote 调用）——对于现有的仅限回环的威胁模型来说足够，但并不声称与之对等。