前言¶

在 DSH（DeepSeek Harness）里做自然语言问数，常见做法是手写 MCP 或临时脚本去连 ClickHouse：既要让模型能探库表结构，又要防止误执行 INSERT、ALTER 一类语句。连接串、结果行数、超时和资源上限往往分散在多处，排查「连不上」和「查挂了」也费时。

下面介绍社区插件 dsh-clickhouse（维护者 saichao，分类：联网工具）。它把「库表探查 + 单条只读 SQL」收成七个 clickhouse_* 工具，供 agent 按「先摸清结构、再问数」的顺序调用；实现上只用 Node 内置 fetch，装进 profile 后无额外运行时依赖解析。

这是什么¶

dsh-clickhouse 面向 DSH / DeepSeek Harness，定位是 ClickHouse 结构探索与带护栏的只读查询。简介原文为：ClickHouse query tools for DSH / DeepSeek Harness: schema exploration plus guarded read-only SQL；中文说明为带只读护栏的 ClickHouse 数据问答插件，零运行时依赖。

• 仓库：https://github.com/saichao/dsh-clickhouse
• 社区目录页：https://www.skillhub.cn/plugins/saichao/dsh-clickhouse
• 当前 package 版本：0.1.1，许可证 MIT，要求 Node >=20

插件以当前 DSH 进程权限访问你配置的 ClickHouse HTTP 端点；安装前请自行审阅源码与许可证。

核心功能¶

七个工具与使用顺序¶

工具按实际问数流程编排，并支持按字段名反查表：

返回值对模型是结构化的（含 summary、columns、rows、rowCount、truncated、elapsedMs、queryId、executedSql、notes 等），并由工具渲染为 Markdown 表格。

只读护栏¶

客户端：每条语句只允许一条 SQL，且 leading keyword 为 SELECT / WITH / SHOW / DESCRIBE / EXPLAIN / EXISTS；语句任意位置出现写关键字会被拒绝；并拒绝 INTO OUTFILE、FORMAT、SETTINGS 及外部表函数（可通过配置放宽部分项）。

服务端：查询附带 max_result_rows（result_overflow_mode=break）、max_execution_time、max_memory_usage；配置项 readonly 默认为 true 时还会加 readonly=1（老版本 ClickHouse 如 21.12 上只读模式可能拒 numbers() 等，确需时可设为 false，客户端护栏仍生效）。

README 注明已在 ClickHouse 21.12 上验证；非 ASCII 别名需用反引号，否则会给出改法提示而非裸语法错误。

零运行时依赖¶

不依赖 profile 内额外 node_modules 解析，HTTP 请求走 Node 内置 fetch。

安装与启用¶

社区目录与 README 给出的三步与命令如下。

1. 安装：DSH 设置 → 插件（插件市场）搜索 clickhouse，选择 dsh-clickhouse 安装。命令行等价：

dsh plugin --profile <profile> add github:saichao/dsh-clickhouse

2. 启用并重启：在市场里启用插件后重启 DSH。

3. 配置连接：在 profile 用户补丁层写入连接信息（路径示例 ~/.dsh/profiles/<profile>/cordis.patch.yml），再重启一次；若漏配，插件会给出明确报错（含 HTTP 8123 与 TCP 9000 的区分说明），而不是笼统的 fetch failed：

- id: clickhouse
  name: dsh-clickhouse
  config: { url: http://<主机>:8123, user: default, password: '' }

从源码部署时，README 还提供 pnpm install、pnpm build、node scripts/install.mjs 等流程（面向开发者维护 profile bundle）；一般用户以市场安装与 cordis.patch.yml 覆盖为主。

配置改动注意：改 cordis.patch.yml 前建议备份（同文件常含模型与密钥等）；README 实测用户补丁层覆盖后 DSH HMR 可立即重组工具树，但 bundle 安装路径仍建议以重启后行为为准确认。

配置要点¶

推荐在用户补丁层按 id: clickhouse 整行覆盖 bundle 里的 config：

- id: clickhouse
  name: dsh-clickhouse
  config:
    url: http://localhost:8123
    user: default
    password: ''
    database: default
    readonly: true

典型用法¶

在对话中让模型依次调用工具即可；README 示例（任意实例均可复现的 system 库）如下。

clickhouse_query 执行：

SELECT database AS `库`, count() AS `表数` FROM system.tables
WHERE database LIKE 'system%' GROUP BY database ORDER BY `表数` DESC LIMIT 5

模型侧可见类似输出摘要：

查询完成：1 行 / 2 ms
| 库 | 表数 |
| --- | --- |
| system | 75 |

完整演示输出见仓库 docs/demo-output.txt。本地也可用 node scripts/demo.mjs 打印与模型一致的渲染结果（需已安装并配置）。

适用场景与注意¶

适合：已在 DSH 中做 ClickHouse 问数、希望 agent 自带探库与只读 SQL、且希望限制写操作与结果规模的团队或个人。

注意：

• 插件以 DSH 进程权限 访问 ClickHouse；应对生产库时配合 allowDatabases / denyDatabases 与网络隔离。
• url 必须是 HTTP 接口（默认 8123），不是原生 TCP 9000。
• 社区目录站点 skillhub.cn 为独立生态索引，与 DeepSeek / 幻方无官方从属关系；插件星标以目录页展示为准（当前线索为 0）。

结尾¶

dsh-clickhouse 把 ClickHouse 问数收敛为七个有序工具，并在客户端与服务端双层限制只读与资源。若要在 Harness 里接自己的实例，可从社区目录页查看条目说明，或在 GitHub 阅读 README 中的护栏范围与验证记录。

• 目录页：https://www.skillhub.cn/plugins/saichao/dsh-clickhouse
• GitHub：https://github.com/saichao/dsh-clickhouse