技能定位

本 Skill 服务火山引擎 AI 原生 BaaS 平台 Supabase 版 PostgreSQL 引擎，使用本地 byted-postgresql-cli 完成云资源管理和 PostgreSQL 数据面操作。

它不是官方开源 supabase CLI，也不是通用 PostgreSQL 管理工具。不能把官方 Supabase CLI 的命令、资源模型或认证方式直接套用到本平台。

主要资源层级为：

控制面使用火山引擎账号、Console Login 或 AK/SK 凭据；数据面通过 CLI 临时解析连接信息，调用 PostgreSQL 驱动或本机 psql、pg_dump。

核心能力

本 Skill 适用于以下火山引擎 PostgreSQL 任务：

查询、创建、配置、启动、停止、重命名和删除 Workspace。

管理 Branch、默认 Branch、子 Branch、恢复窗口和时间点恢复。

查询和调整 Compute 配置、自动休眠及分析加速。

创建和管理 Database、Role、密码和 Endpoint。

执行 SQL 查询或进入本地 psql。

使用 pg_dump 导出数据库或拉取 Schema。

运行数据库安全和性能诊断。

发起和查看两个 Branch 之间的 Schema Diff。

通过 MCP Server 向 AI Agent 提供 PostgreSQL 资源工具。

排查认证、Region、权限、Workspace、Branch、连接、SQL 和异步操作问题。

适用范围

推荐场景

“列出我可以访问的 PostgreSQL Workspace。”

“查询 Workspace 下有哪些 Branch、Database 和 Role。”

“查看某个 Branch 的 Compute 和 Endpoint 状态。”

“执行一条只读 SQL，统计当前数据库中的表数量。”

“检查数据库是否存在安全或性能问题。”

“比较两个 Branch 的 Schema 差异。”

“通过 MCP 将 PostgreSQL 资源接入 AI Agent。”

“帮我排查 PostgreSQL CLI 的认证或权限错误。”

不适场景

只讨论 PostgreSQL 或 Supabase 通用概念，不操作火山引擎资源。

操作火山引擎 RDS MySQL、Redis 或其他非 PostgreSQL 产品。

使用官方 Supabase CLI 的本地容器、迁移或项目配置工作流。

只编写与 PostgreSQL 后端无关的前端代码。

只需要静态资料，不需要读取云端实时状态。

快速安装

开始前请确认已安装 Node.js、npm 和 npx。

如果系统找不到命令，检查 npm 全局 bin 目录是否已加入 PATH，或者在 Agent 配置中使用 CLI 二进制的绝对路径。

鉴权配置

Console Login

本地开发和交互式操作推荐使用 Console Login：

AK/SK

Agent 运行环境建议使用环境变量：

Profile

也可以使用本地 Profile：

凭据配置位于 ~/.volcengine/config.json；CLI 产品数据位于 ~/.volcengine-postgresql/。不要读取、打印或提交包含 Secret Key、Session Token、数据库密码或完整连接串的文件。

认证验证：

使用方式

Skill 安装完成后，支持 Skill 的 AI Agent 通常会自动发现它。也可以显式指定：

Agent 应先读取 Skill 规则，再根据当前 CLI 的帮助和认证状态调用命令，不应凭记忆猜测命令、资源 ID 或参数。

首次使用建议按以下顺序：

安装 CLI。

完成登录或 AK/SK 配置。

执行 status --output json 验证认证和 Region。

查询 Workspace 并确认目标。

显式传入 --workspace-id 和 --branch-id 执行后续操作。

先进行只读查询，再根据用户确认执行写操作。

常用操作

查询资源

多 Branch 场景下必须明确 --branch-id，不要依赖默认 Branch 或仅凭名称推断目标资源。列表结果应根据 total、limit、offset 和 next_offset 处理分页。

执行 SQL

执行 SQL 前应确认 Region、Workspace、Branch、Database 和 Role，并先向用户展示 SQL：

输出分页

Agent 或脚本优先使用 --output json，不要解析表格文本。列表结果必须保留 total、limit、offset 和 next_offset；存在下一页时，使用下一页偏移继续查询，而不是猜测资源总量或一次请求无限数据。

使用 psql

本机需要安装 PostgreSQL psql：

导出和 Schema

导出前先预览：

db dump 和 db pull 需要本机安装 pg_dump。连接密码默认掩码；只有在受信任的本地环境中确有需要时才使用 --reveal，不得把明文输出写入日志、Shell 历史或构建产物。

Schema Diff 用于比较两个 Branch 的 Schema，结果必须经过人工或流水线审核：