# Mirabase 开发者文档 > 一套接口同时提供文件库、知识库和记忆。同一个 Entry 可以按路径、按 id 或按语义到达,权限和版本链只有一份。 API 参考: https://mirabase.io/zh/developers/api.md. OpenAPI: https://api.mirabase.dev/v2/openapi.yaml --- # 5 分钟快速开始 按路径写入和读取文件,编辑后查看版本,对比并回滚;让 Agent 在分支上修改后合并;获取引用到文件版本的回答;通过 MCP 连接 Agent。 ## 准备工作 > **说明:** TypeScript SDK 的包名是 `@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](https://mirabase.io/zh/developers/sdks.md#install)。每一步的示例都接着上一步写,沿用前面定义的变量;`mirabase`(TypeScript)和 `mb`(Python)是第 1 步创建的客户端,其他页面的示例也用它们。 TypeScript: ```bash npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz ``` Python: ```bash pip install https://mirabase.io/sdk/mirabase-0.3.0rc1-py3-none-any.whl ``` curl: ```bash # curl 示例用 jq 读取字段,例如: # macOS: brew install jq # Debian 或 Ubuntu: sudo apt-get install jq # 后续的 curl 示例都用 $SPACE_ID,default 表示你的默认 Space。 export SPACE_ID=default ``` 需要 Space id 的地方都可以写 `default`,它表示你自己的默认 Space;Key 只能看到一个 Space 时,表示那个 Space。SDK 在不指定 Space 时使用默认 Space。curl 示例需要 bash 或 zsh:`$'…'` 会把 `\n` 转换为换行符。 ## 第 1 步:注册并创建 API Key 打开 [控制台](https://console.mirabase.dev),登录并接受条款。登录方式以登录页实际提供的方式为准,同一个已验证邮箱无论用哪种方式,都归到同一账户。首次登录会自动创建你的租户和默认 Space。然后在 API Key 页面创建一个 API Key。明文只显示一次,请立即保存。将其放入环境变量,然后确认它可用: curl: ```bash export MIRABASE_API_KEY="mb_live_..." curl https://api.mirabase.dev/v2/whoami \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts import { Mirabase } from "@mirabase/sdk/developer"; // Reads MIRABASE_API_KEY when apiKey is omitted. const mirabase = new Mirabase({ apiKey: process.env.MIRABASE_API_KEY }); const me = await mirabase.whoami(); ``` Python: ```python from mirabase import Mirabase # Reads MIRABASE_API_KEY when api_key is omitted. mb = Mirabase() me = mb.whoami() ``` 响应中的 `effective_capabilities` 是这个 Key 当前具备的能力。详见 [认证与 API Key](https://mirabase.io/zh/developers/authentication.md)。 > **说明:** 注册受容量限制。当天的新账户名额用完或注册暂时关闭时,无法创建新账户,控制台会说明原因,请稍后再试。新账户需要审批:审批通过前可以登录并创建 Key,但用 Key 调用 API 会返回 403 `account_pending_approval`;通过后所有 Key 立即可用,无需重新创建。 ## 第 2 步:按路径写入文件 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write) 的请求体就是文件内容,无需预先创建上级目录。响应返回时写入已提交,立即可读: curl: ```bash 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) ``` TypeScript: ```ts const path = "/notes/launch.md"; const v1 = await mirabase.files.write(path, "The launch is on March 14.\nTina owns the checklist.\n", { contentType: "text/markdown", }); console.log(v1.version_id, v1.entry.id, v1.entry.knowledge.state); ``` Python: ```python path = "/notes/launch.md" v1 = mb.files.write(path, "The launch is on March 14.\nTina owns the checklist.\n", content_type="text/markdown") print(v1["version_id"], v1["entry"]["id"], v1["entry"]["knowledge"]["state"]) ``` - `entry.id`:这个文件的稳定身份,改名和移动都不变。 - `version_id`:这次写入产生的不可变版本。后面的步骤用它对比和回滚。 - `entry.knowledge.state`:`searchable` 表示词法检索已经能找到这段文本,处理完成后变为 `indexed`。 ## 第 3 步:读取文件 按同一路径读取,得到写入的原始字节。`ETag` 就是这次读到的版本,下一步用它做条件写入。 curl: ```bash # -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" ``` TypeScript: ```ts const file = await mirabase.files.read(path); console.log(file.text()); console.log(file.etag); // the version you read ``` Python: ```python file = mb.files.read(path) print(file.text()) print(file.etag) # the version you read ``` ## 第 4 步:编辑文件并查看版本 `PATCH` 按原文精确替换文本,并生成一个新版本。带上 `If-Match` 后,如果其他调用方或 Agent 在此期间写入过这个文件,请求会失败并返回 412,不会覆盖对方的修改。版本列表按从新到旧排列,`updated_from` 指向上一个版本。 curl: ```bash # 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}' ``` TypeScript: ```ts // Fails with 412 if the file changed after you read it. const v2 = await mirabase.files.edit(path, { old_text: "March 14", new_text: "March 21" }, { ifMatch: file.etag }); console.log(v2.version_id, v2.previous_version_id); // List the file's versions, newest first. for await (const version of mirabase.files.versions(path)) { console.log(version.id, version.updated_from ?? null, version.created_at); } ``` Python: ```python # Fails with 412 if the file changed after you read it. v2 = mb.files.edit(path, {"old_text": "March 14", "new_text": "March 21"}, if_match=file.etag) print(v2["version_id"], v2.get("previous_version_id")) # List the file's versions, newest first. for version in mb.files.versions(path): print(version["id"], version.get("updated_from"), version["created_at"]) ``` ## 第 5 步:对比并回滚 对比第 1 个版本和最新版本,得到统一格式的 diff。回滚会把旧版本的内容写成一个新版本,之前的所有版本都会保留,因此回滚本身也可以再回滚。 curl: ```bash # 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}' ``` TypeScript: ```ts // Compare version 1 with the latest version. const diff = await mirabase.versions.diff({ path }, v1.version_id); console.log(diff.unified_diff); // Write version 1's content back as a new version. const reverted = await mirabase.files.revert(path, v1.version_id); console.log(reverted.latest_version_id); ``` Python: ```python # Compare version 1 with the latest version. diff = mb.versions.diff({"path": path}, v1["version_id"]) print(diff.get("unified_diff")) # Write version 1's content back as a new version. reverted = mb.files.revert(path, v1["version_id"]) print(reverted["latest_version_id"]) ``` ```diff --- /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](https://mirabase.io/zh/developers/permissions.md#agents)。 curl: ```bash # 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}' ``` TypeScript: ```ts // 1. Create a branch for the Agent. Main does not change until the merge. const branch = await mirabase.branches.create({ name: "agent/checklist" }); // 2. The Agent writes to the branch. await mirabase.files.write("/notes/checklist.md", "- [ ] Freeze the API\n- [ ] Publish the SDK\n", { branch: branch.id, contentType: "text/markdown", }); // 3. Create a checkpoint that the branch can roll back to. const checkpoint = await mirabase.branches.checkpoints.create(branch.id, "draft-1"); console.log(checkpoint.id); // 4. Compare the branch with main. for await (const change of mirabase.branches.diff(branch.id)) { console.log(change.change, change.path); console.log(change.unified_diff); } // 5. Merge into main. The SDK sends the Idempotency-Key automatically. const merged = await mirabase.branches.merge(branch.id, { message: "Add the launch checklist", on_conflict: "abort" }); console.log(merged.state, merged.merged); ``` Python: ```python # 1. Create a branch for the Agent. Main does not change until the merge. branch = mb.branches.create({"name": "agent/checklist"}) # 2. The Agent writes to the branch. mb.files.write( "/notes/checklist.md", "- [ ] Freeze the API\n- [ ] Publish the SDK\n", branch=branch["id"], content_type="text/markdown", ) # 3. Create a checkpoint that the branch can roll back to. checkpoint = mb.branches.checkpoints.create(branch["id"], "draft-1") print(checkpoint["id"]) # 4. Compare the branch with main. for change in mb.branches.diff(branch["id"]): print(change["change"], change["path"]) print(change.get("unified_diff")) # 5. Merge into main. The SDK sends the Idempotency-Key automatically. merged = mb.branches.merge(branch["id"], {"message": "Add the launch checklist", "on_conflict": "abort"}) print(merged["state"], merged["merged"]) ``` 分支的有效期、回滚和大规模合并见 [分支与检查点](https://mirabase.io/zh/developers/branches.md)。 ## 第 7 步:就文件提问并获取引用 [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) 从文件、知识和记忆中选取证据,由模型生成回答,并在正文里用 `[cN]` 标注引用。每条引用指向一个 Entry 的具体版本:这里的 `version_id` 是第 5 步回滚产生的版本。证据不足时返回 `abstained`,不会编造回答。 curl: ```bash 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}]}' ``` TypeScript: ```ts const reply = await mirabase.answer("When is the launch, and who owns the checklist?"); if (reply.status === "answered") console.log(reply.answer, reply.citations); else console.log("abstained:", reply.reason); ``` Python: ```python reply = mb.answer("When is the launch, and who owns the checklist?") if reply["status"] == "answered": print(reply["answer"], reply["citations"]) else: print("abstained:", reply.get("reason")) ``` ```json { "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 Code: ```bash claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \ --header "Authorization: Bearer $MIRABASE_API_KEY" ``` Codex: ```bash codex mcp add mirabase --url https://api.mirabase.dev/mcp \ --bearer-token-env-var MIRABASE_API_KEY ``` JSON: ```json { "mcpServers": { "mirabase": { "type": "http", "url": "https://api.mirabase.dev/mcp", "headers": { "Authorization": "Bearer mb_live_..." } } } } ``` 连接后可以让 Agent 执行:“读取 Mirabase 中的 /notes/launch.md 和 /notes/checklist.md,列出发布前还剩哪些事项。”MCP 工具支持列出、读取、写入、编辑和删除文件,并涵盖检索、回答和记忆;版本和分支目前通过 API 和 SDK 使用。工具清单见 [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md#tools)。 ## 下一步 1. 了解 [Entry、版本、文件、知识和记忆](https://mirabase.io/zh/developers/concepts.md) 的关系。 2. [检索](https://mirabase.io/zh/developers/retrieval.md#search) 文件,或用 [上下文](https://mirabase.io/zh/developers/retrieval.md#context) 为自己的模型获取证据。 3. [写入一条记忆](https://mirabase.io/zh/developers/memory.md#create),或 [导入一段对话](https://mirabase.io/zh/developers/memory.md#conversation),让服务从中提炼记忆。 4. 为每个最终用户 [单独建一个 Space](https://mirabase.io/zh/developers/concepts.md#space-per-user),用你自己的用户 id 找到它。 5. 让 Agent 的写入 [先经过提案和审核](https://mirabase.io/zh/developers/files.md#proposals),或 [限制它可写入的目录](https://mirabase.io/zh/developers/permissions.md#roots)。 6. 使用 [变更流和快照](https://mirabase.io/zh/developers/sync.md) 保持 Space 同步。 --- # 认证与 API Key 发送、创建、限定、轮换和吊销 API Key。 ## 发送 API Key 在每个请求中发送 `Authorization: Bearer mb_live_...`。令牌是 256 位随机值,不是 JWT,不包含任何可读信息。服务端只保存哈希,并在每个请求上查询验证。 ```bash curl https://api.mirabase.dev/v2/whoami \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` > **注意:** Key 只保存在服务端。不要写入前端代码、移动应用或公开仓库。怀疑泄露时立即吊销。 只有 [`GET /llms.txt`](https://mirabase.io/zh/developers/api/discovery.md#discovery-llms) 和 [`GET /v2/openapi.yaml`](https://mirabase.io/zh/developers/api/discovery.md#discovery-openapi) 不需要凭据。 ## 在控制台创建 API Key [控制台](https://console.mirabase.dev) 提供 API Key 的创建、收窄、轮换和吊销。第一个 Key 在这里创建:注册不会自动签发 Key。明文只显示一次。 控制台的登录会话用于管理账户,也用于控制台自身的功能(文件列表与删除、处理进度、检索测试台、请求日志)。读取文件内容和写入文件只接受 API Key。账户待审批期间,登录会话仅可管理 API Key、查看账户信息和只读列表,其余请求返回 403 `account_pending_approval`。 ## 通过 API 创建 API Key [`POST /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 签发 Key。只有 `tenant_admin` 能签发,Agent 不能为自己签发;新 Key 的能力、Space 范围和到期时间都不能超出签发者。`token` 只在这次响应里出现,请立即保存。 curl: ```bash curl -X POST https://api.mirabase.dev/v2/api-keys \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "ci-reader", "grant_capabilities": ["knowledge:read"], "allowed_space_ids": ["'$SPACE_ID'"], "expires_at": "2027-01-01T00:00:00Z"}' ``` TypeScript: ```ts const key = await mirabase.keys.create({ actor_id: principalId, name: "ci-reader", grant_capabilities: ["knowledge:read"], allowed_space_ids: [spaceId], expires_at: "2027-01-01T00:00:00Z", }); ``` Python: ```python key = mb.keys.create({ # The principal the key acts as: here, yourself. "actor_id": me["principal"]["id"], "name": "ci-reader", "grant_capabilities": ["knowledge:read"], "allowed_space_ids": [space_id], "expires_at": "2027-01-01T00:00:00Z", }) ``` 在有团队的账户中,Admin 能管理哪些主体和 Key,见 [签发 API Key](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 的说明;Owner 不受这些限制。 ## 按元数据限定 API Key 签发 Key 时传入 `metadata_scope`,这个 Key 只能看到带有对应元数据标签的 Entry。不同元数据键之间是“且”,同一个元数据键的多个值之间是“或”。这类 Key 能调用的操作见 [metadata_scope 参数](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create.body.metadata_scope),写入时的标签规则见 [DevMetadataScope](https://mirabase.io/zh/developers/api/schemas.md#DevMetadataScope)。 ```bash curl -X POST https://api.mirabase.dev/v2/api-keys \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "acme-agent", "grant_capabilities": ["knowledge:read", "knowledge:answer", "knowledge:write"], "metadata_scope": {"customer": ["acme", "shared"]}}' ``` - 范围由服务端在每个请求上检查,调用方无法在请求里绕过它。 - 近似文档的取代和记忆的修订只发生在范围键上取值相同的 Entry 之间,一个客户的写入不会影响另一个客户的内容。 - 账户记忆没有标签,带范围的 Key 无法读取。 - 通过 MCP 连接时,`tools/list` 只向带范围的 Key 列出它能调用的工具。带范围的 Key 也可以在 [控制台](https://console.mirabase.dev) 的 API Key 页面签发。 - 范围不隐藏 Space 本身的名称和 `external_id`。要在最终用户之间做硬隔离,请为每个用户建一个 Space,见 [一个最终用户一个 Space](https://mirabase.io/zh/developers/concepts.md#space-per-user)。 ## 查看 API Key 的权限 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 同时返回主体、Key 和有效能力。收到 403 时,先查看此接口的响应:如果 `effective_capabilities` 比 `principal.capabilities` 窄,或者 `key.allowed_space_ids` 有值,限制来自 Key,不是主体。有效能力的计算方式见 [能力](https://mirabase.io/zh/developers/permissions.md#capabilities)。 ## 轮换或替换 API Key [`POST /v2/api-keys/{key_id}/rotate`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-rotate) 在一个事务内签发新 Key 并吊销旧 Key,没有重叠期。Key 不能轮换自身:一旦响应丢失,调用方将失去可用的凭据。替换当前正在使用的 Key 的步骤如下: 1. 调用 [`POST /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 签发新 Key。 2. 将调用方切换到新 Key。 3. 调用 [`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-revoke) 吊销旧 Key。 > **说明:** 如果签发响应丢失,旧 Key 仍可使用,换一个 `Idempotency-Key` 重新签发即可。未使用的 Key 会保留在 [`GET /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-list) 中,直至管理员将其吊销。 ## 查找未使用的 API Key 每个 Key 都有 `last_used_at`,即它最近一次调用接口的时间(见 [DevApiKey](https://mirabase.io/zh/developers/api/schemas.md#DevApiKey.last_used_at))。清理闲置的 Key、确认发出的 Key 是否已开始使用,都可以依据这个字段;[控制台](https://console.mirabase.dev) 的 Key 列表也显示它。 ## 吊销 API Key [`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-revoke) 返回后,这个 Key 的下一个请求返回 401,且已发起的在途写入也无法提交。吊销不级联:处置泄露时,按每个 Key 的 `issued_by_key_id` 查出它签发过的 Key,逐个吊销。 ## 删除账户 要删除账户及其全部数据,请[联系我们](https://mirabase.app/contact),并提供账户的邮箱和 `tenant_id`(由 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 返回)。 - 数据删除后无法恢复。请先用 [导出](https://mirabase.io/zh/developers/sync.md#export) 保存需要保留的文件;导出只含文件,不含记忆和版本历史。 - 如果只需删除部分内容,无需联系我们:用 [彻底删除](https://mirabase.io/zh/developers/files.md#delete) 删除文件,用 [遗忘](https://mirabase.io/zh/developers/memory.md#govern) 删除记忆。 ## 下一步 - [SDK](https://mirabase.io/zh/developers/sdks.md):安装客户端,无需手动构造请求。 - [权限](https://mirabase.io/zh/developers/permissions.md):能力的计算方式,以及如何将 Key 限制在特定 Space 和目录。 - [连接 Agent](https://mirabase.io/zh/developers/agents.md):为 Agent 配置独立的主体和 Key。 --- # SDK 安装和配置 TypeScript 与 Python 客户端,并了解它们替你处理的 Space 选择、流式回答、错误、重试和分页。 ## 安装 SDK | 语言 | 包 | 版本 | 运行要求 | | --- | --- | --- | --- | | TypeScript | `@mirabase/sdk` | 0.3.0-rc.1 | Node.js 20.3 及以上,仅提供 ES 模块,无依赖 | | Python | `mirabase` | 0.3.0rc1 | Python 3.11 及以上,无依赖 | TypeScript: ```bash npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz ``` Python: ```bash pip install https://mirabase.io/sdk/mirabase-0.3.0rc1-py3-none-any.whl ``` > **说明:** 0.3.0-rc.1(Python 为 0.3.0rc1)是 0.3.0 的候选版本。正式版发布前,方法和返回字段仍可能调整。 > **说明:** 安装包由本站点直接提供,地址中包含版本号。升级时请使用新版本的地址;旧版本地址长期有效,且内容保持不变。每个文件的 SHA-256 列于 `https://mirabase.io/sdk/SHA256SUMS`。 > **注意:** 在 0.2.0 中,固定到某个 Space 的客户端(通过 `space` 选项或 `space(id)`)在调用 `search`、`context` 和 `answer` 时未限定到该 Space,而是会读取该 Key 可读的所有 Space。请升级到 0.3.0-rc.1(Python 为 0.3.0rc1)。 ## 创建客户端 TypeScript: ```ts import { Mirabase } from "@mirabase/sdk/developer"; // Reads MIRABASE_API_KEY when apiKey is omitted. const mirabase = new Mirabase(); await mirabase.files.write("/notes/plan.md", "We ship on Friday.\n"); const hits = await mirabase.search("when do we ship?"); ``` Python: ```python from mirabase import Mirabase # Reads MIRABASE_API_KEY when api_key is omitted. mb = Mirabase() mb.files.write("/notes/plan.md", "We ship on Friday.\n") hits = mb.search("when do we ship?") ``` | TypeScript | Python | 默认值 | 含义 | | --- | --- | --- | --- | | `apiKey` | `api_key` | 环境变量 `MIRABASE_API_KEY` | API Key | | `baseUrl` | `base_url` | `https://api.mirabase.dev` | 服务地址 | | `space` | `space` | 不固定 | 把客户端固定到一个 Space,见下文 | | `timeoutMs` | `timeout` | 60 秒 | 每次尝试的超时 | | `maxRetries` | `max_retries` | 3 | 最多重试几次 | | `maxRetryAfterMs` | `max_retry_after` | 60 秒 | 服务要求等待的时间超过该值时不等待,直接返回错误 | Python 另有 `AsyncMirabase`,方法相同,用于 `asyncio`,支持 `async with` 和 `aclose()`。每个请求都带 `User-Agent: mirabase-node/<版本>`(Python 是 `mirabase-python/<版本>`);版本号也可以从 `SDK_VERSION`(TypeScript)和 `mirabase.__version__`(Python)读到。 ## 选择调用的 Space | 客户端 | 文件、导入、对话等 | `search`、`context`、`answer` | | --- | --- | --- | | 不固定 | 默认 Space | 这个 Key 能读的全部 Space | | 用 `space` 选项或 `space(id)` 固定 | 固定的 Space | 只读固定的 Space | - 每次调用都可以用 `space` 指定一个 Space。`search`、`context` 和 `answer` 还接受 `spaces`:一组 Space id,或 `"all"`(这个 Key 能读的全部 Space)。`spaces` 优先于 `space`,两者都优先于客户端固定的 Space。 - 需要 Space id 的地方都可以写 `default` 或 `ext:`。 - 默认 Space 只查一次并缓存,用的是一次 [`GET /v2/spaces/default`](https://mirabase.io/zh/developers/api/spaces.md#spaces-read)。 每个最终用户一个 Space 时,用 `spaceFor`(Python 是 `space_for`)按你自己的用户 id 取得一个固定在这个用户 Space 上的客户端;Space 不存在时会创建。只需获取 Space 本身时使用 `spaces.ensure`。两者都只发一次 [`PUT /v2/spaces/ext:`](https://mirabase.io/zh/developers/api/spaces.md#spaces-ensure),重复调用是安全的。见 [一个最终用户一个 Space](https://mirabase.io/zh/developers/concepts.md#space-per-user)。 TypeScript: ```ts const user = await mirabase.spaceFor("user-42", { name: "User 42" }); await user.conversations.add(messages, { sessionId: "chat-1" }); const reply = await user.answer("What does this user prefer?"); // reads this Space only const space = await mirabase.spaces.ensure("user-42"); // the Space itself ``` Python: ```python user = mb.space_for("user-42", name="User 42") user.conversations.add(messages, session_id="chat-1") reply = user.answer("What does this user prefer?") # reads this Space only space = mb.spaces.ensure("user-42") # the Space itself ``` ## 流式获取回答 `answer.stream` 接受与 `answer` 相同的参数,边生成边返回 `start`、`delta`、`replace` 和 `final` 事件,事件的含义见 [流式获取回答](https://mirabase.io/zh/developers/retrieval.md#answer-stream)。`stream.text` 是到目前为止的文本,`final` 的 `answer` 与 `answer()` 的返回值相同。 TypeScript: ```ts const stream = mirabase.answer.stream("When do releases go out?"); for await (const event of stream) { if (event.type === "start") console.log("evidence items:", event.evidence_count); if (event.type === "delta") process.stdout.write(event.text); if (event.type === "replace") console.log("\n(the text so far is replaced by the final answer)"); } // final is authoritative: the same object mirabase.answer returns. const reply = await stream.finalAnswer(); console.log(reply.status, reply.answer, reply.citations); ``` Python: ```python with mb.answer.stream("When do releases go out?") as stream: for event in stream: if event["type"] == "start": print("evidence items:", event["evidence_count"]) elif event["type"] == "delta": print(event["text"], end="", flush=True) elif event["type"] == "replace": print("\n(the text so far is replaced by the final answer)") # final is authoritative: the same object mb.answer returns. reply = stream.final_answer() print(reply["status"], reply["answer"], reply["citations"]) ``` - `error` 事件、中途断流和无法解析的数据都作为 `MirabaseError` 抛出,不会抛出原始的解析错误。已经开始的流不会自动重试。 - 提前跳出循环、调用 `close()` 或取消 `signal` 都会关闭连接,服务随之取消回答。Python 用 `with` 和 `for`,`AsyncMirabase` 用 `async with` 和 `async for`。 - `answer` 本身不流式返回:传 `stream: true`(Python 是 `stream=True`)会抛出 `MirabaseConfigError`,代码为 `stream_not_supported`,不发出请求。 ## 处理错误 请求失败时抛出 `MirabaseError` 或它的子类。子类由 HTTP 状态码决定,可以用 `instanceof`(Python 用 `except`)只处理一类错误。具体情况按 `code` 和 `action` 分支,二者保持稳定;`message` 供人阅读。 | 类 | HTTP 状态码 | | --- | --- | | `MirabaseValidationError` | 400、422 | | `MirabaseAuthenticationError` | 401 | | `MirabasePermissionError` | 403 | | `MirabaseNotFoundError` | 404、410 | | `MirabaseConflictError` | 409、412 | | `MirabaseRateLimitError` | 429 | | `MirabaseServerError` | 500 及以上 | | `MirabaseConnectionError` | 没有收到响应:网络故障或超时。错误信息写明地址、请求和原因 | | `MirabaseConfigError` | 调用本身有误,在发出请求前检出。创建客户端时即校验 API Key:首尾的空白字符会被去除,Key 中含有换行、空格、控制字符或非 ASCII 字符时,代码为 `invalid_api_key`,错误信息不包含 Key | 这些类都继承 `MirabaseError`;其他状态码抛出的是 `MirabaseError` 本身。 | TypeScript | Python | 含义 | | --- | --- | --- | | `status` | `status` | HTTP 状态码 | | `code` | `code` | 错误码,见 [错误码](https://mirabase.io/zh/developers/errors.md#codes) | | `type` | `type` | 错误的大类,如 `not_found`、`rate_limit` | | `action` | `action` | 下一步操作,仅在服务返回时提供 | | `retryable` | `retryable` | 重试是否有意义 | | `requestId` | `request_id` | 请求 id,联系支持时请提供 | | `field` | `field` | 422 时第一个出错的字段 | | `errors` | `errors` | 422 时请求体里的全部问题,每项是 `{field, code, message}` | | `limit` | `limit` | 429 时触发的限制:`request_rate` 或 `concurrency` | | `retryAfterSeconds` | `retry_after_seconds` | 服务要求等待的秒数 | | `currentVersionId` | `current_version_id` | 412 时文件的当前版本 | | `body` | `body` | 响应体 | TypeScript: ```ts import { MirabaseConflictError, MirabaseRateLimitError } from "@mirabase/sdk/developer"; const { etag } = await mirabase.files.stat("/notes/plan.md"); try { await mirabase.files.write("/notes/plan.md", "v2\n", { ifMatch: etag }); } catch (error) { if (error instanceof MirabaseConflictError && error.code === "precondition_failed") { // Someone else wrote first: read again, then retry on error.currentVersionId. } else if (error instanceof MirabaseRateLimitError) { console.log(error.limit, error.retryAfterSeconds); } else { throw error; } } ``` Python: ```python from mirabase import MirabaseConflictError, MirabaseRateLimitError etag = mb.files.stat("/notes/plan.md").etag try: mb.files.write("/notes/plan.md", "v2\n", if_match=etag) except MirabaseConflictError as error: if error.code != "precondition_failed": raise ... # Someone else wrote first: read again, then retry on error.current_version_id. except MirabaseRateLimitError as error: print(error.limit, error.retry_after_seconds) ``` ## 重试和幂等 - 429 会自动重试,按 `Retry-After` 等待。`Retry-After` 超过 `maxRetryAfterMs`(Python 为 `max_retry_after`)时不等待,直接抛出 `MirabaseRateLimitError`。 - 网络错误和 5xx 只在重发安全时重试:读请求,以及带幂等键的写请求。 - 对接受 `Idempotency-Key` 的调用,SDK 会自动生成幂等键并在重试时复用,避免重复写入。规则见 [API 约定](https://mirabase.io/zh/developers/conventions.md#idempotency)。 - `retryable` 为 `false` 的错误不重试。 ## 遍历列表 列表方法返回可直接遍历的对象,并按需自动翻页。`limit` 是每页条数,不是总数;只需前几条时使用 `take`。 TypeScript: ```ts for await (const entry of mirabase.entries.list()) { console.log(entry.id); } const firstTen = await mirabase.entries.list().take(10); ``` Python: ```python for entry in mb.entries.list(): print(entry["id"]) first_ten = mb.entries.list().take(10) ``` `search` 返回命中的数组,数组上另有 `traceId` 和 `partial`(Python 是 `trace_id` 和 `partial`)。`partial` 为 `true` 时结果可能不完整。 ## 上传大文件 `files.write` 自动选择上传方式:16 MiB 以内使用单次 `PUT`,超过 16 MiB 使用分片上传。调用方式不变。 ## 直接调用接口 [API 参考](https://mirabase.io/zh/developers/api.md) 中的每个接口在 `raw` 上都有对应的方法(TypeScript 为 `mirabase.raw`,Python 为 `mb.raw`)。资源方法不适用时可调用它,认证、重试和错误处理方式相同。 ## 下一步 - [核心概念](https://mirabase.io/zh/developers/concepts.md):了解 Space、Entry、版本和记忆。 - [文件与版本](https://mirabase.io/zh/developers/files.md):写入、读取和修改文件。 - [记忆](https://mirabase.io/zh/developers/memory.md#conversation):用 `conversations.add` 写入对话,并等待服务提炼记忆。 - [API 约定](https://mirabase.io/zh/developers/conventions.md):了解 SDK 自动处理的分页、幂等和重试规则。 --- # 核心概念 API 背后的数据模型:Space、Entry 与版本、文件、知识、记忆、分支和访问控制。 Mirabase 的来源层只有一种数据:**Entry 加不可变版本**。文件是 Entry 的定位方式,知识是它的处理结果,记忆的一部分来源于它。 ```text Entry ├─ id, space_id, title, metadata ├─ latest_version_id newest committed version ├─ current_version_id version serving search ├─ file { path, size, media_type, etag } or null ├─ knowledge { state, indexed_version_id } ├─ memory { scope, kind, pinned, exclude } or null ├─ memory_exclude kept out of memory distillation └─ access { role, capabilities } ``` ## Space Space 是权限和路径的边界。每个账户有一个默认 Space,也可以用 [`POST /v2/spaces`](https://mirabase.io/zh/developers/api/spaces.md#spaces-create) 创建更多 Space。成员、角色和文件树都按 Space 划分。 一个账户可以有多个 Space(上限为 `tenant_spaces`,见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)),因此可以为每个最终用户或每个项目分别创建一个。删除 Space 会删除其中的全部内容,不能撤销,默认 Space 不能删除,见 [`DELETE /v2/spaces/{space_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-delete)。 ### 一个最终用户一个 Space 最终用户之间要硬隔离时,给每个用户一个 Space:文件、知识和记忆都按 Space 分开,元数据做不到这一点。把你自己的用户 id 设为 Space 的 `external_id`,之后在需要 Space id 的地方写 `ext:`,例如 `ext:user-42`。路径、`?space_id=` 和请求体中的 `space_ids` 均支持这种写法,无需维护映射表。 [`PUT /v2/spaces/ext:`](https://mirabase.io/zh/developers/api/spaces.md#spaces-ensure) 有则返回、无则创建。同时到达的两个请求只创建一个 Space,重复调用也是安全的,所以给新用户写入之前调用一次即可。SDK 里对应 `spaces.ensure`,`spaceFor`(Python 是 `space_for`)还会返回一个固定在这个 Space 上的客户端。 curl: ```bash # Returns the Space whose external_id is user-42 (200), or creates it (201). curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "User 42"}' # ext:user-42 works wherever a Space id does. curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42/files?path=/notes/plan.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: text/markdown" \ --data-binary "We ship on Friday." ``` TypeScript: ```ts // A client pinned to the user's Space. The Space is created on the first call. const user = await mirabase.spaceFor("user-42", { name: "User 42" }); await user.files.write("/notes/plan.md", "We ship on Friday.\n"); const hits = await user.search("when do we ship?"); // reads this Space only ``` Python: ```python # A client pinned to the user's Space. The Space is created on the first call. user = mb.space_for("user-42", name="User 42") user.files.write("/notes/plan.md", "We ship on Friday.\n") hits = user.search("when do we ship?") # reads this Space only ``` - `search`、`context` 和 `answer` 不传 `space_ids` 时读取这个 Key 能读取的全部 Space,不只是默认 Space。请求只涉及一个用户时,请指定这个用户的 Space。SDK 中固定在一个 Space 上的客户端只读那个 Space。 - [`GET /v2/spaces?external_id=`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 按 `external_id` 查找,最多返回一个 Space,不会创建(SDK 的 `spaces.findByExternalId`、`spaces.find_by_external_id`)。 - 删除 Space 之后,它的 `external_id` 可以再次使用。 ## Entry 与版本 Entry 是一份来源的稳定身份:文件、网址或一段文本。每次内容变化产生一个版本,版本不可变,版本链一直保留。 - `latest_version_id` 是最新提交的版本,读取操作默认使用该版本,因此刚写入的内容立即可读。 - `current_version_id` 是 `search` 和 `context` 读取的版本。最新版本完成索引后它等于 `latest_version_id`;更新的版本还在处理时,它仍是之前的版本。第一版处理完之前不存在。 - 修改标题也会产生新版本,因为标题会编入索引。版本上唯一可修改的字段是 `message`。 同一个 Entry 可以按路径、按 id 或按语义(检索)到达。身份、权限和版本链是同一套。 ## 文件 有路径的 Entry 即文件。路径即身份:两个路径存放相同的字节即为两个文件。改名和移动不改变 Entry id。没有路径的 Entry 也合法,比如用 `ingest` 导入的网址和文本,它们的 `file` 是 `null`。 **有路径用 `files`,按 id 用 `entries`**,两者的读取参数相同。详见 [文件与版本](https://mirabase.io/zh/developers/files.md)。 ## 知识 知识不是单独的资源,而是 Entry 的处理状态。写入提交后,后台解析、切块、建索引,状态在 `knowledge.state` 上: | 状态 | 含义 | 能做什么 | | --- | --- | --- | | `readable` | 已提交 | 按路径或 id 读取原件 | | `searchable` | 请求体中 64 KiB 以内的文本已进入新鲜缓冲 | 词法检索 | | `indexed` | 处理完成 | 全文检索、向量检索和重排检索 | | `failed` | 处理失败,字节仍可读 | 读取原件,或调用 `reprocess` | 写入在处理完成之前就已提交。需要等待处理完成时,在写入请求中带上 `Prefer: wait=N`,见 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write)。 ## 记忆 记忆是一条有范围、状态和来源的陈述:账户记忆、以 Entry 写入的记忆,或从 Entry 提炼出的事实。提炼出的事实不是 Entry,它的 id 也不是 Entry id;范围、状态和有效期见 [记忆模型](https://mirabase.io/zh/developers/memory.md#model)。 ## 分支 分支是叠在 Space 主线上的写时复制层,用作 Agent 的工作区。分支里的内容不产生版本、不处理,合并进主线时每个路径才成为一个新版本。详见 [分支与挂载](https://mirabase.io/zh/developers/branches.md)。 ## 访问控制 每个请求以一个主体(人或 Agent)的身份执行,由 API Key 携带。请求能做什么,取决于主体和 Key 共同持有的能力、主体在 Space 里的角色,以及 Space 所有者为成员设的读写根路径,见 [权限](https://mirabase.io/zh/developers/permissions.md)。 ## 下一步 - [文件与版本](https://mirabase.io/zh/developers/files.md):从写入一个文件开始。 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):搜索、构建上下文和带引用的回答。 - [记忆](https://mirabase.io/zh/developers/memory.md):从对话里提炼事实,并审核、更正和遗忘。 --- # 术语表 文档中反复出现的术语,每个用一句话定义,并链接到讲解它的页面。 | 术语 | 定义 | 详见 | | --- | --- | --- | | Space | 权限和路径的边界,成员、角色和文件树都按 Space 划分,每个账户有一个默认 Space。 | [核心概念](https://mirabase.io/zh/developers/concepts.md#space) | | Entry | 一份来源的稳定身份,可以是文件、网址或一段文本。 | [核心概念](https://mirabase.io/zh/developers/concepts.md#entry-version) | | 版本 | Entry 内容的一次不可变记录,内容每变化一次产生一个新版本。 | [核心概念](https://mirabase.io/zh/developers/concepts.md#entry-version) | | 知识状态 | Entry 的处理进度,报告在 `knowledge.state` 上。 | [核心概念](https://mirabase.io/zh/developers/concepts.md#knowledge) | | 记忆 | 一条有范围、状态和来源的陈述,可以是账户记忆、以 Entry 写入的记忆,或从 Entry 提炼的事实。 | [记忆](https://mirabase.io/zh/developers/memory.md#model) | | 记忆范围 | 记忆归属的对象:`project` 属于一个 Space,`agent` 属于一个 Agent,`account` 属于账户。 | [记忆](https://mirabase.io/zh/developers/memory.md#model) | | 记忆状态 | 记忆在审核中的位置:`candidate`、`confirmed`、`rejected` 或 `superseded`。 | [记忆](https://mirabase.io/zh/developers/memory.md#model) | | 主体 | 请求以其身份执行的人(`kind: human`)或 Agent(`kind: agent`),API Key 属于主体但本身不是主体。 | [权限](https://mirabase.io/zh/developers/permissions.md#principals) | | 能力 | 对一类操作的许可,例如 `knowledge:read` 或 `knowledge:write`。 | [权限](https://mirabase.io/zh/developers/permissions.md#capabilities) | | API Key | 每个请求以 `Authorization: Bearer mb_live_...` 发送的凭据,只能收窄其主体的权限。 | [认证与 API Key](https://mirabase.io/zh/developers/authentication.md#bearer) | | Agent | `kind: agent` 的主体,有自己的权限、记忆和审计身份。 | [权限](https://mirabase.io/zh/developers/permissions.md#principals) | | 上下文包 | `context` 为一个任务返回的结果:服务挑选来源,在 token 预算内打包,并在 `route` 中说明取舍。 | [检索与上下文](https://mirabase.io/zh/developers/retrieval.md#context) | | 引用 | 上下文包中一条来源的 `[cN]` 编号,回答用它标注出处。 | [检索与上下文](https://mirabase.io/zh/developers/retrieval.md#answer) | | 分支 | 叠在 Space 主线上的写时复制层,用作 Agent 的工作区,合并后才在主线产生版本。 | [分支与挂载](https://mirabase.io/zh/developers/branches.md#branches) | | 检查点 | 分支自身改动在某一时刻的记录,分支可以回滚到这个检查点。 | [分支与挂载](https://mirabase.io/zh/developers/branches.md#checkpoints) | | 快照 | 某一时刻 Space 里每个文件的路径和版本的记录,不复制任何字节。 | [同步、快照与导出](https://mirabase.io/zh/developers/sync.md#snapshots) | | 提案 | Agent 对他人文件提交的待审核写入,审核人批准后才写成新版本。 | [文件与版本](https://mirabase.io/zh/developers/files.md#proposals) | | 任务 | 单次请求内无法完成的工作,返回 202 和 `job_id`,可轮询任务直至进入终态。 | [API 约定](https://mirabase.io/zh/developers/conventions.md#jobs) | | 读取根路径 | Space 所有者为成员设定的 `read_root`,成员只能读取这个目录及其下的内容,其外的路径返回 404。 | [权限](https://mirabase.io/zh/developers/permissions.md#roots) | | 写入根路径 | Space 所有者为成员设定的 `write_root`,成员只能在这个目录下写入。 | [权限](https://mirabase.io/zh/developers/permissions.md#roots) | | 幂等键 | 写请求上的 `Idempotency-Key` 请求头,带相同的键重发不会再执行一遍。 | [API 约定](https://mirabase.io/zh/developers/conventions.md#idempotency) | | 游标 | 列表或变更流返回的不透明字符串,用于读取下一页或继续读取。 | [API 约定](https://mirabase.io/zh/developers/conventions.md#pagination) | | ETag | 文件最新版本的 id,用于条件写入和条件读取。 | [API 约定](https://mirabase.io/zh/developers/conventions.md#conditional) | | 离线整理 | 部署可选的功能,在没有 Agent 工作时整理已有的记忆、不生成新内容,API 把一次运行称为 dream。 | [记忆](https://mirabase.io/zh/developers/memory.md#dreams) | ## 下一步 - [文件与版本](https://mirabase.io/zh/developers/files.md):从写入一个文件开始。 - [权限](https://mirabase.io/zh/developers/permissions.md):主体、能力、角色和根路径如何共同决定一次请求。 - [API 参考](https://mirabase.io/zh/developers/api.md):每个接口的参数和响应。 --- # 文件与版本 写入、读取、编辑和整理文件,比较和回滚版本,处理 Agent 的提案。 ## 写入文件 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write) 创建或替换一个文件,请求体即文件内容。返回时写入已提交,可以立即读取。大小上限、状态码和请求头见参考页。 curl: ```bash curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: text/markdown" \ --data-binary "Mirabase keeps files, knowledge and memory in one place." ``` TypeScript: ```ts const written = await mirabase.files.write( "/notes/hello.md", "Mirabase keeps files, knowledge and memory in one place.", { contentType: "text/markdown" }, ); ``` Python: ```python written = mb.files.write( "/notes/hello.md", "Mirabase keeps files, knowledge and memory in one place.", content_type="text/markdown", ) ``` - 查看响应的 `version_created`:字节和媒体类型都没有变化时为 `false`,不产生版本,也不计配额。 - 未携带 `Content-Type` 时,文件存为 `application/octet-stream`。 - 要等到这个版本可以检索再返回,带上 [Prefer: wait=N](https://mirabase.io/zh/developers/api/files.md#files-write.Prefer)。该 API Key 已有 4 个等待中的请求时不再等待,响应也不带 `Preference-Applied`。 - 带 `branch` 参数时写到分支而不是主线,见 [分支与挂载](https://mirabase.io/zh/developers/branches.md#reads)。 ## 记录发生时间、元数据和记忆开关 一次写入还可以记下三项:内容发生的时间 [occurred_at](https://mirabase.io/zh/developers/api/files.md#files-write.occurred_at)、你自己的元数据 [metadata](https://mirabase.io/zh/developers/api/files.md#files-write.metadata),以及是否从中提炼记忆 [memory_exclude](https://mirabase.io/zh/developers/api/files.md#files-write.memory_exclude)。它们记在文件的 Entry 上,不随版本变化。`PUT` 的请求体是文件字节,所以这三项作为查询参数发送,`metadata` 是 URL 编码的 JSON。 ```bash # The body is the file, so the three values ride in the query. --url-query (curl 7.87 or newer) # URL-encodes each one; metadata is a JSON object. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files" \ --url-query "path=/recordings/2026-11-06-standup.m4a" \ --url-query "occurred_at=2026-11-06T09:30:00+08:00" \ --url-query 'metadata={"device":"recorder-01","room":"3f"}' \ --url-query "memory_exclude=true" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: audio/mp4" \ --data-binary @standup.m4a ``` - 只更新传入的项:覆盖写入已有文件时,未传入的项保持不变。内容未变时同样生效:再次写入相同的字节、只传入新的 `occurred_at`,返回 `version_created: false`,发生时间随之更新。 - [批量写入](https://mirabase.io/zh/developers/files.md#batch) 的每一条和 [大文件](https://mirabase.io/zh/developers/files.md#uploads) 的完成请求里,它们是同名的请求体字段。 - 事后修改用 [`PATCH /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update)。 ## 避免覆盖已有修改 不带条件时后写覆盖,版本链仍然完整。要避免覆盖,把读到的 `ETag` 放进 `If-Match`;只想新建时发送 `If-None-Match: *`。条件请求的完整规则见 [API 约定](https://mirabase.io/zh/developers/conventions.md#conditional)。 curl: ```bash # Fails with 412 if someone wrote a newer version since you read this one. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H 'If-Match: "ver_2b10"' \ -H "Content-Type: text/markdown" \ --data-binary @hello.md # Fails with 412 if the file already exists. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/new.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "If-None-Match: *" \ -H "Content-Type: text/markdown" \ --data-binary @new.md ``` TypeScript: ```ts // Fails with 412 if someone wrote a newer version since you read this one. await mirabase.files.write("/notes/hello.md", nextText, { contentType: "text/markdown", ifMatch: written.entry.file!.etag, }); // Fails with 412 if the file already exists. await mirabase.files.write("/notes/new.md", newText, { contentType: "text/markdown", createOnly: true }); ``` Python: ```python # Fails with 412 if someone wrote a newer version since you read this one. mb.files.write( "/notes/hello.md", "Mirabase keeps files, knowledge and memory in one place, with every version kept.", content_type="text/markdown", if_match=written["entry"]["file"]["etag"], ) # Fails with 412 if the file already exists. mb.files.write("/notes/new.md", "A new note.", content_type="text/markdown", create_only=True) ``` 收到 412 `precondition_failed` 时,错误中的 `current_version_id` 是当前版本:重新读取、合并你的修改,再用新的 `ETag` 写入。 ## 编辑文本 [`PATCH /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-patch) 按字符串替换,不必发送整个文件。只支持 UTF-8 文本;每条 `old_text` 必须恰好出现一次,除非设置 `replace_all`。 ```bash curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"edits": [{"old_text": "one place", "new_text": "a single place"}]}' ``` 编辑失败时不产生版本。`edit_no_match` 时重新读取再编辑;`edit_ambiguous` 时补充上下文或设置 `replace_all`;文件太大或不是文本时改用 `PUT` 替换。错误码和大小上限见参考页。 ## 读取文件 [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-read) 按路径读取,[`GET /v2/entries/{entry_id}/content`](https://mirabase.io/zh/developers/api/entries.md#entries-content) 按 id 读取,两者参数相同,默认读取最新版本。[view](https://mirabase.io/zh/developers/api/schemas.md#DevFileView) 决定返回哪种形式,默认是原始字节。文本文件的 `text` 视图写入后即可读取,其他视图需等待处理完成。 读取旧版本带 `version`,按快照读取带 `snapshot`(见 [快照](https://mirabase.io/zh/developers/sync.md#snapshots)),读取部分字节用 `Range`。各参数的规则见参考页。 ### 下载地址 要把大文件交给浏览器或其他服务,用 [`GET /v2/spaces/{space_id}/files/content-url`](https://mirabase.io/zh/developers/api/files.md#files-contenturl) 或 [`GET /v2/entries/{entry_id}/content-url`](https://mirabase.io/zh/developers/api/entries.md#entries-contenturl) 为原始字节签发短期地址,获取时不需要 API Key。 curl: ```bash # A signed URL for the original bytes, valid 60 to 300 seconds. Fetch it without the key. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/videos/talk.mp4&expires_in=120" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts const link = await mirabase.files.contentUrl("/videos/talk.mp4", { expiresIn: 120 }); // link.url works until link.expires_at for anyone who holds it: treat it like the key. const bytes = await fetch(link.url); ``` Python: ```python from urllib.request import urlopen link = mb.files.content_url("/videos/talk.mp4", expires_in=120) # link["url"] works until link["expires_at"] for anyone who holds it: treat it like the key. data = urlopen(link["url"]).read() ``` > **注意:** 地址到期前,任何获得此地址的人都能下载,吊销 Key 也无法阻止,因此请像保管 Key 一样保管此地址。 ## 管理目录 [`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/zh/developers/api/tree.md#tree-list) 列出目录。[`POST /v2/spaces/{space_id}/tree/operations`](https://mirabase.io/zh/developers/api/tree.md#tree-operations) 按顺序执行 `mkdir`、`move`、`copy`、`delete` 和 `restore`,全部生效或全部不生效。 curl: ```bash curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"operations": [ {"op": "mkdir", "path": "/archive/2026"}, {"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"}, {"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"}, {"op": "delete", "path": "/drafts", "recursive": true} ]}' ``` TypeScript: ```ts // All or none, in order. copy returns the new Entries in copies. const done = await mirabase.tree.apply([ { op: "mkdir", path: "/archive/2026" }, { op: "move", from: "/notes/old.md", to: "/archive/2026/old.md" }, { op: "copy", from: "/templates/report.md", to: "/reports/2026-11.md" }, { op: "delete", path: "/drafts", recursive: true }, ]); // The shortcuts send one operation each. await mirabase.tree.move("/notes/draft.md", "/notes/final.md"); ``` Python: ```python # All or none, in order. copy returns the new Entries in copies. done = mb.tree.apply([ {"op": "mkdir", "path": "/archive/2026"}, {"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"}, {"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"}, {"op": "delete", "path": "/drafts", "recursive": True}, ]) # The shortcuts send one operation each. mb.tree.move("/notes/draft.md", "/notes/final.md") ``` - `move` 和 `copy` 的 `to` 是完整的新路径。目标被占用时返回 409 `path_conflict`,不覆盖也不合并。 - 保留响应里的 `delete_batch_id`:它能恢复这次请求删除的全部内容。 - 每个复制出的文件是新的 Entry,列在响应的 `copies` 里;历史不复制,之后像新文件一样处理。 - 超过同步上限的子树返回 409 `subtree_too_large`,请改用 [以任务方式运行大型目录操作](https://mirabase.io/zh/developers/files.md#jobs)。 ### 路径规则 路径是绝对路径,以 `/` 开头,结尾不带 `/`;名字按 NFKC 和大小写折叠比较,所以 `/Docs` 和 `/docs` 是同一个目录。长度和字符的完整规则见 [DevPath](https://mirabase.io/zh/developers/api/schemas.md#DevPath)。 `/.mirabase/` 是保留路径,写入返回 403 `reserved_path`。例外是 `/.mirabase/skills//...`,那里存放你的技能文件,`context` 会读取其中的 `SKILL.md`。`/.mirabase/memory/MEMORY.md` 是生成的只读视图,见 [记忆](https://mirabase.io/zh/developers/memory.md#memory-md);开启了离线整理的部署上,`/.mirabase/memory/RECENT.md` 也是,见 [索引写法](https://mirabase.io/zh/developers/memory.md#memory-index)。 ## 以任务方式运行大型目录操作 超过同步上限的单条 `move`、`copy`、递归 `delete` 或按 `delete_batch_id` 的 `restore`,带 `Prefer: respond-async` 时改为任务执行,返回 202、`job_id` 和 `Location: /v2/jobs/{job_id}`。按 [API 约定](https://mirabase.io/zh/developers/conventions.md#jobs) 跟踪任务。 curl: ```bash # One operation over the synchronous limit runs as a job: 202 with job_id. curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Prefer: respond-async" \ -H "Content-Type: application/json" \ -d '{"operations": [{"op": "delete", "path": "/old-exports", "recursive": true}]}' # Poll until status is succeeded or failed. curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts // Under the limit it runs right away; over it, the result is a JobReceipt. const started = await mirabase.tree.start({ op: "delete", path: "/old-exports", recursive: true }); if ("job_id" in started) { let job = await mirabase.jobs.get(started.job_id); while (job.status === "queued" || job.status === "running") { await new Promise((resolve) => setTimeout(resolve, 2000)); job = await mirabase.jobs.get(started.job_id); } // A failed delete keeps what it did: restore it with job.result?.delete_batch_id. } ``` Python: ```python # Under the limit it runs right away; over it, the result is a JobReceipt. started = mb.tree.start({"op": "delete", "path": "/old-exports", "recursive": True}) if "job_id" in started: # Polls until status is succeeded, failed, or cancelled. job = mb.jobs.wait(started["job_id"]) # A failed delete keeps what it did: restore it with job["result"]["delete_batch_id"]. ``` > **注意:** 任务中的 `move` 是一个事务,`delete`、`restore` 和 `copy` 则分批执行,不是原子操作:删除任务失败时会留下删除了一部分的目录,用 `result.delete_batch_id` 恢复。 ## 批量写入 [`POST /v2/spaces/{space_id}/files/batch`](https://mirabase.io/zh/developers/api/files.md#files-batch) 在一个请求里写入和删除多个小文本文件。每个条目单独提交,单条失败不影响其余条目;每条结果有自己的 `status`,按位置对应请求条目。 ```bash curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/batch" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: import-2026-11-06" \ -H "Content-Type: application/json" \ -d '{"items": [ {"op": "put", "path": "/notes/a.md", "content": "First note", "media_type": "text/markdown"}, {"op": "delete", "path": "/notes/old.md"} ]}' ``` 带相同的 `Idempotency-Key` 重新发送,可以完成中途中断的批次:已提交的条目重放,其余条目继续执行。单条 `DELETE` 第二次调用返回 404;重试时需要区分“已删除”和“原本不存在”,请用这个接口。 ## 上传大文件 超过 16 MiB 的文件使用分片上传:发起上传、获取分片地址、逐片 `PUT`,最后完成上传。完成时才解析路径,之后的行为与 `PUT` 相同,包括 `If-Match` 和 `If-None-Match: *`。 ```bash # 1. Start the upload. checksum_sha256 is the Base64 SHA-256 of the whole file. curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/uploads" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path": "/videos/talk.mp4", "size": 734003200, "media_type": "video/mp4", "checksum_sha256": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="}' # 2. Ask for part URLs, at most 128 at a time. Each one lasts five minutes. curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/parts" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"part_numbers": [1, 2, 3]}' # 3. PUT each part to its URL with the returned required_headers, and keep each ETag. # 4. Finish. The file appears at its path now. curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/complete" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"parts": [{"part_number": 1, "etag": "\"9b2c\""}, {"part_number": 2, "etag": "\"71fd\""}]}' ``` - 上传中断后再次调用 [`POST /v2/uploads/{upload_id}/parts`](https://mirabase.io/zh/developers/api/uploads.md#uploads-parts):它不再返回已收到的分片,因此可以续传。 - 分片地址和上传会话都会过期,过期后只能重新发起上传。有效期见参考页。 ## 添加没有路径的来源 [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) 导入网址、文本或对话(见 [记忆](https://mirabase.io/zh/developers/memory.md#conversation)),返回 202 以及 `entry_id`、`version_id` 和 `job_id`。一次调用创建一个 Entry,相同内容导入两次会创建两个,因此重试时请带 `Idempotency-Key`。网址在响应之后抓取,无效网址表现为失败的任务。 ```bash curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: article-2026-11-06" \ -H "Content-Type: application/json" \ -d '{"kind": "url", "url": "https://example.com/article"}' ``` 导入文本和对话时可以带 [redact_secrets](https://mirabase.io/zh/developers/api/schemas.md#DevIngestText.redact_secrets),在保存之前替换看起来像凭据的内容。它只识别形状明确的凭据,不能代替你自己的脱敏。导入对话时还可以带 [memory_instructions](https://mirabase.io/zh/developers/api/schemas.md#DevIngestConversation.memory_instructions),说明在你的应用里哪些内容需要记住。 ## 比较和回滚版本 [`GET /v2/entries/{entry_id}/versions`](https://mirabase.io/zh/developers/api/entries.md#entries-listversions) 列出版本链,最新的在前。[`POST /v2/entries/{entry_id}/revert`](https://mirabase.io/zh/developers/api/entries.md#entries-revert) 把旧版本的内容写成新版本,不改写历史。 ```bash curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/revert" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"version_id": "ver_1a07"}' ``` [`GET /v2/entries/{entry_id}/diff?from=&to=`](https://mirabase.io/zh/developers/api/entries.md#entries-diff) 比较两个版本,[`GET /v2/entries/{entry_id}/lineage`](https://mirabase.io/zh/developers/api/entries.md#entries-lineage) 说明 Entry 从哪里来、每个版本怎样产生。按路径调用时用 [`GET /v2/spaces/{space_id}/files/diff`](https://mirabase.io/zh/developers/api/files.md#files-diff) 和 [`GET /v2/spaces/{space_id}/files/lineage`](https://mirabase.io/zh/developers/api/files.md#files-lineage)。 curl: ```bash # Compare an older version with the latest. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=ver_1a07" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Where the file came from, and how each version came about. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts // An Entry by id, or by the path of its file. const diff = await mirabase.versions.diff({ path: "/notes/hello.md" }, "ver_1a07"); if (!diff.identical) console.log(diff.unified_diff ?? diff.diff_omitted); const lineage = await mirabase.versions.lineage({ path: "/notes/hello.md" }); console.log(lineage.origin.kind, lineage.data.map((version) => version.kind)); ``` Python: ```python # An Entry by id, or by the path of its file. The older version here is the quickstart's write. diff = mb.versions.diff({"path": "/notes/hello.md"}, written["version_id"]) if not diff["identical"]: print(diff.get("unified_diff") or diff.get("diff_omitted")) lineage = mb.versions.lineage({"path": "/notes/hello.md"}) print(lineage["origin"]["kind"], [version["kind"] for version in lineage["data"]]) ``` Agent 编辑文件时可以记录改动出自哪段对话:在主线上的 `PUT` 和 `PATCH` 带 [session_id](https://mirabase.io/zh/developers/api/files.md#files-write.session_id),取值与导入那段对话时相同。`lineage` 会显示这个版本的 `session_id`,之后可以用 [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 找到那段对话。 > **注意:** 替换文件的新版本最终处理失败时,路径会退回上一个可用版本,并由 `changes` 报告,因此返回 200 并不保证该路径始终保持这些字节。失败的版本保留在 `versions` 中,状态为 `discarded`,可以用 `version` 读取它的字节,或用 `revert` 恢复。需要确认新版本已经生效时,请查看 `knowledge.state`。 ## 查看处理状态 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 和 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read) 用于查询处理进度。[`POST /v2/entries/{entry_id}/reprocess`](https://mirabase.io/zh/developers/api/entries.md#entries-reprocess) 用于重试失败的版本,或重新处理最新版本。如需等待文件变为可检索或跟踪批量导入进度,见 [处理进度](https://mirabase.io/zh/developers/processing.md)。 ## 删除和彻底删除 | 操作 | 效果 | 需要 | 可否撤销 | | --- | --- | --- | --- | | `DELETE` 文件或 Entry | 移入废纸篓,在检索中立即不可见 | `knowledge:write` 和 editor | 可以,用 `restore` | | [`POST /v2/entries/{entry_id}/purge`](https://mirabase.io/zh/developers/api/entries.md#entries-purge) | 彻底删除 Entry、全部版本和路径 | `knowledge:manage` 和 Space 所有者 | 不可以 | > **说明:** 彻底删除不计配额,配额用完时也能调用。 ## 处理 Agent 的提案 Agent 修改不属于自己的文件时,默认返回 403 `proposal_required`,不产生任何内容。Space 所有者把它的 `write_mode` 设为 `direct` 后才能直接写入,见 [权限](https://mirabase.io/zh/developers/permissions.md#write-mode)。否则,Agent 可以带 `Prefer: handling=proposal` 把这次写入转成提案:文件保持不变,返回 202 和 `proposal_id`,由审核人决定。文件的 `PUT` 和 `PATCH`、`files/batch`、分片上传的完成请求和分支合并都支持这个请求头。 curl: ```bash # As the Agent: propose instead of failing with 403 proposal_required. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/plan.md" \ -H "Authorization: Bearer $AGENT_KEY" \ -H "Prefer: handling=proposal" \ -H "Content-Type: text/markdown" \ --data-binary @plan.md # As a reviewer: open proposals, what each one changes, then decide. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Agreed plan"}' ``` TypeScript: ```ts // As the Agent. On its own files and new files this is an ordinary write. const agent = new Mirabase({ apiKey: process.env.AGENT_KEY }); const submitted = await agent.proposals.submit("/notes/plan.md", nextPlan, { contentType: "text/markdown" }); if ("proposal_id" in submitted) { // Poll until a reviewer acts: status leaves "open". const proposal = await agent.proposals.get(submitted.proposal_id); } // As a reviewer. for await (const proposal of mirabase.proposals.list()) { const change = await mirabase.proposals.diff(proposal.id); if (change.unified_diff?.includes("Thursday")) { await mirabase.proposals.approve(proposal.id, { message: "Agreed plan" }); } else { await mirabase.proposals.reject(proposal.id); } } ``` Python: ```python import os # As the Agent. On its own files and new files this is an ordinary write. agent = Mirabase(api_key=os.environ["AGENT_KEY"]) submitted = agent.proposals.submit( "/notes/plan.md", "Releases move to Thursday.", content_type="text/markdown", ) if "proposal_id" in submitted: # Poll until a reviewer acts: status leaves "open". proposal = agent.proposals.get(submitted["proposal_id"]) # As a reviewer. for proposal in mb.proposals.list(): change = mb.proposals.diff(proposal["id"]) if "Thursday" in change.get("unified_diff", ""): mb.proposals.approve(proposal["id"], message="Agreed plan") else: mb.proposals.reject(proposal["id"]) ``` - 只有在不带这个请求头会返回 403 时才生效:自己的文件和新文件照常直接写入。 - 移动、删除和恢复他人的文件、`revert` 以及记忆写入不能转成提案,仍返回 403。 - 审核人是 Space 所有者,以及能直接修改该文件的 editor:人类用户,和 `direct` 模式下文件在其 `write_root` 内的 Agent。 - 提案不是版本:只有作者和 Space 所有者能在 `versions` 中看到提案内容,检索永远不会返回它。 ## 下一步 - [同步、快照与导出](https://mirabase.io/zh/developers/sync.md):跟上文件的变化。 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):在写入的内容里检索。 - [API 约定](https://mirabase.io/zh/developers/conventions.md#conditional):条件请求和幂等的通用规则。 --- # 处理进度 文件写入后先变为可检索,记忆随后生成:等待单个文件可检索、跟踪批量导入进度,并识别检索时尚未处理完成的内容。 写入文件后,服务依次提取文本、建立索引并发布到搜索。这三步完成后,文件即可按语义检索;关联、分类、摘要和记忆在之后生成,不影响检索。请求体中 64 KiB 以内的文本在写入后立即可以按词检索,见 [检索](https://mirabase.io/zh/developers/retrieval.md#search)。 最新版本所处的阶段记在 [stage](https://mirabase.io/zh/developers/api/schemas.md#DevEntryProcessing.stage) 中:为 `enriching` 或 `ready` 时,搜索即可找到该版本。 ## 等待单个文件可检索 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 返回最新版本的 `stage` 和 `progress`;排队等待期间还会返回 `queue`,说明排在前面的任务数和等待原因。SDK 的 `entries.waitUntil`(Python 为 `entries.wait_until`)会自动轮询该接口,默认等待至文件可检索;传入 `until: "ready"` 时则等待全部步骤完成。 curl: ```bash curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts // Returns once search finds the file ("enriching" or "ready"), or when it failed. const status = await mirabase.entries.waitUntil({ path: "/notes/launch.md" }, { onProgress: (s) => console.log(s.stage, `${s.progress.done}/${s.progress.total}`), }); if (status.stage === "failed") console.log(status.error?.code); ``` Python: ```python # Returns once search finds the file ("enriching" or "ready"), or when it failed. status = mb.entries.wait_until( {"path": "/notes/launch.md"}, on_progress=lambda s: print(s["stage"], f"{s['progress']['done']}/{s['progress']['total']}"), ) if status["stage"] == "failed": print(status["error"]["code"]) ``` - 处理失败时,`waitUntil` 会返回最后获取的状态而不抛出异常,此时请检查 `error` 字段。失败的版本可通过 [`POST /v2/entries/{entry_id}/reprocess`](https://mirabase.io/zh/developers/api/entries.md#entries-reprocess) 重试。 - 超过等待时间(默认 10 分钟)时,SDK 抛出代码为 `wait_timeout` 的错误,服务端的处理继续进行。 - 只写入一个文件时,也可以在写入请求中带 `Prefer: wait`,见 [写入文件](https://mirabase.io/zh/developers/files.md#write)。 ## 跟踪批量导入 导入大量文件时,无需逐个查询 Entry。[`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing) 按阶段统计 Space 中的 Entry,并返回其变为可检索的速率和预计剩余时间。SDK 的 `spaces.waitUntil`(Python 为 `spaces.wait_until`)会轮询该接口,直至 Space 中的全部 Entry 可检索;`onProgress` 会接收每次轮询获取的统计数据,可用于展示进度。 curl: ```bash curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts // Waits until every Entry in the Space is searchable; failed Entries count as finished. const summary = await mirabase.spaces.waitUntil({ onProgress: ({ counts, eta_seconds }) => console.log(counts, eta_seconds), }); console.log(`${summary.counts.failed} failed`); ``` Python: ```python # Waits until every Entry in the Space is searchable; failed Entries count as finished. summary = mb.spaces.wait_until( on_progress=lambda s: print(s["counts"], s.get("eta_seconds")), ) print(summary["counts"]["failed"], "failed") ``` - 失败的 Entry 计入 `counts.failed`,失败原因可通过 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 查看。 - 记忆在文件可检索之后单独提炼,`memory` 报告仍在排队或运行的提炼任务。仅等待提炼的 Entry 仍计为可检索。如需等待记忆提炼完成,请传入 `until: "ready"`。 - 不同 Space 和账户的任务轮流执行,因此一个 Space 的大批量导入不会阻塞其他 Space 的新文件。 ## 识别尚未处理完成的内容 所检索的 Space 中仍有 Entry 在处理时,`search`、`context` 和 `answer` 的响应带 `pending_processing`,其中 `entries` 是尚不可检索的 Entry 数。这些 Entry 的内容可能不在本次结果中:如果需要的内容可能在其中,请稍后再查询,或先等待处理完成。 ```json { "pack_id": "pck_...", "items": [ "..." ], "pending_processing": { "entries": 12 } } ``` SDK 的 `context` 和 `answer` 会原样返回该字段;`search` 返回命中结果数组,该字段位于数组的 `pendingProcessing` 属性中(Python 为 `pending_processing`)。MCP 工具 `mira.search` 的结果同样包含 `pending_processing`。 ## 处理队列已满时 账户排队的任务数超过上限时,写入请求会返回 429 `ingest_backlog`:`queue` 给出排队任务数和预计等待时间,`Retry-After` 为 30 到 600 秒。请按 `Retry-After` 等待后重试。SDK 仅在 `Retry-After` 不超过 `maxRetryAfterMs`(Python 为 `max_retry_after`,默认 60 秒)时自动等待并重试;超过时抛出 `MirabaseRateLimitError`,请读取 `retryAfterSeconds`(Python 为 `retry_after_seconds`)后自行等待,或调大该选项,见 [重试和幂等](https://mirabase.io/zh/developers/sdks.md#retries)。账户管理员可以随时通过 [`GET /v2/queue`](https://mirabase.io/zh/developers/api/usage.md#usage-queue) 查看队列。 ## 下一步 - [文件与版本](https://mirabase.io/zh/developers/files.md):写入、读取和修改文件。 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):在处理完成的内容上检索。 - [API 参考](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing):处理进度的全部字段。 --- # 同步、快照与导出 用目录树、变更流和 Webhook 将 Space 同步到其他系统,用快照固定某一时刻,用导出和导入迁移整个 Space。 同步由两个接口配合:[`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/zh/developers/api/tree.md#tree-list) 取得某一时刻的全貌,[`GET /v2/spaces/{space_id}/changes`](https://mirabase.io/zh/developers/api/changes.md#changes-list) 取得之后的变更。 ## 运行同步循环 1. 读 `tree`,保留**第一页**的 `changes_cursor`。翻页不是同一个快照,第一页的游标能覆盖翻页期间的写入。 2. 把游标传给 `changes`,应用返回的事件。 3. 继续用响应里的 `cursor`。`has_more` 为 `true` 时立即再调用一次,否则带 `wait` 长轮询。 curl: ```bash # 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" ``` TypeScript: ```ts // Every page of the tree, plus the first page's changes_cursor. const { nodes, changesCursor } = await mirabase.tree.snapshot("/", { recursive: true }); for (const node of nodes) mirror(node); // Long-polls, follows has_more, and reconnects after failures it can retry. for await (const change of mirabase.changes.watch({ cursor: changesCursor })) apply(change); ``` Python: ```python # Every page of the tree, plus the first page's changes_cursor. nodes, cursor = mb.tree.snapshot(recursive=True) for node in nodes: print(node["path"]) # Long-polls, follows has_more, and reconnects after failures it can retry. for change in mb.changes.watch(cursor=cursor): print(change["op"], change.get("path")) ``` - 不带 `cursor` 时变更流从当前时刻开始,所以全量同步要先读 `tree`。 - 游标过期时返回 410 `cursor_expired`:重新读 `tree`,从新的 `changes_cursor` 继续。事件的保留期和长轮询的上限见参考页。 ## 事件 每个事件的 `op` 是 `create`、`update`、`move`、`delete` 或 `restore`,含义见 [DevChangeOp](https://mirabase.io/zh/developers/api/schemas.md#DevChangeOp)。 ## 应用事件 - 事件可能重复,也可能重复 `tree` 已经展示的内容,所以按 `entry_id` 幂等应用。 - `move` 只带新路径。自己维护 `entry_id` 到路径的映射,从 `tree` 开始。 - 目录自身不产生事件,空目录的增删需通过 `tree` 查看。 - Agent 的私有记忆不进入变更流。 - 带 `branch` 时是分支自己的变更流,形状和规则都不同,见 [分支与挂载](https://mirabase.io/zh/developers/branches.md#reads)。 ## 查看最近的修改 多人或多个 Agent 共用一个 Space 时,开始工作前可先调用 [`GET /v2/spaces/{space_id}/activity`](https://mirabase.io/zh/developers/api/changes.md#changes-activity):该接口已将最近几天的变更流按主体和 Entry 汇总,无需从头读取 `changes` 再自行归并。 ## 接收 Webhook 不想轮询 `changes` 时,用 [`POST /v2/spaces/{space_id}/webhooks`](https://mirabase.io/zh/developers/api/webhooks.md#webhooks-create) 订阅主线的变更。Mirabase 按顺序推送,每批若干条事件,同一时间只有一批在途,至少送达一次;请求体的结构见 [DevWebhookPayload](https://mirabase.io/zh/developers/api/schemas.md#DevWebhookPayload)。 curl: ```bash 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"]}' ``` TypeScript: ```ts const webhook = await mirabase.webhooks.create({ url: "https://hooks.example.com/mirabase", ops: ["create", "update", "delete"], }); // Store webhook.secret now: it is in this response only. for await (const delivery of mirabase.webhooks.deliveries(webhook.id)) console.log(delivery.attempt, delivery.outcome); ``` Python: ```python webhook = mb.webhooks.create({ "url": "https://hooks.example.com/mirabase", "ops": ["create", "update", "delete"], }) # Store webhook["secret"] now: it is in this response only. for delivery in mb.webhooks.deliveries(webhook["id"]): print(delivery["attempt"], delivery["outcome"]) ``` TypeScript: ```ts 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); ``` Python: ```python import os from mirabase import parse_webhook def receive(header: str | None, body: bytes) -> None: """header is the Mirabase-Signature header, body the raw request body.""" # Verify against the raw body, before parsing JSON. Raises ValueError on a bad or stale signature. payload = parse_webhook(secret=os.environ["MIRABASE_WEBHOOK_SECRET"], header=header, body=body) # Dedupe on payload["delivery_id"]: a retry resends the same batch. for change in payload["events"]: print(change["op"], change.get("path")) ``` - 每个请求都要按上面的示例校验签名;签名格式和时间戳容差见 [DevWebhook](https://mirabase.io/zh/developers/api/schemas.md#DevWebhook)。 - 按 `Mirabase-Delivery-Id`(即 `delivery_id`)去重:重试时同一批原样重发。事件按 `entry_id` 应用。 - 尽快返回 2xx,将耗时的处理放在响应之后。失败的判定标准以及重试间隔见 [DevWebhook](https://mirabase.io/zh/developers/api/schemas.md#DevWebhook)。 - 密钥只在创建响应中返回。密钥丢失时调用 [`POST /v2/webhooks/{webhook_id}/rotate-secret`](https://mirabase.io/zh/developers/api/webhooks.md#webhooks-rotatesecret)。 推送停止时,`status` 变为 `disabled`,[disabled_reason](https://mirabase.io/zh/developers/api/schemas.md#DevWebhook.disabled_reason) 说明原因。[`PATCH /v2/webhooks/{webhook_id}`](https://mirabase.io/zh/developers/api/webhooks.md#webhooks-update) 带 `{status: "active"}` 重新启用,[`GET /v2/webhooks/{webhook_id}/deliveries`](https://mirabase.io/zh/developers/api/webhooks.md#webhooks-deliveries) 列出推送记录。 ## 创建快照 [`POST /v2/spaces/{space_id}/snapshots`](https://mirabase.io/zh/developers/api/snapshots.md#snapshots-create) 记录当前时刻每个文件的路径和版本。版本不可变,所以快照不复制字节。 curl: ```bash 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" ``` TypeScript: ```ts const snapshot = await mirabase.snapshots.create("before-import"); const then = await mirabase.files.readText("/notes/hello.md", { snapshot: "before-import" }); for await (const node of mirabase.tree("/", { recursive: true, snapshot: snapshot.id })) console.log(node.path); // Everything written after the snapshot, with no gap and no overlap. for await (const change of mirabase.changes.watch({ cursor: snapshot.changes_cursor })) apply(change); ``` Python: ```python snapshot = mb.snapshots.create("before-import") # Read a file as the snapshot pinned it, by name or id. then = mb.files.read("/notes/hello.md", snapshot="before-import").text() for node in mb.tree("/", recursive=True, snapshot=snapshot["id"]): print(node["path"]) # Everything written after the snapshot, with no gap and no overlap. for change in mb.changes.watch(cursor=snapshot["changes_cursor"]): print(change["op"], change.get("path")) ``` - 在 `tree`、`files` 和 `files/content-url` 上传入 `snapshot=`,即可读取快照固定的版本,即使文件此后已修改、移动或移入废纸篓。 - 快照的 `changes_cursor` 从同一时刻衔接 `changes`,因此快照加变更流就是一次不遗漏、不重复的全量同步。 - 快照只包含有路径的文件:空目录、记忆、导入的网址和文本都不在其中。 ## 导出和导入 [`POST /v2/spaces/{space_id}/exports`](https://mirabase.io/zh/developers/api/transfers.md#transfers-createexport) 把文件导出为 tar 归档,[`POST /v2/spaces/{space_id}/imports`](https://mirabase.io/zh/developers/api/transfers.md#transfers-createimport) 把 tar 或 gzip 压缩的 tar 导入 Space。两者都以任务执行,返回 202 和 `job_id`,按 [API 约定](https://mirabase.io/zh/developers/conventions.md#jobs) 跟踪。 curl: ```bash # 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"}' ``` TypeScript: ```ts const exported = await mirabase.transfers.startExport({ snapshot: "before-import" }); // ...poll mirabase.jobs.get(exported.job_id) until it succeeded, then: const archive = await mirabase.transfers.archiveUrl(exported.job_id); // Put the archive somewhere as a file, then import it into another Space. const written = await mirabase.files.write("/imports/space.tar", await (await fetch(archive.url)).blob(), { space: otherSpaceId, contentType: "application/x-tar", }); const imported = await mirabase.transfers.startImport( { source_entry_id: written.entry.id, path: "/", on_conflict: "skip" }, { space: otherSpaceId }, ); ``` Python: ```python from urllib.request import urlopen exported = mb.transfers.start_export({"snapshot": "before-import"}) # Polls until status is succeeded, failed, or cancelled. mb.jobs.wait(exported["job_id"]) archive = mb.transfers.archive_url(exported["job_id"]) # Put the archive in another Space as a file, then import it there. other_space_id is that Space's id. uploaded = mb.files.write( "/imports/space.tar", urlopen(archive["url"]).read(), space=other_space_id, content_type="application/x-tar", ) imported = mb.transfers.start_import( {"source_entry_id": uploaded["entry"]["id"], "path": "/", "on_conflict": "skip"}, space=other_space_id, ) ``` ### 导出 - 任务开始时确定文件列表,因此归档对应开始时刻的 Space 状态;传入 `snapshot` 时则对应该快照的状态。 - 归档只包含文件:没有路径的内容、记忆和版本历史都不导出。归档的格式见参考页。 - 任务成功后,用 [`GET /v2/jobs/{job_id}/content-url`](https://mirabase.io/zh/developers/api/transfers.md#transfers-archiveurl) 获取归档的下载地址。 > **注意:** 归档保留 7 天。彻底删除该 Space 内的任何文件,或者设置、修改发起人的 `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`](https://mirabase.io/zh/developers/api/transfers.md#transfers-createfork))即将上线。在此之前,可先创建快照,带 `snapshot` 导出,新建一个 Space,再将归档导入其中。 ## 下一步 - [分支与挂载](https://mirabase.io/zh/developers/branches.md):给 Agent 一个可以放弃的工作区。 - [API 约定](https://mirabase.io/zh/developers/conventions.md#jobs):跟踪导出和导入这类任务。 - [错误码](https://mirabase.io/zh/developers/errors.md#codes):`cursor_expired` 等错误码的处理方式。 --- # 检索与上下文 由调用方选择来源的 search、由服务选择来源并分配预算的 context,以及带引用的 answer。 三个接口都需要 `knowledge:read`,`answer` 另外需要 `knowledge:answer`。不传 `space_ids` 时使用调用方能读的全部 Space,不只是默认 Space。请求只涉及一个最终用户或一个项目时,请在 `space_ids` 里指定它的 Space。 | 接口 | 来源选择方 | 适用场景 | | --- | --- | --- | | [`POST /v2/retrieval/search`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-search) | 调用方 | 你知道要找什么,想自己排序和展示 | | [`POST /v2/retrieval/context`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext) | 服务 | 给 Agent 的一个任务组装上下文,要控制 token 预算 | | [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) | 服务,并由模型作答 | 你没有自己的模型,想直接获得带引用的回答 | ## 检索 写入后的下一个请求就能通过词法检索到,处理完成后再加上向量检索和重排。 curl: ```bash curl -X POST https://api.mirabase.dev/v2/retrieval/search \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "where do files and memory live"}' ``` TypeScript: ```ts const hits = await mirabase.search("where do files and memory live"); ``` Python: ```python hits = mb.search("where do files and memory live") ``` 读取结果时注意以下字段: - `score` 只在同一个响应内可比较。 - `freshness: pending_index` 表示命中来自新鲜缓冲:仅完成词法匹配,该版本尚未处理完成。 - `partial` 为 `true` 时,某路检索发生降级,或分数未经相关度校准。 - `modified_at` 是该版本的写入时间;`occurred_at` 是来源自身的时间,例如对话中某条消息产生的时间。若写入时已知内容发生的时间,请传入 `occurred_at`。 - 段落注明截至日期时,命中结果带有 `stated_date` 和 `stated_date_from`。多个文件同时上传且 `modified_at` 相同时,可用它区分新旧记录。判定规则见 [stated_date](https://mirabase.io/zh/developers/api/schemas.md#DevSearchHit.stated_date)。 - 针对历史消息发起检索时,传入 `reference_time` 和 `timezone`,查询中的“昨天”“上周”即按该消息的时间换算。`context` 和 `answer` 同样接受这两个参数。 - 分支里的内容在合并之前检索不到。 ## 构建上下文 `context` 接收一个任务描述,由服务挑选来源、分配预算并打包,同时在 `route` 里解释它的选择。路由用确定性规则,不调用模型,所以同样的输入可以重放和解释。 curl: ```bash curl -X POST https://api.mirabase.dev/v2/retrieval/context \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task": "Fix the failing upload test", "purpose": "coding", "tier": "standard", "budget_tokens": 4000}' ``` TypeScript: ```ts const pack = await mirabase.context("Fix the failing upload test", { purpose: "coding", tier: "standard", budget_tokens: 4000, }); ``` Python: ```python pack = mb.context( "Fix the failing upload test", purpose="coding", tier="standard", budget_tokens=4000, ) ``` 来源有 `memory`、`agent_profile`、`skills`、`files`、`changes` 和 `knowledge`。`route.sources` 逐个列出已启用来源的预算、用量、选中和省略的数量,以及 `why` 中的稳定代码;已禁用的来源记录在 [rules_fired](https://mirabase.io/zh/developers/api/schemas.md#DevContextRoute.rules_fired) 中。未用完的预算留空,记在 `route.unused_tokens` 中,不会填入不相关的内容。 - `budget_tokens` 覆盖整个响应,不只是 `items`;`tokens_used` 不会超过它。 - `memory_view` 是确定性的记忆视图:相同的记忆生成相同的字节,与任务无关。把 `memory_view_etag` 作为 `have_memory_etag` 传回,视图未变更时不再重复返回,适合作为 prompt 缓存前缀。 - 技能来自 `/.mirabase/skills//SKILL.md`。`skills` 条目的 `text` 是一行描述,正文按 `path` 读取。 - 条目可能带 `flags`:`stale`、`superseded`、`conflict` 或 `agent_written`。 - 打包期间证据变化时,服务会自动重新打包一次;仍然变化才返回 409 `evidence_changed`,此时再发一次同样的请求。 ### 表格计算 任务要对表格求和、计数、求平均或取最大值、最小值时,服务会在整张表上计算,不调用模型;何时计算、不计算的原因和上限见 [API 参考](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext)。计算结果是单独的一个条目,正文写明运算、所用的列、筛选条件、参与计算的行数和结果。 ### 以文本形式获取上下文 若无需自行拼接提示词,可在请求中传入 `render: "text"`,响应将增加 `rendered` 字段:`rendered.text` 是将该上下文包排版后的文本,可直接放入提示词。首行声明内容为参考材料而非指令;随后是记忆视图;之后在各自的 `[cN]` 编号下列出各来源内容。同一上下文包渲染出的文本完全相同。 ## 获取带引用的回答 [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) 用 `context` 会选的证据回答 `question`,在正文里用 `[cN]` 标注引用。它接受与 `context` 相同的选择参数,另有 `history`、`output_language`、`include` 和 `stream`。自己有模型时,通常用 `context` 更合适。 curl: ```bash curl -X POST https://api.mirabase.dev/v2/retrieval/answer \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"question": "When do releases go out?", "output_language": "en"}' ``` TypeScript: ```ts const reply = await mirabase.answer("When do releases go out?", { output_language: "en" }); if (reply.status === "answered") console.log(reply.answer, reply.citations); else console.log("abstained:", reply.reason); // Report what you used, the same as for a context pack. await mirabase.context.feedback(reply.pack_id, reply.citations.map((citation) => citation.citation_id)); ``` Python: ```python reply = mb.answer("When do releases go out?", output_language="en") if reply["status"] == "answered": print(reply["answer"], reply["citations"]) else: print("abstained:", reply.get("reason")) # Report what you used, the same as for a context pack. mb.context.feedback(reply["pack_id"], [citation["citation_id"] for citation in reply["citations"]]) ``` - 先看 `status`:`answered` 或 `abstained`。放弃时 `answer` 为空,`reason` 说明原因,取值见 [DevAnswerAbstainReason](https://mirabase.io/zh/developers/api/schemas.md#DevAnswerAbstainReason)。找不到相关证据时不调用模型,直接返回 `no_evidence`。 - `citations` 只列回答里引用了的证据,按首次引用的顺序;`evidence_count` 是交给模型的条目数。`pack_id` 和上下文包一样可以接收反馈。 - 模型会得知每条证据的写入时间和内容对应的日期。问题问的是当前状态(如“现在”“目前”)时,关于同一事物的证据按从新到旧排列。同一事物指同一个 Entry、多次保存的同一个网页,或 `metadata.subject_key` 取值相同的几个 Entry;路径或标题相似不算。要让一组文件(如每周的状态报告)按新旧排列,请给它们设置相同的 `subject_key`。 - 回答默认不使用 `changes` 和 `skills` 两个来源;要使用它们,请传 [weights](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer.body.weights)。 - 同时运行的回答数有上限,超出时返回 429 `rate_limited`,见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)。502 `model_failed` 和 503 `answer_unavailable` 可以稍后重试。SDK 只在 429 时自动重试回答;502 和 503 不重试,因为每次尝试都是一次模型调用。 ### 查看模型读过的证据 请求带 `include: ["evidence"]` 时,响应增加 `evidence`,按模型读取的顺序列出它读过的每一条证据,不带正文。回答给出旧值时,用它核对模型读了哪几条,以及每一条的日期。 ### 流式获取回答 请求带 `stream: true` 时,响应是 `text/event-stream`,而不是单个 JSON 响应体。认证、校验和等待空闲名额都在流打开之前完成,因此这些错误仍是普通的 HTTP 响应。流打开后状态码是 200,之后的错误作为 `error` 事件返回。两个 SDK 都提供 `answer.stream`,替你解析事件。各事件的 `data` 结构见 [获取带引用的回答](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer)。 curl: ```bash # -N turns off curl's output buffering, so each event prints as it arrives. curl -N -X POST https://api.mirabase.dev/v2/retrieval/answer \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"question": "When do releases go out?", "stream": true}' ``` TypeScript: ```ts const stream = mirabase.answer.stream("When do releases go out?"); for await (const event of stream) { if (event.type === "start") console.log("evidence items:", event.evidence_count); if (event.type === "delta") process.stdout.write(event.text); if (event.type === "replace") console.log("\n(the text so far is replaced by the final answer)"); } // final is authoritative: the same object mirabase.answer returns. const reply = await stream.finalAnswer(); console.log(reply.status, reply.answer, reply.citations); ``` Python: ```python with mb.answer.stream("When do releases go out?") as stream: for event in stream: if event["type"] == "start": print("evidence items:", event["evidence_count"]) elif event["type"] == "delta": print(event["text"], end="", flush=True) elif event["type"] == "replace": print("\n(the text so far is replaced by the final answer)") # final is authoritative: the same object mb.answer returns. reply = stream.final_answer() print(reply["status"], reply["answer"], reply["citations"]) ``` ```text : stream open id: 1 event: start data: {"request_id":"req_5d1e","pack_id":"pck_7c19","evidence_count":6,"partial":false} id: 2 event: delta data: {"text":"Releases go out "} : ping id: 3 event: delta data: {"text":"on Thursdays [c1]."} id: 4 event: final data: {"status":"answered","answer":"Releases go out on Thursdays [c1].","citations":[{"citation_id":"c1","entry_id":"ent_9a41","version_id":"ver_4d02","title":"release-notes.md","source":"files","path":"/notes/release-notes.md","text":"From November on, releases go out on Thursdays."}],"evidence_count":6,"pack_id":"pck_7c19","partial":false,"route":{"purpose":"task","tier":"standard","rules_fired":["source:off:changes:answer_default","source:off:skills:answer_default"],"sources":[],"unused_tokens":1200}} ``` - 按顺序拼接 `delta` 的文本。收到 `replace` 时丢弃已显示的文本,改为显示 `final` 的 `answer`;有的回答只有 `final`,没有 `delta`。 - 以 `:` 开头的行是保持连接的注释,忽略它们,也忽略不认识的事件名。 - `final` 和 `error` 只发送其中一个,发送后流结束。收到 `error` 时丢弃已显示的文本。未收到这两者即结束的流说明连接已中断:请按请求失败处理并重新提问。流不支持续传。 - 流式回答在流结束之前占用一个回答名额。断开连接会取消回答并释放名额;在 SDK 里提前跳出循环、调用 `close()` 或取消 `signal` 都会断开连接。 - SDK 的 `answer.stream` 把 `error` 事件、中途断流和无法解析的数据都作为 `MirabaseError` 抛出,已经开始的流不会自动重试。`mirabase.answer(question, { stream: true })` 不会流式返回:它抛出 `MirabaseConfigError`,代码为 `stream_not_supported`,请改用 `answer.stream`。 ## 发送反馈 [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-contextfeedback) 传实际用到的 `used_citation_ids`,只传引用,不传内容。报告会累加,重复或分几次报告都安全。 curl: ```bash curl -X POST "https://api.mirabase.dev/v2/retrieval/context/$PACK_ID/feedback" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"used_citation_ids": ["c1"]}' ``` TypeScript: ```ts await mirabase.context.feedback(pack.pack_id, ["c1"]); ``` Python: ```python mb.context.feedback(pack["pack_id"], ["c1"]) ``` ## 授权 - 服务在规划之前先解析允许访问的 Space;对于不可见或不存在的 Space,服务均返回 404 `not_found`。 - 所有结果都经过同一道最终检查,`route` 和省略计数在授权之后生成。 - `scope_used.space_ids` 是这次实际用到的 Space。 - `agent_profile` 仅对 Agent 的 Key 启用。 > **说明:** MCP 客户端可以用同一个 API Key 连接 `/mcp`。工具 `mira.search`、`mira.context`、`mira.answer` 和 `mira.context.feedback` 各对应一次上面的请求,见 [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md)。 ## 查看检索过程 将请求中的 [explain](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-search.body.explain) 设为 `true` 时,`search`、`context` 和 `answer` 的每条结果以及响应本身都会包含 `explain`:说明结果由哪几路检索召回、重排前后的位置、匹配的查询词,以及调整了其位置的规则。检索结果及其顺序不会因此改变。 - 控制台的“检索测试台”以你的登录身份或你提供的 API Key 运行搜索、上下文和回答,并显示每条结果的召回原因。 - 控制台的“请求日志”列出账户最近的 API 请求(仅含元数据),可按状态、路由、API Key、客户端和错误码筛选;对于检索请求,可以查看其轨迹,或在检索测试台中重新打开。仅团队所有者和管理员可查看。 - 同样的数据也可以通过 API 读取:[`GET /v2/request-logs`](https://mirabase.io/zh/developers/api/request-logs.md#requestlogs-list) 和 [`GET /v2/retrieval/traces/{trace_id}`](https://mirabase.io/zh/developers/api/request-logs.md#requestlogs-trace)。所需权限和保留期见 [API 参考](https://mirabase.io/zh/developers/api/request-logs.md)。 ## 下一步 - [记忆](https://mirabase.io/zh/developers/memory.md):让上下文里带上提炼出的事实。 - [连接 Agent](https://mirabase.io/zh/developers/agents.md):让 Agent 通过 MCP 使用同样的检索。 - [API 约定](https://mirabase.io/zh/developers/conventions.md#rate-limits):检索的并发和速率限制。 --- # 记忆 写入、提炼、审核、更正和遗忘记忆,以及离线整理记忆。 ## 记忆模型 `/v2/memories` 用统一结构返回三种来源:账户记忆、以 Entry 写入的记忆、从 Entry 提炼的事实。只有以 Entry 写入的记忆,`id` 才是 Entry id。提炼的事实通过 `provenance` 关联到 Entry 和版本。 每条记忆有一个范围和一个状态:范围决定记忆归谁([DevMemoryScope](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryScope)),状态决定检索是否使用它([DevMemoryStatus](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryStatus))。 遗忘是物理删除,没有正文可返回,所以没有 `forgotten` 状态。 ## 写入记忆 一句始终成立的陈述,例如偏好或决定,用 [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) 写入。写入后立即为 `confirmed`,此后的上下文和回答都会使用。同一内容不会重复写入,各范围需要的权限见参考。 curl: ```bash curl -X POST https://api.mirabase.dev/v2/memories \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scope": "project", "space_id": "'$SPACE_ID'", "kind": "decision", "text": "Releases go out on Thursdays."}' ``` TypeScript: ```ts const memory = await mirabase.memories.create({ scope: "project", space_id: spaceId, kind: "decision", text: "Releases go out on Thursdays.", }); ``` Python: ```python memory = mb.memories.create({ "scope": "project", "space_id": space_id, "kind": "decision", "text": "Releases go out on Thursdays.", }) ``` ## 从对话中提炼记忆 若要提出候选而非直接写入,请导入对话:[`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) 带 `kind: conversation`、`session_id` 和 `messages`,返回 202。一个批次是一个 Entry,无论有多少轮。发送时持有 `memory:confirm`,提炼出的事实即是 `confirmed`,否则是 `candidate`;回执的 `memory_status` 说明是哪一种。 curl: ```bash curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: chat-42-batch-1" \ -H "Content-Type: application/json" \ -d '{"kind": "conversation", "session_id": "chat-42", "messages": [ {"role": "user", "content": "Let us ship on Thursdays from now on.", "timestamp": 1762416000000}, {"role": "assistant", "content": "Noted: releases on Thursdays."} ]}' ``` TypeScript: ```ts const receipt = await mirabase.conversations.add( [ { role: "user", content: "Let us ship on Thursdays from now on.", timestamp: 1762416000000 }, { role: "assistant", content: "Noted: releases on Thursdays." }, ], { sessionId: "chat-42", idempotencyKey: "chat-42-batch-1" }, ); ``` Python: ```python receipt = mb.conversations.add( [ {"role": "user", "content": "Let us ship on Thursdays from now on.", "timestamp": 1762416000000}, {"role": "assistant", "content": "Noted: releases on Thursdays."}, ], session_id="chat-42", idempotency_key="chat-42-batch-1", ) ``` 提炼在索引完成后进行,因此处理任务变为 `succeeded` 时,记忆可能尚未生成。轮询 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing),直到 `memory.state` 不再为 `pending`:`ready` 时用 [`GET /v2/memories?entry_id=`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 列出该批次生成的记忆;`skipped` 表示该版本不提炼,原因见下文;`failed` 表示提炼失败。 curl: ```bash # Repeat until memory.state is no longer "pending". # "skipped" means the batch is not distilled: memory.reason says why. curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Then list what the batch wrote. curl "https://api.mirabase.dev/v2/memories?entry_id=$ENTRY_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts let processing = await mirabase.entries.processing(receipt.entry_id); for (let attempt = 0; attempt < 30 && processing.memory?.state === "pending"; attempt += 1) { await new Promise((resolve) => setTimeout(resolve, 2000)); processing = await mirabase.entries.processing(receipt.entry_id); } if (processing.memory?.state === "skipped") { // Not distilled. reason says why, for example "model_not_configured"; // remediation.action, when present, says what to do. console.log(processing.memory.reason, processing.memory.remediation?.action); } else { for await (const memory of mirabase.memories.list({ entry: receipt.entry_id })) { console.log(memory.status, memory.text); } } ``` Python: ```python import time processing = mb.entries.processing(receipt["entry_id"]) for _ in range(30): if processing.get("memory", {}).get("state") != "pending": break time.sleep(2) processing = mb.entries.processing(receipt["entry_id"]) memory_state = processing.get("memory", {}) if memory_state.get("state") == "skipped": # Not distilled. reason says why, for example "model_not_configured"; # remediation["action"], when present, says what to do. print(memory_state.get("reason"), memory_state.get("remediation", {}).get("action")) else: for memory in mb.memories.list(entry=receipt["entry_id"]): print(memory["status"], memory["text"]) ``` - 同一批次重复导入会产生两个 Entry,因此重试时请携带 `Idempotency-Key`,见 [幂等](https://mirabase.io/zh/developers/conventions.md#idempotency)。 - 持续记录同一段对话时,每个批次使用相同的 `session_id`。该 id 也会存为元数据键 `session_id`,因此 [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 可将它们一并列出,检索时可用 `filter.metadata` 限定到该对话。 - `proposal` 模式的 Agent 导入时,提炼结果总是 `candidate`。 ### 提炼被跳过的原因 写入回执、处理状态和任务中的 `memory` 是同一个对象。`state` 为 `skipped` 时,`reason` 说明原因;原因可以处理时还带 `remediation`,按其中的 `remediation.action` 处理,例如部署没有配置提炼模型时,改为直接 [写入记忆](https://mirabase.io/zh/developers/memory.md#create)。部署不提炼记忆或 Entry 带有 `memory_exclude` 时,写入回执即为 `skipped`,无需轮询。`distill_disabled`、`model_not_configured` 和 `distill_paused` 涉及部署配置和账户用量,只有属于 `tenant_admin` 或持有 `knowledge:manage`、且未收窄到 Space 或元数据范围的 Key 能看到;其他 Key 看到的是 `distill_unavailable`(替代前两个);`distill_paused` 不返回原因,状态仍为 `pending`。部署停止提炼之前已经提炼完成的版本仍为 `ready`。全部原因和对应的处理方式见 [DevMemoryProcessingReason](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryProcessingReason) 和 [remediation](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryProcessing.remediation)。 ## 审核、更正和遗忘记忆 ```bash # Candidates waiting for review in one Space. curl "https://api.mirabase.dev/v2/memories?space_id=$SPACE_ID&status=candidate" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Confirm one, or send "reject". curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/review" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"decision": "confirm"}' # Replace it with what is true now. The response is a new memory whose supersedes names the old one. curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/correct" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Releases go out on Wednesdays."}' # Where it came from. curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Forget it for good. curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` - 候选记忆需由人工审核:用 [`POST /v2/memories/{memory_id}/review`](https://mirabase.io/zh/developers/api/memories.md#memories-review) 确认或驳回。 - 内容有误时用 [`POST /v2/memories/{memory_id}/correct`](https://mirabase.io/zh/developers/api/memories.md#memories-correct) 写入正确的陈述,旧记忆关闭并保留为历史;新写入的记忆或更正可在 30 分钟内用 [`POST /v2/memories/{memory_id}/undo`](https://mirabase.io/zh/developers/api/memories.md#memories-undo) 撤销。 - [`DELETE /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-forget) 永久遗忘,不能撤销。驳回或遗忘一条提炼事实后,同一句话不会在这个 Space 里再被提炼。 - [`GET /v2/memories/{memory_id}/provenance`](https://mirabase.io/zh/developers/api/memories.md#memories-provenance) 列出一条记忆依据的 Entry 版本和引文。 - 不想让一份来源产生记忆时,用 [`PATCH /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 设置 `memory_exclude: true`:从它提炼的事实停用,搜索和读取不受影响。设回 `false` 会重新提炼,已遗忘或更正的内容不会恢复。 ## MEMORY.md `/.mirabase/memory/MEMORY.md` 是生成的只读视图,供开始工作的 Agent 读取该 Space 的记忆。同样的记忆产生同样的字节,`ETag` 是内容哈希,适合做 prompt 缓存前缀。用 [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-read) 读取;它只有原始字节,写入返回 405 `virtual_file`。在默认写法中,从对话提炼的事实不包含在内,请使用 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 或检索。开启了离线整理的部署改用索引写法,并增加 `RECENT.md`,见 [索引写法](https://mirabase.io/zh/developers/memory.md#memory-index)。 ```bash # Send back the ETag you have. 304 means nothing changed. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H 'If-None-Match: ""' ``` ## 离线整理(dreams) Agent 不在工作时,后台会整理已有的记忆。API 将一次整理运行称为一个 dream。它**只整理、不生成**:不写新记忆,不改记忆的正文,每个动作都带证据,都可以撤销。合并和取代只生成提案,模型不会自行修改任何记忆,经人工批准后才生效。 > **说明:** 离线整理是部署可选的功能。未开启该功能的部署上,本节和下面两节的接口都返回 404,`MEMORY.md` 保持上面的默认写法,也没有 `RECENT.md`。 ### 它做什么 - 核对引文:将每条提炼记忆的逐字引文与来源 Entry 的当前版本比对。若所有引文均不再存在,则将该记忆标为休眠(`quote_missing`)。 - 找出闲置的记忆:长期未被取用、也无人确认过的提炼记忆,默认只写进报告,设置为 `apply` 时标为休眠(`unused`),再次被取用时恢复。 - 统计重复:找出表达同一内容的记忆组,并在报告里记录整理前后生效记忆的条数和 token 数(`view`)。 - 比较记忆:Space 所有者显式开启 `d4` 后,才会调用模型比较成对的提炼记忆,判断是否重复、谁取代谁、是否矛盾,结论只会成为 [整理提案](https://mirabase.io/zh/developers/memory.md#memory-proposals)。默认不调用模型。 - 自动运行:某个范围有新记忆时自动运行,也可以手动发起。 ### 它不做什么 - 不生成:不写新记忆,不改记忆正文,不写 Entry、文件或版本,除 `MEMORY.md` 和 `RECENT.md` 外不写入任何内容。 - 模型不直接修改:模型只说明两条记忆的关系,并逐字引用来源,不写任何会进入记忆的文字,也不直接改动记忆。`auto` 档位尚未开放。 - 不改动人工确认的内容:审核通过的候选和带 `memory:confirm` 导入的对话里提炼出的记忆,既不会因为找不到引文而被标记,也不会因为闲置而休眠;以 Entry 写入的记忆和账户记忆,整理都不修改。只有未经人工审核就生效的提炼记忆才可能休眠,它们的状态也是 `status: "confirmed"`。 - 不恢复已遗忘的记忆:撤销一次整理也不会使其恢复。 - 不越界:只在一个范围里整理(Space 的项目记忆,或一个 Agent 的私有记忆),不跨范围,不跨 Space,不在分支上运行。 - 不删除:整理本身最重的动作是标记休眠;关闭一条记忆只发生在人批准提案之后,也可以撤销。物理删除只来自调用方的遗忘和彻底删除。 ### 记忆分层 不同的记忆适用不同的规则:很少用到却重要的规则,不应因为较少使用而被搁置;事件有先后顺序,不应作为重复项合并。层由记忆的 `kind` 和有效时间决定,在整理时计算;记忆本身没有这个字段,提案和判定上带 `layer`。 四个层各包含哪些记忆、哪些层参与比较和生成整理提案,见 [DevMemoryLayer](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryLayer);记忆闲置多久会休眠,见 [DevMemoryDormancyReason](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryDormancyReason)。 取代只在模型判断的新旧与来源的时间先后一致时才成立,否则降为矛盾(`conflict`),仅供人工查看。 ### 休眠与唤醒 休眠的记忆带 `dormant: {reason, dream_id}`。它不再进入 `RECENT.md`,也不参与模型比较,但仍可列出和搜索。`MEMORY.md` 里只有人工写入和人工确认过的记忆,这些从不休眠。两种原因的条件和清除方式见 [DevMemoryDormancyReason](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryDormancyReason)。 - 解除休眠不需要调用专门接口:通过 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) 读取记忆,或搜索、上下文包、回答返回这条记忆时,记忆即被唤醒。读取 `MEMORY.md`、`RECENT.md` 和列表不算。 - 从 `apply` 改回 `report` 不清除已有的标记,如需清除请撤销那次整理。 ### 设置:默认只出提案 每个 Space 有三个设置:`memory_dreaming`(默认 `propose`,整理照常运行;`off` 停止)、`dormancy`(默认 `report`,闲置的记忆只写进报告;`apply` 标为休眠)和 `d4`(默认 `off`,不调用模型;`shadow` 只记录判定;`propose` 把通过校验的判定写成提案)。在 `propose` 下,整理本身只做可撤销、不修改正文的标记;合并重复的记忆、用新记忆取代旧记忆、标出互相矛盾的记忆、把 Agent 的私有记忆提升到项目,这类改动只生成 [整理提案](https://mirabase.io/zh/developers/memory.md#memory-proposals),由人工决定。只有 Space 所有者能修改设置。 curl: ```bash curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Stop dreams for this Space. What they already did stays; undo a dream to take it back. curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"memory_dreaming": "off"}' # Mark unused memories dormant, and let a model propose merges and supersessions. curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"dormancy": "apply", "d4": "propose"}' ``` TypeScript: ```ts const settings = await mirabase.memory.settings.get(); // settings.memory_dreaming is "propose" unless someone changed it. await mirabase.memory.settings.update("off"); // A field left out keeps its value. settings.d4_available says whether this deployment can ask a model. await mirabase.memory.settings.update({ dormancy: "apply", d4: "propose" }); ``` Python: ```python settings = mb.memory.settings.get() # settings["memory_dreaming"] is "propose" unless someone changed it. mb.memory.settings.update("off") # A field left out keeps its value. settings["d4_available"] says whether this deployment can ask a model. mb.memory.settings.update(dormancy="apply", d4="propose") ``` - 先读一次报告再把 `dormancy` 改为 `apply`。 - 先用 `shadow` 运行一段时间并查看判定,再改为 `propose`:已记录的判定直接转为提案,无需再次调用模型。 - 响应里的 `d4_available` 为假时,这个部署不调用模型,无论 `d4` 如何设置。 ### 发起、查看和撤销整理 [`POST /v2/spaces/{space_id}/memory/dreams`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-start) 立即发起一次整理,返回 202,`job_id` 即整理 id,用 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read) 跟进。[`GET /v2/memory/dreams/{dream_id}`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-read) 是报告,[`GET /v2/memory/dreams/{dream_id}/actions`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-actions) 列出每个改动和理由,[`GET /v2/memory/dreams/{dream_id}/judgments`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-judgments) 列出模型比较过的每一对。[`POST /v2/memory/dreams/{dream_id}/undo`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-undo) 撤销整次整理。一个范围同一时间只有一次整理。 curl: ```bash # Start one now. job_id is the dream id (drm_...). curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/dreams" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scope": "project"}' # Poll until status is succeeded or failed. curl "https://api.mirabase.dev/v2/jobs/$DREAM_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # The report, then every change with its reason. curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/actions" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Every pair a model was asked about, proposed or not. curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/judgments" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Take it back. curl -X POST "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/undo" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` TypeScript: ```ts const started = await mirabase.memory.dreams.start({ scope: "project" }); let job = await mirabase.jobs.get(started.job_id); while (job.status === "queued" || job.status === "running") { await new Promise((resolve) => setTimeout(resolve, 2000)); job = await mirabase.jobs.get(started.job_id); } const dream = await mirabase.memory.dreams.get(started.job_id); console.log(dream.counts.checked, dream.counts.dormant_marked, dream.view?.live_before, dream.view?.live_after); for await (const action of mirabase.memory.dreams.actions(dream.id)) { console.log(action.seq, action.memory_id, action.action, action.reason, action.state); } for await (const judgment of mirabase.memory.dreams.judgments(dream.id)) { console.log(judgment.outcome, judgment.kind, judgment.member_ids, judgment.evidence); } if (dream.undoable) await mirabase.memory.dreams.undo(dream.id); ``` Python: ```python started = mb.memory.dreams.start(scope="project") # Polls until status is succeeded, failed, or cancelled. mb.jobs.wait(started["job_id"]) dream = mb.memory.dreams.get(started["job_id"]) print(dream["counts"]["dormant_marked"], dream.get("view")) for action in mb.memory.dreams.actions(dream["id"]): print(action["seq"], action["memory_id"], action["action"], action["reason"], action["state"]) for judgment in mb.memory.dreams.judgments(dream["id"]): print(judgment["outcome"], judgment.get("kind"), judgment["member_ids"], judgment.get("evidence")) if dream["undoable"]: mb.memory.dreams.undo(dream["id"]) ``` - 撤销针对整次整理,逐条进行:休眠标记清除,未处理的提案变为 `withdrawn`,已批准的合并和取代被还原。之后变更过的记忆保持不变,计入 `conflict_skipped`。 - 报告和动作只统计来源对调用方可见的记忆;`agent` 范围的整理只对对应 Agent 和 Space 所有者可见。 ## 整理提案 离线整理提出但不自行执行的改动称为整理提案,与 [文件提案](https://mirabase.io/zh/developers/files.md#proposals) 不同。整理提案的种类见 [DevMemoryProposalKind](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryProposalKind),状态见 [DevMemoryProposalStatus](https://mirabase.io/zh/developers/api/schemas.md#DevMemoryProposalStatus)。调用方必须能看到每个成员的来源才能看到该整理提案。 > **说明:** 只有 Space 的 `d4` 设置为 `propose` 且当前部署已配置模型(`d4_available` 为真)时,整理才会生成提案;否则列表为空。 ### 逐字引文 模型不生成结论文字,因此目前始终不返回 `proposed_text`。判断依据都来自来源原文:`evidence` 每个条目带 `memory_id`、`entry_id`、`version_id` 和逐字的 `quote`,`times` 是决定新旧顺序的日期,`plan` 写明批准后保留哪条(`keep`)、关闭哪些(`close`)。引文必须在对应记忆的来源中逐字匹配,否则整组判定会被丢弃,不会成为提案。 curl: ```bash # Open proposals of one dream, oldest first. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/proposals?dream_id=$DREAM_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Read the exact version a quote came from. curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content?view=text&version=$VERSION_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Carry it out. It takes effect only now. curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID/approve" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # Or close it without changing any memory. curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$OTHER_PROPOSAL_ID/reject" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` TypeScript: ```ts for await (const proposal of mirabase.memory.proposals.list({ dreamId: dream.id })) { console.log(proposal.kind, proposal.layer, proposal.plan, proposal.times); for (const { entry_id, version_id, quote } of proposal.evidence ?? []) { // Read the exact version the quote came from, and show both to the person deciding. const source = await mirabase.entries.content(entry_id, { view: "text", version: version_id }); console.log(quote, source.text?.includes(quote)); } } // Once a person has decided. await mirabase.memory.proposals.approve(proposalId); await mirabase.memory.proposals.reject(otherProposalId); ``` Python: ```python proposals = mb.memory.proposals.list(dream_id=dream["id"]).to_list() for proposal in proposals: print(proposal["kind"], proposal.get("layer"), proposal.get("plan"), proposal.get("times")) for evidence in proposal.get("evidence", []): # Read the exact version the quote came from, and show both to the person deciding. source = mb.entries.content(evidence["entry_id"], view="text", version=evidence["version_id"]) print(evidence["quote"], evidence["quote"] in source.get("text", "")) # Once a person has decided: proposal_id is the one approved, other_proposal_id the one rejected. mb.memory.proposals.approve(proposal_id) mb.memory.proposals.reject(other_proposal_id) ``` ### 批准和驳回 [`POST /v2/memory/proposals/{proposal_id}/approve`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memoryproposals-approve) 执行 `merge` 或 `supersede`:`plan.close` 中的记忆关闭,`plan.keep` 保留,正文不变。[`POST /v2/memory/proposals/{proposal_id}/reject`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memoryproposals-reject) 关闭提案,不修改任何记忆。 - `conflict` 和 `promote` 不能批准。矛盾需要通过 [更正或遗忘](https://mirabase.io/zh/developers/memory.md#govern) 其中一条来解决,或者直接驳回。 - 撤销批准:[撤销那次整理](https://mirabase.io/zh/developers/memory.md#dreams)。撤销针对整次整理,不能只撤销其中一条提案。 ### 从记忆查找提案 开启了离线整理的部署上,[`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 和 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) 会在有待处理提案时返回 `pending_proposals`:关于这条记忆(或它所在组的成员)的提案 id,最早的在前,只包含调用方可见的提案,没有时不返回。要在界面上为这条记忆显示“待处理”标记,用这个字段即可。 curl: ```bash # pending_proposals is present only when there are open proposals you can see. curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts const memory = await mirabase.memories.get("distill:ent_7f20:fact_31"); for (const id of memory.pending_proposals ?? []) { const proposal = await mirabase.memory.proposals.get(id); console.log(proposal.kind, proposal.plan, proposal.evidence); } ``` Python: ```python memory = mb.memories.get("distill:ent_7f20:fact_31") for pending_id in memory.get("pending_proposals", []): proposal = mb.memory.proposals.get(pending_id) print(proposal["kind"], proposal.get("plan"), proposal.get("evidence")) ``` ## MEMORY.md 的索引写法与 RECENT.md 开启了离线整理的部署上,`MEMORY.md` 是一份索引:按“规则和偏好”“决定和进度”“事实”分节,一行一条记忆,行尾是 `[m1]` 这样的引用号,文件末尾的 `References` 表把引用号映射到记忆 id。内容是人工写入的记忆(账户记忆、以 Entry 写入的记忆)和人工确认过的提炼记忆,这些都不会休眠;内容相同的记忆只出现一次。 ```markdown # Memory ## Rules and preferences - Keep answers short and in English. [m1] ## Decisions and progress - Releases go out on Thursdays. [m2] ## Facts - The staging database runs PostgreSQL 16. [m3] ## References [m1]: mem_5d02 [m2]: ent_9a41 [m3]: distill:ent_7f20:fact_31 ``` - 整份最多 2,000 token,其中提炼记忆最多占 800 token。写不下的不截断,整条略去,最后一行写 `… N more: GET /v2/memories?space_id=...`。 - 不写日期和时间。排序只随内容变化:先列人工写入的记忆,再列人工确认过的提炼记忆,提炼记忆按新近度和 id 排序,不看取用次数。所以检索命中不会让 `ETag` 变化,它以 `mf2.` 开头,仍然适合做 prompt 缓存前缀。 `/.mirabase/memory/RECENT.md` 是第二个生成文件:这个 Space 最近 7 天写入的项目记忆和 Agent 记忆,包括尚未审核的候选,最新的在前,最多 50 条、1,000 token。每行标明类型和状态,引用号格式为 `[r1]`,`ETag` 以 `rf1.` 开头。账户记忆和休眠的记忆不在其中。读写规则与 `MEMORY.md` 相同。 ```markdown # Recent memory - (decision, confirmed) Releases go out on Thursdays. [r1] - (preference, candidate) Use metric units in reports. [r2] ## References [r1]: ent_9a41 [r2]: distill:ent_7f20:fact_44 ``` curl: ```bash # The stable part: send back the ETag you have, 304 means nothing changed. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H 'If-None-Match: "mf2."' # The part that moves: what was written in the last 7 days. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/RECENT.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts const index = await mirabase.files.read("/.mirabase/memory/MEMORY.md"); const recent = await mirabase.files.read("/.mirabase/memory/RECENT.md"); // MEMORY.md first, as the cached prefix; RECENT.md later, where the prompt changes anyway. const prompt = [index.text(), recent.text()].join("\n"); ``` Python: ```python index = mb.files.read("/.mirabase/memory/MEMORY.md") recent = mb.files.read("/.mirabase/memory/RECENT.md") # MEMORY.md first, as the cached prefix; RECENT.md later, where the prompt changes anyway. prompt = index.text() + "\n" + recent.text() # Later, send back the ETag you have: None means nothing changed. newer = mb.files.read_if_changed("/.mirabase/memory/MEMORY.md", index.etag) ``` - 把 `MEMORY.md` 放在提示词前部做稳定前缀,`RECENT.md` 放在后部经常变化的地方。 - 两个文件都只包含调用方可见的记忆,因此不同调用方可能获得不同的字节和 `ETag`。 ## 按 id 读取记忆 索引里只有一句话和一个 id。如需详情,按 `References` 里的 id 调用 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read);如需查看依据的版本和引文,再调用 [`GET /v2/memories/{memory_id}/provenance`](https://mirabase.io/zh/developers/api/memories.md#memories-provenance)。 curl: ```bash # An id from the References table. export MEMORY_ID="distill:ent_7f20:fact_31" curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # The versions and quotes it rests on. curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts const memory = await mirabase.memories.get("distill:ent_7f20:fact_31"); // memory.group_id and memory.sources when other memories say the same; memory.dormant when a dream set it aside. const provenance = await mirabase.memories.provenance(memory.id); ``` Python: ```python # An id from the References table. memory = mb.memories.get("distill:ent_7f20:fact_31") # memory["group_id"] and memory["sources"] when other memories say the same; memory["dormant"] when a dream set it aside. # The versions and quotes it rests on. provenance = mb.memories.provenance(memory["id"]) ``` 通过 MCP 工作的 Agent 用工具 `mira.memory.get`:输入 `memory_id`,默认连同来源返回 `{memory, provenance}`;传 `include_provenance: false` 只取记忆。它只在开启了离线整理的部署上出现在工具清单里。 ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "mira.memory.get", "arguments": { "memory_id": "distill:ent_7f20:fact_31" } } } ``` 开启了离线整理的部署上,内容相同的提炼记忆在列表中合并为一组,带 `group_id` 和 `sources`;遗忘、更正和审核仍然按单条 id 调用。 ## 下一步 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):记忆如何进入上下文和回答。 - [连接 Agent](https://mirabase.io/zh/developers/agents.md):Agent 用 MCP 工具读写记忆。 - [权限](https://mirabase.io/zh/developers/permissions.md):谁能确认、更正和遗忘记忆。 --- # 连接 Agent(MCP) 通过 MCP 将 Claude Code、Codex 等 Agent 接入 Mirabase:连接方式、协议版本、可用的工具及其参数,以及推荐的调用顺序。 ## 连接 Agent MCP 地址是 `https://api.mirabase.dev/mcp`,传输方式是 Streamable HTTP,凭据为 API Key:`Authorization: Bearer mb_live_...`。请为 Agent 单独创建一个 Key,并关联到一个 `agent` 主体,使它拥有自己的权限、记忆和审计身份,见 [权限](https://mirabase.io/zh/developers/permissions.md#principals)。 Claude Code: ```bash claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \ --header "Authorization: Bearer $MIRABASE_API_KEY" ``` Codex: ```bash codex mcp add mirabase --url https://api.mirabase.dev/mcp \ --bearer-token-env-var MIRABASE_API_KEY ``` JSON: ```json { "mcpServers": { "mirabase": { "type": "http", "url": "https://api.mirabase.dev/mcp", "headers": { "Authorization": "Bearer mb_live_..." } } } } ``` - 任何支持 Streamable HTTP 且可发送请求头的 MCP 客户端均可连接,配置格式见上方 JSON。 - `tools/list` 只列出这个 Key 能调用的工具:只读的 Key 不会列出写工具,带元数据范围的 Key 只列出范围内可用的工具,见 [按元数据授权](https://mirabase.io/zh/developers/authentication.md#metadata-scope)。 - 握手响应的 `instructions` 说明每个工具的用途和调用时机。支持这个字段的客户端会把它传给模型。 - 每个工具都带 `title` 和 `annotations`(`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`)。支持这些提示的客户端可以自动放行只读工具,并在 `mira.memory.forget` 和 `mira.files.delete` 这类工具之前请用户确认。 ## 协议版本 支持的协议版本、`initialize` 如何选定版本、`MCP-Protocol-Version` 请求头,以及参数不符合 `inputSchema` 时各版本的返回,见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#mcp-rpc)。握手响应中的服务名(`serverInfo.name`)为 `mirabase-developer`。 - `structuredContent` 与 `content` 文本中的 JSON 为同一对象。`outputSchema` 仅列出必有字段,结果中可能包含其他字段。哪些工具带 `outputSchema`,见 [工具](https://mirabase.io/zh/developers/api/mcp.md#tools)。 - [`GET /mcp`](https://mirabase.io/zh/developers/api/mcp.md#mcp-handshake) 返回的服务信息中,`protocol_versions` 按从新到旧的顺序列出支持的版本。 ## 工具 每个工具均通过 `/v2` 请求执行,因此权限、限流和错误与直接调用 API 完全相同。多数工具发起一次请求;`mira.memory.get` 默认连同来源一起读取,发起两次请求。 | 工具 | 作用 | 对应的请求 | | --- | --- | --- | | `mira.whoami` | 这个 Key 的身份和权限。调用被拒绝时先调用它 | [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) | | `mira.context` | 为任务获取一份按 token 预算组装的上下文包,并附带各来源的入选原因 | [`POST /v2/retrieval/context`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext) | | `mira.search` | 搜索指定范围,返回按相关度排序且带引用的段落 | [`POST /v2/retrieval/search`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-search) | | `mira.answer` | 根据已保存的内容回答问题,并标注引用 | [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) | | `mira.context.feedback` | 回报上下文包里实际用到了哪几条 | [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-contextfeedback) | | `mira.files.list` | 列目录 | [`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/zh/developers/api/tree.md#tree-list) | | `mira.files.read` | 按路径读文件,正文按窗口返回 | [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-read) | | `mira.entries.read` | 按 id 读一个 Entry 的内容,包括没有路径的内容 | [`GET /v2/entries/{entry_id}/content`](https://mirabase.io/zh/developers/api/entries.md#entries-content) | | `mira.files.write` | 新建或整体替换一个文件 | [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write) | | `mira.files.edit` | 按原文精确替换文件里的文字 | [`PATCH /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-patch) | | `mira.files.delete` | 把文件移入废纸篓 | [`DELETE /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-delete) | | `mira.trash.list` | 列出一个 Space 废纸篓里的 Entry | [`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list) | | `mira.trash.restore` | 把废纸篓里的一个 Entry 恢复到原路径 | [`POST /v2/entries/{entry_id}/restore`](https://mirabase.io/zh/developers/api/entries.md#entries-restore) | | `mira.activity` | 近期由谁做了哪些修改,按主体和文件汇总 | [`GET /v2/spaces/{space_id}/activity`](https://mirabase.io/zh/developers/api/changes.md#changes-activity) | | `mira.conversation.ingest` | 保存一段对话,由服务从中提炼记忆 | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) | | `mira.text.ingest` | 把一段文本保存为一个没有路径的 Entry | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) | | `mira.url.ingest` | 抓取一个公开网页,把可读正文保存为一个 Entry | [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/zh/developers/api/ingest.md#ingest-ingest) | | `mira.memory.remember` | 以陈述形式写入一条记忆 | [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) | | `mira.memory.list` | 列出记忆,可按范围、状态、类别和字面内容筛选 | [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) | | `mira.memory.forget` | 按 id 遗忘一条记忆 | [`DELETE /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-forget) | | `mira.memory.correct` | 用更正后的陈述替换一条记忆 | [`POST /v2/memories/{memory_id}/correct`](https://mirabase.io/zh/developers/api/memories.md#memories-correct) | | `mira.memory.review` | 确认或拒绝一条待审核的记忆 | [`POST /v2/memories/{memory_id}/review`](https://mirabase.io/zh/developers/api/memories.md#memories-review) | | `mira.memory.get` | 按 id 读取一条记忆及其来源。仅在开启离线整理的部署上提供 | [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) | - `/v2` 请求失败时,工具调用返回一个带 `isError: true` 的结果:`content` 的文本给出错误码、能否重试和下一步,`_meta["dev.mirabase/error"]` 是完整的错误信封,包括 `code` 和 `remediation.action`,见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)。失败的结果不带 `structuredContent`。Key 缺少工具需要的能力时同样如此,错误码为 `forbidden`。参数不符合工具定义时的返回取决于协议版本,见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#mcp-rpc)。 - 一次工具调用计入限流的请求数是 `/mcp` 这一次,加上它发出的 `/v2` 请求数,所以通常是两次。 - `mira.memory.remember` 的 `agent` 范围是该 Agent 自己的私有记忆,须使用 Agent 的 Key。 ## 工具参数 工具的参数是 `tools/call` 中 `arguments` 的字段。每个工具的参数、类型、取值范围和是否必填,见 [API 参考](https://mirabase.io/zh/developers/api/mcp.md#tools);`tools/list` 返回的 `inputSchema` 是同一份定义。 ## 推荐的调用顺序 - 任务开始时调用 `mira.context`:服务按固定规则选择来源并分配预算,`route` 说明每个选择。已知要查找的内容时使用 `mira.search`。用完之后用 `mira.context.feedback` 回报实际用到的条目。 - 用户要的是答案本身时用 `mira.answer`;要为自己的推理收集材料时用 `mira.context`。 - 与他人共用一个 Space 时,开始前先调用 `mira.activity`,避免修改同一个文件。 - 调用 `mira.files.write` 和 `mira.files.edit` 时传入 `session_id`,以便将文件的每个版本追溯到修改它的对话,见 [文件与版本](https://mirabase.io/zh/developers/files.md#versions)。 - 对话告一段落时用 `mira.conversation.ingest` 保存,同一段对话的每一批用同一个 `session_id`。只有一句明确的结论要记时,用 `mira.memory.remember`。 - 用户给出一段要保存的文本或一个链接时,用 `mira.text.ingest` 或 `mira.url.ingest`。以后要按路径读取或修改的内容,用 `mira.files.write` 写成文件。 - 用户指出一条记忆有误并给出正确陈述时,用 `mira.memory.correct` 一步替换,旧的那条作为历史保留。`mira.memory.forget` 永久删除、不能撤销,只在用户要求遗忘时调用。`mira.memory.review` 只在用户说明候选记忆是否正确之后调用,Agent 不应自行判断并确认。 - 要恢复已删除的文件,先用 `mira.trash.list` 找到 id,再用 `mira.trash.restore` 恢复到原路径。原路径已被其他文件占用时返回 `path_conflict`。 ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mira.conversation.ingest", "arguments": { "session_id": "chat-42", "messages": [ { "role": "user", "content": "Let us ship on Thursdays from now on." }, { "role": "assistant", "content": "Noted: releases on Thursdays." } ] } } } ``` > **说明:** 从文件和检索结果中读取的文本是数据,不是指令。让 Agent 仅将你的输入作为指令。 ## 下一步 - [权限](https://mirabase.io/zh/developers/permissions.md):配置 Agent 的写入模式、读取根路径和写入根路径。 - [分支](https://mirabase.io/zh/developers/branches.md):让 Agent 在分支上工作,合并前可以审查。 - [记忆](https://mirabase.io/zh/developers/memory.md):审核 Agent 记录的记忆。 --- # 框架集成(即将上线) 在 Vercel AI SDK、LangChain、LlamaIndex、OpenAI Agents SDK、Mastra 和 CrewAI 中使用 Mirabase 的工具、记忆和检索。 > **注意:** 以下集成包尚未发布,包名在发布前可能调整,发布时本页会给出安装命令。在此之前,请直接使用 [SDK](https://mirabase.io/zh/developers/sdks.md) 或 [MCP](https://mirabase.io/zh/developers/agents.md)。 每个集成均提供相同的五个工具:`mirabase_search`、`mirabase_answer`、`mirabase_read_file`、`mirabase_write_file` 和 `mirabase_list_files`。引用附带文件路径和版本。将通过 `spaceFor(userId)`(Python 为 `space_for`)固定到某个 Space 的客户端传入集成,即可为每个最终用户使用独立的 Space。各集成基于 SDK 0.3.0-rc.1(Python 为 0.3.0rc1)。 - `mirabase_list_files` 以 `size_bytes` 返回文件大小,TypeScript 与 Python 一致。响应带 `pending_processing` 时,`mirabase_search` 将其一并交给模型。 - 基于对话的消息历史和 Session 默认读取最近 20 个批次,可用 `maxBatches`(Python 为 `max_batches`)调整。 - `mirabaseAnswerModel` 发送最近 10 轮对话,每轮保留开头的 4,000 个字符;超过 4,000 个字符的问题保留末尾部分,并在该次调用中给出警告。检索器和工具对超长的查询、任务或问题同样保留末尾部分。 | 框架 | 语言 | 包名(未发布) | 提供的组件 | 测试版本 | | --- | --- | --- | --- | --- | | Vercel AI SDK | TypeScript | `@mirabase/vercel-ai` | 工具、记忆中间件、封装 Mirabase 带引用回答的模型 | `ai` 7.0.173 | | LangChain.js | TypeScript | `@mirabase/langchain` | 检索器、基于对话的消息历史、文档加载器、工具 | `@langchain/core` 1.4.1 | | LangChain | Python | `mirabase-langchain` | 检索器、基于对话的消息历史、文档加载器、工具 | `langchain-core` 1.8.1 | | LlamaIndex | Python | `mirabase-llamaindex` | 检索器、带引用的查询引擎、读取器 | `llama-index-core` 0.14.26 | | OpenAI Agents SDK | TypeScript | `@mirabase/openai-agents` | 工具、基于对话的 Session | `@openai/agents` 0.22.0 | | OpenAI Agents SDK | Python | `mirabase-openai-agents` | 工具、基于对话的 Session | `openai-agents` 0.24.0 | | Mastra | TypeScript | `@mirabase/mastra` | 工具、记忆处理器 | `@mastra/core` 1.83.0 | | CrewAI | Python | `mirabase-crewai` | 工具、在 Mirabase 中检索的 Knowledge | `crewai` 1.15.41 | > **说明:** 示例中的 `model` 指你在该框架中使用的模型。 ## Vercel AI SDK `mirabaseTools` 提供五个工具;`mirabaseMemory` 是模型中间件,在调用模型前用最后一条用户消息构建上下文,调用后将本轮对话存为 Mirabase 对话,供服务提炼记忆。在未配置自有模型时,可使用 `mirabaseAnswerModel`,将 Mirabase 的带引用回答作为模型调用。 ```ts import { Mirabase } from "@mirabase/sdk/developer"; import { mirabaseMemory, mirabaseTools } from "@mirabase/vercel-ai"; import { generateText, stepCountIs, wrapLanguageModel } from "ai"; const mb = await new Mirabase().spaceFor("user-42"); // one Space per end user const { text } = await generateText({ model: wrapLanguageModel({ model, middleware: mirabaseMemory({ client: mb, sessionId: "chat-1" }) }), tools: mirabaseTools({ client: mb }), stopWhen: stepCountIs(5), prompt: "What did we decide about the launch?", }); ``` ## LangChain `MirabaseRetriever` 返回带引用的文档,`metadata` 中包含路径、版本和引用 id;`MirabaseChatMessageHistory` 将消息历史存为 Mirabase 对话。此外还提供文档加载器和工具。 TypeScript: ```ts import { Mirabase } from "@mirabase/sdk/developer"; import { MirabaseChatMessageHistory, MirabaseRetriever } from "@mirabase/langchain"; const mb = new Mirabase(); const docs = await new MirabaseRetriever({ client: mb, k: 5 }).invoke("When do we ship?"); console.log(docs[0]?.metadata.path, docs[0]?.metadata.citation_id); const history = new MirabaseChatMessageHistory({ client: await mb.spaceFor("user-42"), sessionId: "chat-1" }); ``` Python: ```python from mirabase import Mirabase from mirabase_langchain import MirabaseChatMessageHistory, MirabaseRetriever mb = Mirabase() docs = MirabaseRetriever(client=mb, k=5).invoke("When do we ship?") print(docs[0].metadata["path"], docs[0].metadata["citation_id"]) history = MirabaseChatMessageHistory(mb.space_for("user-42"), "chat-1") ``` ## LlamaIndex `MirabaseQueryEngine` 调用 Mirabase 的回答接口作答,无需自备模型,`source_nodes` 为被引用的片段;`MirabaseRetriever` 则可接入 LlamaIndex 的查询引擎,由你自己的模型作答。 ```python from mirabase import Mirabase from mirabase_llamaindex import MirabaseQueryEngine, MirabaseRetriever mb = Mirabase() response = MirabaseQueryEngine(client=mb).query("When do we ship?") print(response, [n.node.metadata["path"] for n in response.source_nodes]) nodes = MirabaseRetriever(mb, similarity_top_k=5).retrieve("launch owner") ``` ## OpenAI Agents SDK `mirabaseTools`(Python 为 `mirabase_tools`)提供启用严格模式的五个工具;`MirabaseSession` 将每一轮对话存为 Mirabase 对话。 TypeScript: ```ts import { Agent, run } from "@openai/agents"; import { Mirabase } from "@mirabase/sdk/developer"; import { MirabaseSession, mirabaseTools } from "@mirabase/openai-agents"; const mb = await new Mirabase().spaceFor("user-42"); const assistant = new Agent({ name: "Assistant", instructions: "Answer from the user's files.", tools: mirabaseTools({ client: mb }) }); const session = new MirabaseSession({ client: mb, sessionId: "chat-1" }); const result = await run(assistant, "What did we decide about the launch?", { session }); ``` Python: ```python from agents import Agent, Runner from mirabase import Mirabase from mirabase_openai_agents import MirabaseSession, mirabase_tools mb = Mirabase().space_for("user-42") assistant = Agent(name="Assistant", instructions="Answer from the user's files.", tools=mirabase_tools(mb)) result = Runner.run_sync(assistant, "What did we decide?", session=MirabaseSession(mb, "chat-1")) ``` ## Mastra `mirabaseMemory` 是一个处理器:在输入阶段注入 Mirabase 构建的上下文,在输出阶段将本轮对话存为 Mirabase 对话。它可以与 Mastra 自身的线程记忆同时使用。 ```ts import { Agent } from "@mastra/core/agent"; import { Mirabase } from "@mirabase/sdk/developer"; import { mirabaseMemory, mirabaseTools } from "@mirabase/mastra"; const mb = await new Mirabase().spaceFor("user-42"); const memory = mirabaseMemory({ client: mb, sessionId: "chat-1" }); const assistant = new Agent({ id: "assistant", name: "Assistant", instructions: "Be brief.", model, tools: mirabaseTools({ client: mb }), inputProcessors: [memory], outputProcessors: [memory] }); const { text } = await assistant.generate("What should I cook tonight?"); ``` ## CrewAI `mirabase_knowledge` 是通过 Mirabase 进行检索的 CrewAI `Knowledge` 数据源,无需本地向量库或向量模型的 API Key;`mirabase_tools` 提供五个工具。 ```python from crewai import Agent, Crew, Task from mirabase import Mirabase from mirabase_crewai import mirabase_knowledge, mirabase_tools mb = Mirabase() planner = Agent( role="Planner", goal="Answer from the team's notes", backstory="Knows the release plan.", tools=mirabase_tools(mb, read_only=True), knowledge=mirabase_knowledge(mb, path="/notes"), ) task = Task(description="When do we ship, and who owns it?", expected_output="A day and a name", agent=planner) print(Crew(agents=[planner], tasks=[task]).kickoff()) ``` ## 下一步 - [SDK](https://mirabase.io/zh/developers/sdks.md):集成所基于的客户端。 - [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md):不使用框架时,通过 MCP 接入同样的工具。 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):集成调用的检索接口。 --- # 分支与挂载 面向 Agent 的写时复制工作区、FUSE 挂载、同步命令和 Git 工作区。 ## 使用分支 分支是叠在 Space 主线上的一层写时复制覆盖层,是 Agent 的工作区。分支里的内容**不解析、不进索引、不提炼记忆**,合并进主线才走正常处理,所以失败的试验不会污染知识和记忆。 ```bash # Open a branch. Keep its id (brn_...). curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "try-new-outline"}' # Write to it. Main does not change. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md&branch=$BRANCH_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: text/markdown" \ --data-binary @hello.md # See what changed. curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Merge into main. Idempotency-Key is required here. curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: merge-try-new-outline" \ -H "Content-Type: application/json" \ -d '{"message": "New outline", "on_conflict": "abort"}' ``` [`POST /v2/spaces/{space_id}/branches`](https://mirabase.io/zh/developers/api/branches.md#branches-create) 创建分支,[`GET /v2/spaces/{space_id}/branches/{branch_id}/diff`](https://mirabase.io/zh/developers/api/branches.md#branches-diff) 查看路径级改动,[`POST /v2/spaces/{space_id}/branches/{branch_id}/merge`](https://mirabase.io/zh/developers/api/branches.md#branches-merge) 合并进主线,[`DELETE /v2/spaces/{space_id}/branches/{branch_id}`](https://mirabase.io/zh/developers/api/branches.md#branches-abandon) 放弃分支。 - 会重试的调用里请用分支 id(以 `brn_` 开头),不要用名字:分支关闭后,名字可能指向另一个分支。 - 创建分支只需 Space 写权限,`write_mode` 在合并时才检查,所以 `proposal` 模式的 Agent 也能自由试验。 - 在这个 Space 有 `read_root` 的成员不能使用分支,见 [权限](https://mirabase.io/zh/developers/permissions.md#roots)。 ## 在分支上读写 `files`、`files/batch`、`tree`、`tree/operations`、`uploads` 和 `changes` 接受可选的 `branch` 参数。不带时作用于主线。 - 分支读取先查覆盖层,未命中再穿透到主线最新内容。未被分支修改过的路径读到的是主线当前的内容,不是创建分支时的内容。 - 写入分支不产生版本,合并之前也不计 `writes`。响应里的 `etag` 是内容哈希,可以放回 `If-Match`。 - 分支上的 `DELETE` 只在这个分支隐藏文件,主线不变。要撤销分支上的改动,请回滚到检查点。 - 符号链接和权限位(`symlink`、`chmod`、`mode`)只在分支上可用,主线没有符号链接。 - `changes?branch=` 是分支自己的变更流,游标从 `tree?branch=` 获取,与主线的游标不通用。`source: branch` 的事件每个路径只留最新一次,当作要重读的路径处理。 - `search` 和 `context` 不接受 `branch`:分支内容在合并之前检索不到。 ## 创建检查点和回滚 检查点记录分支某一时刻自身的改动。穿透到主线的路径不会被固定。回滚之后,后续的检查点仍保留,因此回滚可以撤销;用比回滚点旧的 `changes` 游标请求时,接口返回 410,需从 `tree?branch=` 重新读取。 ```bash curl -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": "before-refactor"}' curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/rollback" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"checkpoint_id": "'$CHECKPOINT_ID'"}' ``` ## 合并分支 合并必须带 `Idempotency-Key`。全部路径一起生效或一起不生效,每个路径在主线上产生一个带 `message` 的新版本。 - 每个路径与分支首次修改它时主线上的版本比较,主线之后又修改过即视为冲突。默认整次合并失败,返回 409 `merge_conflict`,`error.conflicts` 列出每条冲突;`on_conflict` 可以改为保留主线或覆盖主线。不做内容合并。 - 带 `paths` 时只合并这些路径,分支保持 `active`;不带时分支变为 `merged`,之后不能再写入。 - Agent 合并不属于自己的文件需要 `write_mode: direct`。带 `Prefer: handling=proposal` 时,它对这类文件的修改变为提案,见 [提案](https://mirabase.io/zh/developers/files.md#proposals)。 ## 以任务方式合并 超过同步上限的合并带 `Prefer: respond-async` 时作为任务执行,返回 202 和 `job_id`,进度通过 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read) 查询,见 [任务](https://mirabase.io/zh/developers/conventions.md#jobs)。 curl: ```bash # Over 1000 paths: run the merge as a job instead of 409 merge_too_large. curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: merge-big-refactor" \ -H "Prefer: respond-async" \ -H "Content-Type: application/json" \ -d '{"message": "Big refactor", "on_conflict": "abort"}' ``` TypeScript: ```ts const merged = await mirabase.branches.startMerge(branchId, { message: "Big refactor", on_conflict: "abort" }); if ("job_id" in merged) { const job = await mirabase.jobs.get(merged.job_id); // job.result?.merged counts paths; a failed plan lists job.result?.conflicts. } ``` Python: ```python # branch_id is the branch to merge: the id mb.branches.create returned. merged = mb.branches.start_merge(branch_id, {"message": "Big refactor", "on_conflict": "abort"}) if "job_id" in merged: job = mb.jobs.get(merged["job_id"]) # job["result"]["merged"] counts paths; a failed plan lists job["result"]["conflicts"]. ``` - 任务先规划全部路径:有冲突时直接失败,不写入任何内容。 - 之后分批合并,不是原子的。中途出现的冲突会使任务停止,已合并的路径已经离开分支:再合并一次以处理剩余路径。 - 任务排队或运行期间,这个分支不能再合并或写入文件;改名、创建检查点和放弃仍可用,放弃会使任务停止。 ## 有效期和回收 每次写入将 `expires_at` 向后推迟 `ttl_days` 天,`ttl_days` 可以在创建时或用 [`PATCH /v2/spaces/{space_id}/branches/{branch_id}`](https://mirabase.io/zh/developers/api/branches.md#branches-update) 设置。一直没有写入的分支过期,变为 `abandoned`。分支放弃、过期或合并之后再保留 `branch_reclaim_days` 天,然后回收。分支空间计入 `storage_bytes`。各项默认值见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)。 ## 存储分支对象 [`PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}`](https://mirabase.io/zh/developers/api/branches.md#branches-putobject) 存储一个按哈希命名的不透明对象,用于存放 Git bundle 和 overlay。对象不是路径,不出现在 `tree` 和 `changes` 中,不合并、不解析、不索引,计入 `storage_bytes`。分支已合并或已放弃时,对象在回收之前仍可读取。 > **注意:** 分支对象中的内容(包括 Git bundle)在分支回收之前无法彻底删除。`purge` 只作用于主线的 Entry。要尽快移除这些内容,请放弃分支,等待 `branch_reclaim_days` 天后回收。 > **即将上线** ## CLI 和挂载(即将上线) `mirabase` CLI 是无运行时依赖的单文件程序,适合放入沙箱,全部调用公开 API。它读取 `MIRABASE_API_KEY`(必填)、`MIRABASE_API_URL` 和 `MIRABASE_SPACE`。挂载写入分支,不写入主线:编辑器一次保存会产生多次写入和改名。 > **说明:** CLI 尚未发布,以下命令目前无法安装。分支功能本身已经上线,上文各节的接口均可直接调用。 ```bash export MIRABASE_API_KEY="mb_live_..." # Stays in the foreground and prints the branch it opened. mirabase mount ./workspace --space "$SPACE_ID" # In another shell: grep -rn "TODO" ./workspace sed -i 's/one place/a single place/' ./workspace/notes/hello.md mirabase drain ./workspace mirabase branch diff "$BRANCH_ID" --space "$SPACE_ID" mirabase branch merge "$BRANCH_ID" --message "Wording" --space "$SPACE_ID" ``` | 命令 | 作用 | | --- | --- | | `mirabase mount --space s [--branch b] [--read-only]` | FUSE 挂载,未传 `--branch` 时自动创建分支 | | `mirabase sync --space s [--branch b] [--once]` | 用于无 FUSE 的沙箱环境:拉取、监听本地改动并推送 | | `mirabase drain [dir] [--timeout 5m] [--ack]` | 阻塞至本地写入全部上传;退出码 0 表示全部上传,1 表示有写入被放弃或认证失败,2 表示超时,3 表示自己的写入被其他机器覆盖 | | `mirabase branch ` | `create`、`list`、`get`、`rename`、`extend`、`diff`、`checkpoint`、`checkpoints`、`rollback`、`merge`、`abandon` | | `mirabase git save\|restore\|worktree` | Git 工作区,见下一节 | - 一致性为 close-to-open:其他机器在下次打开时看到新内容。`fsync` 只保证写入本地磁盘,跨机器可见性以 `drain` 为准。 - 同一路径并发写时后写覆盖。 - 支持改名、mkdir、unlink、truncate、可执行位和符号链接,不支持硬链接、设备文件和文件锁。 - `.mirabase/memory/MEMORY.md` 在挂载目录里只读,写入返回 `EROFS`。 - 默认不上传 `.git/`、`node_modules/`、`.venv/`、`__pycache__/` 和 `.DS_Store`,只留在本地。可以用 `.mirabaseignore`(gitignore 语法)调整。 - Linux 下挂载需要 `/dev/fuse`(在容器中还需要 `SYS_ADMIN`);不具备时请使用 `mirabase sync`。macOS 下需先安装 macFUSE 或 FUSE-T。 ## Git 工作区(即将上线) `mirabase git save` 将提交打包为 bundle(首次之后仅打包增量),将未提交和未跟踪的改动存为 overlay,再创建一个检查点,`git` 字段记录 `HEAD`、ref 和移除凭据后的远端地址。`mirabase git restore ` 在全新环境中恢复并校验 `HEAD` 和工作区。`mirabase git worktree --ref r` 恢复后用 `git worktree` 打开另一个 ref。 ```bash # In a Git repository: bundle commits, store uncommitted changes, create a checkpoint. # Without --branch it opens one and remembers it in .git/mirabase-branch. mirabase git save --space "$SPACE_ID" --name "before-upgrade" # Somewhere else: restore and verify HEAD and the working tree. mirabase git restore "$CHECKPOINT_ID" ./repo --space "$SPACE_ID" ``` - bundle 和 overlay 存为分支对象,不会发送给模型提供方。 - 暂存区状态不单独保存,恢复后全部是未暂存改动。 - `.gitignore` 忽略的文件和 `.env` 默认不保存。需要时显式传 `--include-ignored`。 - 保存的内容在分支回收之前无法彻底删除,见 [分支对象](https://mirabase.io/zh/developers/branches.md#objects)。 ## 下一步 - [同步、快照与导出](https://mirabase.io/zh/developers/sync.md#snapshots):只要一个只读的固定点时用快照。 - [权限](https://mirabase.io/zh/developers/permissions.md):谁能合并,Agent 的改动什么时候变成提案。 - [API 约定](https://mirabase.io/zh/developers/conventions.md#idempotency):合并必须带幂等键。 --- # 权限 主体、能力、Space 角色、读写根路径和 API Key 的限制如何共同决定一次请求。 ## 请求的判定 一次请求必须同时满足以下条件,任一条件不满足即被拒绝: ```text allowed = capability in (principal.capabilities ∩ key.capabilities) and space in key.allowed_space_ids (when set) and the Space role is sufficient and the path is under the member's read_root / write_root (when set) ``` ## 主体 | 类型 | 说明 | | --- | --- | | 人 | `kind: human`,可以具备 `tenant_admin` 角色 | | Agent | `kind: agent`,有自己的权限、记忆和审计身份 | | API Key | 凭据,不是主体,只能收窄所属主体 | 主体没有显示名,请自行按 `id` 记录名称。[`POST /v2/principals`](https://mirabase.io/zh/developers/api/principals.md#principals-create) 只能创建 `human` 和 `agent`,`tenant_admin` 角色不能通过 API 授予。 ## 能力 能力是对一类操作的许可,例如 `knowledge:read`、`knowledge:write`、`knowledge:manage`、`knowledge:answer` 和 `memory:confirm`。一个 API Key 的有效能力是主体能力和 Key 能力的交集。[`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 的 `effective_capabilities` 给出这个交集。 每种能力允许的操作见参考页的 [DevCapability](https://mirabase.io/zh/developers/api/schemas.md#DevCapability);每个操作需要的能力写在参考页该操作的条目里。 ## Space 角色 成员在每个 Space 中有一个角色:`owner`、`editor` 或 `viewer`。一次操作既要求能力,也要求最低角色。各角色可执行的操作见 [DevSpaceRole](https://mirabase.io/zh/developers/api/schemas.md#DevSpaceRole);每个操作需要的能力和更严格的规则,见 [API 参考](https://mirabase.io/zh/developers/api.md) 中该操作的说明。 Space 所有者用 [`PUT /v2/spaces/{space_id}/members/{principal_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember) 设置成员的角色、`write_mode`、`write_root` 和 `read_root`。 ## Agent 的写入模式 `write_mode` 只对 Agent 生效,且只针对不属于它的文件。新成员默认为 `proposal`:修改他人的文件返回 403 `proposal_required`,移动和删除也一样,不会创建任何内容。设为 `direct` 后可以直接写入。Space 所有者始终是 `direct`。 `proposal` 模式的 Agent 可以带 `Prefer: handling=proposal` 把这类写入变成提案,由审核人批准,见 [提案](https://mirabase.io/zh/developers/files.md#proposals)。 ## 写入根路径和读取根路径 Space 所有者可以在设置成员时把它限制在一棵子树内。两种根路径都只会收窄:角色、能力和 API Key 的限制照常生效,没有拒绝规则。取值规则见 [write_root](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember.body.write_root) 和 [read_root](https://mirabase.io/zh/developers/api/spaces.md#spaces-setmember.body.read_root)。 curl: ```bash # The Agent reads /projects/acme and writes only under /projects/acme/drafts. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"role": "editor", "write_mode": "direct", "read_root": "/projects/acme", "write_root": "/projects/acme/drafts"}' ``` TypeScript: ```ts await mirabase.spaces.members.set(agentId, { role: "editor", write_mode: "direct", read_root: "/projects/acme", write_root: "/projects/acme/drafts", }); ``` Python: ```python # agent_id is the Agent's principal id. It reads /projects/acme and writes only under /projects/acme/drafts. mb.spaces.members.set(agent_id, { "role": "editor", "write_mode": "direct", "read_root": "/projects/acme", "write_root": "/projects/acme/drafts", }) ``` | 根路径 | 范围内 | 范围外 | | --- | --- | --- | | `write_root` | 在该目录下写入,不能重命名、移动或删除目录本身 | 403 `outside_write_root`,读取不受影响 | | `read_root` | 读取该目录及其下所有内容;没有 `write_root` 时也在此写入 | 404,与不存在相同;检索、上下文、记忆和变更流都不包含范围外的内容 | - 没有路径的 Entry(`ingest`、项目记忆、提炼的事实)在两种范围之外,成员自己的 Agent 记忆除外。 - 读取根路径和写入根路径在目录重命名或移动后仍然有效。删除某个成员的读取根路径或写入根路径,或包含这些路径的目录时,服务返回 409 `directory_is_write_root` 或 `directory_is_read_root`,Space 所有者执行此操作时也是如此。 - `write_root` 不限制分支;合并写入主线时逐个路径检查,全部通过或全部不生效。 - [`GET /v2/spaces`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 和 [`GET /v2/spaces/{space_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-read) 返回你自己的 `read_root` 和 `write_root`,从那里开始读 `tree`。 ## 为 Agent 配置权限 为 Agent 创建独立的主体,不要共用人的 API Key。这样它的写入、记忆和审计都有自己的身份,吊销时不影响他人。 ```bash # 1. Create the Agent. Without grant_capabilities it gets knowledge:read. curl -X POST https://api.mirabase.dev/v2/principals \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"kind": "agent", "grant_capabilities": ["knowledge:read", "knowledge:write"]}' # 2. Make it a member of one Space. write_mode direct lets it change files it does not own. curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"role": "editor", "write_mode": "direct"}' # 3. Issue its key, narrowed to that Space. curl -X POST https://api.mirabase.dev/v2/api-keys \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"actor_id": "'$AGENT_ID'", "name": "docs-agent", "grant_capabilities": ["knowledge:read", "knowledge:write"], "allowed_space_ids": ["'$SPACE_ID'"]}' ``` ## 按 Space 限定 API Key - 访问收窄范围外的 Space 时,服务返回 404,与 Space 不存在时的响应相同。 - 受范围限制的 API Key 不能访问账户级和租户级功能:账户记忆、[`GET /v2/principals`](https://mirabase.io/zh/developers/api/principals.md#principals-list)、[`GET /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-list)、[`GET /v2/audit/events`](https://mirabase.io/zh/developers/api/audit.md#audit-events)。 - 比所属主体窄的 Key 只能为该主体签发 Key,因此切换身份也无法绕过限制。 ## 不可见即不存在 看不见的资源和不存在的资源返回同一个 404。收到 403 时查看 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami),收到 404 时检查 id、Key 的 Space 范围和成员关系。 ## 审计 [`GET /v2/audit/events`](https://mirabase.io/zh/developers/api/audit.md#audit-events) 返回治理和访问事件。事件只含标识符,不含用户内容。治理动作与它所做的修改在同一事务里记录,失败时一起回滚。 > **说明:** 权限变更在下一条语句立即生效,API Key 吊销也是如此,没有缓存窗口。 ## 下一步 - [认证与 API Key](https://mirabase.io/zh/developers/authentication.md):创建、轮换和吊销 Key。 - [文件与版本](https://mirabase.io/zh/developers/files.md#proposals):提案的提交和审核。 - [错误码](https://mirabase.io/zh/developers/errors.md#codes):403 的各个错误码分别表示什么。 --- # API 约定 所有接口共用的规则:请求与响应、请求 id、版本、分页、幂等、条件请求、任务、错误、重试和限流。 ## 请求与响应 | 项目 | 约定 | | --- | --- | | 地址 | `https://api.mirabase.dev`,接口都在 `/v2` 下 | | 认证 | `Authorization: Bearer `,见 [认证](https://mirabase.io/zh/developers/authentication.md) | | 请求体 | UTF-8 的 JSON,`Content-Type: application/json`。文件内容除外,按文件本身的类型发送原始字节 | | 字段名 | 小写加下划线,如 `next_cursor` | | 时间 | RFC 3339,响应一律为 UTC,如 `2026-11-06T08:30:00.000Z`。请求中的时间需带时区偏移 | | id | 不透明字符串。原样保存和传回,不要解析,也不要依赖前缀 | | 校验 | 严格。未知字段或查询参数返回 422 `validation_error`,由 `field` 指明字段名 | | 错误 | 所有错误结构相同,见下文 [错误](https://mirabase.io/zh/developers/conventions.md#errors) | ## 请求 id 每个响应都带 `X-Request-Id`,错误体中的 `request_id` 与之相同。联系支持时请提供该值。你也可以在请求中传入 `X-Request-Id`,服务会原样沿用;若格式无效,则替换为服务生成的值。 ## 版本 - 大版本在路径里:`/v2`。 - 每个响应都带 `Mirabase-Contract-Version`,当前为 `1.0`。请求无需携带该请求头;若传入服务不支持的值,返回 400 `unsupported_contract_version`,移除该请求头即可。 - 新增接口、可选参数和响应字段不会升级版本号,因此客户端应忽略未知的响应字段。 - 标有“即将上线”的接口尚未提供,上线前可能调整;标有“需要部署开启”的接口为可选功能。两者均在 [API 参考](https://mirabase.io/zh/developers/api.md) 中标明。 - 机器可读的契约是 OpenAPI 文档。它的地址和这份文档对应的规格版本都在 [API 概览](https://mirabase.io/zh/developers/api.md)。 ## 行为变更 最近一次更新改变了下列已有行为。新增的参数和字段不在此列,见各指南页和 [API 参考](https://mirabase.io/zh/developers/api.md)。 - [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) 不传 `weights` 时不再使用 `changes` 和 `skills` 两个来源。找不到相关证据的问题返回 `abstained`,`reason` 为 `no_evidence`。要恢复原来的行为,请传 `weights`,见 [带引用回答](https://mirabase.io/zh/developers/retrieval.md#answer)。 - 每个主体同时运行的回答从 1 个改为 3 个。 - 429 `rate_limited` 的错误信封多了一个 `limit`。并发限制的 429 不再带 `RateLimit-*` 响应头,见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)。 - [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) 写入与现行记忆相同的 `project` 或 `agent` 记忆时,返回 200 和已有的那条记忆,不再新建一条并返回 201。 - 处理完成前读取 `view=table`,现在返回 404 `content_not_ready`,不再返回 404 `not_found`。 - MCP 的 `tools/list` 多了 8 个工具;带元数据范围的 Key 只看到它能调用的工具,见 [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md#tools)。 - MCP 工具调用成功时,结果的 JSON 位于 `content` 的文本中;仅当协商的协议版本为 `2025-06-18` 或更高版本时,九个只读工具的结果才会在 `structuredContent` 中另含同一对象,见 [协议版本](https://mirabase.io/zh/developers/agents.md#protocol-versions)。Key 缺少工具所需能力时,返回含 `isError: true` 的工具结果(错误码 `forbidden`),不再返回 JSON-RPC 错误 `-32003`。 - 失败的 MCP 工具结果不再带 `structuredContent`,各协议版本都是如此:错误说明在 `content` 的文本中,错误信封在 `_meta["dev.mirabase/error"]` 中。见 [工具](https://mirabase.io/zh/developers/agents.md#tools)。 - [`GET /v2/openapi.yaml`](https://mirabase.io/zh/developers/api/discovery.md#discovery-openapi) 只描述 API Key 能调用的操作,并带有示例;控制台、运营方和尚未上线的操作不再出现在其中。它的 `ETag` 随之改变。 - `stated_date` 不再取句子中间提到的日期,仅取带“截至”“as of”等标记的日期、小节标题中的日期、行首或分句开头的日期,以及文档开头的日期,见 [检索](https://mirabase.io/zh/developers/retrieval.md#search)。 - 表格汇总只在完整理解问题时才计算,命中表格的旧版本时也不计算;此前会计算的部分问题现在返回 `table_aggregate:not_computed:`,见 [上下文](https://mirabase.io/zh/developers/retrieval.md#context)。 - 问题询问当前状态时,从新到旧的排序只作用于关于同一事物的证据:同一个 Entry、多次保存的同一个网页,或 `metadata.subject_key` 取值相同的几个 Entry。路径或标题相似、位于同一文件夹都不算同一事物。分数相近但主题不同的证据不再因日期较新而排在前面,见 [带引用回答](https://mirabase.io/zh/developers/retrieval.md#answer)。 - MCP 的 `initialize` 现按客户端请求的协议版本响应(支持 `2024-11-05` 至 `2025-11-25` 的四个版本),不再固定返回 `2024-11-05`;服务名改为 `mirabase-developer`。见 [协议版本](https://mirabase.io/zh/developers/agents.md#protocol-versions)。 - 当部署不提炼记忆或 Entry 带有 `memory_exclude` 时,对话的 `memory.state` 初始即为 `skipped`,并在 `reason` 中说明原因,不再先显示为 `pending`。见 [跳过提炼的原因](https://mirabase.io/zh/developers/memory.md#skip-reasons)。 - 已经提炼完成的版本,在部署关闭提炼或移除模型后仍为 `ready`,不再变为 `skipped`。`distill_disabled`、`model_not_configured` 和 `distill_paused` 只对属于 `tenant_admin` 或持有 `knowledge:manage`、且未收窄的 Key 显示,其他 Key 看到的是 `distill_unavailable`(替代前两个);`distill_paused` 不返回原因,状态仍为 `pending`。见 [提炼被跳过的原因](https://mirabase.io/zh/developers/memory.md#skip-reasons)。 - 在有团队的账户中,Admin 不能再为他人创建的 Agent 或最终用户签发 Key,也不能再吊销 Owner 或其他 Admin 的 Key。见 [用 API 创建](https://mirabase.io/zh/developers/authentication.md#api)。 - 写入请求返回 429 `ingest_backlog` 时,`Retry-After` 为 30 到 600 秒,不再固定为 30 秒。`Retry-After` 超过 `maxRetryAfterMs`(Python 为 `max_retry_after`,默认 60 秒)时,SDK 不自动重试,直接抛出 `MirabaseRateLimitError`。见 [处理队列已满时](https://mirabase.io/zh/developers/processing.md#backlog)。 - SDK 在创建客户端时校验 API Key:去除首尾的空白字符;Key 中含有换行、空格、控制字符或非 ASCII 字符时,抛出 `MirabaseConfigError`,代码为 `invalid_api_key`,不再等到发出请求时才报错。见 [处理错误](https://mirabase.io/zh/developers/sdks.md#errors)。 - 导入对话时带 `redact_secrets`,现对每条消息分别替换,标题单独替换;`secrets_redacted` 为消息和标题中实际替换的数量。跨两条消息的凭据不再作为一处识别。导入文本的行为不变。 - 检索结果的 `score`、排序和 `explain` 中的候选数,仅依据调用方可读取的内容计算。读取范围受限的调用方(例如设有 `read_root` 的成员)得到的 `score` 可能变化;候选内容全部可读取的调用方,结果不变。 - [`GET /v2/retrieval/traces/{trace_id}`](https://mirabase.io/zh/developers/api/request-logs.md#requestlogs-trace) 对本次更新之前记录的轨迹不再返回 `summary.candidates` 和 `summary.fused_count`。 - 账户待审批期间,控制台登录会话仅可管理 API Key、查看账户信息和只读列表;检索、重新处理、删除以及创建或修改 Space 等请求返回 403 `account_pending_approval`,此前 [`POST /v2/spaces`](https://mirabase.io/zh/developers/api/spaces.md#spaces-create) 返回 201。见 [在控制台创建 API Key](https://mirabase.io/zh/developers/authentication.md#console)。 - 未能发出的模型调用(在连接阶段失败)不再计入每月模型配额。模型调用因配额被拒绝时,429 `quota_exceeded` 的 `message` 不再包含本次调用所需的用量和账户的剩余额度,请通过 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 查看。 - 同一账户内,各 Space 的记忆提炼任务轮流执行,一个 Space 的积压不再延后其他 Space 的提炼;导入对话不再延后文本的记忆提炼。 ## 分页 列表返回 `{data, next_cursor}`。将 `next_cursor` 原样作为 `cursor` 传回以获取下一页;最后一页不含 `next_cursor`。游标为不透明字符串,不要解析或自行构造。 | 参数 | 说明 | | --- | --- | | `limit` | 每页条数,默认 20,最大 100 | | `cursor` | 上一页返回的 `next_cursor`。翻页时其他参数保持不变 | curl: ```bash # First page curl "https://api.mirabase.dev/v2/entries?limit=100" \ -H "Authorization: Bearer $MIRABASE_API_KEY" # Next page: pass next_cursor back as cursor. curl "https://api.mirabase.dev/v2/entries?limit=100&cursor=$NEXT_CURSOR" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` TypeScript: ```ts // Iterating fetches pages as needed. for await (const entry of mirabase.entries.list({ limit: 100 })) { console.log(entry.id); } ``` Python: ```python # Iterating fetches pages as needed. for entry in mb.entries.list(limit=100): print(entry["id"]) ``` 各列表的排序规则见 [API 参考](https://mirabase.io/zh/developers/api.md) 中对应接口的说明。变更流除外:返回 `{data, cursor, has_more}`,且始终包含 `cursor` 以便继续读取,见 [同步](https://mirabase.io/zh/developers/sync.md#loop)。检索不分页,通过 `limit` 控制返回条数。 ## 幂等 网络中断时,无法确认写入是否已生效。携带 `Idempotency-Key` 重发请求是安全的:幂等键、主体、API Key、操作和输入均相同时,服务在 24 小时内直接返回首次结果,不会重复执行。 | 项目 | 规则 | | --- | --- | | 格式 | 1 到 512 个可见 ASCII 字符,建议用 UUID。每个逻辑请求一个新键 | | 保留 | 24 小时 | | 同一个键、不同输入 | 返回 409 `conflict`,`remediation.action` 是 `use_new_idempotency_key` | | 作用范围 | 按 API Key 隔开:两个 Key 用同一个键互不影响 | ```bash curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Idempotency-Key: 7d3f4c0e-5b1a-4f6e-9c2d-1a2b3c4d5e6f" \ -H "Content-Type: application/json" \ -d '{"kind":"text","text":"The launch moved to March 14."}' ``` - 大多数 `POST`、`PUT`、`PATCH` 接口支持该请求头,合并分支则必须携带。各接口是否支持见 [API 参考](https://mirabase.io/zh/developers/api.md) 中的参数表。 - 不接受的接口重发也是安全的:`GET` 不改数据;上传的 `parts`、`complete`、`abort` 按上传 id 判重;[`PATCH /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 重发返回相同的结果。 - 单条 `DELETE` 不支持该请求头:第二次调用返回 404 `not_found`,同样可以确认结果。如需可重放的删除,请使用带幂等键的 `files/batch`。 - SDK 会自动给接受这个头的调用生成键,重试用的是同一个。 ## 条件请求 文件的 `ETag` 是它最新版本的 id,版本不可变,所以它是强校验器。用它避免覆盖他人的改动,也避免重复下载。 | 请求头 | 用在 | 效果 | | --- | --- | --- | | `If-Match: ""` | 写入、修改、删除、回滚 | 仅当文件仍为该版本时执行;否则返回 412 `precondition_failed`,错误体中的 `current_version_id` 为当前版本 | | `If-None-Match: *` | 写入 | 仅当路径下尚无文件时写入;已有文件则返回 412 `precondition_failed` | | `If-None-Match: ""` | 读取 | 内容未变更时返回 304,无响应体 | | `Range`, `If-Range` | 读取原件 | 返回 206 和请求的字节段;范围在文件之外返回 416 `range_not_satisfiable` | 写入成功的响应包含新版本的 `ETag`,下一次 `If-Match` 可直接使用,无需再次读取。完整示例见 [文件](https://mirabase.io/zh/developers/files.md#conditional)。 ## 任务 无法在单次请求内完成的操作会转为任务:返回 202,携带 `job_id` 和指向该任务的 `Location`。每隔 1 到 2 秒轮询一次 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read),直至状态变为终态。 每种状态的含义见 [DevJobStatus](https://mirabase.io/zh/developers/api/schemas.md#DevJobStatus),任务的种类见 [DevJobKind](https://mirabase.io/zh/developers/api/schemas.md#DevJobKind)。 | 请求 | 说明 | | --- | --- | | 写入内容之后的处理(解析、索引、提炼) | 写入本身已提交,处理在后台运行。`Prefer: wait=N`(最多 10 秒)可使响应等待至处理完成,见 [文件](https://mirabase.io/zh/developers/files.md#processing) | | 大的目录操作和分支合并 | 超过同步上限时带 `Prefer: respond-async`,见 [文件](https://mirabase.io/zh/developers/files.md#jobs) 和 [分支](https://mirabase.io/zh/developers/branches.md#async-merge) | | 导出和导入 | 总是任务,见 [同步](https://mirabase.io/zh/developers/sync.md#export) | ```bash curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` 目录、合并、导出、导入这类任务只有发起人和 Space 所有者能读,完成后保留 7 天。任务没有长轮询。 ## 错误 所有错误结构相同。`type` 表示错误大类,适合按类别统一处理;具体情况按稳定的 `code` 和 `remediation.action` 分支处理;`message` 供人工阅读,内容可能变更。 ```json { "error": { "code": "precondition_failed", "type": "conflict", "status": 412, "message": "the file has moved on", "request_id": "req_a18f", "retryable": false, "current_version_id": "ver_3c44", "remediation": { "action": "reread_and_retry", "doc_url": "https://api.mirabase.dev/llms.txt" } } } ``` 每个字段的含义见 [DevErrorBody](https://mirabase.io/zh/developers/api/schemas.md#DevErrorBody),`type` 与 HTTP 状态码的对应关系见 [DevErrorType](https://mirabase.io/zh/developers/api/schemas.md#DevErrorType),全部错误码见 [错误码](https://mirabase.io/zh/developers/errors.md#codes)。 ### 一次列出全部出错字段 请求体校验失败时,422 `validation_error` 的 `errors` 会列出发现的全部问题,便于一次修正。字段路径用点号分隔,例如 `messages.0.role`。 ```json { "error": { "code": "validation_error", "type": "invalid_request", "status": 422, "message": "query is required", "request_id": "req_b27c", "retryable": false, "field": "query", "errors": [ { "field": "query", "code": "validation_error", "message": "query is required" }, { "field": "colour", "code": "validation_error", "message": "unknown field: colour" } ], "remediation": { "action": "fix_request", "doc_url": "https://api.mirabase.dev/llms.txt" } } } ``` 各 SDK 按 HTTP 状态码抛出 `MirabaseError` 的子类,例如 `MirabaseNotFoundError`、`MirabaseRateLimitError`,错误对象上也有 `type` 和 `errors`,见 [SDK](https://mirabase.io/zh/developers/sdks.md#errors)。 ## 重试 - 检查 `retryable`。若有 `Retry-After`,按其指定的时间等待后再重试;否则使用带抖动的指数退避。 - 重试写操作时请携带 `Idempotency-Key`,否则可能产生多余版本。 每个错误码给出的 `Retry-After` 秒数见 [错误码](https://mirabase.io/zh/developers/errors.md#codes)。 ## 限流与限额 通过认证的响应都带 `RateLimit-Limit`、`RateLimit-Remaining` 和 `RateLimit-Reset`。每个 Key 有两个令牌桶:`GET`、`HEAD` 一个,其他方法一个。桶容量等于每分钟额度,所以允许一分钟额度的突发。账户另有所有 Key 合计的总额度;因总额度受限的请求,响应头报告的是总额度的令牌桶。限流按服务进程执行,这些数字只作参考,不是精确额度。 ```bash curl https://api.mirabase.dev/v2/limits \ -H "Authorization: Bearer $MIRABASE_API_KEY" curl https://api.mirabase.dev/v2/usage \ -H "Authorization: Bearer $MIRABASE_API_KEY" ``` 每项限额的名称、默认值、范围和超出时的返回见 [API 参考](https://mirabase.io/zh/developers/api/schemas.md#DevLimit)。默认值是暂定的:以 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 返回的部署实际值为准,用 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 查看当前用量。并发限额占满时,请求先在服务端等待名额,因此短时间的并发突发只会变慢,不会被拒绝。 429 `rate_limited` 的错误信封带 `limit`,说明触发的是哪一种限制。`request_rate` 是每分钟的请求额度:按 `Retry-After` 等待后重试。`concurrency` 是对进行中的调用数量的限制:请求已经在服务端等过名额,响应不带 `RateLimit-*` 响应头。这时应减少同时发出的调用,延长等待的作用不大。 单个接口自己的上限,例如文件大小、批量条数和取值范围,写在 [API 参考](https://mirabase.io/zh/developers/api.md) 中该接口的说明和参数里。 ### 套餐 每个账户有一个套餐,见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 和 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 响应中的 [plan](https://mirabase.io/zh/developers/api/schemas.md#DevPlan)。套餐决定适用哪些限额,具体数值以 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 的返回为准。 | 套餐 | 说明 | | --- | --- | | `standard` | 使用当前部署的限额。 | | `free` | 自助注册账户的初始套餐。除当前部署的限额外,还限制存储空间、每月写入量、每月模型 token 数、每月模型费用和请求速率。持久配额用尽时返回 429 `quota_exceeded`,并由 `quota` 字段指明耗尽的配额项。 | | `legacy` | 在推出套餐之前开通的账户。与 `standard` 一样使用当前部署的限额。 | ## 下一步 - [错误码](https://mirabase.io/zh/developers/errors.md):每个错误码的含义和 `remediation.action`。 - [SDK](https://mirabase.io/zh/developers/sdks.md):客户端已内置这些规则。 - [API 参考](https://mirabase.io/zh/developers/api.md):每个接口的参数和响应。 --- # 错误码 API Key 可能收到的每个错误码,及其 HTTP 状态码、remediation.action、含义和 Retry-After。 这张表从 OpenAPI 规格生成。错误信封的结构、重试策略和限流规则见 [API 约定](https://mirabase.io/zh/developers/conventions.md#errors)。按 `code` 和 `remediation.action` 分支处理;没有 `remediation.action` 的错误码没有固定的下一步,按 HTTP 状态码处理。后续可能新增错误码,未知错误码同样按 HTTP 状态码处理。 ## 错误码 | 错误码 | 状态 | `remediation.action` | 含义 | | --- | --- | --- | --- | | `validation_error` | 400 / 422 | `fix_request` | 请求不合法。 | | `invalid_request` | 400 / 422 | `fix_request` | 请求不合法。 | | `unsupported_contract_version` | 400 | `drop_contract_version` | 服务不支持这个 `Mirabase-Contract-Version` 值:去掉这个请求头。 | | `unauthorized` | 401 | `check_api_key` | Key 缺失、无效、已过期或已吊销。 | | `account_pending_approval` | 403 | `wait_for_approval` | 账户尚未通过审批。审批通过后,用原来的 Key 重试。 | | `account_rejected` | 403 | `contact_support` | 账户未通过审批。请通过联系页咨询。 | | `account_suspended` | 403 | `contact_support` | 账户已停用。请通过联系页咨询。 | | `forbidden` | 403 | `check_permissions` | 能力或角色不足。 | | `identity_override` | 403 | `remove_identity_fields` | 请求里出现了 `principal_id` 这类由服务端控制的字段。 | | `proposal_required` | 403 | `request_direct_write_mode` | Agent 修改他人的文件,需要 `write_mode: direct`。 | | `reserved_path` | 403 | `choose_another_path` | 路径在 `/.mirabase/` 下。 | | `outside_write_root` | 403 | `ask_owner_to_change_write_root` | 写入落在成员的写入根路径之外。 | | `outside_read_root` | 403 | `ask_owner_to_change_read_root` | 有读取根路径的成员使用了分支。 | | `outside_metadata_scope` | 403 | `omit_scope_metadata_keys` | 带元数据范围的 Key 在范围的键上写了其他值:去掉这个键,或使用范围内的第一个值。 | | `scoped_key_route_unavailable` | 403 | `use_unscoped_key` | 带元数据范围的 Key 只能读取、检索、回答和导入:这个操作需要不带范围的 Key。 | | `console_session_required` | 403 | `use_console` | 这个操作只接受控制台会话,不接受 API Key:请在控制台里完成。 | | `not_found` | 404 | `check_identifier` | 不存在,或对你不可见。 | | `content_not_ready` | 404 | `wait_and_retry` | 这个视图需等待处理完成。 | | `branch_not_found` | 404 | `check_identifier` | 分支不存在。 | | `checkpoint_not_found` | 404 | `check_identifier` | 检查点不存在。 | | `object_not_found` | 404 | `check_identifier` | 分支对象不存在。 | | `snapshot_not_found` | 404 | `check_identifier` | 快照不存在。 | | `webhook_not_found` | 404 | `check_identifier` | Webhook 不存在。 | | `upload_not_found` | 404 | `check_identifier` | 上传不存在。 | | `virtual_file` | 405 | `use_memories_api` | `/.mirabase/memory/MEMORY.md` 和 `RECENT.md` 是只读视图。 | | `request_timeout` | 408 | `retry_later` | 读取请求体超时。 | | `conflict` | 409 | - | 请求与当前状态冲突。只有在 `Idempotency-Key` 被复用于不同输入时,`remediation.action` 才是 `use_new_idempotency_key`;其他冲突没有动作。 | | `path_conflict` | 409 | `choose_another_path` | 目标路径已被占用。 | | `not_a_directory` | 409 | `choose_another_path` | 路径中的某一段是文件。 | | `move_into_descendant` | 409 | `choose_another_path` | 目录不能移动到自身内部。 | | `copy_into_descendant` | 409 | `choose_another_path` | 目录不能复制到自身内部。 | | `directory_not_empty` | 409 | `set_recursive` | 删除非空目录需要 `recursive: true`。 | | `subtree_too_large` | 409 | `split_request` | 超过同步节点上限:拆分请求,或带 `Prefer: respond-async`。 | | `directory_is_write_root` | 409 | `change_member_write_root` | 该目录是某个成员的写入根路径,或包含它。 | | `directory_is_read_root` | 409 | `change_member_read_root` | 该目录是某个成员的读取根路径,或包含它。 | | `content_url_unavailable` | 409 | `use_content_endpoint` | 服务端保存的小文本文件没有下载地址:用 `view=raw` 读取。 | | `too_many_open_proposals` | 409 | `review_or_withdraw_proposals` | 这个 Agent 在该 Space 里已有 100 个打开的提案。 | | `proposal_conflict` | 409 | `resubmit_proposal` | 提交提案后文件已变更或移入废纸篓:请重新提交。 | | `proposal_closed` | 409 | `stop_retrying` | 提案或整理提案已不在打开状态。 | | `memory_pending_review` | 409 | `review_memory_first` | 这条记忆正在等待审核:先审核,再修改。 | | `memory_already_reviewed` | 409 | `stop_retrying` | 这条记忆已不在待审核状态。 | | `memory_superseded` | 409 | `read_current_memory` | 这条记忆已被后来的修订取代:请读取当前的记忆。 | | `undo_window_expired` | 409 | `stop_retrying` | 撤销只在 30 分钟内可用。 | | `undo_not_applicable` | 409 | `undo_the_correction` | 提炼出的事实没有可撤销的写入:撤销取代它的那次更正。 | | `upload_not_open` | 409 | `start_new_upload` | 上传已完成或已中止:请重新发起。 | | `upload_conflict` | 409 | `start_new_upload` | 上传处于冲突状态:请重新发起。 | | `snapshot_name_taken` | 409 | `choose_another_name` | 这个 Space 已有同名快照。 | | `too_many_snapshots` | 409 | `delete_unused_snapshots` | 这个 Space 的快照数量已达上限。 | | `snapshot_too_large` | 409 | `review_usage` | 超过快照的文件数上限。 | | `too_many_webhooks` | 409 | `delete_unused_webhooks` | 这个 Space 的 Webhook 数量已达上限。 | | `export_too_large` | 409 | `split_request` | 导出超过文件数或字节上限:按 `path` 分次导出。 | | `artifact_not_ready` | 409 | `wait_for_job` | 导出尚未完成。 | | `space_busy` | 409 | `wait_and_retry` | 这个 Space 持续繁忙了 2 秒。`Retry-After`:1 秒。 | | `space_external_id_taken` | 409 | `find_space_by_external_id` | 账户里的另一个 Space 已使用这个 `external_id`。如果你能看到它,用 [`GET /v2/spaces?external_id=`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 或 [`PUT /v2/spaces/ext:`](https://mirabase.io/zh/developers/api/spaces.md#spaces-ensure) 获取;如果看不到,请换一个 id。 | | `job_in_flight` | 409 | `wait_and_retry` | 有工作正在进行:等待 `job_id`。 | | `evidence_changed` | 409 | `retry_request` | 构建结果期间证据发生了变化:请重新发送。 | | `branch_not_active` | 409 | `open_new_branch` | 分支已合并或已放弃。 | | `branch_name_taken` | 409 | `choose_another_name` | 已有同名的活跃分支。 | | `branch_limit_reached` | 409 | `abandon_or_merge_branches` | 这个 Space 的活跃分支数量已达上限。 | | `branch_too_large` | 409 | `merge_or_split_branch` | 分支的路径数量已达上限。 | | `checkpoint_limit_reached` | 409 | `open_new_branch` | 分支的检查点数量已达上限。 | | `merge_conflict` | 409 | `resolve_conflicts` | 主线修改了分支也修改过的路径:见 `conflicts`。 | | `merge_too_large` | 409 | `split_request` | 一次合并超过 1000 个路径:用 `paths` 分批,或带 `Prefer: respond-async`。 | | `merge_in_progress` | 409 | `wait_for_job` | 这个分支的合并任务正在排队或运行。 | | `dream_run_in_flight` | 409 | `wait_for_job` | 这个范围的一次整理正在排队或运行。 | | `dreaming_disabled` | 409 | `enable_memory_dreaming` | 这个 Space 的整理设置为 `off`。 | | `api_key_not_live` | 409 | `issue_new_key` | Key 已吊销或已过期。 | | `self_rotation_not_allowed` | 409 | `issue_new_key_then_revoke` | Key 不能轮换自己。 | | `owner_membership_immutable` | 409 | `keep_owner_membership` | 所有者的成员关系不能修改。 | | `default_space_protected` | 409 | `keep_default_space` | 默认 Space 不能删除。 | | `tenant_deleted` | 409 | `stop_requests` | 账户已删除。 | | `tenant_limit_reached` | 409 | `delete_unused_resources` | 账户的活跃 Key、主体或 Space 数量已达上限。 | | `gone` | 410 | `stop_retrying` | 这张回执对应的 Entry 已被彻底删除。 | | `cursor_expired` | 410 | `resync_from_tree` | 游标已超过 90 天:从 `tree` 重新同步。 | | `artifact_expired` | 410 | `start_new_export` | 导出失败、已超过 7 天,或因彻底删除或读取根路径变化而失效。 | | `export_invalidated` | 410 | `start_new_export` | 导出期间有内容被彻底删除,或读取范围发生了变化:请重新导出。 | | `precondition_failed` | 412 | `reread_and_retry` | `If-Match` 或 `If-None-Match` 不满足。 | | `payload_too_large` | 413 | `reduce_payload` | 请求体过大。 | | `patch_base_too_large` | 413 | `use_put` | 文件超过 1 MiB,不能用 `PATCH`。 | | `archive_too_large` | 413 | `split_archive` | 导入的归档过大,或包含超过 10,000 个条目。 | | `upload_invalid` | 413 / 422 | `fix_request` | 上传请求不合法,或文件超过上限。 | | `upload_media_type_mismatch` | 415 | `fix_request` | 上传内容的类型与发起时声明的不一致。 | | `unsupported_media_type` | 415 | `use_put` | 不是 UTF-8 文本。 | | `range_not_satisfiable` | 416 | `fix_request` | `Range` 超出文件范围。 | | `invalid_path` | 422 | `fix_path` | 路径不符合规则。 | | `path_too_long` | 422 | `shorten_path` | 路径超过长度上限。 | | `edit_no_match` | 422 | `reread_and_retry` | 找不到 `old_text`。 | | `edit_ambiguous` | 422 | `add_context_or_replace_all` | `old_text` 出现了不止一次。 | | `view_not_available` | 422 | `choose_another_view` | 这个来源没有这种视图。 | | `upload_expired` | 422 | `start_new_upload` | 上传会话已结束。 | | `upload_size_mismatch` | 422 | `fix_request` | 上传的字节数与发起时声明的 `size` 不一致。 | | `upload_integrity_mismatch` | 422 | `start_new_upload` | 上传的内容与 `checksum_sha256` 不符:请重新上传。 | | `checksum_mismatch` | 422 | `fix_request` | 分支对象的哈希与它的 `sha256` 不符。 | | `unknown_citation` | 422 | `use_citations_from_pack` | 反馈里的某个引用不在这个上下文包里。 | | `write_root_outside_read_root` | 422 | `set_write_root_inside_read_root` | 写入根路径不在读取根路径之内。 | | `invalid_webhook_url` | 422 | `fix_webhook_url` | Webhook 地址不是 443 端口上的公网 `https` 地址。 | | `unsupported_archive` | 422 | `use_tar_archive` | 导入的不是 tar 或 gzip 压缩的 tar。 | | `rate_limited` | 429 | `wait_and_retry` | 达到请求速率或并发上限。`Retry-After`:`limit` 为 `request_rate` 时,是请求令牌桶腾出空间所需的秒数;`limit` 为 `concurrency` 时为 1。 | | `too_many_waiters` | 429 | `wait_and_retry` | 一个 Key 已保持 4 个长轮询。`Retry-After`:1 秒。 | | `ingest_backlog` | 429 | `wait_and_retry` | 账户的排队任务过多:使内容可检索的任务超过 `tenant_queued_jobs`,或摘要、分类、关联和记忆任务超过它的五倍。`queue` 给出该类任务的数量、上限、处理是否已暂停,以及队列预计所需的时间。限定了部分 Space 或元数据范围的 Key 只会被告知已达上限。`Retry-After`:30 到 600:账户队列降到上限以下的预计时间;处理暂停期间为 600。对限定了部分 Space 或元数据范围的 Key 为 60。 | | `too_many_jobs` | 429 | `wait_and_retry` | 这个 Space 已在运行 4 个改动目录树的任务,或 4 个导出。`Retry-After`:30 秒。 | | `login_code_throttled` | 429 | `wait_and_retry` | 控制台邮箱验证码:请求过于频繁,或同一地址的错误验证码过多。`Retry-After`:验证码请求过于频繁时为 60;一小时内请求或错误验证码过多时为 3600。 | | `quota_exceeded` | 429 | `review_usage` | 持久配额已用尽,或本次调用所需的量超过剩余额度,重试无效。`quota` 指明是哪一项:`writes`、`storage_bytes`、`model_tokens` 或 `model_spend_micro_usd`。 | | `internal_error` | 500 | `retry_later` | 服务内部错误。 | | `model_failed` | 502 | `retry_later` | 回答时模型调用失败。 | | `original_unavailable` | 503 | `retry_later` | 原件暂时不可用。 | | `answer_unavailable` | 503 | `retry_later` | 回答模型暂时不可用。 | | `object_store_unavailable` | 503 | `retry_later` | 对象存储暂时不可用。 | | `object_store_request_failed` | 503 | `retry_later` | 对象存储暂时不可用。 | | `object_stream_integrity_mismatch` | 503 | `retry_later` | 对象存储暂时不可用。 | | `spec_unavailable` | 503 | `feature_not_enabled` | 这个部署没有启用该功能,重试无效。 | | `webhooks_unavailable` | 503 | `feature_not_enabled` | 这个部署没有启用该功能,重试无效。 | | `answer_not_configured` | 503 | `use_context_with_your_model` | 这个部署没有配置回答模型:用 [`POST /v2/retrieval/context`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-buildcontext) 构建上下文包,交给你自己的模型。 | | `deadline_exceeded` | 504 | `retry_later` | 检索超过了请求里的 `deadline_ms`。 | ## 下一步 - [API 约定](https://mirabase.io/zh/developers/conventions.md#errors):错误信封、重试和限流。 - [SDK](https://mirabase.io/zh/developers/sdks.md#errors):SDK 抛出的错误类型。 - [API 参考](https://mirabase.io/zh/developers/api.md):每个接口可能返回的状态码。 --- # 技能(Skills) Mirabase 官方技能:告诉 Agent 何时调用哪个 MCP 工具、按什么顺序、哪些操作先征得用户同意。包括九个按任务划分的技能,以及项目记忆和带引用知识库两个完整场景。 技能是一个文件夹,里面有一个 `SKILL.md`:开头的 `name` 和 `description` 说明它做什么、何时使用,正文是步骤。技能描述常驻 Agent 的上下文,正文在任务匹配时才加载,所以技能在使用前占用很少。官方技能采用 Agent Skills 格式,不依赖特定的 Agent 平台;它们调用的工具来自 Mirabase 的 [MCP 服务](https://mirabase.io/zh/developers/agents.md)。 ## 官方技能 | 技能 | 用途 | | --- | --- | | `mirabase` | 入口技能:判断内容应存为文件、记忆还是对话记录,保存邮件、会议记录和网页,选择要加载的技能,处理任务的开始与结束。 | | `mirabase-setup` | 连接 Agent,用 `mira.whoami` 检查 Key,解释 401、403、404 和 429。 | | `mirabase-files` | 按路径读写、编辑、移动、复制和上传文件,用 ETag 避免覆盖他人的修改。 | | `mirabase-recover` | 查看版本与差异、回滚、从废纸篓恢复、创建和读取快照。 | | `mirabase-branches` | 在分支上修改多个文件、设检查点、展示差异供审查后合并,以及审查 Agent 的提案。 | | `mirabase-sync` | 通过 CLI 同步本地目录,或通过变更流和 Webhook 跟踪变化。 | | `mirabase-recall` | 搜索、为任务获取上下文包、带引用回答,并读取检索结果对应的完整 Entry。 | | `mirabase-memories` | 记住、更正、审核和遗忘记忆,并选择正确的范围。 | | `mirabase-access` | 为每个 Agent 签发受限的 Key,设置读写根路径、写入模式和标签范围,轮换和吊销 Key。 | | `mirabase-project-memory` | 场景:编程 Agent 在多次会话之间保留一个仓库的约定、决定和进度。 | | `mirabase-knowledge-base` | 场景:把一个文档目录载入 Space,文档更改后重新载入,并基于这些文档带引用回答。 | - 每个描述都包含中英文的示例请求,并写明不适用的情形,帮助 Agent 加载正确的技能。 - 不可撤销的操作(彻底删除、遗忘记忆、吊销 Key、覆盖式合并)都要求先征得用户同意。技能从不打印或保存 Key,并把工具返回的内容当作数据而不是指令。 - 全部描述合计约 1,700 个 token;单个技能文件在 1,300 到 2,150 个 token 之间,只在使用时读取(按 `cl100k_base` 计)。 ## 场景技能 **项目记忆(`mirabase-project-memory`)**:每个仓库使用一个独立的 Space(如 `ext:acme-web`)。会话开始时以 `purpose: "coding"` 调用 `mira.context`,从项目记忆中读取约定、决定和上次的进度;工作中把约定和决定各记为一条项目记忆,需要说明理由的决定另写一份简短的决定记录;会话结束时用 `mira.memory.correct` 更新这项工作的进度记忆(每项独立任务各保留一条)。代码、差异和日志不写入 Mirabase,它们已在仓库里。 **知识库(`mirabase-knowledge-base`)**:每个知识库使用一个独立的 Space。附带的载入脚本(Node 18 或更新版本,无依赖)把目录中的文档写到 `/kb/` 下,内容相同的文件不产生新版本,本地已删除的文件只列出、不删除;文档以 `memory_exclude` 写入,按原文检索和引用,不提炼为记忆。回答使用 `mira.answer`:`answered` 时给出答案和所引用文件的路径,`abstained` 时说明检索到的内容不足以回答,不用通用知识补充。 ## 安装(即将上线) > **即将上线** 官方技能与开源仓库一同发布,源代码在开源仓库发布后提供。发布后,按所用的 Agent 平台安装: Claude Code: ```bash export MIRABASE_API_KEY="mb_live_..." # From the root of the open-source repository. The plugin folder adds the MCP server, the skills, and the hooks. claude --plugin-dir clients/agent-plugin ``` Codex: ```bash export MIRABASE_API_KEY="mb_live_..." codex mcp add mirabase --url https://api.mirabase.dev/mcp --bearer-token-env-var MIRABASE_API_KEY # Then paste the section in clients/agent-plugin/codex/AGENTS.md into your project's AGENTS.md. ``` Agent Skills: ```agent skills # From the root of the open-source repository: copy all eleven skills into the host's skills directory. SKILLS_DIR=~/.claude/skills # Claude Code without the plugin; other hosts document their own mkdir -p "$SKILLS_DIR" && cp -R clients/agent-plugin/skills/* "$SKILLS_DIR"/ # Then add the MCP server: https://api.mirabase.dev/mcp, Streamable HTTP, # header "Authorization: Bearer $MIRABASE_API_KEY". ``` - Claude Code:插件目录一次加入 MCP 服务、全部技能和钩子。钩子在会话开始时读取记忆,并在上下文压缩前、会话结束时以及每 20 条消息时,把用户和助手的文字保存到 `MIRABASE_SPACE` 指定的 Space(默认 Space),保存时遮盖疑似凭据;设置 `MIRABASE_CAPTURE=off` 可关闭保存。 - Codex:通过项目的 `AGENTS.md` 提供规则。插件中的 `codex/AGENTS.md` 是一段可粘贴的简短规则,覆盖存储规则和两个场景;如果你的 Codex 版本支持加载 Agent Skills,也可以像其他平台一样复制技能文件夹。 - 其他支持 Agent Skills 的平台(示例中的 Agent Skills 选项卡):复制技能文件夹。只复制一部分时,务必包含入口技能 `mirabase`,其他技能会引用它。 > **说明:** 在此之前,MCP 服务已可直接使用:握手响应的 `instructions` 已说明何时读取、何时保存、保存到哪里,支持该字段的客户端会把它交给模型。连接方式见 [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md)。 ## 下一步 - [基于 Mirabase 开发](https://mirabase.io/zh/developers/build.md):编写自己的技能,并了解技能、SDK、Webhook 和供应商插件如何配合。 - [连接 Agent(MCP)](https://mirabase.io/zh/developers/agents.md):技能调用的全部工具及其参数。 - [权限](https://mirabase.io/zh/developers/permissions.md):为每个 Agent 设置写入模式和读写根路径。 --- # 基于 Mirabase 开发 SDK、MCP、技能、Space 中的技能、Webhook 和供应商插件各自的作用与组合方式;一个应用的核心调用流程;如何编写并检查自己的技能。 ## 扩展方式 | 方式 | 谁用它、做什么 | | --- | --- | | [SDK](https://mirabase.io/zh/developers/sdks.md)(TypeScript、Python) | 你的应用代码调用 `/v2`:写入文件和对话,获取上下文包,带引用回答。 | | [MCP 服务](https://mirabase.io/zh/developers/agents.md) | Agent 通过 `mira.*` 工具读写文件、检索、获取上下文、回答和管理记忆,权限与 `/v2` 相同。分支、访问管理和二进制上传只能通过 REST。 | | [技能](https://mirabase.io/zh/developers/skills.md) | Agent 平台加载技能,按技能决定何时调用哪个工具、按什么顺序、先问用户什么。 | | Space 中的技能 | 调用 `mira.context` 的任何 Agent:上下文包会推荐存在 Space 中的技能,无需在每个 Agent 上安装。 | | [Webhook 与变更流](https://mirabase.io/zh/developers/sync.md) | 你的服务在 Space 中的文件变化时运行自己的处理,例如重新生成索引或通知团队。 | | 供应商插件 | 自部署的引擎用它替换嵌入、重排、回答、提炼、分类、OCR、转写或联网搜索的实现。托管服务不加载插件。 | ### 选择扩展方式 - 你的产品调用 Mirabase:用 SDK。 - Agent 调用 Mirabase:连接 MCP,并安装技能告诉它如何使用。 - 同一套做法要提供给一个团队的所有 Agent:把技能存在 Space 中。 - Mirabase 中的变化要触发你自己的系统:用 Webhook 或变更流。 - 在自己的部署中更换模型:写一个供应商插件。 ## 核心调用流程 下面的程序演示四类常用调用:按路径写入文件,保存对话,为任务获取上下文包交给自己的模型,或直接获取带引用的回答。它在一个独立的 Space(`ext:example-core-loop`)中运行,不影响你的其他数据;只需设置 `MIRABASE_API_KEY`,Key 需要能创建 Space、读取、写入和回答。 TypeScript: ```ts import { Mirabase } from "@mirabase/sdk/developer"; const mb = new Mirabase(); // reads MIRABASE_API_KEY // A Space of its own, created on the first run; the client reads and writes that Space only. const space = await mb.spaceFor("example-core-loop", { name: "Core loop example" }); // 1. A file at a stable path. The same bytes again create no new version. await space.files.write( "/handbook/travel.md", "# Travel policy\n\nHotels up to 180 euros a night are approved automatically.\nBook economy for flights under six hours.\n", ); // 2. A conversation. Memories are distilled from it in the background. await space.conversations.add( [ { role: "user", content: "I'm going to Berlin for the trade fair on 12 March. I prefer hotels near the fair." }, { role: "assistant", content: "Noted: Berlin, 12 March, a hotel close to the fair." }, ], { sessionId: "core-loop-demo", redactSecrets: true }, ); await space.spaces.waitUntil({ waitTimeoutMs: 120_000 }); // searchable by meaning // 3. Context for your own model: memories and passages within a token budget, each with a citation id. const pack = await space.context("Book a hotel for the Berlin trip within policy.", { budget_tokens: 1500 }); // API field names stay snake_case // ...send pack.items to your model; afterwards report the citation ids it actually used: // await space.context.feedback(pack.pack_id, usedCitationIds); // 4. Or a cited answer from Mirabase. It abstains when the evidence is not there. const answer = await space.answer("How much can a hotel cost per night without approval?"); console.log(answer.status, answer.answer, answer.citations.map((citation) => citation.path ?? citation.url ?? citation.entry_id)); ``` Python: ```python from mirabase import Mirabase mb = Mirabase() # reads MIRABASE_API_KEY # A Space of its own, created on the first run; the client reads and writes that Space only. space = mb.space_for("example-core-loop", name="Core loop example") # 1. A file at a stable path. The same bytes again create no new version. space.files.write( "/handbook/travel.md", "# Travel policy\n\nHotels up to 180 euros a night are approved automatically.\n" "Book economy for flights under six hours.\n", ) # 2. A conversation. Memories are distilled from it in the background. space.conversations.add( [ {"role": "user", "content": "I'm going to Berlin for the trade fair on 12 March. I prefer hotels near the fair."}, {"role": "assistant", "content": "Noted: Berlin, 12 March, a hotel close to the fair."}, ], session_id="core-loop-demo", redact_secrets=True, ) space.spaces.wait_until(timeout=120) # searchable by meaning # 3. Context for your own model: memories and passages within a token budget, each with a citation id. pack = space.context("Book a hotel for the Berlin trip within policy.", budget_tokens=1500) # ...send pack["items"] to your model; afterwards report the citation ids it actually used: # space.context.feedback(pack["pack_id"], used_citation_ids) # 4. Or a cited answer from Mirabase. It abstains when the evidence is not there. answer = space.answer("How much can a hotel cost per night without approval?") print(answer["status"], answer["answer"], [c.get("path") or c.get("url") or c["entry_id"] for c in answer["citations"]]) ``` - `spaceFor`(Python 为 `space_for`)在首次运行时创建 Space,之后找到同一个 Space;它返回的客户端只读写这个 Space。为每个最终用户建一个 Space,并在服务端按已登录用户选择对应的客户端,即可把不同用户的数据分开。绑定 Space 只会设置客户端默认访问的 Space,实际可访问的范围由 Key 的权限决定:Key 本身仍能读取它可见的所有 Space,需要硬边界时,签发只允许访问该用户 Space 的 Key,见 [权限](https://mirabase.io/zh/developers/permissions.md)。 - 不超过 64 KiB 的文本写入后即可按词检索,处理完成后即可按语义检索;需要等待时可调用 `waitUntil`(Python 为 `wait_until`)。 - `context.feedback` 回报模型实际用到的条目,只发送引用 id,不发送内容。 - 可运行的完整版本是开源仓库中的 `examples/core-loop`,源代码在开源仓库发布后提供。 ## 编写技能 技能模板是一个可运行的小技能 `changelog`:根据 Space 中的变更和已保存的决定起草更新日志,经用户确认后写入 `/changelog/.md`。复制它,再按下列顺序修改: 1. 文件夹名与 `name` 相同:小写单词,用连字符连接,不超过 64 个字符。 2. 先写描述:Agent 只根据描述决定是否加载技能,而且描述常驻上下文。写清做什么,给出两三个用户的真实请求,并用“Not for”指明相邻的技能。不超过 650 个字符。 3. 写步骤:每一步写出确切的工具名或接口,并说明常见错误的处理方式。不可撤销或对外发出的操作,写明先征得用户同意。 4. 删除模板中的注释:技能每次加载都会读取全部内容。 5. 在调整描述之前写好触发测试:应当加载这个技能的请求,以及应当加载其他技能的相近请求。 模板附带的检查会确认技能提到的每个 `mira.*` 工具和 `/v2` 接口都存在,并用一个只看名称和描述的词法路由器为你的请求和官方请求打分;如果你的描述误匹配了本应由其他技能处理的请求,应修改描述,而不是修改请求。模板与检查工具的源代码在开源仓库发布后提供。 ## 把技能存在 Space 中 写入 `/.mirabase/skills//SKILL.md` 的文件会被上下文包当作技能来源:Agent 调用 `mira.context` 时,`items` 中 `source` 为 `skills` 的条目是技能描述的一行摘要,Agent 在使用前用 `mira.files.read` 读取完整文件。这样,一个团队的约定可以随 Space 提供给所有 Agent,而不必在每个 Agent 上安装。官方技能要求 Agent 在第一次使用某个 Space 中的技能前、以及该技能更改后,先征得用户同意,并且从不运行 Space 中存放的脚本。 curl: ```bash curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:team-handbook/files?path=/.mirabase/skills/changelog/SKILL.md" \ -H "Authorization: Bearer $MIRABASE_API_KEY" \ -H "Content-Type: text/markdown" \ --data-binary @changelog/SKILL.md ``` TypeScript: ```ts import { readFile } from "node:fs/promises"; import { Mirabase } from "@mirabase/sdk/developer"; const team = new Mirabase().space("ext:team-handbook"); // the Space whose Agents should see the skill await team.files.write("/.mirabase/skills/changelog/SKILL.md", await readFile("changelog/SKILL.md", "utf8")); ``` Python: ```python from pathlib import Path from mirabase import Mirabase team = Mirabase().space("ext:team-handbook") # the Space whose Agents should see the skill team.files.write("/.mirabase/skills/changelog/SKILL.md", Path("changelog/SKILL.md").read_text()) ``` - 只认这一层:`/.mirabase/skills/` 下每个文件夹中的 `SKILL.md`。同一文件夹中的其他文件是技能自己的参考资料,Agent 只读取,不执行。 - 技能来源在上下文包中有自己的预算份额。预算较小时摘要可能放不下,`route` 中这一来源会报告 `budget_too_small`,所以描述要短。 > **注意:** 存在 Space 中的技能和其他内容一样:能写这个 Space 的人就能改变 Agent 收到的指示。只把这个文件夹的写入权限交给可信的成员(用写入根路径限制其他成员,见 [权限](https://mirabase.io/zh/developers/permissions.md)),不能更改的规则放在 Agent 自己的技能目录中。 ## 响应变化 需要在文件变化时运行自己的处理(重新生成派生文件、同步到其他系统、通知团队),用 [Webhook](https://mirabase.io/zh/developers/sync.md#webhooks) 让 Mirabase 推送变更,或用 [变更流](https://mirabase.io/zh/developers/sync.md#loop) 从游标开始长轮询。两者给出相同的事件;Webhook 需要一个公网 HTTPS 地址,变更流不需要。 ## 供应商插件(自部署) 自部署的 Mirabase 引擎通过提供方接口调用模型和工具:嵌入、重排、回答、提炼、分类、OCR、转写和联网搜索。插件是一个 ES 模块,导出 `{ name, register(api) }`,在 `register` 中为某个提供方接口登记一个实现;部署时用环境变量 `MIRABASE_PROVIDER_PLUGINS` 加载,再用该接口对应的变量选择它。 - 插件在引擎进程中运行,权限与引擎相同。只加载自己编写或审查过的代码。托管服务不加载任何插件。 - 一致性检查套件逐项核对每个提供方接口的契约(例如重排必须返回候选自己的 `index`、取消时立即停止),不依赖测试框架。 - 插件接口、各提供方接口的契约和示例插件见开源仓库中的 `docs/providers.md`,源代码在开源仓库发布后提供。 ## 下一步 - [技能](https://mirabase.io/zh/developers/skills.md):官方技能和两个场景技能。 - [SDK](https://mirabase.io/zh/developers/sdks.md):安装 SDK,了解错误类型和重试。 - [检索与上下文](https://mirabase.io/zh/developers/retrieval.md):上下文包的预算、来源和反馈。