一、背景：AI 写 SQL，为什么总是「差那么一口气」？
2026 年，AI 编码助手已经无处不在。Claude Code、Cursor、GitHub Copilot......它们能在几秒钟内生成逻辑清晰的 SQL，帮你完成 CRUD、JOIN、窗口函数，甚至数据迁移脚本。但作为长期与数据库打交道的 DBA，你一定踩过这样的坑：
⚠️ 典型踩坑场景
AI 生成的 SQL 在本地 MySQL 跑得飞快，上线到分布式数据库（如 TiDB）后，要么执行计划跑偏、要么事务死锁、要么主键热点让写入 QPS 断崖式下跌。更可怕的是：AI 并不知道它错了。
根本原因在于：AI 工具具备通用语言能力，却缺少特定数据库的领域知识。
- 它知道
AUTO_INCREMENT，但不知道在 TiDB 的分布式架构下这会造成写入热点； - 它会写
BEGIN ... COMMIT，但不清楚悲观锁与乐观锁在高并发场景下的行为差异； - 它能生成 TLS 连接代码，但很可能默认跳过证书验证......
「大多数数据库事故并非因为语法错误，而是因为缺少上下文。」------ PingCAP 工程博客
正是为了弥补这一鸿沟，PingCAP 开源了 pingcap/agent-rules（AgenticStore），一个专为 AI 代码助手设计的「数据库技能包」。
二、pingcap/agent-rules 是什么？
pingcap/agent-rules 是 PingCAP 维护的一个开源仓库，官方定位是：
AgenticStore ------为代码 Agent 设计和整理可复用 SKILLS 的仓库。专注于面向 Agentic App 的数据库配置工作流，当前主要支持 TiDB Cloud 作为数据库提供商。
简单来说，它把 PingCAP 工程师多年积累的 TiDB/MySQL 运维经验，打包成一份份小型「技能文档」，让 AI Agent 在编写代码时能够动态检索、按需注入------就像给 AI 配备了一本专家手册。
核心理念
与直接在 Prompt 里堆砌长篇规则不同，AgenticStore 采用了模块化、按需加载的设计：
① 选择（Select）
Agent 根据任务上下文（如「为 TiDB 写 Schema」）选择对应的技能目录，例如 skills/tidb-sql。
② 检索（Retrieve）
从技能目录的 references/ 子目录中按需提取相关规则，如 transactions.md、auto-random.md，不一次性加载全部文档。
③ 应用（Apply）
将规则作为约束条件，驱动代码生成，避免依赖通用猜测，产出符合生产环境要求的代码。
这种设计比「把所有规则塞进 CLAUDE.md」更高效：每次只加载与任务相关的片段，既节省上下文窗口，又避免规则之间的干扰。
三、AgenticStore 的核心设计：SKILL 体系
目录结构规范
每个技能是一个独立目录，命名使用小写字母、数字和连字符，核心文件结构如下：
# 以 tidb-sql 为例
skills/tidb-sql/
├── SKILL.md # 技能入口文件（含 YAML 元数据 + 工作流）
├── references/ # 专项参考文档（按需检索）
│ ├── auto-random.md
│ ├── transactions.md
│ ├── full-text-search.md
│ ├── mysql-compatibility-notes.md
│ ├── explain.md
│ ├── vector.md
│ ├── flashback.md
│ └── tidb-cloud-ssl.md
└── scripts/ # 可执行脚本或模板（可选）
└── collect_diag_info.sqlSKILL.md 的结构约定
每个 SKILL.md 都包含 YAML 格式元数据 + 结构化正文，让 AI Agent 能快速解析意图：
---
name: tidb-sql
description: "编写、审查和适配 TiDB SQL..."
when_to_use:
- "生成必须在 TiDB 上运行的 SQL"
- "将 MySQL SQL 迁移到 TiDB"
- "调试 TiDB SQL 兼容性错误"
tools: ["sql_executor", "explain_analyzer"]
---
## 工作流
1. 识别目标引擎和版本
2. 关键能力确认（TiFlash、全文搜索等）
3. 生成 TiDB 安全 SQL
...💡 设计哲学
保持简洁、实用、可组合。 每份技能文档力求「能被 AI 直接执行」，而非「给人类阅读的 Wiki」。长篇参考资料统一放到references/，SKILL.md 只保留工作流骨架和高价值规则。
四、12 个内置技能全览
截至 2026 年 4 月，仓库共包含 12 个技能模块，覆盖数据库核心操作到全栈框架集成：
| 技能名称 | 图标 | 功能描述 |
|---|---|---|
tidb-sql |
🗄️ | TiDB SQL 编写与迁移，处理 TiDB/MySQL 兼容性差异的核心技能 |
tidb-query-tuning |
🔍 | 慢查询诊断与优化，含执行计划分析、统计信息管理六步工作流 |
tidbx |
☁️ | TiDB Cloud 完整生命周期管理：创建、连接、配置、销毁 |
tidb-cloud-zero |
⚡ | 零配置快速启动 TiDB Cloud Serverless 集群的精简技能 |
tidbx-serverless-driver |
🚀 | Serverless HTTP 驱动使用指南，边缘运行时（Edge Runtime）最佳实践 |
pytidb |
🐍 | Python + TiDB 开发：连接池、ORM 集成、向量搜索等配置 |
mysql |
🐬 | 通用 MySQL 最佳实践，部分规则（如 TLS 配置）可复用于 TiDB |
tidbx-kysely |
🔧 | Kysely 查询构建器集成模式（TCP + Serverless/边缘环境双版本） |
tidbx-prisma |
🔷 | Prisma ORM 接入 TiDB：Schema 定义、数据库迁移、类型化客户端 |
tidbx-nextjs |
▲ | Next.js App Router + TiDB 集成，覆盖 Vercel/Serverless 部署场景 |
tidbx-javascript-mysql2 |
🟨 | Node.js mysql2 驱动生产级配置，连接池与 TLS 安全设置 |
tidbx-javascript-mysqljs |
🟩 | Node.js mysqljs 驱动接入 TiDB 的兼容性配置与注意事项 |
五、重点技能深度剖析
5.1 tidb-sql：从「能跑」到「安全」
这是整个仓库最核心的技能。它系统梳理了 TiDB 与 MySQL 的差异，并告诉 AI Agent 如何生成「TiDB 安全」的 SQL。
① 主键热点 ------ AUTO_INCREMENT vs AUTO_RANDOM
在分布式数据库中，AUTO_INCREMENT 生成的自增主键会集中写入同一个 Region，造成写入热点，严重限制并发写入性能。
| 场景 | 通用 AI 生成 | 接入 tidb-sql 技能后 |
|---|---|---|
| 创建用户表 | id BIGINT AUTO_INCREMENT PRIMARY KEY ❌ |
id BIGINT PRIMARY KEY AUTO_RANDOM ✅ |
| 高并发写入 | 所有写入集中在同一 Leader Region，吞吐受限 | ID 分散到全局多个 Region，线性扩展写入 |
-- ❌ 通用 AI 可能生成
CREATE TABLE users (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) NOT NULL
);
-- ✅ tidb-sql 技能引导生成（避免写入热点）
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_RANDOM,
email VARCHAR(255) NOT NULL
);② 事务模式 ------ 悲观锁 vs 乐观锁的选择
TiDB 同时支持悲观事务和乐观事务，而通用 AI 往往默认使用 BEGIN（假设悲观锁行为），在高冲突场景下可能引发大量重试甚至死锁。tidb-sql 技能包含 transactions.md，告诉 AI 如何根据冲突频率选择事务模式，并自动添加重试逻辑：
-- 高冲突场景：使用悲观事务（更接近 MySQL 行为）
BEGIN PESSIMISTIC;
UPDATE account SET balance = balance - 100 WHERE id = 1;
UPDATE account SET balance = balance + 100 WHERE id = 2;
COMMIT;
-- 低冲突场景：使用乐观事务（更高吞吐，需应用层处理重试）
BEGIN OPTIMISTIC;
-- ... DML ...
COMMIT; -- 遇到写冲突会报错，应用需捕获并重试③ 其他覆盖的差异点
- 向量支持：TiDB 特有 VECTOR 类型和向量函数/索引（MySQL 不支持）
- 全文搜索：TiDB 自有实现，与 MySQL FULLTEXT 不完全兼容
- 外键支持：仅 TiDB v6.6.0+ 版本支持
- 程序化对象：不支持存储过程、函数、触发器、事件
- 几何/空间类型：TiDB 不支持 GEOMETRY/SPATIAL 相关功能
5.2 tidb-query-tuning：六步慢查询诊断工作流
这是面向 DBA 最有价值的技能之一。它将 TiDB 慢查询分析标准化为一个清晰的六步工作流：
Step 1 --- 捕获执行计划
使用 EXPLAIN ANALYZE 获取实际执行统计，比较 estRows（预估行数）与 actRows（实际行数）；使用 PLAN REPLAYER DUMP 收集完整现场快照。
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 12345;
-- 重点关注 estRows vs actRows 差异，差异大 → 统计信息过期Step 2 --- 检查统计信息健康度
SHOW STATS_HEALTHY WHERE Healthy < 80;
-- 健康度低于 80 时，更新统计信息
ANALYZE TABLE orders;⚠️ 核心规则：大多数糟糕的执行计划根因在统计信息过期，而非优化器 Bug。先检查统计信息，再怀疑优化器。
Step 3 --- 识别瓶颈模式
根据症状参考对应专项文档，优先查阅内置的历史案例库（references/optimizer-oncall-experiences/）：
- 错误的连接顺序 → 查看
join-reorder.md - 子查询问题 → 查看
subquery.md - 索引选错 → 查看
index-selection.md
Step 4 --- 本地复现
tiup playground v7.5.0 # 启动本地 TiDB 环境
# 然后加载 PLAN REPLAYER 快照复现问题Step 5 --- 应用修复（侵入性由低到高）
刷新统计信息 → 添加索引 → 创建 SQL Binding → 使用 Optimizer Hint → 调整 Session 变量⚠️ 注意 ：清理全局绑定需用
DROP GLOBAL BINDING，不要直接删除mysql.bind_info表记录！否则可能需要重启 TiDB 才能完全清除缓存。
Step 6 --- 验证改进效果
再次运行 EXPLAIN ANALYZE，确认执行计划和性能均已改善。
5.3 tidbx-nextjs + tidbx-prisma：全栈 Agentic App 场景
随着 AI 应用（Agentic App）的兴起，越来越多的开发者需要快速构建「AI + 数据库」的全栈应用。这两个技能专门应对 Next.js + Prisma + TiDB Cloud 的生产部署场景，覆盖：
- SSL 连接配置
- Connection Pool 调优
- Edge Runtime 兼容性
- Vercel 部署最佳实践
- Schema Migration
- 类型安全客户端生成
✅ 典型效果：通过这些技能，AI Agent 生成的 Next.js API Route 代码会自动包含 TiDB Cloud SSL 证书验证、连接池复用（避免 Serverless 环境下频繁建立连接），以及 Prisma schema 中 TiDB 不支持功能的替换方案。
六、快速上手：三步接入
方式一：通过 npx 安装（推荐）
# 将 pingcap/agent-rules 中的所有技能安装到当前 AI 工具配置
npx skills add pingcap/agent-rules安装后，支持 Claude Code、Cursor 等主流 AI 编码工具的技能加载，Agent 会自动根据任务上下文调用相关技能，无需手动触发。
方式二：手动引用特定技能
如果只想使用某一个技能，可以将对应 SKILL.md 的内容直接包含到你的 CLAUDE.md、.cursorrules 或项目上下文中：
## Skills
@skills/tidb-sql/SKILL.md
@skills/tidb-query-tuning/SKILL.md方式三：克隆仓库自定义
git clone https://github.com/pingcap/agent-rules.git
cd agent-rules/skills
# 查看某个技能的具体内容
cat tidb-sql/SKILL.md
# 按需修改、贡献新技能或 PR 到官方仓库💡 使用建议
对于新接触 TiDB 的团队，建议先从 tidb-sql + tidb-query-tuning 两个技能入手；构建全栈 AI 应用时再叠加框架集成技能。不要一次性加载全部 12 个技能，按需加载效果更好。
七、DBA 视角：对我有什么价值？
7.1 从「被动救火」到「主动注入经验」
传统工作模式下，DBA 的知识沉淀往往停留在 Wiki、运维手册或个人脑袋里，难以系统化地传递给开发团队。AgenticStore 的思路是：把专家经验结构化成 AI 可理解的格式，让 AI 代替你在每次代码生成时检查规范。
类比到日常工作，可以考虑为自己维护的数据库环境编写类似的技能文件：
| 场景 | 可沉淀为技能的内容 |
|---|---|
| PostgreSQL 日常运维 | 连接池配置规范、EXPLAIN ANALYZE 解读工作流、常见慢查询模式 |
| MySQL 巡检 | 关键参数检查清单、主从延迟诊断步骤、索引使用率检查 SQL |
| Grafana 监控 | 告警阈值规范（CPU 40-75%、内存 40-70%）、巡检报告生成流程 |
| 团队规范 | SQL 审查 Checklist、部署变更影响评估框架 |
7.2 AI Agent + 专业知识库 = 运维自动化的新范式
AgenticStore 本质上是 PingCAP 在探索一种新的知识管理模式：不是写文档给人看，而是写「技能」给 AI 执行。在运维自动化领域，这与构建运维中台的方向高度契合------用结构化的专家知识驱动 AI Agent，实现从「人工执行」到「智能执行」的跃迁。
7.3 局限性需清醒认识
⚠️ 注意事项
- 技能覆盖范围目前以 TiDB/MySQL 生态为主，PostgreSQL 生态尚未覆盖
- 技能质量依赖维护者的经验深度，需定期审查更新
- 不能替代人工代码审查------生产变更仍需经验丰富的工程师把关
- AI 可能「选错技能」或「误用规则」，需要配合良好的测试环境验证
八、思考与展望
PingCAP 通过 pingcap/agent-rules 向业界展示了一个有趣的命题：数据库厂商如何在 AI 编程时代保持技术影响力。答案不是强推 IDE 插件，而是把自己的领域知识以开放、可组合的形式提供给 AI Agent。
这背后的趋势值得关注：
🔖 Agent Skills 标准化
随着 Claude Code、Cursor 等工具竞争加剧，技能/规则格式的标准化是大势所趋。谁能建立生态，谁就能影响 AI 代码生成的质量。
🔖 领域知识资产化
企业多年积累的运维经验、最佳实践，正在成为构建 AI Agent 能力的核心竞争力。「把知识写成技能文件」将是 DBA/SRE 的新职责之一。
🔖 Agentic App 的数据库需求
向量搜索、全文检索、高并发事务......AI 应用对数据库提出了全新要求，AgenticStore 的 TiDB 技能包已经开始覆盖这些场景。
我们正在进入一个新时代：代码不只是人写的，而是人与 AI 协作写的。在这个时代，如何把专家经验喂给 AI，比如何使用 AI 更重要。pingcap/agent-rules 是这个方向上一个值得学习的探索。
参考资源
- 📦 GitHub 仓库 ：github.com/pingcap/agent-rules
- 📝 官方博客 ：Teaching AI Agents to Speak "Production" SQL
- 📖 TiDB for AI 文档 ：docs.pingcap.com/zh/ai/
- 🔧 Claude Code + TiDB MCP ：开始使用指南