同步、快照与导出
Markdown 版用目录树、变更流和 Webhook 将 Space 同步到其他系统,用快照固定某一时刻,用导出和导入迁移整个 Space。
同步由两个接口配合:GET /v2/spaces/{space_id}/tree 取得某一时刻的全貌,GET /v2/spaces/{space_id}/changes 取得之后的变更。
运行同步循环
- 读
tree,保留第一页的changes_cursor。翻页不是同一个快照,第一页的游标能覆盖翻页期间的写入。 - 把游标传给
changes,应用返回的事件。 - 继续用响应里的
cursor。has_more为true时立即再调用一次,否则带wait长轮询。
# First page of the tree. Keep its changes_cursor.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree?recursive=true" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Then follow the feed, waiting up to 30 seconds when nothing has changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/changes?cursor=$CURSOR&wait=30" \
-H "Authorization: Bearer $MIRABASE_API_KEY"- 不带
cursor时变更流从当前时刻开始,所以全量同步要先读tree。 - 游标过期时返回 410
cursor_expired:重新读tree,从新的changes_cursor继续。事件的保留期和长轮询的上限见参考页。
事件
每个事件的 op 是 create、update、move、delete 或 restore,含义见 DevChangeOp。
应用事件
- 事件可能重复,也可能重复
tree已经展示的内容,所以按entry_id幂等应用。 move只带新路径。自己维护entry_id到路径的映射,从tree开始。- 目录自身不产生事件,空目录的增删需通过
tree查看。 - Agent 的私有记忆不进入变更流。
- 带
branch时是分支自己的变更流,形状和规则都不同,见 分支与挂载。
查看最近的修改
多人或多个 Agent 共用一个 Space 时,开始工作前可先调用 GET /v2/spaces/{space_id}/activity:该接口已将最近几天的变更流按主体和 Entry 汇总,无需从头读取 changes 再自行归并。
接收 Webhook
不想轮询 changes 时,用 POST /v2/spaces/{space_id}/webhooks 订阅主线的变更。Mirabase 按顺序推送,每批若干条事件,同一时间只有一批在途,至少送达一次;请求体的结构见 DevWebhookPayload。
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/mirabase", "ops": ["create", "update", "delete"]}'import { parseWebhook } from "@mirabase/sdk/developer";
// Verify against the raw body, before parsing JSON. Throws on a bad or stale signature.
const payload = await parseWebhook({
secret: process.env.MIRABASE_WEBHOOK_SECRET!,
header: request.headers.get("Mirabase-Signature"),
body: await request.text(),
});
// Dedupe on payload.delivery_id: a retry resends the same batch.
for (const change of payload.events) apply(change);- 每个请求都要按上面的示例校验签名;签名格式和时间戳容差见 DevWebhook。
- 按
Mirabase-Delivery-Id(即delivery_id)去重:重试时同一批原样重发。事件按entry_id应用。 - 尽快返回 2xx,将耗时的处理放在响应之后。失败的判定标准以及重试间隔见 DevWebhook。
- 密钥只在创建响应中返回。密钥丢失时调用
POST /v2/webhooks/{webhook_id}/rotate-secret。
推送停止时,status 变为 disabled,disabled_reason 说明原因。PATCH /v2/webhooks/{webhook_id} 带 {status: "active"} 重新启用,GET /v2/webhooks/{webhook_id}/deliveries 列出推送记录。
创建快照
POST /v2/spaces/{space_id}/snapshots 记录当前时刻每个文件的路径和版本。版本不可变,所以快照不复制字节。
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/snapshots" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "before-import"}'
# Read a file as the snapshot pinned it, by name or id.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md&snapshot=before-import" \
-H "Authorization: Bearer $MIRABASE_API_KEY"- 在
tree、files和files/content-url上传入snapshot=<id 或名称>,即可读取快照固定的版本,即使文件此后已修改、移动或移入废纸篓。 - 快照的
changes_cursor从同一时刻衔接changes,因此快照加变更流就是一次不遗漏、不重复的全量同步。 - 快照只包含有路径的文件:空目录、记忆、导入的网址和文本都不在其中。
导出和导入
POST /v2/spaces/{space_id}/exports 把文件导出为 tar 归档,POST /v2/spaces/{space_id}/imports 把 tar 或 gzip 压缩的 tar 导入 Space。两者都以任务执行,返回 202 和 job_id,按 API 约定 跟踪。
# Export as a job, then follow it with GET /v2/jobs/$JOB_ID
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/exports" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"snapshot": "before-import"}'
# Once it succeeded: a signed download, valid up to five minutes.
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID/content-url" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Import a tar that is already a file you can read, into another Space.
curl -X POST "https://api.mirabase.dev/v2/spaces/$OTHER_SPACE_ID/imports" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source_entry_id": "'$ARCHIVE_ENTRY_ID'", "path": "/", "on_conflict": "skip"}'导出
- 任务开始时确定文件列表,因此归档对应开始时刻的 Space 状态;传入
snapshot时则对应该快照的状态。 - 归档只包含文件:没有路径的内容、记忆和版本历史都不导出。归档的格式见参考页。
- 任务成功后,用
GET /v2/jobs/{job_id}/content-url获取归档的下载地址。
read_root,都会使归档立即失效,需要重新导出。导入
- 先用
PUT .../files或uploads把归档放进任意 Space,source_entry_id是归档的 Entry id。 - 本 API 导出的归档会按原路径和媒体类型导回,因此导出后再导入可以还原;其他归档放到
path下。 - 每个文件都像
PUT一样写入,适用相同的路径规则、写入根路径、write_mode和配额;导入不会变成提案。 - 导入不是原子操作:无法写入的条目不会中止任务,计入
result.failed;配额用完时任务停止,已导入的内容保留。
即将上线
复刻 Space(POST /v2/spaces/{space_id}/forks)即将上线。在此之前,可先创建快照,带 snapshot 导出,新建一个 Space,再将归档导入其中。
