dsh-sql

Readme

[English](README.en.md)

# dsh-sql

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

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

![npm version](https://img.shields.io/npm/v/dsh-sql?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-sql) ![license](https://img.shields.io/npm/l/dsh-sql) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-sql?style=social)

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

## 兼容性

在 `@deepseek-ai/dsh@0.1.2-alpha.4` 源码模式下验证（2026-09-02）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。

## 安装

```bash
dsh plugin --profile web add dsh-sql
```

## 卸载

```bash
dsh plugin --profile web remove dsh-sql
```

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


## 配置

```yaml
- id: sql
  name: '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 分钟）
    execTimeoutMs: 120000             # 单次写操作超时（默认 120 秒，5 秒 - 10 分钟）
    readOnly: false                   # true 时禁用 sql_exec
    writeApproval: true               # 写操作先弹审批（默认 true）
```

## 工具一览

| 工具 | 作用 | 安全 |
| :-- | :-- | :-- |
| `sql_list` | 列出连接 + 连通性测试 | — |
| `sql_query` | 只读查询（SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH）| 关键字白名单 + 拒绝多语句 |
| `sql_exec` | 写操作/DDL（可多语句脚本）| readOnly 禁用 + 审批门 |
| `sql_schema` | 表清单 / 表结构 | 标识符白名单校验 |

### 示例

```text
sql_list {}
sql_schema {}                                  # 列出所有表
sql_schema { table: users }                    # 看 users 表结构
sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
```

## 安全设计

- **词法级只读保护**：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
- **标识符校验**：表名只允许字母/数字/下划线，杜绝 schema 注入
- **密钥不落配置**：密码支持 `DSH_SQL_PASSWORD_<连接名>` 环境变量

## 引擎

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

## 开发

```bash
pnpm install
pnpm test       # 构建 + 35 个测试（含真实 SQLite 集成）
```

## License

MIT