接口说明

Marvnor 守真专用模型系统保存你提供的记录，根据这些记录回答结构化问题：证据支持返回 TRUE，证据否定返回 FALSE，无法确定返回 UNKNOWN。它能标出冲突，并支持原地纠错和定向删除。无需安装客户端或 SDK。

快速开始 · 纠错与删除 · 大模型接入

1. 地址与认证

接口地址：https://api.marvnor.com

请求使用 UTF-8 JSON。除公开套餐目录外，本文接口都需要客户中心创建的 API Key：

Authorization: Bearer <你的 API Key>
Content-Type: application/json

同一份记忆的写入、查询和删除必须使用同一个 Key。不同 Key 的记忆互不共享，不需要填写 project 或 environment。Key 应保存在自己服务端的环境变量中，不要放进网页代码、公开仓库或发给大模型。

30 天未使用，记忆数据会连同 Key 一起销毁。

2. 接口一览

AI 工具可通过 https://api.marvnor.com/v1/mcp 使用同一组能力。它是现有接口的 MCP 连接层，核验仍调用 /v1/evaluate，不增加推理字段。使用客户中心的连接 AI 工具页面配置即可。

/v1/evaluate 是唯一推理入口。每道题的答案固定六个字段。数据管理接口返回操作状态、数量或记录凭证，不返回已保存的原始记录。

3. 保存事实

POST /v1/relations

{
  "relations": [{
    "source": "demo-order-001",
    "relation": "status",
    "target": "paid",
    "client_record_id": "demo-status-001"
  }]
}

这条记录表示“订单 demo-order-001 的状态是 paid”。

同一 Key 下，client_record_id 不能分配给另一条事实；相同编号和相同事实可以重复提交。单次接收 1–10,000 条，较大的导入请使用分批导入。

查询中的主体和取值最多 2,000 字符，因此实际接入建议使用简短、稳定的业务名称或编号，而非整段文章。写入和查询应使用相同命名，不要依赖自动同义词匹配。

成功响应中的 ok 表示操作成功，accepted 是本次接收数量，record_ids 按输入顺序给出记录凭证。另有 request_id，按调用情况可能包含 billing 用量回执。请保存凭证与原始事实的对应表，不解析凭证内容，也不把接收成功当作事实已经被独立证实。

4. 查询与六字段答案

POST /v1/evaluate

{
  "questions": [
    {"id": "paid", "source": "demo-order-001", "relation": "status", "target": "paid"}
  ]
}

已保存上述事实且没有冲突时：

{
  "answers": {
    "paid": {
      "conclusion": "TRUE",
      "conflict": false,
      "reason": "supported_evidence",
      "path": ["demo-order-001", "paid"],
      "decision": "answer",
      "evidence_kind": "direct"
    }
  }
}

TRUE 表示已提交证据支持该说法，不代表对现实世界作出绝对保证。UNKNOWN 不是 FALSE。HTTP 200 表示请求成功，不等于业务结论成立。

decision 的公开值包括 answer、abstain、clarify、unknown、open、allow、block、needs_review。需要澄清、复核或无法确定时，应补充依据或向用户确认。它不替代客户自己的业务授权。

evidence_kind 的公开值包括 direct、indirect、explicit_negative、conflict、incompatible_context、no_path、unknown、composite、quarantined。最后一项表示该证据未用于形成有效支持，不表示对内容作出法律判断。无法识别的类别按“需要复核”处理，不默认通过。

请求范围

• questions 必填，每次 1–20 道题。id 必填且在本次请求中唯一。
• 普通题使用 id、source、relation，可带 target、context、as_of。文本字段非空，最多 2,000 字符。
• 请求可附带 relations，最多 200 条临时事实，参与本次所有题目的判断但不会保存。支持 source、relation、target、polarity、confidence、context、validity，不支持记录编号或来源字段。
• 复合题使用 id 和 claim，不能同时填写普通题字段。
• 旧接入中的 include_advice 布尔参数可以省略；它不会增加返回字段。

推理响应外层只有 answers，不附加用量或诊断字段。路径最多返回 2,048 项、合计 131,072 字符；超出时整项 path 为空列表，并标记 path_omitted_limit。复合题的 path 本身也为空，所以空列表不能直接解释为查询失败。

查询某项有哪些已知取值

省略 target，不是传空字符串：

{
  "questions": [
    {"id": "current-status", "source": "demo-order-001", "relation": "status"}
  ]
}

结果仍为六字段，path 是去重、排序后的直接已知候选值，不是全部记忆导出或开放式全文搜索。

普通自定义属性默认单值。同一主体的同一单值属性，在兼容范围、重叠有效时间内出现不同取值，会返回 UNKNOWN 和 conflict: true，例如同一订单同时标为 paid 和 unpaid。supports 等已定义为多值的类型允许多个对象，不会仅因取值多而冲突。不能额外提交 multiple: true 自行改变规则。

