# XBuckle — full documentation for LLMs

> Local cloud runtime for apps and AI coding agents. Generated from the docs tree.

Source: https://github.com/21stware/xbuckle
Site: https://21stware.github.io/xbuckle/
Index: https://21stware.github.io/xbuckle/llms.txt

## Default endpoints

- HTTP: http://127.0.0.1:3100
- MCP: http://127.0.0.1:3101
- Postgres: postgresql://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable
- Redis: redis://127.0.0.1:6379
- SMTP: 127.0.0.1:1025
- anon: xbuckle-anon-key · service_role: xbuckle-service-role-key

---

# Source: docs/guide/what-is-xbuckle.md

# 产品介绍

**XBuckle** 让你在开发时**不必四处注册云服务**：在本机直接启动一套仿真环境（数据库、登录、存储、缓存、邮件等），用真实 SDK 对接。  
AI 编程助手可以**自动配置** env 与连通；功能跑通后，再把地址与密钥换成云上的，**平滑迁到生产**。

## 核心卖点

| 卖点 | 含义 |
|---|---|
| **不用四处注册** | 开发阶段不必先办一堆云账号才能写代码 |
| **本机仿真环境** | 电脑上直接启动，真协议、真 SDK，不是手写假接口 |
| **Agent 自动配置** | 对接说明可交给 AI 助手改配置、做自检 |
| **生产平滑迁移** | 本地与云上同一套 SDK 用法；上线时换端点与密钥即可 |

## 适合谁

- 想先写功能、后办云账号的开发者  
- 本地联调云能力（登录 / 库 / 存储等）的人  
- 希望 AI 助手也能接上同一套本机环境的人  

## 它不是什么

| 是 | 不是 |
|---|---|
| 本机开发与联调环境 | 生产环境 / 托管云 |
| 常见协议与 API 形状 | 完整兼容每一家云厂商 |
| 桌面应用 + AI 可自动配置 | 又一个远程 BaaS |

能力是**子集**——够本地开发与验收。详见 [能做什么](/reference/services)。

## 怎么用（一句话）

**下载安装 → 本机起项目 → 自己或 Agent 对接 → 上线时迁到真实云。**

- 步骤：[三分钟上手](/guide/quickstart)  
- 日常：[使用说明](/humans/)  
- AI：[给 AI 用](/agents/)  
- 上线检查：[Connect / Ship](/humans/connect-ship)  

## 项目与端口

每个项目有自己的配置与端口。应用和 AI 连的是**当前项目**的地址。  
多项目可同时开，各自改端口。说明见 [端口怎么配](/guide/ports)。

---

# Source: docs/guide/quickstart.md

# 三分钟上手

不用先去各家云控制台注册。本机装好、起环境、对接应用；上线时再迁到真实云。

## 1. 下载安装

