ClickHouse 托管 Postgres…

当 ClickHouse 托管 Postgres 实例出现变慢、CPU 高、吞吐低、缓存抖动等性能问题时，按证据化流程定位根因并给出（而非执行）修复建议。

适用场景

解决思路

1. 先确认可用的两个 API：位于 https://api.clickhouse.cloud 的 Prometheus 指标（operation `postgresInstancePrometheusGet`，Prometheus tag）和 Slow Query Patterns（operation `slowQueryPatternsGetList`，Postgres tag，Beta），两者均使用 ClickHouse Cloud API key/secret 做 HTTP Basic 认证，且都需要 `organizationId` 和 `serviceId` 路径参数，需向用户索取。
2. 明确自己拿不到的信息：没有查询计划/EXPLAIN 输出、没有按表的扫描类型计数器（`seq_scan`/`idx_scan`）、没有 autovacuum 或 last-ANALYZE 时间戳；因此只能从 IO 和时序信号推理，不能从计划树推理。
3. 第 1 步：发现实时 API 形态。按 `rules/openapi-discovery.md`，从 `https://api.clickhouse.cloud/v1` 拉取 OpenAPI spec，按 `operationId` 定位 `postgresInstancePrometheusGet`（Prometheus tag）和 `slowQueryPatternsGetList`（Postgres tag），解析其路径模板、必需查询参数以及慢查询端点的响应 schema，并基于 schema 属性描述构建会话级角色映射 `{ 语义角色 → 实际字段名 }`；后续所有请求和引用都用解析出的名字，绝不凭记忆硬编码字段名。
4. 第 2 步：只抓取一次 Prom 获取系统 gauge。按 `rules/prometheus-scrape.md`，一次抓取、不等待，关注无需 delta 的当前值：`CacheHitRatio`、`ActiveConnections`、`MemoryUsedPercent`、`FilesystemUsedPercent`。`CacheHitRatio` 明显低于约 95%（在本应能装进缓存的工作负载上）本身就是信号；`ActiveConnections` 逼近连接池上限本身就是信号，这些都不需要变化率。第二次抓取用于计数器 delta 是可选（opt-in）的，仅在 Step 4 分诊指向写拥塞（此时死锁和回滚的速率重要，且 Slow Query Patterns API 无法替代）时才用；读路径场景（最常见的 RCA 形态）单次抓取足够。
5. 第 3 步：拉取 top 慢查询模式。请求 slow query patterns，按 `rules/slow-query-patterns-fields.md` 了解关键字段及读法。这是主要诊断依据——它返回所请求窗口内每个模式的累计总量（调用次数、运行时间、blocks、rows），相当于你本来要从两次 Prom 抓取推导的“变化率”数据，但按查询粒度且无需等待。若没有任何模式返回有意义的 `totalDurationUs`，说明报告可能被夸大或问题不是查询形态的，此时停止并告诉用户你查看了什么。
6. 第 4 步：分诊，选择正确的启发式。按 `rules/triage.md`，把 Prom + 慢查询的组合信号匹配到某个启发式形态，每个形态对应一个文件：`rules/heuristic-full-scan.md`（读路径全表扫描）、`rules/heuristic-hot-loop.md`（来自应用的 N+1 / 热循环）、`rules/heuristic-write-congestion.md`（死锁、慢写、高回滚率）。若信号不能干净匹配任何形态，不要臆造假设，而是列出 top 模式并询问用户认得哪个工作负载；欢迎以 PR 形式新增启发式。
7. 第 5 步：先推理再建议。使用 `rules/output-template.md` 的格式，始终包含：症状、证据、假设（注明仅凭此表面无法排除的替代原因）、短期修复、长期跟进项。
8. 第 6 步：不要应用修复。按 `rules/recommend-only.md`，绝不执行 DDL，绝不调用 `pg_cancel_backend` 或 `pg_terminate_backend`；只写出建议并解释原因，由人来应用。
9. 优化执行顺序：Step 2 和 Step 3 只共享认证、无数据依赖，用后台 curl（`&` + `wait`）并行执行，把串行的约 2s 降到约 1s。
10. 如需在单次上下文加载中查看所有规则展开的完整指南，读取 `AGENTS.md`。

适用边界 · 注意事项

• 不适用于非 ClickHouse 托管的 Postgres 实例（依赖 ClickHouse Cloud API 与对应端点）。
• 当问题不是查询形态（慢查询模式无有意义 `totalDurationUs`）时，应停止并说明已查看内容，而非继续套用启发式。
• 本流程只给建议不执行修复，不适用于需要直接执行 DDL 或终止后端进程的场景。