数据库工作台 alingalingling/dsh-data-workbench

dsh-db-workbench（数据库工作台）

给你的 DeepSeek Harness 智能体装上真正的数据库能力：把自然语言问题变成对真实数据库执行的 SQL —— 带 schema 内省、受护栏的写入、EXPLAIN、以及 CSV/JSON 导入导出。

- SQLite 开箱即用 —— 零依赖，基于 Node 内置的 node:sqlite。
- PostgreSQL 与 MySQL 惰性加载、可选（pg / mysql2）。
- 优美的 Web 工作台 —— 聊天旁的一个「数据库」标签页（外加设置里的全屏「Database」页面）：schema 树、SQL 编辑器、结果网格、查询历史。
- 默认安全 —— 连接默认只读（除非你显式开启写），危险语句被拒绝，并把「先看 schema 再写 SQL」的工作流教给模型。

安装

用预构建的 tarball（推荐，内含编译好的 lib/）
dsh plugin --profile web add ./dsh-db-workbench-0.2.3.tgz

从 npm（发布后可用）
dsh plugin --profile web add dsh-db-workbench

卸载：

dsh plugin --profile web remove dsh-db-workbench

dsh plugin add 会把参数转发给 profile 目录里的 pnpm，然后自动激活插件的 bundle 层。

快速上手

1. 安装插件并打开 DSH Web 界面。
2. 在会话里直接让智能体搭一个内存 SQLite 数据库：

创建一个名为 analytics 的 SQLite 数据库连接，然后建一张 orders 表（id、customer、amount 三列）并插入几行数据。

3. 智能体会自动调用 db_connection_add、db_execute、db_query。你也可以在 $DSH_HOME/settings.yaml 里手写连接配置（见下）。

工具

| 工具 | 用途 | 读 / 写 |
| db_connections | 列出已配置的连接及其状态 | 读 |
| db_connection_add | 新增或更新连接配置 | 配置 |
| db_connection_remove | 删除连接（并关闭） | 配置 |
| db_test_connection | 连接健康检查（SELECT 1） | 读 |
| db_schema | 列出表，或描述某张表（列/索引/外键） | 读 |
| db_query | 执行只读 SQL（SELECT / WITH / PRAGMA / EXPLAIN） | 读 |
| db_browse | 快速浏览表数据（SELECT * LIMIT/OFFSET） | 读 |
| db_execute | 执行写入/DDL SQL，带事务与护栏 | 写 |
| db_plan | 查看查询计划（EXPLAIN QUERY PLAN / EXPLAIN） | 读 |
| db_import | 把 CSV/JSON 文件导入表（自动推断类型并建表） | 写 |
| db_import_database | 导入整个数据库：.db/.sqlite 文件（注册为连接）或 .sql 转储（执行） | 写 |
| db_export | 执行查询并把结果写成 CSV/JSON 文件 | 读 + 文件 |
| db_history | 回看本会话最近的查询与写入 | 读 |

Web 工作台

安装后，工作台会出现在两个位置，两者共享同一个 host 领域（在一处新增的连接，另一处立刻可见，模型也可用）：

- 会话标签页 —— 会话顶部的「聊天」标签旁，会多一个 「数据库」标签，让你在对话的同时就能跑 SQL、看表结构，无需离开会话。这是日常使用的主入口。
- 设置页 —— 打开 DSH Web 设置（左下角齿轮图标），选择 Database 页面，可得到同一工作台的全屏版本。

功能：

- 连接管理 —— 通过表单新增/删除/测试连接（驱动、目标、凭据、只读开关）；重加同名即覆盖。
- 导入数据库 —— 一键导入已有 .db/.sqlite 文件为连接，或把 .sql 转储执行到目标连接。
- Schema 树 —— 左侧 连接 → 表 → 列 树；双击表可加载 SELECT * … LIMIT 100，展开可见列类型、主键、可空性。
- SQL 编辑器 —— Ctrl+Enter 运行查询，结果以网格展示（NULL、数字、截断均有标记），还可把当前结果下载为 CSV。
- 查询历史 —— 每次查询/写入都会被记录（内存态，重启后清空），点击历史条目即可回填编辑器。

