# 提案

Agent 对不属于自己的文件提出的修改，以及对这些修改的审核。

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

## 读取提案

`GET /v2/proposals/{proposal_id}`

读取一个提案。只有作者和 Space 的审核人能看到；对其他人返回 404 `not_found`。需要 `knowledge:read`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 响应

- `200` `application/json` `DevProposal`

### 错误状态

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

### 响应结构示例

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "entry_id": "<entry_id>",
  "status": "open",
  "base_version_id": "<base_version_id>",
  "proposed_version_id": "<proposed_version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## 批准提案

`POST /v2/proposals/{proposal_id}/approve`

将提案内容写成文件的新版本，作者是提交提案的 Agent。只有审核人能操作，且只限其 `write_root` 以内。提交提案后文件已修改或已移入废纸篓时返回 409 `proposal_conflict`（含 `current_version_id`），提案保持打开状态，Agent 需要重新提交。已不在打开状态的提案返回 409 `proposal_closed`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevApproveProposalRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message` | `string` | 可选 | 成为新版本的 `message`，最多 120 个字符。 最长 120 |

### 响应

- `200` `application/json` `DevProposal`

### 错误状态

`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/proposals/$PROPOSAL_ID/approve" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应结构示例

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "entry_id": "<entry_id>",
  "status": "open",
  "base_version_id": "<base_version_id>",
  "proposed_version_id": "<proposed_version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## 查看提案改动

`GET /v2/proposals/{proposal_id}/diff`

将提案内容与 `base`（默认，即提案所基于的版本）或文件的 `latest` 比较，查看文件更新后还剩哪些改动。响应结构与 Entry 的 `diff` 相同。文件在废纸篓中时返回 404。需要 `knowledge:read`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `against` | 查询 | `base \| latest` | 可选 | 与提案内容比较的基准版本：`base`（默认，即提案基于的版本）或 `latest`（文件当前版本）。 默认 "base" |

### 响应

- `200` `application/json` `DevVersionDiff`

### 错误状态

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

### 响应结构示例

```json
{
  "entry_id": "<entry_id>",
  "from_version_id": "<from_version_id>",
  "to_version_id": "<to_version_id>",
  "identical": false,
  "basis": "original"
}
```

## 拒绝提案

`POST /v2/proposals/{proposal_id}/reject`

关闭提案而不修改文件。只有审核人能操作。已不在打开状态的提案返回 409 `proposal_closed`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevEmptyRequest`

### 响应

- `200` `application/json` `DevProposal`

### 错误状态

`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/proposals/$PROPOSAL_ID/reject" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应结构示例

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "entry_id": "<entry_id>",
  "status": "open",
  "base_version_id": "<base_version_id>",
  "proposed_version_id": "<proposed_version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## 撤回提案

`POST /v2/proposals/{proposal_id}/withdraw`

关闭自己提交的提案。已不在打开状态的提案返回 409 `proposal_closed`。需要 `knowledge:write`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevEmptyRequest`

### 响应

- `200` `application/json` `DevProposal`

### 错误状态

`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/proposals/$PROPOSAL_ID/withdraw" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应结构示例

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "entry_id": "<entry_id>",
  "status": "open",
  "base_version_id": "<base_version_id>",
  "proposed_version_id": "<proposed_version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## 列出提案

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

列出这个 Space 中你能看到的提案，最早的在前。需要 `knowledge:read`。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 |
| `status` | 查询 | `DevProposalStatus` | 可选 | 只保留这个状态的提案。默认 `open`。 默认 "open" |
| `entry_id` | 查询 | `DevId` | 可选 | 只保留针对这个文件的提案，用它的 Entry id 指定。 长度 1 到 256 |
| `author_id` | 查询 | `DevId` | 可选 | 只保留这个主体提交的提案。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevProposal[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

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

### 响应结构示例

```json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "entry_id": "<entry_id>",
      "status": "open",
      "base_version_id": "<base_version_id>",
      "proposed_version_id": "<proposed_version_id>",
      "size_bytes": 1,
      "media_type": "<media_type>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```
