---
title: "`conversation` 操作"
---

<!-- i18n: source=docs/reference/operations/conversation.md blob=11f53adffc40df382651dd38d150af1095bef85c model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/conversation.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/conversation.md), which is authoritative.

<a id="conversation-operations"></a>

每个 `conversation.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个操作都是 HTTP 上的 `POST /v1/<op>`，同时也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会在传输层能够提供时，从令牌和 MCP 会话中填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们保留各自平面的 org）之外，所有操作的 org 都取该安装的 org，而[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)的命名空间和 agent 也会如此填充；参见[身份与命名空间](/docs/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

<!-- prettier-ignore-start -->

<a id="conversationappend"></a>

## `conversation.append`

向线程记录一轮对话（角色 + 内容）。

`POST /v1/conversation.append` · MCP `loom_conversation_append` · role `writer` · 幂等

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `thread_id` | `str` | 必填 | 要追加到的线程；无需事先创建。 |
| `msg_id` | `str` | `''` | 可选；省略时由服务器派生内容哈希 |
| `role` | `Literal['user', 'assistant', 'system', 'tool']` | 必填 | 发言者：`user`、`assistant`、`system` 或 `tool`。 |
| `content` | `str` | 必填 | 消息文本，按原样存储；user 或 assistant 的轮次还会被嵌入以供 `conversation.search` 使用，除非其文本被判定为高。 |
| `reasoning` | `str` | `''` | 模型在这一轮的推理内容，与 `content` 一并存储；为空表示没有。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示没有。 |
| `run_id` | `str` | `'-'` | 此次调用所属的 agent 运行（任务范围）；`'-'` 表示没有。 |
| `metadata` | `dict[str, Any]` | *（计算得出）* | 存储在消息上的自由格式 JSON；可通过 `get` 和 `list` 读回。 |
| `tokens` | `int` | `0` | 调用方上报的该消息的 token 数，按给定值存储；0 表示未上报。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `msg_id` | `str` | 消息 id：传入的 id，或服务器派生的内容哈希。 |
| `ts` | `datetime` | 本次调用的服务器时间；消息写入时的时间戳。 |
| `stored` | `bool` | 当记录功能关闭，或该轮次在嵌入进行期间被删除时为 False。 |
| `reason` | `Literal['', 'duplicate', 'logging_disabled', 'deleted']` | ""（已写入）、"duplicate"（该 msg_id 已写入；stored=True）、"logging_disabled" 或 "deleted"（stored=False）。 |

<a id="conversationcompact"></a>

## `conversation.compact`

将旧的对话轮次总结为一条带嵌入向量的 system 轮次，并将原始轮次标记为已删除（tombstone）。

`POST /v1/conversation.compact` · MCP `loom_conversation_compact` · 角色 `writer` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在该操作允许的情况下可为任意 agent。 |
| `thread_id` | `str` | 必填 | 要压缩的线程。 |
| `keep_recent` | `int` | `10` | 最新的这么多条消息保持原文；更早的消息会被总结，数量以摘要器的提示词能容纳为限。 |
| `min_to_compact` | `int` | `4` | 如果在最后 keep_recent 条之前的新轮次少于该值，则跳过；之前的摘要不计入。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `compacted` | `bool` | 写入了摘要并将原始消息标记为已删除时为 True；否则由 `reason` 说明原因。 |
| `messages_summarized` | `int` | 摘要替换了多少条较早的消息，不含之前的摘要；未压缩时为 0。 |
| `summary_msg_id` | `str` | 合成的 `system` 摘要消息的 id；未压缩时为空。 |
| `tokens_in` | `int` | 摘要器 LLM 调用所用的提示词 token 数；未发起调用时为 0。 |
| `tokens_out` | `int` | 摘要的补全 token 数；未发起调用时为 0。 |
| `reason` | `str` | compacted=False 的原因：nothing-to-compact、below-min-to-compact、already-compacted、summarizer-empty、embed-failed（嵌入器恢复响应后重试）、summary-high-sensitivity（不要重试：同一窗口会得到相同的摘要）。 |

<a id="conversationcreate"></a>

## `conversation.create`

创建一个线程容器。

`POST /v1/conversation.create` · MCP `loom_conversation_create` · 角色 `writer` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `thread_id` | `str` | 必填 | 调用方为该线程指定的 id；使用相同 id 重新创建会替换其标题、元数据和 `run_id`。 |
| `title` | `str` | `''` | 在线程列表中显示的标题；为空表示无标题。 |
| `metadata` | `dict[str, Any]` | *（自动计算）* | 存储在线程行上的自由格式 JSON；`conversation.get` 会返回它。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `thread_id` | `str` | 原样返回输入的 `thread_id`。 |
| `created_at` | `datetime` | 本次调用写入线程行的时间。 |

<a id="conversationdelete"></a>

## `conversation.delete`

软删除一个会话线程：包括它的消息、线程行，以及没有被其他 agent 持有的 embedding。

`POST /v1/conversation.delete` · MCP `loom_conversation_delete` · 角色 `admin` · 幂等 · 有审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下匹配任意 agent。 |
| `thread_id` | `str` | 必填 | 要软删除的线程。 |
| `confirm_thread_id` | `str` | 必填 | 必须与 `thread_id` 相同，否则调用会返回 400 并且不会删除任何内容。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `tombstoned_at` | `datetime` | 标记在每个受影响行上的墓碑时间。 |
| `thread_id` | `str` | 输入 `thread_id` 的回显。 |
| `rows_affected` | `dict[str, int]` | {table_name: 被标记墓碑的行数}；对于 loom.conversation_embeddings，按轮次计数（无论有多少个 embedding 模型持有该轮次，每个轮次只计一行）。 |
| `total` | `int` | 各表 `rows_affected` 之和。 |

<a id="conversationget"></a>

## `conversation.get`

按 id 获取单个线程：线程元数据，以及可选的消息。

`POST /v1/conversation.get` · MCP `loom_conversation_get` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | "*" 或 "-" 表示读取线程中所有 agent 的轮次（两个 agent 都记录过一次的轮次），适用于只有 id 的调用方，与 conversation.search 对 "*" 和 "-" 的读取方式相同；其他任何值只读取该 agent 的轮次。 |
| `thread_id` | `str` | 必填 | 要获取的线程。 |
| `include_messages` | `bool` | `False` | 默认关闭：元数据查询只需两次点读。 |
| `limit` | `int` | `100` | 设置 `include_messages` 时最多返回的消息数（1-1000）。 |
| `offset` | `int` | `0` | 从 `order` 起算的一端开始要跳过的消息数。 |
| `order` | `Literal['asc', 'desc']` | `'asc'` | 页面从线程的哪一端开始计数。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `found` | `bool` | 当线程既没有线程行也没有任何有效消息时为 False。 |
| `thread_id` | `str` | 输入 `thread_id` 的回显。 |
| `title` | `str` | 来自 `conversation.create` 或 `update` 的标题；未设置时为空。 |
| `metadata` | `dict[str, Any]` | 线程元数据 JSON；未设置时为 `{}`，标题生成器写入的 `title_refused` 标记除外。 |
| `run_id` | `str` | 该调用所属的 agent 运行（任务范围）；无则为 `'-'`。 |
| `user_id` | `str` | 该行所属的终端用户；无则为 `'-'`。 |
| `agent` | `str` | 线程的所有者（其线程行的 agent）；对于仅由追加构建的线程，为所读消息中最近的写入者，因此未设置 `include_messages` 时为空。 |
| `created_at` | `datetime \| None` | 线程行首次写入的时间；对于仅由追加构建的线程为 None。 |
| `updated_at` | `datetime \| None` | 线程行最近一次变更的时间；对于仅由追加构建的线程为 None。 |
| `msg_count` | `int` | 线程中有效（未被墓碑标记）的消息数，即使不返回消息也会返回。 |
| `messages` | `list[_ConversationEntry]` | 仅当 include_messages=True 时填充；使用简单的 limit/offset 切片（基于游标的分页遍历应使用 conversation.list）。 |
| `next_cursor` | `str \| None` | 当 `order="asc"` 时，为本页之后轮次的 `conversation.list` 游标；当本页已到末尾或 order 为 `desc` 时为 None。 |

<a id="conversationlist"></a>

## `conversation.list`

枚举某个 agent / 命名空间下已存储的对话线程。

`POST /v1/conversation.list` · MCP `loom_conversation_list` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | "*" 或 "-" 表示读取线程中所有 agent 的轮次（两个 agent 都记录过一次的轮次），适用于只有线程 id 的调用方，与 conversation.search 对 "*" 和 "-" 的处理相同；其他任何值则只读取该 agent 的轮次。 |
| `thread_id` | `str` | 必填 | 要分页浏览的线程，按消息从旧到新排列。 |
| `run_id` | `str \| None` | `None` | 可选过滤条件；None 或 "-" 表示所有运行 |
| `limit` | `int` | `100` | 每页最多返回的消息数（1-1000）。 |
| `cursor` | `str \| None` | `None` | 不透明的 (ts, msg_id) |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_ConversationEntry]` | 按时间顺序排列的一页消息。 |
| `next_cursor` | `str \| None` | 作为 `cursor` 传入即可获取下一页；已是最后一页时为 None。 |