面板与 agent 工具共享同一个 host 领域，所以在 GUI 里加的连接模型立刻可用，反之亦然。

关于持久化。 连接配置是持久的（存在 $DSH_HOME/settings.yaml）。数据则取决于数据库本身：:memory: SQLite 连接在每个新进程里都是空库，而文件型 SQLite（或 Postgres/MySQL 服务器）会跨会话保留数据。

连接配置

连接保存在持久的 db-workbench settings 命名空间里，可在 Web 设置页修改，也可直接写 $DSH_HOME/settings.yaml：

db-workbench:
connections:
local:
driver: sqlite
path: ./data/app.db # 省略 path 则为内存数据库 analytics: driver: postgres host: db.example.com port: 5432 database: warehouse user: read_only passwordEnv: WAREHOUSE_PG_PASSWORD # 从环境变量读取密码 ssl: true readonly: true mysql: driver: mysql host: 127.0.0.1 database: shop user: root password: changeme # 建议用 passwordEnv；内联密码明文存储 readonly: false

安全模型

- 默认只读。 每个连接默认 readonly: true；除非显式设为 readonly: false，否则 db_execute 与 db_import 会被拒绝。
- 语句分类。 db_query 只接受只读语句；db_execute 只接受写入/DDL 语句。
- 危险操作护栏。 DROP/TRUNCATE，以及不带 WHERE 的 UPDATE/DELETE，必须显式传 allow_destructive: true。
- 事务。 SQLite 写入包裹在 BEGIN/COMMIT 中（失败自动回滚）。
- 结果有界。 db_query 默认最多返回 100 行（可调），SQLite 驱动最多只把 5000 行载入内存。
- 密钥安全。 优先用 passwordEnv；内联 password 标记为 role(secret)，设置页会脱敏。

驱动

| 驱动 | 依赖 | 说明 |
| sqlite | 无（内置 node:sqlite） | 文件、:memory:、schema 内省、EXPLAIN QUERY PLAN |
| postgres | pg（可选） | dsh plugin --profile <name> add pg |
| mysql | mysql2（可选） | dsh plugin --profile <name> add mysql2 |

开发

pnpm install # 安装开发与构建依赖
pnpm run typecheck # tsc --noEmit（host 半边）
pnpm run build # 产出 lib/（host 半边）
pnpm run build:client # 产出 lib/client.js（浏览器工作台面板）
pnpm test # 单元测试 + cordis 集成测试（工具 + 远程服务）
pnpm pack # 生成 tarball 供 dsh plugin add 使用

插件分两半。host 半边是纯 ESM TypeScript，用 tsc 编译：注册 model-facing 工具（通过本地零依赖的 defineTool，见 src/tool-def.ts）+ 一个 TypertRemoteService（source-mode @Remote 方法）供浏览器面板调用。

重要架构经验： host 侧工具插件绝不能在运行时 import @deepseek-ai/dsh-tools。一旦 import，就会在 profile 的 node_modules 里装进第二份该包，遮蔽官方 harness 自己的副本，破坏内部 TOOL_RUNTIME_SCHEDULER 的 Symbol() 派发（报错 Cannot read properties of undefined (reading 'prepare')）。因此本插件自己把工具 schema DSL 编译成 JSON Schema。运行时 @deepseek-ai/* 依赖只有 cordis（仅类型）、dsh-settings、dsh-typert-protocol、schemastery；dsh-tools/dsh-llm 只作为 devDependencies 供测试套件使用。浏览器半边用 tsdown 打成 lib/client.js（CJS __ModuleLoader__ 交接，CSS 内联）。pg/mysql2 保持可选、按需惰性加载。

许可证

MIT