1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | clickhouse-architecture-advisor-clickhouse-agent-skills |
| 项目自述名称 | ClickHouse Agent Skills（仓库自述名；本子技能自身标题为 “ClickHouse Architecture Advisor”） |
| 作者/维护者 | ClickHouse Inc（官方账号） |
| 来源链接 | https://github.com/ClickHouse/agent-skills/tree/main/skills/clickhouse-architecture-advisor |
| 许可证 | Apache-2.0（GitHub API 实测） |
| GitHub Stars | 495（GitHub API 实测；为 agent-skills 整仓库星数，仓库共含 11 个子技能，此数字不代表本子技能自身热度） |
| Forks | 32（GitHub API 实测） |
| 最新版本 | 0.1.0（技能自身 metadata.json，面向 ClickHouse 24.1+） |
| 安装方式 | npx skills add clickhouse/agent-skills 或官方 CLI clickhousectl skills（README） |
2. 功能介绍与亮点
在同仓库的 clickhouse-best-practices（逐条 SQL 规则）之上，补上“架构该怎么设计”这一层决策支持，覆盖 5 类真实存在的架构选型难题：
- 摄入策略：直接批量写入 / 异步插入 / Kafka 引擎+物化视图，按吞吐量与延迟容忍度决策
- 时间序列分区与保留：分区键与 TTL 设计
- 关联路径选择：JOIN / 字典 / 反范式化三者取舍
- 迟到数据与可变状态：处理乱序事件与 upsert 模式
- 实时预聚合：增量物化视图设计
亮点：① 每条建议强制标注 official（官方文档直接支持）/ derived（从官方行为推导）/ field（经验性、需声明启发式）三级来源，杜绝把经验之谈包装成官方结论；② 决策规则文件直接引用真实 ClickHouse 文档链接（如异步插入、Kafka 引擎、增量物化视图等官方页面），经抽查内容与 ClickHouse 官方文档一致；③ 输出格式固定为“负载摘要→关键决策→建议（What/Why/How/来源标注/验证方法）”，结构化程度高；④ 纯 Markdown/YAML 规则文件，不含任何可执行脚本。
3. 适用场景
固定分类：数据分析与可视化
面向正在为可观测性、安全日志（SIEM）、产品分析、IoT 遥测、金融行情等实时分析场景设计 ClickHouse 系统架构的数据工程师与后端工程师——尤其是需要在“摄入方式该选哪种”“JOIN 还是字典查找”“怎么处理迟到数据”这类系统级权衡上给出可追溯依据、而非泛泛而谈的场合。与偏重表结构与单条查询审查的 clickhouse-best-practices互补，后者管“写法对不对”，本技能管“架构该怎么搭”。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库自带
.claude-plugin/marketplace.json市场清单，官方安装命令的目标目录表中列有.claude/skills/ - Codex：原生支持——官方安装命令的目标目录表明确列出 Codex，对应目录为
.codex/skills/ - OpenClaw：未验证——抓取材料中未出现相关声明
- Hermes Agent：未验证——抓取材料中未出现相关声明
5. 推荐理由
多数厂商技能停留在“规则检查”层面，本技能额外解决的是 agent 在系统设计对话里最容易露怯的问题：把没有文档依据的经验判断说得像官方结论一样笃定。强制的三级来源标注让 agent 在给架构建议时必须诚实区分“文档写的”“推出来的”“纯经验的”，对摄入策略、分区、关联这类一旦选错就要返工重建的高成本决策尤其有价值。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 子目录本身无独立 star 计数，仓库整体 495 星不可作为本子技能依据；经 GitHub code search 交叉验证，本技能已被官方 GitHub 账号维护的 github/agentfinder-catalog、stacklok/toolhive-catalog 两个技能目录收录，并被 AI 编程 agent Cline 的官方仓库 cline/skills 直接引入（归入其 data-analyst 技能集），另见于 VoltAgent/awesome-agent-skills 精选列表，代码搜索命中约 123 处引用（数字为近似估计）；仓库自 2026-04-14 起两次提交后未见进一步更新 |
| 可用性 | 9 | npx skills add clickhouse/agent-skills 或官方 CLI clickhousectl skills 一条命令安装；内容为纯 Markdown/YAML 决策文件，无需额外依赖或付费账号，开源自建 ClickHouse 或使用 Cloud 免费额度均可完整使用；文档含 SKILL.md、编译版 AGENTS.md、5 份决策规则文件与示例目录，结构完整 |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合 | 8.3 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行 | 无——技能全部内容为 Markdown 决策文档与 YAML 映射表，不含任何脚本或可执行代码 |
| ② 联网外发 | 无默认外联；建议中引用的官方文档链接仅供 agent 参考，不涉及技能自身联网行为 |
| ③ API key/凭据 | 不需要——本技能仅输出架构建议文本，不连接数据库、不处理凭据 |
| ④ 可疑指令 | 抽查 SKILL.md、README 与全部 5 份决策规则文件，未发现要求执行特权操作或数据外发的可疑指令 |
| ⑤ 作者信誉 | ClickHouse Inc 官方 GitHub 组织账号，metadata.json 注明出品方与发布月份 |
| ⑥ License | Apache-2.0，明确 |
| ⑦ 维护时间 | 最近一次提交为 2026-05-19（修复 YAML 语法），距今约两个月 |
7. 跟同类 Skills 相比的优势
同为数据库/数据平台官方出品、聚焦“设计与优化”的技能与本技能的定位差异：
| 技能 | 出品方 | 覆盖层次 | 是否需付费账号 |
|---|---|---|---|
| ClickHouse Architecture Advisor（本次推荐） | ClickHouse Inc | 系统架构层：摄入/分区/关联/迟到数据/预聚合的 5 类决策框架，官方/推导/经验三级标注 | 否，开源自建即可用 |
| ClickHouse Best Practices（同仓库姊妹技能） | ClickHouse Inc | Schema 与单条查询层：31 条规则配 SQL 对照示例 | 否 |
| DuckDB Skills | DuckDB 官方 | 本地文件查询执行层：6 个协同子技能，含查询沙箱 | 否 |
| Databricks Agent Skills | Databricks | 企业级 Lakehouse 全栈：28 个子技能覆盖摄入/建模/看板/机器学习全流程 | 需付费工作区 |
差异化在于分层定位：Best Practices 管“写法对不对”，Architecture Advisor 管“架构该怎么搭”，二者互补而非重叠；相比 Databricks 的全栈式覆盖，ClickHouse 这一对技能都不依赖企业级付费工作区，个人开发者用开源版本即可完整体验。
8. 用户评价
该技能已被 GitHub 官方维护的 agent 技能目录 agentfinder-catalog、技能注册表 stacklok/toolhive-catalog 收录，并被 AI 编程 agent Cline 的官方技能仓库直接引入，但目前未见具名的独立用户评价内容。
9. 其他补充
仓库遵循 agentskills.io 开放技能规范；同仓库另有 clickhouse-best-practices（规则层）、chdb-sql/chdb-datastore（Python 内嵌分析）、clickhousectl-local-dev/clickhousectl-cloud-deploy（部署）等其他技能，均可按需单独安装。
10. 安装使用方式
- 推荐方式：
npx skills add clickhouse/agent-skills，CLI 会自动检测已安装的 agent 并询问装到哪个目录 - ClickHouse 官方 CLI：
clickhousectl skills - 手动安装：将仓库
skills/clickhouse-architecture-advisor/整个目录复制进目标 agent 的技能目录即可，符合 Agent Skills 开放规范的 agent 均可直接加载 - 安装后无需重启；agent 在用户讨论实时摄入策略、分区设计、JOIN 与字典取舍、迟到数据处理或预聚合方案时会自动触发本技能
11. 注意事项
- 内容面向 ClickHouse 24.1+ 版本设计的行为与配置项，过旧版本可能不完全适用
- 本技能是合集仓库
ClickHouse/agent-skills中的一个子目录，只需要架构级建议时安装本子技能即可，配合clickhouse-best-practices使用效果更完整 - Codex 外的 OpenClaw、Hermes Agent 兼容性未获官方明确声明，跨 agent 使用前建议自行验证
- 技能定位是“决策建议”而非自动执行——不会自动应用架构变更，输出的建议仍需工程师评估后自行落地