# 处理进度

文件写入后先变为可检索，记忆随后生成：等待单个文件可检索、跟踪批量导入进度，并识别检索时尚未处理完成的内容。

写入文件后，服务依次提取文本、建立索引并发布到搜索。这三步完成后，文件即可按语义检索；关联、分类、摘要和记忆在之后生成，不影响检索。请求体中 64 KiB 以内的文本在写入后立即可以按词检索，见 [检索](https://mirabase.io/zh/developers/retrieval.md#search)。

最新版本所处的阶段记在 [stage](https://mirabase.io/zh/developers/api/schemas.md#DevEntryProcessing.stage) 中：为 `enriching` 或 `ready` 时，搜索即可找到该版本。

## 等待单个文件可检索

[`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 返回最新版本的 `stage` 和 `progress`；排队等待期间还会返回 `queue`，说明排在前面的任务数和等待原因。SDK 的 `entries.waitUntil`（Python 为 `entries.wait_until`）会自动轮询该接口，默认等待至文件可检索；传入 `until: "ready"` 时则等待全部步骤完成。

curl:

```bash
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
// Returns once search finds the file ("enriching" or "ready"), or when it failed.
const status = await mirabase.entries.waitUntil({ path: "/notes/launch.md" }, {
  onProgress: (s) => console.log(s.stage, `${s.progress.done}/${s.progress.total}`),
});
if (status.stage === "failed") console.log(status.error?.code);
```

Python:

```python
# Returns once search finds the file ("enriching" or "ready"), or when it failed.
status = mb.entries.wait_until(
    {"path": "/notes/launch.md"},
    on_progress=lambda s: print(s["stage"], f"{s['progress']['done']}/{s['progress']['total']}"),
)
if status["stage"] == "failed":
    print(status["error"]["code"])
```

- 处理失败时，`waitUntil` 会返回最后获取的状态而不抛出异常，此时请检查 `error` 字段。失败的版本可通过 [`POST /v2/entries/{entry_id}/reprocess`](https://mirabase.io/zh/developers/api/entries.md#entries-reprocess) 重试。
- 超过等待时间（默认 10 分钟）时，SDK 抛出代码为 `wait_timeout` 的错误，服务端的处理继续进行。
- 只写入一个文件时，也可以在写入请求中带 `Prefer: wait`，见 [写入文件](https://mirabase.io/zh/developers/files.md#write)。

## 跟踪批量导入

导入大量文件时，无需逐个查询 Entry。[`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing) 按阶段统计 Space 中的 Entry，并返回其变为可检索的速率和预计剩余时间。SDK 的 `spaces.waitUntil`（Python 为 `spaces.wait_until`）会轮询该接口，直至 Space 中的全部 Entry 可检索；`onProgress` 会接收每次轮询获取的统计数据，可用于展示进度。

curl:

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

TypeScript:

```ts
// Waits until every Entry in the Space is searchable; failed Entries count as finished.
const summary = await mirabase.spaces.waitUntil({
  onProgress: ({ counts, eta_seconds }) => console.log(counts, eta_seconds),
});
console.log(`${summary.counts.failed} failed`);
```

Python:

```python
# Waits until every Entry in the Space is searchable; failed Entries count as finished.
summary = mb.spaces.wait_until(
    on_progress=lambda s: print(s["counts"], s.get("eta_seconds")),
)
print(summary["counts"]["failed"], "failed")
```

- 失败的 Entry 计入 `counts.failed`，失败原因可通过 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 查看。
- 记忆在文件可检索之后单独提炼，`memory` 报告仍在排队或运行的提炼任务。仅等待提炼的 Entry 仍计为可检索。如需等待记忆提炼完成，请传入 `until: "ready"`。
- 不同 Space 和账户的任务轮流执行，因此一个 Space 的大批量导入不会阻塞其他 Space 的新文件。

## 识别尚未处理完成的内容

所检索的 Space 中仍有 Entry 在处理时，`search`、`context` 和 `answer` 的响应带 `pending_processing`，其中 `entries` 是尚不可检索的 Entry 数。这些 Entry 的内容可能不在本次结果中：如果需要的内容可能在其中，请稍后再查询，或先等待处理完成。

```json
{
  "pack_id": "pck_...",
  "items": [
    "..."
  ],
  "pending_processing": {
    "entries": 12
  }
}
```

SDK 的 `context` 和 `answer` 会原样返回该字段；`search` 返回命中结果数组，该字段位于数组的 `pendingProcessing` 属性中（Python 为 `pending_processing`）。MCP 工具 `mira.search` 的结果同样包含 `pending_processing`。

## 处理队列已满时

账户排队的任务数超过上限时，写入请求会返回 429 `ingest_backlog`：`queue` 给出排队任务数和预计等待时间，`Retry-After` 为 30 到 600 秒。请按 `Retry-After` 等待后重试。SDK 仅在 `Retry-After` 不超过 `maxRetryAfterMs`（Python 为 `max_retry_after`，默认 60 秒）时自动等待并重试；超过时抛出 `MirabaseRateLimitError`，请读取 `retryAfterSeconds`（Python 为 `retry_after_seconds`）后自行等待，或调大该选项，见 [重试和幂等](https://mirabase.io/zh/developers/sdks.md#retries)。账户管理员可以随时通过 [`GET /v2/queue`](https://mirabase.io/zh/developers/api/usage.md#usage-queue) 查看队列。

## 下一步

- [文件与版本](https://mirabase.io/zh/developers/files.md)：写入、读取和修改文件。
- [检索与上下文](https://mirabase.io/zh/developers/retrieval.md)：在处理完成的内容上检索。
- [API 参考](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing)：处理进度的全部字段。
