catalog/repos/514-labs--agent-skills.md

AI编程智能技能集

AI编程助手 ClickHouse 数据应用 MooseStack 技能扩展

Agent Skills — MooseStack + ClickHouse

一组技能集合，为 AI 编程助手扩展特定领域专业知识，用于基于 MooseStack 和 ClickHouse 构建数据应用。

安装

npx skills add 514-labs/agent-skills

支持 Claude Code、Cursor、Copilot、Windsurf、Gemini CLI、Codex 以及 20+ 其他智能体。

技能列表

技能	类型	描述
clickhouse-best-practices	参考规范（28 条规则）	模式设计、查询优化与数据写入最佳实践 — ClickHouse SQL + MooseStack TypeScript & Python
514-cli	工作流	514 CLI 基础操作 — 登录、关联项目、查看部署状态、浏览文档
514-debug	工作流	部署调试 — 状态检查、日志追踪、慢查询发现、资源检查、诊断 SQL
perf-optimize	工作流（7 个阶段）	端到端优化与基准测试：分析生产环境、提出候选方案、对比冻结基线与实验分支、汇总结果并合并最优 PR
production-rollout-plan	工作流（5 个阶段）	生产发布规划：对选定变更进行分类、定义发布/验证/回滚步骤，并审查安全的生产上线路径

工作流关系图

• perf-optimize -> production-rollout-plan
• 一旦确定了具体变更，也可直接单独使用 production-rollout-plan

---

clickhouse-best-practices

Fork 自 ClickHouse/agent-skills，提供 28 条经过实战验证的规则，涵盖模式设计、查询优化和数据写入 — 均基于 ClickHouse SQL。我们在每条规则中加入了 MooseStack TypeScript 和 Python 示例，让智能体在编写应用代码（而不仅仅是原始 DDL）时同样遵循这些规范。

适用场景

团队使用 MooseStack + ClickHouse 在应用中构建分析功能 — 这类功能对性能、模式设计和数据建模要求极高，直接影响最终用户体验。本技能确保智能体从一开始就做出正确的决策。

高性能的面向用户仪表盘。 用户期望图表和筛选器能在毫秒内响应。当分析查询超出事务数据库承载能力时，迁移到 ClickHouse 可带来 10–100 倍的性能提升 — 但前提是模式必须针对实际访问模式进行设计。本技能引导智能体选择正确的 orderByFields、分区方式和数据类型，使数据模型从第一天起就具备良好性能。

应用内数据驱动的对话功能。 LLM 现在可以通过 MCP 查询数据库，将自然语言转化为实时分析结果。答案质量取决于数据建模水平：清晰的模式、合理的类型选择以及预聚合正确维度的物化视图。本技能确保智能体构建出支持对话的数据模型，返回快速、准确的结果。

内容概览

28 条规则，每条均包含 ClickHouse SQL + MooseStack TypeScript + MooseStack Python 示例：

类别	规则数	影响程度	示例
排序键 / orderByFields	4	关键	按基数从低到高排列列，优先考虑过滤列
类型选择	5	关键	优先使用原生类型，减少位宽，避免 Nullable
JOIN 优化	5	关键	先过滤再连接，单值匹配使用 ANY
批量写入	1	关键	每批 1 万至 10 万行
避免 Mutation	2	关键	禁止 ALTER TABLE UPDATE/DELETE
分区	4	高	生命周期管理，基数控制在 1000 以内
跳数索引	1	高	针对非 ORDER BY 过滤字段使用布隆过滤器
物化视图	2	高	实时场景用增量方式，批处理用可刷新方式
异步写入	2	高	适用于高频小批量写入
避免 OPTIMIZE	1	高	让合并自然发生
JSON 使用	1	中	动态模式使用 JSON 类型

浏览规则：skills/clickhouse/best-practices/ | 易读概览：SKILL.md

示例提示词

以下是我们的源数据样本 [粘贴模式或 CSV 头]。我们的查询主要按地区和时间范围过滤。请使用 clickhouse-best-practices-ts-py 技能，创建一个优化的 TypeScript 数据模型，设置正确的 orderByFields、分区方式和类型注解。使用 moose query 验证该表在这些访问模式下的性能。

请使用 clickhouse-best-practices-ts-py 技能，对照 app/dashboard/ 下 Next.js 前端中的查询，审查这个 OlapTable 定义。根据实际的过滤和 GROUP BY 模式，orderByFields 的顺序是否正确？某些字符串列是否应设为 LowCardinality？这些字段上的 Nullable 是否合理？

我需要追踪含履行状态频繁更新的订单行项目。请使用 clickhouse-best-practices-ts-py 技能，推荐应使用哪种表引擎和数据模型来避免 Mutation？请展示 TypeScript 和 Python 两个版本。