发生冲突时，可省略 target 查询候选值，再核对原始依据。多值属性的肯定与明确否定也可能冲突，不能忽略 conflict。

5. 范围、时间与复合判断

范围 context

可包含 domain_id、subdomain_id、scope、subject_version，每项为最多 200 字符的非空字符串。qualifiers 最多 64 个条件，键最多 100 字符，值为 JSON 标量或这些值的列表，不接受嵌套对象。

{"scope": "store-a", "subject_version": "v2"}

查询时提供与事实匹配的范围。不匹配不等于事实为假；业务范围也不能代替不同客户之间的 Key 隔离。

有效时间 validity 与查询时点 as_of

{
  "kind": "interval",
  "valid_from": "2026-10-01T00:00:00Z",
  "valid_to": "2026-10-31T23:59:59Z"
}

时间使用 ISO 8601，建议带时区。interval 至少给出开始或结束时间，开始不能晚于结束。persistent 表示不随查询时点过期，不能同时设置开始或结束时间。

未填写 validity 也按无时间限制处理，不会仅因缺少时间标记变成未知；仍可能遇到冲突或缺少其他支持。observed_at、recorded_at 是可选时间字段，不替代有效期。

查询用 as_of 指定时点；不写不等于自动查询“现在”。落在有效期外的事实不能作为该时点的支持，也不能据此推断其反面成立。

依据位置 evidence_refs

最多 64 项。每项必填 source_id（1–200 字符）和 locator（1–500 字符）；可填 content_hash（1–200 字符）、observed_at（ISO 8601）、role（1–80 字符，默认 fact_support）。这些是客户提交的引用，不会在六字段答案里另行回传原文。

复合题

支持 atom、and、or、not、implies，以及统一指定范围和时点的 scope：

{
  "questions": [{
    "id": "ready",
    "claim": {
      "op": "scope",
      "context": {"scope": "store-a"},
      "as_of": "2026-10-09T00:00:00Z",
      "claim": {
        "op": "and",
        "claims": [
          {"op": "atom", "source": "demo-order-002", "relation": "status", "target": "paid"},
          {"op": "atom", "source": "demo-order-002", "relation": "stock_status", "target": "reserved"}
        ]
      }
    }
  }]
}

atom 必填主体、属性和取值；and / or 的 claims 含 1–256 个子项；not 使用一个 claim；implies 使用 if 和 then 两个子项（兼容 op: "if" 和 when 写法）。scope 必须有 claim，并至少提供非空 context 或有效 as_of。

嵌套范围不能互相矛盾；内层时点只覆盖自己的子项。单请求所有复合题合计最多 512 个判断节点，嵌套深度最多 64 层。没有提交过上述订单数据时，示例不会凭空得到肯定答案。

6. 修改、删除与导入

操作示例见纠错与删除指南。

• 修改：PATCH /v1/relations/{record_id}，至少一个待修改字段，可修改保存事实表中的字段，但不能修改 client_record_id。内置类型和自定义属性均可编辑，保留原记录凭证和自定义编号。成功仅返回 {"ok":true}。
• 单条删除：DELETE /v1/relations/{record_id}，成功返回 {"ok":true,"deleted_count":1}。
• 批量删除：POST /v1/relations/delete，在 record_ids、client_record_ids、完整 relations、batch_id 中四选一。列表限 1–10,000 项，编号不能重复。
• 凭证列表：GET /v1/relations?limit=100&cursor=0，limit 为 1–500，cursor 为非负整数；返回 ok、只含 record_id 的 relations、next_cursor、request_id。next_cursor: null 表示结束，不会返回事实内容。
• 分批导入：写入接口同时提供 batch_id（1–200 字符）、total（正整数总条数）、offset（非负整数，首块为 0）。每块最多 10,000 条；总量受服务可接受上限约束，单块上限不等于账户容量。
• 导入进度：GET /v1/relations/batches/{batch_id} 返回 ok、batch_id、total、next_offset、status、request_id。状态为 partial、complete 或 deleted；不存在的批次返回 404。

只删除指定记录会保留 Key 和其他记录。全部清空会销毁当前 Key 的全部记忆并注销 Key，不可当作普通测试数据清理。

修改后的记录仍使用原凭证或原 client_record_id 定位；按完整事实删除时，需要使用修改后的内容。编辑与删除响应不会回传记录详情，核验结果仍从 /v1/evaluate 获取。

7. 用量与排错

当前套餐和用量规则见客户中心；程序可读取公开的 GET /v1/plans。账户用量可通过带 Key 的 GET /v1/quota 查看。调用是否计入用量按当前规则执行，不以结论为 TRUE、FALSE 或 UNKNOWN 区分。

网络超时不能证明写入失败，不要无条件循环重试。保留 HTTP 状态、时间和响应中已有的 request_id，通过客户中心联系客服；不要发送完整 Key。