polygres-cli

Polygres CLI

通过已安装的 polygres 命令操作用户的 Polygres 项目。 将 CLI 视为操作和安全边界。不要调用私有控制平面路由，也不要推测未记录的请求负载。

优先使用可用的 MCP 连接

当当前会话中有可用的 Polygres MCP 工具时，请阅读 references/mcp-tool-contract.md，并使用发现的兼容工具执行交互式项目操作。调用 whoami，遵守固定项目或多项目边界，并以发现的工具目录为准。

当用户明确要求使用 CLI、MCP 不可用或不兼容，或操作属于 CLI 的功能范围时，请使用此技能中的 CLI 工作流， 例如迁移、Runtime 密钥、交互式数据库访问、启动导入，以及旧版向量或文本配置。切勿臆造 MCP 工具来对应 CLI 命令。

安全起步

1. 在进行实时或端到端测试之前，以及不确定命令是否可用或兼容时，运行 polygres --version 和 polygres --help。
2. 如果找不到该命令，请告知用户如何安装 polygres-cli，并让他们批准或自行执行安装。不要悄悄安装软件包。
3. 对于在 Polygres 源代码检出目录中进行的实时测试，请创建隔离测试环境，根据该检出的依赖安装策略从检出目录重新安装 polygres-cli 和 polygres-sdk，并在测试前验证它们的版本和导入来源。不要用 PyPI 软件包替代正在测试的检出版本。
4. 在源代码检出目录之外，将已安装的 CLI 和 SDK 版本与应用或当前技能兼容性记录所要求的版本进行比较。不能仅因命令存在就认定其为当前版本。更改已安装的软件包前，必须获得批准。
5. 当身份或当前组织不确定时，在执行变更前运行 polygres whoami。需要身份验证时，使用 polygres login。
6. 使用 polygres projects list、明确指定的 --project，或 polygres projects use <project> 确定项目。在执行破坏性操作、生成密钥或修改架构之前，说明已确定的项目。
7. 确定 project_mode。如果值为 synced，请在选择任何命令前阅读 references/synced-projects.md。
8. 对于 Agent 必须解析的输出，优先使用 polygres --json ...。将 stdout 视为 JSON 通道，将 stderr 视为诊断信息。

如果随附示例与已安装版本的 --help 不同，请以已安装版本的命令功能为准，并说明版本不匹配。切勿猜测替代命令。

路由请求

仅阅读任务所需的参考资料：

用户意图	参考资料
登录、登出、身份、组织、项目选择或状态	references/authentication-and-projects.md
创建同步项目、功能、生命周期交接和权限边界	references/synced-projects.md
环境、Postgres 元数据、psql、Runtime API 密钥	references/database-and-keys.md
从 CSV、TSV、JSON 数组或 JSONL/NDJSON 导入数据集或执行回填	references/data-imports.md
验证、插入、更新插入或忽略单个 JSON 对象或运行时事件	references/rows.md
迁移列表／应用和 SQL 安全	references/migrations.md
图、文本、现有向量配置及通用检索准备情况	references/retrieval.md
通过 MCP 执行已批准的图计划，或改用 CLI	references/mcp-graph-retrieval.md
Polygres AI Context 集合、筛选条件、点、操作和检索	references/context.md
JSON 输出、轮询、退出代码、重试和恢复	references/automation-and-errors.md

执行操作

1. 将请求归类为只读、修改、破坏性、修改架构或生成机密信息。
2. 加载相关参考文档并验证本地输入。
3. 确定身份验证方式和项目上下文。
4. 确定项目模式，并停止执行该模式下不可用的任何命令。
5. 对于修改操作，展示目标项目、受影响的资源、重要选项和可逆性。
6. 在需要时获取明确批准。如果现有的合并式流水线批准明确指定了此确切项目、源范围、操作和未更改的计划摘要，则可接受该批准。
7. 运行文档中说明的最精简命令。
8. 保留结果中的项目、作业、迁移、配置、密钥和请求 ID。
9. 仅报告观察到的最终状态。如果操作仍在运行，请说明这一点并提供状态命令。

获取同意

以下操作前，必须先获得用户的明确批准：

• replace_existing 导入；
• 应用 SQL 迁移；
• 创建或更新文本配置，包括生成的 TSVector 列或托管文本索引；
• 对文本配置重新索引；
• 撤销 Runtime API 密钥；
• 删除现有向量或文本配置；
• 所有持久化的 pgContext 修改，包括创建、更新集合，设置默认项，添加向量，更改默认向量，重新索引或删除；注册筛选器；协调点位；以及取消或重试操作；
• pgContext 点位 upsert 或删除操作，若其会成为持久化操作，或删除映射会破坏用户的服务行为；
• 使用 --yes 的任何命令；
• 任何其他具有破坏性或难以撤销的操作。

只有在获得针对该确切操作和目标的批准后，才能添加 --yes。 如果用户的命令或匹配的合并式流水线批准已授权 rows insert、rows upsert 或 rows ignore 命令，则不要再要求二次确认。 在获得 add-column 或 new-table 集合创建操作的批准前，还要展示预检 DDL、受影响的架构对象和所有权边界。

保护机密信息

• 绝不请求、获取、存储、记录或传递原生数据库密码。
• 绝不请求、打印或将同步源连接写入参数、生成的文件或转录记录。优先使用 CLI 的隐藏式交互 URL 提示。 对于经批准的非交互操作，使用 --connection-env 引用由用户填充的环境变量；绝不查看其值。
• 让 psql 提示用户输入数据库密码。
• 如果 Agent 终端无法维持交互式 TTY，请向用户提供无需密码的命令，或让他们直接运行 polygres db psql。
• 绝不向用户索要 POLYGRES_ACCESS_TOKEN。它是开发和测试用的覆盖设置，并非公开的身份验证流程。
• 在运行 polygres keys create <name> 前发出警告，因为 Runtime API 密钥密文只会显示一次，并可能进入终端或 Agent 历史记录。
• 可让用户在自己的终端中创建密钥，避免密文进入 Agent 转录记录。
• 绝不将令牌、密钥或密码放入源文件、示例、命令参数、日志或最终摘要。

在本地准备非 CSV 数据

对于 TSV、JSON 数组和 JSONL/NDJSON 数据集，请阅读 references/data-imports.md 并使用 scripts/prepare_import.py。如果单个 JSON 对象是作为单条写入数据使用，请改用 references/rows.md。应从此技能目录解析脚本路径，不要假设仓库中包含 scripts/。

此转换器仅在本地运行，并会生成经过审核的 CSV 文件。它不会调用 Polygres。除非说明结果并获得所需批准，否则绝不要静默扁平化嵌套 JSON、重命名列或合并 null 值与空字符串。

不要将 SQL 迁移作为通用行导入机制。不要调用后端 SQL 导入或 pg_dump 路由，因为当前公开 CLI 中不包含这些命令。

处理故障

使用 references/automation-and-errors.md 解读退出代码。尤其要注意：

• 修复验证问题后，再重试退出代码 2。
• 退出代码 3 时重新进行身份验证。
• 退出代码 4 时说明缺少权限。
• 退出代码 5 时解决资源缺失问题。
• 退出代码 6 时解决冲突或项目选择不明确的问题。
• 退出代码 7 时遵循速率限制指引。
• 将退出代码 8 视为远程故障或超时。
• 退出代码 9 时安装缺失的本地依赖项（如 psql），或将其交由他人处理。

导入或配置操作超时后，重新提交前先检查已知资源或作业的状态。客户端超时并不能证明服务端操作失败。