dsh-sql-connect

DeepSeek Harness 只读数据库插件：PostgreSQL、MySQL/MariaDB、SQLite。模型可以发现已配置的连接和表结构，并用参数化 SELECT 拿到有界结果。

兼容 DeepSeek Harness 0.1.5-rc.x / 0.1.6-alpha.x。Harness 仍可能发生不兼容变更。

安装

已经能打开 Harness Web 后，执行：

dsh plugin --profile web add dsh-sql-connect

然后重启：

dsh web

打开终端这一次打印的 http://127.0.0.1:3080/?token=...。旧标签没有新 token，会一直停在「正在加载模型…」。

平时如果跑的不是 dsh web，把 --profile web 换成你实际启动的 profile 名。

pnpm 10+ 若拦截 better-sqlite3 的安装脚本，在 $DSH_HOME/profiles/web/pnpm-workspace.yaml（默认 $DSH_HOME 是 ~/.dsh）加上：

allowBuilds:
  better-sqlite3: true

再重新执行安装命令。

卸载：

dsh plugin --profile web remove dsh-sql-connect

然后重启 profile。

配置连接

打开：设置 → 插件 → 插件配置 → 数据库连接

若没有这张卡片：到插件列表看 sql-connect 是否为「已启用 / 未运行」。未运行表示当前进程没加载到插件，确认装进了正在运行的 profile 并已重启。

以本地 PostgreSQL 为例：

1. 添加连接
   • 名称：market-cards（字母开头，只含字母、数字、_、-）
   • 数据库：PostgreSQL
   • 凭据引用：只填 MARKET_CARDS_POSTGRES_URL
     不要写成 MARKET_CARDS_POSTGRES_URL:postgres://...
   • Schema / 表：可留空
   • 点 保存配置
2. 凭据
   • 出现名为 MARKET_CARDS_POSTGRES_URL 的密码框后再填完整 URL：
     postgres://用户:密码@127.0.0.1:5432/库名
   • 点 保存 / 轮换，状态变为「已配置」

连接 URL 写到 $DSH_HOME/.credentials.yaml，不会进 Settings，也不会进模型上下文。不要把带密码的 URL 发给模型或写入 cordis.patch.yml。

SQLite 填「SQLite 文件」路径，不需要凭据引用。文件必须已存在。

MySQL/MariaDB 凭据引用同样只填环境变量名，URL 形如 mysql://用户:密码@host/database。

配置完成后新开一个会话，问：

列出已配置的数据库连接，然后列出 market-cards 里的表。

正常时会调用 db_list_connections / db_list_tables，而不是 psql 或扫描 PG* 环境变量。

常见问题

| 现象 | 原因 | 处理 | | --- | --- | --- | | 模型说没有连接工具，去找 psql / PG* | 插件没装进正在运行的 profile | dsh web 就要 --profile web；装完重启 | | 设置里没有「数据库连接」卡片，插件显示未运行 | Host 没加载插件 | 确认安装命令成功后重启 | | dsh plugin add 找不到包 | 默认 npm 镜像尚未同步 | npm config get registry 若不是 npmjs.org，改用 https://registry.npmjs.org 后再装 | | Host 拒绝了配置 | 「凭据引用」里粘了整段 URL | 引用栏只留变量名，URL 放到「凭据」 | | 一直「正在加载模型…」，终端无报错 | 用了重启前的旧标签 | 打开终端新打印的 ?token= URL | | SOCKS / all_proxy 提示 | Clash 的 socks5 不被 Harness 使用 | 可忽略；页面卡住则绕过 localhost |

安全模型

插件采用多层防护，但数据库权限是最终安全边界：

• PostgreSQL 和 MySQL/MariaDB 查询运行在只读事务中；SQLite 文件以只读和 query_only 模式打开。
• db_query 只接受 SQL 解析器识别出的单条 SELECT。多语句、写语句、SELECT INTO 和锁定读取会被拒绝。
• 可按连接限制 schema 和表；配置 allowedSchemas 后，查询中的表必须显式带 schema。
• 查询受超时、全局并发、最大返回行数和累计行数据字节数限制。
• PostgreSQL/MySQL 结果使用流式读取；SQLite 在隔离子进程中执行，超时或取消会终止该进程。
• 连接 URL 只能通过凭据引用解析，不会写入 Settings、模型工具 schema 或正常工具结果中。

