/byted-supabase

name: byted-supabase
description: Manage Volcengine's AI-native BaaS platform (Supabase edition / 火山引擎 AI 原生 BaaS 平台 Supabase 版) — a Volcengine-operated distribution that differs from official Supabase. Covers workspaces, branches, SQL queries, schema changes, Auth, Realtime, Edge Functions, Storage, frontend static-site hosting, and TypeScript type generation through the byted-supabase-cli command-line tool (installed via `npm i -g @byted-supabase/cli`; this is NOT the official `supabase` CLI). Run byted-supabase-cli subcommands to get real-time results. Use this skill when the user needs to create, inspect, or manage Volcengine Supabase resources (workspaces, databases, branches, Auth, Realtime, Edge Functions, Storage, frontend deployment, API keys, or type generation). Do NOT use it for general database discussions, non-Supabase services, or pure client-side coding unrelated to Supabase backend management.
version: 2.3.3
license: Apache-2.0
metadata:
  openclaw:
    emoji: "🧩"
    homepage: "https://www.volcengine.com/"
    requires:
      bins:
        - byted-supabase-cli
    os:
      - darwin
      - linux

火山引擎 AI 原生 BaaS 平台 · Supabase 版

本 Skill 用于在对话中充当**火山引擎「AI 原生 BaaS 平台 Supabase 版」的智能运维与开发代理**。

> ℹ️ **这是火山引擎自研的 AI 原生 BaaS 平台（Supabase 版），不是官方开源 Supabase。** 它在 Supabase 协议/生态之上做了火山引擎的平台化适配，**与官方存在差异**： > - 用 **`byted-supabase-cli`** 操作（**不是**官方 `supabase` CLI），通过 **火山引擎账号 / AK-SK** 鉴权； > - 资源模型为 **workspace（工作区）/ branch（分支）/ compute（算力）**，并有 `endpoints`、`computes` 等火山专有命令； > - 部分命令、参数与行为与官方 Supabase CLI **不同**。 > > 👉 操作以本 Skill 文档与 `byted-supabase-cli <command> --help` 为准，**不要套用官方 Supabase CLI 的命令习惯**。

它会：

• 识别用户的 Supabase 自然语言需求
• 直接调用 **`byted-supabase-cli`** 命令行工具获取实时结果
• 基于返回结果做解释、排障和下一步建议

核心原则

> 本节为通用工作纪律，**任何 Supabase 任务都应遵守**。

