dsh-sql 0.1.0

package/README.en.md

@@ -0,0 +1,88 @@
+[中文](README.md)
+
+# dsh-sql
+
+> **Your agent can query databases now**: SQLite / MySQL / PostgreSQL engines, read-only whitelist + write approval gate.
+
+DSH (DeepSeek Harness) engineer-grade database plugin: four tools covering connection management, read-only queries, write operations, and schema introspection.
+
+![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)
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-sql
+```
+
+## Configuration
+
+```yaml
+- id: sql
+  name: 'dsh-sql'
+  config:
+    connections:
+      - name: local
+        engine: sqlite
+        file: E:\data\app.db          # or :memory:
+      - name: prod
+        engine: postgres
+        host: db.internal
+        database: app
+        # password: xxx              # prefer env var DSH_SQL_PASSWORD_PROD
+      - name: legacy
+        engine: mysql
+        host: 127.0.0.1
+        port: 3306
+        user: root
+        database: legacy
+    maxRows: 1000                     # query row cap (1-10000)
+    readOnly: false                   # true disables sql_exec
+    writeApproval: true               # approve write operations first (default true)
+```
+
+## Tools
+
+| Tool | Purpose | Safety |
+| :-- | :-- | :-- |
+| `sql_list` | List connections + connectivity test | — |
+| `sql_query` | Read-only queries (SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH) | Keyword whitelist + rejects multi-statement |
+| `sql_exec` | Writes / DDL (multi-statement scripts allowed) | readOnly lock + approval gate |
+| `sql_schema` | Table list / table structure | Identifier whitelist validation |
+
+### Examples
+
+```text
+sql_list {}
+sql_schema {}                                  # list all tables
+sql_schema { table: users }                    # inspect the users table
+sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
+sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
+```
+
+## Safety
+
+- **Read-only whitelist**: sql_query only allows SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH; multi-statement queries are rejected outright
+- **Write approval gate**: sql_exec asks for approval by default (mirroring dsh-email's send approval); headless environments without an approval channel are denied
+- **readOnly mode**: lock out writes entirely for production databases
+- **Row clamping**: maxRows capped at 10000, overflow flagged with truncated
+- **Identifier validation**: table names restricted to alphanumerics and underscores — no schema injection
+- **Secrets stay out of config**: passwords via `DSH_SQL_PASSWORD_<CONNECTION>` env vars
+
+## Engines
+
+- **SQLite**: built-in `node:sqlite` (Node 22.13+), zero dependencies
+- **MySQL**: mysql2 pool
+- **PostgreSQL**: pg pool
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # build + 27 tests, including a real SQLite integration suite
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,88 @@
+[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)
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-sql
+```
+
+## 配置
+
+```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）
+    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 只放行 SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH，多语句直接拒绝
+- **写审批门**：sql_exec 默认弹审批（对齐 dsh-email 的发信审批），headless 环境无审批通道时拒绝执行
+- **readOnly 模式**：生产库可整体禁用写
+- **行数钳制**：maxRows 上限 10000，超量截断并标记 truncated
+- **标识符校验**：表名只允许字母/数字/下划线，杜绝 schema 注入
+- **密钥不落配置**：密码支持 `DSH_SQL_PASSWORD_<连接名>` 环境变量
+
+## 引擎
+
+- **SQLite**：Node 22.13+ 内置 `node:sqlite`，零依赖
+- **MySQL**：mysql2 连接池
+- **PostgreSQL**：pg 连接池
+
+## 开发
+
+```bash
+pnpm install
+pnpm test       # 构建 + 27 个测试（含真实 SQLite 集成）
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-sql 组合包补丁：把数据库工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载，默认注册一个
+# 内存 SQLite 连接（sql_list 可见）。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: sql
+#     name: 'dsh-sql'
+#     config:
+#       connections:
+#         - name: local
+#           engine: sqlite
+#           file: E:\data\app.db
+#       maxRows: 1000      # sql_query 返回行数上限（1-10000，默认 1000）
+#       readOnly: false    # true 时 sql_exec 被禁用
+#       writeApproval: true # 写操作先弹审批（默认 true）
+#
+- insert:
+    - id: sql
+      name: 'dsh-sql'
+      config:
+        maxRows: 1000

package/lib/adapters.d.ts

