# AI编程智能技能集

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

# Agent Skills — MooseStack + ClickHouse

一组技能集合，为 AI 编程助手扩展特定领域专业知识，用于基于 [MooseStack](https://docs.fiveonefour.com/moosestack) 和 [ClickHouse](https://clickhouse.com/docs) 构建数据应用。

## 安装

```bash
npx skills add 514-labs/agent-skills
```

支持 Claude Code、Cursor、Copilot、Windsurf、Gemini CLI、Codex 以及 [20+ 其他智能体](https://agentskills.io)。

## 技能列表

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

### 工作流关系图

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

---

## clickhouse-best-practices

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

### 适用场景

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

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

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

### 内容概览

**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/`](./skills/clickhouse/best-practices/) | 易读概览：[SKILL.md](./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 服务器](https://docs.fiveonefour.com/moosestack/moosedev-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](https://docs.fiveonefour.com/moosestack) | [ClickHouse](https://clickhouse.com/docs)

---

## production-rollout-plan

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

### 阶段

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

### 使用方式

```
/production-rollout-plan [project-slug]
```

### 前置条件

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

**文档：** [MooseStack](https://docs.fiveonefour.com/moosestack) | [ClickHouse](https://clickhouse.com/docs)

---

## 支持的智能体

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

| 智能体 | 配置目录 |
|-------|------------------|
| [Claude Code](https://claude.ai/code) | `.claude/skills/` |
| [Cursor](https://cursor.sh) | `.cursor/skills/` |
| [Windsurf](https://codeium.com/windsurf) | `.windsurf/skills/` |
| [GitHub Copilot](https://github.com/features/copilot) | `.github/skills/` |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `.gemini/skills/` |
| [Cline](https://github.com/cline/cline) | `.cline/skills/` |
| [Codex](https://openai.com/codex) | `.codex/skills/` |
| [Goose](https://github.com/block/goose) | `.goose/skills/` |
| [Roo Code](https://roo.ai) | `.roo/skills/` |
| [OpenHands](https://github.com/All-Hands-AI/OpenHands) | `.openhands/skills/` |

以及 [另外 13 个](https://agentskills.io)。

## 致谢

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

## 许可证

Apache 2.0 — 详见 [LICENSE](./LICENSE)。