Mental Models 模块

更新时间：2026-11-03

心智模型接口

本文介绍心智模型相关的 9 个接口。创建和管理可刷新的合成知识，支持刷新、预览刷新结果和查看历史版本。

调用说明

接入地址：https://cloud.memory.bj.baidubce.com/api，下文路径直接拼接在该地址后。
请求头：Authorization: Bearer <token> 必填；有 JSON 请求体时需携带 Content-Type: application/json。
错误码、异步操作和 operationId 的说明见 API 简介。

接口列表

接口	方法	路径
列出心智模型	`GET`	`/v1/default/banks/{bank_id}/mental-models`
创建心智模型	`POST`	`/v1/default/banks/{bank_id}/mental-models`
获取心智模型	`GET`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}`
更新心智模型	`PATCH`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}`
删除心智模型	`DELETE`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}`
清空心智模型正文	`POST`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/clear`
心智模型历史	`GET`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/history`
刷新心智模型	`POST`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh`
预览心智模型刷新	`POST`	`/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/dry-run-refresh`

列出心智模型

GET /v1/default/banks/{bank_id}/mental-models

列出由用户维护、持续保持最新的文档。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`tags`	query	`array<string>?`	否	按 tags 筛选。
`tags_match`	query	`"any" \\| "all" \\| "exact"`	否	tag 的匹配方式；默认值：`"any"`
`detail`	query	`"metadata" \\| "content" \\| "full"`	否	详情级别：metadata 仅含名称和标签；content 另含内容和配置；full 还包含 reflect_response；默认值：`"full"`
`limit`	query	`integer`	否	默认值：`100`；取值范围：`1`–`1000`
`offset`	query	`integer`	否	默认值：`0`；最小值：`0`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<MentalModelResponse>`	是	结果项目列表。

items[] · MentalModelResponse

数据结构 MentalModelResponse：

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`source_query`	`string?`	否	生成或刷新内容所使用的源查询。
`content`	`string?`	否	Mental model 内容，采用格式规范的 Markdown，由 Reflect 接口自动生成。
`tags`	`array<string>`	否	默认值：`[]`
`max_tokens`	`integer?`	否	最大 token 数。
`trigger`	`MentalModelTrigger-Output?`	否	触发方式或触发配置。
`last_refreshed_at`	`string?`	否	最近刷新时间。
`created_at`	`string?`	否	创建时间。
`reflect_response`	`object?`	否	完整的 Reflect API 响应 payload，包括 based_on facts 和 observations。
`is_stale`	`boolean?`	否	自 last_refreshed_at 后写入了符合此 mental model tag/fact_type scope 的新 memories，或 consolidation 仍有待处理项时为 true。仅在 detail=full 时填充。

trigger · MentalModelTrigger-Output

数据结构 MentalModelTrigger-Output：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Output \\| TagGroupOr-Output \\| TagGroupNot-Output>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "id": "string",
      "bank_id": "string",
      "name": "string",
      "source_query": "string",
      "content": "string",
      "tags": [],
      "max_tokens": 0,
      "trigger": {
        "mode": "full",
        "refresh_after_consolidation": false,
        "refresh_cron": "string",
        "fact_types": [],
        "exclude_mental_models": false,
        "exclude_mental_model_ids": [],
        "tags_match": "any",
        "tag_groups": [],
        "include_chunks": false,
        "recall_max_tokens": 0,
        "recall_chunks_max_tokens": 0
      },
      "last_refreshed_at": "string",
      "created_at": "string",
      "reflect_response": {},
      "is_stale": false
    }
  ]
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_mental_models

创建心智模型

POST /v1/default/banks/{bank_id}/mental-models

在后台使用 source query 运行 Reflect 创建 mental model。返回用于跟踪进度的 operation ID。内容由 Reflect 接口自动生成；可通过 Operations 接口查询完成状态。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`id`	`string?`	否	Mental model 的可选自定义 ID（小写字母数字和连字符）。
`name`	`string`	是	Mental model 的可读名称。
`source_query`	`string`	是	用于生成内容的查询。
`tags`	`array<string>`	否	标签。 for scoped visibility；默认值：`[]`
`max_tokens`	`integer`	否	生成内容的最大 token 数；默认值：`2048`；取值范围：`256`–`8192`
`trigger`	`MentalModelTrigger-Input`	否	触发器设置；默认值：`{}`

trigger · MentalModelTrigger-Input

数据结构 MentalModelTrigger-Input：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

请求示例

                JSON
                
            

                {
  "id": "team-communication",
  "max_tokens": 2048,
  "name": "Team Communication Preferences",
  "source_query": "How does the team prefer to communicate?",
  "tags": [
    "team"
  ],
  "trigger": {
    "refresh_after_consolidation": false
  }
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`mental_model_id`	`string?`	否	已创建 mental model 的 ID。
`operation_id`	`string`	是	用于跟踪 refresh 进度的 operation ID。

响应示例

                JSON
                
                {
  "operation_id": "string",
  "mental_model_id": "string"
}

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=create_mental_model

获取心智模型

GET /v1/default/banks/{bank_id}/mental-models/{mental_model_id}

按 ID 获取指定 mental model。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id
`detail`	query	`"metadata" \\| "content" \\| "full"`	否	详情级别：metadata 仅含名称和标签；content 另含内容和配置；full 还包含 reflect_response；默认值：`"full"`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`source_query`	`string?`	否	生成或刷新内容所使用的源查询。
`content`	`string?`	否	Mental model 内容，采用格式规范的 Markdown，由 Reflect 接口自动生成。
`tags`	`array<string>`	否	默认值：`[]`
`max_tokens`	`integer?`	否	最大 token 数。
`trigger`	`MentalModelTrigger-Output?`	否	触发方式或触发配置。
`last_refreshed_at`	`string?`	否	最近刷新时间。
`created_at`	`string?`	否	创建时间。
`reflect_response`	`object?`	否	完整的 Reflect API 响应 payload，包括 based_on facts 和 observations。
`is_stale`	`boolean?`	否	自 last_refreshed_at 后写入了符合此 mental model tag/fact_type scope 的新 memories，或 consolidation 仍有待处理项时为 true。仅在 detail=full 时填充。

trigger · MentalModelTrigger-Output

数据结构 MentalModelTrigger-Output：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Output \\| TagGroupOr-Output \\| TagGroupNot-Output>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

响应示例

                JSON
                
            

                {
  "id": "string",
  "bank_id": "string",
  "name": "string",
  "source_query": "string",
  "content": "string",
  "tags": [],
  "max_tokens": 0,
  "trigger": {
    "mode": "full",
    "refresh_after_consolidation": false,
    "refresh_cron": "string",
    "fact_types": [
      "world"
    ],
    "exclude_mental_models": false,
    "exclude_mental_model_ids": [
      "string"
    ],
    "tags_match": "any",
    "tag_groups": [],
    "include_chunks": false,
    "recall_max_tokens": 0,
    "recall_chunks_max_tokens": 0
  },
  "last_refreshed_at": "string",
  "created_at": "string",
  "reflect_response": {},
  "is_stale": false
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_mental_model

更新心智模型

PATCH /v1/default/banks/{bank_id}/mental-models/{mental_model_id}

更新 mental model 的名称和/或 source query。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`name`	`string?`	否	mental model 的新名称。
`source_query`	`string?`	否	Mental model 的新 source query。
`max_tokens`	`integer?`	否	生成内容的最大 token 数；取值范围：`256`–`8192`
`tags`	`array<string>?`	否	标签。 for scoped visibility
`trigger`	`MentalModelTrigger-Input?`	否	触发器设置。

trigger · MentalModelTrigger-Input

数据结构 MentalModelTrigger-Input：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Input \\| TagGroupOr-Input \\| TagGroupNot-Input>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

请求示例

                JSON
                
            

                {
  "max_tokens": 4096,
  "name": "Updated Team Communication Preferences",
  "source_query": "How does the team prefer to communicate?",
  "tags": [
    "team",
    "communication"
  ],
  "trigger": {
    "refresh_after_consolidation": true
  }
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`source_query`	`string?`	否	生成或刷新内容所使用的源查询。
`content`	`string?`	否	Mental model 内容，采用格式规范的 Markdown，由 Reflect 接口自动生成。
`tags`	`array<string>`	否	默认值：`[]`
`max_tokens`	`integer?`	否	最大 token 数。
`trigger`	`MentalModelTrigger-Output?`	否	触发方式或触发配置。
`last_refreshed_at`	`string?`	否	最近刷新时间。
`created_at`	`string?`	否	创建时间。
`reflect_response`	`object?`	否	完整的 Reflect API 响应 payload，包括 based_on facts 和 observations。
`is_stale`	`boolean?`	否	自 last_refreshed_at 后写入了符合此 mental model tag/fact_type scope 的新 memories，或 consolidation 仍有待处理项时为 true。仅在 detail=full 时填充。

trigger · MentalModelTrigger-Output

数据结构 MentalModelTrigger-Output：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Output \\| TagGroupOr-Output \\| TagGroupNot-Output>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

响应示例

                JSON
                
            

                {
  "id": "string",
  "bank_id": "string",
  "name": "string",
  "source_query": "string",
  "content": "string",
  "tags": [],
  "max_tokens": 0,
  "trigger": {
    "mode": "full",
    "refresh_after_consolidation": false,
    "refresh_cron": "string",
    "fact_types": [
      "world"
    ],
    "exclude_mental_models": false,
    "exclude_mental_model_ids": [
      "string"
    ],
    "tags_match": "any",
    "tag_groups": [],
    "include_chunks": false,
    "recall_max_tokens": 0,
    "recall_chunks_max_tokens": 0
  },
  "last_refreshed_at": "string",
  "created_at": "string",
  "reflect_response": {},
  "is_stale": false
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=update_mental_model

删除心智模型

DELETE /v1/default/banks/{bank_id}/mental-models/{mental_model_id}

删除 mental model。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

无展开字段（标量、自由 object 或未声明 properties）

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=delete_mental_model

清空心智模型正文

POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/clear

清空 mental model 内容，使下一次 refresh 执行完整重新合成。适用于经过多次增量 refresh 后产生偏移的 delta-mode models。清空后调用 /refresh 接口触发干净的完整重建。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`name`	`string`	是	名称。
`source_query`	`string?`	否	生成或刷新内容所使用的源查询。
`content`	`string?`	否	Mental model 内容，采用格式规范的 Markdown，由 Reflect 接口自动生成。
`tags`	`array<string>`	否	默认值：`[]`
`max_tokens`	`integer?`	否	最大 token 数。
`trigger`	`MentalModelTrigger-Output?`	否	触发方式或触发配置。
`last_refreshed_at`	`string?`	否	最近刷新时间。
`created_at`	`string?`	否	创建时间。
`reflect_response`	`object?`	否	完整的 Reflect API 响应 payload，包括 based_on facts 和 observations。
`is_stale`	`boolean?`	否	自 last_refreshed_at 后写入了符合此 mental model tag/fact_type scope 的新 memories，或 consolidation 仍有待处理项时为 true。仅在 detail=full 时填充。

trigger · MentalModelTrigger-Output

数据结构 MentalModelTrigger-Output：

字段	类型	必填	说明
`mode`	`"full" \\| "delta"`	否	刷新模式。full（默认）每次刷新都从头生成 mental model 内容；delta 在现有内容上进行局部编辑，逐字节保留未变化的章节，移除过时内容并加入新内容。如果 mental model 尚无内容，或 source_query 自上次刷新后发生变化，delta 会自动回退为完整生成；默认值：`"full"`
`response_schema`	`object?`	否	用于结构化输出的可选 JSON Schema。设置后，每次刷新都会执行与 Reflect`response_schema` 相同的结构化抽取，并将解析结果存入 `reflect_response.structured_output`，同时保留 Markdown 内容。
`keep_trace`	`boolean`	否	为 true 时，记录 mental model 每次刷新的执行 trace，便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace；工具输出会缩减为结果数量，以限制存储规模；默认值：`false`
`refresh_after_consolidation`	`boolean`	否	为 true 时，在 observations consolidation 后刷新此 mental model（实时模式）；默认值：`false`
`refresh_cron`	`string?`	否	用于按固定计划刷新此 mental model 的 cron 表达式（UTC，标准 5 字段语法，例如`0 3 * * *` 表示每天 UTC 03:00）。与 refresh_after_consolidation 互斥：model 只能在 consolidation 后刷新或按 cron 刷新，不能同时启用。计划刷新仅在 model 已过期时执行（自上次刷新后 scope 内出现新 memories）；没有变化时跳过，避免浪费 LLM 调用。null 表示不设置计划。
`fact_types`	`array<"world" \\| "experience" \\| "observation">?`	否	筛选 Reflect 时检索的 fact type。null 表示全部类型（world、experience、observation）。
`exclude_mental_models`	`boolean`	否	为 true 时，从 Reflect 循环中排除所有 mental models（跳过 search_mental_models 工具）；默认值：`false`
`exclude_mental_model_ids`	`array<string>?`	否	按 ID 从 Reflect 循环中排除指定 mental models。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"?`	否	覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时，有 tags 的 model 默认为 all_strict（用于安全隔离），无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Output \\| TagGroupOr-Output \\| TagGroupNot-Output>?`	否	Refresh 时使用的复合布尔 tag 表达式，用于替代 model 自身的 tags。设置后，这些 tag groups 会传给 Reflect，model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式，以实现复杂的 tag scope。
`include_chunks`	`boolean?`	否	覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank／全局配置默认值（recall_include_chunks）。
`recall_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank／全局配置默认值（recall_max_tokens）。
`recall_chunks_max_tokens`	`integer?`	否	覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank／全局配置默认值（recall_chunks_max_tokens）。

