dsh-sql 0.4.1 → 0.4.2

package/README.en.md

@@ -4,7 +4,7 @@
 
 > **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.
+DSH (DeepSeek Harness) engineer-grade database plugin: six tools covering connection management, read-only queries, write operations, schema introspection, database statistics, and health checks.
 
 ![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)
 
@@ -12,7 +12,7 @@ DSH (DeepSeek Harness) engineer-grade database plugin: four tools covering conne
 
 ## Compatibility
 
-Verified against source-run `@deepseek-ai/dsh@0.1.2-alpha.4` on 2026-09-02. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against the official `@deepseek-ai/dsh@0.1.2-rc.1` release and current source checkout on 2026-09-04. `0.1.2-alpha.5` remains supported because both releases use the same plugin/tool contract. Built for the cordis patch-bundle model (`cordis.patch.yml` + `dsh.bundle.patch`) with no runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -57,6 +57,8 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
     writeApproval: true               # approve write operations first (default true)
 ```
 
+With no connection configuration, the plugin provides a `:memory:` SQLite connection. If configuration is present but invalid, the plugin fails to load with the validation error instead of silently falling back to the in-memory database.
+
 ## Tools
 
 | Tool | Purpose | Safety |
@@ -65,6 +67,8 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 | `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 |
+| `sql_stats` | Table counts, row estimates, and database size | Quoted identifiers + isolated query failures |
+| `sql_health` | Connection and safety-configuration checks | Per-connection probe; passwords are never returned |
 
 ### Examples
 
@@ -72,6 +76,8 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 sql_list {}
 sql_schema {}                                  # list all tables
 sql_schema { table: users }                    # inspect the users table
+sql_stats {}                                   # inspect the default connection's data size
+sql_health {}                                  # check connections and safety settings
 sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
 sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 ```
@@ -81,7 +87,9 @@ sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 - **Lexer-grade read-only guard**: sql_query strips strings/comments before validation, then rejects data-modifying CTEs (WITH…DELETE/UPDATE), SELECT INTO, FOR UPDATE/FOR SHARE, PRAGMA assignment, and multi-statement input
 - **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
-- **Streaming row cap**: SQLite iterator / MySQL stream / PostgreSQL portal all stop at maxRows+1, so large queries are never fully materialized; overflow is flagged with truncated
+- **Streaming row cap**: SQLite iterators, MySQL Readables, and PostgreSQL Query row events collect at most maxRows+1 rows and flag overflow with truncated. MySQL and PostgreSQL close the query's dedicated connection at the cap; smaller results return the connection to the pool, without materializing the full result in memory
+- **Cancellation-aware execution**: queries and writes observe Harness `exec.signal`; cancellation stops waiting and destroys the active dedicated MySQL/PostgreSQL connection
+- **Lossless large integers**: bigint values within JavaScript's safe integer range are returned as numbers; larger values are returned as decimal strings instead of silently losing precision
 - **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
 
@@ -95,7 +103,7 @@ sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 
 ```bash
 pnpm install