1. 打开 [下载页（GitHub Releases）](https://github.com/21stware/xbuckle/releases)  
2. 下载最新的 **macOS** 安装包（`.dmg` 或 `.zip`）  
3. 把 **XBuckle** 放进「应用程序」  
4. 打开应用  

不需要安装 Node，不需要在终端里敲命令，也**不需要先注册云服务**。

若系统提示无法验证开发者：系统设置 → 隐私与安全性 → 仍要打开。正式签名版本一般不会遇到。

## 2. 本机启动仿真环境

1. 新建项目（或打开已有项目文件）  
2. 勾选你需要的服务，例如登录、数据库、缓存  
3. 启动服务  

每个项目会保存自己的端口。若和别的程序冲突，在项目菜单或设置里改端口，也可以一键「建议空闲端口」。

## 3. 对接应用（人或 Agent）

1. 打开 **Connect**  
2. 复制整页说明  
3. 自己改配置，或交给 **AI 助手自动配置**  
4. 用官方 SDK 访问说明里的本机地址  

应用连的是**当前这个项目**的地址。功能跑通后，上线时把端点与密钥换成云上的即可（平滑迁移）。

## 接下来

| 你想… | 去这里 |
|---|---|
| 熟悉桌面里有哪些页面 | [桌面应用](/guide/desktop) |
| 日常怎么用 | [使用说明](/humans/) |
| 让 AI 助手自动配置 | [给 AI 用](/agents/) |
| 上线前检查 | [Connect / Ship](/humans/connect-ship) |

## 给贡献者

只有你在改 **XBuckle 源码** 时，才需要：

```bash
git clone https://github.com/21stware/xbuckle.git
cd xbuckle && npm install
npm run electron:dev
```

日常当用户使用，请始终走上面的「下载安装」。

---

# Source: docs/guide/ports.md

# 端口怎么配

## 先记住一句

**端口跟着项目走。**  
应用和 AI 连的是「当前打开项目」的地址。改端口、换项目之后，以 **Connect** 里显示的为准。

## 在哪里改

| 入口 | 做什么 |
|---|---|
| 标题栏项目菜单 → **Ports…** | 改当前项目的端口 |
| **Settings** 里当前项目的 Ports | 同上；可点 **Suggest free ports** 自动找空闲端口 |
| Settings → **新建项目默认端口** | 只影响以后新建的项目 |

两个项目不要抢同一端口。同时开多个 XBuckle 时，建议给每个项目不同端口。

## 新建项目时的默认值

未改过时大致是：

| 用途 | 默认端口 |
|---|---:|
| 应用 HTTP / 登录 / 存储等 | 3100 |
| AI 助手（MCP） | 3101 |
| 数据库 | 5432 |
| 缓存 | 6379 |
| 邮件捕获 | 1025 |

这些只是起点。真正连应用时，请用 Connect 复制出来的地址。

## 本地密钥（Supabase 形）

仅本机有效，**不要**当成云上的正式密钥：

| 用途 | 值 |
|---|---|
| 前端 anon | `xbuckle-anon-key` |
| 服务端 service_role | `xbuckle-service-role-key` |

## 更多

- 速查表：[端口速查](/reference/ports)  
- 项目文件里怎么存端口：[项目文件](/reference/xbujson)

---

# Source: docs/guide/desktop.md

# 桌面应用

从 [Releases](https://github.com/21stware/xbuckle/releases) 安装后打开即可。下面是界面里你会用到的部分。

## 主要页面

| 页面 | 做什么 |
|---|---|
| **Services** | 安装、启停服务；看数据、日志、对接提示 |
| **Connect** | 一键生成对接说明，复制给自己或 AI |
| **Control** | 看流量、做故障模拟等（进阶） |
| **Ship** | 上线前检查、带密钥本地跑命令（进阶） |
| **Settings** | 主题、新建项目的默认端口等 |

## 项目

- 一个项目 = 一套服务与端口配置  
- 可随时改端口；多项目同时开时建议错开  
- 可导出快照、在访达中显示文件  

端口说明：[端口怎么配](/guide/ports)。

## Connect

1. 服务在跑  
2. 打开 Connect，复制  
3. 改你的应用配置，或交给 AI  

Connect **不会自动改**你别的代码仓库，只生成说明。

更多：[Connect 与 Ship](/humans/connect-ship)。

---

# Source: docs/guide/serve.md

# 无界面运行

大多数人直接打开桌面应用即可。  
如果你只想在后台跑本机服务（CI、脚本、常驻），可以用同一份安装包加参数，不必打开窗口。

端口仍以**当前项目配置**为准；下表是新建未改时的默认值。

| 默认端口 | 用途 |
|---:|---|
| 3100 | HTTP / 应用对接 |
| 3101 | AI（MCP） |
| 5432 | 数据库 |
| 6379 | 缓存 |
| 1025 | 邮件捕获 |

## 怎么选

| 方式 | 适合谁 |
|---|---|
| 双击打开桌面应用 | 绝大多数用户 |
| 安装包 `--serve` | 已安装、只要后台服务 |
| 源码 `npm run serve` | 改 XBuckle 本身的贡献者 |

## 安装包：只起服务

与 GUI 是**同一份**应用，加参数即可：

**macOS**

```bash
/Applications/XBuckle.app/Contents/MacOS/XBuckle --serve
```

或：

```bash
open -a XBuckle --args --serve
# 若 open 不传参，用直接执行 Contents/MacOS/XBuckle
```

**也可用环境变量**

```bash
XBUCKLE_SERVE=1 /Applications/XBuckle.app/Contents/MacOS/XBuckle
# 兼容旧名：XBUCKLE_HEADLESS=1
```

行为：

- 不创建窗口；macOS 下隐藏 Dock 图标  
- 仍读写正常的 Electron `userData`（与 GUI 同一份 handler 状态）  
- Ctrl+C / SIGTERM 退出  

## 生产环境怎么理解「生产」

XBuckle **不是** 线上业务后端。这里的「发布后生产」指：

- 把 XBuckle **分发给开发者 / CI**，在他们机器上当本地云  
- 业务生产（Origin 线上）仍走云 Supabase / Workers  

推荐拓扑：

```text
开发者本机 / CI
  ├─ xbuckle --serve   (或 npm run serve)
  └─ origin frontend → http://127.0.0.1:3100
```

可用 launchd / systemd / 进程管理器把 `XBuckle --serve` 做成登录自启，不必开 GUI。

## 健康检查

```bash
curl -sf http://127.0.0.1:3100/health
```

## 与 acceptance:server 的区别

- `acceptance:server`：给黄金测试用，默认挂 `fixtures/functions`  
- `serve` / `--serve`：给日常开发与发布后无 UI 使用；functions 目录由你设置 `XBUCKLE_FUNCTIONS_DIR`

---

# Source: docs/humans/index.md

# 使用说明

开发时不必先四处注册云服务。装好 XBuckle 之后，日常大致是：

1. **打开项目**（或新建一个）  
2. **本机启动**需要的仿真服务  
3. 在 **Connect** 复制对接说明——自己改配置，或交给 **Agent 自动配置**  
4. 用真实 SDK 开发；上线前再把地址与密钥换成云上的，**平滑迁移**  

## 常见场景

<div class="xb-split">
  <div class="xb-panel">
    <h3>替代本机 Supabase</h3>
    <p>不想为了本地开发起一整套 Docker Supabase 时。</p>
    <a href="/humans/replace-supabase">怎么切换 →</a>
  </div>
  <div class="xb-panel">
    <h3>Connect 与 Ship</h3>
    <p>对接说明怎么用；上线前检查与迁移准备。</p>
    <a href="/humans/connect-ship">面板说明 →</a>
  </div>
</div>

## 建议记住

- **生产构建**里不要写死本机地址  
- 上线时换云端点与密钥，SDK 用法可保持一致  
- 端口看 **Connect** 或当前项目设置  
- 交给 AI 时，优先贴 **Connect** 全文  

## 更多

- [三分钟上手](/guide/quickstart)  
- [桌面应用](/guide/desktop)  
- [常见用法](/humans/workflows)  
- [对接各厂商面](/humans/vendor-faces)

---

# Source: docs/humans/replace-supabase.md

# 替代本机 Supabase

目标：在 **不改线上、不写坏其他仓库** 的前提下，用 XBuckle 替换 `supabase start`（Docker）做日常开发，降低内存与启动成本。

## 已验证能覆盖的主路径

Origin dogfood（只读 Origin 仓库）已覆盖：

- 全部 migrations 应用（含 pgcrypto）
- signup → `auth.users` 同步 → `handle_new_user` → profiles  
- projects / rpml_files CRUD + RLS  
- `create_access_token` / `publish_release`  
- Storage bucket  
- `agent-chat` → 本机 LLM mock（SSE）  

跑分：

```bash
npm run origin:dogfood
# 或
ORIGIN_ROOT=/path/to/origin npm run origin:dogfood
```

## 人怎么切（以 Vite 前端为例）

1. 启动 XBuckle（推荐无 UI）：

```bash
XBUCKLE_FUNCTIONS_DIR=/path/to/your-app/supabase/functions \
XBUCKLE_AGENT_MOCK=1 \
npm run serve

# 或发布后的安装包：
# /Applications/XBuckle.app/Contents/MacOS/XBuckle --serve
```

2. **只改本机** `frontend/.env.local`（不要提交、不要用于 prod build）：

```bash
VITE_SUPABASE_URL=http://127.0.0.1:3100
VITE_SUPABASE_ANON_KEY=xbuckle-anon-key
```

3. 若需要跑 edge：安装 Deno；`XBUCKLE_FUNCTIONS_DIR` 指向应用的 `supabase/functions`。  
   - 无真实 LLM key 时加 `XBUCKLE_AGENT_MOCK=1`（打到 XBuckle `/llm`，并把 `AGENT_MODEL`
     一并钉成 `gpt-mock`，覆盖 `functions/.env` 里为真实厂商写的模型名）  
   - 想保留应用自己的模型名，用 `XBUCKLE_LLM_MODELS=模型名` 注册，或在 shell 里显式设
     `AGENT_MODEL`  
   - 有 key 时可去掉 mock，仍会强制 `SUPABASE_URL` 为本机  

4. 首次空库时，用控制面或脚本应用 migrations（dogfood 使用 `POST /db/exec`）。桌面 Data 面板也可执行 SQL。

## 仍然更适合留在 Docker / 云的场景

- 真 Google/GitHub OAuth（XBuckle 仅本地 auto-code）  
- 依赖完整 WAL Realtime / Presence 的产品路径  
- 官方 E2E 若写死 `127.0.0.1:54321` 与 Supabase CLI 行为  
- 需要 `pg_cron` 真调度外发邮件（本机为 stub + 不外发）  

## 安全约束（硬）

| 做 | 不做 |
|---|---|
| 只写 loopback URL | 把 dogfood 指到 `*.supabase.co` |
| 只读其他产品仓库做验证 | 在 XBuckle 任务里改 Origin 产品代码（除非你明确要求） |
| 本地 anon/service_role 固定串 | 把云密钥写进 functions `.env` 还指望 XBuckle 去打云 |

## 相关

- [端口与密钥](/guide/ports)
- [Acceptance / Dogfood](/agents/testing)
- [环境变量](/reference/env)

---

# Source: docs/humans/connect-ship.md

# Connect 与 Ship

## Connect：对接说明

根据**当前项目**已启动的服务，生成一段说明：该装什么 SDK、env 怎么写、本机地址是什么、有哪些限制。

| 场景 | 用哪个 |
|---|---|
| **第一次**把应用接到本机 | From scratch |
| 已经接好，继续日常开发 | Develop |

### 怎么用

1. 服务在跑  
2. 打开 Connect，选好 tab  
3. 复制全文  
4. 自己改应用配置，或整段交给 AI 助手  

Connect **只生成说明**，不会自动改你别的代码仓库。

### Develop 适合什么时候

项目已经用 XBuckle 跑起来了，新人或不熟悉的 AI 要在同一本机环境上继续改功能、迁库、联调——用 Develop，而不是重新「接线」一遍。

## Ship：上线前

偏「快要上线」时用：

- 检查清单  
- env 模板  
- 扫项目里用到的环境变量  
- 带本机钥匙串密钥本地跑命令（日志会打码）  

Ship 是检查和本地验证，**不是**一键部署到云上。  
生产密钥请放钥匙串或你们自己的密钥系统，不要当成 mock 里的生产真相。

## Control（进阶）

看最近请求、模拟故障、固定某条路径的响应。适合联调「下游挂了怎么办」。

---

# Source: docs/agents/index.md

# 给 AI 用

XBuckle 支持 **Agent 自动配置**：人在本机起好仿真环境后，编程助手可以读对接说明、改应用 env、接 SDK、做连通自检——减少手工搬砖。

## 它需要知道的几件事

- 这是 **本机仿真环境**，不是远程云；开发时不必先办一堆云账号  
- 应用应使用 **真实 SDK** 连当前项目的本机地址  
- 上线时再换成生产端点与密钥（**平滑迁移**），不要把 loopback 写进生产构建  
- 能力是子集；不确定时读 [能做什么](/reference/services)  
- **不要**把验收流量打到用户的生产云，除非人明确要求  

## 怎么接

1. 人先在桌面打开项目、启动服务  
2. 把 **Connect** 说明交给助手，或让助手连上 MCP  
3. 助手改应用 env / 初始化代码（自动配置）  
4. 跑自检确认能打通本机  

端口以 **当前打开的项目** 为准。

## 深入

| 文档 | 内容 |
|---|---|
| [接上 MCP](/agents/mcp) | 工具、资源、常用顺序 |
| [推荐流程](/agents/workflow) | 从接到验收的一步步 |
| [可粘贴说明](/agents/prompt) | 直接塞进系统提示 |
| [验收](/agents/testing) | 回归与 dogfood |

给爬虫 / 长上下文：站点根目录的 [llms.txt](/llms.txt)。

---

# Source: docs/agents/mcp.md

# MCP 对接

## 连接

- 默认：`http://127.0.0.1:3101`  
- 桌面应用启动时会拉起 MCP；headless 用 `npm run serve` / `npm run acceptance:server`  

在 Cursor 等客户端里把该地址配成 MCP server（HTTP MCP）。

Agent 自助搭云的首选路径见 skill [`skills/xbuckle-local-cloud`](../../skills/xbuckle-local-cloud/SKILL.md)：**打开 / 绑定应用仓库里的 `*.xbujd` 包**，按包内 `.xbuj` 用 `services.*` 对齐 runtime。

## 项目包（真相源）

```text
app/**/my-app.xbujd/
  my-app.xbuj           ← 提交
  handler.json          ← 提交
  database/pg.dump      ← 已被包内 .gitignore 排除；网盘 / .xbudump 共享，勿 force-add
```

不要在应用仓库根另写 `xbuckle.stack.json`（legacy）。

## 控制面：服务生命周期

| Tool | 用途 |
|---|---|
| `services.register` | 安装并启动 catalog 服务（`installed` + `running`） |
| `services.unregister` | 卸载（`installed=false`，`stopped`） |
| `services.configure` | 写入 per-service config bag |
| `services.start` / `services.stop` | 启停（start 也会 mark installed） |
| `services.list` / `services.describe` | 目录、限制、envHints、当前 config |
| `stack.plan` / `stack.apply` / `stack.status` | **Legacy** — 旧 `xbuckle.stack.json` 客户端；新流程勿用 |

Env 由 Agent / 人类写入应用仓库（Connect 文案或 catalog `envHints`）。XBuckle **不会**代写 `.env`。

## 观测

| Tool | 用途 |
|---|---|
| `observe.tables` | 列表（public） |
| `observe.query` | 只读 SQL（单条 SELECT/WITH） |
| `observe.traffic` | 按 `serviceId` / `pathPrefix` / `since` 过滤流量 |
| `observe.events` | mail / queue / functions / edge / billing 等缓冲 |
| `traffic.recent` | 未过滤的最近流量 |
| `runtime.selftest` / `compat.check` | 健康与分层检查 |

## 内容突变（数据面仍优先官方 SDK）

| Tool | 用途 |
|---|---|
| `data.query` / `data.tables` | 控制面 SQL / 表（DDL/DML；应用应走 `:5432`） |
| `auth.mint` / `auth.users.*` | 本地用户与 token |
| `s3.*` / `queue.*` / `cache.*` / `mail.*` / `flags.*` / `llm.*` / … | 各 vendor face |

## 故障与 Ship

| Tool | 用途 |
|---|---|
| `chaos.*` / `route.override.*` | 故障注入与固定响应 |
| `ship.checklist` / `env_template` / `scan` / `run` | 上线检查与密钥注入跑命令 |

## Resources

`resources/list` → `xbuckle://agent-guide`、`catalog`、`coverage`、`connect`、`ship` 等。

## 反模式

- 新建 `xbuckle.stack.json` 当第二份服务清单  
- 用 `data.query` 代替应用里的 `pg` 客户端  
- 把云端 URL 写进本地 env 再跑 destructive 工具  
- 假设 S3 / Search / Gateway 等是完整云厂商  
- 指望 MCP 写出应用的 `.env`，或以 `.xbudump` 当作活绑定

---

# Source: docs/agents/workflow.md

# 推荐工作流

## 场景：帮人类把应用接到 XBuckle

```text
1. health + runtime.selftest
2. 读桌面 Connect → From scratch 的 prompt（或 services.describe）
3. 在应用仓库改 env（仅 loopback）
4. 用真实 SDK 发一个最小请求并确认 traffic.recent
5. 更新/补充测试；不要改 XBuckle 除非任务要求
```

## 场景：已有 .xbuj，继续开发（功能 / 数据）

```text
1. 人类 Open 仓库里的 .xbuj（旁路 .xbujd/ 复用数据）
2. 复制 Connect → Develop tab 的 prompt
3. selftest；迁移/灌数打 :5432；业务用真实 SDK
4. traffic.recent / Control 验收
5. 这不是 Connect，也不是 Ship
```

## 场景：实现依赖 Postgres / Redis 的功能

```text
1. 确认 database / cache 服务在跑（Develop prompt）
2. DATABASE_URL / REDIS_URL → 本机 wire
3. 迁移或建表：可用 MCP data.query / 应用 migration 跑到 :5432
4. 业务代码只用官方 SDK
5. 用 chaos.inject 验证超时/重试（可选）
```

## 场景：Supabase 形应用（Auth + REST + RLS）

```text
1. 指 VITE_SUPABASE_URL=http://127.0.0.1:3100
2. anon key = xbuckle-anon-key
3. 应用 migrations 到 PGlite（/db/exec 或 psql :5432）
4. signup → 带 JWT 调 /rest/v1
5. 需要 edge：XBUCKLE_FUNCTIONS_DIR + deno；无 key 时 XBUCKLE_AGENT_MOCK=1
```

## 场景：修 flaky 联调

```text
1. traffic.recent 看实际 path/status
2. route.override.set 固定下游
3. 或 chaos.inject 制造 500/延迟
4. 修应用重试/错误处理
5. chaos.clear
```

## 场景：上线前检查

```text
1. ship.scan + ship.checklist
2. ship.env_template 对齐部署密钥（不是 mock 值）
3. 提醒人类：生产构建不要 bake localhost
```

## 输出期望

向人类汇报时写清：

- 改了哪些 env（值是否仅 loopback）  
- 打过哪些端点 / selftest 结果  
- 已知能力缺口（对照 services.describe）

---

# Source: docs/agents/prompt.md

# 给 Agent 的短指令

把下面整段发给 agent（可再附上桌面 Connect 页内容）。

````md
你在使用 XBuckle —— 本机云运行时（不是托管云）。
若已通过 `npx skills add` 安装 `xbuckle-local-cloud`，先阅读该 skill 并按 bootstrap 清单执行。

## 端点
- HTTP / Supabase 形: http://127.0.0.1:3100
- MCP: http://127.0.0.1:3101
- Postgres: postgresql://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable
- Redis: redis://127.0.0.1:6379
- SMTP capture: 127.0.0.1:1025

## Supabase 形本地 key
- anon: xbuckle-anon-key
- service_role: xbuckle-service-role-key

## 规则
1. 只用真实 SDK / 官方客户端打上述本机地址。
2. 业务代码不要依赖 POST /db（那是控制面）；DB 走 :5432。
3. 先 MCP `runtime.selftest`，再改应用。
4. 禁止把验收流量发到 *.supabase.co 或其他生产后端，除非人类明文要求。
5. 能力是子集：先 `services.describe` 或阅读 docs 里的服务边界，不要假设完整 AWS/Supabase。
6. 需要 edge 时：人类应设置 XBUCKLE_FUNCTIONS_DIR；无 LLM key 时用 XBUCKLE_AGENT_MOCK=1。
7. 不要修改无关仓库；XBuckle 与业务仓分离。

## 完成标准
- selftest/acceptance 相关项通过
- 汇报改动的 env（必须是 loopback）与验证过的路径
````

## 更短版（上下文紧张时）

```text
XBuckle local runtime: HTTP :3100, MCP :3101, PG :5432, Redis :6379.
Supabase anon=xbuckle-anon-key. Use real SDKs. No prod URLs. Run runtime.selftest first.
Honest subsets only — check services.describe. App DB via :5432 not POST /db.
```

---

# Source: docs/agents/testing.md

# 验收与 Dogfood

## 单元测试（Vitest）

```bash
npm test                 # vitest run
npm run test:watch       # interactive
```

覆盖（`tests/**/*.test.ts`）：

| 套件 | 内容 |
|---|---|
| `config-data-binding` | `.xbuj` / manifest v2 `data` 绑定解析、路径 helpers |
| `xbu-merge` | Load data **merge** 规则 + `hasInstanceData` |
| `profile-archive` | `.xbu` v2 ZIP 往返（FORMAT / manifest.xbuj / data/*）、legacy 读 |
| `project-package` | `prepareOpenPath` / 包内 config 解析 |
| `project-data-guards` | `loadProjectData` 注入 `pg.dump`、绑定空包 |
| `xbu-load-ui` / path helpers | 进度 UI store、链接路径解析 |

`npm run acceptance` 会先跑 `npm test`。

`.xbu` 归档往返也在 acceptance：`profile.archive_roundtrip`（`scripts/acceptance/profile-roundtrip.mjs`）。

## 契约层：acceptance

```bash
npm run acceptance
```

会先 `typecheck`、**单元测试**、重新打包 `server.cjs`，再对 headless proxy 跑黄金脚本（LLM、Auth、S3、DB wire、Redis、Secrets、Queue、Search、MCP、Ship、PostgREST、GoTrue、Storage、Realtime、Edge …）。

期望：**全部 PASS**（当前 82 项）。细节见 [Acceptance 参考](/reference/acceptance)。

Agent 侧也可先调 `runtime.selftest`（更快的探针集合）。

## 场景层：Origin dogfood

在 **不修改 Origin 仓库** 的前提下，只读其 migrations/functions，验证「能否当本地 Supabase」：

```bash
ORIGIN_ROOT=/path/to/origin npm run origin:dogfood
```

会：

1. 起 proxy，并设置 `XBUCKLE_FUNCTIONS_DIR` 到 Origin 的 `supabase/functions`  
2. `XBUCKLE_AGENT_MOCK=1`（LLM 走本机，并把 `AGENT_MODEL` 一并钉成 `gpt-mock`）  
3. 应用全部 SQL migrations  
4. signup / profile / project / RLS / access_token / publish_release / storage / agent-chat  

期望：**21 项全 PASS**。需要本机装 `deno` 才能跑 edge 两项。

失败时不要改 Origin；在 XBuckle 或测试脚本侧修。这类失败最常见的形态是应用
`functions/.env` 给真实厂商钉了模型名或 base URL，而 XBuckle 只改写了其中一部分——
覆盖要成套，否则应用会打到本机 mock 却带着云厂商的模型名。

## Agent 验收清单（复制用）

```text
[ ] GET :3100/health
[ ] runtime.selftest → 0 failures
[ ] 应用 env 仅为 127.0.0.1/localhost
[ ] 最小业务路径（登录或一条 REST/SQL）成功
[ ] traffic.recent 能看到对应请求
[ ] 若声称 Supabase 替换：migrations + RLS +（可选）agent-chat
[ ] 未对 *.supabase.co 发送写操作
```

---

# Source: docs/reference/ports.md

# 端口与端点

端口是 **每个 Profile（`.xbuj`）自己的** `ports` 字段，不是全局常量。完整说明见 [指南：端口与密钥](/guide/ports)。

## Listeners（新建未改时的默认值）

| 字段 | 默认端口 | 用途 |
|---:|---:|---|
| `proxy` | 3100 | HTTP 代理 / SDK base / Supabase 形路径 |
| `mcp` | 3101 | MCP（Agent 工具） |
| `pg` | 5432 | Postgres (PGlite) wire |
| `redis` | 6379 | Redis RESP |
| `smtp` | 1025 | SMTP 捕获 |

应用与 Agent 应使用 Connect / MCP 给出的**当前项目**地址；多实例并行时请改各 Profile 的 ports。

## Supabase-shaped paths（在 proxy 端口上）

- `/auth/v1/*`
- `/rest/v1/*`
- `/storage/v1/*`
- `/realtime/v1/websocket`
- `/functions/v1/<name>`

## Control-plane paths（非业务）

- `/db`, `/db/query`, `/db/exec`, `/db/reset`
- `/cache`, `/mail`, `/secrets`, …（桌面 explorer / MCP）

---

# Source: docs/reference/env.md

# 环境变量

## 应用侧（指到 XBuckle）

| 变量 | 示例 | 说明 |
|---|---|---|
| `DATABASE_URL` | `postgresql://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable` | 真 Postgres SDK |
| `REDIS_URL` | `redis://127.0.0.1:6379` | 真 Redis SDK |
| `VITE_SUPABASE_URL` | `http://127.0.0.1:3100` | supabase-js |
| `VITE_SUPABASE_ANON_KEY` | `xbuckle-anon-key` | 本地 anon |
| `SUPABASE_URL` | `http://127.0.0.1:3100` | 服务端 / edge |
| `SUPABASE_ANON_KEY` | `xbuckle-anon-key` | |
| `SUPABASE_SERVICE_ROLE_KEY` | `xbuckle-service-role-key` | 仅本机服务端 |

## XBuckle 进程侧

| 变量 | 说明 |
|---|---|
| `XBUCKLE_FUNCTIONS_DIR` | 指向 `supabase/functions` 目录以启用 `/functions/v1` |
| `XBUCKLE_SUPABASE_URL` | edge 子进程看到的 Supabase URL（必须 loopback；默认 `http://127.0.0.1:3100`） |
| `XBUCKLE_AGENT_MOCK` | `1` 时强制 `AGENT_PROVIDER=openai`、`OPENAI_BASE_URL=<local>/llm`、`AGENT_MODEL=gpt-mock` |
| `XBUCKLE_LLM_MODELS` | 逗号分隔，额外注册 `/llm` 可服务的模型名（应用想保留自己的模型名时用） |
| `XBUCKLE_EDGE_LOG` | `1` 时打印 Deno edge 日志 |
| `CLOUDMOCK_PROXY` | acceptance 脚本用的代理基址 |
| `CLOUDMOCK_MCP` | acceptance 脚本用的 MCP 基址 |
| `ORIGIN_ROOT` | `origin:dogfood` 只读 Origin 仓路径 |
| `DATABASE_URL` | `pg-query.mjs` 等脚本连 wire 时使用 |

## Edge 从 functions `.env` 读取时

会合并 `functions/.env` 与 `functions/<name>/.env`，但 **始终覆盖**：

- `SUPABASE_URL` → 本机  
- `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` → XBuckle 本地键  

避免 functions 环境误指云项目。

Mock 模式（`XBUCKLE_AGENT_MOCK=1` 或无任何厂商 key）还会覆盖 `AGENT_MODEL`：
既然 provider 与 base URL 已被钉到本机 mock，`functions/.env` 里为真实厂商钉的模型名
（如 `deepseek-v4-flash`）就会被 `/llm` 判为未知模型而 400。只有**在 shell 里显式设置**
的 `AGENT_MODEL` 才会被保留，与 `SUPABASE_URL` 同一条规则。

想让应用继续用自己的模型名（不经 edge，直接打 `/llm`），用
`XBUCKLE_LLM_MODELS=your-model-a,your-model-b` 注册即可；未注册的模型名仍按 OpenAI 形
返回 400 `model_not_found`。

---

# Source: docs/reference/services.md

# 能做什么

XBuckle 模拟的是开发常用的**协议与厂商表面**，不是完整云。  
下面用来对齐预期：能联调什么、哪里会不够用。日常以桌面 **Services** 面板里的说明为准。

---

以下偏技术细节，给需要核对兼容面的人与 AI。

## Coverage Contract

每个宣称兼容的协议面（`wireCompatible` / catalog 服务）应满足四条，否则在 `limits` 中**显式豁免**：

| 维度 | 要求 |
|---|---|
| **lifecycle** | 核心资源 create / get / list / update（或厂商等价）+ delete/cancel |
| **errors** | 至少 401/403、404、校验 400，响应为厂商形 JSON |
| **observe** | 流量进 Global Control；领域 In/Out 或 history 进该服务 View/Data |
| **acceptance** | `scripts/acceptance` 含 happy + ≥2 条负路径 |

矩阵状态：`met` | `partial` | `exempt` | `missing`（源码 `shared/coverage.ts`）。MCP：`xbuckle://coverage`、`services.describe`、`compat.check`。

仿真的是**厂商/协议表面**，不是某个应用的业务捷径。任意项目用官方 SDK / 标准 HTTP 指到本机即可联调——见 [厂商面接入](/humans/vendor-faces)。

**Provider 目录**（`shared/service-providers.ts`）只含本机可打的云 / 事实标准面，且均为 `wireCompatible: true`。长尾 SaaS 不列；Ship 侧也不会再出现「只改文档、本地打不通」的选项。

**豁免示例**：Cache（RESP）与 SMTP（banner）的 `errors` 维度为 `exempt`——无 HTTP JSON 401/404 形状，在各自 `limits` 中写明。

## Wire 强（优先用官方 SDK）

| 服务 | 兼容面 | 主要限制 |
|---|---|---|
| Database | Postgres wire + PostgREST `/rest/v1` + Realtime CDC（由 REST 写入驱动） | PGlite 扩展子集；wire SQL 暂不扇出 CDC |
| Cache | Redis RESP | 非 Cluster/模块/完整 Lua |
| SMTP / Mail | 本地捕获 | **不外发** |
| Auth | OIDC + GoTrue `/auth/v1` | OAuth 为本地 auto-code；非真 Google/GitHub |

## Supabase 形适配器

| 表面 | 状态 |
|---|---|
| GoTrue signup/login/refresh/magic link | 可用；用户同步到 `auth.users` |
| PostgREST + RLS (`auth.uid()`) | 常用 filter/rpc/upsert |
| Storage `/storage/v1` | bucket/object/signed 子集 |
| Realtime | heartbeat/join + postgres_changes（REST 路径） |
| Edge `/functions/v1` | 本机 Deno；需 `XBUCKLE_FUNCTIONS_DIR` |
| pgcrypto | 已加载；`pg_net`/`pg_cron` 为 stub |

## Shape 级 mock（能联调，非全量云）

S3、SQS、Secrets Manager、Feature Flags、Search、API Gateway、CDN、Edge Worker rewrite、**Billing（Stripe `/billing/v1` + Paddle `/paddle`）**、SMS、LLM（echo/stream mock）等。

**Billing**：

- Stripe 形：`/billing/v1`（customers / checkout sessions / invoices）
- Paddle Billing API 形：`/paddle`（customers / subscriptions / prices / products / portal-sessions / events + 可选 localhost 签名 webhook）
- **不**模拟 `cdn.paddle.com` / Paddle.js overlay

**LLM**：OpenAI 兼容 `/llm/v1/chat/completions` 与 Anthropic `/llm/v1/messages`，用于本地 agent 与 edge mock，不是计费云模型。

## Explicit non-goals

真扣款 / 真短信 / 真邮件外发、SigV4 密码学校验、CF Workers isolate、完整 ES DSL、Redis Cluster 等。见 `docs/REALITY-REASSESSMENT.md`。

## 如何自查

- MCP：`services.describe`、`xbuckle://coverage`、`compat.check`
- 文档站本页
- 源码：`src/data/serviceSim.ts`、`shared/coverage.ts`

---

# Source: docs/reference/xbujson.md

# XBUJ · 项目文件

> **v2 目标模型**（`.xbuj` 契约 + `.xbu` 完整文档、Open xbu ≠ Load data）见
> **[xbuj-xbu-v2.md](./xbuj-xbu-v2.md)**。下文描述的是当前仍在用的 **`.xbujd/` 兼容布局**。

打开单位是 **`.xbujd/` 目录包**；包内的 `.xbuj` 是配置，数据与配置同目录。

| 形式 | 角色 | 打开后行为 |
|---|---|---|
| **`Name.xbujd/`** | **活项目包**（配置 + 数据） | Open Folder 绑定该目录；读写回写包内 |
| **裸 `.xbuj`** | **仅配置** | Open File；不绑定数据目录；Save As 可另存为包 |
| **`.xbudump`** | **一次性快照**（ZIP） | Import → 物化为新的 `Name.xbujd/` 再打开 |

兼容读取：旧后缀 `.xbujson` / `.xbu` 仍可打开；旧旁路布局（`a.xbuj` 与 `a.xbujd/` 同级）首次打开会迁入包内并提示 Migrated。

包内 `.xbuj` 只记录：

- profile 名称
- 要安装的 service 列表
- 可选的 provider 面（如 billing → stripe | paddle）
- 可选的 `ports`（proxy / mcp / pg / redis / smtp；缺省用内置默认值）

## 本地优先：目录即项目

```text
my-app.xbujd/                 ← 打开单位
  my-app.xbuj                 ← 轻量配置（提交）
  handler.json                ← handler 状态（可 diff，提交）
  database/pg.dump            ← 二进制 dump（已被 .gitignore 排除，走网盘共享）
  database/meta.json          ← dump 引擎版本戳（自动，随 dump 一并忽略）
  README.md                   ← 自动生成的 git / 数据共享说明
  .gitignore  .gitattributes  ← git 卫生（自动生成，缺省才写）
  .xbuckle.lock               ← 运行期占用锁（勿提交；已被 .gitignore 覆盖）
```

| 文件 | 角色 |
|---|---|
| **`my-app.xbujd/`** | 项目包（Open Folder） |
| **`my-app.xbujd/my-app.xbuj`** | 轻量配置（services / providers / ports） |
| `my-app.xbujd/database/pg.dump` | PGlite 二进制 dump |
| `my-app.xbujd/database/meta.json` | 写 dump 的 PGlite 版本 + 时间；版本不匹配时打开会告警 |
| `my-app.xbujd/handler.json` | handler 状态（**不含** dump；缩进 JSON，可 diff） |
| `my-app.xbujd/.xbuckle.lock` | 绑定期间的进程占用锁（pid/host）；退出自动清除，陈旧锁自动接管 |

磁盘写入有约 5s 防抖，且内容未变则跳过。完整可携快照仍用 **Export .xbudump**。

| 时机 | 行为 |
|---|---|
| 新建 profile | 默认 `~/Documents/XBuckle/<name>.xbujd/`；Choose Folder… 选父目录 |
| 增删 service、切 provider | 约 600ms 防抖后自动写回包内 `.xbuj` |
| DB / handler 变更 | 约 5s 防抖后写入包内 |
| Save As… | 另存为新的 `.xbujd` 包 |
| Export .xbudump… | ZIP 根布局对齐活包（`.xbuj` + `handler.json` + `database/pg.dump`）+ v3 profile/ |
| 导入 `.xbudump` | 物化为 `Name.xbujd/` 后打开 |
| 打开已绑定包 | 直接切到该 profile 并从包内恢复数据 |
| 删除 profile | 一并删除托管目录里的包；自选位置的文件保留 |
| 关闭 profile | 只移出列表，包原样保留 |

文件被外部改动时会弹 **Reload / Keep mine**。

## 文件格式

```json
{
  "kind": "xbuckle.config",
  "version": 1,
  "name": "my-app",
  "services": ["auth", "database", "cache", "s3", "llm"],
  "providers": {
    "llm": "openai",
    "billing": "stripe"
  },
  "ports": {
    "proxy": 3200,
    "mcp": 3201,
    "pg": 5433,
    "redis": 6380,
    "smtp": 1026
  },
  "generatedAt": "2026-08-07T12:00:00.000Z"
}
```

| 字段 | 必需 | 说明 |
|---|---|---|
| `kind` | 推荐 | 固定 `xbuckle.config` |
| `version` | 可选 | 当前 `1` |
| `name` | 推荐 | profile 名；缺省为 `Untitled` |
| `services` | **是** | catalog service id 数组 |
| `providers` | 可选 | `serviceId → providerId` |
| `ports` | 可选 | 本项目监听端口 |
| `generatedAt` | 可选 | ISO 时间戳 |

**合法 service ids**：`auth` · `database` · `cache` · `secrets` · `s3` · `search` · `mail` · `smtp` · `queue` · `llm` · `edge-functions` · `billing` · `feature-flags`

## 在 XBuckle 中使用

| 入口 | 行为 |
|---|---|
| 空文档屏 | **Open Folder…**（主）/ Open File… / New Document |
| File → Open Folder…（⌘O） | 选择 `.xbujd` 目录 |
| File → Open File…（⇧⌘O） | `.xbuj` / `.xbudump` |
| 标题栏 Save As… | 另存为新包 |
| 标题栏 Export | 导出 `.xbudump` |
| Settings → Profiles | Reveal Project Folder |
| 双击裸 `.xbuj` | 打开为配置-only（若旁有旧 sidecar 则迁入包） |
| `xbuckle://` 深链 | 确认后创建新包 |

## URL scheme

```
xbuckle://create?name=my-app&services=auth,database,cache
xbuckle://create?name=shop&services=auth,billing&providers=billing:paddle
xbuckle://create?config=<url-encoded JSON>
```

## SDK：`@xbuckle/config`

```bash
npm install @xbuckle/config
```

```ts
import { buildFile, buildLink, type Plan } from "@xbuckle/config";

const plan: Plan = {
  name: "my-app",
  serviceIds: ["auth", "database", "cache"],
  providers: { llm: "openai" },
};

const xbujText = buildFile(plan); // 写入 my-app.xbujd/my-app.xbuj
const link = buildLink(plan);
```

## Git 共享

共享时把 **`.xbujd/`** 放进 git，用 Open Folder 打开——但 **dump 不进 git**：
`pg.dump` 是 gzip 二进制，git 无法做增量压缩，每次提交数据变更都会让历史
整体膨胀一份 dump 的大小。因此包内自动生成的 `.gitignore` 默认排除
`database/pg.dump` 与 `database/meta.json`。

数据走带外共享：把 `database/pg.dump`（连同 `meta.json`）通过网盘 /
AirDrop / 对象存储发给协作者，对方放进包内 `database/` 再 Open Folder 即可；
或者用 **Export .xbudump** 发一次性快照（导入会物化为新包）。

绑定或首次写入时会在包内生成（已存在则不动）：

- `.gitignore` — 忽略 `.xbuckle.lock`、`*.tmp`、`database/pg.dump`、`database/meta.json`
- `.gitattributes` — 将 `database/pg.dump` 标记为 `binary`（仅在你 force-add 或上 LFS 时生效）
- `README.md` — 记录上述 git / 数据共享约定

注意事项：

- **确实需要把数据纳入版本管理时**才考虑 git LFS（历史不膨胀，但 LFS 存储同样逐版本累积，协作者都需装 LFS）：

```bash
git lfs install
git lfs track "*.xbujd/database/pg.dump"
git add .gitattributes
```

- **引擎版本**：`database/meta.json` 记录写 dump 的 PGlite 版本；协作双方 XBuckle 版本差异过大时，打开会在日志中告警（restore 可能失败，需一方重新导出）。网盘共享时请连同该文件一起发。
- **并发保护**：包被某个 XBuckle 进程绑定时会持有 `.xbuckle.lock`（含 pid/host）。同机第二个实例打开同一包会唤起持有者窗口；跨机残留的锁（拷贝/克隆带来）会被自动接管。

源码：`packages/config` · `shared/xbujson.ts` · `src/lib/xbujson.ts` · `src/runtime/profileDocument.ts` · `electron/project-data.ts` · `electron/project-package.ts`