# 数据结构

请求和响应用到的数据结构，从 OpenAPI 规格生成。

## DevAccountQueue

账户的处理队列：把写入的内容变为可检索内容的任务（解析、索引、发布和索引投影），以及之后的模型处理（摘要、分类、记忆）。计数单位是任务而不是文件，一个文件对应多个任务。查看单个文件请用 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing)。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `queued` | `integer` | 必填 | 等待中的任务数：`due` 与 `delayed` 之和。 |
| `due` | `integer` | 必填 | 已可运行、正在等待工作进程的任务。 |
| `delayed` | `integer` | 必填 | 正在等待重试退避或预定时间的任务。 |
| `running` | `integer` | 必填 |  |
| `paused` | `boolean` | 必填 | 服务运营方暂停了本账户的处理时为 true；恢复之前不会运行任何任务。 |
| `paused_at` | `string (date-time)` | 可选 |  |
| `oldest_queued_seconds` | `integer` | 可选 | 最早的就绪任务已等待的时长。没有就绪任务时不返回。 |
| `eta_seconds` | `integer` | 可选 | 就绪任务预计还需的秒数，根据服务过去 15 分钟的吞吐量和本账户应得的公平份额估算。仅为估计值：暂停期间或近期没有吞吐量可供参考时不返回。 |
| `limit` | `integer` | 必填 | `tenant_queued_jobs`：使内容可检索的排队任务（解析、识别、建索引、发布）超过此数时，写入返回 429 `ingest_backlog`。文件可检索之后排队的摘要、分类、关联和记忆任务另有上限，为此数的五倍，因此写入仍被接受时 `queued` 可能大于 `limit`。 |
| `as_of` | `string (date-time)` | 必填 |  |

## DevActivityActor

一个主体在这段时间里改了什么。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `principal_id` | `DevId` | 可选 | 谁做的改动。服务自己做的改动没有这个字段。 |
| `last_changed_at` | `string (date-time)` | 必填 | 这个主体最近一次改动的时间。 |
| `change_count` | `integer` | 必填 | 这个主体在这段时间里做了多少次改动。 |
| `files` | `DevActivityFile[]` | 必填 | 被改动的 Entry，最近改的排在前面，最多 50 个。 |
| `files_truncated` | `true` | 可选 | 这个主体改动的 Entry 超过 50 个时出现，值为 true：`files` 里是最近的 50 个。 |

## DevActivityFile

一个主体在该时间段内改动过的一个 Entry，按最近一次改动后的状态返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 被改动的 Entry。 |
| `path` | `DevPath` | 可选 | 最近一次改动时它在哪个路径。没有路径的 Entry 没有这个字段。 |
| `op` | `DevChangeOp` | 必填 | 最近一次改动：`create`、`update`、`move`、`delete` 或 `restore`。 |
| `version_id` | `DevId` | 可选 | 最近一次改动写入的版本，仅在产生了新版本时返回。 |
| `changed_at` | `string (date-time)` | 必填 | 最近一次改动提交的时间。 |
| `change_count` | `integer` | 必填 | 这个主体在这段时间里改了这个 Entry 多少次。 |

## DevAnswer

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `status` | `DevAnswerStatus` | 必填 | `answered`；证据不足以回答时是 `abstained`。 |
| `answer` | `string` | 必填 | 放弃回答时为空。用 `[cN]` 引用证据。 |
| `reason` | `DevAnswerAbstainReason` | 可选 | 放弃回答时出现。 |
| `citations` | `DevAnswerCitation[]` | 必填 | 只列 `answer` 引用了的证据，按首次引用的顺序。 |
| `evidence` | `DevAnswerEvidence[]` | 可选 | 仅在请求带 `include: ["evidence"]` 时返回：模型读过的每一条证据，按读取顺序排列。 |
| `evidence_count` | `integer` | 必填 | 交给模型的条目数。 |
| `pack_id` | `DevId` | 必填 | 用 [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-contextfeedback) 报告你用到了什么。 |
| `partial` | `boolean` | 必填 | 检索的某一路降级时为 true，这时证据可能不全。 |
| `pending_processing` | `DevPendingProcessing` | 可选 | 仅当所检索的 Space 中仍有 Entry 在处理时返回：回答可能缺少这些 Entry 的内容。 |
| `route` | `DevContextRoute` | 必填 | 证据是怎么选出来的，和上下文包里的含义相同。 |
| `explain` | `DevAnswerExplain` | 可选 | 仅当请求设置了 `explain` 时返回。 |

## DevAnswerAbstainReason

`no_evidence`：没有可引用的内容，没有调用模型。`model_abstained`：证据回答不了这个问题。`insufficient_evidence`：修正一次之后回答仍然没有引用任何内容。

取值: `no_evidence | model_abstained | insufficient_evidence`

## DevAnswerCitation

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `citation_id` | `string` | 必填 | 在 `answer` 里以 `[cN]` 出现。 |
| `entry_id` | `DevId` | 必填 | 这段内容所在的 Entry。 |
| `version_id` | `DevId` | 必填 | 读取这段内容时所用的版本。 |
| `space_id` | `DevId` | 可选 | 该 Entry 所在的 Space。账户记忆没有这个字段。 |
| `path` | `DevPath` | 可选 | 文件的路径。没有路径的 Entry 不带这个字段。 |
| `url` | `string` | 可选 | 从网址导入的 Entry：该网址，用于链接回原网页。文件则带 `path`。 |
| `occurred_at` | `string (date-time)` | 可选 | 这段内容所说的事发生的时间：Entry 的 `occurred_at`，对话则是其中消息的时间。来源没有时间时不带这个字段。 |
| `modified_at` | `string (date-time)` | 可选 | 读取这段内容时所用的版本写入的时间。和 `occurred_at` 一起用来分辨新旧。 |
| `stated_date` | `string (date)` | 可选 | 段落内容截至哪天，格式 `YYYY-MM-DD`。只认年月日写全的日期，句子中间提到的日期一律不算：“自 2026-03-01 起，API 运行在集群 B 上”说的是现在的情况，不是 2026-03-01 那天的情况。按以下顺序取第一个有日期的来源：段落标明为自己日期的日期（前面有“as of”“updated”“last modified”“截至”“更新于”，或后面有“updated”“更新”）；所在小节标题里的日期；段落里一行、一个列表项或一个分句开头的日期；文档 front matter（`modified`、`updated`、`date`、`created`）或顶部标题里的日期。同一来源有几个日期时，取不晚于该版本写入时间的最晚一个。都没有时不返回：宁可不给日期，也不给错的日期。多个文件同时写入时，用它区分较早和较新的记录；有 `occurred_at` 时优先用 `occurred_at`。 |
| `stated_date_from` | `text \| heading \| document` | 可选 | `stated_date` 取自哪里：段落正文（`text`）、段落上方的小节标题（`heading`）或文档开头（`document`）。 |
| `title` | `string` | 必填 | Entry 的标题；文件的标题就是文件名。 |
| `source` | `DevContextSource` | 必填 | 这段内容来自哪个上下文来源。 |
| `text` | `string` | 必填 | 模型读到的段落。 |
| `explain` | `DevHitExplain` | 可选 | 仅当请求设置了 `explain` 时返回。 |

## DevAnswerEvidence

模型读过的一条证据，形式是不带 `text` 的引用。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `citation_id` | `string` | 必填 | 模型引用它时可用的 id。 |
| `entry_id` | `DevId` | 必填 | 这段内容所在的 Entry。 |
| `version_id` | `DevId` | 必填 | 读取这段内容时所用的版本。 |
| `space_id` | `DevId` | 可选 | 该 Entry 所在的 Space。账户记忆没有这个字段。 |
| `path` | `DevPath` | 可选 | 文件的路径。没有路径的 Entry 不带这个字段。 |
| `url` | `string` | 可选 | 从网址写入的 Entry 上：那个网址。 |
| `occurred_at` | `string (date-time)` | 可选 | 与引用上的同名字段相同。 |
| `modified_at` | `string (date-time)` | 可选 | 与引用上的同名字段相同。 |
| `stated_date` | `string (date)` | 可选 | 与引用上的同名字段相同。 |
| `stated_date_from` | `text \| heading \| document` | 可选 | 与引用上的同名字段相同。 |
| `title` | `string` | 必填 | Entry 的标题；文件的标题就是文件名。 |
| `source` | `DevContextSource` | 必填 | 这段内容来自哪个上下文来源。 |
| `explain` | `DevHitExplain` | 可选 | 仅当请求设置了 `explain` 时返回。 |

## DevAnswerExplain

回答上的 `explain`：检索摘要，以及每个句子使用了哪些引用。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `terms` | `string[]` | 必填 | 词法检索所用的词。 |
| `candidates` | `DevExplainCandidateCount[]` | 必填 | 每一路检索中你能读取的候选数。没有返回任何你能读取的结果的那一路检索不列出。 |
| `fused_count` | `integer` | 必填 | 各路检索合并后你能读取的候选数。 |
| `rerank` | `DevExplainRerankSummary` | 必填 |  |
| `clauses` | `string[]` | 可选 | 任务陈述了多件事时：分别检索的各个子句。 |
| `sentences` | `DevAnswerSentence[]` | 必填 | 拆分为句子的回答。放弃回答时为空。 |

## DevAnswerRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `question` | `string` | 必填 | 要回答的问题，1 到 4000 个字符。 长度 1 到 4000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则使用调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `purpose` | `DevContextPurpose` | 可选 | 回答用来做什么，与 `context` 的同一个参数：`task`、`coding`、`research` 或 `audit`。 |
| `weights` | `DevContextWeights` | 可选 | 与 `context` 相同。不传时，回答不使用 `changes` 和 `skills` 两个来源：无论问题是什么，它们列出的都是最近的文件和技能。这时 `route.rules_fired` 会列出 `source:off:changes:answer_default` 和 `source:off:skills:answer_default`。要包含它们，请传 `weights`。 |
| `tier` | `DevContextTier` | 可选 | 检索证据时投入的工作量，与 `context` 上的含义相同：`fast`、`standard` 或 `deep`。 默认 "standard" |
| `budget_tokens` | `integer` | 可选 | 模型读取的证据的预算。 500 到 16000，默认 4000 |
| `history` | `DevAnswerTurn[]` | 可选 | 之前的对话轮次，最早的在前。追问会和它所追问的问题一起搜索。各轮合计超过 12,000 个字符时，最早的几轮会被略去。 最多 10 项 |
| `output_language` | `string` | 可选 | BCP 47 语言标签，如 `en` 或 `zh-CN`。只影响 `answer` 的语言。 最长 35 |
| `filter` | `DevRetrievalFilter` | 可选 | 缩小答案可引用的证据范围，和 `context` 相同。 |
| `include` | `evidence[]` | 可选 | `["evidence"]` 在响应里增加 `evidence`：模型读过的每一条证据，不带正文。用它查看回答除了引用的段落之外还依据了什么。 1 项 |
| `stream` | `boolean` | 可选 | 为 true 时以 `text/event-stream` 流式返回回答，而不是单个 JSON 响应体。每个事件有一个 `id`（按顺序为 1、2、3……）、一个 `event` 名称和一行 JSON 格式的 `data`： - `start`（`DevAnswerStreamStart`）：检索完成后、任何文本之前发送一次，带 `request_id`、`pack_id` 和交给模型的证据数量。在检索阶段失败的流没有 `start`。 - `delta`（`DevAnswerStreamDelta`）：回答的下一段文本，按顺序拼接。 - `replace`（`DevAnswerStreamReplace`）：至多发送一次，紧接在 `final` 之前，表示已流式返回的文本不是最终回答（服务修正了没有引用的草稿，或回答改为放弃）。丢弃已流式返回的文本，显示 `final.answer`。 - `final`（`DevAnswer`）：与本操作不带 `stream` 时返回的 JSON 相同，以它为准。 - `error`（`DevErrorResponse`）：与 HTTP 错误相同的错误信封，其中的 `status` 是这个请求本应得到的状态码。丢弃已流式返回的文本：没有生成回答。`retryable` 说明重新提问是否有用。 `final` 和 `error` 只发送其中一个，它是最后一个事件，之后流关闭。没有收到这两者就结束的流是被中断了：按请求失败处理，重新提问。以 `:` 开头的行是注释，在流打开时以及每空闲 15 秒时发送，用于保持连接，不带任何内容。流不能续传：`id` 只表示顺序，`Last-Event-ID` 会被忽略。忽略未知的事件名，后续可能新增事件。关闭连接会取消回答。认证、校验和等待空闲名额都在流打开之前完成，因此这些错误是普通的 HTTP 响应。 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

## DevAnswerSentence

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | 必填 | `answer` 中的一个句子，带有其中的 `[cN]` 标记。 |
| `citation_ids` | `string[]` | 必填 | 该句子中的引用，按首次出现的顺序排列。 |

## DevAnswerStatus

取值: `answered | abstained`

## DevAnswerStreamDelta

流式回答中 `delta` 事件的 `data`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | 必填 | 回答的下一段文本，接在之前的文本后面。 |

## DevAnswerStreamReplace

流式回答中 `replace` 事件的 `data`：一个空对象。已流式返回的文本作废。

取值: `object`

## DevAnswerStreamStart

流式回答中 `start` 事件的 `data`：检索完成后、任何文本之前已知的信息。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `request_id` | `string` | 必填 | 请求 id，与响应头 `X-Request-Id` 相同。反馈问题时请带上它。 |
| `pack_id` | `DevId` | 必填 | 与 `final` 事件中的 `pack_id` 相同。 |
| `evidence_count` | `integer` | 必填 | 交给模型的条目数。为 0 表示回答将是放弃，原因为 `no_evidence`。 |
| `partial` | `boolean` | 必填 | 检索的某一路降级时为 true，这时证据可能不全。 |
| `evidence` | `DevAnswerEvidence[]` | 可选 | 只在请求带 `include: ["evidence"]` 时出现：模型读取的每一条证据，与 `final` 中的列表相同。 |

## DevAnswerTurn

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `role` | `user \| assistant` | 必填 | 谁说的：`user` 或 `assistant`。 |
| `content` | `string` | 必填 | 说了什么，1 到 4000 个字符。 长度 1 到 4000 |

## DevApiKey

Key 是凭据，不是主体，只能收窄所属主体的权限。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 以 `key_` 开头。它不是密钥本身：令牌只在创建或轮换 Key 时返回一次。 |
| `principal_id` | `DevId` | 必填 | 这个 Key 代表的主体。 |
| `name` | `string` | 必填 | 你为这个 Key 指定的名称。 |
| `prefix` | `string` | 必填 | 令牌的非敏感前缀，用于在列表中识别 Key。 |
| `capabilities` | `DevCapability[]` | 必填 | 这个 Key 能做什么。不会超过它所属主体的能力。 |
| `allowed_space_ids` | `DevId[]` | 可选 | 不存在表示没有收窄到特定 Space。 |
| `metadata_scope` | `DevMetadataScope` | 可选 | Key 受限的元数据范围。没有这个字段表示不按元数据限制。 |
| `expires_at` | `string (date-time)` | 可选 | 过了这个时间 Key 就失效。不过期的 Key 不带这个字段。 |
| `revoked_at` | `string (date-time)` | 可选 | Key 被吊销的时间。仍然有效时不带这个字段。 |
| `last_used_at` | `string (date-time)` | 可选 | 这个 Key 最近一次调用 API 的时间，精确到分钟。尚未使用时不返回该字段。 |
| `created_by` | `DevId` | 必填 | 签发它的主体。 |
| `issued_by_key_id` | `DevId` | 可选 | 签发或轮换出这个 Key 的 Key。未通过 Key 签发时不存在。 |
| `created_at` | `string (date-time)` | 必填 | 签发时间。 |

## DevApproveProposalRequest

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

## DevArchive

导出的归档。`expires_at` 之后删除，或 Space 内有文件被彻底删除时立即删除。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `size_bytes` | `integer` | 必填 | 归档的字节数。 |
| `sha256` | `string` | 必填 | 归档的十六进制 SHA-256。 |
| `media_type` | `string` | 必填 | `application/x-tar`。 |
| `expires_at` | `string (date-time)` | 必填 | 归档被删除的时间。 |

## DevArchiveUrl

导出归档的短期签名 URL。在 `expires_at` 之前，任何持有者均可下载，吊销 Key 也无法阻止：请像保管 Key 一样保管它。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | `string (uri)` | 必填 | 签名地址。使用普通的 `GET` 请求获取。 |
| `method` | `GET` | 必填 | 恒为 `GET`。 |
| `expires_at` | `string (date-time)` | 必填 | UTC。最晚是请求后 5 分钟。 |
| `job_id` | `DevId` | 必填 | 长度 1 到 256 |
| `size_bytes` | `integer` | 必填 | 归档的字节数。 |
| `media_type` | `string` | 必填 | `application/x-tar`。下载响应带这个类型，以及 `Content-Disposition: attachment` 和 `Cache-Control: private, no-store`。 |
| `sha256` | `string` | 必填 | 归档的十六进制 SHA-256。 |

## DevAuditEvent

只含标识符。审计事件不含用户内容。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `action` | `string` | 必填 | 稳定的动作名，如 `entry.read`、`acl.set`、`api_key.revoke`。 |
| `outcome` | `DevAuditOutcome` | 必填 | 这个动作的结果：`allowed`、`denied` 或 `failed`。 |
| `principal_id` | `DevId` | 必填 | 执行动作的主体。 |
| `key_id` | `DevId` | 可选 | 请求不是用 API Key 认证时不存在。 |
| `space_id` | `DevId` | 可选 | 动作不属于单一 Space 时不存在。 |
| `resource_kind` | `string` | 必填 | 动作对象：`entry`、`version`、`recall`、`tenant`、`tool`、`api_key`、`memory`、`principal`、`space`、`branch`、`proposal`、`snapshot`、`webhook`、`job`、`dream` 或 `developer_account`。以后可能增加新的类型。 |
| `resource_id` | `DevId` | 可选 | 为 `entry` 和 `version` 时，该字段是 Entry id，版本由 `version_id` 指定。 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `request_id` | `string` | 可选 | 引起这条事件的请求，与错误体里 `request_id` 是同一个 id。 |
| `created_at` | `string (date-time)` | 必填 | 事件记录的时间。 |

## DevAuditOutcome

取值: `allowed | denied | failed`

## DevBacklog

队列已满时账户的处理队列。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `queued` | `integer` | 必填 | 账户中已达上限的那一类排队任务数。对限定了部分 Space 或元数据范围的 Key，返回上限值。 |
| `limit` | `integer` | 必填 | 使内容可检索的任务（解析、识别、建索引、发布）排满时为 `tenant_queued_jobs`；摘要、分类、关联和记忆任务排满时为它的五倍。 |
| `paused` | `boolean` | 必填 | 服务运营方暂停本账户的处理时为 true：在处理恢复之前，等待不起作用。对限定了部分 Space 或元数据范围的 Key 始终为 false。 |
| `eta_seconds` | `integer` | 可选 | 完成账户全部就绪任务预计所需的秒数。无法估计时不返回；对限定了部分 Space 或元数据范围的 Key 也不返回。 |

## DevBranch

叠在 Space 上的写时复制层。读取时先查分支，未命中则回退到主线最新版本，因此分支未修改过的路径显示主线当前的内容，而非创建分支时的内容。分支里的内容不解析、不索引、不提炼记忆，合并之前 `search` 和 `context` 都看不到。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `name` | `string` | 必填 | 分支的名字。分支活跃期间，路径和 `?branch=` 里可以用它代替 id。 |
| `state` | `DevBranchState` | 必填 | 已过 `expires_at` 但清扫任务还没处理到的分支也算 `abandoned`。 |
| `parent_branch_id` | `DevId` | 可选 | 从主线创建的分支没有这个字段。节点是复制过来的，没有父分支链。 |
| `base_change_seq` | `integer` | 必填 | 开分支时主线的变更序号。 |
| `main_changed_paths` | `integer` | 必填 | 自 `base_change_seq` 以来主线变更的路径数。分支未修改过的路径会随主线变化，可通过该数值看出。事件保留 90 天，因此该数值可能偏少。 |
| `created_by` | `DevId` | 必填 | 长度 1 到 256 |
| `ttl_days` | `integer` | 必填 | 每次写入把 `expires_at` 往后推的天数。 |
| `expires_at` | `string (date-time)` | 必填 | 分支的到期时间。过了这个时间分支被放弃，随后被回收。 |
| `created_at` | `string (date-time)` | 必填 | 分支创建的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 分支最近一次变动的时间。 |

## DevBranchChange

分支视角下的变更。`source: branch` 的事件是压缩过的，每个路径只留最新一次写入，所以把它们当作要重读的路径。`source: main` 的事件是这个分支穿透读到的主线变更。`seq` 按来源各自计数。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source` | `branch \| main` | 必填 | `branch`：在这个分支上做的改动。`main`：该分支穿透读到的主线改动。 |
| `seq` | `integer` | 必填 | 在它的 `source` 之内的序号。 |
| `op` | `DevChangeOp` | 必填 | 改动的种类：`create`、`update`、`move`、`delete` 或 `restore`。 |
| `path` | `DevPath` | 可选 | 长度 1 到 4096 |
| `kind` | `DevBranchNodeKind` | 可选 | `branch` 的改动才有：这个路径是目录、文件还是符号链接。 |
| `entry_id` | `DevId` | 可选 | 长度 1 到 256 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `actor_principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 改动发生的时间。 |

## DevBranchChangeFeed

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevBranchChange[]` | 必填 | 这一页的事件。 |
| `cursor` | `DevCursor` | 必填 | 传回来继续读取。 |
| `has_more` | `boolean` | 必填 | 还有就绪事件时为 true，请立即带 `cursor` 再次调用。 |

## DevBranchDiffItem

一个改过的路径，与这个分支第一次改它时主线上的版本比较。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `change` | `DevBranchDiffOp` | 必填 | 分支对这个路径做的是新增、修改还是删除。 |
| `kind` | `DevBranchNodeKind` | 必填 | 这个路径在分支上是目录、文件还是符号链接。 |
| `size` | `integer` | 可选 | 文件才有：分支上内容的字节数。 |
| `mode` | `644 \| 755` | 可选 | 文件才有：`644` 或 `755`。 |
| `sha256` | `string` | 可选 | 文件才有：分支上内容的十六进制 SHA-256。 |
| `base_version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `unified_diff` | `string` | 可选 | 只有文本文件有。字节的差异无法按行看出时为空。 |
| `diff_omitted` | `too_large` | 可选 | 文本文件的 diff 太大无法计算时出现。 |

## DevBranchDiffOp

取值: `added | modified | deleted`

## DevBranchFileDeletion

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `deleted` | `true` | 必填 | 恒为 true：这个路径在分支上已经隐藏。 |

## DevBranchFileMeta

分支改过的路径上的 `view=meta`。穿透到主线的路径返回 Entry。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `kind` | `file \| symlink` | 必填 | 这个路径在分支上是文件还是符号链接。 |
| `size` | `integer` | 可选 | 只有文件有：字节数。 |
| `media_type` | `string` | 可选 | 只有文件有：写入时带的媒体类型。 |
| `mode` | `644 \| 755` | 可选 | 只有文件有：`644` 或 `755`。 |
| `sha256` | `string` | 可选 | 只有文件有：内容的十六进制 SHA-256。 |
| `etag` | `string` | 可选 | 仅限文件：下次写入时在 `If-Match` 中传回。它是内容哈希，不是版本。 |
| `link_target` | `string` | 可选 | 只有符号链接有：链接指向哪里。 |
| `updated_at` | `string (date-time)` | 必填 | 分支最近一次改这个路径的时间。 |

## DevBranchFileText

分支改过的路径上的 `view=text`。只有文本文件有：分支里的内容不解析。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `view` | `text` | 必填 | 恒为 `text`。 |
| `text` | `string` | 必填 | 文件内容，UTF-8 文本。 |

## DevBranchFileWrite

