byted-supabase

Files (36)

• LICENSE
• SKILL.md
• openai.yaml · agents/
• .env.example · examples/hello-world-node/
• README.md · examples/hello-world-node/
• index.mjs · examples/hello-world-node/
• package.json · examples/hello-world-node/
• .env.example · examples/hello-world-python/
• README.md · examples/hello-world-python/
• main.py · examples/hello-world-python/
• pyproject.toml · examples/hello-world-python/
• meta.json
• ai-gateway.md · references/
• app-integration-guide.md · references/
• edge-function-dev-guide.md · references/
• iam-permission-guide.md · references/
• advanced.md · references/pg-best-practices/
• conn.md · references/pg-best-practices/
• data.md · references/pg-best-practices/
• index.md · references/pg-best-practices/
• lock.md · references/pg-best-practices/
• monitor.md · references/pg-best-practices/
• query.md · references/pg-best-practices/
• schema.md · references/pg-best-practices/
• security.md · references/pg-best-practices/
• rls-guide.md · references/
• sandbox-guide.md · references/
• schema-guide.md · references/
• sdk-pitfalls.md · references/
• security-guide.md · references/
• sql-playbook.md · references/
• tool-reference.md · references/
• workflows.md · references/
• sandbox-cli-lifecycle.sh · scripts/
• sandbox-node.mjs · scripts/
• sandbox-python.py · scripts/

SKILL.md (first lines)

# 火山引擎 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. **绝不**把它当作「重启 / 休眠 / 省资源」的手段——workspace 休眠/唤醒用 `projects sleep`/`projects wake`，算力重启/自动休眠配置用 `computes restart`/`projects settings`，二者都**不会**等同于 workspace 暂停。
>
> （`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**（创建、删除、查看配置、上传/下载对象）
- 需要运行隔离代码、执行 AI Coding Agent、上传文件或管理临时 **Sandbox**
- 需要**部署前端静态站点**（并按需与 Supabase 后端打通）
- 需要获取 Supabase 项目的 **API Key** 或 **连接信息**
- 需要为 Supabase 数据库 **生成 TypeScript 类型定义**

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

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

## 命令行工具

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

```bash
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](#核心原则)。）

## 鉴权与前置条件

鉴权方式取决于运行模式：

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

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

```bash
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 场景）**

```bash
export VOLCENGINE_ACCESS_KEY=<AK>
export VOLCENGINE_SECRET_KEY=<SK>
export VOLCENGINE_REGION=<region>          # 例如 cn-beijing / cn-shanghai
export VOLCENGINE_SESSION_TOKEN=<token>    # 可选：使用临时凭据时才需要
```

> 在沙箱 / VeFaaS IAM 等已自带角色凭据的环境里，可不显式设置 AK/SK，CLI 会自动取临时凭据。

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples