# 文件与版本

写入、读取、编辑和整理文件，比较和回滚版本，处理 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/<name>/...`，那里存放你的技能文件，`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)：条件请求和幂等的通用规则。
