1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | clickhouse-js-node-rowbinary | GitHub API / SKILL.md |
| 作者/维护者 | ClickHouse Inc（官方 ClickHouse/agent-skills 仓库，子目录提交者 Peter Leonov，GitHub 账号 company 字段实测为 “ClickHouse”） |
GitHub API |
| 来源链接 | https://github.com/ClickHouse/agent-skills/tree/main/skills/clickhouse-js-node-rowbinary | — |
| 许可证 | Apache-2.0（仓库级 GitHub API 与子目录 package.json 均实测一致） | GitHub API / package.json |
| GitHub Stars / Forks | 所属仓库 496★ / 32 forks（该数字属整个 ClickHouse Agent Skills 合集，不代表本技能个体热度，仅供了解所属仓库规模） | GitHub API |
| 最新版本 | 配套 npm 包 @clickhouse/rowbinary v0.2.0；子目录最近一次提交 2026-06-30 |
子目录 package.json / 提交历史 |
| 安装方式 | npx skills add ClickHouse/clickhouse-js/skills/clickhouse-js-node-rowbinary（技能单装）或 npm install @clickhouse/rowbinary（连库带装，见第 9 章） |
仓库 README |
2. 功能介绍与亮点
clickhouse-js-node-rowbinary 教 agent 为 ClickHouse 的 RowBinary 系列二进制协议（RowBinary/RowBinaryWithNames/RowBinaryWithNamesAndTypes）生成专属的读写代码，而非直接调用一个黑盒库。
核心能力：
- 先判断该不该用 RowBinary：SKILL.md 开篇给出选型依据——字符串/JSON 为主的结果应优先用
JSONEachRow（V8 原生 JSON.parse 更快），只有宽数值类型（Int128/Decimal256）、二进制定长字段（UUID/IPv6/FixedString）或高吞吐定长数值列场景才该上 RowBinary - 读写双向：
reader.md/writer.md两份独立参考文档分别覆盖解码（字节→值）与编码（值→字节），并列出流式增量 vs 整缓冲区、行对象 vs 按列 typed array 等关键工程取舍 - 让 agent“现改代码”而非复用通用库：生成的定制化 parser 针对具体查询的列类型做 monomorphize（把多个字段的边界检查合并成一次、常量偏移量读取），实测比调用通用库快 1.5–3.4 倍
- 配套 112 个测试文件与
@clickhouse/rowbinarynpm 包（v0.2.0，含写入器新特性、类型安全加固），仓库自带按方向拆分的 eval 数据集
亮点：官方对该技能做了跨模型量化评测并公开发布——Sonnet 4.6 带技能后测试通过率从 60.4% 提升到 94.0%（+34pp），Opus 4.8 从 71.5% 到 94.7%（+23pp），Haiku 4.5 从约 52% 提升到 86.0%；ClickHouse 官方博客与官方 X 账号均发文专门介绍这一“库即 agent skill”的设计。
3. 适用场景
固定分类：工程效率与代码质量
- 用 Node.js 连接 ClickHouse、需要高吞吐读取或写入宽数值列（Int128/Decimal/UUID/IPv6 等）结果的后端开发者
- 需要为特定查询手写高性能二进制编解码器、又想避免从零实现踩坑（字节序、变长编码、精度丢失）的场景
- 用 agent 辅助生成数据管道代码、希望生成结果经过测试与基准验证而非“一次性能用就行”的团队
4. 跨 Agent 兼容性
- Claude Code：原生支持——技能遵循标准 SKILL.md 格式，
npx skills add安装器可自动识别.claude/skills/目录 - Codex / OpenClaw / Hermes Agent：支持——该技能与同仓库姊妹技能（如 clickhouse-js-node-coding）共用同一套安装器（npm 包
skills，源码仓库vercel-labs/skills），其src/agents.ts显式定义了codex、openclaw、hermes-agent三个 agent profile（分别探测$CODEX_HOME//etc/codex、~/.openclaw、~/.hermes/$HERMES_HOME）；仓库自身 README 的“Supported Agents”表未逐一列出 OpenClaw/Hermes，但安装器源码层面的支持面覆盖二者
以上结论基于已抓取材料判断，未为兼容性单独发起搜索。
5. 推荐理由
官方对该技能做了跨三模型的量化基准测试并公开数据，证明其确实把二进制协议编解码这一高出错率任务的正确率大幅提升，而非停留在文档承诺层面。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 子目录自身提交记录较少（近 1 个月内 1 次功能提交），但 ClickHouse 官方博客发布专题文章介绍该技能，官方 X 账号亦发文推广，官方渠道曝光度明显高于合集内多数仅有内部提交记录的同级子技能 |
| 可用性 | 9 | 单条命令即装；reader.md/writer.md/README/EXAMPLES/CHANGELOG 文档体系完整；112 个测试文件全部通过，另有跨三模型的评测结果公开可查；配套 npm 包持续迭代（0.2.0 新增写入器）；无付费依赖，可用于自建或云上任意 ClickHouse 实例 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单： ① 执行 shell 命令——技能本身是代码生成指导文档，不涉及执行任意 shell 命令；配套 npm 包按标准 Node.js 方式引入 ② 联网外发数据——生成的代码解析用户自己发起请求获得的响应数据，技能自身不涉及向第三方地址外发数据 ③ API key/凭据——不涉及新增凭据，沿用用户已有的 ClickHouse 连接配置 ④ 可疑指令——审阅 SKILL.md、reader.md、writer.md 全文及测试目录清单，内容均为透明的二进制协议编解码说明，未见 prompt injection 或混淆代码迹象 ⑤ 作者/组织信誉——ClickHouse Inc 官方仓库，提交者身份可核实为该公司员工 ⑥ License——Apache-2.0，仓库级与包级一致 ⑦ 维护时间——子目录最近一次提交 2026-06-30，一个月内，配套 npm 包仍在迭代
综合评分：8.3（三项均值）
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| clickhouse-js-node-coding（同合集内） | ClickHouse 官方 Node.js 客户端通用编码参考手册，覆盖插入/查询/参数化等 12 类场景 | 覆盖客户端 API 使用的方方面面，但不涉及二进制协议本身的编解码实现；本技能专攻 RowBinary 单一高性能场景，深度远超广度 |
| mongodb-connection（mongodb/agent-skills） | MongoDB 官方连接池配置与容量估算指导 | 解决连接管理这一横切关注点，不生成协议级编解码代码；本技能面向数据格式与序列化性能这一更底层的问题 |
| 通用 Protobuf/Avro 代码生成工具（非 skill，行业惯例参照） | 依赖独立的 schema 编译器生成静态代码 | 那类工具需要预先定义 schema 文件并运行编译步骤；本技能让 agent 在对话中直接依据查询的列类型现场生成定制代码，无需额外构建步骤 |
差异化核心在于“协议级性能优化”：多数数据库客户端技能止步于“如何正确调用 API”，本技能进一步给出如何针对具体数据形状生成比通用调用快数倍的专属编解码器,并用公开的跨模型评测数据证明这一路径确实有效。
8. 用户评价
该技能目前在 Reddit、Hacker News 等平台尚无具名用户评价；已发现的公开讨论均来自 ClickHouse 官方渠道（博客文章、官方 X 账号），第三方技能市场收录页面上的信息为聚合展示，未见独立用户就该技能发表具体使用体验。
9. 其他补充
该技能同时以 @clickhouse/rowbinary npm 包形式独立发布，README 中形容其设计理念为“库本身即是参考实现，注释即设计说明，SKILL.md 即代码生成策略”；仓库内还有 clickhouse-js-node-troubleshooting（报错排查）等互补技能可按需单独安装。
10. 安装使用方式
- 技能单装：
npx skills add ClickHouse/clickhouse-js/skills/clickhouse-js-node-rowbinary - 连库带装：
npm install @clickhouse/rowbinary后执行npx skills-npm setup，同时获得可直接调用的库 API 与配套技能 - ClickHouse 官方 CLI：
clickhousectl skills（安装整个 agent-skills 合集后按需勾选） - 手动安装：将
skills/clickhouse-js-node-rowbinary目录复制到对应 agent 的技能目录
安装后无需重启；当在 Node.js 环境中处理 ClickHouse 的 RowBinary/RowBinaryWithNames/RowBinaryWithNamesAndTypes 响应或需要生成高性能编解码器时会自动触发。
11. 注意事项
- 仅支持 Node.js 运行时，不覆盖浏览器端场景
- SKILL.md 明确指出 RowBinary 并非总是最优选择——字符串/JSON 为主的结果应优先使用
JSONEachRow等格式，盲目套用本技能可能得不偿失 - 写入器（encode 方向）覆盖度略低于读取器，个别解码专用路径（如
Dynamic/JSON类型的运行时头解析、按列 typed array 输出）尚未有对应的编码镜像 - 该子技能未出现在仓库顶层 README 的“Available Skills”清单中（该清单未及时更新覆盖全部子目录），但子目录自身 SKILL.md、测试与文档均完整，不影响可用性