dsh-db-connector

dsh plugin --profile web add dsh-db-connector

dsh-db-connector



[English](./README.md)

一个面向 DeepSeek Harness

（dsh，基于 Cordis 的「一切皆是插件」框架）的数据库连接器 bundle。

它通过五个面向模型的工具，加上一个人类可用的 /db 命令，为你的 agent 提供对

SQLite、PostgreSQL、MySQL 的安全且可审计的访问，并刻意聚焦于

只读安全、schema 智能、写操作审批门、持久化 SQL 审计——这正是官方 dsh 工具目录尚未覆盖的领域。

本 bundle 为全新独立实现，未照搬任何现有开源 dsh 工具代码；工具名、参数结构与结果格式均属本 bundle 自身设计，与任何官方 dsh schema 无关。

---

功能总览

关注点 · 说明

连接管理 · 命名连接（SQLite / PostgreSQL / MySQL）；惰性打开、复用、显式关闭，每个连接一行脱敏状态。

凭据处理 · 密钥来自 环境变量（${VAR} 占位、passwordEnv）或 dsh 凭据服务（passwordRef）。绝不写入日志或审计。

Schema 内省 · 表 / 视图 / 列（名称/类型/可空/默认值/主键）/ 索引 / 外键；按连接缓存快照（TTL），支持刷新与过滤。

只读查询 · db_query 只执行 SELECT / EXPLAIN 类语句，其余在接触数据库之前即被拒绝；带结果行数上限、SELECT 前置 LIMIT、JSON 化结果。

写操作审批门 · INSERT / UPDATE / DELETE / DDL 必须显式传入 allowWrite: true 确认；写入在事务中执行：成功 COMMIT，失败 ROLLBACK。

SQL 审计 · 每次调用（含被拒与失败）追加一条 JSONL 记录：时间、连接、语句摘要+摘要哈希、类型、行数、耗时、状态、错误、来源（tool/command/cli）。

注入防护 · 值一律以参数绑定（? 或 :name）下发，从不拼接进 SQL 文本。

超时 · 基于 AbortSignal 的语句级截止时间，对同步 SQLite 也能真实终止（子进程隔离）。

---

最低要求

• Node.js ≥ 22.13（使用内置、无需 flag 的 node:sqlite）。
• 一个运行中的 dsh profile，工具才会出现在 ctx.tools 上。
• 可选 服务器驱动（peer 依赖，仅在需要相应引擎时装）：
• PostgreSQL：npm i pg
• MySQL：npm i mysql2

SQLite 无需任何额外安装。开发（npm test）建议使用 Node ≥ 23.6，可原生运行类型剥离的测试文件。

---

如何接入 dsh（bundle 规范）

本包是一个 bundle：package.json 声明了 dsh.bundle.patch → ./cordis.patch.yml，补丁按包含包名的方式插入一行插件，由 Node 解析安装后的代码。入口模块导出标准 name / inject / apply(ctx, config)。

将 bundle 安装进某个 profile：

dsh plugin --profile <name> add /path/to/dsh-db-connector

该包也已发布到 npm，可单独使用引擎 / 编程式 API：

npm install -g dsh-db-connector   # 全局安装，CLI 方式使用引擎
npm install dsh-db-connector      # 或作为本地依赖加入

（等价地：把 "dsh-db-connector": "link:/path/to/dsh-db-connector" 加入 profile 的 dependencies，并把 "dsh-db-connector" 追加到 dsh.profile.bundles。）

启动时 apply(ctx, config) 依次：

1. 读取插件配置（apply 的第二个参数，支持 $DSH_HOME 与 DSH_DB_CONNECTOR_* 环境变量兜底）；

2. 预注册配置中的 connections（首次使用时惰性打开）；

3. 在 ctx.tools 上注册五个工具；

4. 若该服务存在，在 ctx.commands 上注册 /db 命令；

5. 上下文销毁时关闭全部连接并刷新审计日志。

所有注册均为 effect 式，卸载该行即自动撤销。

---

插件配置

配置写在插件行的 config: 块中（或后续补丁层按 id: db-connector 覆盖）。

- insert:
    - id: db-connector
      name: 'dsh-db-connector'
      config:
        # 启动时预注册的连接；各自惰性打开。
        connections:
          appdata:
            driver: sqlite
            database: ./data/app.db
          warehouse:
            driver: postgres
            host: db.internal
            database: warehouse
            user: readonly
            passwordEnv: WAREHOUSE_PG_PASSWORD   # 环境变量名，而非值
            # ...或 passwordRef: WAREHOUSE_PG_PASSWORD（dsh 凭据服务）

        audit:
          enabled: true
          path: .dsh-db/audit.jsonl
          # path 默认即此值；支持 ${ENV}

        query:
          maxRows: 1000
          timeoutMs: 30000
          maxSqlChars: 512

        schema:
          ttlMs: 60000

        defaultAllowWrite: false

