需要在不改动 PlanetScale…

在不修改 PlanetScale 的前提下，只读收集并输出组织、数据库、分支、Query Insights、备份、角色、webhook、流量控制和安全性证据。

适用场景

解决思路

1. 明确目标：以只读方式构建有证据支撑的 PlanetScale 数据库库存，不施加任何变更。
2. 默认允许：列出 organizations、databases、branches、keyspaces、regions 和 sizes。
3. 默认允许：读取 branch metadata。
4. 默认允许：读取 webhook configuration。
5. 默认允许：读取 schema recommendations。
6. 默认允许：通过 MCP 或 API 读取 Query Insights、anomalies 和 query patterns。
7. 默认允许：读取 traffic budgets 和 rules。
8. 默认允许：读取 Postgres roles 和非机密 role metadata。
9. 默认允许：读取 backup schedules 和 restore metadata。
10. 默认允许：读取 branch schema。
11. 默认允许：用 Connections CLI view 检查 live connection/session metadata。
12. 默认允许：检查 repository files，识别 frameworks、ORMs、migrations、SQL tagging 和 connection config。
13. 默认允许：检查 Terraform 或其他 infrastructure-as-code definitions，识别 PlanetScale roles、backups、backup policies、Postgres parameters 和 supported extensions。
14. 未经明确批准，不执行任何 create、update、delete、enable、disable、reset、deploy、restore、promote、enforce 或 apply 操作。
15. 未经明确批准，不执行任何 SQL mutation。
16. 除非操作者明确要求做 credential work，不执行任何会生成新凭据的命令。
17. 每个命令和 endpoint 都依据官方文档，而不是猜测；PlanetScale 发布 agent-readable docs：Docs index https://planetscale.com/docs/llms.txt；任意 docs page 可在 URL 后加 `.md` 得到 markdown；API reference https://planetscale.com/docs/openapi.yaml（OpenAPI 3.0）。
18. 调用 endpoint 前先在 API reference 中验证路径。
19. 未验证路径返回 404 时，应视为路径错误而不是发现；不要把它记录为平台状态，也不要据此得出“未配置”的结论。
20. 命令失败时，重新对照文档核验。已验证 interface notes：`pscale database show <database> --org <org>` —— org 是 flag，不是 positional argument。
21. `pscale api <path>` 使用 org-relative paths，例如 `organizations/{org}/databases/{db}/branches/{branch}`；没有 `get` 子命令，也没有 `/v1/` 前缀；查询参数用 `-Q key=value` flags；不要把 `?`/`&` 嵌入 path，否则会在 shell globbing 下出错。
22. `pscale webhook list <database> --org <org>` —— database 是 positional argument。
23. `pscale backup list <database> <branch>` —— 必须提供 branch。
24. `pscale branch connections top <database> <branch>` —— 可通过 reserved administrative connection 对 Postgres 和 Vitess 做 live read-only session inventory；除非操作者明确批准该运维操作，否则不要 cancel queries 或 terminate connections。
25. Query Insights 是 public API。Live query telemetry 路径：`.../branches/{branch}/insights`（按 pattern 统计；支持 `from`/`to`/`period`、`q`、`sort`、`dir`、`tablet_type`、`type`、`fields` 和分页）。
26. 同一 branch path 下的相关 endpoint：`insights/errors`、`insights/anomalies`、`insights/tags`、`insights/tags/summaries`、`insights/{fingerprint}`（单次执行）、`insights/{fingerprint}/summary`、`insights/{fingerprint}/traffic/budgets`。
27. `query-patterns` 路径返回生成的报告 metadata，不是 live patterns。
28. Traffic budgets 路径：`.../branches/{branch}/traffic/budgets`；CLI 没有 `pscale traffic-control budget list`，做 inventory 要用 API。
29. Postgres roles：通过 `.../branches/{branch}/roles` 列出；单个 role 按 ID 获取，不按 name 获取（`pscale role get <db> <branch> <role-id>`）。
30. IP restrictions：使用 database-level `organizations/{org}/databases/{db}/cidrs`；branch-level IP-restriction 路径无效。
31. Schema recommendations：使用 database-level `.../databases/{db}/schema-recommendations`；branch-level 路径无效；请求 `page=2` 当前会返回 404，即使响应报告有 `next_page`；用 database object 的 `open_schema_recommendations_count` 作为权威总数；将返回页视为 sample；当 itemized list 只覆盖总数的一部分时，在报告中说明。
32. PITR state 和 branch-level backup policies 没有已验证的 read path；从 `pscale backup list` 和 database-level backup policy 记录 backup posture；把 PITR 标记为 `not assessed in this run`，不要探测路径。
33. List endpoints 会分页；在报告计数前，跟随 pagination parameters 直到 exhausted（除上述 schema-recommendations 情况外）。
34. 将 access failures（403、缺少 token scopes、timeouts）记录到 internal run log 供操作者查看；它们不是 findings，也不进入 customer report。
35. Database identity：记录 organization、database、branch、engine（Vitess 或 Postgres）、region 和 cloud provider、production/development branch status、branch protection 和 safe workflow state、size 和 cluster shape。
36. Branches and schema workflow：对 Vitess，记录 production branch、production 和 staging branches 是否启用 safe migrations、open deploy requests、deploy request approval setting、pending schema changes、branch strategy 是否有启用 safe migrations 的 staging branch。
37. Branches and schema workflow：对 Postgres，记录 branch list、branches 是从 backup 还是 empty 创建、schema changes 是手动管理还是通过 migrations 或 ORM、是否有单独 branch 用于 migration testing、团队是否期待 Vitess-style deploy requests；若是，则标记 Postgres branches 不会以同样方式使用 deploy requests。
38. Observability：记录 Insights availability、query tags 是否存在、出现了哪些 tags、是否存在 high-cardinality tags、是否启用 complete/raw query collection、active anomalies、具有 high latency/high rows read/high error rate/high execution count 的 query patterns、所用 Insights interface 暴露时的 Postgres CPU-heavy query patterns 和 Vitess vindex-usage data、application deploy identifiers 是否在 comments 或 tags 中可见。
39. Recommendations：记录 open schema recommendations、recommendation type、受影响的 table/query、提议的 DDL 或 action、是否存在 branch/deploy workflow 来安全评估它、该 recommendation 是否可作为 application code、ORM migration 或 database DDL 实现。
40. Webhooks and automation：记录 configured webhooks、subscribed events、enabled state、last delivery success/failure、destination category（Slack、PagerDuty、internal automation、CI、agent queue、unknown）、webhook signature verification 是否有文档或实现、webhook handling 是否 idempotent 和 asynchronous。
41. Postgres Traffic Control：仅对 Postgres 记录 existing budgets and rules、budget modes（off、warn、enforce）、limits（rate、capacity、burst、concurrency、warning threshold）、rules by fingerprint/keyspace/query kind/tags、rules 是否绑定到有意义的 SQLCommenter tags、是否有 production budget 处于 enforce mode。
42. Postgres safety：仅对 Postgres 记录 application role usage、apps 是否使用 default role、app roles 是否 least-privilege、是否为 application roles 启用 `pg_strict`、是否为合适 workloads 使用 PgBouncer、live connections 是否显示 blockers、idle-in-transaction sessions 或 connection saturation during an active incident、是否配置 private connectivity 和 IP restrictions、backup retention 和 PITR 是否满足 customer recovery expectations。
43. Vitess safety：仅对 Vitess 记录 safe migrations state、deploy request workflow、admin approval requirement、gated deployment usage、schema revert availability、branch 和 keyspace topology、sharding/vschema status、sharded query patterns 是否使用相关 vindexes、backups 和 restore posture。
44. Evidence format：对每条 finding 包含 evidence：Source（MCP、CLI、API、dashboard-observed、SQL read-only、repository file）、path 或 command used、timestamp、raw value 或 concise excerpt、confidence（high、medium、low）。
45. Output：返回 inventory table、missing evidence table、risk flags、recommended next skills to run。
46. 最后输出：`No changes have been applied.`

适用边界 · 注意事项

• 需要执行变更、SQL mutation 或生成新凭据，且未获得明确批准时，不适用。
• 缺少 PlanetScale 账号、API token、`pscale` CLI 或 MCP/API 访问权限时，无法完成该只读盘点。
• 目标不是 PlanetScale 数据库时，不适用。