dsh-tool-sql

English | 中文

为 DeepSeek Harness（dsh）提供只读 SQL 查询能力的 Cordis 工具插件。Agent 可以通过自然语言查询数据、列出表、查看表结构，支持 PostgreSQL 和 MySQL，默认强制只读、拒绝一切写操作。

基于官方「一切皆插件」架构，通过 ctx.tools.register(defineTool(...)) 注册模型可见工具，完全遵循官方 adding-a-tool 契约。

安装

直接从 GitHub 安装（无需发布 npm）：

npm install github:LJH-snow/dsh-tool-sql
# 或指定分支/标签
npm install github:LJH-snow/dsh-tool-sql#main

或从本地目录安装：

git clone https://github.com/LJH-snow/dsh-tool-sql
cd dsh-tool-sql
npm install && npm run build   # 构建到 lib/
npm install /path/to/dsh-tool-sql

发布到 npm 后，也可用 npm install @libai168/dsh-tool-sql 安装。

需要 @deepseek-ai/cordis（^4.0.1）与 @deepseek-ai/dsh-tools（^0.1.0-rc.6）作为 peer 依赖，由宿主 dsh 运行时提供。

配置

在 dsh 的组合配置（cordis.yml）中加载插件：

- name: 'dsh-tool-sql'
  config:
    type: 'postgres'        # 或 'mysql'
    host: 'localhost'
    port: 5432              # 可选（postgres 5432，mysql 3306）
    user: 'dbuser'
    password: 'dbpass'
    database: 'appdb'
    maxRows: 100            # 可选，单次查询返回最大行数（默认 100）
    timeoutMs: 15000        # 可选，查询超时毫秒数（默认 15000）
    ssl: false              # 可选，启用 TLS

完整示例：examples/cordis.yml。

安全：插件默认强制只读。仅允许 SELECT/EXPLAIN/SHOW/DESCRIBE/WITH/PRAGMA/VALUES 语句；包含写关键字（INSERT/UPDATE/DELETE/DDL 等）一律拒绝。凭据只从插件配置读取，绝不打印或写入日志。

工具

| 工具 | 说明 | |---|---| | sql_query | 执行只读 SQL 查询，以 JSON 返回行数据（超出 maxRows 截断；可选 limit 1-1000） | | sql_list_tables | 列出表（PostgreSQL：public schema；MySQL：当前数据库） | | sql_describe_table | 查看表结构（列名/类型/可空/默认值） | | sql_explain | 查看只读语句的执行计划（自动补 EXPLAIN 前缀） | | sql_list_indexes | 列出表的索引（名称/覆盖列/是否唯一） | | sql_database_info | 数据库信息（版本/当前库/当前用户/服务器时间） | | sql_table_stats | 各表估算行数（近似值，从大到小） | | sql_search_columns | 按列名跨表搜索（支持 %/_，最多 100 条） | | sql_ping | 连接测试（SELECT 1，返回往返延迟） | | sql_list_views | 列出视图及定义 | | sql_list_schemas | 列出可见 schema（PostgreSQL）或数据库/schema（MySQL） | | sql_list_sequences | 列出序列（PostgreSQL）；MySQL 提示不支持 | | sql_list_constraints | 列出主键、唯一、检查约束 | | sql_list_databases | 列出连接可见的数据库/schema（PostgreSQL 排除模板库） | | sql_list_roles | 列出 PostgreSQL 角色或 MySQL 账号及关键属性 | | sql_list_grants | 列出可见权限（PostgreSQL：public schema 表授权；MySQL：用户权限） | | sql_list_materialized_views | 列出物化视图（PostgreSQL）；MySQL 提示不支持 | | sql_list_partitions | 列出表分区、方式、边界和估算行数 | | sql_get_table_row_count | 对安全校验后的表名执行精确 COUNT(*) 行数统计 | | sql_table_size | 表占用空间（数据/索引/合计字节） | | sql_get_schema | 查看建表 DDL（MySQL：服务器原样；PostgreSQL：catalog 生成简化版） | | sql_preview | 预览表前 N 行数据（表名严格校验，LIMIT 1-100，默认 10） | | sql_list_functions | 列出函数/存储过程（名称/参数/语言/返回类型） | | sql_list_triggers | 列出触发器（名称/表/时机/事件/定义） | | sql_list_foreign_keys | 列出外键（表.列 → 引用表.引用列） | | sql_schema_dump | 导出整库结构：所有表 DDL + 视图定义 | | sql_list_extensions | 列出数据库扩展（PostgreSQL）；MySQL 提示不支持 | | sql_search_tables | 按表/视图/物化视图名称搜索（支持 %/_，最多 100 条） | | sql_database_size | 当前数据库容量（PostgreSQL 为总量；MySQL 为数据+索引） | | sql_list_table_sizes | 列出所有表的磁盘占用，按总量从大到小 | | sql_get_table_comments | 查看表注释与全部列注释 | | sql_list_incoming_foreign_keys | 查看引用指定表的外键，用于子表影响分析 | | sql_get_column_stats | 列质量分析：总数/非空/空值/去重值/去重比例 | | sql_get_function_source | 返回函数/存储过程源码（匹配全部重载或 SHOW CREATE） | | sql_list_enum_types | 列出 PostgreSQL enum 类型及值；MySQL 提示不支持 | | sql_get_table_health | 查看 PostgreSQL 表活动/维护健康；MySQL 提示不支持 | | sql_list_active_queries | 列出连接可见的非空闲查询（包含查询文本） | | sql_search_routines | 按函数/存储过程名称搜索（支持 %/_，最多 100 条） | | sql_search_indexes | 按表名或索引名搜索索引，返回覆盖列与唯一性 | | sql_list_index_usage | 列出 PostgreSQL 索引使用统计；MySQL 提示不支持 | | sql_list_locks | 列出连接可见的锁（PostgreSQL pg_locks；MySQL performance_schema） | | sql_get_table_last_access | 查看 PostgreSQL 表最近 seq/index scan 时间与次数；MySQL 提示不支持 | | sql_search_view_definitions | 按视图名或定义文本搜索视图并返回定义 | | sql_search_routine_definitions | 按函数/存储过程名称或源码文本搜索并返回完整定义 | | sql_search_trigger_definitions | 按触发器/表/动作文本搜索触发器并返回定义或动作语句 | | sql_search_constraint_definitions | 按名称或定义文本搜索主键/唯一/检查约束定义 | | sql_search_table_ddl | 按表名搜索并返回建表 DDL（PostgreSQL 简化生成；MySQL 服务器原样） | | sql_get_table_dependencies | 查找引用某表的对象：视图/物化视图、例程、触发器、入向外键 | | sql_get_view_dependencies | 查看视图引用的表、视图和例程 | | sql_get_routine_dependencies | 查看函数/存储过程源码中引用的表、视图和例程 | | sql_get_routine_references | 查找源码文本引用某对象的函数/存储过程（删除/重命名影响分析） | | sql_get_trigger_dependencies | 查看触发器使用的表和触发例程 |

开发

npm install
npm run typecheck   # 类型检查
npm test            # 单元测试（vitest）
npm run build       # 构建到 lib/

开发计划、决策记录见 DEVELOPMENT.md。

发布与生态

1. 发布使用你的 npm scope：@libai168/dsh-tool-sql（npm 发布需要启用 2FA bypass 的 granular access token，或 trusted publishing）。
2. npm run build 后执行 npm publish --access public。
3. 为你的 GitHub 仓库添加 dsh-plugin topic，便于生态发现。

License

MIT