数据结构
Markdown 版请求和响应用到的数据结构,从 OpenAPI 规格生成。
DevAccountQueue
账户的处理队列:把写入的内容变为可检索内容的任务(解析、索引、发布和索引投影),以及之后的模型处理(摘要、分类、记忆)。计数单位是任务而不是文件,一个文件对应多个任务。查看单个文件请用 GET /v2/entries/{entry_id}/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 报告你用到了什么。 |
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
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
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。只有文本文件有:分支里的内容不解析。
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
存储在分支中的对象。
DevBranchRef
分支 id,或活跃分支的名字。id 以 brn_ 开头。会重试的调用里请用 id:第一个分支关闭后,名字可能指向另一个分支。
取值: string
DevBranchState
分支的状态。active:可写入。merged:已合并到主线,只读。abandoned:未合并即关闭。已合并或已放弃的分支在结束 branch_reclaim_days 天后被回收。
取值: active | merged | abandoned
DevCapability
一个 Key 可以做什么。请求按 Key 和它的主体共同持有的能力行事(即 GET /v2/whoami 里的 effective_capabilities)。每个已上线的操作在 x-mirabase-capability 里写明它需要哪一项。 - knowledge:read:读取 Space、文件、Entry、记忆和变更流,调用搜索和上下文。 - knowledge:answer:调用 POST /v2/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。
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} 上的 metadata 相同。检索的 filter.metadata 按它匹配。 |
memory_exclude | boolean | 为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 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
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
DevContextPurpose
取值: task | coding | research | audit
DevContextRendered
上下文包的文本形式,仅在请求设置了 render 时返回。
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 回报你用了哪些。 |
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 会报告它们何时可检索。 |
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
DevContextScopeUsed
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 关闭这个来源。
DevConversationContentPart
content 为列表时的一段。保留文本分段,跳过图片等其他分段。
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、读取 Entry 内容与处理状态、GET /v2/jobs/{id}、读取记忆、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。
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= 或路径 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。超过部署的大小上限返回 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)。 |
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 和 GET /v2/entries/{entry_id} 会返回这个字段;在此之前、解析失败时以及写入回执中不返回。 |
error | DevProcessingFailure | 处理失败的原因,与 GET /v2/entries/{entry_id}/processing 返回的 error 相同。state 为 failed 时,GET /v2/entries 和 GET /v2/entries/{entry_id} 返回这个字段;其他情况以及写入回执中不返回。 |
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 会把它放回这里。没有路径的 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。 |
queue | DevBacklog | 429 ingest_backlog 时返回:账户的队列。也可随时用 GET /v2/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 见 错误码。
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
DevExplainRerank
DevExplainRerankSummary
| 字段 | 类型 | 说明 |
|---|---|---|
applied必填 | boolean | 跳过重排、重排失败或未给出分数时为 false;此时 score 不是经过校准的相关性。 |
pool必填 | integer | 送去重排的候选数。 |
below_floor必填 | integer | 重排后低于相关性下限的候选数。 |
DevExplainSummary
请求设置了 explain 时,说明检索的执行过程。
| 字段 | 类型 | 说明 |
|---|---|---|
terms必填 | string[] | 词法检索所用的词。 |
candidates必填 | DevExplainCandidateCount[] | 每一路检索中你能读取的候选数。没有返回任何你能读取的结果的那一路检索不列出。 |
fused_count必填 | integer | 各路检索合并后你能读取的候选数。 |
rerank必填 | DevExplainRerankSummary | |
clauses | string[] | 任务陈述了多件事时:分别检索的各个子句。 |
DevFieldError
请求体中的一个问题。
DevFileAttributes
写文件时可以随字节一起记到文件的 Entry 上的内容。每个字段都可选,只有传了的才会改:替换文件时保留它已有的元数据、时间和开关。字节没变、不产生版本时它们也生效。只对主线:在分支上或在变成提案的写入上设置其中任何字段都返回 422,因为 Entry 属于文件的所有者。
| 字段 | 类型 | 说明 |
|---|---|---|
occurred_at | string (date-time) | 文件内容发生的时间,例如录音或录像的录制时间。检索的 occurred_from / occurred_to 以此为准,段落中也会返回该时间;未提供时以文件写入时间为准。 |
metadata | DevMetadata | 整体替换 Entry 的元数据,与 PATCH /v2/entries/{id} 上的 metadata 相同。检索的 filter.metadata 按它匹配。 |
memory_exclude | boolean | 为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关。 |
DevFileBatchDelete
DevFileBatchItem
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} 上的 metadata 相同。检索的 filter.metadata 按它匹配。 |
memory_exclude | boolean | 为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 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
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
导入时无法写入的一个归档成员。
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":"…"} 一起列出,用 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} 的 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} 才是 succeeded;同样的进度也在 GET /v2/entries/{entry_id}/processing。对话在这之后才提炼:两处都用 memory.state 报告提炼进度。 |
knowledge必填 | DevEntryKnowledge | 64 KiB 以内的文本通常是 searchable,其他内容在处理完成前是 readable。 |
memory_status | candidate | confirmed | 只在对话上出现:提炼出的内容是直接生效还是等待审核。 |
memory | DevMemoryProcessing | 仅对话包含此字段:索引完成后将进行提炼时为 pending;不进行提炼时为 skipped,并在 reason 中说明原因。后续进展请轮询 GET /v2/entries/{entry_id}/processing。 |
secrets_redacted | integer | 只有请求带了 redact_secrets 才有:替换了几处。0 表示没有发现像凭据的内容。 |
DevIngestRequest
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} 的 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} 的 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 上的相同。
DevJobKind
任务做什么。processing:解析并索引一个版本,由 ingest、reprocess 或彻底删除产生。tree:以任务方式运行的目录操作、合并、导出或导入,id 以 tjb_ 开头。dream:一次离线整理,id 以 drm_ 开头。
取值: processing | tree | dream
DevJobProgress
树任务的进度。done 是已经处理的节点、合并路径、导出文件或归档成员的数量。
DevJobReceipt
| 字段 | 类型 | 说明 |
|---|---|---|
job_id必填 | DevId | 轮询 GET /v2/jobs/{job_id},直到 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
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。
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":"…"} 查询该对话。写入时未指定则不返回;回滚和复制不继承该字段。 |
DevMcpHandshake
tools 列出这个 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 是完整的受治理列表,含候选和历史。上下文包里的 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= 按它筛选。 |
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 和 GET /v2/memories/{memory_id} 返回的提炼记忆上,且只在开启了证据化记忆的部署上提供:同一属性的当前值。同一 Space、同一范围里后来的对话改了这个属性时出现(先是“住在上海”,后来“搬到杭州”)。这条记忆仍是 status: "confirmed":它曾经成立,只是不再是当前值,MEMORY.md 也不再列出它。只有你能读取的更新值才算。 |
dormant | DevMemoryDormancy | 只在开启了离线整理的部署上,且只出现在 GET /v2/memories 和 GET /v2/memories/{memory_id}:被整理标为休眠的提炼记忆。它照常列出、照常可搜索。MEMORY.md 只收录人写入或确认过的记忆,这类记忆不会休眠;撤销那次整理即可清除。 |
group_id | DevId | 只在开启了离线整理的部署上,且只出现在 GET /v2/memories 和 GET /v2/memories/{memory_id} 的提炼记忆上:这条记忆所在的组。同一 Space、同一范围、同一状态、说同一句话(经 Unicode 规范化、忽略大小写和空白后比较)的提炼记忆是一组,以你看得见的最小 id 列一次。只计来源你看得见的成员。 |
sources | DevMemorySource[] | 有 group_id 时:你看得见的组员,最小 id 在前,包括这一条。 |
pending_proposals | DevId[] | 只在开启了离线整理的部署上,出现在 GET /v2/memories 和 GET /v2/memories/{memory_id}:关于这条记忆(或它所在组的成员)的打开状态的整理提案,最早的在前,只含你看得见的提案。没有时不返回。 |
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},或由搜索、上下文包、回答返回)即恢复生效。规则和偏好不会被标为 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},或由搜索、上下文包、回答返回)即恢复生效。来源之后再提炼一次(包括改写这条记忆的提炼)会清除这两种原因。两种同时存在时报告 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 获取。提炼放弃时为 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} 将 memory_exclude 设为 false。write_memories_directly:当前部署不执行提炼,请用 POST /v2/memories 自行写入记忆。review_usage:查看 GET /v2/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
支撑提案的一段逐字引文,取自读到它的那个来源版本。
DevMemoryProposalKind
整理提案建议的改动。merge:两条记忆表达同一内容,一条并入另一条。supersede:较新的记忆取代较旧的。conflict:两条记忆互相矛盾,仅供人工查看,不能批准。promote:把 Agent 的私有记忆提升到项目,不能批准。
取值: merge | supersede | conflict | promote
DevMemoryProposalPlan
批准会做什么:留下的那条记忆,以及被它取代或并入它的记忆。
DevMemoryProposalStatus
整理提案的状态。open:等待人工处理。approved:已执行。rejected:已关闭且未做改动,同样的成员不会再被提出同样的改动。stale:批准前有成员发生了变化。withdrawn:提案未处理时,它所属的整理被撤销。
取值: open | approved | rejected | stale | withdrawn
DevMemoryProposalTime
支持提案的一个日期:来源里的原话,或来源本身的日期。
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
一组提炼记忆中的一个成员。
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 撤销了什么,以及随之恢复了什么。
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
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)。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 在已存储对象的媒体类型与上传时声明的不一致时返回。
DevProcessingProgress
主要步骤(提取文本、建立索引、发布到搜索)中已完成的步数。
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} 获取结果。
| 字段 | 类型 | 说明 |
|---|---|---|
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,以及完成此次删除的任务。
DevQueueEstimate
批量写入放入处理队列的条目数,以及队列大约需要的时间。
| 字段 | 类型 | 说明 |
|---|---|---|
queued_items必填 | integer | 写入了新版本、因而进入处理队列的条目数。 |
eta_seconds | integer | 完成账户全部就绪任务预计所需的秒数(见 GET /v2/queue)。无法估计时不返回;对限定了部分 Space 或元数据范围的 Key 也不返回。 |
paused | boolean | 服务运营方暂停了本账户的处理时返回,值为 true。对限定了部分 Space 或元数据范围的 Key 从不返回。 |
DevRemediation
错误的处理方式。请按 action 分支处理,错误对象上的 message 可能变更。
DevReplacingMemory
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} 读取。 |
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} 一致,调用方也能直接读取这条记忆。候选、被拒和被取代的记忆永远不会附上。某个属性后来有了新值(用户搬家、换工作),旧记忆仍是已确认的,照样附上:它是历史,不是错误。这时它带 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 会报告它们何时可检索。 |
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= 可以按它找到这个 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 的回执。内容在后台彻底删除。
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。 |
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 是整张表的行数。
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
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。
DevTreeCopied
DevTreeCopy
在此 Space 内复制单个文件或整个目录。to 为完整的新路径,缺失的上级目录会自动创建。to 已被占用时返回 409 path_conflict,将目录复制到其自身下返回 409 copy_into_descendant。每个复制出的文件都是新的 Entry,其第一个版本与源文件的最新字节共享存储;历史记录不复制。副本按新文件处理,计一次 writes,并按完整大小计入 storage_bytes。proposal 模式的 Agent 可以复制不属于自己的文件。计入单次请求 200 个节点的上限。携带 branch 时返回 422。
DevTreeDelete
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 下载。 |
created | integer | 导入:新建的文件数。skipped 为未改动的成员数(on_conflict: "skip"、字节相同,或导出归档中 files/ 以外的成员)。 |
updated | integer | 导入:原来就有、这次写了新版本的文件数。 |
failed | integer | 导入:没能写入的成员数。 |
failures | DevImportFailure[] | 导入:前 100 个无法写入的成员,按归档内的序号标识。不包含路径。最多 100 项 |
DevTreeMkdir
同时创建缺失的上级目录。目录已存在也算成功。
DevTreeMove
移动或重命名文件、目录。to 是完整的新路径,缺失的上级目录会自动创建。to 被占用时返回 409 path_conflict,不覆盖也不合并。重命名和移动一样,整棵子树都计入请求的节点上限。把目录移到它自己里面时返回 409 move_into_descendant。
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:主线没有符号链接。合并时跳过它们。
DevUpdateBranchRequest
设置 ttl_days 同时续期:expires_at 更新为当前时间加上该天数。
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
至少传一个。
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
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 即可从同一位置继续读取。
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。 |
