# 目录树

列出 Space 的目录树，以及创建、移动、复制、删除和恢复路径。

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

## 列出目录

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

列出一个目录，或返回一个文件。有 `read_root` 的成员只能看到该目录及其下属路径：其他路径（包括 `/` 和 `read_root` 之上的目录）都返回 404 `not_found`。[`GET /v2/spaces/{space_id}`](https://mirabase.io/zh/developers/api/spaces.md#spaces-read) 会显示你的 `read_root`。带 `snapshot` 时列出快照里的内容：目录是快照里文件所在的目录，`changes_cursor` 是快照的游标；两种列表的翻页游标不能混用。需要 `knowledge:read`。

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

指南：[文件与版本](https://mirabase.io/zh/developers/files.md#tree)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `path` | 查询 | `DevPath` | 可选 | Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。 长度 1 到 4096 |
| `recursive` | 查询 | `boolean` | 可选 | `true` 列出 `path` 的全部后代，而不是只列直接子节点。 |
| `branch` | 查询 | `DevBranchRef` | 可选 | 代替主线使用的分支：分支 id，或活跃分支的名称。在这个 Space 设有 `read_root` 的成员，对任何分支都返回 403 `outside_read_root`。 |
| `snapshot` | 查询 | `DevSnapshotRef` | 可选 | 快照 id 或名称。路径、版本和 `read_root` 均按创建快照时的状态判断；文件当前也必须对你可见。 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json` `DevTreePage`

### 错误状态

`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/tree" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "data": [
    {
      "path": "/notes/hello.md",
      "name": "research",
      "kind": "dir",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ],
  "changes_cursor": "<cursor>"
}
```

## 执行目录操作

`POST /v2/spaces/{space_id}/tree/operations`

在一次请求中创建目录，以及移动、复制、删除和恢复路径：1 到 200 个操作，按顺序应用，全部生效或全部不生效。一个请求最多删除、恢复或复制 200 个节点，最多移动 1000 个。子树超过同步上限时返回 409 `subtree_too_large`。带 `Prefer: respond-async` 时，只含一条 `move`、`copy`、递归 `delete` 或按 `delete_batch_id` 的 `restore` 的请求超过上限，会改为异步任务执行，最多 10000 个节点：返回 202，带 `job_id`、`Location` 和 `Preference-Applied: respond-async`。能提前完成的校验都在任务创建前完成；每一批都会重新校验权限，因此吊销 Key 或移除成员会使任务停止。任务中的 `move` 在一个事务内完成；`delete`、`restore` 和 `copy` 每批 200 个节点，不是原子操作。一个 Space 同时最多运行 4 个修改目录树的任务，导出另计 4 个，超出时返回 429 `too_many_jobs`。`copy` 在 `copies` 中返回新的 Entry。有 `write_root` 的成员只能修改其下的节点（403 `outside_write_root`）；删除的目录本身是或包含任何成员的 `write_root` 时返回 409 `directory_is_write_root`，Space 所有者也一样。有 `read_root` 的成员在 `from` 或 `path` 位于范围外时返回 404，目标在写入根路径外时返回 403 `outside_write_root`，无论目标处是否存在内容；删除的目录本身是或包含某个成员的 `read_root` 时返回 409 `directory_is_read_root`。需要 `knowledge:write`。

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

指南：[文件与版本](https://mirabase.io/zh/developers/files.md#tree)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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`。 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |
| `Prefer` | 请求头 | `string` | 可选 | `respond-async`：只有一条操作、本该返回 409 `subtree_too_large` 的请求改为异步任务执行，返回 202 `DevJobReceipt`。没超过上限时照常执行，不带 `Preference-Applied`；多条操作超过上限返回 422 `validation_error`，`field: "Prefer"`。其他偏好会被忽略。 |

### 请求体

`application/json` `DevTreeOperationsRequest` 原子执行：全部按顺序生效，或全部不生效。一次请求最多删除、恢复或复制 200 个节点，最多移动 1000 个。带 `branch` 时 `restore` 和 `copy` 返回 422（请改为回滚到检查点）。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `operations` | `DevTreeOperation[]` | 必填 | 1 到 200 个操作，按顺序执行。 1 到 200 项 |

### 响应

- `200` `application/json` `DevTreeOperationsResponse`
- `202` `application/json` `DevJobReceipt`

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。
- `Preference-Applied` `respond-async`。

### 错误状态

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

### 请求示例

```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":"/notes/drafts"}]}'
```

### 响应结构示例

```json
{}
```
