技能创建器
skill-creator
创建、改进和评估自定义技能，把专业流程转化为可重复使用的 AI 能力。
探索技能
数据与研究 · SKILL.md
byted-supabase
byted-supabase【数据与研究】火山引擎 Supabase . 管理 AIDAP Supabase 项目、工作区、数据库、分支、Auth、Realtime、Edge Functions、Storage、API Keys、SQL、Schema 变更、TypeScript 类型生成和 MCP 集成。
独立 GitHub 快照 · 自动分类 · 以原作者文档为准
技能说明
GitHubname: byted-supabase description: 火山引擎 Supabase . 管理 AIDAP Supabase 项目、工作区、数据库、分支、Auth、Realtime、Edge Functions、Storage、API Keys、SQL、Schema 变更、TypeScript 类型生成和 MCP 集成。 version: 2.3.8 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操作（不是官方supabaseCLI），通过 火山引擎账号 / 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 前必须：
- 向用户明确复述影响并取得二次确认——「这会停掉整个 workspace
<ref>，期间客户业务完全不可用、且不会自动恢复，确认吗？」- 核对目标
ref无误，绝不停错 workspace；- 绝不把它当作「重启 / 休眠 / 省资源」的手段——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）：
- 绝不用
user_metadata/raw_user_meta_data做鉴权判断 —— 它用户可改，放进 RLS/授权逻辑即可被伪造。鉴权数据存raw_app_meta_data/app_metadata。 service_role/ 密钥绝不出现在前端。前端用 publishable /anonkey；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 这一个二进制：
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 配置 / 登录（推荐）
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>
export VOLCENGINE_SECRET_KEY=<SK>
export VOLCENGINE_REGION=<region> # 例如 cn-beijing / cn-shanghai
export VOLCENGINE_SESSION_TOKEN=<token> # 可选：使用临时凭据时才需要
在沙箱 / VeFaaS IAM 等已自带角色凭据的环境里，可不显式设置 AK/SK，CLI 会自动取临时凭据。
地域（region）：可缺省，不指定时默认 cn-beijing。需要指定到其他地域（如 cn-shanghai）时再用 --region，或在 login / configure set 时设好（写进 profile 后续无需重复）。解析优先级：--region > 环境变量 > profile > 已 link 的 region > 默认（cn-beijing）。
鉴权自检：能成功跑通 byted-supabase-cli projects list 即说明凭据 + region 可用。
⛔ 权限被拒（
AccessDenied/ 无权限）：多为 IAM 授权不足（非 AK/SK/region 问题，别重配凭据），切勿编造策略名/权限项/控制台 URL；主账号 vs 子账号分流、授权路径与官方文档见references/iam-permission-guide.md。
目标定位（workspace / branch）
- workspace（工作区/项目）：用
--workspace-id ws-...指定（其别名--project-ref与官方 Supabase CLI 兼容）。 - branch（分支）：用
--branch-id br-...指定；不传则落到该 workspace 的默认分支。 - 默认目标（可选）：
byted-supabase-cli link --workspace-id ws-... --region <region>把某 workspace 设为本目录的默认链接；之后数据面命令可用--linked（多数命令默认--linked=true）而不必每次重复--workspace-id。 - 输出格式：管理类命令加
-o json便于解析；db query默认即输出 JSON（agent 模式）。 - 列表分页（避免一次取太多）：返回列表的命令（
projects list/branches list/projects operations）支持--limit(1-100) +--offset，优先显式分页拉取，别一次性取回过多数据；建议每页--limit 10，需要更多再递增--offset翻页；尤其branches list缺省会返回全部，分支多时务必加--limit或用--search过滤。其余 list 命令暂无分页参数，详见 tool-reference。
标准使用流程
- 先执行
byted-supabase-cli link status -o json，读type字段确认当前是火山账号方式（management）还是分支 URL + Key 方式（solo）。 - Workspace 模式：确认
workspace_id（必要时branch_id），优先执行只读查询（如projects list、db query "select ..."）。 - 分支 URL + Key 方式：确认已 link 的 Supabase URL；根据操作需要确认 anon key、service-role key 或 database URL 是否已配置，优先执行只读查询（如
storage buckets list、functions list、auth config get）。 - 需要变更时再执行写操作；破坏性操作（删除/停机）在非交互环境需加
--yes，执行前向用户确认。⛔ 尤其 Workspace 模式的projects stop（暂停 workspace）属高危红线——客户业务会彻底停服且无法靠 IO 自动唤醒，务必先二次确认（见核心原则 5）。 - 变更后再次查询确认结果已生效（对应核心原则 2）。
能力范围（动作 → CLI 命令）
完整命令、参数与等价 SQL 见
references/tool-reference.md。下表为速查。
工作区（workspace / project）
| 需求 | 命令 |
|---|---|
| 列出 workspace | projects list |
| workspace 详情 / 概览 | projects list --workspace-id ws-... --detail ／ projects overview |
| 创建 workspace | projects create <name>（region 走全局/env/profile）。创建成功后必须主动说明休眠超时并非阻塞询问，见下方「💤 休眠超时」 |
| 配置算力自动休眠 | projects settings compute <ref> --min-cu <n> --max-cu <n> [--suspend-timeout-seconds <秒>]（底层 ModifyComputeSettings；设置算力自动休眠超时用 --service-type Supabase --min-cu 0.5，见下方💤）。该命令只修改配置，不会立即让 workspace 或 compute 进入休眠。 |
| 立即休眠整个 workspace | projects sleep --workspace-id <workspace-id> --yes（底层 SuspendWorkspace；这是 workspace 休眠，不是暂停） |
| 唤醒休眠 workspace | projects wake --workspace-id <workspace-id> --yes（先调用 DescribeWorkspaceEndpoint 获取 AddressDomain，再访问一次 Supabase 实例触发唤醒） |
| ⛔ 暂停 / 恢复整个 workspace（停机/开机，高危，见核心原则 5） | projects stop --workspace-id <workspace-id> ／ projects start --workspace-id <workspace-id> |
| 删除 workspace | projects delete <ref> --yes |
| 获取 API Keys | projects api-keys --workspace-id ws-... |
| 获取访问地址 / 连接串 | endpoints list --workspace-id ws-... ／ db connection-string --workspace-id ws-... |
💤 休眠超时（SuspendTimeoutSeconds）—— 创建后务必主动说明、非阻塞询问。
- 含义：分支算力无流量自动休眠（scale-to-zero）前的空闲等待秒数。到点自动休眠，下次访问 exposeURL（或任意请求）即自动唤醒（冷启动）——这是「休眠」而非「暂停 workspace」（区别见下方辨析与核心原则 5）。
- 取值语义：
-1= 显式关闭自动休眠（算力常驻 / 永不休眠）；0= 未设置的平台默认（行为上等同常驻）；300–604800秒（5 分钟–7 天）= 启用，空闲到点休眠。新建 workspace 默认不休眠（projects list --detail显示为0）。想关闭已开启的自动休眠就传-1（不是0）。- 修改方式：
projects settings compute <ref> --service-type Supabase --min-cu 0.5 --max-cu 2 --suspend-timeout-seconds <秒> --yes。⚠️ 必带--yes+--min-cu/--max-cu，且 Supabase 服务 min CU 下限 0.5——这几个坑照抄即可，细节见 tool-reference 的「💤 休眠超时」。- 创建后协议（非阻塞）：
projects create成功后，主动向用户解释上面的含义并非阻塞地提示是否设置休眠超时，可直接用这段话：「关于空闲休眠：当前算力常驻、不会自动休眠—稳定但更耗资源。如果想节省算力，可配置空闲自动休眠时间（再次访问无需手动操作，Supabase 自动唤醒），推荐 1 小时。」推荐 1 小时（--suspend-timeout-seconds 3600）；用户没回应或表示不需要就保持默认不休眠，不要因此卡住或阻塞后续流程。
AI Gateway
AI Gateway 提供 Workspace 分支的大模型访问、图片生成、Seedance 视频生成的能力。涉及 AI Gateway 的任务，先阅读完整指南 references/ai-gateway.md，再根据需要执行：
- 模型/端点查询：
ai-gateway status、ai-gateway models list - OpenAI 兼容调用：
ai-gateway chat completions - 图片生成：参考指南中的 Images API 示例
- 额度管理：
ai-gateway quota get、quota set-default、quota users list/get/set - 用量汇总：
ai-gateway usage
指南包含 Supabase Auth access_token、Third-Party Auth JWT、后端 service_role_key 的 JavaScript/Python 接入 Demo，以及额度单位、图片模型尺寸和排障说明。命令和参数以 byted-supabase-cli ai-gateway --help 为准。
Sandbox（隔离执行）
涉及运行不可信代码、隔离测试、AI Coding Agent、临时服务或 Sandbox 文件操作时，先阅读 references/sandbox-guide.md。
- 先检查
byted-supabase-cli --version和sandbox --help，命令不存在就byted-supabase-cli update。 - 一次性任务和调试用 CLI 的
create、connect、exec、kill；应用内连续执行、后台任务用 E2B 兼容 SDK。 - e2b SDK 必须低于 2.51（Node
e2b@2.50.0，Python 由byted_supabase_sandbox约束）：2.51 起改走/v2/sandboxes，网关 6.9.1 之前返回 404。Node SDK 要先npm pack再装 tgz，不要直接装目录。 - 创建身份三选一：用户 session（推荐）、后端 service_role +
ownerUserId、service_role +PassServiceRoleJwtToSandbox（绕过 RLS，慎用）。anon key 不能当apiKey。 - 严格区分管理面凭据、CLI 的
envdAccessToken、用户 session token 和 service_role key；sandboxID和 token 只放环境变量，不输出。执行结束或失败后都要 kill。 - 后台命令必须
timeoutMs: 0，启动后立即disconnect()。 - 结果要看
exit_code/status和 stdout / stderr，外层命令成功不代表沙箱内任务成功。 - 端口预览地址默认持有即可访问，只交给沙箱归属者；遇到 401、501、502 按参考文档的常见问题排查。
分支（branch）
| 需求 | 命令 |
|---|---|
| 列出 / 创建 / 删除分支 | branches list ／ branches create <name> ／ branches delete <branch-id> |
| 查看 / 设默认分支 | branches get <id> ／ branches get-default ／ branches set-default <id> |
| 重启分支算力（reboot）/ 时间点恢复 | computes restart <branch-id> [--compute-id <compute-id>] ／ branches restore <id> --restore-time <ts> |
⚠️ 暂停 / 重启 / 休眠 三者别混淆（最常见的误判）：
- 重启分支算力（"重启""reboot""重启算力"）→
computes restart <id> [--compute-id <compute-id>]，底层RestartBranch；切勿用projects stop+projects start模拟（那是整个 workspace 停机再开机）。- workspace 休眠 =
projects sleep，调用SuspendWorkspace，让整个 workspace 进入休眠；不要用projects stop代替。- workspace 唤醒 =
projects wake，先通过DescribeWorkspaceEndpoint获取AddressDomain，再访问 Supabase 实例一次触发唤醒；不要用projects start，后者对应显式暂停后的恢复。- 算力自动休眠 = 通过
projects settings设置SuspendTimeoutSeconds，由平台按空闲时间自动执行；这不是算力重启，也不是立即 workspace 休眠。- ⛔ 暂停 / 恢复 = workspace 级停机/开机（
projects stop/projects start），影响其下所有分支。高危红线：停后客户业务彻底不可用且无法靠 IO 自动唤醒，必须人工projects start——执行projects stop前务必复述影响并二次确认（详见核心原则 5）。一句话记忆：休眠/重启 → 客户访问能自愈或单命令恢复（低危）；暂停 → 客户访问救不回来，只能人工 start（高危，先确认）。
数据库（database）
| 需求 | 命令 |
|---|---|
| 执行 SQL（行内 / 文件） | db query "<sql>" --workspace-id ws-... ／ db query -f file.sql --workspace-id ws-... |
| 列出表 / 扩展 / 已应用迁移 | 用 db query 跑对应 SQL（见 tool-reference） |
| 应用 schema 变更 | db query -f file.sql（即时）／ 声明式见 db schema declarative |
| 生成类型 | gen types --lang typescript --workspace-id ws-... -s public |
| 安全/性能巡检 | db advisors --workspace-id ws-... ／ inspect db <subcmd> |
⚠️ 本 fork 无独立
migration子命令；schema 变更与提交流程见下方「数据库 schema 变更与提交」。
Auth（认证）
平台支持 Supabase Authentication。Auth 多在应用侧通过 SDK 使用（注册/登录/会话/JWT），管理与配置见火山Authentication 文档；SDK 用法见
references/app-integration-guide.md。
🔐 鉴权数据用
app_metadata（不可被用户改），绝不用user_metadata做授权判断（见安全 checklist）。
Realtime（实时）
平台支持 Supabase Realtime（Postgres Changes / Broadcast / Presence），在应用侧通过 SDK 订阅。配置见火山Realtime 文档；SDK 用法见
references/app-integration-guide.md。
Edge Functions（边缘函数）
| 需求 | 命令 |
|---|---|
| 列出函数 | functions list --workspace-id ws-... |
| 新建函数（本地脚手架） | functions new <name> → 编辑 supabase/functions/<name>/index.ts |
| 部署函数 | functions deploy <name> --workspace-id ws-...（公开访问加 --no-verify-jwt） |
| 下载 / 删除函数 | functions download <name> ／ functions delete <name> |
部署从本地函数目录进行（
functions new→ 编辑 →functions deploy），不再支持单文件/内联代码。编写规范见references/edge-function-dev-guide.md。
Storage（对象存储）
| 需求 | 命令 |
|---|---|
| 列出 / 创建 / 查看 / 删除 bucket | storage buckets list ／ storage buckets create <id> [--public] ／ storage buckets get <id> ／ storage buckets delete <id> |
| 对象列出 / 上传下载 | storage ls <path> ／ storage cp <src> <dst> |
| 对象移动 / 删除 | storage mv <src> <dst> ／ storage rm <file...> |
对象路径形如
ss:///<bucket>/<path>，目录操作加-r递归。
部署前端静态站点
需要把前端静态站点部署上线（可选与 Supabase 后端打通、注入环境变量，或一键创建前端 + 新建后端）时，参考
references/tool-reference.md的「Pages 动作」一节和references/workflows.md（Pages 工作流），按其中命令操作即可。⚠️ 是否新建 Supabase 要分清：
pages fast create一键链路一定会新建一个全新的 Supabase workspace（不能复用现有的）。若用户已有 Supabase（workspace / SQL / Edge Functions 都就绪），只想部署前端，别用 fast create，改用原子链路pages upload→pages create --no-deploy→pages bind <pages-project-id> --workspace-id <现有ws>→pages deploy（这条完全不建新实例）。
数据库 schema 变更与提交
做 schema 变更用 db query（行内或 -f file.sql）直接对库执行，可自由迭代。
- 本 fork 没有独立
migration子命令，不要套用官方supabase migration new/apply_migration的习惯。 - 变更前后都用只读查询确认（核心原则 2）。
- 改完跑巡检 →
byted-supabase-cli db advisors --workspace-id ws-...，修掉安全/性能告警。 - 若变更涉及视图、函数、触发器或 Storage，回到安全 checklist逐条复核。
- 需要版本化 / 可追溯的 schema 演进时，改用声明式管理：
byted-supabase-cli db schema declarative --help。
注意事项
- 本 fork 无全局只读开关；写操作的安全边界依赖 RLS（anon vs service_role）+ 操作纪律。
db query默认连接--linked项目；未 link 时务必显式传--workspace-id（必要时--branch-id）。
在线文档
对应核心原则 1：不确定时先查这些。
- 新功能发布记录（changelog）：https://www.volcengine.com/docs/87275/2105759?lang=zh
- API 发布历史 / API 列表：https://www.volcengine.com/docs/87275/2105870?lang=zh ／ https://www.volcengine.com/docs/87275/2105871?lang=zh
- SDK 发布历史 / 概述：https://www.volcengine.com/docs/87275/2248647?lang=zh ／ https://www.volcengine.com/docs/87275/2248648?lang=zh
- 使用 Database：https://www.volcengine.com/docs/87275/2385100?lang=zh
- 使用 Authentication：https://www.volcengine.com/docs/87275/2277072?lang=zh
- 使用 Realtime：https://www.volcengine.com/docs/87275/2277058?lang=zh
- 使用 Edge Function：https://www.volcengine.com/docs/87275/2288709?lang=zh
- 使用 Storage：https://www.volcengine.com/docs/87275/2277057?lang=zh
- Go SDK：https://www.volcengine.com/docs/87275/2248650?lang=zh ／ Python SDK：https://www.volcengine.com/docs/87275/2375511?lang=zh
参考资料
| 文档 | 用途 |
|---|---|
references/tool-reference.md | 命令速查：动作 → CLI + 等价 SQL |
references/ai-gateway.md | AI Gateway 接入 Demo、图片生成、额度管理与排障 |
references/workflows.md | 常见操作流程（巡检 / 变更 / 发布） |
references/sql-playbook.md | 常用 SQL 示例（CRUD / JOIN / pgvector / RPC） |
references/app-integration-guide.md | 接入 TS/Python 应用：SDK 初始化 + CRUD + Auth + Realtime |
references/schema-guide.md | 表结构设计与变更规范 |
references/rls-guide.md | 行级安全（RLS）策略配置 |
references/security-guide.md | Supabase 特有安全陷阱 checklist |
references/iam-permission-guide.md | 权限被拒（IAM 授权不足）排查：主账号 vs 子账号分流 + 授权路径 |
references/pg-best-practices/index.md | Postgres 性能与最佳实践（索引 / 连接 / 锁 / 监控等） |
references/edge-function-dev-guide.md | Edge Function 编写与部署 |
references/sdk-pitfalls.md | SDK 与查询常见陷阱（URL 长度限制 / 错误捕获 / 索引评估） |
references/sandbox-guide.md | Sandbox CLI/SDK 生命周期、凭据边界与失败诊断 |
examples/hello-world-node/ | Node.js Sandbox SDK 最小完整示例：注册/登录用户、创建 Sandbox、执行命令并回收 |
examples/hello-world-python/ | Python Sandbox SDK 最小完整示例：注册/登录用户、创建 Sandbox、执行命令并回收 |
scripts/sandbox-cli-lifecycle.sh、scripts/sandbox-node.mjs、scripts/sandbox-python.py | Sandbox CLI 生命周期和 Node/Python 完整示例 |
📚 Postgres 最佳实践细分（均由上方
index.md索引，可按需直达）：query.md·conn.md·security.md·schema.md·lock.md·data.md·monitor.md·advanced.md
💡 典型工作流：先用 CLI 创建 workspace / 建表 / 配置 RLS，再参考应用集成文档在业务代码中集成 Supabase SDK。