<a id="conversationlist_saved_messages"></a>

## `conversation.list_saved_messages`

按保存时间由新到旧分页列出用户保存的消息，不带查询：在输入任何内容之前，“已保存”面板显示的就是这个首屏视图。

`POST /v1/conversation.list_saved_messages` · MCP `loom_conversation_list_saved_messages` · 角色 `viewer` · 读操作 · 不在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | 必填 | 仅列出该用户保存的消息。 |
| `conversation_id` | `str \| None` | `None` | 可选：仅列出从某一个对话中保存的消息。 |
| `limit` | `int` | `50` | 每页最多返回的消息数（1-200）。 |
| `cursor` | `str \| None` | `None` | 不透明值；传入上一页的 `next_cursor`。 |
| `fields` | `list[str] \| None` | `None` | 调用方要读取的输出字段（按行模型解析的白名单；未知名称会返回 422）；不设置则返回全部字段。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_SavedMessageHit]` | 当前页，最近保存的在前。 |
| `next_cursor` | `str \| None` | 作为 `cursor` 传入以获取下一页；已是最后一页时为 None。 |

<a id="conversationsave_message"></a>

## `conversation.save_message`

保存用户选中用于搜索的一条聊天消息，无论该命名空间是否记录对话记录。

`POST /v1/conversation.save_message` · MCP `loom_conversation_save_message` · 角色 `writer` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `conversation_id` | `str` | 必填 | 客户端的对话 id；它在 Loom 中仍作为线程 id。 |
| `message_id` | `str` | 必填 | 客户端的稳定消息 id。 |
| `role` | `Literal['user', 'assistant']` | 必填 | 只有可选择的 user 和 assistant 消息会被嵌入。 |
| `content` | `str` | 必填 | 消息文本；当对话记录中已有该消息时会被忽略。 |
| `user_id` | `str` | 必填 | 所有者是配对搜索操作中的硬性过滤条件。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `conversation_id` | `str` |  |
| `message_id` | `str` |  |
| `indexed` | `bool` | 当该轮消息已保存并且拥有已保存搜索可排序的向量时为 True：包括新写入、重新保存（完成上次中断的保存所遗留的部分），以及现已标记为已保存的对话记录消息。 |
| `reason` | `Literal['', 'duplicate', 'owner_mismatch', 'deleted', 'unsupported_role', 'embed_failed', 'high_sensitivity']` | "duplicate"：已保存，未做任何更改。"owner_mismatch"：已存储的消息属于其他用户。"deleted"：已存储的消息已被标记删除。"unsupported_role"：已存储的消息是 system 或 tool 消息，不会被嵌入。… |
| `ts` | `datetime` | 已存储消息的时间戳；被拒绝时为拒绝发生的时间。 |

<a id="conversationsaved_status"></a>

## `conversation.saved_status`

一次调用即可查询用户在某个会话中保存了哪些消息：聊天客户端在打开会话时，会据此绘制每条消息的保存状态。

`POST /v1/conversation.saved_status` · MCP `loom_conversation_saved_status` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下匹配任意 agent。 |
| `user_id` | `str` | 必填 | 该行所属的终端用户；`'-'` 表示无。 |
| `conversation_id` | `str` | 必填 | 消息所属的会话；消息 id 在会话内唯一。 |
| `message_ids` | `list[str]` | 必填 | 要检查的消息（1-500 条）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `saved` | `list[str]` | `message_ids` 中该用户已保存的子集，顺序与请求一致。 |

<a id="conversationsearch"></a>

## `conversation.search`

按与 `query` 的嵌入相似度对对话消息排序。

`POST /v1/conversation.search` · MCP `loom_conversation_search` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | "*" 或 "-" 搜索所有 agent 的对话轮次；其他任何值只搜索该 agent 的对话轮次。 |
| `query` | `str` | 必填 | 与消息内容匹配的文本，按嵌入相似度匹配；嵌入器不可用时按子串匹配。 |
| `thread_id` | `str \| None` | `None` | 可选：限定在某一个线程内 |
| `run_id` | `str \| None` | `None` | 可选：按 run_id 过滤；None 或 "-" 表示所有运行 |
| `role` | `Literal['user', 'assistant', 'system', 'tool'] \| None` | `None` | 按发言者过滤；除压缩摘要外的 system 轮次以及 tool 轮次不会被嵌入，因此只能通过子串回退匹配到。 |
| `user_id` | `str \| None` | `None` | 可选的所有者过滤；None 或 "-" 表示所有用户。 |
| `top_k` | `int` | `20` | 最多返回这么多条命中结果（1-200）。 |
| `namespace_scope` | `Literal['this', 'all_mine']` | `'all_mine'` | "all_mine" 还会读取调用者自己的命名空间，最多读取 `memory_search_fanout_max_namespaces` 个，与 knowledge.search 相同。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `hits` | `list[_ConversationHit]` | 匹配的消息，相似度最高的在前；没有任何消息达到相似度下限时为空；使用子串回退时，按最新的在前排列，且没有下限。 |
| `namespaces_skipped` | `list[str]` | 调用者的命名空间中，all_mine 搜索因达到 `memory_search_fanout_max_namespaces` 上限而未读取的命名空间；按名称指定其中一个即可搜索它。 |

<a id="conversationsearch_saved_messages"></a>

## `conversation.search_saved_messages`

仅对某个用户通过 conversation.save_message 保存的消息进行混合搜索，而不是搜索整个对话记录。

`POST /v1/conversation.search_saved_messages` · MCP `loom_conversation_search_saved_messages` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `user_id` | `str` | 必填 | 该行所属的终端用户；`'-'` 表示无。 |
| `query` | `str` | 必填 |  |
| `conversation_id` | `str \| None` | `None` |  |
| `role` | `Literal['user', 'assistant'] \| None` | `None` |  |
| `top_k` | `int` | `20` |  |
| `search_mode` | `Literal['hybrid', 'semantic', 'lexical']` | `'hybrid'` | hybrid：向量检索与针对每条消息全文的 BM25 检索，通过倒数排名融合；semantic：仅向量检索；lexical：仅 BM25 检索。 |
| `lexical_weight` | `float` | `1.0` | 融合中 BM25 检索的权重（hybrid 模式）；1.0 表示权重相等。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `hits` | `list[_SavedMessageHit]` |  |

<a id="conversationset_logging"></a>

## `conversation.set_logging`

切换此命名空间是否记录对话记录。

`POST /v1/conversation.set_logging` · MCP `loom_conversation_set_logging` · 角色 `admin` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `enabled` | `bool` | 必填 | 为 True 时在此命名空间中记录对话记录；为 False 时 `append` 不存储任何内容。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该操作读取或写入的命名空间。 |
| `enabled` | `bool` | 当前生效的日志记录开关状态。 |

<a id="conversationthreads"></a>

## `conversation.threads`

按时间倒序列出命名空间中最近的对话线程。

`POST /v1/conversation.threads` · MCP `loom_conversation_threads` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'*'` | "*" 或 "-" 列出所有 agent 的线程 |
| `window_days` | `int` | `30` | 只返回在最近这么多天内有有效消息的线程（1-365）。 |
| `limit` | `int` | `30` | 最多返回这么多个线程（1-200）。 |
| `offset` | `int` | `0` | 在返回当前页之前要跳过的线程数（0-100,000）；默认 0，即第一页。 |
| `fields` | `list[str] \| None` | `None` | 调用方要读取的输出字段（白名单，按行模型解析；未知名称会返回 422）；未设置时返回所有字段。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `threads` | `list[ConversationThreadSummary]` | 线程列表，按最近活跃时间倒序，每个线程带有消息数和最后一条消息的摘录。 |

