pgbot Skill：给 AI Agent 装上 PostgreSQL 诊断能力

pgbot Skill：给 AI Agent 装上 PostgreSQL 诊断能力

AI Agent 能写代码、跑命令、管文件，但面对”数据库为什么这么慢”这类问题，通常只能靠猜——没有内置的数据库感知能力。pgbot 解决的就是这个缺口：它是一个纯读 PostgreSQL 诊断工具，以 MCP 工具 + Agent Skill 的形式，给任何 AI Agent 赋予专业的数据库健康检查能力，而且所有发现均由 Go 程序确定性计算，AI 只负责解释和排序，不负责”发明”诊断结论。

核心能力与设计原则

pgbot 的本质是一套”只读观察”系统：

• 只读优先：所有操作（inspect / top_queries / vacuum_health / unused_indexes）均为只读，从不写入数据库，AI 通过它无法破坏任何数据
• 确定性计算：诊断结论由 Go 程序从 PostgreSQL 统计视图直接读取，不是模型推理出来的，避免幻觉
• 发现优先（Findings-first）：输出的是结构化发现列表，每个发现带置信度标签和完整 caveat，AI 必须携带每个警告才能给出建议
• MCP 协议：以 Model Context Protocol 对外暴露工具，Claude Code、Cursor、Codex 等主流 AI 编码工具开箱即用
• Skill 层：附带的 postgres-diagnostics Skill 定义了一套”何时用哪个命令、如何解读结果、如何排序优先级”的工作流，让 Agent 真正像 DBA 一样思考

认可度

• GitHub star：796（截至 2026-08-28）
• 本周增长：发布不久即在 skilld.dev trending 出现，被 ClaudePluginHub 收录
• 社区覆盖：ClaudePluginHub 收录为正式 Plugin，附 3 个 slash 命令（/pg-health、/pg-slow、/pg-indexes）
• 维护状态：GitHub 显示最近 3 小时有提交，维护活跃（Excellent）

链接

GitHub：https://github.com/pgrundev/pgbot

原作者

GitHub 用户 pgrundev，项目采用 MIT 许可证。同时维护 pgbot.dev 官网和安装脚本，提供一键安装和完整的 Skill/Plugin 分发。

介绍

pgbot 最初是一个独立的 Go CLI 工具，专注于 PostgreSQL 的只读诊断。它的核心价值在于把 DBA 的专业经验编码成可执行的检查规则，让任何有数据库连接权限的人（无论是人类还是 AI Agent）都能得到一致、可靠的诊断报告。

在 AI Agent 场景下，pgbot 采用了”MCP 工具 + Skill 工作流”的双层设计：

MCP 工具层（pgbot mcp）：通过 stdio 对接 AI Agent，提供结构化 JSON 返回，包含：inspect（完整健康报告）、top_queries（按执行时间排序的查询）、vacuum_health（自动清理状态）、unused_indexes（未使用索引）、suggest_indexes（基于 hypopg 的索引建议）等。每个工具返回稳定 JSON 格式，带 exactness 标签。

Skill 层（postgres-diagnostics）：定义何时调用哪个命令、如何解读结果、优先级如何排序。例如：发现”未使用索引”时，必须携带”扫描计数是按节点统计的，副本能看到主节点看不到的索引使用情况”这一警告；发现慢查询时，必须标注”单个查询占 DB 总执行时间 30% 以上才是真正的热点，删索引解决不了它”。

这种”工具提供数据、Skill 提供判断框架”的分离设计，让 pgbot 既适合人类 DBA 使用，也适合 AI Agent 自动化调用。

特点

• 零破坏风险：所有操作只读，AI 无法通过 pgbot 对数据库执行任何写操作
• 确定性诊断：发现由 Go 程序计算而非模型推理，不存在”AI 虚构表名或索引名”的问题
• MCP 原生集成：Claude Code、Cursor、Codex 等主流工具一条命令接入，无需额外配置
• 三命令全家桶：/pg-health（综合健康检查）、/pg-slow（慢查询分析）、/pg-indexes（索引诊断），覆盖 DBA 日常三大场景
• caveat 内嵌：每个发现携带完整警告条件，Skill 层强制要求 AI 将警告纳入建议，避免盲目优化

使用方法

安装 pgbot 二进制：

curl -fsSL https://pgbot.dev/install | sh

方式一：直接 CLI 调用（适合人类 DBA）

export DATABASE_URL="postgres://pgbot_ro@host:5432/db"
pgbot inspect                    # 综合健康报告
pgbot queries "$DSN"             # 慢查询 Top N
pgbot indexes "$DSN"             # 未使用索引
pgbot vacuum "$DSN"              # autovacuum 状态

方式二：MCP 接入 AI Agent

在 Claude Code/Cursor/Codex 的 MCP 配置中添加：

{
  "mcpServers": {
    "pgbot": {
      "command": "pgbot",
      "args": ["mcp"],
      "env": { "DATABASE_URL": "postgres://pgbot_ro@host:5432/db" }
    }
  }
}

方式三：Agent Skill 安装（一键）

npx skills add pgrundev/pgbot

然后对 Agent 说：

“Is my Postgres healthy?”

Agent 会自动调用 pgbot inspect，读取结果，按 Skill 规则排序后给出”最严重 → 次严重”的诊断报告。

Claude Code Plugin（最完整）：

claude plugin marketplace add pgrundev/pgbot
claude plugin install pgbot@pgbot

这会同时注册 MCP 工具、Skill 和三个 slash 命令。

使用场景与目标用户

适用场景：
– AI Agent 开发阶段：给 Cursor/Claude Code 装上数据库感知能力，让 Agent 在优化代码前先了解数据库实际状态
– 数据库巡检：CI/CD 流程中集成 pgbot inspect --json，在每次部署前做数据库健康检查
– 慢查询诊断：快速定位”哪个查询吃掉了 60% 的 DB 时间”
– 索引审计：识别可以安全删除的冗余/未使用索引（不会误删仍被副本引用的索引）

目标用户：
– 后端工程师（需要 AI Agent 帮助分析数据库性能）
– DevOps/SRE（自动化数据库巡检接入 CI）
– DBA（作为第二意见工具，验证自己的判断）

输入与输出案例

输入（对 Agent）：

“My Postgres database feels slow after our last release. Can you check what’s going on?”

Agent 执行：

pgbot inspect "$DATABASE_URL"

输出（pgbot 返回的结构化 JSON，Agent 解读后呈现）：

【健康报告 — 优先级排序】

🔴 高风险
1. 查询占比异常：单个查询 "SELECT * FROM orders WHERE..." 占 DB 总执行时间的 67%
   → 原因：orders 表缺少索引，扫描全表
   → 建议：在 orders(user_id, created_at) 上建复合索引
   ⚠️ 注意：扫描计数按节点统计，副节点上看起来未使用的索引可能仍在服务读请求

🟡 中等优化
2. 未使用索引：idx_products_category（3.2 GB）
   → 该索引最近 30 天零扫描
   → 建议：确认无副本依赖后可删除
   ⚠️ 注意：删除前检查 pg_indexes 中的 indexname 匹配

🟢 健康
- Autovacuum 正常
- 磁盘使用率 42%
- WAL 无积压

整个过程中 Agent 只是搬运工——数据来自 pgbot，解释规则来自 Skill，Agent 不创造任何诊断结论。

GitHub: https://github.com/pgrundev/pgbot