跳到主要内容
开发者文档
文档目录

数据结构

Markdown 版

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

DevAccountQueue

账户的处理队列:把写入的内容变为可检索内容的任务(解析、索引、发布和索引投影),以及之后的模型处理(摘要、分类、记忆)。计数单位是任务而不是文件,一个文件对应多个任务。查看单个文件请用 GET /v2/entries/{entry_id}/processing。

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

DevActivityActor

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

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

DevActivityFile

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

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

DevAnswer

字段类型说明
status必填DevAnswerStatusanswered;证据不足以回答时是 abstained。
answer必填string放弃回答时为空。用 [cN] 引用证据。
reasonDevAnswerAbstainReason放弃回答时出现。
citations必填DevAnswerCitation[]只列 answer 引用了的证据,按首次引用的顺序。
evidenceDevAnswerEvidence[]仅在请求带 include: ["evidence"] 时返回:模型读过的每一条证据,按读取顺序排列。
evidence_count必填integer交给模型的条目数。
pack_id必填DevId用 POST /v2/retrieval/context/{pack_id}/feedback 报告你用到了什么。
partial必填boolean检索的某一路降级时为 true,这时证据可能不全。
pending_processingDevPendingProcessing仅当所检索的 Space 中仍有 Entry 在处理时返回:回答可能缺少这些 Entry 的内容。
route必填DevContextRoute证据是怎么选出来的,和上下文包里的含义相同。
explainDevAnswerExplain仅当请求设置了 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_idDevId该 Entry 所在的 Space。账户记忆没有这个字段。
pathDevPath文件的路径。没有路径的 Entry 不带这个字段。
urlstring从网址导入的 Entry:该网址,用于链接回原网页。文件则带 path。
occurred_atstring (date-time)这段内容所说的事发生的时间:Entry 的 occurred_at,对话则是其中消息的时间。来源没有时间时不带这个字段。
modified_atstring (date-time)读取这段内容时所用的版本写入的时间。和 occurred_at 一起用来分辨新旧。
stated_datestring (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_fromtext | heading | documentstated_date 取自哪里:段落正文(text)、段落上方的小节标题(heading)或文档开头(document)。
title必填stringEntry 的标题;文件的标题就是文件名。
source必填DevContextSource这段内容来自哪个上下文来源。
text必填string模型读到的段落。
explainDevHitExplain仅当请求设置了 explain 时返回。

DevAnswerEvidence

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

字段类型说明
citation_id必填string模型引用它时可用的 id。
entry_id必填DevId这段内容所在的 Entry。
version_id必填DevId读取这段内容时所用的版本。
space_idDevId该 Entry 所在的 Space。账户记忆没有这个字段。
pathDevPath文件的路径。没有路径的 Entry 不带这个字段。
urlstring从网址写入的 Entry 上:那个网址。
occurred_atstring (date-time)与引用上的同名字段相同。
modified_atstring (date-time)与引用上的同名字段相同。
stated_datestring (date)与引用上的同名字段相同。
stated_date_fromtext | heading | document与引用上的同名字段相同。
title必填stringEntry 的标题;文件的标题就是文件名。
source必填DevContextSource这段内容来自哪个上下文来源。
explainDevHitExplain仅当请求设置了 explain 时返回。

DevAnswerExplain

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

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

DevAnswerRequest

字段类型说明
question必填string要回答的问题,1 到 4000 个字符。长度 1 到 4000
space_idsDevSpaceRef[]Space 的 id;default 指你的默认 Space,和路径里的含义相同。不传则使用调用方可读的全部 Space;可读 Space 超过 200 个的 Key 必须显式指定(否则返回 422)。1 到 64 项
purposeDevContextPurpose回答用来做什么,与 context 的同一个参数:task、coding、research 或 audit。
weightsDevContextWeights与 context 相同。不传时,回答不使用 changes 和 skills 两个来源:无论问题是什么,它们列出的都是最近的文件和技能。这时 route.rules_fired 会列出 source:off:changes:answer_default 和 source:off:skills:answer_default。要包含它们,请传 weights。
tierDevContextTier检索证据时投入的工作量,与 context 上的含义相同:fast、standard 或 deep。默认 "standard"
budget_tokensinteger模型读取的证据的预算。500 到 16000,默认 4000
historyDevAnswerTurn[]之前的对话轮次,最早的在前。追问会和它所追问的问题一起搜索。各轮合计超过 12,000 个字符时,最早的几轮会被略去。最多 10 项
output_languagestringBCP 47 语言标签,如 en 或 zh-CN。只影响 answer 的语言。最长 35
filterDevRetrievalFilter缩小答案可引用的证据范围,和 context 相同。
includeevidence[]["evidence"] 在响应里增加 evidence:模型读过的每一条证据,不带正文。用它查看回答除了引用的段落之外还依据了什么。1 项
streamboolean为 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 响应。
profilestring当前部署上声明的检索配置:上述设置(以及候选数和重排数)的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时,使用部署为所检索的 Space 或本账户设定的默认配置。
rerankbooleanfalse 跳过重排:结果保持融合后候选的顺序,分数不代表相关性,有结果时 partial 为 true。不能与 min_score 同时使用;true 不能与 fast 档同时使用。
min_scorenumber保留的最低重排分数,取值 0 到 1。它替代服务默认的相关性下限,同时移除低于该值的词法匹配。来自新鲜缓冲的命中(freshness: pending_index)没有重排分数,会被保留。重排失败时不生效(partial 会注明)。需要启用重排。0 到 1
max_per_entryinteger每个 Entry 最多返回的片段数。这是硬上限:腾出的名额分给其他 Entry,而不是同一 Entry 的更多片段。在 context 和 answer 中,它只作用于搜索结果,不作用于任务指定的文件或最近的变更。1 到 50
reference_timestring (date-time)查询中的相对时间(“昨天”“上周”)从哪一刻算起。默认为当前时刻。替一条较早的消息检索时,传该消息的时间。在 answer 上,它同时是告诉模型的“今天”。
timezonestring提问者所在的 IANA 时区,例如 Asia/Shanghai:它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。
explainboolean为 true 时,每个命中、条目或引用以及响应本身都带上 explain:由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据,以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选:读范围、元数据范围或权限之外的内容一律不计入。

DevAnswerSentence

字段类型说明
text必填stringanswer 中的一个句子,带有其中的 [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,这时证据可能不全。
evidenceDevAnswerEvidence[]只在请求带 include: ["evidence"] 时出现:模型读取的每一条证据,与 final 中的列表相同。

DevAnswerTurn

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

DevApiKey

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

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

DevApproveProposalRequest

字段类型说明
messagestring成为新版本的 message,最多 120 个字符。最长 120

DevArchive

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

字段类型说明
size_bytes必填integer归档的字节数。
sha256必填string归档的十六进制 SHA-256。
media_type必填stringapplication/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必填stringapplication/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_idDevId请求不是用 API Key 认证时不存在。
space_idDevId动作不属于单一 Space 时不存在。
resource_kind必填string动作对象:entry、version、recall、tenant、tool、api_key、memory、principal、space、branch、proposal、snapshot、webhook、job、dream 或 developer_account。以后可能增加新的类型。
resource_idDevId为 entry 和 version 时,该字段是 Entry id,版本由 version_id 指定。
version_idDevId长度 1 到 256
request_idstring引起这条事件的请求,与错误体里 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_secondsinteger完成账户全部就绪任务预计所需的秒数。无法估计时不返回;对限定了部分 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_idDevId从主线创建的分支没有这个字段。节点是复制过来的,没有父分支链。
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 | mainbranch:在这个分支上做的改动。main:该分支穿透读到的主线改动。
seq必填integer在它的 source 之内的序号。
op必填DevChangeOp改动的种类:create、update、move、delete 或 restore。
pathDevPath长度 1 到 4096
kindDevBranchNodeKindbranch 的改动才有:这个路径是目录、文件还是符号链接。
entry_idDevId长度 1 到 256
version_idDevId长度 1 到 256
actor_principal_idDevId长度 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这个路径在分支上是目录、文件还是符号链接。
sizeinteger文件才有:分支上内容的字节数。
mode644 | 755文件才有:644 或 755。
sha256string文件才有:分支上内容的十六进制 SHA-256。
base_version_idDevId长度 1 到 256
unified_diffstring只有文本文件有。字节的差异无法按行看出时为空。
diff_omittedtoo_large文本文件的 diff 太大无法计算时出现。

DevBranchDiffOp

取值: added | modified | deleted

DevBranchFileDeletion

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

DevBranchFileMeta

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

字段类型说明
branch_id必填DevId长度 1 到 256
path必填DevPath长度 1 到 4096
kind必填file | symlink这个路径在分支上是文件还是符号链接。
sizeinteger只有文件有:字节数。
media_typestring只有文件有:写入时带的媒体类型。
mode644 | 755只有文件有:644 或 755。
sha256string只有文件有:内容的十六进制 SHA-256。
etagstring仅限文件:下次写入时在 If-Match 中传回。它是内容哈希,不是版本。
updated_at必填string (date-time)分支最近一次改这个路径的时间。

DevBranchFileText

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

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

DevBranchFileWrite

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

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

DevBranchNodeKind

取值: dir | file | symlink

DevBranchObject

存储在分支中的对象。

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

DevBranchRef

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

取值: string

DevBranchState

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

取值: active | merged | abandoned

DevCapability

一个 Key 可以做什么。请求按 Key 和它的主体共同持有的能力行事(即 GET /v2/whoami 里的 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
pathDevPath长度 1 到 4096
version_idDevId长度 1 到 256
actor_principal_idDevId长度 1 到 256
created_at必填string (date-time)改动提交的时间。

DevChangeFeed

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

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

DevChangeOp

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

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

DevCheckpoint

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

字段类型说明
id必填DevId长度 1 到 256
branch_id必填DevId长度 1 到 256
name必填string创建时指定的名称。
gitDevCheckpointGit
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_idstring你为该文件所出自的对话指定的 id,与 PUT files?session_id= 相同:记录在本次完成上传所创建的版本上,可通过 lineage 查看。仅用于主线:分支上传传入该字段返回 422。长度 1 到 256
occurred_atstring (date-time)文件内容发生的时间,例如录音或录像的录制时间。检索的 occurred_from / occurred_to 以此为准,段落中也会返回该时间;未提供时以文件写入时间为准。
metadataDevMetadata整体替换 Entry 的元数据,与 PATCH /v2/entries/{id} 上的 metadata 相同。检索的 filter.metadata 按它匹配。
memory_excludeboolean为 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。
sha256string原始字节的十六进制 SHA-256,已知时提供。

DevContentView

取值: text | table | recognized

DevContextChange

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

DevContextFeedbackRequest

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

DevContextFlag

字段类型说明
type必填stale | superseded | conflict | agent_writtenstale、superseded、conflict 或 agent_written。
citation_idstringconflict 时:与这一条矛盾的条目。
grant_idstringagent_written 时出现。

DevContextItem

字段类型说明
entry_id必填DevId长度 1 到 256
version_id必填DevId长度 1 到 256
space_idDevId长度 1 到 256
title必填string这段内容出自的 Entry 的标题。
text必填string一个段落。skills 条目为一行描述,正文按 path 读取。
citation_id必填string在该上下文包内标识此条目,如 c1。通过 feedback 报告实际使用的条目时传入该值。
source必填DevContextSource
pathDevPath长度 1 到 4096
urlstring从网址导入的 Entry:该网址,用于链接回原网页。文件则带 path。
occurred_atstring (date-time)这段内容所说的事发生的时间:Entry 的 occurred_at,对话则是其中消息的时间。来源没有时间时不带这个字段。
modified_atstring (date-time)读取这段内容时所用的版本写入的时间。和 occurred_at 一起用来分辨新旧。
stated_datestring (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_fromtext | heading | documentstated_date 取自哪里:段落正文(text)、段落上方的小节标题(heading)或文档开头(document)。
is_current_versionfalse有比这个更新的版本生效时出现,值为 false。
flagsDevContextFlag[]没有时不出现。
freshnesspending_indexpending_index 表示条目来自新鲜缓冲,只是词法匹配。
memory_kindstringmemory 条目上出现。
changeDevContextChangechanges 条目上出现。
memoryDevRoutedMemory仅在开启证据化记忆的部署上提供:从这段原文提炼出的已确认记忆。一次响应里每个文件最多一条。计入 tokens_used。
explainDevHitExplain仅当请求设置了 explain 时返回。不计入 tokens_used。

DevContextOmitted

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

DevContextPurpose

取值: task | coding | research | audit

DevContextRendered

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

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

DevContextRequest

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

DevContextResponse

字段类型说明
pack_id必填DevId这个上下文包的标识。用 POST /v2/retrieval/context/{pack_id}/feedback 回报你用了哪些。
memory_view_etagstring下次作为 have_memory_etag 传回。记忆来源关闭或预算不足以容纳视图时不返回。
memory_viewDevMemoryViewhave_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_processingDevPendingProcessing仅当所检索的 Space 中仍有 Entry 在处理时返回:这些 Entry 的文本可能不在本次结果中。GET /v2/spaces/{space_id}/processing 会报告它们何时可检索。
renderedDevContextRendered请求带了 render 才有。
explainDevExplainSummary仅当请求设置了 explain 时返回。

DevContextRoute

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

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

DevContextRouteSource

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

DevContextScopeUsed

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

DevContextSource

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

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

DevContextTier

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

取值: fast | standard | deep

DevContextWeights

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

字段类型说明
memorynumbermemory 的权重:与任务相关的记忆。0 到 1
agent_profilenumberagent_profile 的权重:Agent 自己的档案。0 到 1
skillsnumberskills 的权重:Agent 自己的技能。0 到 1
filesnumberfiles 的权重:任务里点名的文件。0 到 1
changesnumberchanges 的权重:最近写入的内容。0 到 1
knowledgenumberknowledge 的权重:检索找到的其余内容。0 到 1

DevConversationContentPart

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

字段类型说明
typestring这一段的类型,照聊天接口的写法,比如 text、image_url。
textstring这一段的文字。没有文字的段略过。

DevConversationMessage

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

字段类型说明
role必填string自由文本,比如 user 或 assistant,不能有换行。长度 1 到 128
contentstring | DevConversationContentPart[] | null文字,或者一组分段,其中的文字段会拼起来。没有文字的消息可以是 null 或不带这个字段。
nameobject接收但忽略。
tool_callsobject接收但忽略。
tool_call_idobject接收但忽略。
function_callobject接收但忽略。
timestampstring (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必填stringKey 的名称,1 到 256 个字符,用于在列表中区分各个 Key。长度 1 到 256
grant_capabilities必填DevCapability[]不能超过该主体和调用方的能力。至少 1 项
allowed_space_idsDevId[]不传表示不限制 Space;不接受空数组。1 到 100 项
metadata_scopeDevMetadataScope将 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_atstring (date-time)必须是未来时间。调用方的 Key 有到期时间时必填,且不能晚于该到期时间。

DevCreateBranchRequest

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

字段类型说明
name必填string分支的名称,1 到 255 个字符。长度 1 到 255
fromDevId要复制的活跃分支的 id。
checkpoint_idDevId要复制的检查点的 id。
ttl_daysinteger每次写入把 expires_at 推后的天数,1 到 365。不传则使用服务默认值。1 到 365

DevCreateCheckpointRequest

字段类型说明
name必填string检查点的名字,1 到 255 个字符。长度 1 到 255
gitDevCheckpointGit

DevCreateExportRequest

字段类型说明
snapshotDevSnapshotRef快照 id 或名字:导出当时的文件。不带时导出任务开始那一刻的实时目录树。
pathDevPath只导出这个目录(或文件)及其下面的内容。
formattar唯一支持的格式。

DevCreateForkRequest

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

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

DevCreateImportRequest

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

DevCreateMemoryRequest

字段类型说明
scope必填DevMemoryScope记忆的范围:project、agent 或 account。
space_idDevSpaceRefproject 和 agent 必填;default 指你的默认 Space,和路径里一样。账户记忆不属于任何 Space,不带这个字段。
kind必填stringpreference、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
pinnedboolean账户记忆没有这个字段。默认 false

DevCreatePrincipalRequest

字段类型说明
kind必填DevPrincipalKind主体类型:人(human)或 Agent(agent)。
grant_capabilitiesDevCapability[]要授予的能力,不能超过你持有的能力。不传时 Agent 获得 knowledge:read,人没有任何能力。

DevCreateSnapshotRequest

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

DevCreateSpaceRequest

字段类型说明
name必填stringSpace 的名称,1 到 512 个字符。长度 1 到 512
descriptionstringSpace 的用途,1 到 4096 个字符。长度 1 到 4096
external_idstring你为这个 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必填stringhttps,端口 443,不带用户名、密码和片段,主机是完整域名或公网 IP。每次推送都会重新解析主机,只要有一个地址是私有、回环、链路本地、唯一本地、运营商级 NAT、基准测试、文档、组播或保留地址(包括映射和 NAT64 形式)就拒绝连接。最长 2048
opsDevChangeOp[]要推送的事件类型;默认包含全部五种。不可重复。1 到 5 项
descriptionstring供人阅读的备注,最多 256 个字符。最长 256
cursorDevCursor从这个 changes 游标之后开始。默认从当前时刻开始。游标过期时,接口返回 410 cursor_expired。

DevCreatedWebhook

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

字段类型说明
id必填DevId长度 1 到 256
space_id必填DevId长度 1 到 256
url必填string (uri)端口 443 上的 https。
ops必填DevChangeOp[]要推送的事件类型。其他类型的事件直接跳过,不排队。
descriptionstring给人看的备注。
status必填DevWebhookStatusactive;停止投递时为 disabled,原因见 disabled_reason。
disabled_reasonDevWebhookDisabledReasonstatus 是 disabled 时出现。
cursor必填DevCursor最后一批推送或跳过之后的变更流位置。
consecutive_failures必填integer上次成功以来失败的尝试次数。
last_success_atstring (date-time)最近一次投递成功的时间。
last_failure_atstring (date-time)最近一次投递失败的时间。
next_attempt_atstring (date-time)下一次尝试最早的开始时间。停用时没有。
created_by_principal_id必填DevId长度 1 到 256
created_at必填string (date-time)这个 Webhook 创建的时间。
updated_at必填string (date-time)这个 Webhook 的设置或状态最近一次变动的时间。
secretstringwhsec_ 加 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_idDevIdagent 整理:是谁的私有记忆。
status必填DevDreamStatusqueued、running,然后是 succeeded 或 failed。
trigger必填DevDreamTriggermanual:有人手动发起。schedule:由这个 Space 的定时整理发起。
started_by_principal_idDevId仅限手动(manual)发起的整理。
created_at必填string (date-time)这次整理排队的时间。
started_atstring (date-time)开始运行的时间。还在排队时没有。
finished_atstring (date-time)结束时间,无论成功或失败均会记录。
undone_atstring (date-time)被撤销的时间。未撤销过时不返回。
undone_by_principal_idDevId长度 1 到 256
undo_expires_atstring (date-time)undoable 为真时:可撤销的最晚时间;如果同一范围内有三次后续整理在此之前完成,撤销期限会提前。从本次整理完成时起算;如果本次整理的提案最后一次获批的时间更晚,则从那时起算。
undoable必填boolean当前是否可撤销。
counts必填DevDreamCounts
viewDevDreamView
d4DevDreamD4Report整理进入比较阶段后出现。
model_tokens必填integer这次整理估算消耗的模型 token;在这个 Space 里有 read_root 的成员看到的是 0。
errorDevJobFailure

DevDreamAction

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

字段类型说明
seq必填integer在这次整理里的顺序,动作按它排列。
memory_id必填DevId长度 1 到 256
entry_id必填DevId长度 1 到 256
action必填DevDreamActionKind
reason必填DevDreamActionReason
state必填DevDreamActionState
proposal_idDevIdsupersede 和 merge:被批准的提案。
target_memory_idDevIdsupersede 和 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_candidatesinteger整理走到休眠这一步后才有:它找到的闲置提炼记忆,即 90 天没有被取用、这个范围连续三次整理都没有被取用、不在同类型取用最多的 20 条之内,并且不是规则、偏好或人确认过的记忆。Space 设置为 dormancy: "report" 时,它们只列为 reported 动作。
dormant_unusedinteger和 dormancy_candidates 一起出现:其中被标为 dormant、原因 unused 的记忆(Space 设置为 dormancy: "apply")。
supersededinteger本次整理的 supersede 提案获批后,被较新记忆取代的记忆数。大于 0 时返回。
mergedinteger这次整理的 merge 提案被批准后,并入另一条的记忆。有了才出现。
undoneinteger撤销后:撤销了的动作。
conflict_skippedinteger撤销后:因记忆此后发生变更(被遗忘、确认、重新提炼,或被后续整理接管)而跳过的动作。
checkedinteger核对过的提炼记忆。
skipped_confirmedinteger人确认过的记忆,整理从不改动:审核通过的候选,以及带 memory:confirm 导入的对话里提炼出的记忆。
skipped_not_readyinteger来源有更新的版本还在处理的记忆。
skipped_no_quoteinteger没有引文可核对的记忆。
stale_skippedinteger在核对和写入之间变过、留给下一次整理的记忆。
vetoedinteger之前的撤销指定不要再改动的记忆。
already_dormantinteger之前的整理已经标为休眠的记忆。
groupsinteger说同一件事的记忆组(两条或以上)。
grouped_factsinteger与至少另一条说法相同的提炼记忆的条数。
remaininginteger因单次整理最多核对 10000 条而尚未核对的记忆。该范围的下一次整理(手动或自动)从上次核对的最后一条之后继续;单次整理到达末尾后,下一次从头开始。

DevDreamD4Report

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

字段类型说明
status必填ran | skippedskipped:本次运行未调用模型,由 skipped 字段说明原因。
skippedDevDreamD4SkipReasonD4 被跳过,或没比完所有配对就停下时才有。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
kindDevMemoryProposalKind它的结论。discarded 的判定没有。
member_ids必填DevId[]被比较的记忆。
layer必填DevMemoryLayer这一对所在的记忆层:rule、decision、event 或 knowledge。
signals必填string[]为什么比较这一对:entity、predicate、kind。
discard_reasonDevDreamJudgmentDiscardReasondiscarded 的判定才有:它为什么被丢弃。
planDevMemoryProposalPlan
evidenceDevMemoryProposalEvidence[]判定所依据的逐字引文。discarded 的判定不留引文,所以没有这个字段。
timesDevMemoryProposalTime[]决定哪条记忆较新的日期。
modelstring被询问的模型。
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_afterinteger整理后这个范围里生效的记忆条数。整理完成后返回。
tokens_afterinteger整理后它们的 token 数。整理完成后返回。

DevEmptyRequest

取值: object

DevEnrichment

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

取值: relations | classification | summary | memory

DevEnsureSpaceRequest

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

字段类型说明
namestring新建 Space 的名称,默认为 external_id。长度 1 到 512
descriptionstring新建 Space 的描述。长度 1 到 4096

DevEntry

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

字段类型说明
id必填DevId以 ent_ 开头。新增版本、改名、移动都不会改变它。
space_id必填DevIdEntry 所在的 Space。
title必填string文件的标题是文件名;其他情况是你给的标题,或从内容里取的标题。
latest_version_id必填DevId最新写入的版本。按路径或 id 读取时默认返回它。
current_version_idDevIdsearch 和 context 读取的版本。latest_version_id 指向的版本完成索引后,两者相同;更新的版本还在处理时,它仍是之前的版本。第一版处理完之前不存在。
metadata必填DevMetadata你在导入时、写文件时或用 PATCH 设置的内容,加上服务写入的 mirabase. 开头的键。没有时为空。
occurred_atstring (date-time)来源本身发生的时间:导入或写文件时传的 occurred_at,或对话里消息的时间。未知时不返回;检索的时间过滤此时按写入时间算。
source_typeDevSourceType这是哪种来源:file、note(导入的文本)、web(导入的网址)、agent-conversation(导入的对话)。与搜索命中报告的值相同,filter.source_types 按它匹配。
urlstring从网址写入的 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 的能力。
trashDevEntryTrash只在废纸篓列表里出现(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。
textstring文本形式的内容。table 视图没有。
tableDevTableContent表格形式的内容。仅在 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_atstring (date-time)内容最后一次变更的时间,即最新版本写入的时间。与 tree 列表返回的值相同。

DevEntryKnowledge

字段类型说明
state必填DevKnowledgeState
indexed_version_idDevId长度 1 到 256
parsedDevParsedSummary已索引版本的解析结果。Entry 有了已索引的版本后,GET /v2/entries 和 GET /v2/entries/{entry_id} 会返回这个字段;在此之前、解析失败时以及写入回执中不返回。
errorDevProcessingFailure处理失败的原因,与 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 相同。
errorDevProcessingFailure仅在 status 为 failed 时出现。
stage必填DevProcessingStage最新版本当前所处的阶段。从 enriching 开始,搜索即可找到它。
progress必填DevProcessingProgress已完成的主要步骤。
queueDevProcessingQueue仅在当前步骤等待开始时返回。
enrichmentsDevEnrichment[]仅在 stage 为 enriching 时返回:仍在运行的处理。
memoryDevMemoryProcessing只在对话批次上出现:记忆提炼的进度。等它离开 pending 后再读取记忆。

DevEntryTrash

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

字段类型说明
deleted_at必填string (date-time)进废纸篓的时间。没有路径的 Entry 取清理完成的时间,晚几秒。
pathDevPath文件原来的路径。POST /v2/entries/{id}/restore 会把它放回这里。没有路径的 Entry 没有这个字段。
delete_batch_idDevId把文件放进废纸篓的那次删除。tree/operations 的 restore 接受它,把那次删除去掉的内容全部恢复。
deleted_byDevId将文件移入废纸篓的主体 id。没有路径的 Entry 不返回此字段。
sizeinteger最新版本的大小(字节),与原 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)。
typeDevErrorType错误的大类,由 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必填integerHTTP 状态,在响应体里重复一遍。
message必填string给人看的英文说明,可能会变:分支处理请按 code。
request_id必填string在服务日志里标识这次请求。反馈问题时请带上它。
retryable必填booleanquota_exceeded 时为 false:配额变更之前,重试无效。
fieldstring422 时第一个出错的字段。请求体里有不认识的字段时,这里是那个字段的名称。
errorsDevFieldError[]请求体校验返回 422 时:列出发现的每个问题,最多 20 个,以便一次改完。第一个就是 field 和 message 描述的那个问题。
limitrequest_rate | concurrency429 rate_limited 时返回:触发的是哪一种限制。request_rate 是每分钟的请求额度,即 RateLimit-* 响应头描述的额度。concurrency 是对进行中的操作数量的限制(搜索和上下文请求、回答,或对同一个 Space 的写入);请求已经等待过空闲名额,这时不返回 RateLimit-* 响应头,减少同时发出的调用比延长等待更有效。
quotawrites | storage_bytes | model_tokens | model_spend_micro_usd429 quota_exceeded 时返回:指明哪项配额已用完。writes、model_tokens 和 model_spend_micro_usd 在下个月初(UTC)重置;storage_bytes 在文件被彻底删除后释放。剩余额度见 GET /v2/usage。
queueDevBacklog429 ingest_backlog 时返回:账户的队列。也可随时用 GET /v2/queue 查看。
current_version_idDevId412 precondition_failed 和 409 proposal_conflict 时返回:文件当前的最新版本。
job_idDevId409 job_in_flight 时返回:需要等待的任务。
conflictsDevMergeConflict[]409 merge_conflict 时出现:挡住合并的每个路径。
remediationDevRemediation

每个错误码的状态码、含义、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

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

DevExplainRerank

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

DevExplainRerankSummary

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

DevExplainSummary

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

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

DevFieldError

请求体中的一个问题。

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

DevFileAttributes

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

字段类型说明
occurred_atstring (date-time)文件内容发生的时间,例如录音或录像的录制时间。检索的 occurred_from / occurred_to 以此为准,段落中也会返回该时间;未提供时以文件写入时间为准。
metadataDevMetadata整体替换 Entry 的元数据,与 PATCH /v2/entries/{id} 上的 metadata 相同。检索的 filter.metadata 按它匹配。
memory_excludeboolean为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关。

DevFileBatchDelete

字段类型说明
op必填delete恒为 delete。
path必填DevPath长度 1 到 4096
if_matchstring文件的 etag:仅当其仍为当前值时删除,否则该项返回 412 precondition_failed。

DevFileBatchItem

取值: DevFileBatchPut | DevFileBatchDelete

DevFileBatchPut

字段类型说明
op必填put恒为 put。
path必填DevPath长度 1 到 4096
content必填stringUTF-8 文本,最大 64 KiB。
media_typestring默认 text/plain。
if_matchstring文件的 etag。
if_none_match*只接受 *:仅当路径上尚无文件时写入,与 PUT 的 If-None-Match: * 相同。已有文件时该项返回 412 precondition_failed,批次中其余项照常执行。不能与 if_match 同时指定。
occurred_atstring (date-time)文件内容发生的时间,例如录音或录像的录制时间。检索的 occurred_from / occurred_to 以此为准,段落中也会返回该时间;未提供时以文件写入时间为准。
metadataDevMetadata整体替换 Entry 的元数据,与 PATCH /v2/entries/{id} 上的 metadata 相同。检索的 filter.metadata 按它匹配。
memory_excludeboolean为 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_idstring这些改动出自你的哪段对话,与 PUT files?session_id= 相同:它会记录在每条 put 创建的版本上,可在 lineage 中查看。仅适用于主线:带 branch 时返回 422。长度 1 到 256

DevFileBatchResponse

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

DevFileBatchResult

字段类型说明
path必填DevPath长度 1 到 4096
status必填integer这一项如果单独发请求会得到的 HTTP 状态,比如 200、201、404、412。
writeDevFileWrite
proposalDevProposalReceiptPrefer: handling=proposal 让这一条变成提案时出现,代替 write,状态是 202。
deletionDevFileDeletiondelete 成功时返回。
branch_writeDevBranchFileWrite请求带了 branch 时代替 write 出现。
branch_deletionDevBranchFileDeletion请求带了 branch 时代替 deletion 出现。
errorDevErrorBody仅失败的项返回:单独发送请求时会返回的错误体。

DevFileDeletion

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

DevFileEdit

字段类型说明
old_text必填string必须恰好出现一次,除非设置了 replace_all。最短 1
new_text必填string用来替换 old_text 的内容。为空字符串时删除 old_text。
replace_allboolean替换 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_idDevId这次写入替换掉的版本。新建文件、或没有产生新版本时不带这个字段。
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。

字段类型说明
andDevFilterCondition[]以下条件全部成立。1 到 16 个。1 到 16 项
orDevFilterCondition[]以下条件至少一个成立。1 到 16 个。1 到 16 项
notDevFilterCondition该条件不成立。没有该键的 Entry 满足 {"not": {"key": k, "eq": v}}。
keystring键条件中的元数据键:1 到 64 个字符,可用 a-z、0-9、_、.、-。
eqDevMetadataValueEntry 在该键下存有该值。最短 1
inDevMetadataValue[]Entry 在该键下存有这些值之一,1 到 32 个。1 到 32 项
existsbooleantrue:Entry 有该键;false:Entry 没有该键。
gtDevFilterRangeBound大于。不能与 gte 同时使用。
gteDevFilterRangeBound大于或等于。不能与 gt 同时使用。
ltDevFilterRangeBound小于。不能与 lte 同时使用。
lteDevFilterRangeBound小于或等于。不能与 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[]返回它的各路检索,以及它在每一路中的位置。对于计算得出的表格,此项为空。
fusedDevExplainRank各路检索合并后、重排前的位置和分数,二者都只在你能读取的候选中计算。
rerankDevExplainRerank重排给出的位置和分数。未重排或重排未给出分数时不返回。
matched_termsstring[]其文本匹配到的查询词。中文按两字词匹配。
lexicalstrong | covered | partial其词语对查询的覆盖程度:strong 不受相关性下限限制,covered 和 partial 受限制。
admitted_byDevExplainAdmission使它通过相关性下限的依据。未应用下限时不返回。
boostsDevExplainBoost[]使它排名上升的规则。
reordered_by_datestring设为 newest_first 时:排序所依据的日期(occurred_at,没有时取 stated_date),格式为 YYYY-MM-DD。
computed_tabletrue服务对整张表计算得出的条目为 true(route.rules_fired 中有 table_aggregate:computed)。

DevId

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

取值: string

DevIdempotencyKey

取值: string

DevImportConflict

取值: skip | overwrite

DevImportFailure

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

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

DevIngestConversation

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

字段类型说明
kind必填conversation恒为 conversation。
session_id必填string你给这段对话的 id,1 到 256 个字符。同一段对话分几段写入时都带同一个 session_id:每一批是一个独立的 Entry,这个 id 同时记成元数据键 session_id(除非你的 metadata 里已经有这个键),所以同一段对话的各批可以用 GET /v2/entries?metadata={"session_id":"…"} 一起列出,用 filter.metadata 一起检索。没传 title 时用它给 Entry 起名。长度 1 到 256
messages必填DevConversationMessage[]这一批的消息,按说话的先后顺序排列:1 到 1000 条。1 到 1000 项
titlestring默认为 Conversation <session_id>。长度 1 到 512
metadataDevMetadata和其他来源一样记在 Entry 上。对话的时间取自消息的 timestamp。
memory_excludeboolean为 true 时,这个 Entry 从一开始就不参与记忆提炼:它照常保存、建索引、可检索,但不会从中提炼任何记忆。和 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关,之后可以改回来。
redact_secretsboolean为 true 时,在存任何东西之前先把文本(和 title)里看起来像凭据的内容替换掉:私钥块、JWT、Bearer 令牌、常见的 API Key 格式,以及 password=、api_key: 这类写法后面的值。此后检索、读取和提炼出的记忆看到的都只是替换后的文本,回执里的 secrets_redacted 说明替换了几处。不常见的密钥格式可能无法识别。
memory_instructionsstring你对这段对话该记住什么的说明,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必填DevEntryKnowledge64 KiB 以内的文本通常是 searchable,其他内容在处理完成前是 readable。
memory_statuscandidate | confirmed只在对话上出现:提炼出的内容是直接生效还是等待审核。
memoryDevMemoryProcessing仅对话包含此字段:索引完成后将进行提炼时为 pending;不进行提炼时为 skipped,并在 reason 中说明原因。后续进展请轮询 GET /v2/entries/{entry_id}/processing。
secrets_redactedinteger只有请求带了 redact_secrets 才有:替换了几处。0 表示没有发现像凭据的内容。

DevIngestRequest

取值: DevIngestUrl | DevIngestText | DevIngestConversation

DevIngestText

字段类型说明
kind必填text恒为 text。
text必填string要保存的文本,1 到 2,000,000 个字符。长度 1 到 2000000
titlestring默认取第一行。长度 1 到 512
occurred_atstring (date-time)文本内容发生的时间,比如会议或邮件的日期。默认未知;此时检索的 occurred_from / occurred_to 按写入时间算。
metadataDevMetadata
memory_excludeboolean为 true 时,这个 Entry 从一开始就不参与记忆提炼:它照常保存、建索引、可检索,但不会从中提炼任何记忆。和 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关,之后可以改回来。
redact_secretsboolean为 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
titlestring这个 Entry 的标题,1 到 512 个字符。长度 1 到 512
occurred_atstring (date-time)网页内容发生的时间,如果你知道的话。检索的 occurred_from / occurred_to 按它算。
metadataDevMetadata
memory_excludeboolean为 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_idsDevId[]不存在表示没有收窄到特定 Space。
metadata_scopeDevMetadataScopeKey 受限的元数据范围。没有这个字段表示不按元数据限制。
expires_atstring (date-time)过了这个时间 Key 就失效。不过期的 Key 不带这个字段。
revoked_atstring (date-time)Key 被吊销的时间。仍然有效时不带这个字段。
last_used_atstring (date-time)这个 Key 最近一次调用 API 的时间,精确到分钟。尚未使用时不返回该字段。
created_by必填DevId签发它的主体。
issued_by_key_idDevId签发或轮换出这个 Key 的 Key。未通过 Key 签发时不存在。
created_at必填string (date-time)签发时间。
tokenstring密钥明文,只显示这一次。幂等重放时不存在,因为服务端不保存:原响应丢失时请轮换 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必填DevJobStatusqueued、running,然后是 succeeded、failed 或 cancelled。
stage必填string任务正在做什么,见上面的说明。
entry_idDevId处理任务:正在处理的 Entry。
version_idDevId处理任务:正在处理的版本。
errorDevJobFailure仅在 status 为 failed 时出现。
memoryDevMemoryProcessing对话批次的处理任务:记忆提炼的进度。status 不等它完成。
space_idDevId仅限树任务。
progressDevJobProgress
resultDevTreeJobResult
queueDevQueueEstimate导入:进入处理队列的已导入文件数,以及账户队列大约需要的时间。
created_at必填string (date-time)任务创建的时间。
updated_at必填string (date-time)任务最近一次改变状态或有进展的时间。

DevJobFailure

处理任务的 code 和 message 与 GET /v2/entries/{id}/processing 上的相同。

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

DevJobKind

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

取值: processing | tree | dream

DevJobProgress

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

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

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_read600每个 Key:每分钟的 GET、HEAD、search 和 context 请求数429 rate_limited,带 limit: request_rate
requests_per_minute_write120每个 Key:每分钟的其他请求数429 rate_limited,带 limit: request_rate
retrieval_concurrency2每个主体:同时运行的搜索和上下文调用数等待名额最多 1 秒后,返回 429 rate_limited,带 limit: concurrency
agent_retrieval_concurrency8每个 Agent 主体,代替 retrieval_concurrency等待名额最多 1 秒后,返回 429 rate_limited,带 limit: concurrency
answer_concurrency3每个主体:同时运行的回答数等待名额最多 10 秒后,返回 429 rate_limited,带 limit: concurrency
space_write_concurrency4每个 Space:同时运行的写入数等待名额最多 1 秒后,返回 429 rate_limited,带 limit: concurrency
space_writes_per_month100,000每个 Space:一个 UTC 自然月内的写入数429 quota_exceeded
tenant_writes_per_month1,000,000每个账户:一个 UTC 自然月内的写入数429 quota_exceeded
space_storage_bytes10 GiB每个 Space:存储的字节数429 quota_exceeded
tenant_storage_bytes100 GiB每个账户:存储的字节数429 quota_exceeded
tenant_model_tokens_per_month1,000,000每个账户(仅 free 套餐):一个 UTC 自然月内服务的语言模型为该账户生成的 token(回答、提炼、摘要、分类、记忆整理)。仅在套餐设定此项时列出429 quota_exceeded,带 quota: model_tokens;需要模型的处理步骤以 quota_exceeded 失败
tenant_model_spend_micro_usd_per_month2,000,000每个账户(仅 free 套餐):一个 UTC 自然月内所有计费的模型调用(语言模型、语音识别、OCR、重排、向量生成、网页搜索),按服务的标价计算,单位为百万分之一美元。每次调用前检查;超出剩余额度的长录音在转写前即被拒绝。仅在套餐设定此项时列出429 quota_exceeded,带 quota: model_spend_micro_usd;需要模型的处理步骤以 quota_exceeded 失败
tenant_queued_jobs10,000每个账户:使内容可检索的排队任务(解析、图片、音频和视频识别、建索引、发布)。文件可检索之后的模型处理(摘要、分类、关联、记忆)另有上限,为此数的五倍429 ingest_backlog
space_active_branches100每个 Space:活跃分支数409 branch_limit_reached
branch_paths10,000每个分支:路径数409 branch_too_large
branch_checkpoints100每个分支:检查点数409 checkpoint_limit_reached
branch_ttl_days30每个分支:无写入多少天后过期-
branch_reclaim_days7每个分支:结束后多少天被回收-
space_snapshots100每个 Space:快照数409 too_many_snapshots
snapshot_files10,000每个快照:文件数409 snapshot_too_large
export_max_bytes4 GiB每次导出:原件字节数409 export_too_large
import_max_bytes1 GiB每次导入:归档字节数413 archive_too_large
tenant_api_keys100每个账户:活跃的 Key 数409 tenant_limit_reached
tenant_principals200每个账户:主体数409 tenant_limit_reached
tenant_spaces10,000每个账户:未删除的 Space 数409 tenant_limit_reached
team_members50每个团队:成员数(控制台)-
team_pending_invitations20每个团队:等待接受的邀请数(控制台)-
team_invitations_per_day100每个团队:一天内发出的邀请数(控制台)-
tenant_requests_per_minute_read6,000每个账户:所有 Key 合计的每分钟读取请求数,为 requests_per_minute_read 的 10 倍429 rate_limited,带 limit: request_rate
tenant_requests_per_minute_write1,200每个账户:所有 Key 合计的每分钟其他请求数,为 requests_per_minute_write 的 10 倍429 rate_limited,带 limit: request_rate
tenant_retrieval_concurrency80每个账户:所有主体合计同时运行的搜索和上下文调用数,为 agent_retrieval_concurrency 的 10 倍等待名额最多 1 秒后,返回 429 rate_limited,带 limit: concurrency

DevLimits

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

DevLineage

Entry 的来源,以及一页版本(最新的在前)。不列出复制操作者。

字段类型说明
entry_id必填DevId长度 1 到 256
origin必填DevLineageOrigin这个 Entry 是怎么来的。
data必填DevLineageVersion[]一页版本,最新的在前。
next_cursorDevCursor长度 1 到 1024

DevLineageOrigin

字段类型说明
kind必填DevLineageOriginKindcreated:直接写入的。copy:从另一个 Entry 复制来的。branch_merge:由一次分支合并首次写入。
sourceDevLineageRefcopy 时:复制来源的 Entry 和版本。
branch_idDevIdbranch_merge 时:分支,只给 id。分支关闭后会被回收。
chainDevLineageRef[]copy 且来源本身也是复制来的:再往上的来源,最近的在前,最多 16 个。
chain_truncatedtrue来源链超过 16 步。

DevLineageOriginKind

取值: created | copy | branch_merge

DevLineageRef

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

字段类型说明
visible必填boolean来源对你不可见时为 false:不带 id,链在此处结束。
entry_idDevId长度 1 到 256
version_idDevId长度 1 到 256
purgedtrue来源已被彻底删除时是 true。id 仍然给出。

DevLineageVersion

字段类型说明
version_id必填DevId长度 1 到 256
parent_version_ids必填DevId[]这个版本写入时所基于的版本。Entry 的第一个版本为空。
created_at必填string (date-time)这个版本写入的时间。
author_principal_idDevId长度 1 到 256
kind必填DevVersionKind
restored_fromDevIdrevert 时出现。
proposal_idDevIdproposal_accept 时出现。
branch_idDevIdbranch_merge 时出现。
messagestring该版本的说明;未设置时不返回。
session_idstring该版本出自哪段对话:写文件时传入的 session_id。可通过 GET /v2/entries?metadata={"session_id":"…"} 查询该对话。写入时未指定则不返回;回滚和复制不继承该字段。

DevMcpHandshake

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

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

DevMcpRequest

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

取值: object

DevMcpResponse

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

取值: object

DevMcpTool

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

DevMcpToolName

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

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

DevMemory

三种来源共用一个形状:账户记忆、写成 Entry 的记忆、从 Entry 提炼出的事实。除非记忆是写成 Entry 的,否则 id 不是 Entry id。pinned 只对这一种有效。被遗忘的记忆没有正文留下,所以不会返回。 “记忆”出现在四个地方,各是不同的集合。GET /v2/memories 是完整的受治理列表,含候选和历史。上下文包里的 memory_view(以及 MEMORY.md)是已确认、当前有效内容的索引,不含敏感类别。search 的 include: ["memory"] 把记忆加进命中,并改用记忆的排序方式。检索命中或上下文条目上的 memory 是从那段内容提炼出的一条已确认事实。

字段类型说明
id必填DevId把它传给其他记忆接口。提炼事实的 id 里有冒号,放进路径时要做百分号编码。
entry_idDevId这条记忆本身对应的 Entry,或它从中提炼出来的 Entry。账户记忆没有这个字段。
space_idDevId账户记忆没有这个字段:它不属于任何你能访问的 Space。
scope必填DevMemoryScope这是谁的记忆:account(这个人,跨 Space)、project(这个 Space)或 agent(某个 Agent 自己的)。
kind必填string记忆的类别,例如 preference、decision 或 progress;提炼出的事实还有别的类别,例如 experience。GET /v2/memories?kind= 按它筛选。
status必填DevMemoryStatusconfirmed 的记忆在检索和 MEMORY.md 里生效;candidate 等待审核;rejected 和 superseded 是历史记录。
text必填string记忆的内容,一句陈述。
pinned必填boolean这条记忆是否置顶。只有写成 Entry 的记忆可以置顶。
supersedesDevId更正时出现:被它替换的记忆。
valid_fromstring (date-time)这个事实从什么时候开始成立(来源里说明了的话)。
valid_tostring (date-time)这条记忆不再是当前值的时间。带 replaced_by 时,是更新的值开始生效的时间。
created_at必填string (date-time)这条记忆最初写入或提炼出来的时间。
updated_at必填string (date-time)最后一次变更的时间:审核、更正、置顶或修改有效期。
replaced_byDevReplacingMemory只出现在 GET /v2/memories 和 GET /v2/memories/{memory_id} 返回的提炼记忆上,且只在开启了证据化记忆的部署上提供:同一属性的当前值。同一 Space、同一范围里后来的对话改了这个属性时出现(先是“住在上海”,后来“搬到杭州”)。这条记忆仍是 status: "confirmed":它曾经成立,只是不再是当前值,MEMORY.md 也不再列出它。只有你能读取的更新值才算。
dormantDevMemoryDormancy只在开启了离线整理的部署上,且只出现在 GET /v2/memories 和 GET /v2/memories/{memory_id}:被整理标为休眠的提炼记忆。它照常列出、照常可搜索。MEMORY.md 只收录人写入或确认过的记忆,这类记忆不会休眠;撤销那次整理即可清除。
group_idDevId只在开启了离线整理的部署上,且只出现在 GET /v2/memories 和 GET /v2/memories/{memory_id} 的提炼记忆上:这条记忆所在的组。同一 Space、同一范围、同一状态、说同一句话(经 Unicode 规范化、忽略大小写和空白后比较)的提炼记忆是一组,以你看得见的最小 id 列一次。只计来源你看得见的成员。
sourcesDevMemorySource[]有 group_id 时:你看得见的组员,最小 id 在前,包括这一条。
pending_proposalsDevId[]只在开启了离线整理的部署上,出现在 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_sourcesDevForgottenSource[]只在遗忘提炼事实时出现:它所出自的 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。
countinteger只在 state 为 ready 时出现:这一批写下的记忆数,含候选。0 表示没有值得保留的内容。
reasonDevMemoryProcessingReason状态为 skipped 时,表示不执行提炼的原因。状态为 pending 时,仅可能为 distill_paused,表示等待时间比平时长,且只向能看到账户状态的调用方返回。状态为 skipped 时,仅当服务无法判断原因时才不返回此字段。部署停止提炼之前已提炼完的版本仍为 ready。
remediationDevRemediation仅当 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_idDevIdagent 提案:是谁的私有记忆。
dream_id必填DevId提出它的那次整理。
kind必填DevMemoryProposalKind它建议做什么:merge、supersede、conflict 或 promote。
member_ids必填DevId[]它涉及的记忆,已排序。
proposed_textstring它提出的陈述。目前不返回;conflict 始终不返回。
evidenceDevMemoryProposalEvidence[]支撑这条提案的逐字引文。
planDevMemoryProposalPlanapprove 会做什么。conflict 没有,它没有可执行的内容。
layerDevMemoryLayer成员所在的记忆层:rule、decision、event 或 knowledge。
timesDevMemoryProposalTime[]决定哪条记忆较新的日期。
status必填DevMemoryProposalStatus整理在提案处于打开状态期间被撤销时为 withdrawn;成员在批准前发生变更为 stale;rejected 的提案不会再针对相同的成员提出。整理被撤销后,approved 仍保持为 approved:请查看该次整理的动作以确认改动是否仍然有效。
reviewed_by_principal_idDevId批准或拒绝该提案的主体。
reviewed_atstring (date-time)批准或拒绝的时间。
closed_atstring (date-time)脱离 open 状态的时间,不论原因。
created_at必填string (date-time)这次整理写下这条提案的时间。

DevMemoryProposalEvidence

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

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

DevMemoryProposalKind

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

取值: merge | supersede | conflict | promote

DevMemoryProposalPlan

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

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

DevMemoryProposalStatus

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

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

DevMemoryProposalTime

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

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

DevMemoryProvenance

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

DevMemoryProvenanceSource

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

DevMemoryScope

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

取值: project | agent | account

DevMemorySection

字段类型说明
source必填account | agent | project | usageaccount、agent、project 或 usage。
kind必填string记忆的种类,比如 preference、decision。
text必填string记忆的内容。
confidence必填number0 到 1:这条记忆记录的置信度。0 到 1
valid_untilstring (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_availableboolean当前部署是否可调用模型执行 D4(运营方已启用该功能并配置了模型)。它描述的是部署的配置,因此仅向属于 tenant_admin 或持有 knowledge:manage 的 Key 返回,且该 Key 未限定到 Space 或元数据范围。
updated_atstring (date-time)设置最近一次修改的时间。尚未配置过此 Space 时不返回。
updated_by_principal_idDevId长度 1 到 256

DevMemorySource

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

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

DevMemorySourceRef

字段类型说明
memory_idDevId长度 1 到 256
candidate_idDevId长度 1 到 256
claim_idDevId长度 1 到 256
entry_idDevId长度 1 到 256
version_idDevId长度 1 到 256
space_idDevId长度 1 到 256
recorded_at必填string (date-time)这条记忆记录的时间。
valid_from必填string (date-time)这条记忆开始生效的时间。

DevMemoryStatus

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

取值: candidate | confirmed | rejected | superseded

DevMemoryUndoReceipt

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

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

DevMemoryView

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

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

DevMergeConflict

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

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

DevMergeConflictPolicy

取值: abort | keep_main | keep_branch

DevMergeProposed

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

DevMergeRequest

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

字段类型说明
message必填string1 到 1000 个字符。记为本次合并写入主线的每个版本的说明。长度 1 到 1000
pathsDevPath[]只合并这些路径,1 到 1000 个;目录会包含其下的全部内容。不传则合并整个分支。1 到 1000 项
on_conflictDevMergeConflictPolicy对分支起点之后主线又修改过的路径的处理方式: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_itemsDevMergeProposed[]带 Prefer: handling=proposal 时:合并的 Agent 不拥有的文件,没有写入而是提交了提案。它们和合并的路径一样离开分支。没有时不出现。

DevMergeSkipReason

取值: symlink | unchanged | kept_main

DevMergeSkipped

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

DevMergedOp

取值: create | update | delete | mkdir

DevMergedPath

字段类型说明
path必填DevPath长度 1 到 4096
op必填DevMergedOp合并在主线上做了什么:create、update、delete 或 mkdir。
entry_idDevId长度 1 到 256
version_idDevId长度 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_msinteger音频和视频:时长,单位为毫秒。
speakersinteger音频和视频:转写结果区分出的说话人数;未区分时不返回。
sheetsinteger电子表格和 CSV:工作表数。
rowsinteger电子表格和 CSV:所有工作表的总行数。
columnsinteger电子表格和 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必填DevPrincipalKindhuman 表示人,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 在已存储对象的媒体类型与上传时声明的不一致时返回。

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

DevProcessingProgress

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

字段类型说明
done必填integer
total必填integer

DevProcessingQueue

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

字段类型说明
position必填integer本账户中排在这一项之前开始的就绪任务数,不计其他账户的任务。对限定了部分 Space 或元数据范围的 Key,只计同一 Space 中的任务(限定元数据范围时,只计该 Key 能读取的文件)。
waited_seconds必填integer该步骤进入队列后经过的秒数。
waiting_for必填capacity | retry | pausedcapacity:所有工作进程均繁忙,有空闲时即开始。其他 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
pathDevPath文件现在的位置。在废纸篓里时没有。
status必填DevProposalStatus在审核人批准或拒绝、或作者撤回之前为 open。
base_version_id必填DevId长度 1 到 256
proposed_version_id必填DevId长度 1 到 256
approved_version_idDevId批准时写入的版本。
author_principal_idDevId长度 1 到 256
reviewed_by_principal_idDevId批准或拒绝该提案的主体。
size_bytes必填integer提案内容的字节数。
media_type必填string提案内容的媒体类型。
sha256string提案字节的十六进制 SHA-256。
created_at必填string (date-time)提案提出的时间。
reviewed_atstring (date-time)批准或拒绝的时间。
closed_atstring (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_idDevId仅彻底删除该次删除操作移除的 Entry。不传则彻底删除当前 Space 废纸篓中你可见的全部内容。

DevPurgedEntry

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

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

DevQueueEstimate

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

字段类型说明
queued_items必填integer写入了新版本、因而进入处理队列的条目数。
eta_secondsinteger完成账户全部就绪任务预计所需的秒数(见 GET /v2/queue)。无法估计时不返回;对限定了部分 Space 或元数据范围的 Key 也不返回。
pausedboolean服务运营方暂停了本账户的处理时返回,值为 true。对限定了部分 Space 或元数据范围的 Key 从不返回。

DevRemediation

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

字段类型说明
action必填string稳定的动作名,如 unauthorized 之后的 check_api_key。
doc_urlstring (uri)该动作的文档地址。

DevReplacingMemory

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

DevRequestClient

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

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

DevRequestLog

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

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

DevRequestLogPage

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

DevRetrievalClock

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

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

DevRetrievalExplainFlag

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

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

DevRetrievalFilter

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

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

DevRetrievalKnobs

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

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

DevRetrievalTrace

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

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

DevRevertRequest

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

DevReviewMemoryRequest

字段类型说明
decision必填confirm | rejectconfirm 确认候选记忆;reject 驳回候选记忆。

DevRollbackRequest

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

DevRotatedWebhookSecret

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

DevRoutedMemory

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

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

DevSearchHit

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

字段类型说明
entry_id必填DevId这段内容所在的 Entry。
version_id必填DevId读取这段内容时所用的版本。
space_idDevId账户记忆没有这个字段:它不属于任何你能访问的 Space。
title必填stringEntry 的标题;文件的标题就是文件名。
text必填string匹配到的内容片段。
score必填number只在同一个响应内可比较。
citation_id必填stringc1、c2……按这次响应里的次序编号。
source_type必填string来源的类型:file、note、web、agent-conversation,或某种记忆类型。
pathDevPath文件的路径。没有路径的 Entry 不带这个字段。
urlstring从网址导入的 Entry:该网址,用于链接回原网页。文件则带 path。
occurred_atstring (date-time)这段内容所说的事发生的时间:Entry 的 occurred_at,对话则是其中消息的时间。来源没有时间时不带这个字段。
modified_atstring (date-time)读取这段内容时所用的版本写入的时间。和 occurred_at 一起用来分辨新旧。
stated_datestring (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_fromtext | heading | documentstated_date 取自哪里:段落正文(text)、段落上方的小节标题(heading)或文档开头(document)。search 中只会出现 text 和 document。
freshnesspending_indexpending_index 表示命中来自新鲜缓冲,只是词法匹配。
memoryDevRoutedMemory仅在开启证据化记忆的部署上提供:从这段原文提炼出的已确认记忆。一次响应里每个文件最多一条。pending_index 命中上永远没有。
explainDevHitExplain仅当请求设置了 explain 时返回。

DevSearchHitField

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

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

DevSearchRequest

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

DevSearchResponse

字段类型说明
data必填DevSearchHit[]命中,最相关的在前。
trace_id必填DevId长度 1 到 256
partial必填boolean某个检索分支降级,或分数不是校准过的相关度时为 true。
explainDevExplainSummary仅当请求设置了 explain 时返回。
pending_processingDevPendingProcessing仅当所检索的 Space 中仍有 Entry 在处理时返回:这些 Entry 的文本可能不在本次结果中。GET /v2/spaces/{space_id}/processing 会报告它们何时可检索。

DevSetSpaceMemberRequest

字段类型说明
role必填editor | viewereditor 可以写,viewer 只能读。所有者身份不在这里授予。
write_modeDevWriteMode新成员默认 proposal;已有成员不传时保留现值。
write_rootstring | null将该成员的写入范围限制在某个已有目录及其子树下。权限只会收窄:角色、能力和 Key 的限制照常生效,读取不受影响,且成员不能重命名、移动或删除该目录本身。不传时保持现值;传入 null 或 / 取消限制。目录不存在时返回 404 not_found,路径指向文件时返回 409 not_a_directory,两者均带 field: write_root。范围外的写入返回 403 outside_write_root,写入没有路径的 Entry 同样返回该错误(成员自己的 Agent 记忆除外)。长度 1 到 8192
read_rootstring | 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必填stringSpace 的名字。
descriptionstring说明这个 Space 用来做什么的备注。
external_idstring你自己给这个 Space 的 id(例如你的用户 id),设置过才有。在账户的 Space 之间唯一;用 GET /v2/spaces?external_id= 可以按它找到这个 Space。
is_default必填boolean对你来说 default 指向的那个 Space 上为 true。
access_role必填DevSpaceRole你在这个 Space 里的角色:owner、editor 或 viewer。
read_rootDevPath你在此 Space 中的读取根路径,返回读取时该目录的路径。可读取整个 Space 时不返回。请从该路径开始读取 tree:范围外的内容均视为不存在。
write_rootDevPath你在此 Space 中的写入根路径,返回读取时该目录的路径。写入不受限时,不返回该字段。
created_at必填string (date-time)Space 创建的时间。
updated_at必填string (date-time)名称、描述或 external_id 最后一次修改的时间。

DevSpaceActivity

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

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

DevSpaceDeletion

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

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

DevSpaceMember

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

DevSpaceMemoryProgress

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

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

DevSpaceProcessing

Space 的处理进度。

字段类型说明
space_id必填DevId长度 1 到 256
counts必填DevSpaceProcessingCounts
stages必填DevSpaceProcessingStages
searchable_per_minutenumber过去五分钟内平均每分钟变为可检索的 Entry 数。没有时不返回。
eta_secondsinteger按该速率估算的、所有排队和处理中的 Entry 全部变为可检索所需的秒数。没有速率或没有待处理的 Entry 时不返回。
oldest_queued_secondsinteger本 Space 中等待最久的就绪步骤已排队的秒数。无等待步骤时不返回。
waiting_for_capacity必填boolean本 Space 有就绪步骤正在等待空闲工作进程时为 true。不同 Space 和账户的工作轮流执行。
queue_positioninteger本账户其他 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_usdwrites(按自然月,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这个窗口内该指标已用的量。
limitinteger配额。该指标不限量时不带这个字段。
space_id必填DevId长度 1 到 256

DevStartDreamRequest

字段类型说明
scopeDevDreamScope默认值:Agent Key 为 agent(它自己的私有记忆),其他情况为 project。只有 Agent Key 有 agent 范围;其他调用方指定该值时,接口返回 422。

DevTableContent

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

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

DevTraceCandidates

字段类型说明
lexicalinteger
denseinteger
dense_documentinteger
memoryinteger
relationinteger

DevTraceCitation

字段类型说明
entry_id必填DevId长度 1 到 256
version_id必填DevId长度 1 到 256
citation_idstring
sourcestring

DevTraceSource

字段类型说明
source必填string
budgetinteger
usedinteger
pickedinteger
omittedinteger
whystring

DevTraceStage

字段类型说明
stage必填string阶段,例如 embed、lexical、dense、rerank 或 authorize。
status必填succeeded | failed | cancelled | skipped
duration_msinteger仅对持有 knowledge:manage 的 tenant_admin 返回。

DevTraceSummary

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

字段类型说明
candidatesDevTraceCandidates搜索:每一路检索的候选数,只统计调用方能读取的候选。fused_count 的统计方式相同。在采用该统计方式之前记录的轨迹中,两者均不返回。
fused_countinteger
ranked_countinteger
final_countinteger
rerank_appliedboolean
partialboolean
duration_msinteger
stagesDevTraceStage[]搜索:每个阶段的耗时。
purposestring上下文和回答:路由决策,与响应中的 route 相同。
tierstring
rules_firedstring[]
sourcesDevTraceSource[]
tokens_usedinteger
budget_tokensinteger

DevTreeChmod

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

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

DevTreeCopied

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

DevTreeCopy

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

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

DevTreeDelete

字段类型说明
op必填delete恒为 delete。
path必填DevPath长度 1 到 4096
recursiveboolean目录非空时必填,否则返回 409 directory_not_empty。默认 false

DevTreeJobResult

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

字段类型说明
delete_batch_idDevId递归删除:传给 restore 的 id,可恢复任务删除的全部内容,包括失败前已删除的部分。
copiesinteger到目前为止复制的文件数。
restoredinteger恢复的节点数。
mergedinteger合并:写入主线的路径数。
proposedinteger合并:改成提案而没有直接写入的文件数。
skippedinteger合并、导出或导入:略过的项数。
conflictsDevMergeConflict[]以 merge_conflict 失败的合并:前 100 个冲突路径。最多 100 项
filesinteger导出:归档中的文件数。skipped 为无字节可导出的文件数。
bytesinteger导出:归档里文件的总字节数。
archiveDevArchive成功的导出:归档。用 GET /v2/jobs/{job_id}/content-url 下载。
createdinteger导入:新建的文件数。skipped 为未改动的成员数(on_conflict: "skip"、字节相同,或导出归档中 files/ 以外的成员)。
updatedinteger导入:原来就有、这次写了新版本的文件数。
failedinteger导入:没能写入的成员数。
failuresDevImportFailure[]导入:前 100 个无法写入的成员,按归档内的序号标识。不包含路径。最多 100 项

DevTreeMkdir

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

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

DevTreeMove

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

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

DevTreeNode

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

字段类型说明
path必填DevPath长度 1 到 4096
name必填stringpath 的最后一段,保持写入时的写法。
kind必填DevTreeNodeKinddir 或 file;分支上的列表还会有 symlink。
entry_idDevId长度 1 到 256
version_idDevId文件上:最新的版本。通过 snapshot 列出时,是快照钉住的版本。分支列表里没有。
size_bytesinteger文件上。分支列表里只在分支改过的路径上出现。
etagstring文件上(通过 snapshot 列出时没有)。可在 If-Match 中传回,或与本地持有的值比较以判断内容是否已变更。分支列表里只在分支改过的文件上出现。
sha256string在分支改过的文件上,以及通过 snapshot 列出且已知哈希的文件上出现。
media_typestring文件上。分支列表里只在分支改过的文件上出现。
modified_atstring (date-time)主线列表的文件上:内容最后一次变动的时间,也就是最新版本写入的时间。updated_at 在改名、移动时也会变。
mode644 | 755644 或 755。在分支改过的路径上出现。
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_idDevId请求删除了内容时出现,用来整批恢复。
copiesDevTreeCopied[]请求复制了内容时出现:每个复制出的文件一条。

DevTreePage

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

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

DevTreeRestore

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

字段类型说明
op必填restore恒为 restore。
pathDevPath长度 1 到 4096
delete_batch_idDevId长度 1 到 256

DevUpdateBranchRequest

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

字段类型说明
namestring新名字,1 到 255 个字符。长度 1 到 255
ttl_daysinteger1 到 365。设置后同时为分支续期:expires_at 更新为当前时间加上该天数。1 到 365

DevUpdateEntryRequest

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

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

DevUpdateMemoryRequest

至少传一个。

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

DevUpdateMemorySettingsRequest

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

字段类型说明
memory_dreamingDevMemoryDreamingModeauto 在上线前返回 422。
dormancyDevMemoryDormancyMode离线整理如何处理闲置的记忆:report(默认)或 apply。
d4DevMemoryD4Mode离线整理是否请模型比较记忆:off(默认)、shadow 或 propose。

DevUpdatePrincipalRequest

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

DevUpdateSpaceRequest

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

字段类型说明
namestring新名字,1 到 512 个字符。长度 1 到 512
descriptionstring | null新的描述;传 null 清空。长度 1 到 4096
external_idstring | null新的 external_id,1 到 256 个字符;传入 null 清空。已被占用时返回 409 space_external_id_taken。长度 1 到 256

DevUpdateVersionMessageRequest

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

DevUpdateWebhookRequest

字段类型说明
urlstring新的接收地址,规则与创建时相同。最长 2048
opsDevChangeOp[]此后要推送的事件类型,不可重复。1 到 5 项
descriptionstring | nullnull 清空。最长 256
statusDevWebhookStatusdisabled 停止推送(原因为 manual)。active 重新启用已停用的 Webhook,清零 consecutive_failures 并立即尝试;正在推送的一批按原样重发。
reset_cursortrue跳过所有尚未推送的内容,从当前时刻继续。重新启用因 cursor_expired 停用的 Webhook 时必填。

DevUpload

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

DevUploadPartHeaders

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

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

DevUploadPartTarget

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

DevUploadParts

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

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

DevUploadPartsRequest

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

DevUsageFigure

字段类型说明
metric必填writes | storage_bytes | model_tokens | model_spend_micro_usdwrites(按自然月,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这个窗口内该指标已用的量。
limitinteger配额。该指标不限量时不带这个字段。

DevUsagePage

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

字段类型说明
data必填DevSpaceUsageFigure[]每个 Space 的每个指标一条,按 Space id、再按指标排序。
next_cursorDevCursor长度 1 到 1024
tenant_totalsDevUsageFigure[]仅在第一页返回,且仅针对未限定 Space 范围的 tenant_admin Key。
planDevPlan账户的套餐。每项数值的 limit 取自套餐。

DevVersion

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

字段类型说明
id必填DevId以 ver_ 开头。
entry_id必填DevId这个版本所属的 Entry。
status必填DevVersionStatus处理进行到哪一步。
updated_fromDevId这个版本替换的那个版本。第一个版本没有。
messagestring作者附的说明,类似提交信息。
author_principal_idDevId写入者。
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_diffstring统一 diff 格式的差异。identical 时为空;有 diff_omitted 时没有这个字段。
diff_omittedDevDiffOmitted

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[]要推送的事件类型。其他类型的事件直接跳过,不排队。
descriptionstring给人看的备注。
status必填DevWebhookStatusactive;停止投递时为 disabled,原因见 disabled_reason。
disabled_reasonDevWebhookDisabledReasonstatus 是 disabled 时出现。
cursor必填DevCursor最后一批推送或跳过之后的变更流位置。
consecutive_failures必填integer上次成功以来失败的尝试次数。
last_success_atstring (date-time)最近一次投递成功的时间。
last_failure_atstring (date-time)最近一次投递失败的时间。
next_attempt_atstring (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_statusinteger接收方返回的 HTTP 状态码,收到响应时提供。
error_codeDevWebhookErrorCode
duration_ms必填integer本次尝试耗时,单位为毫秒。
created_at必填string (date-time)这次尝试发生的时间。

DevWebhookDisabledReason

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

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

DevWebhookErrorCode

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

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

DevWebhookOutcome

取值: delivered | failed

DevWebhookPayload

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

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

DevWebhookStatus

取值: active | disabled

DevWhoami

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

DevWhoamiKey

字段类型说明
id必填DevId长度 1 到 256
prefix必填stringKey 的开头几个字符:可以展示,足够区分各个 Key。
capabilities必填DevCapability[]该 Key 本身允许的能力。请求实际生效的是 effective_capabilities,即主体同时具备的那部分能力。
allowed_space_idsDevId[]这个 Key 被收窄到的 Space。不存在表示没有收窄到特定 Space。
metadata_scopeDevMetadataScopeKey 受限的元数据范围。没有这个字段表示不按元数据限制。
expires_atstring (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。