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

# `observe` 操作

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


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

<!-- 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 也是如此；参见[身份与命名空间](/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="observecrystallize"></a>

## `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` | 该行所属的会话或对话；`'-'` 表示无。 |

<a id="observerecord"></a>

## `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"（内容匹配了黑名单模式）；否则为 ""。 |

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