polygres-troubleshooting

Polygres 故障排查

先进行只读检查。确认上下文、保留证据、确定故障边界，并建议最小且安全的修正方案。诊断期间不要进行任何更改。

如果有 Polygres MCP 工具可用，请先阅读 references/mcp-tool-contract.md，调用 whoami，并在使用 CLI 或 SDK 作为备用方案之前，先使用发现的只读目录。请将连接 URL 限制、OAuth 安装、当前作用域、项目边界、项目模式和目录版本视为不同的诊断层。

工作流

1. 使用命令前，先阅读已安装的 polygres --help 和对应命令的帮助信息。已安装版本的行为是判断 CLI 兼容性的准则。
2. 使用 references/context-and-connectivity.md 确认身份、配置来源和一个明确的项目。项目不明确时应停止。
3. 记录症状、时间戳、经过脱敏的命令或 SDK 调用、退出代码或异常类型、request_id、作业 ID，以及分页是否返回游标。 对于生成的管道，还要记录清单状态、计划摘要、已批准的操作 ID、检查点和最后一个成功完成的阶段。
4. 使用 references/projects-and-database.md 检查项目和数据库证据。
5. 如果 project_mode 为 synced，请使用 references/synced-projects.md，并跳过目标数据库、行、导入和迁移检查。
6. 对于导入作业或迁移失败，请使用 references/jobs-and-migrations.md。对于图、向量、文本、混合或一般就绪状态故障，请使用 references/retrieval.md。对于 pgContext 能力、集合、点、操作、召回或 Joint 故障，请使用 references/context.md。 使用 references/mcp-retrieval-quality.md 通过 MCP 评估检索质量，并使用 references/mcp-operation-recovery.md 检查 MCP 操作状态。
7. 将故障归类为 CLI／本地配置、控制平面、Runtime API、Postgres／数据库或连接池，或异步作业状态。有关有类型的 SDK 错误和升级处理，请使用 references/errors-and-escalation.md。
8. 重试前重新检查状态。提出纠正措施，但应先获得明确批准，并将受支持的更改交由 $polygres-cli 处理，应用程序更改则交由 $polygres-sdk 处理。

对于提交后未收到响应的单行写入，除非公开证据已明确其结果，否则应将提交结果视为不确定。不要自动重试仅涉及行的插入、插入或更新操作，或忽略冲突操作。对于由 Context 支持的写入，请在 24 小时重放窗口内使用完全相同的幂等键重放完全相同的请求；复合账本会阻止再次修改行。出现 ROW_CONTEXT_IDEMPOTENCY_EXPIRED 后，应先检查该行和 Context 点，再决定是否使用新键。

证据规则

• 仅使用已安装帮助信息确认的命令和公开的 $polygres-sdk 方法。切勿猜测私有端点或使用内部可观测性功能。
• 原样保留请求 ID 和作业 ID。区分缺少证据与检查成功。
• 切勿记录数据库密码、API 密钥、授权标头、包含凭据的连接字符串或完整环境输出。
• 不要将验证、身份验证、权限或兼容性错误当作暂时性错误重试。对于速率限制或超时，应限制重试次数。
• 如果纠正措施已包含在未变更的合并管道审查中，不要再次请求批准。如果项目、源范围、操作集、出口、破坏性影响或计划摘要发生变化，则应再次请求批准。
• 明确报告分页和部分失败；第一页成功或某个子系统正常，并不能证明整个操作成功。

诊断报告

• **已解析的身份：**账号身份，或无法确认身份的确切原因。
• **已解析的项目：**确切的项目 ID，或阻碍选择项目的歧义。
• **症状：**可观察到的故障及受影响的操作。
• **观察到的证据：**已脱敏的状态、异常类和时间戳。
• **可能原因：**有证据支持的分类及置信度。
• **已执行的安全检查：**使用的公开只读命令和 SDK 调用。
• **纠正措施：**文档记录的最小操作，尚未执行。
• **审批或升级：**所需审批或升级对象。
• **保留的 ID：**不含机密的请求 ID、作业 ID 和游标。
• **未知项：**缺失、过时、不兼容或相互矛盾的证据。

边界

• 诊断期间不得进行变更、轮换凭据、重试作业或 Context 操作、应用迁移、协调点、重建图资源，或启动文本、向量或 Context 重建索引。
• 不得调用未记录的或私有路由，也不得查询私有可观测性系统。
• 如果证据仅支持某个可能的边界，不得声称已找到根本原因。