<a id="conversationunsave_message"></a>

## `conversation.unsave_message`

从用户的已保存消息搜索中撤回一条消息。

`POST /v1/conversation.unsave_message` · MCP `loom_conversation_unsave_message` · 角色 `writer` · 幂等 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下可为任意 agent。 |
| `conversation_id` | `str` | 必填 | 客户端的会话 ID，与传给 conversation.save_message 的相同。 |
| `message_id` | `str` | 必填 | 客户端的消息 ID，与传给 conversation.save_message 的相同。 |
| `user_id` | `str` | 必填 | 仅撤回该用户的已保存记录。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `conversation_id` | `str` |  |
| `message_id` | `str` |  |
| `found` | `bool` | 当该用户不存在已保存记录时为 False：从未保存、已被撤回，或由其他用户保存（不会予以确认）。 |
| `removed` | `bool` | 当该轮对话本身被移除时为 True：该命名空间不记录对话记录，因此这条记录只是因为保存操作才存在。 |
| `ts` | `datetime` |  |

<a id="conversationupdate"></a>

## `conversation.update`

更新单个会话线程的标题、元数据或 run_id。

`POST /v1/conversation.update` · MCP `loom_conversation_update` · 角色 `writer` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；在操作允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `thread_id` | `str` | 必填 | 要更新的线程；线程不存在时返回 `updated=False`。 |
| `title` | `str \| None` | `None` | 如果三个字段都未提供，处理程序会返回 400（空操作说明调用方有错误）。 |
| `metadata` | `dict[str, Any] \| None` | `None` | 新的元数据 JSON，整体替换旧对象；为 None 时保持不变。 |
| `run_id` | `str \| None` | `None` | 线程的新 run；为 None 或 "-" 时保持不变，为 "" 时将其与所属 run 分离。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `updated` | `bool` | 当线程没有对应的线程行（从未创建）时为 False，此时不会写入任何内容。 |
| `thread_id` | `str` | 输入 `thread_id` 的回显。 |
| `updated_at` | `datetime \| None` | 线程新的 `updated_at`；未更新任何内容时为 None。 |

<!-- prettier-ignore-end -->