@@ -0,0 +1,25 @@
+import { type SqlConnectionConfig } from './config.js';
+/** 查询结果：列名 + 行（值数组，损失 JSON 友好）。 */
+export interface QueryResult {
+    columns: string[];
+    rows: unknown[][];
+}
+/** 表列信息。 */
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    notNull: boolean;
+    primaryKey: boolean;
+}
+/** 统一适配器接口。 */
+export interface DatabaseAdapter {
+    engine: 'sqlite' | 'mysql' | 'postgres';
+    listTables(): Promise<string[]>;
+    describeTable(table: string): Promise<ColumnInfo[]>;
+    query(sql: string): Promise<QueryResult>;
+    exec(sql: string): Promise<number>;
+    ping(): Promise<void>;
+    close(): Promise<void>;
+}
+/** 按连接配置创建适配器。 */
+export declare function createAdapter(connection: SqlConnectionConfig): DatabaseAdapter;

package/lib/adapters.js

@@ -0,0 +1,167 @@
+/**
+ * 数据库适配器层：sqlite（node:sqlite 内置）/ mysql（mysql2）/ postgres（pg）三实现。
+ * 统一接口：listTables / describeTable / query / exec / ping / close。
+ *
+ * @module dsh-sql/adapters
+ */
+import { DatabaseSync } from 'node:sqlite';
+import mysql from 'mysql2/promise';
+import pg from 'pg';
+import { assertIdentifier } from './config.js';
+function toValue(value) {
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Uint8Array)
+        return Array.from(value);
+    if (value instanceof Map)
+        return Object.fromEntries(value);
+    return value;
+}
+function rowsToColumns(rows) {
+    const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+    const values = rows.map((row) => columns.map((column) => toValue(row[column])));
+    return { columns, rows: values };
+}
+function quoteSqliteIdentifier(name) {
+    return '"' + name.replace(/"/g, '""') + '"';
+}
+/** SQLite 适配器（node:sqlite，零依赖）。 */
+class SqliteAdapter {
+    engine = 'sqlite';
+    db;
+    constructor(file) {
+        this.db = new DatabaseSync(file === ':memory:' ? ':memory:' : file);
+        this.db.exec('PRAGMA busy_timeout = 5000');
+    }
+    async listTables() {
+        const result = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all();
+        return result.map((row) => String(row.name));
+    }
+    async describeTable(table) {
+        const name = assertIdentifier(table, '表名');
+        const rows = this.db.prepare('PRAGMA table_info(' + quoteSqliteIdentifier(name) + ')').all();
+        return rows.map((row) => ({
+            name: String(row.name),
+            type: String(row.type ?? ''),
+            notNull: Number(row.notnull) === 1,
+            primaryKey: Number(row.pk) === 1,
+        }));
+    }
+    async query(sql) {
+        const rows = this.db.prepare(sql).all();
+        return rowsToColumns(rows);
+    }
+    async exec(sql) {
+        const single = sql.replace(/;\s*$/, '').trim();
+        if (single.includes(';')) {
+            this.db.exec(sql);
+            return 0;
+        }
+        const result = this.db.prepare(single).run();
+        return Number(result.changes);
+    }
+    async ping() {
+        this.db.prepare('SELECT 1').get();
+    }
+    async close() {
+        this.db.close();
+    }
+}
+/** MySQL 适配器（mysql2 连接池）。 */
+class MysqlAdapter {
+    engine = 'mysql';
+    pool;
+    constructor(connection) {
+        this.pool = mysql.createPool({
+            host: connection.host ?? 'localhost',
+            port: connection.port ?? 3306,
+            user: connection.user ?? '',
+            password: connection.password ?? '',
+            database: connection.database ?? '',
+            connectionLimit: 5,
+            enableKeepAlive: true,
+        });
+    }
+    async listTables() {
+        const [rows] = await this.pool.query('SHOW TABLES');
+        return rows.map((row) => String(Object.values(row)[0] ?? ''));
+    }
+    async describeTable(table) {
+        const name = assertIdentifier(table, '表名');
+        const [rows] = await this.pool.query('DESCRIBE `' + name + '`');
+        return rows.map((row) => ({
+            name: String(row.Field),
+            type: String(row.Type ?? ''),
+            notNull: String(row.Null ?? '').toUpperCase() === 'NO',
+            primaryKey: String(row.Key ?? '').toUpperCase() === 'PRI',
+        }));
+    }
+    async query(sql) {
+        const [rows] = await this.pool.query(sql);
+        return rowsToColumns(rows);
+    }
+    async exec(sql) {
+        const [result] = await this.pool.query(sql);
+        return Number(result?.affectedRows ?? 0);
+    }
+    async ping() {
+        await this.pool.query('SELECT 1');
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+/** PostgreSQL 适配器（pg 连接池）。 */
+class PostgresAdapter {
+    engine = 'postgres';
+    pool;
+    constructor(connection) {
+        this.pool = new pg.Pool({
+            host: connection.host ?? 'localhost',
+            port: connection.port ?? 5432,
+            user: connection.user ?? '',
+            password: connection.password ?? '',
+            database: connection.database ?? '',
+            max: 5,
+        });
+    }
+    async listTables() {
+        const result = await this.pool.query("SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name");
+        return result.rows.map((row) => String(row.table_name));
+    }
+    async describeTable(table) {
+        const name = assertIdentifier(table, '表名');
+        const result = await this.pool.query('SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = $1 ORDER BY ordinal_position', [name]);
+        return result.rows.map((row) => ({
+            name: String(row.column_name),
+            type: String(row.data_type ?? ''),
+            notNull: String(row.is_nullable) === 'NO',
+            primaryKey: false,
+        }));
+    }
+    async query(sql) {
+        const result = await this.pool.query(sql);
+        const rows = result.rows;
+        return rowsToColumns(rows);
+    }
+    async exec(sql) {
+        const result = await this.pool.query(sql);
+        return Number(result.rowCount ?? 0);
+    }
+    async ping() {
+        await this.pool.query('SELECT 1');
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+/** 按连接配置创建适配器。 */
+export function createAdapter(connection) {
+    if (connection.engine === 'sqlite')
+        return new SqliteAdapter(connection.file ?? ':memory:');
+    if (connection.engine === 'mysql')
+        return new MysqlAdapter(connection);
+    return new PostgresAdapter(connection);
+}

package/lib/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-sql 配置解析：多连接定义、行数上限、只读模式与写审批策略。
+ *
+ * @module dsh-sql/config
+ */
+/** 单个数据库连接（行配置）。 */
+export interface SqlConnectionConfig {
+    name: string;
+    engine: 'sqlite' | 'mysql' | 'postgres';
+    file?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+/** 插件行配置。 */
+export interface SqlConfig {
+    connections?: SqlConnectionConfig[];
+    maxRows?: number;
+    readOnly?: boolean;
+    writeApproval?: boolean;
+}
+/** 解析后的配置。 */
+export interface ResolvedSqlConfig {
+    connections: SqlConnectionConfig[];
+    maxRows: number;
+    readOnly: boolean;
+    writeApproval: boolean;
+}
+/** 连接密码环境变量名：DSH_SQL_PASSWORD_<NAME 大写>。 */
+export declare function passwordEnvName(name: string): string;
+/**
+ * 解析并校验配置；无连接时给一个内存 SQLite 兜底连接。
+ */
+export declare function resolveConfig(config: SqlConfig | undefined | null, env?: NodeJS.ProcessEnv): ResolvedSqlConfig;
+/** 校验表名/标识符，防注入到 schema 语句。 */
+export declare function assertIdentifier(name: string, label: string): string;

package/lib/config.js

@@ -0,0 +1,67 @@
+/**
+ * dsh-sql 配置解析：多连接定义、行数上限、只读模式与写审批策略。
+ *
+ * @module dsh-sql/config
+ */
+const ENGINES = ['sqlite', 'mysql', 'postgres'];
+/** 连接密码环境变量名：DSH_SQL_PASSWORD_<NAME 大写>。 */
+export function passwordEnvName(name) {
+    return 'DSH_SQL_PASSWORD_' + name.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+}
+/**
+ * 解析并校验配置；无连接时给一个内存 SQLite 兜底连接。
+ */
+export function resolveConfig(config, env = process.env) {
+    const cfg = config ?? {};
+    const rawConnections = Array.isArray(cfg.connections) ? cfg.connections : [];
+    const connections = [];
+    const seen = new Set();
+    for (const raw of rawConnections) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+        if (name === '')
+            throw new Error('connections 里每个连接都需要 name 字段。');
+        if (seen.has(name.toLowerCase()))
+            throw new Error('连接名重复：' + name + '。');
+        seen.add(name.toLowerCase());
+        const engine = raw.engine;
+        if (!ENGINES.includes(engine))
+            throw new Error('连接 ' + name + ' 的 engine 必须是 sqlite / mysql / postgres 之一。');
+        const connection = { name, engine: engine };
+        if (connection.engine === 'sqlite') {
+            connection.file = typeof raw.file === 'string' && raw.file.trim() !== '' ? raw.file.trim() : ':memory:';
+        }
+        else {
+            connection.host = typeof raw.host === 'string' && raw.host.trim() !== '' ? raw.host.trim() : 'localhost';
+            connection.port = typeof raw.port === 'number' && Number.isInteger(raw.port) && raw.port > 0 ? raw.port : (connection.engine === 'postgres' ? 5432 : 3306);
+            connection.user = typeof raw.user === 'string' && raw.user.trim() !== '' ? raw.user.trim() : '';
+            connection.database = typeof raw.database === 'string' && raw.database.trim() !== '' ? raw.database.trim() : '';
+            const direct = typeof raw.password === 'string' ? raw.password.trim() : '';
+            connection.password = direct !== '' ? direct : (env[passwordEnvName(name)]?.trim() ?? '');
+            if (connection.database === '')
+                throw new Error('连接 ' + name + ' 缺少 database 字段。');
+        }
+        connections.push(connection);
+    }
+    if (connections.length === 0) {
+        connections.push({ name: 'default', engine: 'sqlite', file: ':memory:' });
+    }
+    let maxRows = 1000;
+    if (cfg.maxRows !== undefined) {
+        if (typeof cfg.maxRows !== 'number' || !Number.isInteger(cfg.maxRows) || cfg.maxRows <= 0)
+            throw new Error('maxRows 必须是大于 0 的整数。');
+        maxRows = Math.min(10000, cfg.maxRows);
+    }
+    const readOnly = cfg.readOnly === true;
+    const writeApproval = cfg.writeApproval !== false;
+    return { connections, maxRows, readOnly, writeApproval };
+}
+/** 校验表名/标识符，防注入到 schema 语句。 */
+export function assertIdentifier(name, label) {
+    const trimmed = name.trim();
+    if (!/^[A-Za-z0-9_$]+$/.test(trimmed)) {
+        throw new Error(label + ' 非法（只允许字母/数字/下划线/美元符）：' + name);
+    }
+    return trimmed;
+}

package/lib/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * dsh-sql —— 工程师级数据库工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册四个面向模型的工具（sql_list / sql_query /
+ * sql_exec / sql_schema），支持 SQLite / MySQL / PostgreSQL 三引擎与多连接。
+ * sql_exec 默认走宿主审批门（对齐 dsh-email 的发信审批），readOnly 模式可整体禁用写。
+ *
+ * @module dsh-sql
+ */
+import { type SqlConfig } from './config.js';
+import { type SqlToolDefinition } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export declare const inject: string[];
+/** 审批服务最小面（对齐 dsh-email）。 */
+export interface SqlApproval {
+    request(options: {
+        agent?: unknown;
+        toolName?: unknown;
+        callId?: unknown;
+        reason: string;
+        signal?: unknown;
+    }): Promise<'allowed-once' | 'cancelled' | 'unavailable' | string>;
+}
+/** 插件所需的最小 ctx 面。 */
+export interface SqlPluginContext {
+    tools: {
+        register(definition: SqlToolDefinition, options?: {
+            prepend?: boolean;
+        }): () => void;
+    };
+    get?(name: 'approval'): SqlApproval | undefined;
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置、构建四工具、给 sql_exec 注入审批门。
+ */
+export declare function apply(ctx: SqlPluginContext, config?: SqlConfig | null): void;
+export * from './adapters.js';
+export * from './config.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,74 @@
+/**
+ * dsh-sql —— 工程师级数据库工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册四个面向模型的工具（sql_list / sql_query /
+ * sql_exec / sql_schema），支持 SQLite / MySQL / PostgreSQL 三引擎与多连接。
+ * sql_exec 默认走宿主审批门（对齐 dsh-email 的发信审批），readOnly 模式可整体禁用写。
+ *
+ * @module dsh-sql
+ */
+import { resolveConfig } from './config.js';
+import { buildSqlTools } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export const inject = ['tools'];
+/**
+ * 插件入口：解析配置、构建四工具、给 sql_exec 注入审批门。
+ */
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-sql] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const { tools, adapters } = buildSqlTools(cfg);
+    const disposers = [];
+    for (const definition of tools) {
+        if (definition.name === 'sql_exec' && cfg.writeApproval) {
+            const originalGate = definition.gate;
+            definition.gate = async (exec, next) => {
+                const approval = ctx.get?.('approval');
+                if (approval === undefined) {
+                    return {
+                        kind: 'deny',
+                        reason: 'sql_exec 需要确认，但当前环境没有审批通道（如 headless）。如确定安全，可在配置中设置 writeApproval: false 后直接执行。',
+                    };
+                }
+                const execRecord = (typeof exec === 'object' && exec !== null ? exec : {});
+                const args = (typeof execRecord.args === 'object' && execRecord.args !== null ? execRecord.args : {});
+                const sql = typeof args.sql === 'string' ? args.sql : '';
+                const outcome = await approval.request({
+                    agent: execRecord.agent,
+                    toolName: execRecord.name,
+                    callId: execRecord.callId,
+                    reason: '执行数据库写操作：' + sql.slice(0, 200) + (sql.length > 200 ? '…' : ''),
+                    signal: execRecord.signal,
+                });
+                if (outcome === 'allowed-once')
+                    return originalGate ? originalGate(exec, next) : next();
+                if (outcome === 'cancelled')
+                    return { kind: 'deny', reason: '写操作确认被取消，SQL 未执行。' };
+                if (outcome === 'unavailable')
+                    return { kind: 'deny', reason: '写操作确认不可用（没有可用的审批界面），SQL 未执行。' };
+                return {
+                    kind: 'deny',
+                    reason: '写操作未获批准：要么你拒绝了，要么当前会话处于 Full Access（审批策略 never，不会弹框）。若在 Full Access：切到 Read Only / Write 再执行，或关闭 writeApproval（自行承担风险）。',
+                };
+            };
+        }
+        disposers.push(ctx.tools.register(definition, { prepend: true }));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+            for (const adapter of adapters.values())
+                void adapter.close();
+        });
+    }
+}
+export * from './adapters.js';
+export * from './config.js';
+export * from './tools.js';

package/lib/tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 四个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema。
+ *
+ * @module dsh-sql/tools
+ */
+import { type DatabaseAdapter } from './adapters.js';
+import { type ResolvedSqlConfig } from './config.js';
+/** 模型可见的内容块。 */
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+/** 注册给 ctx.tools.register 的原始工具定义。 */
+export interface SqlToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    gate?(exec: unknown, next: () => Promise<unknown>): Promise<unknown>;
+    timeoutMs?: number;
+}
+/** 审批执行上下文的最小面。 */
+export interface SqlExecGateContext {
+    agent?: unknown;
+    name?: unknown;
+    callId?: unknown;
+    signal?: unknown;
+}
+/** 构建四个工具定义；adapters 惰性创建并按连接名缓存。 */
+export declare function buildSqlTools(config: ResolvedSqlConfig): {
+    tools: SqlToolDefinition[];
+    adapters: Map<string, DatabaseAdapter>;
+};

package/lib/tools.js

@@ -0,0 +1,265 @@
+/**
+ * 四个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema。
+ *
+ * @module dsh-sql/tools
+ */
+import { createAdapter } from './adapters.js';
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+/** 只读语句关键字白名单。 */
+const READ_KEYWORDS = /^(select|pragma|explain|show|describe|desc|with)\b/i;
+/** 校验只读查询：白名单开头 + 拒绝多语句。 */
+function assertReadQuery(sql) {
+    const trimmed = sql.trim();
+    if (!READ_KEYWORDS.test(trimmed)) {
+        throw new Error('sql_query 只接受只读语句（SELECT / PRAGMA / EXPLAIN / SHOW / DESCRIBE / WITH）。写操作请用 sql_exec。');
+    }
+    const statements = trimmed.split(';').filter((part) => part.trim() !== '');
+    if (statements.length > 1)
+        throw new Error('sql_query 一次只允许一条语句。');
+    return statements[0].trim();
+}
+const querySchema = {
+    type: 'object',
+    properties: {
+        connection: { type: 'string' },
+        columns: { type: 'array', items: { type: 'string' } },
+        rows: { type: 'array', items: { type: 'array', items: {} } },
+        rowCount: { type: 'integer' },
+        truncated: { type: 'boolean' },
+        maxRows: { type: 'integer' },
+    },
+    additionalProperties: true,
+};
+const execSchema = {
+    type: 'object',
+    properties: {
+        connection: { type: 'string' },
+        changes: { type: 'integer' },
+        readOnly: { type: 'boolean' },
+    },
+    additionalProperties: true,
+};
+const listSchema = {
+    type: 'object',
+    properties: {
+        connections: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: { name: { type: 'string' }, engine: { type: 'string' }, host: { type: 'string' }, database: { type: 'string' }, file: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } },
+                additionalProperties: true,
+            },
+        },
+    },
+    additionalProperties: true,
+};
+const schemaToolSchema = {
+    type: 'object',
+    properties: {
+        connection: { type: 'string' },
+        tables: { type: 'array', items: { type: 'string' } },
+        columns: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: { name: { type: 'string' }, type: { type: 'string' }, notNull: { type: 'boolean' }, primaryKey: { type: 'boolean' } },
+                additionalProperties: true,
+            },
+        },
+    },
+    additionalProperties: true,
+};
+/** 构建四个工具定义；adapters 惰性创建并按连接名缓存。 */
+export function buildSqlTools(config) {
+    const cfg = config;
+    const adapters = new Map();
+    const getAdapter = (name) => {
+        const target = name ?? cfg.connections[0].name;
+        const connection = cfg.connections.find((item) => item.name.toLowerCase() === target.toLowerCase());
+        if (connection === undefined) {
+            throw new Error('未找到名为 ' + target + ' 的数据库连接。可用 sql_list 查看连接清单。');
+        }
+        let adapter = adapters.get(connection.name);
+        if (adapter === undefined) {
+            adapter = createAdapter(connection);
+            adapters.set(connection.name, adapter);
+        }
+        return { adapter, name: connection.name };
+    };
+    const sqlList = {
+        name: 'sql_list',
+        description: '列出配置的数据库连接并逐一做连通性测试（SELECT 1）。返回连接名、引擎、目标与健康状态。',
+        parameters: compileParameters({}),
+        output: {
+            schema: listSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const connections = Array.isArray(rec.connections) ? rec.connections : [];
+                const lines = ['共 ' + connections.length + ' 个数据库连接：'];
+                for (const item of connections) {
+                    const c = asRecord(item);
+                    const target = c.file !== undefined && c.file !== '' ? c.file : c.host + '/' + c.database;
+                    lines.push('- ' + c.name + '（' + c.engine + ' @ ' + target + '）' + (c.ok === true ? ' ✅' : ' ❌ ' + String(c.error ?? '')));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            const rows = [];
+            for (const connection of cfg.connections) {
+                const entry = { name: connection.name, engine: connection.engine };
+                if (connection.engine === 'sqlite')
+                    entry.file = connection.file ?? ':memory:';
+                else {
+                    entry.host = connection.host ?? '';
+                    entry.database = connection.database ?? '';
+                }
+                try {
+                    const { adapter } = getAdapter(connection.name);
+                    await adapter.ping();
+                    entry.ok = true;
+                    entry.error = '';
+                }
+                catch (error) {
+                    entry.ok = false;
+                    entry.error = error instanceof Error ? error.message : String(error);
+                }
+                rows.push(entry);
+            }
+            return { connections: rows };
+        },
+        timeoutMs: 30000,
+    };
+    const sqlQuery = {
+        name: 'sql_query',
+        description: '执行只读 SQL 查询（SELECT / PRAGMA / EXPLAIN / SHOW / DESCRIBE / WITH）。connection 为连接名（缺省第一个连接）。返回列名与行数据，最多 maxRows 行（超出 truncated=true）。写操作请用 sql_exec。',
+        parameters: compileParameters({
+            sql: { type: 'string', required: true, description: '只读 SQL 语句（必填，单条）。' },
+            connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
+        }),
+        output: {
+            schema: querySchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const rows = Array.isArray(rec.rows) ? rec.rows : [];
+                const lines = ['查询返回 ' + rec.rowCount + ' 行' + (rec.truncated === true ? '（截断到 ' + rec.maxRows + ' 行）' : '') + '，列：' + (Array.isArray(rec.columns) ? rec.columns.join(', ') : '')];
+                for (const row of rows.slice(0, 20)) {
+                    lines.push('- ' + (Array.isArray(row) ? row.map((cell) => String(cell)).join(' | ') : String(row)));
+                }
+                if (rows.length > 20)
+                    lines.push('…仅展示前 20 行');
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const sql = assertReadQuery(requiredString(args, 'sql', 'SQL 语句'));
+            const { adapter, name } = getAdapter(optionalString(args, 'connection'));
+            const result = await adapter.query(sql);
+            const total = result.rows.length;
+            const rows = result.rows.slice(0, cfg.maxRows);
+            return {
+                connection: name,
+                columns: result.columns,
+                rows,
+                rowCount: total,
+                truncated: total > cfg.maxRows,
+                maxRows: cfg.maxRows,
+            };
+        },
+        timeoutMs: 60000,
+    };
+    const sqlExec = {
+        name: 'sql_exec',
+        description: '执行写操作或 DDL（INSERT / UPDATE / DELETE / CREATE / ALTER / DROP 等，可多语句脚本）。受 readOnly 模式与写审批门双重保护。返回影响行数（多语句时为 0）。',
+        parameters: compileParameters({
+            sql: { type: 'string', required: true, description: '写操作/DDL SQL（必填）。' },
+            connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
+        }),
+        output: {
+            schema: execSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '执行完成（' + rec.connection + '）：影响 ' + rec.changes + ' 行。' }];
+            },
+        },
+        async execute(rawArgs) {
+            if (cfg.readOnly)
+                throw new Error('当前配置 readOnly=true，sql_exec 已被禁用。需要写操作请把插件配置里的 readOnly 改为 false 后重启。');
+            const args = asRecord(rawArgs);
+            const sql = requiredString(args, 'sql', 'SQL 语句');
+            const { adapter, name } = getAdapter(optionalString(args, 'connection'));
+            const changes = await adapter.exec(sql);
+            return { connection: name, changes, readOnly: false };
+        },
+        gate(exec, next) {
+            return next(); // 审批门由 index.ts 注入（需要宿主 ctx）
+        },
+        timeoutMs: 120000,
+    };
+    const sqlSchema = {
+        name: 'sql_schema',
+        description: '查看数据库结构：不给 table 列出全部表；给 table（表名）返回该表的列信息（名称/类型/非空/主键）。',
+        parameters: compileParameters({
+            table: { type: 'string', description: '表名（可选；缺省列出全部表）。' },
+            connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
+        }),
+        output: {
+            schema: schemaToolSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const columns = Array.isArray(rec.columns) ? rec.columns : [];
+                if (columns.length > 0) {
+                    const lines = ['表 ' + rec.table + ' 的列：'];
+                    for (const item of columns) {
+                        const c = asRecord(item);
+                        lines.push('- ' + c.name + ' ' + c.type + (c.primaryKey === true ? '（主键）' : '') + (c.notNull === true ? '（非空）' : ''));
+                    }
+                    return [{ type: 'text', text: lines.join('\n') }];
+                }
+                const tables = Array.isArray(rec.tables) ? rec.tables : [];
+                return [{ type: 'text', text: '共 ' + tables.length + ' 张表：' + tables.join(', ') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const { adapter, name } = getAdapter(optionalString(args, 'connection'));
+            const table = optionalString(args, 'table');
+            if (table !== undefined) {
+                const columns = await adapter.describeTable(table);
+                return { connection: name, table, columns, tables: [] };
+            }
+            const tables = await adapter.listTables();
+            return { connection: name, tables, columns: [] };
+        },
+        timeoutMs: 30000,
+    };
+    return { tools: [sqlList, sqlQuery, sqlExec, sqlSchema], adapters };
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "dsh-sql",
+  "version": "0.1.0",
+  "description": "DSH 工程师级数据库插件：sql_list/query/exec/schema 四工具，SQLite/MySQL/PostgreSQL 三引擎、多连接、只读模式与写操作审批门、行数钳制。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "sql",
+    "sqlite",
+    "mysql",
+    "postgresql",
+    "database"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "mysql2": "^3.11.0",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.21.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-sql.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-sql/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-sql#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}