-pnpm test       # build + 35 tests, including a real SQLite integration suite
+pnpm test       # build + full test suite, including a real SQLite integration suite
 ```
 
 ## License

package/README.md

@@ -4,7 +4,7 @@
 
 > **你的 agent 会查库了**：SQLite / MySQL / PostgreSQL 三引擎，只读白名单 + 写审批门。
 
-DSH（DeepSeek Harness）工程师级数据库插件：四个工具覆盖连接管理、只读查询、写操作与结构探查。
+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)
 
@@ -12,7 +12,7 @@ DSH（DeepSeek Harness）工程师级数据库插件：四个工具覆盖连接
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.2-alpha.4` 源码模式下验证（2026-09-02）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已在官方 `@deepseek-ai/dsh@0.1.2-rc.1` 与最新源码模式下验证（2026-09-04）；`0.1.2-alpha.5` 仍可使用，两版插件/工具契约一致。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -57,6 +57,8 @@ dsh plugin --profile web remove dsh-sql
     writeApproval: true               # 写操作先弹审批（默认 true）
 ```
 
+配置缺省时会提供一个 `:memory:` SQLite 连接；配置一旦给出但格式无效，插件会直接报错并停止加载，不会静默回退到内存库。
+
 ## 工具一览
 
 | 工具 | 作用 | 安全 |
@@ -65,6 +67,8 @@ dsh plugin --profile web remove dsh-sql
 | `sql_query` | 只读查询（SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH）| 关键字白名单 + 拒绝多语句 |
 | `sql_exec` | 写操作/DDL（可多语句脚本）| readOnly 禁用 + 审批门 |
 | `sql_schema` | 表清单 / 表结构 | 标识符白名单校验 |
+| `sql_stats` | 表数量、行数与库体积概览 | 表名引用 + 查询失败隔离 |
+| `sql_health` | 连接与安全配置自检 | 逐连接探活，不回显密码 |
 
 ### 示例
 
@@ -72,6 +76,8 @@ dsh plugin --profile web remove dsh-sql
 sql_list {}
 sql_schema {}                                  # 列出所有表
 sql_schema { table: users }                    # 看 users 表结构
+sql_stats {}                                   # 查看默认连接的数据规模
+sql_health {}                                  # 检查连接和安全配置
 sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
 sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 ```
@@ -81,7 +87,9 @@ 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
+- **流式行数钳制**：SQLite 迭代器 / MySQL Readable / PostgreSQL Query 行事件最多收集 maxRows+1 行，超量标记 truncated；MySQL 和 PostgreSQL 在达到上限时关闭该查询的专用连接，未达上限则正常归还连接池，避免全量结果驻留内存
+- **可取消执行**：查询与写操作遵守 Harness 的 `exec.signal`；取消时会中止等待并销毁正在工作的 MySQL/PostgreSQL 专用连接
+- **大整数无损**：数据库返回的 bigint 在 JavaScript 安全整数范围内输出 number，超出范围则输出十进制字符串，避免静默丢精度
 - **标识符校验**：表名只允许字母/数字/下划线，杜绝 schema 注入
 - **密钥不落配置**：密码支持 `DSH_SQL_PASSWORD_<连接名>` 环境变量
 