环境变量覆盖：DSH_DB_CONNECTOR_AUDIT_PATH、DSH_DB_CONNECTOR_MAX_ROWS、

DSH_DB_CONNECTOR_TIMEOUT_MS。字符串值中的 ${VAR} 占位会在连接时从环境展开。

凭据——绝不进日志

安全姿势：密钥按名引用，绝不内嵌。

• passwordEnv: PG_PASSWORD 表示从同名环境变量读取值。
• passwordRef: MY_REF 通过 dsh 凭据服务（ctx.credentials）解析，回退为普通环境变量。
• 任意字段可使用 ${VAR} 占位。
• 内联 password 虽可用，但强烈不建议。

本 bundle 从不记录连接配置、密码或连接串：连接摘要只含名称 / 驱动 /

host:port / 库名与 auth=env|credentials|inline|none；错误信息只报环境变量

名字；审计记录只有语句摘要/哈希与计数，不含任何连接配置。

---

工具

五个工具均返回规范 JSON，并以格式化文本呈现给模型。

db_connect

注册、打开、列出或关闭一个命名连接。

{ "action": "connect", "name": "app",
  "config": { "driver": "sqlite", "database": "./data/app.db" } }

{ "action": "connect", "name": "wh",
  "config": { "driver": "postgres", "host": "db.local", "database": "wh",
              "user": "readonly", "passwordEnv": "WH_PASSWORD" } }

{ "action": "list" }
{ "action": "close", "name": "app" }

对已定义（来自配置或先前连接）的名称再次 connect 会重新打开而非报错；全新名称连接失败会大声报错。list 返回脱敏状态。

db_schema

内省某连接：表 / 视图、列、索引、外键。按连接缓存 schema.ttlMs 毫秒；

refresh: true 绕过缓存，filter 只保留名称包含该子串的表/视图。

{ "name": "app", "refresh": false, "filter": "user" }

db_query

运行只读查询（SELECT / EXPLAIN / DESCRIBE / SHOW）。

• 强制只读：任何写/DDL 语句都会以 READ_ONLY_VIOLATION 拒绝，并在接触驱动前记录为 denied 审计。涵盖 INSERT/UPDATE/DELETE/DDL/PRAGMA，以及隐蔽形式：EXPLAIN ANALYZE <dml>（会真实执行其语句）与数据修改型 CTE（WITH x AS (DELETE ...) SELECT ...）。
• 结果上限：行数以 limit（或 query.maxRows）封顶；对无自身 LIMIT 的顶层 SELECT 会追加 guard LIMIT。
• 超时：timeoutMs（或默认值）通过 AbortSignal 执行；SQLite 通过子进程拆解实现真实终止。

{ "name": "app", "sql": "SELECT id, email FROM users WHERE age >= ? AND age < ?",
  "params": [26, 40], "limit": 100 }

值支持位置参数（params 数组对应 ?）或命名参数（namedParams 对象对应 :name），一律参数绑定。占位符数量与值数量不匹配会给出友好的 INVALID_PARAMS。

db_exec

执行可能写入的语句（INSERT / UPDATE / DELETE / DDL，以及分类器无法判读的内容）。

• 写审批门默认开启：非纯读语句必须传 "allowWrite": true（即显式确认），否则以 WRITE_NOT_ALLOWED 拒绝并审计。
• 语句在事务内执行：成功 COMMIT，失败 ROLLBACK（错误不会留下部分行）。结果含受影响行数与回滚说明。
• DDL 会自动使该连接的 schema 缓存失效。

{ "name": "app", "sql": "UPDATE users SET age = age + 1 WHERE id = ?",
  "params": [1], "allowWrite": true }

db_audit

回读审计（元数据 + 语句摘要/哈希；不含凭据）。过滤：name（连接）、kind、since（ISO）、limit（最新的在前，默认 200）。

{ "kind": "denied", "limit": 50 }

---

人类命令（/db）

当命令服务存在（dsh-base 会挂载）时，本 bundle 注册一个 /db 斜杠命令，与工具共用同一引擎与安全门。

/db status
/db connect <name> --driver sqlite --db ./data/app.db
/db connect pg --driver postgres --host h --database d --user u --password-env PG_PASSWORD
/db close <name>
/db schema <name> [--refresh] [--filter sub]
/db query <name> --sql "SELECT ..." [--limit n] [--timeout ms] [--params a,b,c]
/db exec <name> --sql "UPDATE ..." --allo

…(truncated)