不一定需要明确指定技能名称 — 大多数智能体在遇到 ClickHouse 或 MooseStack 上下文时会自动激活。当我们希望对完整规则集进行正式审查时，才会显式调用它。

为获得最佳效果，建议在本地运行 moose dev 并将 MooseStack MCP 服务器 接入智能体。这样智能体可以查询本地 ClickHouse、检查基础设施，并用真实数据验证其建议。

---

514-cli

514 平台的基础工作流技能。教会智能体如何进行身份验证、发现项目、检查已部署的模式并运行指标查询 — 这些是其他 514 工作流技能（如 perf-optimize 和 production-rollout-plan）所依赖的基础能力。

章节

章节	内容
身份验证	登录、whoami、切换组织
项目	列表、关联、初始化
部署	列举与筛选部署
文档	在终端中搜索和浏览 514 文档

前置条件

• 514 CLI — 已安装并加入 PATH

---

514-debug

用于诊断部署问题的工作流技能。当出现故障或异常行为时，本技能引导智能体通过 514 CLI 的可观测性命令排查问题。

章节

章节	内容
部署状态	健康检查、状态过滤、分支定位
日志	错误过滤、全文搜索、时间范围、实时追踪
查询指标	慢查询、内存占用高的查询、耗时/行数过滤
资源检查	表、视图、流、函数、端点、同步任务
诊断查询	即席 ClickHouse SQL — 表大小、运行中的查询、近期错误

前置条件

• 514 CLI — 已安装并加入 PATH

---

perf-optimize

一个工作流技能，引导智能体对 514/Moose 部署中的 ClickHouse 进行性能分析、基准测试和优化方案筛选。涵盖生产环境发现、候选方案生成、冻结基线创建、实验分支基准测试、结果对比和 PR 创建。生产发布规划由独立技能负责。

阶段

阶段	目标
SETUP（初始化）	通过 514 CLI 进行身份验证，确定目标项目和活跃部署，并获取基线 DDL
PROFILE（分析）	获取生产模式和查询数据，进行分析，并将热点查询模式映射回代码
PROPOSE（提案）	展示候选优化方案，并获得用户对要运行的实验的确认
BASELINE（基线）	搭建基准测试框架，创建冻结控制分支，并对基线部署进行基准测试
EXPERIMENT（实验）	在实验分支上运行已批准的优化方案，并对每个候选方案进行基准测试
COMPARE（对比）	对基线与候选结果进行排名，选出最优方案
SHIP（发布）	附带基准测试数据创建最优 PR，并移交给 production-rollout-plan 进行生产发布规划

使用方式

/perf-optimize [project-slug]

若提供了项目 slug，智能体将跳过项目选择提示；否则列出可用项目并请用户选择。

前置条件

• 514 CLI — 已完成身份验证（514 auth login）
• git — 本地可用，用于创建基线/候选分支
• gh CLI — 本地可用，用于创建最优 Pull Request
• moose — 本地可用，包括 moose add benchmark 和 moose dev
• pnpm — 基准测试套件可用
• 一个至少有一个活跃部署的 514/Moose 项目

文档： MooseStack | ClickHouse

---

production-rollout-plan

一个工作流技能，用于为 514/Moose 部署中已选定变更的安全生产发布进行规划。该技能不与基准测试强绑定，可在任何实现工作流确定变更后直接使用。

阶段

阶段	目标
SETUP（初始化）	确定项目、分支、选定变更及受影响的生产资源
CLASSIFY（分类）	确定发布类型和操作风险
PLAN（规划）	定义发布、验证、回滚、数据回填和切换步骤
REVIEW（审查）	展示计划供审批和修订
HANDOFF（移交）	输出已审批的发布计划

使用方式

/production-rollout-plan [project-slug]

前置条件

• 514 CLI — 已完成身份验证（514 auth login）
• moose — 需要本地资源检查时在本地可用
• 一个至少有一个活跃生产部署的 514/Moose 项目

文档： MooseStack | ClickHouse

---

支持的智能体

安装程序会自动检测您已有的智能体。技能与智能体无关 — 同一套技能，适用于所有助手：

智能体	配置目录
Claude Code	.claude/skills/
Cursor	.cursor/skills/
Windsurf	.windsurf/skills/
GitHub Copilot	.github/skills/
Gemini CLI	.gemini/skills/
Cline	.cline/skills/
Codex	.codex/skills/
Goose	.goose/skills/
Roo Code	.roo/skills/
OpenHands	.openhands/skills/

以及 另外 13 个。

致谢

ClickHouse 团队的 agent-skills 仓库完成了将 ClickHouse 最佳实践编码为智能体可消费规则的艰难工作。没有它，就不会有本项目。

许可证

Apache 2.0 — 详见 LICENSE。