XBUJ · 项目文件

Profile document

v2 目标模型（.xbuj 契约 + .xbu 完整文档、Open xbu ≠ Load data）见 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；缺省用内置默认值）

本地优先：目录即项目

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。

文件格式

{
  "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

npm install @xbuckle/config

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）：

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