响应示例

                JSON
                
            

                {
  "id": "string",
  "bank_id": "string",
  "name": "string",
  "source_query": "string",
  "content": "string",
  "tags": [],
  "max_tokens": 0,
  "trigger": {
    "mode": "full",
    "refresh_after_consolidation": false,
    "refresh_cron": "string",
    "fact_types": [
      "world"
    ],
    "exclude_mental_models": false,
    "exclude_mental_model_ids": [
      "string"
    ],
    "tags_match": "any",
    "tag_groups": [],
    "include_chunks": false,
    "recall_max_tokens": 0,
    "recall_chunks_max_tokens": 0
  },
  "last_refreshed_at": "string",
  "created_at": "string",
  "reflect_response": {},
  "is_stale": false
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=clear_mental_model

心智模型历史

GET /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/history

获取 mental model 的刷新历史，展示内容随时间的变化。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

无展开字段（标量、自由 object 或未声明 properties）

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_mental_model_history

刷新心智模型

POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh

提交异步任务，重新通过 Reflect 运行 source query 并更新内容。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	Mental 数据结构 Id

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。
`status`	`string`	是	当前处理状态；异步操作通常为 pending、processing、completed、failed 或 cancelled。

响应示例

                JSON
                
                {
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=refresh_mental_model

预览心智模型刷新

POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/dry-run-refresh

预览心智模型刷新结果，但不持久化任何更改。接口会执行完整的检索与生成流程，并返回拟生成的内容、结构化输出、事实使用情况和执行 trace，适合在修改配置或 prompt 后验证效果。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`mental_model_id`	path	`string`	是	要预览刷新的 mental model ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`mental_model_id`	`string`	是	预览的 mental model ID。
`name`	`string`	是	mental model 的显示名称。
`requested_mode`	`"full" \\| "delta"`	是	请求的刷新模式（来自 model trigger，也可以覆盖）。
`effective_mode`	`"full" \\| "delta"`	是	刷新实际执行的模式。
`mode_fallback_reason`	`"no_baseline_content" \\| "source_query_changed" \\| "structured_doc_unreadable" \\| "delta_ops_failed" \\| "delta_ops_all_skipped"?`	否	请求 delta 但未能应用时的原因。
`outcome`	`"content_written" \\| "content_preserved_no_new_facts" \\| "refresh_failed_empty_candidate" \\| "refresh_failed_delta_not_applied"`	是	实际刷新将如何处理该 document。
`would_persist`	`boolean`	是	实际刷新是否会写入新内容。
`scope`	`MentalModelRefreshScope`	是	解析后的 memory scope。
`window`	`MentalModelRefreshWindow`	是	读取数据时使用的快照窗口。
`facts`	`MentalModelFactCounts`	是	检索到和实际使用的 facts 数量。
`based_on`	`map<string, array<object>>`	否	本次生成所依据的证据，按 fact type 分组；其结构与实际刷新持久化到`reflect_response.based_on` 的内容相同，因此预览无需写入即可展示来源。
`current_content`	`string`	是	model 当前的内容。
`candidate_content`	`string`	是	执行任何 delta 操作之前的原始 Reflect 合成内容。
`preview_content`	`string`	是	实际刷新将保存的内容：delta 模式下为编辑后的 document，full 模式下为候选内容。
`diff`	`string`	是	从`current_content` 到 `preview_content` 的 unified diff；内容相同时为空。
`delta_operations`	`MentalModelDeltaOperations?`	否	delta 模式下生成的结构化操作。
`trace`	`MentalModelRefreshTrace`	是	此次运行的执行 trace；dry-run 始终包含。
`usage`	`TokenUsage`	否	此次运行所有 LLM 调用的 token 用量。
`duration_ms`	`integer`	否	此次运行的实际耗时；默认值：`0`
`warnings`	`array<string>`	否	需要人工关注的情况，以自然语言说明。

scope · MentalModelRefreshScope

数据结构 MentalModelRefreshScope：

字段	类型	必填	说明
`tags`	`array<string>?`	否	用于筛选 memories 的扁平 tags；未使用时为 null。
`tags_match`	`"any" \\| "all" \\| "any_strict" \\| "all_strict" \\| "exact"`	是	解析后的 tag 匹配模式。
`tag_groups`	`array<TagGroupLeaf \\| TagGroupAnd-Output \\| TagGroupOr-Output \\| TagGroupNot-Output>?`	否	设置后用于取代扁平 tags 的复合 tag 表达式。
`fact_types`	`array<string>?`	否	检索的 fact type；null 表示全部类型。
`exclude_mental_models`	`boolean`	是	是否从 Reflect 循环中排除其他 mental models。
`exclude_mental_model_ids`	`array<string>`	否	按 ID 排除的 mental models，始终包含当前刷新的 model。

window · MentalModelRefreshWindow

数据结构 MentalModelRefreshWindow：

字段	类型	必填	说明
`created_after`	`string(date-time)?`	否	memory 创建时间的下界。仅在 delta 模式下设置，其值为 model 的`last_refreshed_at`，因此 delta 刷新只会读取比上次刷新更新的 memories。
`created_before`	`string(date-time)`	是	限定此次刷新的数据库时间快照。此时间之后提交的 memories 不会被读取，因此仍会晚于持久化的 watermark，并由下一次刷新处理。
`watermark`	`string(date-time)?`	否	实际刷新将持久化的`last_refreshed_at`：取快照中可见且在 scope 内的最新 memory 时间，而不是 `now()`。null 表示没有可见且在 scope 内的 memory。

facts · MentalModelFactCounts

数据结构 MentalModelFactCounts：

字段	类型	必填	说明
`retrieved`	`map<string, integer>`	否	Reflect Agent 的工具调用所返回的 facts，按 fact type 统计。
`used`	`map<string, integer>`	否	Agent 声明实际用于生成内容的 facts，按 fact type 统计。

delta_operations · MentalModelDeltaOperations

数据结构 MentalModelDeltaOperations：

字段	类型	必填	说明
`applied`	`array<object>`	否	按顺序应用到 document 的操作。
`skipped`	`array<object>`	否	因无效而被丢弃的操作，每条均附原因。

trace · MentalModelRefreshTrace

数据结构 MentalModelRefreshTrace：

字段	类型	必填	说明
`recorded_at`	`string(date-time)?`	否	记录此 trace 的时间。
`effective_mode`	`"full" \\| "delta"`	是	刷新实际采用 full 还是 delta 模式。
`mode_fallback_reason`	`"no_baseline_content" \\| "source_query_changed" \\| "structured_doc_unreadable" \\| "delta_ops_failed" \\| "delta_ops_all_skipped"?`	否	请求 delta 但未能应用时的原因。
`outcome`	`"content_written" \\| "content_preserved_no_new_facts" \\| "refresh_failed_empty_candidate" \\| "refresh_failed_delta_not_applied"`	是	此次刷新对 document 执行的处理。
`tool_calls`	`array<MentalModelTraceToolCall>`	否	刷新期间执行的 Reflect 工具调用。
`llm_calls`	`array<LLMCallTrace>`	否	刷新期间执行的 LLM 调用。
`delta_operations`	`MentalModelDeltaOperations?`	否	delta 模式下生成的结构化操作。
`usage`	`TokenUsage?`	否	此次刷新所有 LLM 调用的 token 用量。
`duration_ms`	`integer`	否	刷新实际耗时；默认值：`0`
`warnings`	`array<string>`	否	需要人工关注的情况，以自然语言说明。

tool_calls[] · MentalModelTraceToolCall

数据结构 MentalModelTraceToolCall：

字段	类型	必填	说明
`tool`	`string`	是	工具名称，例如 recall、search_observations、get_mental_model 或 expand。
`reason`	`string?`	否	Agent 给出的调用原因。
`input`	`object`	否	工具输入参数。
`output`	`object?`	否	工具返回的结果。dry-run 不存储数据，因此会返回此字段；实际刷新持久化 trace 时会省略，以限制记录大小。
`updated_at`	`string(date-time)?`	否	传给此次调用的刷新窗口下界，即 delta watermark。该筛选实际作用于 memory 的`updated_at`，因此自上次刷新后只要被更新过的 memory 都符合条件。null 表示不施加时间边界，结果不受刷新窗口限制（mental model 查询和 chunk 展开即采用此行为）。
`result_count`	`integer?`	否	工具返回的条目数量（可统计时）。
`duration_ms`	`integer`	是	执行耗时，单位为毫秒。
`iteration`	`integer`	否	此次调用所属的 Agent 循环轮次（从 1 开始）；默认值：`0`

llm_calls[] · LLMCallTrace

数据结构 LLMCallTrace：

字段	类型	必填	说明
`scope`	`string`	是	调用范围，例如 agent_1、agent_2 或 final。
`duration_ms`	`integer`	是	执行耗时，单位为毫秒

delta_operations · MentalModelDeltaOperations

数据结构 MentalModelDeltaOperations：

字段	类型	必填	说明
`applied`	`array<object>`	否	按顺序应用到 document 的操作。
`skipped`	`array<object>`	否	因无效而被丢弃的操作，每条均附原因。

usage · TokenUsage

数据结构 TokenUsage：

字段	类型	必填	说明
`input_tokens`	`integer`	否	消耗的输入／prompt token 数量；默认值：`0`
`output_tokens`	`integer`	否	生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：`0`
`total_tokens`	`integer`	否	token 总数（输入加输出，不含推理 token）；默认值：`0`
`cached_tokens`	`integer`	否	provider 报告的缓存命中／缓存读取 prompt token 数量；默认值：`0`
`thoughts_tokens`	`integer`	否	模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：`0`

usage · TokenUsage

数据结构 TokenUsage：

字段	类型	必填	说明
`input_tokens`	`integer`	否	消耗的输入／prompt token 数量；默认值：`0`
`output_tokens`	`integer`	否	生成的可见输出／completion token 数量（不含推理／思考 token）；默认值：`0`
`total_tokens`	`integer`	否	token 总数（输入加输出，不含推理 token）；默认值：`0`
`cached_tokens`	`integer`	否	provider 报告的缓存命中／缓存读取 prompt token 数量；默认值：`0`
`thoughts_tokens`	`integer`	否	模型生成的推理／思考 token 数量。部分 provider（如 Gemini 2.5+ 系列）按输出费率计费，但不会显示在可见响应中；默认值：`0`

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	校验错误列表。

detail[] · ValidationError

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径。
`msg`	`string`	是	错误消息。
`type`	`string`	是	错误类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文。

operationId=dry_run_refresh_mental_model

评价此篇文章

有帮助没帮助

Knowledge Base 模块

Documents 模块

上下文数据服务

Mental Models 模块

心智模型接口

调用说明

接口列表

列出心智模型

参数

请求头

响应

响应示例

响应

响应示例

创建心智模型

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

获取心智模型

参数

请求头

响应

响应示例

响应

响应示例

更新心智模型

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

删除心智模型

参数

请求头

响应

响应

响应示例

清空心智模型正文

参数

请求头

响应

响应示例

响应

响应示例

心智模型历史

参数

请求头

响应

响应

响应示例

刷新心智模型

参数

请求头

响应

响应示例

响应

响应示例

预览心智模型刷新

参数

请求头

响应

响应