dsh-sql-query

零运行时依赖的 SQL 子集查询引擎，用于 DeepSeek Harness 生态：对 JSON 数组 / CSV / JSONL / 表格文本 / 本地文件执行 SELECT 查询，支持 WHERE、GROUP BY + 聚合、ORDER BY、LIMIT/OFFSET、DISTINCT，并配套 explain_sql 执行计划说明工具。不依赖任何第三方库，仅用 Node 内置模块。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-sql-query
• npm：https://www.npmjs.com/package/dsh-sql-query
• 协议：MIT

功能说明

• sql_query：对结构化数据执行 SQL 子集查询，返回 markdown 结果表格。支持：
  • SELECT 列 / * / 算术表达式（+ - * / %）/ 函数 / AS 别名 / DISTINCT
  • WHERE：= != <> < <= > >=、AND / OR / NOT、IN (...)、LIKE（% 任意、_ 单字符）、IS NULL / IS NOT NULL
  • GROUP BY + 聚合：COUNT / SUM / AVG / MIN / MAX（无 GROUP BY 时整体聚合）
  • ORDER BY 多列 + ASC / DESC（可引用投影别名或原列）
  • LIMIT / OFFSET
  • 列名大小写不敏感，支持中文列名；数字 / 布尔 / 字符串自动类型化
• explain_sql：解析 SQL 并输出执行计划说明（不执行数据）：select 项与是否聚合、WHERE 条件、GROUP BY、ORDER BY、LIMIT，以及逐步处理说明。用于确认写法是否落在支持的子集内。

安装

# 从 npm 安装
dsh plugin --profile web add dsh-sql-query

# 本地开发调试（Debug patch）
# 新建 debug.patch.yml：
# - insert:
#     - id: sql-query
#       name: "E:/dsh-plugins/dsh-sql-query/index.js"
dsh web --patch ./debug.patch.yml

使用说明

1. sql_query —— 执行查询

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | 是 | SQL 查询语句 | | data | string | 否* | JSON 对象数组 | | csv | string | 否* | CSV 文本，首行为表头 | | jsonl | string | 否* | JSONL 文本，每行一个对象 | | text | string | 否* | 表格文本，自动探测制表符/逗号/分号/竖线 | | from | string | 否* | 从本地文件读取（自动识别 CSV/JSON/JSONL） | | limit | number | 否 | 结果展示行数上限，默认 100，上限 1000 | | max_rows | number | 否 | 输入行数上限（防御），默认 100000 |

* data / csv / jsonl / text / from 至少提供一种数据源。

内置函数：ABS ROUND FLOOR CEIL SQRT POWER、UPPER LOWER LENGTH TRIM REVERSE CONCAT SUBSTR REPLACE、COALESCE IF NULLIF GREATEST LEAST。

2. explain_sql —— 执行计划

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | 是 | SQL 查询语句 |

典型场景

• 表格数据问答：拿到一份 CSV/Excel 导出文本，直接用 SQL 问「哪个城市平均分最高」「每组有多少条」。
• 数据探查：SELECT DISTINCT 城市 FROM data 快速看枚举值；COUNT(*) + GROUP BY 看分布。
• 行内计算：SELECT 价格 * 数量 AS 金额 FROM 订单 WHERE 金额 > 1000。
• 查询前自检：复杂 SQL 先用 explain_sql 看解析出的结构和执行步骤，再真正执行。

安全边界

• 只读：两个工具均为纯计算，不写文件、不发网络请求（from 仅读本地文件）。
• 输入上限：输入行数默认 10 万行上限（max_rows 可调至 100 万）；结果展示默认 100 行、上限 1000 行，防止超大结果刷屏。
• 子集而非全量 SQL：不支持子查询、JOIN、写操作（INSERT/UPDATE/DELETE），无注入面；LIKE 模式转义后构造正则，不回溯失控。
• 类型宽松但可预期：混合类型比较按字符串兜底，null 参与比较按 false 处理（除 IS NULL）。

版本说明

| 版本 | 日期 | 说明 | |------|------|------| | 0.1.0 | 2026-10-15 | 首个版本：sql_query + explain_sql，自研分词器与递归下降解析器，支持 SELECT/WHERE/GROUP BY 聚合/ORDER BY/LIMIT，72 断言测试 |

RoadMap

• [ ] HAVING 聚合后过滤
• [ ] 多数据源 JOIN（INNER/LEFT）
• [ ] 子查询（IN (SELECT ...)）
• [ ] 窗口函数（ROW_NUMBER / RANK）
• [ ] CASE WHEN 表达式
• [ ] 日期函数（DATE_ADD / DATEDIFF）

其他插件集成说明

• dsh-csv-explorer：纯 CSV 探查/过滤；本插件提供 SQL 通用查询能力，两者互补。
• dsh-xlsx-lite：先用 read_xlsx 取出 xlsx 数据（或 write_xlsx 落盘），再交给本插件做 SQL 分析。
• dsh-json-yaml-toolkit / dsh-jsonl-stream：JSON/JSONL 解析与转换，可作为本插件的数据源上游。
• dsh-pivot-join：固定透视/连接算子；需要灵活条件与聚合时用本插件的 SQL。
• dsh-stats-toolkit：SQL 做分组初筛，统计插件做深入分析（分位数/异常检测）。

FAQ

Q1：支持哪些 SQL 语法？ 单表 SELECT ... FROM ... [WHERE] [GROUP BY] [ORDER BY] [LIMIT/OFFSET]，含表达式、函数、聚合、DISTINCT。不支持 JOIN、子查询、写操作（见 RoadMap）。

Q2：列名是中文或有空格怎么办？ 中文列名直接写即可（SELECT 姓名 FROM t）。含空格等特殊字符的列名建议先用数据源规整，或用 AS 别名输出。

Q3：null 参与比较是什么行为？ null 与任何值比较均为 false（SQL 三值逻辑的简化），判空请用 IS NULL / IS NOT NULL，兜底用 COALESCE。

Q4：LIKE 的通配符？ % 匹配任意长度、_ 匹配单个字符，其余字符按字面匹配。

Q5：聚合和无 GROUP BY 什么关系？ select 项里出现聚合函数但没有 GROUP BY 时，整个结果集作为一组（如 SELECT COUNT(*) FROM t 返回一行）。

Q6：结果行数太多怎么办？ SQL 里写 LIMIT，或用工具参数 limit 控制展示行数；输入过大时用 max_rows 防御。

许可证

MIT