@@ -95,7 +103,7 @@ sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 35 个测试（含真实 SQLite 集成）
+pnpm test       # 构建 + 完整测试套件（含真实 SQLite 集成）
 ```
 
 ## License

package/lib/adapters.d.ts

@@ -1,5 +1,5 @@
 import { type SqlConnectionConfig } from './config.js';
-/** 查询结果：列名 + 行（值数组，损失 JSON 友好）。 */
+/** 查询结果：列名 + 行（值数组，无损 JSON 友好）。 */
 export interface QueryResult {
     columns: string[];
     rows: unknown[][];
@@ -14,11 +14,11 @@ export interface ColumnInfo {
 /** 统一适配器接口。 */
 export interface DatabaseAdapter {
     engine: 'sqlite' | 'mysql' | 'postgres';
-    listTables(): Promise<string[]>;
-    describeTable(table: string): Promise<ColumnInfo[]>;
-    query(sql: string, limit?: number): Promise<QueryResult>;
-    exec(sql: string): Promise<number>;
-    ping(): Promise<void>;
+    listTables(signal?: AbortSignal): Promise<string[]>;
+    describeTable(table: string, signal?: AbortSignal): Promise<ColumnInfo[]>;
+    query(sql: string, limit?: number, signal?: AbortSignal): Promise<QueryResult>;
+    exec(sql: string, signal?: AbortSignal): Promise<number>;
+    ping(signal?: AbortSignal): Promise<void>;
     close(): Promise<void>;
 }
 /** 按连接配置创建适配器。 */

package/lib/adapters.js

@@ -8,9 +8,20 @@ import { DatabaseSync } from 'node:sqlite';
 import mysql from 'mysql2/promise';
 import pg from 'pg';
 import { assertIdentifier } from './config.js';
+function abortReason(signal) {
+    if (signal.reason !== undefined)
+        return signal.reason;
+    const error = new Error('The operation was aborted.');
+    error.name = 'AbortError';
+    return error;
+}
 function toValue(value) {
-    if (typeof value === 'bigint')
-        return Number(value);
+    if (typeof value === 'bigint') {
+        if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+            return Number(value);
+        }
+        return value.toString();
+    }
     if (value instanceof Date)
         return value.toISOString();
     if (value instanceof Uint8Array)
@@ -27,6 +38,84 @@ function rowsToColumns(rows) {
 function quoteSqliteIdentifier(name) {
     return '"' + name.replace(/"/g, '""') + '"';
 }
+function streamMysqlQuery(corePool, sql, limit, discard) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let columns = [];
+        const rows = [];
+        const stream = corePool.query(sql).stream({ highWaterMark: 64 });
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ columns, rows });
+        };
+        stream.on('fields', (fields) => {
+            columns = fields.map((field) => field.name);
+        });
+        // Consume the Readable, otherwise mysql2 pauses forever at highWaterMark.
+        stream.on('data', (row) => {
+            if (settled)
+                return;
+            if (columns.length === 0)
+                columns = Object.keys(row);
+            rows.push(columns.map((name) => toValue(row[name])));
+            if (rows.length >= limit) {
+                finish();
+                stream.destroy();
+                // mysql2 resumes its connection when only the Readable is destroyed.
+                discard();
+            }
+        });
+        stream.on('end', finish);
+        stream.on('close', finish);
+        stream.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/** pg's `rows` option is a page size; row events avoid its full result accumulator. */
+function streamPostgresQuery(client, sql, limit, discard) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let columns = [];
+        const rows = [];
+        const query = new pg.Query(sql);
+        query.on('row', (row, result) => {
+            if (settled)
+                return;
+            if (columns.length === 0)
+                columns = result?.fields.map((field) => field.name) ?? Object.keys(row);
+            rows.push(columns.map((name) => toValue(row[name])));
+            if (rows.length >= limit) {
+                // Closing this dedicated connection stops server work and prevents reuse.
+                settled = true;
+                discard();
+                resolve({ columns, rows });
+            }
+        });
+        query.on('end', (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (columns.length === 0)
+                columns = result.fields.map((field) => field.name);
+            resolve({ columns, rows });
+        });
+        // Keep this listener after reaching the cap: destroying the client can emit
+        // the driver's asynchronous connection-closed error on this active query.
+        query.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+        client.query(query);
+    });
+}
 /** SQLite 适配器（node:sqlite，零依赖）。 */
 class SqliteAdapter {
     engine = 'sqlite';
@@ -35,13 +124,17 @@ class SqliteAdapter {
         this.db = new DatabaseSync(file === ':memory:' ? ':memory:' : file);
         this.db.exec('PRAGMA busy_timeout = 5000');
     }
-    async listTables() {
+    async listTables(signal) {
+        signal?.throwIfAborted();
         const result = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all();
+        signal?.throwIfAborted();
         return result.map((row) => String(row.name));
     }
-    async describeTable(table) {
+    async describeTable(table, signal) {
+        signal?.throwIfAborted();
         const name = assertIdentifier(table, '表名');
         const rows = this.db.prepare('PRAGMA table_info(' + quoteSqliteIdentifier(name) + ')').all();
+        signal?.throwIfAborted();
         return rows.map((row) => ({
             name: String(row.name),
             type: String(row.type ?? ''),
@@ -49,10 +142,12 @@ class SqliteAdapter {
             primaryKey: Number(row.pk) === 1,
         }));
     }
-    async query(sql, limit) {
+    async query(sql, limit, signal) {
+        signal?.throwIfAborted();
         const statement = this.db.prepare(sql);
         if (limit === undefined || limit <= 0) {
             const rows = statement.all();
+            signal?.throwIfAborted();
             return rowsToColumns(rows);
         }
         const columns = statement.columns().map((column) => column.name);
@@ -60,22 +155,28 @@ class SqliteAdapter {
         for (const raw of statement.iterate()) {
             const row = raw;
             rows.push(columns.map((name) => toValue(row[name])));
+            signal?.throwIfAborted();
             if (rows.length >= limit)
                 break;
         }
         return { columns, rows };
     }
-    async exec(sql) {
+    async exec(sql, signal) {
+        signal?.throwIfAborted();
         const single = sql.replace(/;\s*$/, '').trim();
         if (single.includes(';')) {
             this.db.exec(sql);
+            signal?.throwIfAborted();
             return 0;
         }
         const result = this.db.prepare(single).run();
+        signal?.throwIfAborted();
         return Number(result.changes);
     }
-    async ping() {
+    async ping(signal) {
+        signal?.throwIfAborted();
         this.db.prepare('SELECT 1').get();
+        signal?.throwIfAborted();
     }
     async close() {
         this.db.close();
@@ -96,13 +197,45 @@ class MysqlAdapter {
             enableKeepAlive: true,
         });
     }
-    async listTables() {
-        const [rows] = await this.pool.query('SHOW TABLES');
+    async withSignalConnection(signal, work) {
+        signal?.throwIfAborted();
+        const connection = await this.pool.getConnection();
+        let destroyed = false;
+        let rejectAbort = () => { };
+        const aborted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+        const discard = () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            connection.destroy();
+        };
+        const onAbort = () => {
+            discard();
+            rejectAbort(abortReason(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            signal?.throwIfAborted();
+            return await Promise.race([work(connection, discard), aborted]);
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            if (!destroyed)
+                connection.release();
+        }
+    }
+    async queryRows(sql, signal) {
+        if (signal === undefined)
+            return await this.pool.query(sql);
+        return await this.withSignalConnection(signal, async (connection) => await connection.query(sql));
+    }
+    async listTables(signal) {
+        const [rows] = await this.queryRows('SHOW TABLES', signal);
         return rows.map((row) => String(Object.values(row)[0] ?? ''));
     }
-    async describeTable(table) {
+    async describeTable(table, signal) {
         const name = assertIdentifier(table, '表名');
-        const [rows] = await this.pool.query('DESCRIBE `' + name + '`');
+        const [rows] = await this.queryRows('DESCRIBE `' + name + '`', signal);
         return rows.map((row) => ({
             name: String(row.Field),
             type: String(row.Type ?? ''),
@@ -110,49 +243,22 @@ class MysqlAdapter {
             primaryKey: String(row.Key ?? '').toUpperCase() === 'PRI',
         }));
     }
-    async query(sql, limit) {
+    async query(sql, limit, signal) {
         if (limit === undefined || limit <= 0) {
-            const [rows] = await this.pool.query(sql);
+            const [rows] = await this.queryRows(sql, signal);
             return rowsToColumns(rows);
         }
-        const corePool = this.pool.pool;
-        return await new Promise((resolve, reject) => {
-            let settled = false;
-            let columns = [];
-            const rows = [];
-            const stream = corePool.query(sql).stream({ highWaterMark: 64 });
-            const finish = () => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve({ columns, rows });
-            };
-            stream.on('fields', (fields) => {
-                columns = fields.map((field) => field.name);
-            });
-            stream.on('result', (row) => {
-                if (columns.length === 0)
-                    columns = Object.keys(row);
-                rows.push(columns.map((name) => toValue(row[name])));
-                if (rows.length >= limit)
-                    stream.destroy();
-            });
-            stream.on('end', finish);
-            stream.on('close', finish);
-            stream.on('error', (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                reject(error instanceof Error ? error : new Error(String(error)));
-            });
+        return await this.withSignalConnection(signal, async (connection, discard) => {
+            const coreConnection = connection.connection;
+            return await streamMysqlQuery(coreConnection, sql, limit, discard);
         });
     }
-    async exec(sql) {
-        const [result] = await this.pool.query(sql);
+    async exec(sql, signal) {
+        const [result] = await this.queryRows(sql, signal);
         return Number(result?.affectedRows ?? 0);
     }
-    async ping() {
-        await this.pool.query('SELECT 1');
+    async ping(signal) {
+        await this.queryRows('SELECT 1', signal);
     }
     async close() {
         await this.pool.end();
@@ -172,13 +278,48 @@ class PostgresAdapter {
             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");
+    async withSignalClient(signal, work) {
+        signal?.throwIfAborted();
+        const client = await this.pool.connect();
+        let destroyed = false;
+        let rejectAbort = () => { };
+        const aborted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+        const discard = () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            client.release(true);
+        };
+        const onAbort = () => {
+            discard();
+            rejectAbort(abortReason(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            signal?.throwIfAborted();
+            return await Promise.race([work(client, discard), aborted]);
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            if (!destroyed)
+                client.release();
+        }
+    }
+    async queryWithSignal(query, values, signal) {
+        const run = async (client) => {
+            return values === undefined ? await client.query(query) : await client.query(query, values);
+        };
+        if (signal === undefined)
+            return await run(this.pool);
+        return await this.withSignalClient(signal, run);
+    }
+    async listTables(signal) {
+        const result = await this.queryWithSignal("SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name", undefined, signal);
         return result.rows.map((row) => String(row.table_name));
     }
-    async describeTable(table) {
+    async describeTable(table, signal) {
         const name = assertIdentifier(table, '表名');
-        const result = await this.pool.query(`SELECT c.column_name, c.data_type, c.is_nullable,
+        const result = await this.queryWithSignal(`SELECT c.column_name, c.data_type, c.is_nullable,
               EXISTS (
                 SELECT 1
                 FROM information_schema.table_constraints tc
@@ -193,7 +334,7 @@ class PostgresAdapter {
          FROM information_schema.columns c
         WHERE c.table_schema = 'public'
           AND c.table_name = $1
-        ORDER BY c.ordinal_position`, [name]);
+        ORDER BY c.ordinal_position`, [name], signal);
         return result.rows.map((row) => ({
             name: String(row.column_name),
             type: String(row.data_type ?? ''),
@@ -201,22 +342,22 @@ class PostgresAdapter {
             primaryKey: row.is_primary === true,
         }));
     }
-    async query(sql, limit) {
+    async query(sql, limit, signal) {
         if (limit === undefined || limit <= 0) {
-            const result = await this.pool.query(sql);
+            const result = await this.queryWithSignal(sql, undefined, signal);
             const rows = result.rows;
             return rowsToColumns(rows);
         }
-        const result = await this.pool.query({ text: sql, values: [], rows: limit });
-        const rows = result.rows;
-        return rowsToColumns(rows);
+        return await this.withSignalClient(signal, async (client, discard) => {
+            return await streamPostgresQuery(client, sql, limit, discard);
+        });
     }
-    async exec(sql) {
-        const result = await this.pool.query(sql);
+    async exec(sql, signal) {
+        const result = await this.queryWithSignal(sql, undefined, signal);
         return Number(result.rowCount ?? 0);
     }
-    async ping() {
-        await this.pool.query('SELECT 1');
+    async ping(signal) {
+        await this.queryWithSignal('SELECT 1', undefined, signal);
     }
     async close() {
         await this.pool.end();

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * dsh-sql —— 工程师级数据库工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册四个面向模型的工具（sql_list / sql_query /
- * sql_exec / sql_schema），支持 SQLite / MySQL / PostgreSQL 三引擎与多连接。
+ * 插件导出 apply(ctx, config)：注册六个面向模型的工具（sql_list / sql_query /
+ * sql_exec / sql_schema / sql_stats / sql_health），支持 SQLite / MySQL / PostgreSQL
+ * 三引擎与多连接。
  * sql_exec 默认走宿主审批门（对齐 dsh-email 的发信审批），readOnly 模式可整体禁用写。
  *
  * @module dsh-sql
@@ -22,7 +23,7 @@ type SqlPreToolDecision = {
     kind: 'ask';
     reason?: string;
 };
-/** 审批策略需要读取的 alpha.4 工具执行字段。 */
+/** 审批策略需要读取的 alpha.5 工具执行字段。 */
 interface SqlToolExecution {
     readonly name: string;
     readonly arguments: unknown;
@@ -38,7 +39,7 @@ export interface SqlPluginContext {
     on(event: 'dispose', listener: () => void): () => void;
 }
 /**
- * 插件入口：解析配置、构建四工具、给 sql_exec 注入审批门。
+ * 插件入口：解析配置、构建六工具、给 sql_exec 注入审批门。
  */
 export declare function apply(ctx: SqlPluginContext, config?: SqlConfig | null): void;
 export * from './adapters.js';

package/lib/index.js

@@ -1,8 +1,9 @@
 /**
  * dsh-sql —— 工程师级数据库工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册四个面向模型的工具（sql_list / sql_query /
- * sql_exec / sql_schema），支持 SQLite / MySQL / PostgreSQL 三引擎与多连接。
+ * 插件导出 apply(ctx, config)：注册六个面向模型的工具（sql_list / sql_query /
+ * sql_exec / sql_schema / sql_stats / sql_health），支持 SQLite / MySQL / PostgreSQL
+ * 三引擎与多连接。
  * sql_exec 默认走宿主审批门（对齐 dsh-email 的发信审批），readOnly 模式可整体禁用写。
  *
  * @module dsh-sql
@@ -13,17 +14,10 @@ import { buildSqlTools } from './tools.js';
 export const name = 'sql';
 export const inject = ['tools'];
 /**
- * 插件入口：解析配置、构建四工具、给 sql_exec 注入审批门。
+ * 插件入口：解析配置、构建六工具、给 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 cfg = resolveConfig(config);
     const { tools, adapters } = buildSqlTools(cfg);
     if (cfg.writeApproval) {
         ctx.on('tools/pre-execute', async (exec, next) => {

package/lib/tools.d.ts

@@ -37,7 +37,7 @@ export interface SqlExecGateContext {
     callId?: unknown;
     signal?: unknown;
 }
-/** 构建四个工具定义；adapters 惰性创建并按连接名缓存。 */
+/** 构建六个工具定义；adapters 惰性创建并按连接名缓存。 */
 export declare function buildSqlTools(config: ResolvedSqlConfig): {
     tools: SqlToolDefinition[];
     adapters: Map<string, DatabaseAdapter>;

package/lib/tools.js

@@ -32,6 +32,12 @@ function requiredString(args, key, label) {
         throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
     return value;
 }
+function executionSignal(exec) {
+    if (typeof exec !== 'object' || exec === null)
+        return undefined;
+    const signal = exec.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
 /** 只读语句关键字白名单。 */
 const READ_KEYWORDS = /^(select|pragma|explain|show|describe|desc|with)\b/i;
 /** 去掉字符串、引号标识符与注释，保留真实 SQL 关键字与分号。 */
@@ -125,7 +131,7 @@ function stripSqlNoise(sql) {
     return out;
 }
 /** 写操作关键字：出在 SELECT/EXPLAIN/WITH 语句里即拒绝。 */
-const WRITE_KEYWORDS = /\b(insert|update|delete|replace|merge|drop|alter|create|truncate|call|execute|copy|grant|revoke|attach|detach|vacuum|reindex|refresh|set|reset|begin|commit|rollback|savepoint|release|analyze|load_extension)\b/gi;
+const WRITE_KEYWORDS = /\b(insert|update|delete|replace|merge|drop|alter|create|truncate|call|execute|copy|grant|revoke|attach|detach|vacuum|reindex|refresh|set|reset|begin|commit|rollback|savepoint|release|analyze|load_extension)\b/i;
 /** 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句。 */
 export function assertReadQuery(sql) {
     const trimmed = sql.trim();
@@ -241,17 +247,17 @@ function formatBytes(bytes) {
     return (bytes / 1024 / 1024 / 1024).toFixed(2) + ' GB';
 }
 /** 库体积：SQLite 用页数×页大小；MySQL/PostgreSQL 走系统函数；失败抛错由调用方兜底。 */
-async function databaseSize(adapter, engine) {
+async function databaseSize(adapter, engine, signal) {
     if (engine === 'sqlite') {
-        const pageCount = await adapter.query('PRAGMA page_count', 1);
-        const pageSize = await adapter.query('PRAGMA page_size', 1);
+        const pageCount = await adapter.query('PRAGMA page_count', 1, signal);
+        const pageSize = await adapter.query('PRAGMA page_size', 1, signal);
         return Number(pageCount.rows[0]?.[0] ?? 0) * Number(pageSize.rows[0]?.[0] ?? 0);
     }
     if (engine === 'mysql') {
-        const result = await adapter.query('SELECT SUM(DATA_LENGTH + INDEX_LENGTH) FROM information_schema.tables WHERE TABLE_SCHEMA = DATABASE()', 1);
+        const result = await adapter.query('SELECT SUM(DATA_LENGTH + INDEX_LENGTH) FROM information_schema.tables WHERE TABLE_SCHEMA = DATABASE()', 1, signal);
         return Number(result.rows[0]?.[0] ?? -1);
     }
-    const result = await adapter.query('SELECT pg_database_size(current_database())', 1);
+    const result = await adapter.query('SELECT pg_database_size(current_database())', 1, signal);
     return Number(result.rows[0]?.[0] ?? -1);
 }
 const statsSchema = {
@@ -279,7 +285,7 @@ const healthSchema = {
     },
     additionalProperties: true,
 };
-/** 构建四个工具定义；adapters 惰性创建并按连接名缓存。 */
+/** 构建六个工具定义；adapters 惰性创建并按连接名缓存。 */
 export function buildSqlTools(config) {
     const cfg = config;
     const adapters = new Map();
@@ -296,7 +302,7 @@ export function buildSqlTools(config) {
         }
         return { adapter, name: connection.name };
     };
-    const pingAllConnections = async () => {
+    const pingAllConnections = async (signal) => {
         const rows = [];
         for (const connection of cfg.connections) {
             const entry = { name: connection.name, engine: connection.engine };
@@ -308,11 +314,12 @@ export function buildSqlTools(config) {
             }
             try {
                 const { adapter } = getAdapter(connection.name);
-                await adapter.ping();
+                await adapter.ping(signal);
                 entry.ok = true;
                 entry.error = '';
             }
             catch (error) {
+                signal?.throwIfAborted();
                 entry.ok = false;
                 entry.error = error instanceof Error ? error.message : String(error);
             }
@@ -338,8 +345,8 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute() {
-            return { connections: await pingAllConnections() };
+        async execute(_rawArgs, exec) {
+            return { connections: await pingAllConnections(executionSignal(exec)) };
         },
         timeoutMs: 30000,
     };
@@ -369,11 +376,11 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const sql = assertReadQuery(requiredString(args, 'sql', 'SQL 语句'));
             const { adapter, name } = getAdapter(optionalString(args, 'connection'));
-            const result = await adapter.query(sql, cfg.maxRows + 1);
+            const result = await adapter.query(sql, cfg.maxRows + 1, executionSignal(exec));
             const total = result.rows.length;
             const rows = result.rows.slice(0, cfg.maxRows);
             const format = optionalString(args, 'format')?.toLowerCase() ?? 'table';
@@ -409,13 +416,13 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: '执行完成（' + rec.connection + '）：影响 ' + rec.changes + ' 行。' }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             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);
+            const changes = await adapter.exec(sql, executionSignal(exec));
             return { connection: name, changes, readOnly: false };
         },
         timeoutMs: cfg.execTimeoutMs,
@@ -444,15 +451,16 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: '共 ' + tables.length + ' 张表：' + tables.join(', ') }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const { adapter, name } = getAdapter(optionalString(args, 'connection'));
             const table = optionalString(args, 'table');
+            const signal = executionSignal(exec);
             if (table !== undefined) {
-                const columns = await adapter.describeTable(table);
+                const columns = await adapter.describeTable(table, signal);
                 return { connection: name, table, columns, tables: [] };
             }
-            const tables = await adapter.listTables();
+            const tables = await adapter.listTables(signal);
             return { connection: name, tables, columns: [] };
         },
         timeoutMs: 30000,
@@ -478,15 +486,17 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const { adapter, name } = getAdapter(optionalString(args, 'connection'));
             const engine = adapter.engine;
+            const signal = executionSignal(exec);
             let sizeBytes = -1;
             try {
-                sizeBytes = await databaseSize(adapter, engine);
+                sizeBytes = await databaseSize(adapter, engine, signal);
             }
             catch {
+                signal?.throwIfAborted();
                 sizeBytes = -1;
             }
             const tables = [];
@@ -495,23 +505,25 @@ export function buildSqlTools(config) {
                     const sql = engine === 'mysql'
                         ? 'SELECT TABLE_NAME, TABLE_ROWS FROM information_schema.tables WHERE TABLE_SCHEMA = DATABASE()'
                         : 'SELECT relname, n_live_tup FROM pg_stat_user_tables ORDER BY relname';
-                    const result = await adapter.query(sql);
+                    const result = await adapter.query(sql, undefined, signal);
                     for (const row of result.rows) {
                         tables.push({ name: String(row[0]), rowCount: typeof row[1] === 'number' ? row[1] : Number(row[1] ?? 0) });
                     }
                 }
                 catch (error) {
+                    signal?.throwIfAborted();
                     tables.push({ name: '', error: error instanceof Error ? error.message : String(error) });
                 }
             }
             else {
-                const names = await adapter.listTables();
+                const names = await adapter.listTables(signal);
                 for (const table of names) {
                     try {
-                        const result = await adapter.query('SELECT COUNT(*) FROM ' + quoteIdent(engine, table), 1);
+                        const result = await adapter.query('SELECT COUNT(*) FROM ' + quoteIdent(engine, table), 1, signal);
                         tables.push({ name: table, rowCount: Number(result.rows[0]?.[0] ?? 0) });
                     }
                     catch (error) {
+                        signal?.throwIfAborted();
                         tables.push({ name: table, error: error instanceof Error ? error.message : String(error) });
                     }
                 }
@@ -541,8 +553,8 @@ export function buildSqlTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute() {
-            const connections = await pingAllConnections();
+        async execute(_rawArgs, exec) {
+            const connections = await pingAllConnections(executionSignal(exec));
             const bad = connections.filter((c) => c.ok !== true);
             return {
                 ok: bad.length === 0,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-sql",
-  "version": "0.4.1",
-  "description": "DSH 工程师级数据库插件：sql_list/query/exec/schema 四工具，SQLite/MySQL/PostgreSQL 三引擎、多连接、只读模式与写操作审批门、词法级只读保护、流式行数钳制与可配置查询/写超时。",
+  "version": "0.4.2",
+  "description": "DSH 工程师级数据库插件：sql_list/query/exec/schema/stats/health 六工具，SQLite/MySQL/PostgreSQL 三引擎、多连接、只读模式与写操作审批门、词法级只读保护、流式行数钳制与可配置查询/写超时。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",