dsh-sql 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -10,12 +10,25 @@ DSH (DeepSeek Harness) engineer-grade database plugin: four tools covering conne
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
+## Compatibility
+
+Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
 ## Installation
 
 ```bash
 dsh plugin --profile web add dsh-sql
 ```
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-sql
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 ```yaml
@@ -87,4 +100,4 @@ pnpm test       # build + 35 tests, including a real SQLite integration suite
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -10,12 +10,25 @@ DSH（DeepSeek Harness）工程师级数据库插件：四个工具覆盖连接
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 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
@@ -87,4 +100,4 @@ pnpm test       # 构建 + 35 个测试（含真实 SQLite 集成）
 
 ## License
 
-MIT
+MIT

package/cordis.patch.yml

@@ -12,8 +12,8 @@
 #           engine: sqlite
 #           file: E:\data\app.db
 #       maxRows: 1000      # sql_query 返回行数上限（1-10000，默认 1000）
-      queryTimeoutMs: 60000 # 单次查询超时（5 秒 - 10 分钟）
-      execTimeoutMs: 120000 # 单次写操作超时（5 秒 - 10 分钟）
+#       queryTimeoutMs: 60000 # 单次查询超时（5 秒 - 10 分钟）
+#       execTimeoutMs: 120000 # 单次写操作超时（5 秒 - 10 分钟）
 #       readOnly: false    # true 时 sql_exec 被禁用
 #       writeApproval: true # 写操作先弹审批（默认 true）
 #

package/lib/index.d.ts

@@ -10,6 +10,7 @@
 import { type SqlConfig } from './config.js';
 import { type SqlToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export declare const name = "sql";
 export declare const inject: string[];
 /** 审批服务最小面（对齐 dsh-email）。 */
 export interface SqlApproval {

package/lib/index.js

@@ -10,6 +10,7 @@
 import { resolveConfig } from './config.js';
 import { buildSqlTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export const name = 'sql';
 export const inject = ['tools'];
 /**
  * 插件入口：解析配置、构建四工具、给 sql_exec 注入审批门。

package/lib/tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * 四个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema。
+ * 六个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema / sql_stats / sql_health。
  *
  * @module dsh-sql/tools
  */
@@ -29,6 +29,8 @@ export interface SqlToolDefinition {
 }
 /** 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句。 */
 export declare function assertReadQuery(sql: string): string;
+/** 查询结果转 CSV 文本（RFC 4180 风格转义）。 */
+export declare function toCsv(columns: string[], rows: unknown[][]): string;
 /** 审批执行上下文的最小面。 */
 export interface SqlExecGateContext {
     agent?: unknown;

package/lib/tools.js

@@ -1,5 +1,5 @@
 /**
- * 四个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema。
+ * 六个面向模型的数据库工具：sql_list / sql_query / sql_exec / sql_schema / sql_stats / sql_health。
  *
  * @module dsh-sql/tools
  */
@@ -166,6 +166,8 @@ const querySchema = {
         rowCount: { type: 'integer' },
         truncated: { type: 'boolean' },
         maxRows: { type: 'integer' },
+        format: { type: 'string' },
+        formatted: { type: 'string' },
     },
     additionalProperties: true,
 };
@@ -208,6 +210,75 @@ const schemaToolSchema = {
     },
     additionalProperties: true,
 };
+// ---------- 输出格式与统计辅助 ----------
+/** 按引擎给标识符加引号，防止表名破坏 SQL。 */
+function quoteIdent(engine, name) {
+    if (engine === 'mysql')
+        return '`' + name.replace(/`/g, '``') + '`';
+    return '"' + name.replace(/"/g, '""') + '"';
+}
+/** 查询结果转 CSV 文本（RFC 4180 风格转义）。 */
+export function toCsv(columns, rows) {
+    const escape = (cell) => {
+        if (cell === null || cell === undefined)
+            return '';
+        const text = Array.isArray(cell) || typeof cell === 'object' ? JSON.stringify(cell) : String(cell);
+        return /[",\n\r]/.test(text) ? '"' + text.replace(/"/g, '""') + '"' : text;
+    };
+    const lines = [columns.map(escape).join(',')];
+    for (const row of rows)
+        lines.push(row.map(escape).join(','));
+    return lines.join('\n');
+}
+/** 人类可读的字节数。 */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return bytes + ' B';
+    if (bytes < 1024 * 1024)
+        return (bytes / 1024).toFixed(1) + ' KB';
+    if (bytes < 1024 * 1024 * 1024)
+        return (bytes / 1024 / 1024).toFixed(1) + ' MB';
+    return (bytes / 1024 / 1024 / 1024).toFixed(2) + ' GB';
+}
+/** 库体积：SQLite 用页数×页大小；MySQL/PostgreSQL 走系统函数；失败抛错由调用方兜底。 */
+async function databaseSize(adapter, engine) {
+    if (engine === 'sqlite') {
+        const pageCount = await adapter.query('PRAGMA page_count', 1);
+        const pageSize = await adapter.query('PRAGMA page_size', 1);
+        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);
+        return Number(result.rows[0]?.[0] ?? -1);
+    }
+    const result = await adapter.query('SELECT pg_database_size(current_database())', 1);
+    return Number(result.rows[0]?.[0] ?? -1);
+}
+const statsSchema = {
+    type: 'object',
+    properties: {
+        connection: { type: 'string' },
+        engine: { type: 'string' },
+        tableCount: { type: 'integer' },
+        tables: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        sizeBytes: { type: 'integer' },
+    },
+    additionalProperties: true,
+};
+const healthSchema = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        plugin: { type: 'string' },
+        connections: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        readOnly: { type: 'boolean' },
+        writeApproval: { type: 'boolean' },
+        maxRows: { type: 'integer' },
+        queryTimeoutMs: { type: 'integer' },
+        execTimeoutMs: { type: 'integer' },
+    },
+    additionalProperties: true,
+};
 /** 构建四个工具定义；adapters 惰性创建并按连接名缓存。 */
 export function buildSqlTools(config) {
     const cfg = config;
@@ -225,6 +296,30 @@ export function buildSqlTools(config) {
         }
         return { adapter, name: connection.name };
     };
+    const pingAllConnections = async () => {
+        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 rows;
+    };
     const sqlList = {
         name: 'sql_list',
         description: '列出配置的数据库连接并逐一做连通性测试（SELECT 1）。返回连接名、引擎、目标与健康状态。',
@@ -244,28 +339,7 @@ export function buildSqlTools(config) {
             },
         },
         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 };
+            return { connections: await pingAllConnections() };
         },
         timeoutMs: 30000,
     };
@@ -275,11 +349,16 @@ export function buildSqlTools(config) {
         parameters: compileParameters({
             sql: { type: 'string', required: true, description: '只读 SQL 语句（必填，单条）。' },
             connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
+            format: { type: 'string', description: '输出格式：table（默认表格）/ csv / json。csv 与 json 会额外返回 formatted 文本，便于落盘或转存。' },
         }),
         output: {
             schema: querySchema,
             render: (_args, value) => {
                 const rec = asRecord(value);
+                if (typeof rec.formatted === 'string' && rec.formatted !== '') {
+                    const preview = rec.formatted.length > 4000 ? rec.formatted.slice(0, 4000) + '\n…（预览已截断）' : rec.formatted;
+                    return [{ type: 'text', text: '查询返回 ' + rec.rowCount + ' 行（' + String(rec.format) + ' 格式）：\n' + preview }];
+                }
                 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)) {
@@ -297,7 +376,8 @@ export function buildSqlTools(config) {
             const result = await adapter.query(sql, cfg.maxRows + 1);
             const total = result.rows.length;
             const rows = result.rows.slice(0, cfg.maxRows);
-            return {
+            const format = optionalString(args, 'format')?.toLowerCase() ?? 'table';
+            const base = {
                 connection: name,
                 columns: result.columns,
                 rows,
@@ -305,6 +385,13 @@ export function buildSqlTools(config) {
                 truncated: total > cfg.maxRows,
                 maxRows: cfg.maxRows,
             };
+            if (format === 'csv')
+                return { ...base, format, formatted: toCsv(result.columns, rows) };
+            if (format === 'json') {
+                const objects = rows.map((row) => Object.fromEntries(result.columns.map((column, i) => [column, row[i]])));
+                return { ...base, format, formatted: JSON.stringify(objects, null, 2) };
+            }
+            return base;
         },
         timeoutMs: cfg.queryTimeoutMs,
     };
@@ -373,5 +460,105 @@ export function buildSqlTools(config) {
         },
         timeoutMs: 30000,
     };
-    return { tools: [sqlList, sqlQuery, sqlExec, sqlSchema], adapters };
+    const sqlStats = {
+        name: 'sql_stats',
+        description: '数据库概览统计：表数量、每张表的行数、库体积（SQLite 按页计算，MySQL/PostgreSQL 走系统表）。connection 为连接名（缺省第一个连接）。适合在写查询前先了解数据规模。',
+        parameters: compileParameters({
+            connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
+        }),
+        output: {
+            schema: statsSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const tables = Array.isArray(rec.tables) ? rec.tables : [];
+                const lines = ['连接 ' + rec.connection + '（' + rec.engine + '）：共 ' + tables.length + ' 张表' + (typeof rec.sizeBytes === 'number' && rec.sizeBytes >= 0 ? '，库体积 ' + formatBytes(rec.sizeBytes) : '') + '。'];
+                for (const item of tables.slice(0, 30)) {
+                    const t = asRecord(item);
+                    lines.push('- ' + t.name + '：' + (typeof t.rowCount === 'number' ? t.rowCount + ' 行' : '行数未知' + (t.error ? '（' + t.error + '）' : '')));
+                }
+                if (tables.length > 30)
+                    lines.push('…仅展示前 30 张表');
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const { adapter, name } = getAdapter(optionalString(args, 'connection'));
+            const engine = adapter.engine;
+            let sizeBytes = -1;
+            try {
+                sizeBytes = await databaseSize(adapter, engine);
+            }
+            catch {
+                sizeBytes = -1;
+            }
+            const tables = [];
+            if (engine === 'mysql' || engine === 'postgres') {
+                try {
+                    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);
+                    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) {
+                    tables.push({ name: '', error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            else {
+                const names = await adapter.listTables();
+                for (const table of names) {
+                    try {
+                        const result = await adapter.query('SELECT COUNT(*) FROM ' + quoteIdent(engine, table), 1);
+                        tables.push({ name: table, rowCount: Number(result.rows[0]?.[0] ?? 0) });
+                    }
+                    catch (error) {
+                        tables.push({ name: table, error: error instanceof Error ? error.message : String(error) });
+                    }
+                }
+            }
+            return { connection: name, engine, tableCount: tables.filter((t) => t.name !== '').length, tables, sizeBytes };
+        },
+        timeoutMs: cfg.queryTimeoutMs,
+    };
+    const sqlHealth = {
+        name: 'sql_health',
+        description: 'dsh-sql 自检：逐个连接做连通性测试，并汇总安全配置（只读模式、写审批门、行数上限、超时）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: healthSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const connections = Array.isArray(rec.connections) ? rec.connections : [];
+                const bad = connections.filter((c) => asRecord(c).ok !== true);
+                const lines = ['dsh-sql 自检' + (bad.length === 0 ? '：全部连接正常。' : '：' + bad.length + ' 个连接异常。')];
+                for (const item of connections) {
+                    const c = asRecord(item);
+                    lines.push('- ' + c.name + '（' + c.engine + '）' + (c.ok === true ? ' ✅' : ' ❌ ' + String(c.error ?? '')));
+                }
+                lines.push('- 只读模式：' + (rec.readOnly === true ? '开（sql_exec 已禁用）' : '关'));
+                lines.push('- 写审批门：' + (rec.writeApproval === true ? '开' : '关'));
+                lines.push('- 行数上限：' + String(rec.maxRows) + '；查询超时 ' + String(rec.queryTimeoutMs) + 'ms；写超时 ' + String(rec.execTimeoutMs) + 'ms');
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            const connections = await pingAllConnections();
+            const bad = connections.filter((c) => c.ok !== true);
+            return {
+                ok: bad.length === 0,
+                plugin: 'dsh-sql',
+                connections,
+                readOnly: cfg.readOnly,
+                writeApproval: cfg.writeApproval,
+                maxRows: cfg.maxRows,
+                queryTimeoutMs: cfg.queryTimeoutMs,
+                execTimeoutMs: cfg.execTimeoutMs,
+            };
+        },
+        timeoutMs: 30000,
+    };
+    return { tools: [sqlList, sqlQuery, sqlExec, sqlSchema, sqlStats, sqlHealth], adapters };
 }

package/package.json

@@ -1,68 +1,67 @@
-{
-  "name": "dsh-sql",
-  "version": "0.3.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",
-    "dsh-plugin"
-  ],
-  "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"
-}
+{
+  "name": "dsh-sql",
+  "version": "0.4.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",
+    "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",
+    "dsh-plugin"
+  ],
+  "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"
+}