# 核心概念

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:<external_id>`，例如 `ext:user-42`。路径、`?space_id=` 和请求体中的 `space_ids` 均支持这种写法，无需维护映射表。

[`PUT /v2/spaces/ext:<external_id>`](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)：从对话里提炼事实，并审核、更正和遗忘。
