尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 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"(内容匹配了黑名单模式);否则为 ""。 |