5 分钟快速开始
Markdown 版按路径写入和读取文件,编辑后查看版本,对比并回滚;让 Agent 在分支上修改后合并;获取引用到文件版本的回答;通过 MCP 连接 Agent。
准备工作
@mirabase/sdk,示例从 @mirabase/sdk/developer 导入,需要 Node.js 20.3 或更新版本,只提供 ES 模块:把各步的示例依次存入 quickstart.mjs,用 node quickstart.mjs 运行。Python SDK 的包名是 mirabase,需要 Python 3.11 或更新版本。两者均为 0.x 版本,方法名在 1.0 之前仍可能调整。目前提供的是候选版本,见 SDK。每一步的示例都接着上一步写,沿用前面定义的变量;mirabase(TypeScript)和 mb(Python)是第 1 步创建的客户端,其他页面的示例也用它们。npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz需要 Space id 的地方都可以写 default,它表示你自己的默认 Space;Key 只能看到一个 Space 时,表示那个 Space。SDK 在不指定 Space 时使用默认 Space。curl 示例需要 bash 或 zsh:$'…' 会把 \n 转换为换行符。
第 1 步:注册并创建 API Key
打开 控制台,登录并接受条款。登录方式以登录页实际提供的方式为准,同一个已验证邮箱无论用哪种方式,都归到同一账户。首次登录会自动创建你的租户和默认 Space。然后在 API Key 页面创建一个 API Key。明文只显示一次,请立即保存。将其放入环境变量,然后确认它可用:
export MIRABASE_API_KEY="mb_live_..."
curl https://api.mirabase.dev/v2/whoami \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应中的 effective_capabilities 是这个 Key 当前具备的能力。详见 认证与 API Key。
account_pending_approval;通过后所有 Key 立即可用,无需重新创建。第 2 步:按路径写入文件
PUT /v2/spaces/{space_id}/files 的请求体就是文件内容,无需预先创建上级目录。响应返回时写入已提交,立即可读:
curl -s -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary $'The launch is on March 14.\nTina owns the checklist.\n' \
| tee v1.json | jq '{version_id, entry_id: .entry.id, state: .entry.knowledge.state}'
# Save the id of this first version for steps 4 and 5.
export V1=$(jq -r .version_id v1.json)entry.id:这个文件的稳定身份,改名和移动都不变。version_id:这次写入产生的不可变版本。后面的步骤用它对比和回滚。entry.knowledge.state:searchable表示词法检索已经能找到这段文本,处理完成后变为indexed。
第 3 步:读取文件
按同一路径读取,得到写入的原始字节。ETag 就是这次读到的版本,下一步用它做条件写入。
# -i prints the headers too: ETag and Mirabase-Version-Id identify the version you read.
curl -i "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"第 4 步:编辑文件并查看版本
PATCH 按原文精确替换文本,并生成一个新版本。带上 If-Match 后,如果其他调用方或 Agent 在此期间写入过这个文件,请求会失败并返回 412,不会覆盖对方的修改。版本列表按从新到旧排列,updated_from 指向上一个版本。
# If-Match: the edit fails with 412 if the file changed after version 1.
curl -s -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "If-Match: \"$V1\"" \
-H "Content-Type: application/json" \
-d '{"edits": [{"old_text": "March 14", "new_text": "March 21"}]}' \
| jq '{version_id, previous_version_id}'
# List the file's versions, newest first.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/versions?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq '.data[] | {id, updated_from, created_at}'第 5 步:对比并回滚
对比第 1 个版本和最新版本,得到统一格式的 diff。回滚会把旧版本的内容写成一个新版本,之前的所有版本都会保留,因此回滚本身也可以再回滚。
# Compare version 1 with the latest version.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/launch.md&from=$V1" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq -r .unified_diff
# Write version 1's content back as a new version.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/revert?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version_id": "'$V1'"}' \
| jq '{latest_version_id}'--- /notes/launch.md@ver_eba2c457e8456f97
+++ /notes/launch.md@ver_5e7d2e469ac6c42a
@@ -1,2 +1,2 @@
-The launch is on March 14.
+The launch is on March 21.
Tina owns the checklist.第 6 步:让 Agent 在分支上工作
Agent 的修改先写在分支上,主线保持不变。检查点记录分支当前的状态,分支可以回滚到该检查点。合并前先查看分支相对主线的 diff,确认后再合并;on_conflict: "abort" 表示主线上同一路径已被改动时整个合并不生效。实际使用时,请给 Agent 单独签发一个权限收窄的 API Key。
# 1. Create a branch for the Agent. Main does not change until the merge.
export BRANCH_ID=$(curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "agent/checklist"}' | jq -r .id)
# 2. The Agent writes to the branch.
curl -s -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/checklist.md&branch=$BRANCH_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary $'- [ ] Freeze the API\n- [ ] Publish the SDK\n' \
| jq '{path, changed}'
# 3. Create a checkpoint that the branch can roll back to.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "draft-1"}' | jq '{id, name}'
# 4. Compare the branch with main.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq -r '.data[] | "\(.change) \(.path)\n\(.unified_diff)"'
# 5. Merge into main. Idempotency-Key is required so a retry cannot merge twice.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: merge-$BRANCH_ID" \
-H "Content-Type: application/json" \
-d '{"message": "Add the launch checklist", "on_conflict": "abort"}' \
| jq '{state, merged}'分支的有效期、回滚和大规模合并见 分支与检查点。
第 7 步:就文件提问并获取引用
POST /v2/retrieval/answer 从文件、知识和记忆中选取证据,由模型生成回答,并在正文里用 [cN] 标注引用。每条引用指向一个 Entry 的具体版本:这里的 version_id 是第 5 步回滚产生的版本。证据不足时返回 abstained,不会编造回答。
curl -s -X POST https://api.mirabase.dev/v2/retrieval/answer \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "When is the launch, and who owns the checklist?"}' \
| jq '{status, answer, reason, citations: [.citations[] | {citation_id, path, version_id}]}'{
"status": "answered",
"answer": "The launch is on March 14, and Tina owns the checklist [c1].",
"citations": [
{
"citation_id": "c1",
"entry_id": "ent_cecf61d9d54a1dbb",
"version_id": "ver_0b611ffa8bd0b060",
"space_id": "col_91f8c425c93c2f99",
"path": "/notes/launch.md",
"modified_at": "2026-11-17T05:19:34.078Z",
"title": "launch.md",
"source": "knowledge",
"text": "The launch is on March 14.\nTina owns the checklist.\n"
}
],
"evidence_count": 2,
"pack_id": "trc_b67b4d4494102309",
"partial": false
}第 8 步:通过 MCP 连接 Agent
Agent 通过 MCP 读写同一批文件,读到的版本与 API 和 SDK 返回的一致。在 Claude Code 或 Codex 里添加 Mirabase,或把 JSON 配置填入任意支持远程 MCP 的客户端:
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
--header "Authorization: Bearer $MIRABASE_API_KEY"连接后可以让 Agent 执行:“读取 Mirabase 中的 /notes/launch.md 和 /notes/checklist.md,列出发布前还剩哪些事项。”MCP 工具支持列出、读取、写入、编辑和删除文件,并涵盖检索、回答和记忆;版本和分支目前通过 API 和 SDK 使用。工具清单见 连接 Agent(MCP)。
下一步
- 了解 Entry、版本、文件、知识和记忆 的关系。
- 检索 文件,或用 上下文 为自己的模型获取证据。
- 写入一条记忆,或 导入一段对话,让服务从中提炼记忆。
- 为每个最终用户 单独建一个 Space,用你自己的用户 id 找到它。
- 让 Agent 的写入 先经过提案和审核,或 限制它可写入的目录。
- 使用 变更流和快照 保持 Space 同步。
