dsh-sql

English

@nnyc/dsh-sql

你的 agent 会查库了：SQLite / MySQL / PostgreSQL 三引擎，只读白名单 + 写审批门。

DSH（DeepSeek Harness）工程师级数据库插件：六个工具覆盖连接管理、只读查询、写操作、结构探查、库概览与自检。

兼容性

在 @deepseek-ai/dsh@0.1.1-rc.2 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（cordis.patch.yml + dsh.bundle.patch），运行时不 import 任何 @deepseek-ai/* 内部模块。

安装

dsh plugin --profile web add @nnyc/dsh-sql

卸载

dsh plugin --profile web remove @nnyc/dsh-sql

卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile cordis.patch.yml 中覆盖的插件行。

配置

- id: sql
  name: '@nnyc/dsh-sql'
  config:
    connections:
      - name: local
        engine: sqlite
        file: E:\data\app.db          # 或 :memory:
      - name: prod
        engine: postgres
        host: db.internal
        database: app
        # password: xxx              # 推荐环境变量 DSH_SQL_PASSWORD_PROD
      - name: legacy
        engine: mysql
        host: 127.0.0.1
        port: 3306
        user: root
        database: legacy
    maxRows: 1000                     # 查询返回行数上限（1-10000）
    queryTimeoutMs: 60000             # 单次查询超时（默认 60 秒，5 秒 - 10 分钟；SQLite 为同步本地执行，不适用）
    execTimeoutMs: 120000             # 单次写操作超时（默认 120 秒，5 秒 - 10 分钟；SQLite 同上）
    readOnly: false                   # true 时禁用 sql_exec
    writeApproval: true               # 写操作先弹审批（默认 true）

超时说明：MySQL / PostgreSQL 在适配器层硬性执行超时（连接 10 秒、查询/写操作按配置钳制）； SQLite 走 Node 内置同步 API，无法中断执行中的语句，超时配置不生效（本地文件查询通常毫秒级返回）。

工具一览

工具	作用	安全
sql_list	列出连接 + 连通性测试	—
sql_query	只读查询（SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH；可选 limit 行数上限）	关键字白名单 + 拒绝多语句 + 自动 LIMIT 下推
sql_exec	写操作/DDL（可多语句脚本）	readOnly 禁用 + 审批门
sql_schema	表清单 / 表结构（列 + 索引 + 外键）	标识符白名单校验
sql_stats	库概览：表数/行数/库体积	只读系统表
sql_health	自检：连通性 + 安全配置汇总	—

示例

sql_list {}
sql_schema {}                                  # 列出所有表
sql_schema { table: users }                    # 看 users 表结构（列 + 索引 + 外键）
sql_stats {}                                   # 库概览（表数/行数/体积）
sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
sql_query { sql: SELECT * FROM orders, limit: 20 }   # 只取 20 行
sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
sql_health {}                                  # 连接与安全配置自检

安全设计

• 词法级只读保护：sql_query 先剥离字符串/注释再校验，拒绝 data-modifying CTE（WITH…DELETE/UPDATE）、SELECT INTO、FOR UPDATE/FOR SHARE、PRAGMA 赋值与多语句
• 写审批门：sql_exec 默认弹审批（对齐 dsh-email 的发信审批），headless 环境无审批通道时拒绝执行
• readOnly 模式：生产库可整体禁用写
• 流式行数钳制：SQLite 迭代器 / MySQL stream / PostgreSQL portal 都按 maxRows+1 停表，大查询不会全量载入内存，超量标记 truncated；SELECT/WITH 还会自动下推 LIMIT maxRows+1，大表不会全表过网
• 超时硬兜底：查询与写操作超时由适配器层强制执行（MySQL 流式查询到点 destroy 终止、PostgreSQL 原生 query_timeout、建连 10 秒超时），卡死的 SQL 不再无限挂起；SQLite 同步执行不受超时钳制
• 标识符校验：表名只允许字母/数字/下划线，杜绝 schema 注入
• 密钥不落配置：密码支持 DSH_SQL_PASSWORD_<连接名> 环境变量

引擎

• SQLite：Node 22.13+ 内置 node:sqlite，零依赖
• MySQL：mysql2 连接池
• PostgreSQL：pg 连接池

开发

pnpm install
pnpm test       # 构建 + 49 个测试（含真实 SQLite 集成与流式挂起/超时回归）

License

MIT