**1. 平台演进快 —— 先查在线文档/发布记录，不要只信训练数据。** 命令、参数、`config` 项、API 约定会随版本变化。动手前先查火山引擎官方文档与发布记录（见文末[在线文档](#在线文档)），尤其涉及不确定的命令/参数时；CLI 子命令一律 `byted-supabase-cli <command> --help` 现查，**不要凭记忆猜命令**。

**2. 验证你的工作。** 任何变更落地后，**再跑一条只读查询确认生效**。没有验证的修复＝未完成。

**3. 从错误中恢复，不要死循环。** 同一方法连续失败 2-3 次就停下来换思路：换方法、查文档、更仔细地看报错、必要时查日志。Supabase 类问题不总是靠重试同一条命令解决。

**4. 把表暴露给 Data API（REST）。** 新建的表**不一定**自动通过 Data API 暴露。若要让 `anon` / `authenticated` 角色经 REST 访问某表，需显式 `GRANT`。

> 注意：这与 RLS 是两回事 —— Data API 暴露 + 角色授权决定**表是否可达**；RLS 决定表可达后**哪些行可见**。当用户反馈"SQL 建的表访问不到"，先确认是否已授权这两个角色。**对外（anon/authenticated）授权时务必同时启用 RLS。**

**5. ⛔ 高危红线：`projects stop`（暂停 workspace）会让客户业务彻底不可用。** 暂停后的实例**无法靠客户 IO / 访问流量自动唤醒**（这与分支休眠的「访问即唤醒」**本质不同**）——整个 workspace 及其下**所有分支**停服，REST / Auth / Storage / 直连 DB **全部不可达**，必须由人**手动** `projects start` 才能恢复。因此执行 `projects stop` 前**必须**： > 1. **向用户明确复述影响并取得二次确认**——「这会停掉整个 workspace `<ref>`，期间客户业务完全不可用、且不会自动恢复，确认吗？」 > 2. **核对目标 `ref` 无误**，绝不停错 workspace； > 3. **绝不**把它当作「重启 / 休眠 / 省资源」的手段——重启用 `branches restart`，休眠是平台自动行为，二者都**不会**导致业务停服。 > > （`projects delete` 同属不可逆高危操作，同样需先确认。）

**6. 暴露 schema 内的表必须启用 RLS。** 任何对外暴露的 schema（默认含 `public`）里的每张表都要 `ENABLE ROW LEVEL SECURITY`；私有 schema 也建议启用作为纵深防御。启用后，按真实访问模型写策略，**不要无脑给每张表套同一个 `auth.uid()` 模式**。

**7. 安全 checklist。** 凡涉及 Auth、RLS、视图、Storage 或用户数据的任务，逐条过一遍下面这些 **Supabase 特有的安全陷阱**（完整版见 [`references/security-guide.md`](references/security-guide.md)）：

• **绝不**用 `user_metadata` / `raw_user_meta_data` 做鉴权判断 —— 它**用户可改**，放进 RLS/授权逻辑即可被伪造。鉴权数据存 `raw_app_meta_data` / `app_metadata`。
• **`service_role` / 密钥绝不出现在前端**。前端用 publishable / `anon` key；`service_role` 仅后端。
• **视图默认绕过 RLS** —— PG15+ 用 `CREATE VIEW ... WITH (security_invoker = true)`；更低版本则从 `anon`/`authenticated` 收回视图权限或放进未暴露 schema。
• **`auth.role()` 已弃用** —— 改用策略上的 `TO authenticated` / `TO anon`。开启匿名登录后，匿名用户也带 `authenticated` 角色，`auth.role() = 'authenticated'` 会**静默失效**。
• **只写 `TO authenticated` 是"认证而非授权"（BOLA/IDOR）** —— 必须配所有权谓词：`to authenticated using ( (select auth.uid()) = user_id )`。
• **UPDATE 策略要同时有 `USING` 和 `WITH CHECK`**，否则用户能把行的 `user_id` 改成别人。
• **UPDATE 需要 SELECT 策略** —— RLS 下 UPDATE 要先 SELECT 到行；缺 SELECT 策略时更新静默返回 0 行（无报错）。
• **`SECURITY DEFINER` 函数绕过 RLS**，且 `public` 下默认对所有角色可调用。别用它来"解决"权限报错；非用不可时放进未暴露 schema + 函数体内做 `auth.uid()` 检查 + 改完跑 `db advisors`。
• **Storage upsert 需要 INSERT + SELECT + UPDATE 三个权限**，只给 INSERT 会导致覆盖上传静默失败。
• **固定依赖版本并提交 lockfile**（`@supabase/supabase-js`、`@supabase/ssr`、`supabase-py` 等）。

何时使用本 Skill

**适用场景（应使用）：**

• 用户提到 **Supabase**、**火山引擎 Supabase** 相关的操作需求
• 需要创建、查看、暂停或恢复 Supabase **工作区（workspace / project）**，或**重启分支算力**
• 需要对 Supabase 数据库执行 **SQL 查询、建表、schema 变更**
• 需要管理 Supabase **分支**（创建、删除、恢复、设默认）
• 需要配置 **Auth（认证）** 或使用 **Realtime（实时）**
• 需要部署或管理 **Edge Functions**
• 需要操作 **Storage Bucket**（创建、删除、查看配置、上传/下载对象）
• 需要**部署前端静态站点**（并按需与 Supabase 后端打通）
• 需要获取 Supabase 项目的 **API Key** 或 **连接信息**
• 需要为 Supabase 数据库 **生成 TypeScript 类型定义**

**不适用场景（无需使用）：**

• 仅讨论通用数据库概念，不涉及火山引擎 Supabase 实例
• 操作非 Supabase 的数据库服务（如 RDS MySQL、Redis）
• 纯前端 / 客户端代码编写，不涉及 Supabase 后端资源管理
• 用户只是询问 Supabase 文档 / 概念，无需调用 CLI

命令行工具

本 Skill 的所有能力都来自 `byted-supabase-cli` 这一个二进制：

npm i -g @byted-supabase/cli         # 安装（一次）；装后得到 byted-supabase-cli 命令
byted-supabase-cli --help            # 自检 / 看帮助
byted-supabase-cli <command> --help  # 任何子命令都可加 --help 看参数

> 文档示例统一写作 `byted-supabase-cli`；若你的环境已把它别名/软链为 `supabase`（CLI 二进制自身在 `--help` 里也自称 `supabase`），两种写法等价。（用 `--help` 现查命令结构、不要猜——见[核心原则 1](#核心原则)。）

鉴权与前置条件

`byted-supabase-cli` 用**火山引擎凭据**鉴权。**优先使用 CLI 自带的配置 / 登录方式**（写入 `~/.volcengine/config.json`，一次配置长期复用）：

**方式 1 · CLI 配置 / 登录（推荐）**

byted-supabase-cli login --region cn-beijing   # 1a. 浏览器 OAuth 登录（最省事，缓存临时 STS 凭据）；其他地域替换 cn-beijing
byted-supabase-cli configure set --access-key <AK> --secret-key <SK>   # 1b. 或用 AK/SK 写入默认 profile，可选 [--region <region>]
byted-supabase-cli configure list            # 管理 profile：列出
byted-supabase-cli configure get             # 查看当前 profile
byted-supabase-cli configure profile <name>  # 切换当前 profile

> region 可缺省；若在 `login` / `configure set` 时指定了，会写进 profile，后续命令无需再带 `--region`。

**方式 2 · 环境变量（次要，适合无法持久化的 headless / CI 场景）**

export VOLCENGINE_ACCESS_KEY=<AK>