写入分支的结果。`etag` 是内容哈希，不是版本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `sha256` | `string` | 必填 | 写入字节的十六进制 SHA-256。 |
| `size` | `integer` | 必填 | 字节数。 |
| `media_type` | `string` | 必填 | 随文件存下的媒体类型。 |
| `mode` | `644 \| 755` | 必填 | `644` 或 `755`。 |
| `etag` | `string` | 必填 | 文件在分支上的 ETag，带引号。下一次写入时放进 `If-Match`。 |
| `version_id` | `string` | 必填 | 去掉引号的 `etag`。`changes?branch=` 用同一个 `version_id` 报告这次写入。 |
| `created` | `boolean` | 必填 | 这次写入之前路径上什么都没有时是 true，替换已有文件时是 false。 |
| `changed` | `boolean` | 必填 | 字节、媒体类型和权限位都没变时为 false。 |

## DevBranchNodeKind

取值: `dir | file | symlink`

## DevBranchObject

存储在分支中的对象。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `sha256` | `string` | 必填 | 对象的十六进制 SHA-256，也是它存放用的名字。 |
| `size` | `integer` | 必填 | 字节数。 |
| `created` | `boolean` | 必填 | 这个分支已经有这个对象时是 false。 |

## DevBranchRef

分支 id，或活跃分支的名字。id 以 `brn_` 开头。会重试的调用里请用 id：第一个分支关闭后，名字可能指向另一个分支。

取值: `string`

## DevBranchState

分支的状态。`active`：可写入。`merged`：已合并到主线，只读。`abandoned`：未合并即关闭。已合并或已放弃的分支在结束 `branch_reclaim_days` 天后被回收。

取值: `active | merged | abandoned`

## DevCapability

一个 Key 可以做什么。请求按 Key 和它的主体共同持有的能力行事（即 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 里的 `effective_capabilities`）。每个已上线的操作在 `x-mirabase-capability` 里写明它需要哪一项。 - `knowledge:read`：读取 Space、文件、Entry、记忆和变更流，调用搜索和上下文。 - `knowledge:answer`：调用 [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer)，需同时持有 `knowledge:read`。 - `knowledge:write`：写入、编辑文件和 Entry，把它们移入废纸篓或恢复；导入和上传；操作分支和快照；处理提案；写入 Agent 自己的记忆；关闭或遗忘提炼记忆。 - `knowledge:manage`：创建、修改和删除 Space 及其成员，彻底删除 Entry，管理 Webhook。 - `memory:confirm`：写入、审核、更正和撤销已确认的记忆。带着它导入的对话提炼出的是已确认的记忆，而不是候选。 - `memory:candidate`：可以授予，但没有任何 `/v2` 操作需要它。

取值: `knowledge:read | knowledge:answer | knowledge:write | knowledge:manage | memory:candidate | memory:confirm`

## DevChange

文件或其他 Entry 的一次变更。目录自身不产生事件：移动目录时，里面每个文件各有一条 `move`。`path` 是当时的路径，Entry 没有路径或已彻底删除时不存在。事件可能重复，请按 `entry_id` 应用。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `seq` | `integer` | 必填 | 事件在该 Space 变更流中的位置。序号按提交顺序排列，没有空缺。 |
| `op` | `DevChangeOp` | 必填 | 改动的种类：`create`、`update`、`move`、`delete` 或 `restore`。 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 可选 | 长度 1 到 4096 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `actor_principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 改动提交的时间。 |

## DevChangeFeed

变更流的一页。它用 `cursor`，而不是 `next_cursor`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevChange[]` | 必填 | 这一页的事件，按提交顺序排列。 |
| `cursor` | `DevCursor` | 必填 | 传回来继续读取。序号按提交顺序排列，没有空洞。 |
| `has_more` | `boolean` | 必填 | 还有就绪事件时为 true，请立即带 `cursor` 再次调用。 |

## DevChangeOp

改动的种类。`create`：新建 Entry。`update`：产生新版本，或编辑处理失败后退回上一个版本。`move`：路径改变，`path` 是新路径。`delete`：移入废纸篓或已彻底删除。`restore`：从废纸篓恢复。

取值: `create | update | move | delete | restore`

## DevCheckpoint

某一时刻分支自己的改动。穿透到主线的路径不会被固定。最新的在前。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `name` | `string` | 必填 | 创建时指定的名称。 |
| `git` | `DevCheckpointGit` | 可选 |  |
| `node_count` | `integer` | 必填 | 这个检查点包含的改动路径数。 |
| `created_by` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 检查点建立的时间。 |

## DevCheckpointGit

原样存取，最大 4 MiB。键由写入它的客户端（`mirabase` CLI）决定。只有一条规则：顶层的 `remote_url` 不能带凭据。

取值: `object`

## DevCompleteUploadRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `parts` | `DevCompletedPart[]` | 必填 | 文件的每一个分片，各带它的 `PUT` 返回的 `ETag`。 至少 1 项 |
| `session_id` | `string` | 可选 | 你为该文件所出自的对话指定的 id，与 `PUT files?session_id=` 相同：记录在本次完成上传所创建的版本上，可通过 `lineage` 查看。仅用于主线：分支上传传入该字段返回 422。 长度 1 到 256 |
| `occurred_at` | `string (date-time)` | 可选 | 文件内容发生的时间，例如录音或录像的录制时间。检索的 `occurred_from` / `occurred_to` 以此为准，段落中也会返回该时间；未提供时以文件写入时间为准。 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据，与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 上的 `metadata` 相同。检索的 `filter.metadata` 按它匹配。 |
| `memory_exclude` | `boolean` | 可选 | 为 `true` 时该文件不参与记忆提炼：文件照常保存、建立索引并可检索，但不会从中提炼记忆；为 `false` 时重新提炼。与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关。 |

## DevCompletedPart

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `part_number` | `integer` | 必填 | 分片编号，从 1 开始。 不小于 1 |
| `etag` | `string` | 必填 | 该分片 `PUT` 响应里的 `ETag` 头。 |

## DevContentUrl

原始字节的短期签名 URL。在 `expires_at` 之前，任何持有者均可下载，吊销 Key 也无法阻止：请像保管 Key 一样保管它。URL 中不含文件名。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | `string (uri)` | 必填 | 签名地址。使用普通的 `GET` 请求获取。 |
| `method` | `GET` | 必填 | 恒为 `GET`。 |
| `expires_at` | `string (date-time)` | 必填 | UTC。最晚是请求后 5 分钟。 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `size_bytes` | `integer` | 必填 | 原件的字节数。 |
| `media_type` | `string` | 必填 | 下载响应带这个 `Content-Type`，以及 `Content-Disposition: attachment` 和 `Cache-Control: private, no-store`。 |
| `sha256` | `string` | 可选 | 原始字节的十六进制 SHA-256，已知时提供。 |

## DevContentView

取值: `text | table | recognized`

## DevContextChange

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `create \| update \| move \| restore` | 必填 | `create`、`update`、`move` 或 `restore`。 |
| `at` | `string (date-time)` | 必填 | UTC，精确到微秒。 |

## DevContextFeedbackRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `used_citation_ids` | `string[]` | 必填 | 包里你实际用到的 `citation_id`。只传引用，不传内容。报告会累加：重复报告或分几次报告都安全。 1 到 256 项 |

## DevContextFlag

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | `stale \| superseded \| conflict \| agent_written` | 必填 | `stale`、`superseded`、`conflict` 或 `agent_written`。 |
| `citation_id` | `string` | 可选 | `conflict` 时：与这一条矛盾的条目。 |
| `grant_id` | `string` | 可选 | `agent_written` 时出现。 |

## DevContextItem

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 可选 | 长度 1 到 256 |
| `title` | `string` | 必填 | 这段内容出自的 Entry 的标题。 |
| `text` | `string` | 必填 | 一个段落。`skills` 条目为一行描述，正文按 `path` 读取。 |
| `citation_id` | `string` | 必填 | 在该上下文包内标识此条目，如 `c1`。通过 `feedback` 报告实际使用的条目时传入该值。 |
| `source` | `DevContextSource` | 必填 |  |
| `path` | `DevPath` | 可选 | 长度 1 到 4096 |
| `url` | `string` | 可选 | 从网址导入的 Entry：该网址，用于链接回原网页。文件则带 `path`。 |
| `occurred_at` | `string (date-time)` | 可选 | 这段内容所说的事发生的时间：Entry 的 `occurred_at`，对话则是其中消息的时间。来源没有时间时不带这个字段。 |
| `modified_at` | `string (date-time)` | 可选 | 读取这段内容时所用的版本写入的时间。和 `occurred_at` 一起用来分辨新旧。 |
| `stated_date` | `string (date)` | 可选 | 段落内容截至哪天，格式 `YYYY-MM-DD`。只认年月日写全的日期，句子中间提到的日期一律不算：“自 2026-03-01 起，API 运行在集群 B 上”说的是现在的情况，不是 2026-03-01 那天的情况。按以下顺序取第一个有日期的来源：段落标明为自己日期的日期（前面有“as of”“updated”“last modified”“截至”“更新于”，或后面有“updated”“更新”）；所在小节标题里的日期；段落里一行、一个列表项或一个分句开头的日期；文档 front matter（`modified`、`updated`、`date`、`created`）或顶部标题里的日期。同一来源有几个日期时，取不晚于该版本写入时间的最晚一个。都没有时不返回：宁可不给日期，也不给错的日期。多个文件同时写入时，用它区分较早和较新的记录；有 `occurred_at` 时优先用 `occurred_at`。 |
| `stated_date_from` | `text \| heading \| document` | 可选 | `stated_date` 取自哪里：段落正文（`text`）、段落上方的小节标题（`heading`）或文档开头（`document`）。 |
| `is_current_version` | `false` | 可选 | 有比这个更新的版本生效时出现，值为 false。 |
| `flags` | `DevContextFlag[]` | 可选 | 没有时不出现。 |
| `freshness` | `pending_index` | 可选 | `pending_index` 表示条目来自新鲜缓冲，只是词法匹配。 |
| `memory_kind` | `string` | 可选 | `memory` 条目上出现。 |
| `change` | `DevContextChange` | 可选 | `changes` 条目上出现。 |
| `memory` | `DevRoutedMemory` | 可选 | 仅在开启证据化记忆的部署上提供：从这段原文提炼出的已确认记忆。一次响应里每个文件最多一条。计入 `tokens_used`。 |
| `explain` | `DevHitExplain` | 可选 | 仅当请求设置了 `explain` 时返回。不计入 `tokens_used`。 |

## DevContextOmitted

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `count` | `integer` | 必填 | 符合条件但未纳入的段落数。 |
| `max_score` | `number \| null` | 必填 | 它们当中的最高分；没有可报的分数时为 null。 |

## DevContextPurpose

取值: `task | coding | research | audit`

## DevContextRendered

上下文包的文本形式，仅在请求设置了 `render` 时返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | 必填 | 首行说明这是参考材料，随后是记忆视图（若包中有），接着在各自的 `[cN]` 编号下列出每个条目及其来源、时间和注意事项（如旧版本、已被替换的值）。同一个包渲染出的文字逐字相同，不增不减。 |
| `tokens` | `integer` | 必填 | 使用该包的分词器计算的 `text` token 数。设为 `render: "text"` 时不计入 `tokens_used`：它是同一份内容的另一种形式。设为 `render: "compact"` 时等于 `tokens_used`。 |

## DevContextRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task` | `string` | 必填 | 这份上下文的用途，以自然语言描述。任务包含多个事项时，会分别为每个事项检索。 长度 1 到 1000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则使用调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `purpose` | `DevContextPurpose` | 可选 | 上下文的用途（`task`、`coding`、`research` 或 `audit`）。设置后将跳过意图推断。 |
| `weights` | `DevContextWeights` | 可选 | 在各来源之间调整预算。不传则使用该用途对应的比例。 |
| `tier` | `DevContextTier` | 可选 | `fast` 不调用模型，只按词面匹配；`standard` 加上语义检索和重排；`deep` 查看两倍的候选。 默认 "standard" |
| `budget_tokens` | `integer` | 可选 | 覆盖整个响应，不只是 `items`。设为 `render: "compact"` 时改为覆盖 `rendered.text`，即放入提示词的文本。 500 到 16000，默认 4000 |
| `have_memory_etag` | `string` | 可选 | 仍与 `memory_view_etag` 一致时省略 `memory_view`。 长度 1 到 128 |
| `filter` | `DevRetrievalFilter` | 可选 | 在排序之前缩小搜索范围。作用于所有读取 Entry 的来源；`memory_view` 不受过滤。 |
| `render` | `text \| compact` | 可选 | 设为 `text` 时响应增加 `rendered`：将同一上下文包排版为可直接放入提示词的文本，每个来源列在其引用 id 下。自行使用 `items` 组装提示词时无需传入。设为 `compact` 时以更简短的版式增加 `rendered`（每个来源一行，带出处和一个时间；对话片段中重复的消息时间戳只写一次），并按这段文本而非 JSON 响应计算 `budget_tokens` 和 `tokens_used`，因此同样的预算可容纳更多证据。当模型直接读取该文本时使用此值。`items` 仍包含全部 id、时间和定位信息。 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

## DevContextResponse

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pack_id` | `DevId` | 必填 | 这个上下文包的标识。用 [`POST /v2/retrieval/context/{pack_id}/feedback`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-contextfeedback) 回报你用了哪些。 |
| `memory_view_etag` | `string` | 可选 | 下次作为 `have_memory_etag` 传回。记忆来源关闭或预算不足以容纳视图时不返回。 |
| `memory_view` | `DevMemoryView` | 可选 | `have_memory_etag` 匹配时没有。 |
| `items` | `DevContextItem[]` | 必填 | 为这个任务选出的内容片段，每条都可以用它的 `citation_id` 引用。 |
| `route` | `DevContextRoute` | 必填 | 用了哪些来源、各给了多少预算，以及原因。 |
| `tokens_used` | `integer` | 必填 | 按整个响应计量；设为 `render: "compact"` 时按 `rendered.text` 计量。不超过 `budget_tokens`。 |
| `budget_tokens` | `integer` | 必填 | 这个包是按多少预算组装的。 |
| `tokenizer` | `cl100k_base` | 必填 | 计算 `tokens_used` 和 `budget_tokens` 所用的分词器。 |
| `omitted` | `DevContextOmitted` | 必填 | 符合条件但超出预算或低于相关性阈值的内容。 |
| `scope_used` | `DevContextScopeUsed` | 必填 | 这个包取材的 Space。 |
| `partial` | `boolean` | 必填 | 某个检索分支降级，或分数不是校准过的相关度时为 true。 |
| `pending_processing` | `DevPendingProcessing` | 可选 | 仅当所检索的 Space 中仍有 Entry 在处理时返回：这些 Entry 的文本可能不在本次结果中。[`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing) 会报告它们何时可检索。 |
| `rendered` | `DevContextRendered` | 可选 | 请求带了 `render` 才有。 |
| `explain` | `DevExplainSummary` | 可选 | 仅当请求设置了 `explain` 时返回。 |

## DevContextRoute

说明确定性路由决策，在授权之后生成。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `purpose` | `DevContextPurpose` | 必填 | 实际使用的用途。没有指定时从任务推断。 |
| `tier` | `DevContextTier` | 必填 |  |
| `rules_fired` | `string[]` | 必填 | 稳定的规则名，不会引用任务原文：`purpose:explicit` 或 `purpose:inferred:<purpose>`；`budget:table:<purpose>`；`tier:fast:lexical_only`；`weights:caller`；`scope:no_visible_space`；`files:named_in_task`；关闭的来源记为 `source:off:<source>:<why>`，其中 `<why>` 为 `not_agent_caller`、`weight_zero` 或 `answer_default`；表格计算记为 `table_aggregate:computed` 或 `table_aggregate:not_computed:<reason>`。以后可能新增规则名。 |
| `sources` | `DevContextRouteSource[]` | 必填 | 打开的来源。关闭的来源写在 `rules_fired` 里。 |
| `unused_tokens` | `integer` | 必填 | 未使用的预算：没有高于相关性阈值的内容需要这部分预算。 |

## DevContextRouteSource

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source` | `DevContextSource` | 必填 |  |
| `budget` | `integer` | 必填 | 这个来源可用的 token，已经包括其他来源回流过来的预算。 |
| `used` | `integer` | 必填 | 这个来源实际用掉的 token 数。 |
| `picked` | `integer` | 必填 | 该来源入选上下文包的条目数。 |
| `omitted` | `integer` | 必填 | 该来源被略去的候选数。 |
| `why` | `string` | 必填 | 稳定的代码，比如 `filled`、`below_relevance_floor` 或 `no_file_named_in_task`。 |

## DevContextScopeUsed

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_ids` | `DevId[]` | 必填 | 检索过的 Space。 |

## DevContextSource

上下文条目的来源。这里的 `memory` 指和任务相关的记忆：写成 Entry 的记忆和提炼出的事实。它不是全部记忆——全部记忆是 `memory_view`，一份随条目一起发出的、已确认内容的索引。`knowledge` 是检索找到的其他内容，`files` 是任务里点名的文件，`changes` 是最近写入的内容，`skills` 和 `agent_profile` 是 Agent 自己的。

取值: `memory | agent_profile | skills | files | changes | knowledge`

## DevContextTier

`fast` 不调用模型，只按词面匹配；`standard` 加上语义检索和重排；`deep` 查看两倍的候选。

取值: `fast | standard | deep`

## DevContextWeights

