clickhouse-js-node-troubleshooting-clickhouse-agent-skills

1. 基本信息

项目	内容
名称	clickhouse-js-node-troubleshooting-clickhouse-agent-skills
项目自述名称	仓库自述名 “ClickHouse Agent Skills”（本子技能自身标题为 “ClickHouse JS Node Troubleshooting”，在仓库 README 的“Available Skills”清单中独立列出）
作者/维护者	ClickHouse Inc（官方仓库）；子技能提交者为 ClickHouse 员工 Peter Leonov（GitHub 账号 company 字段实测为 “ClickHouse”），另一次提交由 GitHub Copilot 代理发起、经同一员工审核合并
来源链接	https://github.com/ClickHouse/agent-skills/tree/main/skills/clickhouse-js-node-troubleshooting
许可证	Apache-2.0（GitHub API 实测）
GitHub Stars	该子目录本身无独立 star 计数；合集仓库 agent-skills 整体 496 star / 32 forks（GitHub API 实测），该数字属整个合集仓库，不代表本子技能自身热度
最新版本	仓库未打版本标签；子技能内容最近一次功能性变更为 2026-06-30（同步整理），此前 2026-05-13 从嵌套路径提升为顶层技能；所封装的官方 Node.js 客户端包 `@clickhouse/client` 当前 npm 最新版本 1.23.1（npm 官方 registry 实测）
安装方式	`npx skills add clickhouse/agent-skills` 或官方 CLI `clickhousectl skills`；无需额外依赖安装

2. 功能介绍与亮点

ClickHouse JS Node Troubleshooting 是官方 Node.js 客户端 @clickhouse/client 的专项故障排查手册，把常见报错按症状拆成 9 个独立参考文档，每个报错都给出“先诊断、后修复”的分步流程而非一句话建议：

覆盖 Socket Hang-Up/ECONNRESET、数据类型解析错误、只读用户报错、代理路径混淆、TLS 证书问题、压缩失效、日志无输出、查询参数未插值、FORMAT 子句冲突 9 类高频问题
每类问题附带诊断步骤（如用 curl 探测服务端 Keep-Alive 超时头、开启 WARN 日志定位悬空流）与对应最低客户端版本号要求，避免给出对用户当前版本无效的修复建议
与同仓库的 clickhouse-js-node-coding（面向“如何写”）分工明确、互不重叠，专注“报错后如何修”
已被 ClickHouse 官方客户端仓库 ClickHouse/clickhouse-js 直接收录为随包分发的技能文档，并被 GitHub 官方技能目录 agentfinder-catalog、多 Agent 技能集合 cline/skills 等下游项目引用/收录

3. 适用场景

固定分类：工程效率与代码质量

适合使用 ClickHouse 官方 Node.js 客户端开发应用、遇到连接报错或异常行为的后端/全栈开发者：排查生产环境间歇性 socket hang up、诊断类型转换报错、定位代理或 TLS 配置问题等场景，尤其适合还不熟悉该客户端内部连接复用机制、需要按症状而非试错法解决问题的中初级用户。

4. 跨 Agent 兼容性

Claude Code：✅ 原生支持——仓库自带 .claude-plugin 市场清单，npx skills add 可自动检测并安装
Codex：✅ 支持——npx skills add 所用安装器（npm 包 skills，实测其 repository 字段指向 vercel-labs/skills）源码 src/agents.ts 中显式定义了 codex agent profile（探测 $CODEX_HOME 或 /etc/codex）
OpenClaw：✅ 支持——同一安装器源码中定义了 openclaw profile（探测 ~/.openclaw 等目录）
Hermes Agent：✅ 支持——同一安装器源码中定义了 hermes-agent profile（探测 ~/.hermes 或 $HERMES_HOME）

以上四项结论均直接读取该技能实际使用的安装器源码得出，非仓库自身声明。

5. 推荐理由

官方ClickHouse团队出品，按症状索引精准定位并修复Node客户端连接与解析报错，省去反复试错排查连接抖动等隐蔽问题的时间成本。

6. 评分

