# 变更流

Space 的有序变更流，以及近期活动的汇总。

API 参考。Base URL：`https://api.mirabase.dev`

## 查看近期由谁做了哪些修改

`GET /v2/spaces/{space_id}/activity`

将最近 `days` 天的变更流按主体和 Entry 汇总。在共享 Space 中开始工作前可先读取此接口，了解其他成员的近期修改，避免同时编辑同一文件。最多回看最近 1000 条变更（若该时段内变更超过 1000 条，`truncated` 为 `true`），每个主体最多列出 50 个 Entry。可见范围与 `changes` 一致：设有 `read_root` 的成员仅能看到该目录下的变更。仅支持主线。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#activity)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `days` | 查询 | `integer` | 可选 | 回看的天数，1 到 30。 1 到 30，默认 7 |

### 响应

- `200` `application/json` `DevSpaceActivity`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/activity" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "since": "2026-11-06T00:00:00Z",
  "truncated": false,
  "data": [
    {
      "last_changed_at": "2026-11-06T00:00:00Z",
      "change_count": 1,
      "files": [
        {
          "entry_id": "<entry_id>",
          "op": "create",
          "changed_at": "2026-11-06T00:00:00Z",
          "change_count": 1
        }
      ]
    }
  ]
}
```

## 读取变更流

`GET /v2/spaces/{space_id}/changes`

读取按顺序排列的变更流，保留 90 天。过期的游标返回 410 `cursor_expired`，请使用 `tree` 重新同步。传入 `branch` 时响应为 `DevBranchChangeFeed`，仅接受从 `tree?branch=` 获取的该分支游标。设有 `read_root` 的成员仅能看到该范围内的事件：移入该范围的文件记为 `create`，移出的文件记为不含 `path` 的 `delete`。单页先读取最多 `limit` 条事件再过滤，因此 `has_more` 为 `true` 时 `data` 也可能少于 `limit` 条甚至为空；传入 `wait` 时，过滤后为空的页面会继续等待。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `space_id` | 路径 | `DevSpaceRef` | 必填 | Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。 长度 1 到 256 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `cursor` | 查询 | `DevCursor` | 可选 | 起始游标：上一次响应的 `cursor`，或 `tree`、快照返回的 `changes_cursor`。不传则从当前时刻开始。 长度 1 到 1024 |
| `wait` | 查询 | `integer` | 可选 | 没有事件时长轮询等待的秒数。一个 Key 最多同时保持 4 个长轮询请求，超出时返回 429 `too_many_waiters`。 0 到 30 |
| `limit` | 查询 | `integer` | 可选 | 单次最多读取的事件数：1 到 100，默认 100。 1 到 100，默认 100 |

### 响应

- `200` `application/json` `DevChangeFeed | DevBranchChangeFeed`

### 错误状态

`400` `401` `403` `404` `410` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/changes" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "data": [
    {
      "seq": 1,
      "op": "create",
      "entry_id": "<entry_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ],
  "cursor": "<cursor>",
  "has_more": false
}
```
