跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

observe 操作

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

每个操作都是 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 中。

observe.crystallize

将一个会话中待处理的观察标记为可提取为记忆(仅入队)。

POST /v1/observe.crystallize · MCP loom_observe_crystallize · role writer · idempotent

输入字段 类型 默认值 含义
org str required 租户(身份元组的第一个元素)。
namespace str required 该操作读取或写入的命名空间。
agent str required 写入或读取的 agent;在操作允许的情况下,'-' 或 '*' 表示任意 agent。
user_id str '-' 该行所属的最终用户;'-' 表示无。
session_id str '-' 该行所属的会话或对话;'-' 表示无。
max_observations int 500 该会话中最多有这么多条待处理的观察被标记为就绪,按从旧到新的顺序。
输出字段 类型 含义
enqueued int 为提取 worker 标记为 crystallize:ready 的观察数量;会话没有待处理观察时为 0。
session_id str 该行所属的会话或对话;'-' 表示无。

observe.record

将一次工具观察(输入、输出、文件、错误)记录到情景平面;不调用 LLM。

POST /v1/observe.record · MCP loom_observe_record · role writer · idempotent

输入字段 类型 默认值 含义
org str required 租户(身份元组的第一个元素)。
namespace str required 该操作读取或写入的命名空间。
agent str required 写入或读取的 agent;在操作允许的情况下,'-' 或 '*' 表示任意 agent。
user_id str '-' 该行所属的最终用户;'-' 表示无。
session_id str '-' 该行所属的会话或对话;'-' 表示无。
run_id str '-' 该调用所属的 agent 运行(任务范围);'-' 表示无。
tool_name str required 所运行工具的名称;它通过子串匹配来确定观察的 kind。
tool_input dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None None 由 hook 转发的任意 JSON;会被字符串化并截断,绝不会被执行。
tool_output dict[str, Any] \| list[Any] \| str \| int \| float \| bool \| None None 工具返回的内容;在叙述中会被字符串化并截断为 800 个字符。
file_paths list[str] (computed) 与从输入和叙述中嗅探到的路径合并。
error str \| None None 仅当调用失败时才有值;会将观察的 kind 重新归类为 error。
tags list[str] (computed) 添加在服务器自身标签(observation、kind、文件基名)之后的额外标签;总共最多保留 32 个标签。
observation_date str '' 以 ISO YYYY-MM-DD 格式标记为 valid_at;为空则保持 NULL。
action_type str '' 客户端自身的动作类别(file_read、command_run 等),作为 action:<type> 标签添加。
metadata dict[str, Any] (computed) 客户端上下文(project、repo、event);会被接受,但不存储。
observed_at str '' 工具运行的时刻,这样稍后提交的捕获记录会以其实际发生的时间为准。
输出字段 类型 含义
memory_key str 情景行的键,形如 obs:<session_id>:<hash prefix>;同一次调用重复触发的 hook 会得到相同的键。
memory_id str 始终为空:该行的 id 由表分配,不会回读。
kind str file_edit / command_run / error / web_fetch / file_read / tool_use。
tags list[str] 存储在该行上的标签(最多 32 个)。
file_paths list[str] 存储在该行上的文件路径:包括发送的路径以及在输入和叙述中发现的路径;对自引用调用则为空。
content_sha256 str 所存储观察值(kind、工具、叙述、路径、错误)的哈希。
tool_name str 该行所保存的内容,在账本上记为 out_tool_name / out_has_error / out_narrative_chars —— 叙述只有 40 个字符的观察只是一个工具名,而不是观察。
has_error bool 当 error 非空时为 True(对自引用调用始终为 False)。
narrative_chars int 所存储叙述的字符长度(最多 2000)。
skipped_reason str 该行为何被存为无内容:"self_referential"(工具是 loom 自身或 harness 元工具)、"blacklisted"(内容匹配了黑名单模式);否则为 ""。