SQL 解析和只读事务不能替代最小权限账号。某些数据库函数、扩展或外部表可能在 SELECT 中产生外部副作用；请使用专门的只读数据库角色，并只授予必要 schema、表和视图的读取权限。

工具调用和结果会成为模型上下文，并由 Harness 写入 Session 日志。连接生产数据库前，请先检查 DeepSeek Harness 的安全与遥测设置。

提供的工具

• db_list_connections：返回连接名称、dialect 和可选说明，不包含连接 URL。
• db_list_tables：列出允许访问的表和视图。
• db_describe_table：返回列名、数据库类型、可空性、主键和默认值。
• db_query：执行一条参数化 SELECT，返回列、行数、结构化行和截断状态。

PostgreSQL 参数使用 $1、$2；MySQL/MariaDB 和 SQLite 使用 ?。

YAML / 环境变量（可选）

Web Settings 足够日常使用。若要用 patch 文件管理配置，bundle 会注册 id 为 sql-connect 的配置行。后层 patch 会整体替换 config，请保留全部全局字段：

- id: sql-connect
  config:
    connections:
      - name: analytics-pg
        dialect: postgresql
        description: 只读分析库
        urlEnv: ANALYTICS_POSTGRES_URL
        allowedSchemas: [reporting]
        allowedTables:
          - reporting.orders
          - reporting.customers
      - name: local-sqlite
        dialect: sqlite
        filename: /absolute/path/to/analytics.db
        allowedSchemas: [main]
        allowedTables:
          - main.events
    defaultMaxRows: 200
    maxRows: 1000
    maxResultBytes: 262144
    queryTimeoutMs: 30000
    maxConcurrency: 4

也可以在启动 Harness 之前用环境变量提供 URL（会遮蔽本地凭据存储，Settings 里该引用变为只读）：

export ANALYTICS_POSTGRES_URL='postgres://readonly-user:password@host/database'

allowedTables 可以使用表名或 schema.table。MySQL 的 schema 对应数据库名；PostgreSQL 未指定 schema 时默认为 public；SQLite 使用 main。

自定义精简 profile 必须同时组装 Settings 和本地 credentials provider，否则工具仍可按 YAML 运行，但 Web 卡片和凭据页不可用。

本地开发

pnpm install
pnpm run build --watch

创建 overlay，把入口换成构建产物的绝对路径：

- insert:
    - id: sql-connect-local
      name: /absolute/path/to/dsh-sql-connect/lib/index.js
      config:
        connections: []
        defaultMaxRows: 200
        maxRows: 1000
        maxResultBytes: 262144
        queryTimeoutMs: 30000
        maxConcurrency: 4

dsh web --patch /absolute/path/to/local.cordis.yml

使用 lib/index.js，确保 SQLite 子进程和主插件在同一发布目录。

pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build

SQLite 集成测试始终运行。设置以下变量后还会连真实 PostgreSQL / MySQL：

export DSH_TEST_POSTGRES_URL='postgres://...'
export DSH_TEST_MYSQL_URL='mysql://...'
pnpm run test

CI 使用 PostgreSQL 17 和 MySQL 8.4 service container。

已知限制

• 不支持 INSERT、UPDATE、DELETE、DDL、存储过程或数据库管理命令。
• 不支持 SQL Server、Oracle 和 MongoDB。
• SQL 解析器可能拒绝某些合法但少见的方言扩展；插件会安全失败，而不会绕过检查。
• SQLite 每次操作会启动隔离子进程，更适合本地分析文件，不适合高频低延迟查询。
• 远程数据库凭据使用 Harness 本地 credentials provider，不集成系统 Keychain 或外部 KMS。