每个来源 0 到 1 的偏好，服务端与没传的来源的默认值一起归一化。`0` 关闭这个来源。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory` | `number` | 可选 | `memory` 的权重：与任务相关的记忆。 0 到 1 |
| `agent_profile` | `number` | 可选 | `agent_profile` 的权重：Agent 自己的档案。 0 到 1 |
| `skills` | `number` | 可选 | `skills` 的权重：Agent 自己的技能。 0 到 1 |
| `files` | `number` | 可选 | `files` 的权重：任务里点名的文件。 0 到 1 |
| `changes` | `number` | 可选 | `changes` 的权重：最近写入的内容。 0 到 1 |
| `knowledge` | `number` | 可选 | `knowledge` 的权重：检索找到的其余内容。 0 到 1 |

## DevConversationContentPart

`content` 为列表时的一段。保留文本分段，跳过图片等其他分段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | `string` | 可选 | 这一段的类型，照聊天接口的写法，比如 `text`、`image_url`。 |
| `text` | `string` | 可选 | 这一段的文字。没有文字的段略过。 |

## DevConversationMessage

照聊天接口的写法给的一条消息，对话记录不用清洗就能写入。没有文字的消息（比如只调用工具的那一轮）会被略过；整批没有一条带文字时返回 422。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `role` | `string` | 必填 | 自由文本，比如 `user` 或 `assistant`，不能有换行。 长度 1 到 128 |
| `content` | `string \| DevConversationContentPart[] \| null` | 可选 | 文字，或者一组分段，其中的文字段会拼起来。没有文字的消息可以是 `null` 或不带这个字段。 |
| `name` | `object` | 可选 | 接收但忽略。 |
| `tool_calls` | `object` | 可选 | 接收但忽略。 |
| `tool_call_id` | `object` | 可选 | 接收但忽略。 |
| `function_call` | `object` | 可选 | 接收但忽略。 |
| `timestamp` | `string (date-time) \| integer` | 可选 | 消息的发送时间：RFC 3339 字符串（和本 API 里其他时间一样），或 Unix 毫秒。对于看起来以秒为单位的整数，接口返回 422，以免将消息时间误记为 1970 年。 |

## DevCorrectMemoryRequest

写入替换内容，并关闭旧记忆的有效期。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | 必填 | 更正后的内容，1 到 2000 个字符。 长度 1 到 2000 |

## DevCreateApiKeyRequest

字段名为 `actor_id` 和 `grant_capabilities`，而非 `principal_id` 和 `capabilities`：后两个名字由服务端控制，请求里出现就会被 `identity_override` 拒绝。`POST` 和 `PATCH /v2/principals` 同样如此。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `actor_id` | `DevId` | 必填 | 这个 Key 代表的主体。比自身主体更窄的调用方 Key（能力更少、限定了 Space 或元数据范围）只能为该主体签发 Key。 |
| `name` | `string` | 必填 | Key 的名称，1 到 256 个字符，用于在列表中区分各个 Key。 长度 1 到 256 |
| `grant_capabilities` | `DevCapability[]` | 必填 | 不能超过该主体和调用方的能力。 至少 1 项 |
| `allowed_space_ids` | `DevId[]` | 可选 | 不传表示不限制 Space；不接受空数组。 1 到 100 项 |
| `metadata_scope` | `DevMetadataScope` | 可选 | 将 Key 限制在带有这些元数据标签的 Entry 上：1 到 8 个键，每个键 1 到 8 个值。创建后不可修改，轮换 Key 时保持不变。带范围的 Key 可调用 `whoami`、`limits`、读取 Space、[`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list)、读取 Entry 内容与处理状态、[`GET /v2/jobs/{id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read)、读取记忆、`search`、`context`、`answer`、上下文反馈、`ingest` 和 MCP；其他操作均返回 403 `scoped_key_route_unavailable`。导入时在受限键上传入范围外的值返回 403 `outside_metadata_scope`。若要在最终用户之间实现硬隔离，请为每个用户创建一个 Space；范围用于在同一 Space 内做更细的划分。 |
| `expires_at` | `string (date-time)` | 可选 | 必须是未来时间。调用方的 Key 有到期时间时必填，且不能晚于该到期时间。 |

## DevCreateBranchRequest

`from` 复制另一个活跃分支，`checkpoint_id` 复制一个检查点。两者都不传时从主线创建。同时传两者时，`checkpoint_id` 必须是 `from` 所指分支的检查点，否则返回 404 `checkpoint_not_found`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 分支的名称，1 到 255 个字符。 长度 1 到 255 |
| `from` | `DevId` | 可选 | 要复制的活跃分支的 id。 |
| `checkpoint_id` | `DevId` | 可选 | 要复制的检查点的 id。 |
| `ttl_days` | `integer` | 可选 | 每次写入把 `expires_at` 推后的天数，1 到 365。不传则使用服务默认值。 1 到 365 |

## DevCreateCheckpointRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 检查点的名字，1 到 255 个字符。 长度 1 到 255 |
| `git` | `DevCheckpointGit` | 可选 |  |

## DevCreateExportRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `snapshot` | `DevSnapshotRef` | 可选 | 快照 id 或名字：导出当时的文件。不带时导出任务开始那一刻的实时目录树。 |
| `path` | `DevPath` | 可选 | 只导出这个目录（或文件）及其下面的内容。 |
| `format` | `tar` | 可选 | 唯一支持的格式。 |

## DevCreateForkRequest

把一个 Space 复刻成你拥有的新 Space。即将上线。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 新 Space 的名字。 |
| `snapshot` | `DevSnapshotRef` | 可选 | 按快照固定的文件复刻。不带时用实时目录树。 |

## DevCreateImportRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source_entry_id` | `DevId` | 必填 | 一个你可读的 Entry，其最新版本为 tar 或 gzip 压缩的 tar 归档。请先使用 `PUT .../files` 或 `uploads` 将归档上传至任意 Space。创建任务时固定该版本。 |
| `path` | `DevPath` | 可选 | 导入到的目录，需要时自动创建。默认 `/`。 |
| `on_conflict` | `DevImportConflict` | 可选 | 成员目标路径上已有文件时的处理方式：`skip`（默认）或 `overwrite`。 默认 "skip" |

## DevCreateMemoryRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | 必填 | 记忆的范围：`project`、`agent` 或 `account`。 |
| `space_id` | `DevSpaceRef` | 可选 | `project` 和 `agent` 必填；`default` 指你的默认 Space，和路径里一样。账户记忆不属于任何 Space，不带这个字段。 |
| `kind` | `string` | 必填 | `preference`、`decision` 或 `progress`。账户记忆另有一组：`role`、`project`、`commitment`、`preference`、`person`、`fact`、`episode_summary`、`interview_answer`、`first_screen_pin`、`ask_less`。 长度 1 到 64 |
| `text` | `string` | 必填 | 记忆的内容，1 到 2000 个字符。 长度 1 到 2000 |
| `pinned` | `boolean` | 可选 | 账户记忆没有这个字段。 默认 false |

## DevCreatePrincipalRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `DevPrincipalKind` | 必填 | 主体类型：人（`human`）或 Agent（`agent`）。 |
| `grant_capabilities` | `DevCapability[]` | 可选 | 要授予的能力，不能超过你持有的能力。不传时 Agent 获得 `knowledge:read`，人没有任何能力。 |

## DevCreateSnapshotRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 1 到 255 字节，在 Space 内唯一，不含控制字符，不以 `snp_` 开头。 长度 1 到 255 |

## DevCreateSpaceRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | Space 的名称，1 到 512 个字符。 长度 1 到 512 |
| `description` | `string` | 可选 | Space 的用途，1 到 4096 个字符。 长度 1 到 4096 |
| `external_id` | `string` | 可选 | 你为这个 Space 设定的 id，1 到 256 个字符，例如其数据所属最终用户的 id。之后用 [`GET /v2/spaces?external_id=`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 或路径 `ext:<external_id>` 查找该 Space，无需保存 Mirabase 生成的 id。在账户的所有 Space 中唯一：已被占用时返回 409 `space_external_id_taken`（`field: external_id`）。删除该 Space 后可再次使用。 长度 1 到 256 |

## DevCreateUploadRequest

用于超过 16 MiB 的文件，更小的文件使用 [`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/zh/developers/api/files.md#files-write)。超过部署的大小上限返回 413。大到无法处理的文件仍会保存且可读，`knowledge.state` 最终为 `failed`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 在完成上传时才解析，所以这期间该路径上的文件可能出现或变化。 |
| `size` | `integer` | 必填 | 整个文件的字节数。 不小于 1 |
| `media_type` | `string` | 必填 | 文件的媒体类型，比如 `application/pdf`。 |
| `checksum_sha256` | `string` | 必填 | 整个文件 SHA-256 的 Base64，完成时校验。 |

## DevCreateWebhookRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 必填 | `https`，端口 443，不带用户名、密码和片段，主机是完整域名或公网 IP。每次推送都会重新解析主机，只要有一个地址是私有、回环、链路本地、唯一本地、运营商级 NAT、基准测试、文档、组播或保留地址（包括映射和 NAT64 形式）就拒绝连接。 最长 2048 |
| `ops` | `DevChangeOp[]` | 可选 | 要推送的事件类型；默认包含全部五种。不可重复。 1 到 5 项 |
| `description` | `string` | 可选 | 供人阅读的备注，最多 256 个字符。 最长 256 |
| `cursor` | `DevCursor` | 可选 | 从这个 `changes` 游标之后开始。默认从当前时刻开始。游标过期时，接口返回 410 `cursor_expired`。 |

## DevCreatedWebhook

新建的 Webhook 及其签名密钥，密钥仅返回一次。使用同一 `Idempotency-Key` 重放时不包含密钥。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `url` | `string (uri)` | 必填 | 端口 443 上的 `https`。 |
| `ops` | `DevChangeOp[]` | 必填 | 要推送的事件类型。其他类型的事件直接跳过，不排队。 |
| `description` | `string` | 可选 | 给人看的备注。 |
| `status` | `DevWebhookStatus` | 必填 | `active`；停止投递时为 `disabled`，原因见 `disabled_reason`。 |
| `disabled_reason` | `DevWebhookDisabledReason` | 可选 | `status` 是 `disabled` 时出现。 |
| `cursor` | `DevCursor` | 必填 | 最后一批推送或跳过之后的变更流位置。 |
| `consecutive_failures` | `integer` | 必填 | 上次成功以来失败的尝试次数。 |
| `last_success_at` | `string (date-time)` | 可选 | 最近一次投递成功的时间。 |
| `last_failure_at` | `string (date-time)` | 可选 | 最近一次投递失败的时间。 |
| `next_attempt_at` | `string (date-time)` | 可选 | 下一次尝试最早的开始时间。停用时没有。 |
| `created_by_principal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 这个 Webhook 创建的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 这个 Webhook 的设置或状态最近一次变动的时间。 |
| `secret` | `string` | 可选 | `whsec_` 加 43 个 base64url 字符。HMAC 密钥是整个字符串。 |

## DevCursor

不透明的分页或变更游标。

取值: `string`

## DevDiffBasis

比较的依据：两个文本文件的原始字节，或者其他文件经处理提取出的文本。

取值: `original | text`

## DevDiffOmitted

没有 `unified_diff` 的原因。`too_large`：超过 1 MiB 或改动的行太多。`not_text`：二进制文件，没有提取出的文本。`content_not_ready`：其中一方仍在处理中，请稍后重试。

取值: `too_large | not_text | content_not_ready`

## DevDream

单次整理的报告。整理只重新组织已有记忆：不生成任何内容，每项动作都附带证据，且可以撤销。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `scope` | `DevDreamScope` | 必填 |  |
| `agent_principal_id` | `DevId` | 可选 | `agent` 整理：是谁的私有记忆。 |
| `status` | `DevDreamStatus` | 必填 | `queued`、`running`，然后是 `succeeded` 或 `failed`。 |
| `trigger` | `DevDreamTrigger` | 必填 | `manual`：有人手动发起。`schedule`：由这个 Space 的定时整理发起。 |
| `started_by_principal_id` | `DevId` | 可选 | 仅限手动（`manual`）发起的整理。 |
| `created_at` | `string (date-time)` | 必填 | 这次整理排队的时间。 |
| `started_at` | `string (date-time)` | 可选 | 开始运行的时间。还在排队时没有。 |
| `finished_at` | `string (date-time)` | 可选 | 结束时间，无论成功或失败均会记录。 |
| `undone_at` | `string (date-time)` | 可选 | 被撤销的时间。未撤销过时不返回。 |
| `undone_by_principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `undo_expires_at` | `string (date-time)` | 可选 | `undoable` 为真时：可撤销的最晚时间；如果同一范围内有三次后续整理在此之前完成，撤销期限会提前。从本次整理完成时起算；如果本次整理的提案最后一次获批的时间更晚，则从那时起算。 |
| `undoable` | `boolean` | 必填 | 当前是否可撤销。 |
| `counts` | `DevDreamCounts` | 必填 |  |
| `view` | `DevDreamView` | 可选 |  |
| `d4` | `DevDreamD4Report` | 可选 | 整理进入比较阶段后出现。 |
| `model_tokens` | `integer` | 必填 | 这次整理估算消耗的模型 token；在这个 Space 里有 `read_root` 的成员看到的是 0。 |
| `error` | `DevJobFailure` | 可选 |  |

## DevDreamAction

一次整理对一条记忆做的一个改动；`reported` 表示 `dormancy: "apply"` 时会做、这次没有做的改动。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `seq` | `integer` | 必填 | 在这次整理里的顺序，动作按它排列。 |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `action` | `DevDreamActionKind` | 必填 |  |
| `reason` | `DevDreamActionReason` | 必填 |  |
| `state` | `DevDreamActionState` | 必填 |  |
| `proposal_id` | `DevId` | 可选 | `supersede` 和 `merge`：被批准的提案。 |
| `target_memory_id` | `DevId` | 可选 | `supersede` 和 `merge`：保留的目标记忆。调用方无权读取其来源时不返回。 |
| `created_at` | `string (date-time)` | 必填 | 这个动作发生的时间。 |

## DevDreamActionKind

`dormant` 将记忆标为休眠；`supersede` 和 `merge` 是这次整理的提案被批准后关闭了它。

取值: `dormant | supersede | merge`

## DevDreamActionReason

`proposal`：人批准了这个改动。

取值: `quote_missing | unused | proposal`

## DevDreamActionState

`reported`：`dormancy: "report"` 下的休眠候选；未做任何修改，因此无需撤销。

取值: `applied | undone | conflict_skipped | reported`

## DevDreamCounts

一次整理做了什么。`dormant_marked`、`dormancy_candidates`、`dormant_unused`、`superseded`、`merged`、`undone` 和 `conflict_skipped` 只计来源你看得见的记忆上的动作。其他计数针对整个范围，在这个 Space 里有 `read_root` 的成员看不到。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dormant_marked` | `integer` | 必填 | 因为引文已经找不到而标为休眠的记忆（`quote_missing`）。 |
| `dormancy_candidates` | `integer` | 可选 | 整理走到休眠这一步后才有：它找到的闲置提炼记忆，即 90 天没有被取用、这个范围连续三次整理都没有被取用、不在同类型取用最多的 20 条之内，并且不是规则、偏好或人确认过的记忆。Space 设置为 `dormancy: "report"` 时，它们只列为 `reported` 动作。 |
| `dormant_unused` | `integer` | 可选 | 和 `dormancy_candidates` 一起出现：其中被标为 `dormant`、原因 `unused` 的记忆（Space 设置为 `dormancy: "apply"`）。 |
| `superseded` | `integer` | 可选 | 本次整理的 `supersede` 提案获批后，被较新记忆取代的记忆数。大于 0 时返回。 |
| `merged` | `integer` | 可选 | 这次整理的 `merge` 提案被批准后，并入另一条的记忆。有了才出现。 |
| `undone` | `integer` | 可选 | 撤销后：撤销了的动作。 |
| `conflict_skipped` | `integer` | 可选 | 撤销后：因记忆此后发生变更（被遗忘、确认、重新提炼，或被后续整理接管）而跳过的动作。 |
| `checked` | `integer` | 可选 | 核对过的提炼记忆。 |
| `skipped_confirmed` | `integer` | 可选 | 人确认过的记忆，整理从不改动：审核通过的候选，以及带 `memory:confirm` 导入的对话里提炼出的记忆。 |
| `skipped_not_ready` | `integer` | 可选 | 来源有更新的版本还在处理的记忆。 |
| `skipped_no_quote` | `integer` | 可选 | 没有引文可核对的记忆。 |
| `stale_skipped` | `integer` | 可选 | 在核对和写入之间变过、留给下一次整理的记忆。 |
| `vetoed` | `integer` | 可选 | 之前的撤销指定不要再改动的记忆。 |
| `already_dormant` | `integer` | 可选 | 之前的整理已经标为休眠的记忆。 |
| `groups` | `integer` | 可选 | 说同一件事的记忆组（两条或以上）。 |
| `grouped_facts` | `integer` | 可选 | 与至少另一条说法相同的提炼记忆的条数。 |
| `remaining` | `integer` | 可选 | 因单次整理最多核对 10000 条而尚未核对的记忆。该范围的下一次整理（手动或自动）从上次核对的最后一条之后继续；单次整理到达末尾后，下一次从头开始。 |

## DevDreamD4Report

一次整理的模型比较（D4）。计数针对整个范围；在这个 Space 里有 `read_root` 的成员看不到。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `status` | `ran \| skipped` | 必填 | `skipped`：本次运行未调用模型，由 `skipped` 字段说明原因。 |
| `skipped` | `DevDreamD4SkipReason` | 可选 | D4 被跳过，或没比完所有配对就停下时才有。`remaining` 是留下的数量。 |
| `nominated` | `integer` | 必填 | 找到的值得比较的记忆配对。 |
| `judged` | `integer` | 必填 | 问过模型的配对。 |
| `cached` | `integer` | 必填 | 直接用 30 天内已有判定回答的配对。 |
| `proposed` | `integer` | 必填 | 写成 `open` 提案的判定。 |
| `shadow` | `integer` | 必填 | 只记录下来的判定（`shadow` 设置）。 |
| `discarded` | `integer` | 必填 | 未通过校验或模型无法给出结论的判定；不保留文本。 |
| `stale_skipped` | `integer` | 必填 | 判定写下之前记忆已经变了的配对。 |
| `failed` | `integer` | 必填 | 模型调用失败的配对。 |
| `remaining` | `integer` | 必填 | 因为 `skipped` 而没有判定的配对。 |

## DevDreamD4SkipReason

D4 未运行或提前停止的原因。`deployment_off`、`model_not_configured`、`distill_disabled`（部署的配置）以及 `distill_paused`、`rate_limited`、`token_budget`（账户的用量）只向 `tenant_admin` 的 Key 或持有 `knowledge:manage` 的 Key 显示，且该 Key 未限定 Space 或元数据范围。其他调用方看到的这六种原因都是 `unavailable`。`space_off`、`group_limit` 和 `too_many_open_proposals` 与 Space 本身有关，所有能读取报告的调用方都能看到。

取值: `unavailable | deployment_off | model_not_configured | space_off | distill_disabled | distill_paused | rate_limited | token_budget | group_limit | too_many_open_proposals`

## DevDreamJudgment

一次整理请模型比较的一对记忆，以及结果。仅在调用方对每个成员的来源均有读取权限时可见；`discarded` 判定不保留引文和文本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `dream_id` | `DevId` | 必填 | 长度 1 到 256 |
| `outcome` | `DevDreamJudgmentOutcome` | 必填 |  |
| `kind` | `DevMemoryProposalKind` | 可选 | 它的结论。`discarded` 的判定没有。 |
| `member_ids` | `DevId[]` | 必填 | 被比较的记忆。 |
| `layer` | `DevMemoryLayer` | 必填 | 这一对所在的记忆层：`rule`、`decision`、`event` 或 `knowledge`。 |
| `signals` | `string[]` | 必填 | 为什么比较这一对：`entity`、`predicate`、`kind`。 |
| `discard_reason` | `DevDreamJudgmentDiscardReason` | 可选 | `discarded` 的判定才有：它为什么被丢弃。 |
| `plan` | `DevMemoryProposalPlan` | 可选 |  |
| `evidence` | `DevMemoryProposalEvidence[]` | 可选 | 判定所依据的逐字引文。`discarded` 的判定不留引文，所以没有这个字段。 |
| `times` | `DevMemoryProposalTime[]` | 可选 | 决定哪条记忆较新的日期。 |
| `model` | `string` | 可选 | 被询问的模型。 |
| `prompt_version` | `integer` | 必填 | 做出这个判定所用提示词的版本。提示词版本更新后，旧判定不再复用。 |
| `cached` | `boolean` | 必填 | 为真时，这条判定复用了之前的判定，没有问模型。 |
| `created_at` | `string (date-time)` | 必填 | 这个判定记下的时间。 |

## DevDreamJudgmentDiscardReason

取值: `too_large | model_output | model_failed | unrelated | both_confirmed | quote_unverified | quote_not_in_sources | time_unverified | guard_number | guard_negation | guard_entity | suppressed`

## DevDreamJudgmentOutcome

`open` 及之后的状态即提案的状态；`shadow` 和 `discarded` 只出现在这里。

取值: `open | approved | rejected | stale | withdrawn | shadow | discarded`

## DevDreamScope

整理哪一份记忆：Space 的项目记忆，或某个 Agent 的私有记忆。

取值: `project | agent`

## DevDreamStatus

取值: `queued | running | succeeded | failed`

## DevDreamTrigger

取值: `manual | schedule`

## DevDreamView

整理前后这个范围里生效的记忆：整理只会让它们变少或变短，不会变多或变长。对在此 Space 中设有 `read_root` 的成员不返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `live_before` | `integer` | 必填 | 整理前这个范围里生效的记忆条数。 |
| `tokens_before` | `integer` | 必填 | 整理前它们的 token 数。 |
| `live_after` | `integer` | 可选 | 整理后这个范围里生效的记忆条数。整理完成后返回。 |
| `tokens_after` | `integer` | 可选 | 整理后它们的 token 数。整理完成后返回。 |

## DevEmptyRequest

取值: `object`

## DevEnrichment

Entry 可检索之后运行的处理。搜索不等待这些处理。

取值: `relations | classification | summary | memory`

## DevEnsureSpaceRequest

只在创建 Space 时使用；已有的 Space 原样返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 可选 | 新建 Space 的名称，默认为 `external_id`。 长度 1 到 512 |
| `description` | `string` | 可选 | 新建 Space 的描述。 长度 1 到 4096 |

## DevEntry

文件、网址或对话背后的来源记录，带一条不可变版本链。`file` 和 `memory` 按需出现，`knowledge` 是处理状态。从 Entry 提炼的事实不是 Entry，它们在记忆层，并回指这里。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 以 `ent_` 开头。新增版本、改名、移动都不会改变它。 |
| `space_id` | `DevId` | 必填 | Entry 所在的 Space。 |
| `title` | `string` | 必填 | 文件的标题是文件名；其他情况是你给的标题，或从内容里取的标题。 |
| `latest_version_id` | `DevId` | 必填 | 最新写入的版本。按路径或 id 读取时默认返回它。 |
| `current_version_id` | `DevId` | 可选 | `search` 和 `context` 读取的版本。`latest_version_id` 指向的版本完成索引后，两者相同；更新的版本还在处理时，它仍是之前的版本。第一版处理完之前不存在。 |
| `metadata` | `DevMetadata` | 必填 | 你在导入时、写文件时或用 `PATCH` 设置的内容，加上服务写入的 `mirabase.` 开头的键。没有时为空。 |
| `occurred_at` | `string (date-time)` | 可选 | 来源本身发生的时间：导入或写文件时传的 `occurred_at`，或对话里消息的时间。未知时不返回；检索的时间过滤此时按写入时间算。 |
| `source_type` | `DevSourceType` | 可选 | 这是哪种来源：`file`、`note`（导入的文本）、`web`（导入的网址）、`agent-conversation`（导入的对话）。与搜索命中报告的值相同，`filter.source_types` 按它匹配。 |
| `url` | `string` | 可选 | 从网址写入的 Entry 上：那个网址。用它把检索命中或引用链接回原网页。 |
| `created_at` | `string (date-time)` | 必填 | Entry 第一次写入的时间。 |
| `updated_at` | `string (date-time)` | 必填 | Entry 最后一次变更的时间：新版本、新元数据、移动。这是 Entry 自身的时钟，不是文件内容的修改时间；后者是最新版本的 `created_at`。 |
| `file` | `DevEntryFile \| null` | 必填 | 没有路径的 Entry（如网址或对话）为 null。 |
| `knowledge` | `DevEntryKnowledge` | 必填 | 处理进行到哪一步，以及检索正在使用哪个版本。 |
| `memory` | `DevEntryMemory \| null` | 必填 | 不是作为记忆写入的 Entry 为 null。 |
| `memory_exclude` | `boolean` | 必填 | 这个 Entry 不参与记忆提炼时为 true。任何 Entry 都可以设置，所以它不在 `memory` 下面。 |
| `access` | `DevEntryAccess` | 必填 | 你在这个 Entry 所属 Space 里的角色，以及你所用 Key 的能力。 |
| `trash` | `DevEntryTrash` | 可选 | 只在废纸篓列表里出现（[`GET /v2/entries?trashed=true`](https://mirabase.io/zh/developers/api/entries.md#entries-list)）。 |

## DevEntryAccess

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `role` | `DevSpaceRole` | 必填 | 你在这个 Entry 所在 Space 里的角色。 |
| `capabilities` | `DevCapability[]` | 必填 | 本次请求具备的能力。 |

## DevEntryContent

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `view` | `DevContentView` | 必填 | 这是哪种视图：`text`、`table` 或 `recognized`。 |
| `text` | `string` | 可选 | 文本形式的内容。`table` 视图没有。 |
| `table` | `DevTableContent` | 可选 | 表格形式的内容。仅在 `table` 视图中返回。 |

## DevEntryCopy

用 `tree/operations` 的 `copy` 从这个 Entry 复制出的文件。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `source_version_id` | `DevId` | 必填 | 复制时所用的源版本。 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 复制发生的时间。 |

## DevEntryFile

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `size` | `integer` | 必填 | 最新版本的字节数。 |
| `media_type` | `string` | 必填 | 最新版本的媒体类型。 |
| `etag` | `string` | 必填 | 最新版本的 ETag。放进 `If-Match`，只有他人没改过才会写入。 |
| `modified_at` | `string (date-time)` | 可选 | 内容最后一次变更的时间，即最新版本写入的时间。与 `tree` 列表返回的值相同。 |

## DevEntryKnowledge

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `state` | `DevKnowledgeState` | 必填 |  |
| `indexed_version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `parsed` | `DevParsedSummary` | 可选 | 已索引版本的解析结果。Entry 有了已索引的版本后，[`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 和 [`GET /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-read) 会返回这个字段；在此之前、解析失败时以及写入回执中不返回。 |
| `error` | `DevProcessingFailure` | 可选 | 处理失败的原因，与 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 返回的 `error` 相同。`state` 为 `failed` 时，[`GET /v2/entries`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 和 [`GET /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-read) 返回这个字段；其他情况以及写入回执中不返回。 |

## DevEntryMemory

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | 必填 | 这是谁的记忆：`project`、`agent` 或 `account`。 |
| `kind` | `string` | 必填 | 记忆的种类，比如 `preference`、`decision`。 |
| `pinned` | `boolean` | 必填 | 置顶的记忆在记忆上下文里排在最前。 |
| `exclude` | `boolean` | 必填 | 这个 Entry 的 `memory_exclude` 设置：true 表示不参与记忆提炼。 |

## DevEntryProcessing

Entry 最新版本的处理进度：一次写入是否已可检索，以这里为准。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 最新版本，即这里报告的版本。 |
| `status` | `DevVersionStatus` | 必填 | 到 `published`、`no_recallable_content`、`failed` 或 `discarded` 即为终态。 |
| `knowledge_state` | `DevKnowledgeState` | 必填 | 与 Entry 上的 `knowledge.state` 相同。 |
| `error` | `DevProcessingFailure` | 可选 | 仅在 `status` 为 `failed` 时出现。 |
| `stage` | `DevProcessingStage` | 必填 | 最新版本当前所处的阶段。从 `enriching` 开始，搜索即可找到它。 |
| `progress` | `DevProcessingProgress` | 必填 | 已完成的主要步骤。 |
| `queue` | `DevProcessingQueue` | 可选 | 仅在当前步骤等待开始时返回。 |
| `enrichments` | `DevEnrichment[]` | 可选 | 仅在 `stage` 为 `enriching` 时返回：仍在运行的处理。 |
| `memory` | `DevMemoryProcessing` | 可选 | 只在对话批次上出现：记忆提炼的进度。等它离开 `pending` 后再读取记忆。 |

## DevEntryTrash

已移入废纸篓的 Entry 原先所在的位置。Entry 在废纸篓中时其路径已释放，因此 `file` 为 null。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `deleted_at` | `string (date-time)` | 必填 | 进废纸篓的时间。没有路径的 Entry 取清理完成的时间，晚几秒。 |
| `path` | `DevPath` | 可选 | 文件原来的路径。[`POST /v2/entries/{id}/restore`](https://mirabase.io/zh/developers/api/entries.md#entries-restore) 会把它放回这里。没有路径的 Entry 没有这个字段。 |
| `delete_batch_id` | `DevId` | 可选 | 把文件放进废纸篓的那次删除。`tree/operations` 的 `restore` 接受它，把那次删除去掉的内容全部恢复。 |
| `deleted_by` | `DevId` | 可选 | 将文件移入废纸篓的主体 id。没有路径的 Entry 不返回此字段。 |
| `size` | `integer` | 可选 | 最新版本的大小（字节），与原 `file.size` 的值相同。没有存储大小时不返回。 |

## DevErrorBody

失败的请求在 `error` 下返回的内容：用于分支处理的稳定 `code`、HTTP `status`、供人阅读的 `message`、`request_id`、重试是否有用，以及有固定下一步的错误码所带的 `remediation`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `string` | 必填 | 机器可读的错误码，如 `path_conflict`、`edit_ambiguous`。429 时：`rate_limited` 表示请求速率或并发超限（`limit` 说明是哪一种），`too_many_waiters` 表示一个 Key 已保持 4 个长轮询，`ingest_backlog` 表示排队任务过多，`too_many_jobs` 表示 Space 已在运行 4 个导出或 4 个其他任务，`quota_exceeded` 表示持久配额用完。本字段上的 `x-mirabase-remediation-actions` 列出每个有固定下一步的错误码及其对应的 `remediation.action`。请按 action 分支，不要按 message。没有列出的错误码没有固定下一步，按 HTTP 状态处理。唯一的例外是 `conflict`：只有 `field` 为 `Idempotency-Key` 时才带 `use_new_idempotency_key`。以后可能新增错误码，遇到未知错误码时按未列出的错误码处理。本字段上的 `x-mirabase-error-codes` 列出 API Key 可能收到的每个错误码，以及它的 HTTP 状态码、含义；响应带 `Retry-After` 时，还给出秒数（`retry_after`）。 |
| `type` | `DevErrorType` | 可选 | 错误的大类，由 HTTP 状态码决定，供对同一类错误做相同处理的代码使用：`invalid_request`（400、422 和这里没有列出的其他 4xx）、`authentication`（401）、`permission`（403）、`not_found`（404、410）、`conflict`（409、412）、`rate_limit`（429）、`server`（5xx）。处理具体情况时按 `code` 分支。每个 `/v2` 错误都带这个字段。 |
| `status` | `integer` | 必填 | HTTP 状态，在响应体里重复一遍。 |
| `message` | `string` | 必填 | 给人看的英文说明，可能会变：分支处理请按 `code`。 |
| `request_id` | `string` | 必填 | 在服务日志里标识这次请求。反馈问题时请带上它。 |
| `retryable` | `boolean` | 必填 | `quota_exceeded` 时为 false：配额变更之前，重试无效。 |
| `field` | `string` | 可选 | 422 时第一个出错的字段。请求体里有不认识的字段时，这里是那个字段的名称。 |
| `errors` | `DevFieldError[]` | 可选 | 请求体校验返回 422 时：列出发现的每个问题，最多 20 个，以便一次改完。第一个就是 `field` 和 `message` 描述的那个问题。 |
| `limit` | `request_rate \| concurrency` | 可选 | 429 `rate_limited` 时返回：触发的是哪一种限制。`request_rate` 是每分钟的请求额度，即 `RateLimit-*` 响应头描述的额度。`concurrency` 是对进行中的操作数量的限制（搜索和上下文请求、回答，或对同一个 Space 的写入）；请求已经等待过空闲名额，这时不返回 `RateLimit-*` 响应头，减少同时发出的调用比延长等待更有效。 |
| `quota` | `writes \| storage_bytes \| model_tokens \| model_spend_micro_usd` | 可选 | 429 `quota_exceeded` 时返回：指明哪项配额已用完。`writes`、`model_tokens` 和 `model_spend_micro_usd` 在下个月初（UTC）重置；`storage_bytes` 在文件被彻底删除后释放。剩余额度见 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage)。 |
| `queue` | `DevBacklog` | 可选 | 429 `ingest_backlog` 时返回：账户的队列。也可随时用 [`GET /v2/queue`](https://mirabase.io/zh/developers/api/usage.md#usage-queue) 查看。 |
| `current_version_id` | `DevId` | 可选 | 412 `precondition_failed` 和 409 `proposal_conflict` 时返回：文件当前的最新版本。 |
| `job_id` | `DevId` | 可选 | 409 `job_in_flight` 时返回：需要等待的任务。 |
| `conflicts` | `DevMergeConflict[]` | 可选 | 409 `merge_conflict` 时出现：挡住合并的每个路径。 |
| `remediation` | `DevRemediation` | 可选 |  |

每个错误码的状态码、含义、`remediation.action` 和 `Retry-After` 见 [错误码](https://mirabase.io/zh/developers/errors.md#codes)。

## DevErrorResponse

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `error` | `DevErrorBody` | 必填 | 错误本身。 |

## DevErrorType

错误的大类。以后可能增加新的值：遇到不认识的值时按 `invalid_request` 处理。

取值: `invalid_request | authentication | permission | not_found | conflict | rate_limit | server | string`

## DevExplainAdmission

命中通过相关性下限的依据。

取值: `score | lexical_match | title_named | pinned | same_entry | low_confidence_fallback`

## DevExplainBoost

改变命中位置的规则。

取值: `time_window | newest_on_topic | newest_first`

## DevExplainBranch

命中是由哪一路检索找到的。词法检索和稠密向量检索是两路主要检索；其余是各有规则的来源。

取值: `lexical | dense | dense_document | memory | relation | window_lexical | window_dense | recent | fresh_buffer | named_file | recent_change | skill | agent_profile`

## DevExplainBranchRank

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch` | `DevExplainBranch` | 必填 |  |
| `rank` | `integer` | 必填 | 在这一路检索自身结果中的位置，从 1 开始，只统计你能读取的结果。 |

## DevExplainCandidateCount

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch` | `DevExplainBranch` | 必填 |  |
| `count` | `integer` | 必填 | 这一路检索返回的、你能读取的候选数。 |

## DevExplainRank

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `rank` | `integer` | 必填 | 位置，从 1 开始。 |
| `score` | `number` | 必填 | 只在同一个响应内可比较。 |

## DevExplainRerank

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `rank` | `integer` | 必填 | 位置，从 1 开始。 |
| `score` | `number` | 必填 | 只在同一个响应内可比较。 |
| `pass` | `string` | 可选 | 分数来自任务的某个子句而非整个任务时返回：`clause_1`、`clause_2` 等。 |

## DevExplainRerankSummary

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `applied` | `boolean` | 必填 | 跳过重排、重排失败或未给出分数时为 false；此时 `score` 不是经过校准的相关性。 |
| `pool` | `integer` | 必填 | 送去重排的候选数。 |
| `below_floor` | `integer` | 必填 | 重排后低于相关性下限的候选数。 |

## DevExplainSummary

请求设置了 `explain` 时，说明检索的执行过程。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `terms` | `string[]` | 必填 | 词法检索所用的词。 |
| `candidates` | `DevExplainCandidateCount[]` | 必填 | 每一路检索中你能读取的候选数。没有返回任何你能读取的结果的那一路检索不列出。 |
| `fused_count` | `integer` | 必填 | 各路检索合并后你能读取的候选数。 |
| `rerank` | `DevExplainRerankSummary` | 必填 |  |
| `clauses` | `string[]` | 可选 | 任务陈述了多件事时：分别检索的各个子句。 |

## DevFieldError

请求体中的一个问题。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `field` | `string` | 可选 | 出错的字段，写成以点分隔的路径，例如 `messages.0.role`。问题在于整个请求体时没有这个字段。 |
| `code` | `string` | 必填 | `validation_error`；有更具体的错误码时用那个错误码。 |
| `message` | `string` | 必填 | 给人看的英文说明。 |

## DevFileAttributes

写文件时可以随字节一起记到文件的 Entry 上的内容。每个字段都可选，只有传了的才会改：替换文件时保留它已有的元数据、时间和开关。字节没变、不产生版本时它们也生效。只对主线：在分支上或在变成提案的写入上设置其中任何字段都返回 422，因为 Entry 属于文件的所有者。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `occurred_at` | `string (date-time)` | 可选 | 文件内容发生的时间，例如录音或录像的录制时间。检索的 `occurred_from` / `occurred_to` 以此为准，段落中也会返回该时间；未提供时以文件写入时间为准。 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据，与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 上的 `metadata` 相同。检索的 `filter.metadata` 按它匹配。 |
| `memory_exclude` | `boolean` | 可选 | 为 `true` 时该文件不参与记忆提炼：文件照常保存、建立索引并可检索，但不会从中提炼记忆；为 `false` 时重新提炼。与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关。 |

## DevFileBatchDelete

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `delete` | 必填 | 恒为 `delete`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `if_match` | `string` | 可选 | 文件的 `etag`：仅当其仍为当前值时删除，否则该项返回 412 `precondition_failed`。 |

## DevFileBatchItem

取值: `DevFileBatchPut | DevFileBatchDelete`

## DevFileBatchPut

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `put` | 必填 | 恒为 `put`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `content` | `string` | 必填 | UTF-8 文本，最大 64 KiB。 |
| `media_type` | `string` | 可选 | 默认 `text/plain`。 |
| `if_match` | `string` | 可选 | 文件的 `etag`。 |
| `if_none_match` | `*` | 可选 | 只接受 `*`：仅当路径上尚无文件时写入，与 `PUT` 的 `If-None-Match: *` 相同。已有文件时该项返回 412 `precondition_failed`，批次中其余项照常执行。不能与 `if_match` 同时指定。 |
| `occurred_at` | `string (date-time)` | 可选 | 文件内容发生的时间，例如录音或录像的录制时间。检索的 `occurred_from` / `occurred_to` 以此为准，段落中也会返回该时间；未提供时以文件写入时间为准。 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据，与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 上的 `metadata` 相同。检索的 `filter.metadata` 按它匹配。 |
| `memory_exclude` | `boolean` | 可选 | 为 `true` 时该文件不参与记忆提炼：文件照常保存、建立索引并可检索，但不会从中提炼记忆；为 `false` 时重新提炼。与 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关。 |

## DevFileBatchRequest

最多 50 个条目，总量 1 MiB。每个条目按顺序在各自的事务中提交。一个条目失败不影响其余条目：服务返回 200，每条结果有自己的 `status`。带 `Idempotency-Key` 再发一次可完成请求：已提交的条目重放，其余的继续执行。Entry 之后被彻底删除的条目重放为 410 `gone`，`path` 为 `/`：写入已发生，回执随 Entry 一起彻底删除。请按位置对应结果和条目。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `items` | `DevFileBatchItem[]` | 必填 | 1 到 50 个写入和删除，按顺序执行。 1 到 50 项 |
| `session_id` | `string` | 可选 | 这些改动出自你的哪段对话，与 `PUT files?session_id=` 相同：它会记录在每条 `put` 创建的版本上，可在 `lineage` 中查看。仅适用于主线：带 `branch` 时返回 422。 长度 1 到 256 |

## DevFileBatchResponse

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevFileBatchResult[]` | 必填 | 每项一个结果，顺序与发来的一致。 |
| `queue` | `DevQueueEstimate` | 可选 | 进入处理队列的条目数，以及账户队列大约需要的时间。 |

## DevFileBatchResult

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `status` | `integer` | 必填 | 这一项如果单独发请求会得到的 HTTP 状态，比如 200、201、404、412。 |
| `write` | `DevFileWrite` | 可选 |  |
| `proposal` | `DevProposalReceipt` | 可选 | `Prefer: handling=proposal` 让这一条变成提案时出现，代替 `write`，状态是 202。 |
| `deletion` | `DevFileDeletion` | 可选 | `delete` 成功时返回。 |
| `branch_write` | `DevBranchFileWrite` | 可选 | 请求带了 `branch` 时代替 `write` 出现。 |
| `branch_deletion` | `DevBranchFileDeletion` | 可选 | 请求带了 `branch` 时代替 `deletion` 出现。 |
| `error` | `DevErrorBody` | 可选 | 仅失败的项返回：单独发送请求时会返回的错误体。 |

## DevFileDeletion

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `deleted` | `true` | 必填 | 恒为 true：文件已进废纸篓。 |

## DevFileEdit

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `old_text` | `string` | 必填 | 必须恰好出现一次，除非设置了 `replace_all`。 最短 1 |
| `new_text` | `string` | 必填 | 用来替换 `old_text` 的内容。为空字符串时删除 `old_text`。 |
| `replace_all` | `boolean` | 可选 | 替换 `old_text` 的每一处，而不是要求它正好出现一次。 默认 false |

## DevFilePatchRequest

只支持 UTF-8 文本文件，其他返回 415 `unsupported_media_type`。超过 1 MiB 返回 413 `patch_base_too_large`，请改用 `PUT` 替换。修改按顺序应用，每条作用于上一条的结果。请求期间基线变化时重试一次，再失败返回 412 `precondition_failed`；带 `If-Match` 时不重试。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `edits` | `DevFileEdit[]` | 必填 | 1 到 100 处修改，按顺序应用。 1 到 100 项 |

## DevFileView

读取文件的哪种形式。`raw`：原始字节，支持 `Range`。`meta`：以 JSON 返回的 Entry（`DevEntry`）。`text`：从文件中提取的文本。`table`：表格文件的行。`recognized`：从图片或录音中识别出的文本。`text`、`table` 和 `recognized` 返回 `DevEntryContent`。

取值: `raw | meta | text | table | recognized`

## DevFileWrite

写入已提交且可读。`knowledge.state` 表示索引进度：64 KiB 以内的文本立即为 `searchable`，其他内容在 `indexed` 之前为 `readable`。替换文件的新版本最终处理失败时，路径退回上一个可用版本，`changes` 会报告这一变化。失败的版本留在 `versions` 里，状态为 `discarded`，可以用 `version=` 读取字节，用 `revert` 恢复。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry` | `DevEntry` | 必填 | 写入之后的 Entry。 |
| `version_id` | `DevId` | 必填 | 现在保存这份内容的版本。它就是去掉引号的 `ETag`。 |
| `previous_version_id` | `DevId` | 可选 | 这次写入替换掉的版本。新建文件、或没有产生新版本时不带这个字段。 |
| `version_created` | `boolean` | 必填 | 内容没变、没有产生版本时为 false。 |

## DevFilterCondition

`filter.where` 的一个条件。它必须是以下四种形式之一，其他形式返回 422： - `{"and": [...]}` 或 `{"or": [...]}`：1 到 16 个条件； - `{"not": condition}`； - `{"key": "<metadata key>", <operator>}`，恰好带一个运算符：`eq`（一个值）、`in`（1 到 32 个值）、`exists`（`true`：Entry 有该键；`false`：Entry 没有该键），或由 `gt`/`gte` 和 `lt`/`lte` 构成的范围。范围比较的是该键下存储的值。数字为十进制数，例如 `-12` 或 `3.5`；日期为 `YYYY-MM-DD` 或 ISO 8601 时刻，不带时区偏移的值按 UTC 解释。无法按边界类型解读的值不参与比较。一个键下有多个值时，任一值满足即视为条件成立。`and`、`or` 和 `not` 最多嵌套 3 层，键条件总数最多 16 个。`in` 和 `eq` 还会收窄向量检索；`exists` 和范围只由主数据库执行，因此选择性很强的范围返回的语义匹配可能少于 `limit`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `and` | `DevFilterCondition[]` | 可选 | 以下条件全部成立。1 到 16 个。 1 到 16 项 |
| `or` | `DevFilterCondition[]` | 可选 | 以下条件至少一个成立。1 到 16 个。 1 到 16 项 |
| `not` | `DevFilterCondition` | 可选 | 该条件不成立。没有该键的 Entry 满足 `{"not": {"key": k, "eq": v}}`。 |
| `key` | `string` | 可选 | 键条件中的元数据键：1 到 64 个字符，可用 a-z、0-9、`_`、`.`、`-`。 |
| `eq` | `DevMetadataValue` | 可选 | Entry 在该键下存有该值。 最短 1 |
| `in` | `DevMetadataValue[]` | 可选 | Entry 在该键下存有这些值之一，1 到 32 个。 1 到 32 项 |
| `exists` | `boolean` | 可选 | `true`：Entry 有该键；`false`：Entry 没有该键。 |
| `gt` | `DevFilterRangeBound` | 可选 | 大于。不能与 `gte` 同时使用。 |
| `gte` | `DevFilterRangeBound` | 可选 | 大于或等于。不能与 `gt` 同时使用。 |
| `lt` | `DevFilterRangeBound` | 可选 | 小于。不能与 `lte` 同时使用。 |
| `lte` | `DevFilterRangeBound` | 可选 | 小于或等于。不能与 `lt` 同时使用。 |

## DevFilterRangeBound

范围边界：一个数字，或 `YYYY-MM-DD` 格式的日期，或带时区偏移的 ISO 8601 时刻。同一条件的所有边界类型相同。

取值: `number | string`

## DevForgottenSource

被遗忘的事实所出自的 Entry 版本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevHitExplain

返回这条命中的原因。仅当请求设置了 `explain` 时返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `found_by` | `DevExplainBranchRank[]` | 必填 | 返回它的各路检索，以及它在每一路中的位置。对于计算得出的表格，此项为空。 |
| `fused` | `DevExplainRank` | 可选 | 各路检索合并后、重排前的位置和分数，二者都只在你能读取的候选中计算。 |
| `rerank` | `DevExplainRerank` | 可选 | 重排给出的位置和分数。未重排或重排未给出分数时不返回。 |
| `matched_terms` | `string[]` | 可选 | 其文本匹配到的查询词。中文按两字词匹配。 |
| `lexical` | `strong \| covered \| partial` | 可选 | 其词语对查询的覆盖程度：`strong` 不受相关性下限限制，`covered` 和 `partial` 受限制。 |
| `admitted_by` | `DevExplainAdmission` | 可选 | 使它通过相关性下限的依据。未应用下限时不返回。 |
| `boosts` | `DevExplainBoost[]` | 可选 | 使它排名上升的规则。 |
| `reordered_by_date` | `string` | 可选 | 设为 `newest_first` 时：排序所依据的日期（`occurred_at`，没有时取 `stated_date`），格式为 `YYYY-MM-DD`。 |
| `computed_table` | `true` | 可选 | 服务对整张表计算得出的条目为 true（`route.rules_fired` 中有 `table_aggregate:computed`）。 |

## DevId

服务端签发的不透明标识符，客户端按字节比较。

取值: `string`

## DevIdempotencyKey

取值: `string`

## DevImportConflict

取值: `skip | overwrite`

## DevImportFailure

导入时无法写入的一个归档成员。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `index` | `integer` | 必填 | 成员在归档里的位置，从 0 开始，所有成员都计数（包括 `manifest.json`）。 |
| `code` | `string` | 必填 | 原因，用错误码表示：`invalid_path`、`reserved_path`、`path_conflict`、`unsupported_member`、`payload_too_large`、`proposal_required`…… |

## DevIngestConversation

一个批次是一个 Entry，无论有多少轮。发送时持有 `memory:confirm`，从中提炼的事实就是 `confirmed`，否则是 `candidate`，等待审核。渲染后的对话最多 2,000,000 字符。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `conversation` | 必填 | 恒为 `conversation`。 |
| `session_id` | `string` | 必填 | 你给这段对话的 id，1 到 256 个字符。同一段对话分几段写入时都带同一个 `session_id`：每一批是一个独立的 Entry，这个 id 同时记成元数据键 `session_id`（除非你的 `metadata` 里已经有这个键），所以同一段对话的各批可以用 [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 一起列出，用 `filter.metadata` 一起检索。没传 `title` 时用它给 Entry 起名。 长度 1 到 256 |
| `messages` | `DevConversationMessage[]` | 必填 | 这一批的消息，按说话的先后顺序排列：1 到 1000 条。 1 到 1000 项 |
| `title` | `string` | 可选 | 默认为 `Conversation <session_id>`。 长度 1 到 512 |
| `metadata` | `DevMetadata` | 可选 | 和其他来源一样记在 Entry 上。对话的时间取自消息的 `timestamp`。 |
| `memory_exclude` | `boolean` | 可选 | 为 true 时，这个 Entry 从一开始就不参与记忆提炼：它照常保存、建索引、可检索，但不会从中提炼任何记忆。和 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关，之后可以改回来。 |
| `redact_secrets` | `boolean` | 可选 | 为 true 时，在存任何东西之前先把文本（和 `title`）里看起来像凭据的内容替换掉：私钥块、JWT、`Bearer` 令牌、常见的 API Key 格式，以及 `password=`、`api_key:` 这类写法后面的值。此后检索、读取和提炼出的记忆看到的都只是替换后的文本，回执里的 `secrets_redacted` 说明替换了几处。不常见的密钥格式可能无法识别。 |
| `memory_instructions` | `string` | 可选 | 你对这段对话该记住什么的说明，1 到 2,000 个字符：在你的应用里哪些重要、哪些可以忽略、记到多细（例如“记住饮食禁忌和过敏；忽略关于天气的闲聊”）。它和消息一起交给提炼这段对话的模型，但不能改变规则：每条记忆仍须有消息里的原文作依据，不会凭空生成。它随这一版保存，重新处理时照样使用；要改说明，请重新写入这一批对话。 长度 1 到 2000 |

## DevIngestReceipt

`ingest` 的响应内容：它创建的 Entry 和版本、处理它们的任务，以及这个 Entry 目前已经可以搜索到什么程度。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 新建的 Entry。 |
| `version_id` | `DevId` | 必填 | 它的第一个版本。 |
| `job_id` | `DevId` | 必填 | 处理任务。这个版本索引完成后 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read) 才是 `succeeded`；同样的进度也在 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing)。对话在这之后才提炼：两处都用 `memory.state` 报告提炼进度。 |
| `knowledge` | `DevEntryKnowledge` | 必填 | 64 KiB 以内的文本通常是 `searchable`，其他内容在处理完成前是 `readable`。 |
| `memory_status` | `candidate \| confirmed` | 可选 | 只在对话上出现：提炼出的内容是直接生效还是等待审核。 |
| `memory` | `DevMemoryProcessing` | 可选 | 仅对话包含此字段：索引完成后将进行提炼时为 `pending`；不进行提炼时为 `skipped`，并在 `reason` 中说明原因。后续进展请轮询 [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing)。 |
| `secrets_redacted` | `integer` | 可选 | 只有请求带了 `redact_secrets` 才有：替换了几处。0 表示没有发现像凭据的内容。 |

## DevIngestRequest

取值: `DevIngestUrl | DevIngestText | DevIngestConversation`

## DevIngestText

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `text` | 必填 | 恒为 `text`。 |
| `text` | `string` | 必填 | 要保存的文本，1 到 2,000,000 个字符。 长度 1 到 2000000 |
| `title` | `string` | 可选 | 默认取第一行。 长度 1 到 512 |
| `occurred_at` | `string (date-time)` | 可选 | 文本内容发生的时间，比如会议或邮件的日期。默认未知；此时检索的 `occurred_from` / `occurred_to` 按写入时间算。 |
| `metadata` | `DevMetadata` | 可选 |  |
| `memory_exclude` | `boolean` | 可选 | 为 true 时，这个 Entry 从一开始就不参与记忆提炼：它照常保存、建索引、可检索，但不会从中提炼任何记忆。和 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关，之后可以改回来。 |
| `redact_secrets` | `boolean` | 可选 | 为 true 时，在存任何东西之前先把文本（和 `title`）里看起来像凭据的内容替换掉：私钥块、JWT、`Bearer` 令牌、常见的 API Key 格式，以及 `password=`、`api_key:` 这类写法后面的值。此后检索、读取和提炼出的记忆看到的都只是替换后的文本，回执里的 `secrets_redacted` 说明替换了几处。不常见的密钥格式可能无法识别。 |

## DevIngestUrl

页面在响应返回之后才抓取和解析，因此网址有问题时表现为任务失败：无法抓取页面时为 `url_fetch_failed`，页面没有正文时为 `url_no_readable_content`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `url` | 必填 | 恒为 `url`。 |
| `url` | `string (uri)` | 必填 | 要抓取的网页，`http` 或 `https`，最多 8192 个字符。 最长 8192 |
| `title` | `string` | 可选 | 这个 Entry 的标题，1 到 512 个字符。 长度 1 到 512 |
| `occurred_at` | `string (date-time)` | 可选 | 网页内容发生的时间，如果你知道的话。检索的 `occurred_from` / `occurred_to` 按它算。 |
| `metadata` | `DevMetadata` | 可选 |  |
| `memory_exclude` | `boolean` | 可选 | 为 true 时，这个 Entry 从一开始就不参与记忆提炼：它照常保存、建索引、可检索，但不会从中提炼任何记忆。和 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 的 `memory_exclude` 是同一个开关，之后可以改回来。 |

## DevIssuedApiKey

创建和轮换时返回。服务只保存 `token` 的哈希。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 以 `key_` 开头。它不是密钥本身：令牌只在创建或轮换 Key 时返回一次。 |
| `principal_id` | `DevId` | 必填 | 这个 Key 代表的主体。 |
| `name` | `string` | 必填 | 你为这个 Key 指定的名称。 |
| `prefix` | `string` | 必填 | 令牌的非敏感前缀，用于在列表中识别 Key。 |
| `capabilities` | `DevCapability[]` | 必填 | 这个 Key 能做什么。不会超过它所属主体的能力。 |
| `allowed_space_ids` | `DevId[]` | 可选 | 不存在表示没有收窄到特定 Space。 |
| `metadata_scope` | `DevMetadataScope` | 可选 | Key 受限的元数据范围。没有这个字段表示不按元数据限制。 |
| `expires_at` | `string (date-time)` | 可选 | 过了这个时间 Key 就失效。不过期的 Key 不带这个字段。 |
| `revoked_at` | `string (date-time)` | 可选 | Key 被吊销的时间。仍然有效时不带这个字段。 |
| `last_used_at` | `string (date-time)` | 可选 | 这个 Key 最近一次调用 API 的时间，精确到分钟。尚未使用时不返回该字段。 |
| `created_by` | `DevId` | 必填 | 签发它的主体。 |
| `issued_by_key_id` | `DevId` | 可选 | 签发或轮换出这个 Key 的 Key。未通过 Key 签发时不存在。 |
| `created_at` | `string (date-time)` | 必填 | 签发时间。 |
| `token` | `string` | 可选 | 密钥明文，只显示这一次。幂等重放时不存在，因为服务端不保存：原响应丢失时请轮换 Key。 |

## DevJob

生命周期长于请求的任务，三种类型共用这一结构。处理任务来自 `ingest` 和 `reprocess`，跟随该版本的整条处理链（`parse`、`index`、`publish`）：`stage` 是链上当前所处的阶段，版本索引完成后 `status` 才是 `succeeded`，处理放弃时是 `failed`。`purge` 是单独的任务，`stage` 为 `purge`。树任务（id 以 `tjb_` 开头）来自 `Prefer: respond-async`、导出和导入，`stage` 是 `tree.move`、`tree.delete`、`tree.restore`、`tree.copy`、`branch.merge`、`space.export` 或 `space.import`，`status` 不会是 `cancelled`；只有发起者和 Space 所有者能读取，完成的树任务保留 7 天。离线整理（id 以 `drm_` 开头，仅在开启离线整理的部署上）的 `stage` 是 `memory.dream`。每隔一两秒轮询一次；任务不支持长轮询。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `kind` | `DevJobKind` | 必填 | 这是三种里的哪一种：`processing`（来自 `ingest`、`reprocess`、彻底删除）、`tree`（id 以 `tjb_` 开头）或 `dream`（id 以 `drm_` 开头）。它决定 `stage` 用哪套词、该看哪些字段。 |
| `status` | `DevJobStatus` | 必填 | `queued`、`running`，然后是 `succeeded`、`failed` 或 `cancelled`。 |
| `stage` | `string` | 必填 | 任务正在做什么，见上面的说明。 |
| `entry_id` | `DevId` | 可选 | 处理任务：正在处理的 Entry。 |
| `version_id` | `DevId` | 可选 | 处理任务：正在处理的版本。 |
| `error` | `DevJobFailure` | 可选 | 仅在 `status` 为 `failed` 时出现。 |
| `memory` | `DevMemoryProcessing` | 可选 | 对话批次的处理任务：记忆提炼的进度。`status` 不等它完成。 |
| `space_id` | `DevId` | 可选 | 仅限树任务。 |
| `progress` | `DevJobProgress` | 可选 |  |
| `result` | `DevTreeJobResult` | 可选 |  |
| `queue` | `DevQueueEstimate` | 可选 | 导入：进入处理队列的已导入文件数，以及账户队列大约需要的时间。 |
| `created_at` | `string (date-time)` | 必填 | 任务创建的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 任务最近一次改变状态或有进展的时间。 |

## DevJobFailure

处理任务的 `code` 和 `message` 与 [`GET /v2/entries/{id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing) 上的相同。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `string` | 必填 | 稳定的失败码。按它分支处理。 |
| `message` | `string` | 必填 | 供人阅读的英文说明，可能变更。 |
| `field` | `string` | 可选 | 树任务：错误涉及的请求字段，与同步请求报错时给出的相同。 |

## DevJobKind

任务做什么。`processing`：解析并索引一个版本，由 `ingest`、`reprocess` 或彻底删除产生。`tree`：以任务方式运行的目录操作、合并、导出或导入，id 以 `tjb_` 开头。`dream`：一次离线整理，id 以 `drm_` 开头。

取值: `processing | tree | dream`

## DevJobProgress

树任务的进度。`done` 是已经处理的节点、合并路径、导出文件或归档成员的数量。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `done` | `integer` | 必填 | 到目前为止处理了多少个单位。 |
| `total` | `integer` | 可选 | 任务统计完工作量后确定。 |

## DevJobReceipt

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `job_id` | `DevId` | 必填 | 轮询 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read)，直到 `status` 为 `succeeded` 或 `failed`。 |

## DevJobStatus

任务所处的状态。`queued`：等待开始。`running`：进行中。`succeeded`：已完成；处理任务要等版本变为 `published` 或 `no_recallable_content` 才算成功。`failed`：未成功结束，原因见 `error`。`cancelled`：服务在处理任务完成前停止了它；树任务和整理不会出现这个状态。

取值: `queued | running | succeeded | failed | cancelled`

## DevKnowledgeState

提交后为 `readable`。`searchable` 表示词法搜索已经能找到，适用于请求体里 64 KiB 以内的文本。处理完成后为 `indexed`。放弃处理时为 `failed`，字节仍然可读。

取值: `readable | searchable | indexed | failed`

## DevLimit

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | 稳定的限额名，例如 `requests_per_minute_read`。此字段上的 `x-mirabase-limits` 列出每个限额名的默认值、作用范围，以及超出时的返回（`exceeded`）。部署可以调整这些值，本接口返回实际生效的值。另外，请求体的读取时限为 180 秒，超时返回 408 `request_timeout`，这一项不在列表中。 |
| `value` | `integer` | 必填 | 这个账户在这项限制上的取值。 |

### 限额

| 名称 | 默认值 | 范围 | 超出时 |
| --- | --- | --- | --- |
| `requests_per_minute_read` | 600 | 每个 Key：每分钟的 `GET`、`HEAD`、`search` 和 `context` 请求数 | 429 `rate_limited`，带 `limit: request_rate` |
| `requests_per_minute_write` | 120 | 每个 Key：每分钟的其他请求数 | 429 `rate_limited`，带 `limit: request_rate` |
| `retrieval_concurrency` | 2 | 每个主体：同时运行的搜索和上下文调用数 | 等待名额最多 1 秒后，返回 429 `rate_limited`，带 `limit: concurrency` |
| `agent_retrieval_concurrency` | 8 | 每个 Agent 主体，代替 `retrieval_concurrency` | 等待名额最多 1 秒后，返回 429 `rate_limited`，带 `limit: concurrency` |
| `answer_concurrency` | 3 | 每个主体：同时运行的回答数 | 等待名额最多 10 秒后，返回 429 `rate_limited`，带 `limit: concurrency` |
| `space_write_concurrency` | 4 | 每个 Space：同时运行的写入数 | 等待名额最多 1 秒后，返回 429 `rate_limited`，带 `limit: concurrency` |
| `space_writes_per_month` | 100,000 | 每个 Space：一个 UTC 自然月内的写入数 | 429 `quota_exceeded` |
| `tenant_writes_per_month` | 1,000,000 | 每个账户：一个 UTC 自然月内的写入数 | 429 `quota_exceeded` |
| `space_storage_bytes` | 10 GiB | 每个 Space：存储的字节数 | 429 `quota_exceeded` |
| `tenant_storage_bytes` | 100 GiB | 每个账户：存储的字节数 | 429 `quota_exceeded` |
| `tenant_model_tokens_per_month` | 1,000,000 | 每个账户（仅 `free` 套餐）：一个 UTC 自然月内服务的语言模型为该账户生成的 token（回答、提炼、摘要、分类、记忆整理）。仅在套餐设定此项时列出 | 429 `quota_exceeded`，带 `quota: model_tokens`；需要模型的处理步骤以 `quota_exceeded` 失败 |
| `tenant_model_spend_micro_usd_per_month` | 2,000,000 | 每个账户（仅 `free` 套餐）：一个 UTC 自然月内所有计费的模型调用（语言模型、语音识别、OCR、重排、向量生成、网页搜索），按服务的标价计算，单位为百万分之一美元。每次调用前检查；超出剩余额度的长录音在转写前即被拒绝。仅在套餐设定此项时列出 | 429 `quota_exceeded`，带 `quota: model_spend_micro_usd`；需要模型的处理步骤以 `quota_exceeded` 失败 |
| `tenant_queued_jobs` | 10,000 | 每个账户：使内容可检索的排队任务（解析、图片、音频和视频识别、建索引、发布）。文件可检索之后的模型处理（摘要、分类、关联、记忆）另有上限，为此数的五倍 | 429 `ingest_backlog` |
| `space_active_branches` | 100 | 每个 Space：活跃分支数 | 409 `branch_limit_reached` |
| `branch_paths` | 10,000 | 每个分支：路径数 | 409 `branch_too_large` |
| `branch_checkpoints` | 100 | 每个分支：检查点数 | 409 `checkpoint_limit_reached` |
| `branch_ttl_days` | 30 | 每个分支：无写入多少天后过期 | - |
| `branch_reclaim_days` | 7 | 每个分支：结束后多少天被回收 | - |
| `space_snapshots` | 100 | 每个 Space：快照数 | 409 `too_many_snapshots` |
| `snapshot_files` | 10,000 | 每个快照：文件数 | 409 `snapshot_too_large` |
| `export_max_bytes` | 4 GiB | 每次导出：原件字节数 | 409 `export_too_large` |
| `import_max_bytes` | 1 GiB | 每次导入：归档字节数 | 413 `archive_too_large` |
| `tenant_api_keys` | 100 | 每个账户：活跃的 Key 数 | 409 `tenant_limit_reached` |
| `tenant_principals` | 200 | 每个账户：主体数 | 409 `tenant_limit_reached` |
| `tenant_spaces` | 10,000 | 每个账户：未删除的 Space 数 | 409 `tenant_limit_reached` |
| `team_members` | 50 | 每个团队：成员数（控制台） | - |
| `team_pending_invitations` | 20 | 每个团队：等待接受的邀请数（控制台） | - |
| `team_invitations_per_day` | 100 | 每个团队：一天内发出的邀请数（控制台） | - |
| `tenant_requests_per_minute_read` | 6,000 | 每个账户：所有 Key 合计的每分钟读取请求数，为 `requests_per_minute_read` 的 10 倍 | 429 `rate_limited`，带 `limit: request_rate` |
| `tenant_requests_per_minute_write` | 1,200 | 每个账户：所有 Key 合计的每分钟其他请求数，为 `requests_per_minute_write` 的 10 倍 | 429 `rate_limited`，带 `limit: request_rate` |
| `tenant_retrieval_concurrency` | 80 | 每个账户：所有主体合计同时运行的搜索和上下文调用数，为 `agent_retrieval_concurrency` 的 10 倍 | 等待名额最多 1 秒后，返回 429 `rate_limited`，带 `limit: concurrency` |

## DevLimits

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevLimit[]` | 必填 | 对这个账户生效的每一项限制。 |
| `plan` | `DevPlan` | 可选 | 账户的套餐。`free` 套餐下，`data` 已显示套餐的数值，并列出 `tenant_model_tokens_per_month` 和 `tenant_model_spend_micro_usd_per_month`。 |

## DevLineage

Entry 的来源，以及一页版本（最新的在前）。不列出复制操作者。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `origin` | `DevLineageOrigin` | 必填 | 这个 Entry 是怎么来的。 |
| `data` | `DevLineageVersion[]` | 必填 | 一页版本，最新的在前。 |
| `next_cursor` | `DevCursor` | 可选 | 长度 1 到 1024 |

## DevLineageOrigin

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `DevLineageOriginKind` | 必填 | `created`：直接写入的。`copy`：从另一个 Entry 复制来的。`branch_merge`：由一次分支合并首次写入。 |
| `source` | `DevLineageRef` | 可选 | `copy` 时：复制来源的 Entry 和版本。 |
| `branch_id` | `DevId` | 可选 | `branch_merge` 时：分支，只给 id。分支关闭后会被回收。 |
| `chain` | `DevLineageRef[]` | 可选 | `copy` 且来源本身也是复制来的：再往上的来源，最近的在前，最多 16 个。 |
| `chain_truncated` | `true` | 可选 | 来源链超过 16 步。 |

## DevLineageOriginKind

取值: `created | copy | branch_merge`

## DevLineageRef

复制链往上的一步。对你不可见的来源为 `visible: false`，不带 id，链在此处结束。被彻底删除的来源保留 id，带 `purged: true`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `visible` | `boolean` | 必填 | 来源对你不可见时为 false：不带 id，链在此处结束。 |
| `entry_id` | `DevId` | 可选 | 长度 1 到 256 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `purged` | `true` | 可选 | 来源已被彻底删除时是 true。id 仍然给出。 |

## DevLineageVersion

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `parent_version_ids` | `DevId[]` | 必填 | 这个版本写入时所基于的版本。Entry 的第一个版本为空。 |
| `created_at` | `string (date-time)` | 必填 | 这个版本写入的时间。 |
| `author_principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `kind` | `DevVersionKind` | 必填 |  |
| `restored_from` | `DevId` | 可选 | `revert` 时出现。 |
| `proposal_id` | `DevId` | 可选 | `proposal_accept` 时出现。 |
| `branch_id` | `DevId` | 可选 | `branch_merge` 时出现。 |
| `message` | `string` | 可选 | 该版本的说明；未设置时不返回。 |
| `session_id` | `string` | 可选 | 该版本出自哪段对话：写文件时传入的 `session_id`。可通过 [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/zh/developers/api/entries.md#entries-list) 查询该对话。写入时未指定则不返回；回滚和复制不继承该字段。 |

## DevMcpHandshake

`tools` 列出这个 Key 在这个部署上能调用的工具。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 必填 | MCP 服务的名字。 |
| `version` | `string` | 必填 | 服务的版本。 |
| `protocol` | `string` | 必填 | 服务使用的 MCP 协议版本。 |
| `transport` | `streamable-http` | 必填 | 恒为 `streamable-http`。 |
| `tools` | `DevMcpTool[]` | 必填 | 这个 Key 在这个部署上能调用的工具。 |

## DevMcpRequest

一个 JSON-RPC 2.0 请求，或最多 32 个请求组成的批次。方法由 MCP 定义；`tools/call` 的工具取自 `x-mirabase-mcp-tools`，`arguments` 须符合该工具的 `inputSchema`。

取值: `object`

## DevMcpResponse

一个 JSON-RPC 2.0 响应，或一批响应。工具失败时返回带 `isError: true` 的结果：`content` 的文本给出错误码、能否重试和下一步，`_meta["dev.mirabase/error"]` 是完整的错误信封。失败的结果不带 `structuredContent`。

取值: `object`

## DevMcpTool

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `DevMcpToolName` | 必填 |  |
| `description` | `string` | 必填 | 工具的功能说明，即展示给模型的文本。 |
| `inputSchema` | `object` | 必填 | 工具输入的 JSON Schema。 |

## DevMcpToolName

每个工具是一次 `/v2` 请求：同一个 Key、同样的限制、同样的错误信封。

取值: `mira.whoami | mira.files.list | mira.files.read | mira.files.write | mira.files.edit | mira.files.delete | mira.search | mira.context | mira.context.feedback | mira.activity | mira.memory.list | mira.memory.remember | mira.memory.forget | mira.conversation.ingest | mira.text.ingest | mira.url.ingest | mira.entries.read | mira.answer | mira.memory.correct | mira.memory.review | mira.trash.list | mira.trash.restore | mira.memory.get`

## DevMemory

三种来源共用一个形状：账户记忆、写成 Entry 的记忆、从 Entry 提炼出的事实。除非记忆是写成 Entry 的，否则 `id` 不是 Entry id。`pinned` 只对这一种有效。被遗忘的记忆没有正文留下，所以不会返回。

“记忆”出现在四个地方，各是不同的集合。[`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 是完整的受治理列表，含候选和历史。上下文包里的 `memory_view`（以及 `MEMORY.md`）是已确认、当前有效内容的索引，不含敏感类别。`search` 的 `include: ["memory"]` 把记忆加进命中，并改用记忆的排序方式。检索命中或上下文条目上的 `memory` 是从那段内容提炼出的一条已确认事实。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 把它传给其他记忆接口。提炼事实的 id 里有冒号，放进路径时要做百分号编码。 |
| `entry_id` | `DevId` | 可选 | 这条记忆本身对应的 Entry，或它从中提炼出来的 Entry。账户记忆没有这个字段。 |
| `space_id` | `DevId` | 可选 | 账户记忆没有这个字段：它不属于任何你能访问的 Space。 |
| `scope` | `DevMemoryScope` | 必填 | 这是谁的记忆：`account`（这个人，跨 Space）、`project`（这个 Space）或 `agent`（某个 Agent 自己的）。 |
| `kind` | `string` | 必填 | 记忆的类别，例如 `preference`、`decision` 或 `progress`；提炼出的事实还有别的类别，例如 `experience`。[`GET /v2/memories?kind=`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 按它筛选。 |
| `status` | `DevMemoryStatus` | 必填 | `confirmed` 的记忆在检索和 `MEMORY.md` 里生效；`candidate` 等待审核；`rejected` 和 `superseded` 是历史记录。 |
| `text` | `string` | 必填 | 记忆的内容，一句陈述。 |
| `pinned` | `boolean` | 必填 | 这条记忆是否置顶。只有写成 Entry 的记忆可以置顶。 |
| `supersedes` | `DevId` | 可选 | 更正时出现：被它替换的记忆。 |
| `valid_from` | `string (date-time)` | 可选 | 这个事实从什么时候开始成立（来源里说明了的话）。 |
| `valid_to` | `string (date-time)` | 可选 | 这条记忆不再是当前值的时间。带 `replaced_by` 时，是更新的值开始生效的时间。 |
| `created_at` | `string (date-time)` | 必填 | 这条记忆最初写入或提炼出来的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 最后一次变更的时间：审核、更正、置顶或修改有效期。 |
| `replaced_by` | `DevReplacingMemory` | 可选 | 只出现在 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 和 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) 返回的提炼记忆上，且只在开启了证据化记忆的部署上提供：同一属性的当前值。同一 Space、同一范围里后来的对话改了这个属性时出现（先是“住在上海”，后来“搬到杭州”）。这条记忆仍是 `status: "confirmed"`：它曾经成立，只是不再是当前值，`MEMORY.md` 也不再列出它。只有你能读取的更新值才算。 |
| `dormant` | `DevMemoryDormancy` | 可选 | 只在开启了离线整理的部署上，且只出现在 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 和 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read)：被整理标为休眠的提炼记忆。它照常列出、照常可搜索。`MEMORY.md` 只收录人写入或确认过的记忆，这类记忆不会休眠；撤销那次整理即可清除。 |
| `group_id` | `DevId` | 可选 | 只在开启了离线整理的部署上，且只出现在 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 和 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) 的提炼记忆上：这条记忆所在的组。同一 Space、同一范围、同一状态、说同一句话（经 Unicode 规范化、忽略大小写和空白后比较）的提炼记忆是一组，以你看得见的最小 id 列一次。只计来源你看得见的成员。 |
| `sources` | `DevMemorySource[]` | 可选 | 有 `group_id` 时：你看得见的组员，最小 id 在前，包括这一条。 |
| `pending_proposals` | `DevId[]` | 可选 | 只在开启了离线整理的部署上，出现在 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 和 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read)：关于这条记忆（或它所在组的成员）的打开状态的整理提案，最早的在前，只含你看得见的提案。没有时不返回。 |

## DevMemoryD4Mode

整理是否请模型比较提炼记忆的配对（D4）。`off`（默认）从不询问；`shadow` 询问并记录判定，但不提出任何东西；`propose` 把通过校验的判定写成 `open` 提案。模型从不写会进入记忆的文字：它只说明两条记忆的关系，并逐字引用来源。`d4_available` 为假的部署无论这里怎么设都不会询问模型。

取值: `off | shadow | propose`

## DevMemoryDormancy

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `reason` | `DevMemoryDormancyReason` | 必填 |  |
| `dream_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevMemoryDormancyMode

整理如何处理长期无人使用的提炼记忆（休眠）。`report`（默认）只在报告里计数，并列为 `reported` 动作；`apply` 把它们标为 `dormant`，原因 `unused`。休眠的记忆离开 `RECENT.md`，但照常列出、可搜索，第一次再被取用时（[`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read)，或由搜索、上下文包、回答返回）即恢复生效。规则和偏好不会被标为 `unused`，但引文找不到的规则仍可能被标为 `quote_missing`。人确认过的记忆从不被标记，所以 `MEMORY.md` 里的内容不会休眠。

取值: `report | apply`

## DevMemoryDormancyReason

整理为什么把一条提炼记忆设为休眠。 - `quote_missing`：它的引文在来源当前版本里一条都找不到了。只有无人审核过的提炼记忆才会得到这个原因：`status: "confirmed"` 也包括未经审核即生效的记忆；审核通过的候选，以及带 `memory:confirm` 导入的对话里提炼出的记忆，从不会。确认这条记忆即可清除。 - `unused`：90 天没有被取用、这个范围连续三次整理都没有被取用、不在同类型取用最多的 20 条之内，既不是规则或偏好，也不是人确认过的记忆；只在 Space 设置 `dormancy` 为 `apply` 时出现。再次被取用（[`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read)，或由搜索、上下文包、回答返回）即恢复生效。来源之后再提炼一次（包括改写这条记忆的提炼）会清除这两种原因。两种同时存在时报告 `quote_missing`。

取值: `quote_missing | unused`

## DevMemoryDreamingMode

这个 Space 是否运行离线整理（“dreams”）。`propose` 是默认值，允许运行；`off` 停止。整理只重新组织已有的记忆：不生成任何内容，每个动作都带证据，可以撤销。`auto` 尚不可用。

取值: `off | propose`

## DevMemoryForgetReceipt

正文已不存在，因此没有其他内容可返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `status` | `forgotten` | 必填 | 恒为 `forgotten`。 |
| `remaining_sources` | `DevForgottenSource[]` | 可选 | 只在遗忘提炼事实时出现：它所出自的 Entry。事实已被彻底删除，也不会再被提炼出来，但来源里的原文仍在，仍会被检索到。如果内容本身也需要移除，请将这些 Entry 一并移入废纸篓或彻底删除。 |

## DevMemoryLayer

离线整理如何对待一条提炼出的记忆，由它的 `kind` 和有效时间决定。`rule`：规则和偏好（`preference`、`profile`、`workflow`、`lesson`、`commitment`），不会因闲置而休眠。`decision`：决定和进度（`decision`、`progress`、`task`、`outcome`）。`event`：事件（`experience`、`failure`，以及其他带 `valid_from` 的记忆），不比较也不合并，时间线保持不变。`knowledge`：其余的提炼事实。

取值: `rule | decision | event | knowledge`

## DevMemoryProcessing

对话批次的记忆提炼。它在版本索引完成之后才运行，所以处理任务已经是 `succeeded` 时，这里可能仍是 `pending`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `state` | `pending \| ready \| skipped \| failed` | 必填 | 提炼完成前为 `pending`。完成后为 `ready`，写入的记忆可通过 [`GET /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-list) 获取。提炼放弃时为 `failed`。该版本不执行提炼时为 `skipped`，原因见 `reason`。 |
| `count` | `integer` | 可选 | 只在 `state` 为 `ready` 时出现：这一批写下的记忆数，含候选。0 表示没有值得保留的内容。 |
| `reason` | `DevMemoryProcessingReason` | 可选 | 状态为 `skipped` 时，表示不执行提炼的原因。状态为 `pending` 时，仅可能为 `distill_paused`，表示等待时间比平时长，且只向能看到账户状态的调用方返回。状态为 `skipped` 时，仅当服务无法判断原因时才不返回此字段。部署停止提炼之前已提炼完的版本仍为 `ready`。 |
| `remediation` | `DevRemediation` | 可选 | 仅当 `reason` 有可执行的后续操作时返回，格式与错误响应中的相同。`clear_memory_exclude`：用 [`PATCH /v2/entries/{id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 将 `memory_exclude` 设为 false。`write_memories_directly`：当前部署不执行提炼，请用 [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) 自行写入记忆。`review_usage`：查看 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage)。`wait_and_retry`：稍后再次轮询。 |

## DevMemoryProcessingReason

版本不执行提炼或等待时间比平时长的原因。 - `memory_excluded`：Entry 设置了 `memory_exclude`。 - `distill_disabled`：当前部署已关闭记忆提炼。 - `model_not_configured`：当前部署未配置用于提炼的模型。 - `distill_paused`：账户的记忆提炼已暂停，将在用量周期重置时自动恢复。 - `processing_failed`：该版本处理失败，原因见处理状态中的 `error`。 - `nothing_to_distill`：该版本没有可提炼的文本。 - `distill_unavailable`：当前不执行提炼。除非调用方的 Key 属于 `tenant_admin` 或持有 `knowledge:manage`，且未限定到 Space 或元数据范围，否则调用方看到的是此原因，而非 `distill_disabled` 和 `model_not_configured`：后两者描述的是部署的配置。在管理员看到 `distill_paused`（表示账户已达到用量上限）的情况下，上述调用方看到的是不带原因的 `pending`。后续可能新增原因；遇到未知原因时，请仅按状态处理。

取值: `memory_excluded | distill_disabled | model_not_configured | distill_paused | processing_failed | nothing_to_distill | distill_unavailable`

## DevMemoryProposal

整理提出、但不自行执行的改动，等待人工决定：合并说同一件事的记忆，让较新的记忆取代较旧的，标出互相矛盾的两条，或把 Agent 的私有记忆提升到项目。只有每个成员的来源你都看得见时才可见，否则返回 404。只有 Space 的 `d4` 设置为 `propose`、且这个部署配置了模型时，整理才写提案。模型从不写会进入记忆的文字，所以 `proposed_text` 目前总是没有。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `scope` | `DevDreamScope` | 必填 |  |
| `agent_principal_id` | `DevId` | 可选 | `agent` 提案：是谁的私有记忆。 |
| `dream_id` | `DevId` | 必填 | 提出它的那次整理。 |
| `kind` | `DevMemoryProposalKind` | 必填 | 它建议做什么：`merge`、`supersede`、`conflict` 或 `promote`。 |
| `member_ids` | `DevId[]` | 必填 | 它涉及的记忆，已排序。 |
| `proposed_text` | `string` | 可选 | 它提出的陈述。目前不返回；`conflict` 始终不返回。 |
| `evidence` | `DevMemoryProposalEvidence[]` | 可选 | 支撑这条提案的逐字引文。 |
| `plan` | `DevMemoryProposalPlan` | 可选 | `approve` 会做什么。`conflict` 没有，它没有可执行的内容。 |
| `layer` | `DevMemoryLayer` | 可选 | 成员所在的记忆层：`rule`、`decision`、`event` 或 `knowledge`。 |
| `times` | `DevMemoryProposalTime[]` | 可选 | 决定哪条记忆较新的日期。 |
| `status` | `DevMemoryProposalStatus` | 必填 | 整理在提案处于打开状态期间被撤销时为 `withdrawn`；成员在批准前发生变更为 `stale`；`rejected` 的提案不会再针对相同的成员提出。整理被撤销后，`approved` 仍保持为 `approved`：请查看该次整理的动作以确认改动是否仍然有效。 |
| `reviewed_by_principal_id` | `DevId` | 可选 | 批准或拒绝该提案的主体。 |
| `reviewed_at` | `string (date-time)` | 可选 | 批准或拒绝的时间。 |
| `closed_at` | `string (date-time)` | 可选 | 脱离 `open` 状态的时间，不论原因。 |
| `created_at` | `string (date-time)` | 必填 | 这次整理写下这条提案的时间。 |

## DevMemoryProposalEvidence

支撑提案的一段逐字引文，取自读到它的那个来源版本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `quote` | `string` | 必填 | 引文，一字不差。 |

## DevMemoryProposalKind

整理提案建议的改动。`merge`：两条记忆表达同一内容，一条并入另一条。`supersede`：较新的记忆取代较旧的。`conflict`：两条记忆互相矛盾，仅供人工查看，不能批准。`promote`：把 Agent 的私有记忆提升到项目，不能批准。

取值: `merge | supersede | conflict | promote`

## DevMemoryProposalPlan

批准会做什么：留下的那条记忆，以及被它取代或并入它的记忆。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `keep` | `DevId` | 必填 | 保留的那条记忆。 |
| `close` | `DevId[]` | 必填 | 批准后会被关闭的记忆：被 `keep` 替换或并入 `keep` 的那些。 |

## DevMemoryProposalStatus

整理提案的状态。`open`：等待人工处理。`approved`：已执行。`rejected`：已关闭且未做改动，同样的成员不会再被提出同样的改动。`stale`：批准前有成员发生了变化。`withdrawn`：提案未处理时，它所属的整理被撤销。

取值: `open | approved | rejected | stale | withdrawn`

## DevMemoryProposalTime

支持提案的一个日期：来源里的原话，或来源本身的日期。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `date` | `string` | 必填 | 日期：来源里写的那个，或来源本身的日期。 |
| `quote` | `string` | 必填 | 来源中标明该日期的引文。 |

## DevMemoryProvenance

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `sources` | `DevMemoryProvenanceSource[]` | 必填 | 这条记忆依据的 Entry 版本。一次响应全部返回：这个列表不分页。 |

## DevMemoryProvenanceSource

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `quote` | `string` | 可选 | 该版本中支撑这条记忆的引文。 |
| `merged_from` | `DevId` | 可选 | 只在开启了离线整理的部署上：这条来源出自批准 `merge` 提案时并入这条记忆的那条记忆，值是它的 id；只有你看得见它的来源时才列出。 |

## DevMemoryScope

记忆归谁。`project`：一个 Space 的记忆，创建时必须传 `space_id`。`agent`：一个 Agent 的私有记忆，只能用该 Agent 的 Key 写入，没有路径，也不产生变更事件。`account`：账户自己的记忆，只对所有者列出，不属于任何 Space。

取值: `project | agent | account`

## DevMemorySection

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source` | `account \| agent \| project \| usage` | 必填 | `account`、`agent`、`project` 或 `usage`。 |
| `kind` | `string` | 必填 | 记忆的种类，比如 `preference`、`decision`。 |
| `text` | `string` | 必填 | 记忆的内容。 |
| `confidence` | `number` | 必填 | 0 到 1：这条记忆记录的置信度。 0 到 1 |
| `valid_until` | `string (date-time)` | 可选 | 超过该时间后不再返回这条记忆。不过期时不返回。 |
| `source_ref` | `DevMemorySourceRef` | 必填 | 这条记忆的来源。 |

## DevMemorySettings

一个 Space 的离线整理设置。未配置过的 Space 返回默认值，不带 `updated_*` 字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `memory_dreaming` | `DevMemoryDreamingMode` | 必填 | 是否运行离线整理：`propose`（默认）或 `off`。 |
| `dormancy` | `DevMemoryDormancyMode` | 必填 | 离线整理如何处理闲置的记忆：`report`（默认）或 `apply`。 |
| `d4` | `DevMemoryD4Mode` | 必填 | 离线整理是否请模型比较记忆：`off`（默认）、`shadow` 或 `propose`。 |
| `d4_available` | `boolean` | 可选 | 当前部署是否可调用模型执行 D4（运营方已启用该功能并配置了模型）。它描述的是部署的配置，因此仅向属于 `tenant_admin` 或持有 `knowledge:manage` 的 Key 返回，且该 Key 未限定到 Space 或元数据范围。 |
| `updated_at` | `string (date-time)` | 可选 | 设置最近一次修改的时间。尚未配置过此 Space 时不返回。 |
| `updated_by_principal_id` | `DevId` | 可选 | 长度 1 到 256 |

## DevMemorySource

一组提炼记忆中的一个成员。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevMemorySourceRef

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 可选 | 长度 1 到 256 |
| `candidate_id` | `DevId` | 可选 | 长度 1 到 256 |
| `claim_id` | `DevId` | 可选 | 长度 1 到 256 |
| `entry_id` | `DevId` | 可选 | 长度 1 到 256 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |
| `space_id` | `DevId` | 可选 | 长度 1 到 256 |
| `recorded_at` | `string (date-time)` | 必填 | 这条记忆记录的时间。 |
| `valid_from` | `string (date-time)` | 必填 | 这条记忆开始生效的时间。 |

## DevMemoryStatus

记忆的状态。`candidate`：等待审核，检索不使用。`confirmed`：已生效，检索会使用。`rejected`：审核时被驳回。`superseded`：被更正取代，或被批准的整理提案关闭。`rejected` 和 `superseded` 是历史记录，只有按状态指定时列表才返回它们。

取值: `candidate | confirmed | rejected | superseded`

## DevMemoryUndoReceipt

`undo` 撤销了什么，以及随之恢复了什么。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `DevId` | 必填 | 长度 1 到 256 |
| `status` | `undone` | 必填 | 恒为 `undone`。 |
| `restored` | `DevMemory[]` | 必填 | 恢复的记忆，即被撤销的记忆此前替换的记忆。未替换过任何记忆时为空。 |

## DevMemoryView

确定性的记忆视图：同样的记忆产生同样的字节，与任务无关。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `sections` | `DevMemorySection[]` | 必填 | 视图里的记忆，顺序稳定。 |

## DevMergeConflict

分支第一次改这个路径之后，主线又改过它。null 表示没有这个版本：文件当时不存在。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `base_version_id` | `DevId \| null` | 必填 | 分支在这个路径上起步时主线的版本。那时文件不存在则为 null。 |
| `main_version_id` | `DevId \| null` | 必填 | 主线在这个路径上现在的最新版本。文件已不存在则为 null。 |
| `branch_version_id` | `string \| null` | 必填 | 分支的内容哈希，与去掉引号的 `etag` 相同。删除时为 null。 |

## DevMergeConflictPolicy

取值: `abort | keep_main | keep_branch`

## DevMergeProposed

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `proposal_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevMergeRequest

`paths` 只合并这些路径，目录连同下面的全部内容，分支保持活跃；不传时合并后分支变为 `merged`。`on_conflict` 作用于主线最新版本已不是分支起点版本的路径：`abort` 让整次合并失败，`keep_main` 跳过它们，`keep_branch` 覆盖主线。不做内容合并。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message` | `string` | 必填 | 1 到 1000 个字符。记为本次合并写入主线的每个版本的说明。 长度 1 到 1000 |
| `paths` | `DevPath[]` | 可选 | 只合并这些路径，1 到 1000 个；目录会包含其下的全部内容。不传则合并整个分支。 1 到 1000 项 |
| `on_conflict` | `DevMergeConflictPolicy` | 可选 | 对分支起点之后主线又修改过的路径的处理方式：`abort`、`keep_main` 或 `keep_branch`。 默认 "abort" |

## DevMergeResult

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `branch_id` | `DevId` | 必填 | 长度 1 到 256 |
| `state` | `active \| merged` | 必填 | 合并之后分支的状态：`merged`；只合并了 `paths` 时仍是 `active`。 |
| `merged` | `DevPath[]` | 必填 | 写入主线的路径。对应版本见 `merged_items`。 |
| `skipped` | `DevPath[]` | 必填 | 被跳过的路径。对应原因见 `skipped_items`。 |
| `merged_items` | `DevMergedPath[]` | 必填 | 写入主线的每个路径各一项：执行的操作及生成的版本。 |
| `skipped_items` | `DevMergeSkipped[]` | 必填 | 被跳过的每个路径各一项，附跳过原因。 |
| `proposed_items` | `DevMergeProposed[]` | 可选 | 带 `Prefer: handling=proposal` 时：合并的 Agent 不拥有的文件，没有写入而是提交了提案。它们和合并的路径一样离开分支。没有时不出现。 |

## DevMergeSkipReason

取值: `symlink | unchanged | kept_main`

## DevMergeSkipped

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `reason` | `DevMergeSkipReason` | 必填 | `symlink`：符号链接不合并。`unchanged`：主线已经是同样的内容。`kept_main`：主线已变更，且 `on_conflict` 为 `keep_main`。 |

## DevMergedOp

取值: `create | update | delete | mkdir`

## DevMergedPath

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `op` | `DevMergedOp` | 必填 | 合并在主线上做了什么：`create`、`update`、`delete` 或 `mkdir`。 |
| `entry_id` | `DevId` | 可选 | 长度 1 到 256 |
| `version_id` | `DevId` | 可选 | 长度 1 到 256 |

## DevMetadata

你自己在 Entry 上的键和值，含义由调用方决定。键是 1 到 64 个 `a-z`、`0-9`、`_`、`.`、`-` 字符；值是字符串或字符串列表，总共最多 32 个值。检索可以按它们精确匹配过滤（`filter.metadata`）。只有一个值的列表等同于这个值本身：`["a"]` 存储和读回都是 `"a"`。`mirabase.` 开头的键由服务写入，在请求中传入会被拒绝。身份字段名（`user_id`、`tenant_id`、`principal_id`、`roles`、`capabilities`、`entitlements`，任何大小写风格）出现在请求体任何位置（包括这里）都会返回 403 `identity_override`。要隔离某个最终用户的数据，请为其分配单独的 Space。元数据能缩小检索范围，但记忆按 Space 保存：遗忘一句话、某项事实的变更历史和 `memory_view` 均不按元数据过滤，因此两个最终用户共用一个 Space 也会共用其中的记忆。

取值: `object`

## DevMetadataAnyOf

匹配在该键下持有其中任意一个值的 Entry。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `any` | `DevMetadataValue[]` | 必填 | 要匹配的值，1 到 32 个。 1 到 32 项 |

## DevMetadataScope

按元数据授权：Key 受限的标签。对象的每个键对应一个或多个值。这个 API Key 只能看到在每个键上都至少带有其中一个值的 Entry；不带这些标签的 Entry 对它不存在，搜索、上下文、回答、按 id 读取和记忆都一样。它写入的内容按每个键的第一个值保存，所以能读取自己写入的内容，也不能写入其他范围。`{"customer": ["acme", "shared"]}` 可以读取标为 `acme` 或 `shared` 的内容，写入时标为 `acme`。

取值: `object`

## DevMetadataValue

一个元数据值：不能为空，UTF-8 下最多 256 字节。

取值: `string`

## DevParsedSummary

解析结果的几项统计。返回哪些字段取决于内容类型。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `passages` | `integer` | 必填 | 内容为检索切分成的段落数。 |
| `characters` | `integer` | 必填 | 提取出的文本字符数，包括从图片识别和从音频转写的文字。 |
| `duration_ms` | `integer` | 可选 | 音频和视频：时长，单位为毫秒。 |
| `speakers` | `integer` | 可选 | 音频和视频：转写结果区分出的说话人数；未区分时不返回。 |
| `sheets` | `integer` | 可选 | 电子表格和 CSV：工作表数。 |
| `rows` | `integer` | 可选 | 电子表格和 CSV：所有工作表的总行数。 |
| `columns` | `integer` | 可选 | 电子表格和 CSV：列数最多的工作表的列数。 |

## DevPath

Space 内的绝对路径：以 `/` 开头，名字之间用单个 `/` 连接，结尾不带 `/`。最多 64 层、4096 字节，单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较，并保留写入时的拼写。不允许 `.`、`..`、控制字符、反斜杠和首尾空白。`/.mirabase/` 是保留路径，`/.mirabase/skills/<name>/...` 除外。路径超出这些限制时返回 422 `path_too_long`。

取值: `string`

## DevPendingProcessing

请求所涉 Space 中尚不可检索的 Entry。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entries` | `integer` | 必填 | 调用方可见的 Entry 中仍在排队或正在处理的数量。 |

## DevPlan

账户的套餐。`standard` 使用当前部署的限制。`free` 是自助注册账户的初始套餐：它还限制存储、每月写入、每月模型 token、每月模型费用和请求速率（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)）。`legacy` 是在推出套餐之前开通的账户：与 `standard` 一样，沿用当前部署的限制。

取值: `free | standard | legacy`

## DevPrincipal

没有显示名，目录不保存这个字段。请自行按 `id` 记录名称。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 通过接口创建的主体以 `prn_` 开头。 |
| `kind` | `DevPrincipalKind` | 必填 | `human` 表示人，`agent` 表示 Agent。 |
| `roles` | `string[]` | 必填 | 目录里的角色，例如 `tenant_admin`。 |
| `capabilities` | `DevCapability[]` | 必填 | 签发给该主体的 Key 最多可授予的能力。 |
| `created_at` | `string (date-time)` | 必填 | 主体创建的时间。 |

## DevPrincipalKind

取值: `human | agent`

## DevProcessingFailure

处理失败的原因。值得单独处理的错误码：`url_fetch_failed`（无法抓取页面）、`url_no_readable_content`（已抓取页面但无正文，请直接写入文本）、`unsupported_input`、`document_too_large`、`no_chunks`（未提取出可检索内容）、`extraction_timeout`（读取文件超出时间预算，约为 20 秒加每 MiB 1 秒，已被中止；文件已存储，请转换为 PDF 或纯文本，或拆分后重新导入）、`upload_integrity_mismatch`、`upload_type_mismatch`、`not_configured`（当前部署未启用图片或语音识别，或缺少该内容所需的其他处理步骤；文件已存储且可读取，启用相应步骤后重新处理即可）、`quota_exceeded`（`free` 套餐下账户的每月模型配额不足以完成这一步，例如转写一段很长的录音，因此未执行；文件已存储，请在下个月或升级套餐后重新处理）。其他失败为 `job_failed` 或各自的错误码；遇到未知错误码时，请按任务失败处理。`upload_type_mismatch` 是处理失败：文件字节内容与文件声明的媒体类型不符。它不是请求错误 `upload_media_type_mismatch`；后者由 [`POST /v2/uploads/{upload_id}/complete`](https://mirabase.io/zh/developers/api/uploads.md#uploads-complete) 在已存储对象的媒体类型与上传时声明的不一致时返回。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `string` | 必填 | 稳定的失败码。按它分支处理。 |
| `message` | `string` | 必填 | 供人阅读的英文说明，可能变更。 |

## DevProcessingProgress

主要步骤（提取文本、建立索引、发布到搜索）中已完成的步数。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `done` | `integer` | 必填 |  |
| `total` | `integer` | 必填 |  |

## DevProcessingQueue

当前步骤尚未开始的原因。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `position` | `integer` | 必填 | 本账户中排在这一项之前开始的就绪任务数，不计其他账户的任务。对限定了部分 Space 或元数据范围的 Key，只计同一 Space 中的任务（限定元数据范围时，只计该 Key 能读取的文件）。 |
| `waited_seconds` | `integer` | 必填 | 该步骤进入队列后经过的秒数。 |
| `waiting_for` | `capacity \| retry \| paused` | 必填 | `capacity`：所有工作进程均繁忙，有空闲时即开始。其他 Space 和账户的工作与它轮流执行，因此其他位置的大批量导入不会阻塞它。`retry`：上一次尝试失败，该步骤在短暂延迟后重新运行。`paused`：运营方暂停了本账户的处理；该步骤保留排队位置，处理恢复后运行。限定了部分 Space 或元数据范围的 Key 看到的是 `capacity`，而不是 `paused`。 |

## DevProcessingStage

最新版本在处理中所处的阶段。`queued`：已存储，尚未开始任何步骤。`extracting`：正在提取文本。`indexing`：正在为分块生成向量并写入搜索索引。`enriching`：搜索已能找到它，关联、分类、摘要或记忆仍在生成。`ready`：全部步骤已完成。`failed`：已放弃处理。

取值: `queued | extracting | indexing | enriching | ready | failed`

## DevProposal

对一个文件提出的修改。作者和审核人可见：审核人是 Space 所有者，以及能直接修改这个文件的 editor（人和 `direct` 模式的 Agent，且文件在他们的 `write_root` 以内）。其他调用方收到 404。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 可选 | 文件现在的位置。在废纸篓里时没有。 |
| `status` | `DevProposalStatus` | 必填 | 在审核人批准或拒绝、或作者撤回之前为 `open`。 |
| `base_version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `proposed_version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `approved_version_id` | `DevId` | 可选 | 批准时写入的版本。 |
| `author_principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `reviewed_by_principal_id` | `DevId` | 可选 | 批准或拒绝该提案的主体。 |
| `size_bytes` | `integer` | 必填 | 提案内容的字节数。 |
| `media_type` | `string` | 必填 | 提案内容的媒体类型。 |
| `sha256` | `string` | 可选 | 提案字节的十六进制 SHA-256。 |
| `created_at` | `string (date-time)` | 必填 | 提案提出的时间。 |
| `reviewed_at` | `string (date-time)` | 可选 | 批准或拒绝的时间。 |
| `closed_at` | `string (date-time)` | 可选 | 脱离 `open` 状态的时间，不论原因。 |

## DevProposalReceipt

在原本会返回 403 `proposal_required` 的写入请求上携带了 `Prefer: handling=proposal`：`proposal` 模式的 Agent 修改不属于自己的文件。由审核人决定是否采纳。轮询 [`GET /v2/proposals/{proposal_id}`](https://mirabase.io/zh/developers/api/proposals.md#proposals-read) 获取结果。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `applied` | `false` | 必填 | 恒为 false：本次写入已转为提案，文件未变更。 |
| `proposal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `base_version_id` | `DevId` | 必填 | 提案时文件的最新版本。批准时它必须仍是最新版本。 |
| `proposed_version_id` | `DevId` | 必填 | 提案的内容。批准之前它不是文件的版本。 |

## DevProposalStatus

文件提案的状态。`open`：等待审核。`approved`：已写入为文件的新版本。`rejected`：被审核人拒绝。`withdrawn`：被作者撤回。

取值: `open | approved | rejected | withdrawn`

## DevPurgeTrashReceipt

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `purged` | `DevPurgedEntry[]` | 必填 | 本次调用彻底删除的 Entry，最多 100 个。 |
| `has_more` | `boolean` | 必填 | 废纸篓中仍有剩余项时为 true，需再次调用。 |

## DevPurgeTrashRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | 可选 | 仅彻底删除该次删除操作移除的 Entry。不传则彻底删除当前 Space 废纸篓中你可见的全部内容。 |

## DevPurgedEntry

单个被彻底删除的 Entry，以及完成此次删除的任务。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `job_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevQueueEstimate

批量写入放入处理队列的条目数，以及队列大约需要的时间。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `queued_items` | `integer` | 必填 | 写入了新版本、因而进入处理队列的条目数。 |
| `eta_seconds` | `integer` | 可选 | 完成账户全部就绪任务预计所需的秒数（见 [`GET /v2/queue`](https://mirabase.io/zh/developers/api/usage.md#usage-queue)）。无法估计时不返回；对限定了部分 Space 或元数据范围的 Key 也不返回。 |
| `paused` | `boolean` | 可选 | 服务运营方暂停了本账户的处理时返回，值为 true。对限定了部分 Space 或元数据范围的 Key 从不返回。 |

## DevRemediation

错误的处理方式。请按 `action` 分支处理，错误对象上的 `message` 可能变更。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `action` | `string` | 必填 | 稳定的动作名，如 `unauthorized` 之后的 `check_api_key`。 |
| `doc_url` | `string (uri)` | 可选 | 该动作的文档地址。 |

## DevReplacingMemory

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 含有 `:`。放进路径时要做百分号编码。 |
| `text` | `string` | 必填 | 现值的陈述。 |

## DevRequestClient

发起请求的客户端，根据 `User-Agent` 识别。不保存该请求头本身。

取值: `sdk-typescript | sdk-python | cli | mcp | console | curl | browser | postman | python | node | go | other | unknown`

## DevRequestLog

一次 API 请求，只记录元数据：不含请求体或响应体，不含查询字符串，不含 API Key。未通过认证的请求不属于任何账户，因此不记录。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 请求到达的时间。 |
| `method` | `GET \| HEAD \| POST \| PUT \| PATCH \| DELETE \| OPTIONS` | 必填 |  |
| `route` | `string` | 必填 | 方法和路由模板，例如 `GET /v2/spaces/:space_id/files`。不保存 URL 中的 id 和路径。 |
| `status` | `integer` | 必填 |  |
| `error_code` | `string` | 可选 | 调用方收到的错误 `code`。流式回答在流打开后失败时，为其 `error` 事件的错误码（状态码为 200）。 |
| `duration_ms` | `integer` | 必填 | 从请求到达至返回响应的时间；流式回答计至流结束。 |
| `auth` | `api_key \| console \| token` | 必填 | 请求的认证方式：API Key、控制台会话或登录令牌。 |
| `principal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `key_id` | `DevId` | 可选 | 发出请求的 API Key。 |
| `key_name` | `string` | 可选 | 该 API Key 当前的名称和前缀。API Key 删除后不返回。 |
| `key_prefix` | `string` | 可选 |  |
| `space_id` | `DevId` | 可选 | 路径中的 Space（如有）。 |
| `request_id` | `string` | 必填 | 与 `X-Request-Id` 响应头相同。 |
| `trace_id` | `string` | 可选 | 对于检索调用：搜索的 `trace_id`，或上下文包、回答的 `pack_id`。可通过 [`GET /v2/retrieval/traces/{trace_id}`](https://mirabase.io/zh/developers/api/request-logs.md#requestlogs-trace) 读取。 |
| `client` | `DevRequestClient` | 必填 |  |
| `client_version` | `string` | 可选 | 客户端的版本，`User-Agent` 中带有版本时返回。 |

## DevRequestLogPage

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevRequestLog[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |
| `retention_days` | `integer` | 必填 | 请求日志保留的天数。 |

## DevRetrievalClock

查询中相对时间的解析方式。`search`、`context` 和 `answer` 共用这两个字段。仅启用证据化记忆的部署会解析时间词；其他部署接受这两个字段，但仅 `answer` 会使用。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |

## DevRetrievalExplainFlag

`search`、`context` 和 `answer` 共用的检索选项。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

## DevRetrievalFilter

Entry 成为候选必须满足的条件；各条件是“且”的关系，至少需要一项。它们在排序之前生效，所以 `limit` 和 `budget_tokens` 只用于符合条件的 Entry，新鲜缓冲和最终的授权检查也使用同样的条件。在 `search` 上它缩小每一条命中的范围。在 `context` 和 `answer` 上它缩小所有读取 Entry 的来源（知识、文件、变更、技能、Agent 档案）；`memory_view` 不受过滤。没有元数据的 Entry（包括记忆分面）永远不匹配 `metadata` 条件。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `metadata` | `object` | 可选 | 按 Entry 元数据精确匹配，1 到 32 个键。字符串匹配在该键下持有这个值的 Entry；`{any: [...]}` 匹配至少持有其中一个值的 Entry。各键之间是“且”。 |
| `source_types` | `DevSourceType[]` | 可选 | 保留这些类型的 Entry：取值是命中里的 `source_type`。`file` 是文件，`note` 是写入的文本，`web` 是写入的 URL，`agent-conversation` 是写入的对话。写入时的 `kind` 名 `text`、`url`、`conversation` 可以作为后三者的别名。 1 到 8 项 |
| `occurred_from` | `string (date-time)` | 可选 | 保留发生在此刻或之后的 Entry。Entry 的时间是它的 `occurred_at`，没有时取写入时间。 |
| `occurred_to` | `string (date-time)` | 可选 | 保留发生在此刻或之前的 Entry。早于 `occurred_from` 返回 422。 |
| `where` | `DevFilterCondition` | 可选 | 对 Entry 元数据的条件，支持 `in`、`not`、`exists`、数值和日期范围，可用 `and` 和 `or` 组合。与包括 `metadata` 在内的其他条件同时生效。MCP 工具不接受此参数。 |

## DevRetrievalKnobs

一次请求投入多少检索工作、保留哪些结果。`search`、`context` 和 `answer` 上的字段相同，均为可选：不传时检索行为不变。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |

## DevRetrievalTrace

一次检索调用的记录。只有搜索会保存查询文本；上下文和回答的轨迹不含查询文本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `kind` | `search \| context \| answer` | 必填 |  |
| `created_at` | `string (date-time)` | 必填 |  |
| `principal_id` | `DevId` | 可选 | 长度 1 到 256 |
| `query` | `string` | 可选 | 仅搜索：发送时的查询。 |
| `citations` | `DevTraceCitation[]` | 必填 | 该调用返回的或提供给模型的 Entry 和版本。 |
| `summary` | `DevTraceSummary` | 必填 |  |

## DevRevertRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `version_id` | `DevId` | 必填 | 要回滚到的版本的 id；它的内容成为新的最新版本。 |

## DevReviewMemoryRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `decision` | `confirm \| reject` | 必填 | `confirm` 确认候选记忆；`reject` 驳回候选记忆。 |

## DevRollbackRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `checkpoint_id` | `DevId` | 必填 | 要回滚到的检查点的 id。 |

## DevRotatedWebhookSecret

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `webhook_id` | `DevId` | 必填 | 长度 1 到 256 |
| `secret` | `string` | 可选 | 新的密钥，立即生效，无重叠期。使用 `Idempotency-Key` 重放时不包含。 |

## DevRoutedMemory

一段原文所支持的已确认提炼记忆。原文是证据，这是从中提炼出的陈述。`id` 和 `text` 与 [`GET /v2/memories/{memory_id}`](https://mirabase.io/zh/developers/api/memories.md#memories-read) 一致，调用方也能直接读取这条记忆。候选、被拒和被取代的记忆永远不会附上。某个属性后来有了新值（用户搬家、换工作），旧记忆仍是已确认的，照样附上：它是历史，不是错误。这时它带 `valid_to` 和 `replaced_by`，在上下文包中对应条目标记为 `stale`。两者只在调用方能读取更新的那条记忆时才给出。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 含有 `:`。放进路径时要做百分号编码。 |
| `kind` | `string` | 必填 | 记忆的种类，比如 `preference`、`event`。 |
| `text` | `string` | 必填 | 这条记忆的陈述。 |
| `valid_from` | `string (date-time)` | 可选 | 该值开始生效的时间，已知时返回。 |
| `valid_to` | `string (date-time)` | 可选 | 这个值不再是当前值的时刻：下一个值生效的时间。仍是当前值时不返回。 |
| `replaced_by` | `DevReplacingMemory` | 可选 | 同一属性的当前值。恰好在有更新的值结束这一条时出现。 |

## DevSearchHit

搜索找到的一个段落，带它读自的 Entry 和版本、它的分数，以及来源所在的位置：文件是 `path`，导入的网页是 `url`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 这段内容所在的 Entry。 |
| `version_id` | `DevId` | 必填 | 读取这段内容时所用的版本。 |
| `space_id` | `DevId` | 可选 | 账户记忆没有这个字段：它不属于任何你能访问的 Space。 |
| `title` | `string` | 必填 | Entry 的标题；文件的标题就是文件名。 |
| `text` | `string` | 必填 | 匹配到的内容片段。 |
| `score` | `number` | 必填 | 只在同一个响应内可比较。 |
| `citation_id` | `string` | 必填 | `c1`、`c2`……按这次响应里的次序编号。 |
| `source_type` | `string` | 必填 | 来源的类型：`file`、`note`、`web`、`agent-conversation`，或某种记忆类型。 |
| `path` | `DevPath` | 可选 | 文件的路径。没有路径的 Entry 不带这个字段。 |
| `url` | `string` | 可选 | 从网址导入的 Entry：该网址，用于链接回原网页。文件则带 `path`。 |
| `occurred_at` | `string (date-time)` | 可选 | 这段内容所说的事发生的时间：Entry 的 `occurred_at`，对话则是其中消息的时间。来源没有时间时不带这个字段。 |
| `modified_at` | `string (date-time)` | 可选 | 读取这段内容时所用的版本写入的时间。和 `occurred_at` 一起用来分辨新旧。 |
| `stated_date` | `string (date)` | 可选 | 段落内容截至哪天，格式 `YYYY-MM-DD`。只认年月日写全的日期，句子中间提到的日期一律不算：“自 2026-03-01 起，API 运行在集群 B 上”说的是现在的情况，不是 2026-03-01 那天的情况。按以下顺序取第一个有日期的来源：段落标明为自己日期的日期（前面有“as of”“updated”“last modified”“截至”“更新于”，或后面有“updated”“更新”）；所在小节标题里的日期；段落里一行、一个列表项或一个分句开头的日期；文档 front matter（`modified`、`updated`、`date`、`created`）或顶部标题里的日期。同一来源有几个日期时，取不晚于该版本写入时间的最晚一个。都没有时不返回：宁可不给日期，也不给错的日期。多个文件同时写入时，用它区分较早和较新的记录；有 `occurred_at` 时优先用 `occurred_at`。 |
| `stated_date_from` | `text \| heading \| document` | 可选 | `stated_date` 取自哪里：段落正文（`text`）、段落上方的小节标题（`heading`）或文档开头（`document`）。`search` 中只会出现 `text` 和 `document`。 |
| `freshness` | `pending_index` | 可选 | `pending_index` 表示命中来自新鲜缓冲，只是词法匹配。 |
| `memory` | `DevRoutedMemory` | 可选 | 仅在开启证据化记忆的部署上提供：从这段原文提炼出的已确认记忆。一次响应里每个文件最多一条。`pending_index` 命中上永远没有。 |
| `explain` | `DevHitExplain` | 可选 | 仅当请求设置了 `explain` 时返回。 |

## DevSearchHitField

搜索命中结果中可通过 `fields` 保留的可选字段。

取值: `space_id | path | url | occurred_at | modified_at | stated_date | stated_date_from | freshness | memory`

## DevSearchRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 必填 | 要检索的内容，可使用自然语言或关键词。 长度 1 到 1000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则搜索调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `path` | `DevPath` | 可选 | 把结果限定在这棵子树或这一个文件。在每个被搜索的 Space 里分别解析，都不存在时结果为空。 |
| `include` | `memory[]` | 可选 | `["memory"]` 在结果中加入记忆分面，并把排序切换到记忆档：没有相关性下限，每个 Entry 最多一段。只接受这一个值，且只能指定一次。 1 项 |
| `limit` | `integer` | 可选 | 最多返回多少条命中。这是总数，和列表的每页条数不同。 1 到 50，默认 20 |
| `filter` | `DevRetrievalFilter` | 可选 | 在排序之前缩小搜索范围。与 `path`、`space_ids` 同时生效：必须全部满足。 |
| `tier` | `DevContextTier` | 可选 | 与 `context` 相同：`fast` 不调用模型，只按词面匹配（分数不代表相关性，有命中时 `partial` 为 true）；`standard` 加上语义检索和重排；`deep` 查看两倍的候选，并重排两倍的候选。 默认 "standard" |
| `fields` | `DevSearchHitField[]` | 可选 | 每个命中只保留这些可选字段。`entry_id`、`version_id`、`title`、`text`、`score`、`citation_id` 和 `source_type` 始终返回。每个字段只能指定一次。不传时返回全部字段。 最多 9 项 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

## DevSearchResponse

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevSearchHit[]` | 必填 | 命中，最相关的在前。 |
| `trace_id` | `DevId` | 必填 | 长度 1 到 256 |
| `partial` | `boolean` | 必填 | 某个检索分支降级，或分数不是校准过的相关度时为 true。 |
| `explain` | `DevExplainSummary` | 可选 | 仅当请求设置了 `explain` 时返回。 |
| `pending_processing` | `DevPendingProcessing` | 可选 | 仅当所检索的 Space 中仍有 Entry 在处理时返回：这些 Entry 的文本可能不在本次结果中。[`GET /v2/spaces/{space_id}/processing`](https://mirabase.io/zh/developers/api/spaces.md#spaces-processing) 会报告它们何时可检索。 |

## DevSetSpaceMemberRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `role` | `editor \| viewer` | 必填 | `editor` 可以写，`viewer` 只能读。所有者身份不在这里授予。 |
| `write_mode` | `DevWriteMode` | 可选 | 新成员默认 `proposal`；已有成员不传时保留现值。 |
| `write_root` | `string \| null` | 可选 | 将该成员的写入范围限制在某个已有目录及其子树下。权限只会收窄：角色、能力和 Key 的限制照常生效，读取不受影响，且成员不能重命名、移动或删除该目录本身。不传时保持现值；传入 `null` 或 `/` 取消限制。目录不存在时返回 404 `not_found`，路径指向文件时返回 409 `not_a_directory`，两者均带 `field: write_root`。范围外的写入返回 403 `outside_write_root`，写入没有路径的 Entry 同样返回该错误（成员自己的 Agent 记忆除外）。 长度 1 到 8192 |
| `read_root` | `string \| null` | 可选 | 把这个成员能读取的内容限制在一个已有目录及其下的所有内容。范围只会收窄：角色、能力和 Key 的限制照常生效。不传时保持现值；`null` 或 `/` 取消限制。目录不存在时，接口返回 404 `not_found`；路径指向文件时，接口返回 409 `not_a_directory`，两者都带 `field: read_root`。访问范围外的内容时，这个成员收到 404，如同内容不存在；没有路径的 Entry 也在范围外，成员自己的 Agent 记忆除外；访问这个 Space 的分支时，接口返回 403 `outside_read_root`。没有 `write_root` 时，成员在 `read_root` 下写入；`write_root` 必须是 `read_root` 或它下面的目录，否则接口返回 422 `write_root_outside_read_root`（`field: write_root`），新的 `read_root` 让现有的 `write_root` 落到范围外时也一样。 长度 1 到 8192 |

## DevSnapshot

整个 Space 在某一时刻的只读视图：每个文件的路径及其当时的版本。版本不可变，因此快照不复制字节。在 `tree`、`files` 和 `files/content-url` 上传入 `snapshot` 读取。之后删除的文件仍可通过快照读取；被彻底删除的文件在发起彻底删除时即从快照移除。目录由文件路径推导，因此空目录不在快照中，无路径的内容（记忆、导入的网址和文本）也不在其中。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `name` | `string` | 必填 | 快照的名字。`snapshot=` 里可以用它代替 id。 |
| `file_count` | `integer` | 必填 | 创建快照时的文件数。彻底删除文件不会减少该数值。对设有 `read_root` 的成员，仅统计当时在该范围内的文件。 |
| `changes_cursor` | `DevCursor` | 必填 | 同一时刻的变更流位置。传给 `changes` 即可继续读取快照之后的全部写入，无遗漏也无重复。 |
| `created_by_principal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 快照建立的时间。 |

## DevSnapshotRef

快照 id，或这个 Space 里快照的名字。id 以 `snp_` 开头，名字不能。

取值: `string`

## DevSourceType

取值: `string`

## DevSpace

Space 把一个最终用户或一个项目的文件、Entry 和记忆与账户里的其他内容隔开。这个视图还会返回调用方自己在其中的角色，以及调用方的读取根路径和写入根路径。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 以 `col_` 开头。路径和查询参数里凡是填 Space id 的地方都可以写 `default`，注明可以这样写的 `space_id` 和 `space_ids` 请求字段里也可以。 |
| `name` | `string` | 必填 | Space 的名字。 |
| `description` | `string` | 可选 | 说明这个 Space 用来做什么的备注。 |
| `external_id` | `string` | 可选 | 你自己给这个 Space 的 id（例如你的用户 id），设置过才有。在账户的 Space 之间唯一；用 [`GET /v2/spaces?external_id=`](https://mirabase.io/zh/developers/api/spaces.md#spaces-list) 可以按它找到这个 Space。 |
| `is_default` | `boolean` | 必填 | 对你来说 `default` 指向的那个 Space 上为 true。 |
| `access_role` | `DevSpaceRole` | 必填 | 你在这个 Space 里的角色：`owner`、`editor` 或 `viewer`。 |
| `read_root` | `DevPath` | 可选 | 你在此 Space 中的读取根路径，返回读取时该目录的路径。可读取整个 Space 时不返回。请从该路径开始读取 `tree`：范围外的内容均视为不存在。 |
| `write_root` | `DevPath` | 可选 | 你在此 Space 中的写入根路径，返回读取时该目录的路径。写入不受限时，不返回该字段。 |
| `created_at` | `string (date-time)` | 必填 | Space 创建的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 名称、描述或 `external_id` 最后一次修改的时间。 |

## DevSpaceActivity

Space 最近的变更，按操作主体分组。最近活跃的主体排在前面。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `since` | `string (date-time)` | 必填 | 这段时间从哪一刻算起。 |
| `truncated` | `boolean` | 必填 | 该时间段内的变更超过 1000 条回看上限时为 true，更早的变更未计入。 |
| `data` | `DevActivityActor[]` | 必填 | 每个做过改动的主体一项。 |

## DevSpaceDeletion

删除 Space 的回执。内容在后台彻底删除。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `DevId` | 必填 | 被删除的 Space。 |
| `deleted` | `true` | 必填 | 恒为 true：所有读取都已看不到这个 Space。 |
| `entries` | `integer` | 必填 | 这个 Space 里原有的 Entry 数，包括废纸篓里的。它们正在被彻底删除。 |

## DevSpaceMember

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `principal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `role` | `DevSpaceRole` | 必填 | `owner`、`editor` 或 `viewer`。 |
| `write_mode` | `DevWriteMode` | 必填 |  |
| `write_root` | `DevPath` | 可选 | 该成员可在其下写入的目录，返回读取时该目录的路径。成员可在角色允许的任意位置写入时不返回。目录重命名或移动时，该范围随之更新。 |
| `read_root` | `DevPath` | 可选 | 该成员可在其下读取的目录，返回读取时该目录的路径。成员可读取整个 Space 时不返回。调用方自身设有 `read_root` 时，仅显示位于调用方 `read_root` 以内的其他成员范围。 |

## DevSpaceMemoryProgress

Space 的记忆提炼：一条独立的处理通道，在 Entry 可检索后开始。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pending` | `integer` | 必填 | 记忆提炼正在排队或运行的 Entry。它们已计入可检索或处理中的数量。 |
| `eta_seconds` | `integer` | 可选 | 待完成的提炼预计所需秒数的上限，根据账户每小时的记忆提炼速率计算。没有待完成的提炼时不返回。 |
| `files` | `index_only \| distill` | 必填 | 当前部署是否将按路径写入的文件提炼为记忆。`index_only`：文件会被索引且可检索，记忆来自对话和导入的文本。`distill`：文件也会被提炼。 |

## DevSpaceProcessing

Space 的处理进度。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `counts` | `DevSpaceProcessingCounts` | 必填 |  |
| `stages` | `DevSpaceProcessingStages` | 必填 |  |
| `searchable_per_minute` | `number` | 可选 | 过去五分钟内平均每分钟变为可检索的 Entry 数。没有时不返回。 |
| `eta_seconds` | `integer` | 可选 | 按该速率估算的、所有排队和处理中的 Entry 全部变为可检索所需的秒数。没有速率或没有待处理的 Entry 时不返回。 |
| `oldest_queued_seconds` | `integer` | 可选 | 本 Space 中等待最久的就绪步骤已排队的秒数。无等待步骤时不返回。 |
| `waiting_for_capacity` | `boolean` | 必填 | 本 Space 有就绪步骤正在等待空闲工作进程时为 true。不同 Space 和账户的工作轮流执行。 |
| `queue_position` | `integer` | 可选 | 本账户其他 Space 中、排在本 Space 下一个步骤之前开始的就绪步骤数。没有等待的步骤时不返回；对限定了部分 Space 的 Key 也不返回。 |
| `memory` | `DevSpaceMemoryProgress` | 必填 | 记忆提炼单独报告：只在等待提炼的 Entry 算作可检索，不算作处理中。 |
| `as_of` | `string (date-time)` | 必填 | 读取这些数字的时间。 |

## DevSpaceProcessingCounts

按最新版本所处阶段统计的 Space 中的 Entry。每个 Entry 只计一次。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `queued` | `integer` | 必填 | 已存储，尚未开始任何步骤。 |
| `processing` | `integer` | 必填 | 已开始提取文本或建立索引。 |
| `searchable` | `integer` | 必填 | 搜索已能找到它们；补充处理（关联、分类、摘要、记忆）仍在运行。 |
| `ready` | `integer` | 必填 | 全部步骤已完成。 |
| `failed` | `integer` | 必填 | 已放弃处理。原因见 [`GET /v2/entries/{id}/processing`](https://mirabase.io/zh/developers/api/entries.md#entries-processing)。 |

## DevSpaceProcessingStages

尚未就绪的 Entry，按步骤统计。`enriching` 等于 `counts.searchable`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `queued` | `integer` | 必填 |  |
| `extracting` | `integer` | 必填 |  |
| `indexing` | `integer` | 必填 |  |
| `enriching` | `integer` | 必填 |  |

## DevSpaceRef

Space id；`default` 表示你的默认 Space（你自己的默认 Space，否则为唯一可见的 Space）；或 `ext:<external_id>`，表示带有你为它设定的 id 的 Space，例如 `ext:user-42`。三种写法均可用于路径、`?space_id=` 和 `space_ids`。没有可见的 Space 带有该 `external_id` 时返回 404。

取值: `string`

## DevSpaceRole

主体在一个 Space 中的角色。一次操作既需要能力，也需要最低角色。`viewer`：读取文件、Entry、目录树和记忆；检索、构建上下文、回答和导出。`editor`：在 `viewer` 的基础上，还可以写入、编辑、移动、移入废纸篓、恢复、回滚、导入、导入归档、创建快照、使用分支和审核文件提案（Agent 还需要 `write_mode: direct`）。`owner`：在 `editor` 的基础上，还可以管理成员和 Webhook、修改版本说明、彻底删除 Entry 和删除 Space。有更严格的规则时，操作的说明会写明。

取值: `owner | editor | viewer`

## DevSpaceUsageFigure

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `metric` | `writes \| storage_bytes \| model_tokens \| model_spend_micro_usd` | 必填 | `writes`（按自然月，UTC）、`storage_bytes`（累计）、`model_tokens`（按自然月，UTC：服务的语言模型为本账户生成的 token，包括回答、提炼、摘要、分类和记忆整理）或 `model_spend_micro_usd`（按自然月，UTC：本账户所有计费的模型调用，包括语音识别、OCR、重排、向量生成和网页搜索，按服务的标价计算，单位为百万分之一美元）。两项模型指标只出现在 `tenant_totals` 中，且只在限制它们的套餐上出现；`used` 包含仍在进行中的调用。 |
| `window_start` | `string (date-time)` | 必填 | `used` 开始计数的窗口起点。累计型指标是 Unix 纪元。 |
| `used` | `integer` | 必填 | 这个窗口内该指标已用的量。 |
| `limit` | `integer` | 可选 | 配额。该指标不限量时不带这个字段。 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevStartDreamRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | `DevDreamScope` | 可选 | 默认值：Agent Key 为 `agent`（它自己的私有记忆），其他情况为 `project`。只有 Agent Key 有 `agent` 范围；其他调用方指定该值时，接口返回 422。 |

## DevTableContent

第一张表的前 200 行以内；`row_count` 是整张表的行数。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `columns` | `string[]` | 必填 | 列标题，按顺序。 |
| `rows` | `string[][]` | 必填 | 最多前 200 行，每行是按列顺序排的单元格文字。 |
| `row_count` | `integer` | 必填 | 整张表的总行数，可能多于 `rows` 返回的行数。 |

## DevTraceCandidates

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lexical` | `integer` | 可选 |  |
| `dense` | `integer` | 可选 |  |
| `dense_document` | `integer` | 可选 |  |
| `memory` | `integer` | 可选 |  |
| `relation` | `integer` | 可选 |  |

## DevTraceCitation

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `citation_id` | `string` | 可选 |  |
| `source` | `string` | 可选 |  |

## DevTraceSource

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source` | `string` | 必填 |  |
| `budget` | `integer` | 可选 |  |
| `used` | `integer` | 可选 |  |
| `picked` | `integer` | 可选 |  |
| `omitted` | `integer` | 可选 |  |
| `why` | `string` | 可选 |  |

## DevTraceStage

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `stage` | `string` | 必填 | 阶段，例如 `embed`、`lexical`、`dense`、`rerank` 或 `authorize`。 |
| `status` | `succeeded \| failed \| cancelled \| skipped` | 必填 |  |
| `duration_ms` | `integer` | 可选 | 仅对持有 `knowledge:manage` 的 `tenant_admin` 返回。 |

## DevTraceSummary

为该次检索记录的计数和决策。出现哪些字段取决于 `kind`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `candidates` | `DevTraceCandidates` | 可选 | 搜索：每一路检索的候选数，只统计调用方能读取的候选。`fused_count` 的统计方式相同。在采用该统计方式之前记录的轨迹中，两者均不返回。 |
| `fused_count` | `integer` | 可选 |  |
| `ranked_count` | `integer` | 可选 |  |
| `final_count` | `integer` | 可选 |  |
| `rerank_applied` | `boolean` | 可选 |  |
| `partial` | `boolean` | 可选 |  |
| `duration_ms` | `integer` | 可选 |  |
| `stages` | `DevTraceStage[]` | 可选 | 搜索：每个阶段的耗时。 |
| `purpose` | `string` | 可选 | 上下文和回答：路由决策，与响应中的 `route` 相同。 |
| `tier` | `string` | 可选 |  |
| `rules_fired` | `string[]` | 可选 |  |
| `sources` | `DevTraceSource[]` | 可选 |  |
| `tokens_used` | `integer` | 可选 |  |
| `budget_tokens` | `integer` | 可选 |  |

## DevTreeChmod

只在带 `branch` 时有效，不带时返回 422。合并时 `755` 变为元数据键 `mirabase.mode`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `chmod` | 必填 | 恒为 `chmod`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `mode` | `644 \| 755` | 必填 | `644`；可执行文件用 `755`。 |

## DevTreeCopied

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 副本的位置。 |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `source_entry_id` | `DevId` | 必填 | 长度 1 到 256 |

## DevTreeCopy

在此 Space 内复制单个文件或整个目录。`to` 为完整的新路径，缺失的上级目录会自动创建。`to` 已被占用时返回 409 `path_conflict`，将目录复制到其自身下返回 409 `copy_into_descendant`。每个复制出的文件都是新的 Entry，其第一个版本与源文件的最新字节共享存储；历史记录不复制。副本按新文件处理，计一次 `writes`，并按完整大小计入 `storage_bytes`。`proposal` 模式的 Agent 可以复制不属于自己的文件。计入单次请求 200 个节点的上限。携带 `branch` 时返回 422。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `copy` | 必填 | 恒为 `copy`。 |
| `from` | `DevPath` | 必填 | 长度 1 到 4096 |
| `to` | `DevPath` | 必填 | 长度 1 到 4096 |

## DevTreeDelete

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `delete` | 必填 | 恒为 `delete`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `recursive` | `boolean` | 可选 | 目录非空时必填，否则返回 409 `directory_not_empty`。 默认 false |

## DevTreeJobResult

树任务做了什么。只有计数和 id，失败的合并另外给出前 100 个 `conflicts`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | 可选 | 递归删除：传给 `restore` 的 id，可恢复任务删除的全部内容，包括失败前已删除的部分。 |
| `copies` | `integer` | 可选 | 到目前为止复制的文件数。 |
| `restored` | `integer` | 可选 | 恢复的节点数。 |
| `merged` | `integer` | 可选 | 合并：写入主线的路径数。 |
| `proposed` | `integer` | 可选 | 合并：改成提案而没有直接写入的文件数。 |
| `skipped` | `integer` | 可选 | 合并、导出或导入：略过的项数。 |
| `conflicts` | `DevMergeConflict[]` | 可选 | 以 `merge_conflict` 失败的合并：前 100 个冲突路径。 最多 100 项 |
| `files` | `integer` | 可选 | 导出：归档中的文件数。`skipped` 为无字节可导出的文件数。 |
| `bytes` | `integer` | 可选 | 导出：归档里文件的总字节数。 |
| `archive` | `DevArchive` | 可选 | 成功的导出：归档。用 [`GET /v2/jobs/{job_id}/content-url`](https://mirabase.io/zh/developers/api/transfers.md#transfers-archiveurl) 下载。 |
| `created` | `integer` | 可选 | 导入：新建的文件数。`skipped` 为未改动的成员数（`on_conflict: "skip"`、字节相同，或导出归档中 `files/` 以外的成员）。 |
| `updated` | `integer` | 可选 | 导入：原来就有、这次写了新版本的文件数。 |
| `failed` | `integer` | 可选 | 导入：没能写入的成员数。 |
| `failures` | `DevImportFailure[]` | 可选 | 导入：前 100 个无法写入的成员，按归档内的序号标识。不包含路径。 最多 100 项 |

## DevTreeMkdir

同时创建缺失的上级目录。目录已存在也算成功。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `mkdir` | 必填 | 恒为 `mkdir`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |

## DevTreeMove

移动或重命名文件、目录。`to` 是完整的新路径，缺失的上级目录会自动创建。`to` 被占用时返回 409 `path_conflict`，不覆盖也不合并。重命名和移动一样，整棵子树都计入请求的节点上限。把目录移到它自己里面时返回 409 `move_into_descendant`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `move` | 必填 | 恒为 `move`。 |
| `from` | `DevPath` | 必填 | 长度 1 到 4096 |
| `to` | `DevPath` | 必填 | 长度 1 到 4096 |

## DevTreeNode

Space 目录树的一个节点：目录、文件，或者在分支的列表里出现的符号链接。文件带有客户端读取它或做条件写入所需的内容：它的 Entry、版本、大小、媒体类型和 `etag`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `name` | `string` | 必填 | `path` 的最后一段，保持写入时的写法。 |
| `kind` | `DevTreeNodeKind` | 必填 | `dir` 或 `file`；分支上的列表还会有 `symlink`。 |
| `entry_id` | `DevId` | 可选 | 长度 1 到 256 |
| `version_id` | `DevId` | 可选 | 文件上：最新的版本。通过 `snapshot` 列出时，是快照钉住的版本。分支列表里没有。 |
| `size_bytes` | `integer` | 可选 | 文件上。分支列表里只在分支改过的路径上出现。 |
| `etag` | `string` | 可选 | 文件上（通过 `snapshot` 列出时没有）。可在 `If-Match` 中传回，或与本地持有的值比较以判断内容是否已变更。分支列表里只在分支改过的文件上出现。 |
| `sha256` | `string` | 可选 | 在分支改过的文件上，以及通过 `snapshot` 列出且已知哈希的文件上出现。 |
| `media_type` | `string` | 可选 | 文件上。分支列表里只在分支改过的文件上出现。 |
| `modified_at` | `string (date-time)` | 可选 | 主线列表的文件上：内容最后一次变动的时间，也就是最新版本写入的时间。`updated_at` 在改名、移动时也会变。 |
| `mode` | `644 \| 755` | 可选 | `644` 或 `755`。在分支改过的路径上出现。 |
| `link_target` | `string` | 可选 | 在符号链接上出现。 |
| `updated_at` | `string (date-time)` | 必填 | 节点最近一次变动的时间（包括重命名和移动）。 |

## DevTreeNodeKind

取值: `dir | file | symlink`

## DevTreeOperation

取值: `DevTreeMkdir | DevTreeMove | DevTreeCopy | DevTreeDelete | DevTreeRestore | DevTreeSymlink | DevTreeChmod`

## DevTreeOperationsRequest

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

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

## DevTreeOperationsResponse

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `delete_batch_id` | `DevId` | 可选 | 请求删除了内容时出现，用来整批恢复。 |
| `copies` | `DevTreeCopied[]` | 可选 | 请求复制了内容时出现：每个复制出的文件一条。 |

## DevTreePage

目录的一页。带 `recursive` 时返回全部后代，顺序稳定但不是字母序；不带时返回直接子节点，按名字排序。路径指向文件时返回该文件。`/` 或不传 `path` 表示根目录。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevTreeNode[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |
| `changes_cursor` | `DevCursor` | 必填 | 传给 `changes`，不要传回这个列表，翻页游标是 `next_cursor`。它在读取本页之前获取，因此变更流从此处继续读取不会有遗漏。请保留第一页的值：事件可能重复列表已展示的内容，但不会遗漏。 |

## DevTreeRestore

用 `path` 恢复单个文件，或用 `delete_batch_id` 恢复一次请求删除的全部内容，二者只传一个。缺失的上级目录会重建。重名时返回 409 `path_conflict`，不会自动重命名。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `restore` | 必填 | 恒为 `restore`。 |
| `path` | `DevPath` | 可选 | 长度 1 到 4096 |
| `delete_batch_id` | `DevId` | 可选 | 长度 1 到 256 |

## DevTreeSymlink

只在带 `branch` 时有效，不带时返回 422：主线没有符号链接。合并时跳过它们。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `op` | `symlink` | 必填 | 恒为 `symlink`。 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `target` | `string` | 必填 | 链接指向的目标，1 到 4096 个字符。 长度 1 到 4096 |

## DevUpdateBranchRequest

设置 `ttl_days` 同时续期：`expires_at` 更新为当前时间加上该天数。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 可选 | 新名字，1 到 255 个字符。 长度 1 到 255 |
| `ttl_days` | `integer` | 可选 | 1 到 365。设置后同时为分支续期：`expires_at` 更新为当前时间加上该天数。 1 到 365 |

## DevUpdateEntryRequest

修改标题会产生新版本：标题会纳入索引，而版本不可变。标题相同时不执行任何操作。文件的标题即文件名，因此对文件传 `title` 返回 422，请用 `tree/operations` 重命名。至少传一个字段。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | 可选 | 新标题，1 到 512 个字符。不适用于文件：文件请用 `tree/operations` 改名。 长度 1 到 512 |
| `metadata` | `DevMetadata` | 可选 | 整体替换 Entry 的元数据：需传入所有要保留的键，传 `{}` 清空。不会产生新版本。对任何 Entry 都有效，文件也包括在内。Entry 重新索引后过滤即可看到变化，通常在几秒内。 |
| `metadata_patch` | `object` | 可选 | 按键修改元数据，而不是整体替换：带值的键被设置，值为 `null` 的键被删除，没提到的键保持不变。两个调用方各改不同的键不会互相覆盖。不能与 `metadata` 同时传入。合并后的结果仍然最多 32 个值。 |
| `memory_exclude` | `boolean` | 可选 | 设为 `true` 时停用从该 Entry 提炼的事实，并停止提炼；搜索和读取不受影响。设为 `false` 时重新提炼，已遗忘或更正的事实不会恢复。 |
| `occurred_at` | `string (date-time) \| null` | 可选 | 来源本身发生的时间。传入 `null` 将其清空，检索的时间过滤改回按 Entry 的写入时间计算。不会产生新版本；Entry 重新索引后过滤条件即可反映该变更，通常在几秒内完成。已提炼出的记忆保留其原有的时间。 |

## DevUpdateMemoryRequest

至少传一个。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pinned` | `boolean` | 可选 | 只对以 Entry 写入的记忆有效。固定记忆会改变 Space 的起始内容，所以 Space 所有者必须是人。 |
| `valid_to` | `string (date-time)` | 可选 | 关闭提炼事实或账户记忆。以 Entry 写入的记忆没有有效期，请遗忘或更正它。 |

## DevUpdateMemorySettingsRequest

至少传一个字段；未传的字段保持原值。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_dreaming` | `DevMemoryDreamingMode` | 可选 | `auto` 在上线前返回 422。 |
| `dormancy` | `DevMemoryDormancyMode` | 可选 | 离线整理如何处理闲置的记忆：`report`（默认）或 `apply`。 |
| `d4` | `DevMemoryD4Mode` | 可选 | 离线整理是否请模型比较记忆：`off`（默认）、`shadow` 或 `propose`。 |

## DevUpdatePrincipalRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `grant_capabilities` | `DevCapability[]` | 必填 | 替换该主体的能力。你必须持有此列表中的全部能力，以及该主体现有的全部能力。 |

## DevUpdateSpaceRequest

至少传一个字段。`null` 清空描述或 `external_id`。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 可选 | 新名字，1 到 512 个字符。 长度 1 到 512 |
| `description` | `string \| null` | 可选 | 新的描述；传 `null` 清空。 长度 1 到 4096 |
| `external_id` | `string \| null` | 可选 | 新的 `external_id`，1 到 256 个字符；传入 `null` 清空。已被占用时返回 409 `space_external_id_taken`。 长度 1 到 256 |

## DevUpdateVersionMessageRequest

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

## DevUpdateWebhookRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 可选 | 新的接收地址，规则与创建时相同。 最长 2048 |
| `ops` | `DevChangeOp[]` | 可选 | 此后要推送的事件类型，不可重复。 1 到 5 项 |
| `description` | `string \| null` | 可选 | `null` 清空。 最长 256 |
| `status` | `DevWebhookStatus` | 可选 | `disabled` 停止推送（原因为 `manual`）。`active` 重新启用已停用的 Webhook，清零 `consecutive_failures` 并立即尝试；正在推送的一批按原样重发。 |
| `reset_cursor` | `true` | 可选 | 跳过所有尚未推送的内容，从当前时刻继续。重新启用因 `cursor_expired` 停用的 Webhook 时必填。 |

## DevUpload

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `path` | `DevPath` | 必填 | 长度 1 到 4096 |
| `part_size` | `integer` | 必填 | 除最后一片外，每片都是这个长度。 |
| `expires_at` | `string (date-time)` | 必填 | 上传会话结束时间，不会延长。 |

## DevUploadPartHeaders

每个分片都要带上这些请求头。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content-type` | `string` | 必填 | 每个分片的 `PUT` 都必须带的 `Content-Type`。 |

## DevUploadPartTarget

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `part_number` | `integer` | 必填 | 这个地址对应第几个分片，从 1 数起。 |
| `url` | `string (uri)` | 必填 | 把分片 `PUT` 到这里。 |

## DevUploadParts

已接收的分片不会出现在 `data` 中，因此再次请求即可续传。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevUploadPartTarget[]` | 必填 | 还没上传的每个分片一个上传地址。 |
| `received` | `DevCompletedPart[]` | 必填 | 所请求的分片中已上传的部分，各自带有 `complete` 所需的 `etag`。丢失本地记录的客户端（如崩溃或更换机器）可凭此继续上传，无需重新上传整个文件。 |
| `expires_at` | `string (date-time)` | 必填 | 最多五分钟后到期。 |
| `required_headers` | `DevUploadPartHeaders` | 必填 |  |

## DevUploadPartsRequest

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `part_numbers` | `integer[]` | 必填 | 从 1 开始编号。 1 到 128 项 |

## DevUsageFigure

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `metric` | `writes \| storage_bytes \| model_tokens \| model_spend_micro_usd` | 必填 | `writes`（按自然月，UTC）、`storage_bytes`（累计）、`model_tokens`（按自然月，UTC：服务的语言模型为本账户生成的 token，包括回答、提炼、摘要、分类和记忆整理）或 `model_spend_micro_usd`（按自然月，UTC：本账户所有计费的模型调用，包括语音识别、OCR、重排、向量生成和网页搜索，按服务的标价计算，单位为百万分之一美元）。两项模型指标只出现在 `tenant_totals` 中，且只在限制它们的套餐上出现；`used` 包含仍在进行中的调用。 |
| `window_start` | `string (date-time)` | 必填 | `used` 开始计数的窗口起点。累计型指标是 Unix 纪元。 |
| `used` | `integer` | 必填 | 这个窗口内该指标已用的量。 |
| `limit` | `integer` | 可选 | 配额。该指标不限量时不带这个字段。 |

## DevUsagePage

与其他列表一样分页，租户总量放在页旁边，不放在页内。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevSpaceUsageFigure[]` | 必填 | 每个 Space 的每个指标一条，按 Space id、再按指标排序。 |
| `next_cursor` | `DevCursor` | 可选 | 长度 1 到 1024 |
| `tenant_totals` | `DevUsageFigure[]` | 可选 | 仅在第一页返回，且仅针对未限定 Space 范围的 `tenant_admin` Key。 |
| `plan` | `DevPlan` | 可选 | 账户的套餐。每项数值的 `limit` 取自套餐。 |

## DevVersion

Entry 的一个不可变版本。内容永不改变；处理过程中只有 `status` 会变。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 以 `ver_` 开头。 |
| `entry_id` | `DevId` | 必填 | 这个版本所属的 Entry。 |
| `status` | `DevVersionStatus` | 必填 | 处理进行到哪一步。 |
| `updated_from` | `DevId` | 可选 | 这个版本替换的那个版本。第一个版本没有。 |
| `message` | `string` | 可选 | 作者附的说明，类似提交信息。 |
| `author_principal_id` | `DevId` | 可选 | 写入者。 |
| `created_at` | `string (date-time)` | 必填 | 写入时间。对文件来说即这份内容的修改时间。 |

## DevVersionDiff

同一个 Entry 的两个版本。`identical` 只比较字节的 SHA-256，不读内容，相同的两版 `unified_diff` 为空。1 MiB 以内的文本文件比较原始字节；其他文件在两版都处理完之后比较提取出的文本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `DevId` | 必填 | 长度 1 到 256 |
| `from_version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `to_version_id` | `DevId` | 必填 | 长度 1 到 256 |
| `identical` | `boolean` | 必填 | 两个版本的字节相同时是 true。 |
| `basis` | `DevDiffBasis` | 必填 |  |
| `unified_diff` | `string` | 可选 | 统一 diff 格式的差异。`identical` 时为空；有 `diff_omitted` 时没有这个字段。 |
| `diff_omitted` | `DevDiffOmitted` | 可选 |  |

## DevVersionKind

版本的产生方式。在记录分支合并之前合并的版本显示为 `edit`。`title` 表示字节不变、仅更新标题。

取值: `create | edit | revert | title | proposal_accept | branch_merge | copy`

## DevVersionStatus

一个版本的处理进度。`accepted`：已保存，尚未开始处理。`processing`：正在解析和索引。`published`：处理完成，可供搜索。`no_recallable_content`：处理完成，但没有可索引的内容（空文件、没有文字的图片），不算错误。`failed`：处理已放弃，可用 `POST .../reprocess` 重试。`discarded`：一次编辑处理失败后被搁置，上一个版本继续提供搜索。在 Entry 上它们对应 `knowledge.state`：`published` 和 `no_recallable_content` 是 `indexed`，`failed` 是 `failed`，其余是 `readable`；新鲜缓冲已经能检索到文本时是 `searchable`。

取值: `accepted | processing | published | no_recallable_content | failed | discarded`

## DevWebhook

对一个 Space 变更流的订阅（只有主线，没有分支）。Mirabase 按顺序 POST 最多 100 条事件一批，至少一次，同一时间只有一批在途。每个请求带 `Mirabase-Signature: t=<unix 秒>,v1=<以密钥对 "t.body" 做 HMAC-SHA256 的十六进制>`、`Mirabase-Webhook-Id` 和 `Mirabase-Delivery-Id`；重试时用同一个推送 id 重发同一批。请求体是 `DevWebhookPayload`。10 秒内返回任意 2xx 即为成功。返回其他状态码、重定向（不会跟随重定向）或 10 秒内无响应均视为失败，同一批次在 30 秒后重试，此后每次间隔翻倍，最长 1 小时。请按恒定时间比较签名，`t` 与本机时钟相差超过 5 分钟时拒绝。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `url` | `string (uri)` | 必填 | 端口 443 上的 `https`。 |
| `ops` | `DevChangeOp[]` | 必填 | 要推送的事件类型。其他类型的事件直接跳过，不排队。 |
| `description` | `string` | 可选 | 给人看的备注。 |
| `status` | `DevWebhookStatus` | 必填 | `active`；停止投递时为 `disabled`，原因见 `disabled_reason`。 |
| `disabled_reason` | `DevWebhookDisabledReason` | 可选 | `status` 是 `disabled` 时出现。 |
| `cursor` | `DevCursor` | 必填 | 最后一批推送或跳过之后的变更流位置。 |
| `consecutive_failures` | `integer` | 必填 | 上次成功以来失败的尝试次数。 |
| `last_success_at` | `string (date-time)` | 可选 | 最近一次投递成功的时间。 |
| `last_failure_at` | `string (date-time)` | 可选 | 最近一次投递失败的时间。 |
| `next_attempt_at` | `string (date-time)` | 可选 | 下一次尝试最早的开始时间。停用时没有。 |
| `created_by_principal_id` | `DevId` | 必填 | 长度 1 到 256 |
| `created_at` | `string (date-time)` | 必填 | 这个 Webhook 创建的时间。 |
| `updated_at` | `string (date-time)` | 必填 | 这个 Webhook 的设置或状态最近一次变动的时间。 |

## DevWebhookDelivery

一次推送尝试。不保存请求体、地址和响应体。保留 30 天。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `delivery_id` | `DevId` | 必填 | 这一批，与 `Mirabase-Delivery-Id` 相同。同一批的多次尝试共用它。 |
| `first_seq` | `integer` | 必填 | 过滤前这一批的第一个变更序号。 |
| `last_seq` | `integer` | 必填 | 过滤前这一批的最后一个变更序号。 |
| `event_count` | `integer` | 必填 | 过滤后发出的事件数。 |
| `attempt` | `integer` | 必填 | 这一批的第一次尝试是 1。 |
| `outcome` | `DevWebhookOutcome` | 必填 | 收到任何 2xx 就是 `delivered`，否则是 `failed`。 |
| `http_status` | `integer` | 可选 | 接收方返回的 HTTP 状态码，收到响应时提供。 |
| `error_code` | `DevWebhookErrorCode` | 可选 |  |
| `duration_ms` | `integer` | 必填 | 本次尝试耗时，单位为毫秒。 |
| `created_at` | `string (date-time)` | 必填 | 这次尝试发生的时间。 |

## DevWebhookDisabledReason

Webhook 停用的原因。`failing`：连续 20 次尝试失败。`receiver_gone`：接收方返回 410。`cursor_expired`：游标位置已超出 90 天的变更流。`credential_revoked`：创建它的 API Key 被吊销或过期，或开发者账户被停用。`access_lost`：创建者不再拥有这个 Space，或失去了 `knowledge:read` 或 `knowledge:manage`。`manual`：有人把 `status` 设为 `disabled`。

取值: `failing | receiver_gone | cursor_expired | credential_revoked | access_lost | manual`

## DevWebhookErrorCode

`http_status` 表示收到了非 2xx 响应；其他都是在收到响应之前失败。

取值: `timeout | network | blocked_address | http_status | tls`

## DevWebhookOutcome

取值: `delivered | failed`

## DevWebhookPayload

Webhook 请求的 JSON 请求体。`events` 按 Webhook 的 `ops` 过滤，内容与创建者当前在 `changes` 上看到的一致。`cursor` 是这一批之后的变更流位置：传给 `changes` 即可从同一位置继续读取。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | `space.changes` | 必填 | 恒为 `space.changes`。 |
| `webhook_id` | `DevId` | 必填 | 长度 1 到 256 |
| `delivery_id` | `DevId` | 必填 | 长度 1 到 256 |
| `space_id` | `DevId` | 必填 | 长度 1 到 256 |
| `events` | `DevChange[]` | 必填 |  |
| `cursor` | `DevCursor` | 必填 | 长度 1 到 1024 |

## DevWebhookStatus

取值: `active | disabled`

## DevWhoami

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tenant_id` | `DevId` | 必填 | 该 Key 所属的账户。 |
| `principal` | `DevPrincipal` | 必填 | 这次请求代表的身份。 |
| `key` | `DevWhoamiKey` | 可选 | 请求不是用 API Key 认证时不存在。 |
| `effective_capabilities` | `DevCapability[]` | 必填 | 主体能力与 Key 能力的交集。 |

## DevWhoamiKey

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `DevId` | 必填 | 长度 1 到 256 |
| `prefix` | `string` | 必填 | Key 的开头几个字符：可以展示，足够区分各个 Key。 |
| `capabilities` | `DevCapability[]` | 必填 | 该 Key 本身允许的能力。请求实际生效的是 `effective_capabilities`，即主体同时具备的那部分能力。 |
| `allowed_space_ids` | `DevId[]` | 可选 | 这个 Key 被收窄到的 Space。不存在表示没有收窄到特定 Space。 |
| `metadata_scope` | `DevMetadataScope` | 可选 | Key 受限的元数据范围。没有这个字段表示不按元数据限制。 |
| `expires_at` | `string (date-time)` | 可选 | Key 失效的时间。不会过期时没有这个字段。 |

## DevWriteMode

只对 Agent 生效，且只针对不属于它的文件。Space 所有者始终是 `direct`。

取值: `proposal | direct`

## OperatorUsageTotals

一组调用的用量和运营方成本。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `calls` | `integer` | 必填 |  |
| `errors` | `integer` | 必填 |  |
| `input_tokens` | `integer` | 必填 |  |
| `output_tokens` | `integer` | 必填 |  |
| `total_tokens` | `integer` | 必填 |  |
| `audio_seconds` | `number` | 必填 |  |
| `images` | `integer` | 必填 |  |
| `model_usd` | `number` | 必填 |  |
| `unpriced_calls` | `integer` | 必填 | 模型未定价的调用；其费用不计入 `model_usd`。 |