维度	分数	说明
受欢迎程度	6	子目录自身提交记录较少（2 次，均来自同一员工/其审核的 Copilot 提交），无独立 issue/PR 讨论；但已被 ClickHouse 官方客户端仓库 `clickhouse-js` 收录为随包技能、被 GitHub 官方 `agentfinder-catalog` 与 `cline/skills` 等至少两个独立第三方项目引用/收录，具备真实下游采用证据
可用性	9	单条 `npx skills add` 命令即装；9 类问题各配独立参考文档（合计约 30KB），含诊断步骤与版本号对照；子目录最近一次内容更新为一个月内，仓库整体 10 天前仍有提交；无付费依赖、无需注册账号
安全性	8	见下方安全检查清单
综合	7.7	三项均值

安全检查清单：

检查项	结果
① Shell 命令执行范围	仅建议性诊断命令（如对用户自己的 ClickHouse 地址执行 `curl` 查看响应头），范围明确、无任意执行
② 运行时联网外发数据	建议的诊断请求均指向用户自己配置的 ClickHouse 服务地址，不涉及向第三方地址外发数据
③ API key/凭据	不涉及新增凭据，沿用用户已有的 ClickHouse 连接信息
④ 可疑指令	审阅 SKILL.md 全文与全部 9 个参考文档，未发现 prompt injection 或异常指令
⑤ 作者/组织信誉	ClickHouse Inc 官方组织账号，提交者身份可核实为该公司员工
⑥ License	Apache-2.0，明确
⑦ 最近维护时间	子目录最近一次内容更新约一个月前，仓库整体近日仍有提交，维护活跃

7. 跟同类 Skills 相比的优势

同为“官方数据库厂商 Node.js 客户端疑难排查”类目的技能与本技能的定位差异：

技能	出品方	覆盖范围	深度
ClickHouse JS Node Troubleshooting（本次推荐）	ClickHouse Inc	仅 `@clickhouse/client`（Node.js 运行时）	9 类报错各有独立文档，含具体诊断步骤与客户端版本号对照
mongodb-connection（mongodb/agent-skills）	MongoDB Inc	泛化覆盖 Node.js、Python、Java、Go、C#、Ruby、PHP 等全部官方驱动语言	单一文档讲解连接池通用原理，不区分具体报错类型的分步排查流程

MongoDB 的方案胜在跨语言通用性，但因要兼顾多语言而停留在连接池原理层面；本技能牺牲了跨语言覆盖面，换来针对 Node.js 单一运行时的报错级精确匹配与分步修复指引，更适合已经确定技术栈、只想快速解决具体报错的场景。

8. 用户评价

该技能目前在第三方平台尚无具名用户评价；其所属仓库 ClickHouse/agent-skills 迄今仅有 2 个 issue，均来自仓库内部贡献者，暂无外部用户就本技能发起过公开讨论。

9. 其他补充

仓库遵循 agentskills.io 开放技能规范；同仓库还含 clickhouse-best-practices、clickhouse-architecture-advisor、chdb-sql、chdb-datastore、clickhousectl-local-dev 等其他技能，均可按需单独安装。

10. 安装使用方式

推荐方式：npx skills add clickhouse/agent-skills，CLI 会自动检测已安装的 agent 并询问装到哪个目录，仅需勾选本技能即可，无需装整仓库
ClickHouse 官方 CLI：clickhousectl skills
安装后无需重启；当在 Node.js 环境中使用 @clickhouse/client 遇到报错、异常行为或配置疑问时会自动触发（如“socket hang up”、“连接总是断”等模糊描述也能触发）

11. 注意事项

仅覆盖 Node.js 运行时的 @clickhouse/client 包，明确不适用于浏览器端/Next.js Edge 运行时/Cloudflare Workers 场景下的 @clickhouse/client-web，如遇后者报错需寻找其他资料
与同仓库 clickhouse-js-node-coding 技能是排查/编码两个互补分工，只想学习如何正确编写客户端代码（而非修复报错）应改装后者
本技能是合集仓库 ClickHouse/agent-skills 中的一个子目录，只需该功能时装本子目录即可