用途：面向 Polygres 相关故障的只读诊断，覆盖 MCP、OAuth 连接、CLI、Runtime API、项目、任务、同步、迁移与检索。核心原则是先只读检查、保�留证据、划分故障边界，再建议最小且安全的修正；诊断期间不做任何变更。
主要能力与用法：MCP 工具可用时先读 references/mcp-tool-contract.md、调用 whoami，并使用发现的只读目录，之后才回退到 CLI 或 SDK。将连接 URL 限制、OAuth 安装、当前 scope、项目边界、项目模式与目录版本分别作为独立诊断层。使用命令前先读已安装的 polygres --help 及命令级帮助，以已安装行为为准。通过 references/context-and-connectivity.md 确定身份、配置来源与唯一项目，项目不明确即停止。记录症状、时间戳、脱敏后的命令或 SDK 调用、退出码或异常类型、request_id、job ID 及分页是否返回游标；生成的管道还需记录 manifest 状态、plan digest、已批准 action ID、checkpoint 与最后成功阶段。
按域检查：用 references/projects-and-database.md 检查项目与数据库证据；project_mode 为 synced 时改用 references/synced-projects.md 并跳过目标库、行、导入与迁移检查；导入任务或迁移失败见 references/jobs-and-migrations.md；图、向量、文本、混合或一般就绪失败见 references/retrieval.md；pgContext 相关失败见 references/context.md；MCP 检索评估见 references/mcp-retrieval-quality.md；MCP 操作状态见 references/mcp-operation-recovery.md。故障归类为 CLI/本地配置、控制面、Runtime API、Postgres/数据库或连接池、异步任务状态，类型化 SDK 错误与升级见 references/errors-and-escalation.md。
限制：重试前先复查状态；修正动作需获明确批准，支持的变更交由 $polygres-cli 或应用改动交由 $polygres-sdk。单行写入提交后丢失响应，除非公开证据能判定，否则视为结果未定，不得自动重试仅行级 insert、upsert 或 ignore；Context 支持的写入须在 24 小时回放窗口内用精确幂等键重放，ROW_CONTEXT_IDEMPOTENCY_EXPIRED 后先检查行与 Context 点再选新键。只用已安装帮助与公开 $polygres-sdk 方法确认的命令，不猜私有端点或内部可观测系统。保留 request 与 job ID 原样，区分证据缺失与检查成功。不得记录数据库密码、API 密钥、授权头、含凭据的连接串或完整环境输出。验证、认证、权限或兼容性错误不得当作瞬时错误重试，限流或超时重试须有界。未变的合并管道评审已覆盖的修正无需再次申请批准，但项目、源范围、动作集、出网、破坏性效果或 plan digest 变化时须重新申请。须明确报告分页与部分失败。仅证据支持可能边界时，不得声称根因。