`conversation` 操作
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
每个 conversation.* 操作接受和返回的确切字段。
每个操作都是 HTTP 上的 POST /v1/<op>,同时也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,从令牌和 MCP 会话中填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外,所有操作的 org 都取该安装的 org,而部分操作的命名空间和 agent 也会如此填充;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。
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)。 |
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(不要重试:同一窗口会得到相同的摘要)。 |
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 |
本次调用写入线程行的时间。 |
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 之和。 |
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。 |
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。 |
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。 |
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 |
已存储消息的时间戳;被拒绝时为拒绝发生的时间。 |
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 中该用户已保存的子集,顺序与请求一致。 |
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 上限而未读取的命名空间;按名称指定其中一个即可搜索它。 |
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] |
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 |
当前生效的日志记录开关状态。 |
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] |
线程列表,按最近活跃时间倒序,每个线程带有消息数和最后一条消息的摘录。 |
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 |
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。 |