---
title: "`ops` 操作"
---

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

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

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

<!-- 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，而在[部分操作](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)说明了角色、类型以及 MCP 的 `all` 列表。未知的输入字段会照常处理，并列在 `ignored_args` 中。

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

<a id="opscapabilities"></a>

## `ops.capabilities`

身份是可选的：客户端可以用手中持有的任意令牌发现接口（仅检查角色，不指定命名空间）。

`POST /v1/ops.capabilities` · MCP `loom_ops_capabilities` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | `''` | 租户（身份元组的第一个元素）。 |
| `consumer` | `str` | `''` | 调用方集成的标签，记录在账本行中。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `build_commit` | `str` | 构建所运行镜像的 git 提交；从源码运行时为空。 |
| `schema_version` | `str` | 线路 schema 版本，即 `X-Schema-Version` 头所给出的版本。 |
| `ops` | `list[OpCapability]` | 所有已注册的操作，按名称排序，包括隐藏的操作。 |
| `consumer_field` | `str` | 所有请求模型中指明调用方的每个字段，即存储在每个账本行上的标签。 |

<a id="opshealth"></a>

## `ops.health`

运行部署的自检（schema 约定、嵌入桩、ClickHouse 分片、操作构成、过程平面、worker），并将每项结果报告为 ok、warn 或 fail。

`POST /v1/ops.health` · MCP `loom_ops_health` · 角色 `org_admin` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str \| None` | `None` | 该操作读取或写入的命名空间。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `checks` | `list[OpsHealthCheck]` | 每项健康检查一个条目（schema 约定、嵌入桩、分片、操作构成、worker 等），每个条目包含其状态，状态不为 `ok` 时还包含建议的修复方法。 |
| `worker_status` | `dict[str, dict[str, Any]]` | 此进程中每个后台 worker 的状态：上次运行时间、耗时、结果、上次错误的类型（`last_error_kind`）、连续失败次数和总运行次数；在任何 worker 运行之前为空。 |
| `overall` | `Literal['ok', 'warn', 'fail']` | 任一检查失败时为 `fail`，否则任一检查告警时为 `warn`，否则为 `ok`。 |

<a id="opsprojection_failureslist"></a>

## `ops.projection_failures.list`

列出已记录的投影失败：写入未能生成的派生行（嵌入、图边、摘要）。

`POST /v1/ops.projection_failures.list` · MCP `loom_ops_projection_failures_list` · 角色 `org_admin` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str \| None` | `None` | 该操作读取或写入的命名空间。 |
| `projection` | `str` | `''` | 仅列出此投影的失败（即派生表，例如 `memory_chunks` 或 `entity_edges`）；为空则列出所有投影。 |
| `status` | `Literal['active', 'resolved', 'abandoned', '']` | `'active'` | `active` 列出未解决的失败，`resolved` 列出已修复的失败，`abandoned` 列出修复已放弃的失败（原因在 `error_message` 中），为空则列出全部。 |
| `limit` | `int` | `100` | 最多返回这么多条失败，最新的在前。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[ProjectionFailureRow]` | 与过滤条件匹配的已记录失败，最新的在前。 |
| `total` | `int` | 返回的行数（不含超出 `limit` 的数量）。 |

<a id="opsprojection_failuresresolve"></a>

## `ops.projection_failures.resolve`

按 id 将投影失败标记为已解决，不重试。

`POST /v1/ops.projection_failures.resolve` · MCP `loom_ops_projection_failures_resolve` · 角色 `org_admin` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `failure_ids` | `list[str]` | 必填 | 要标记为已解决且不重试的失败，1 到 500 个 id。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `resolved` | `int` | 提交用于解决的非空 id 数；与任何未解决失败都不匹配的 id 也会计入。 |

<a id="opsprojection_failuresretry"></a>

## `ops.projection_failures.retry`

重试某个命名空间下未解决的投影失败，可选择只重试某一种投影。

`POST /v1/ops.projection_failures.retry` · MCP `loom_ops_projection_failures_retry` · 角色 `org_admin` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str \| None` | `None` | 该操作读取或写入的命名空间。 |
| `projection` | `str` | `''` | 仅重试此投影的失败；为空则重试所有投影。 |
| `limit` | `int` | `50` | 最多重试这么多条未解决的失败，最新的在前。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `results` | `list[ProjectionFailureRetryRow]` | 每个已尝试的失败一个条目，说明是否已重试并解决，以及未成功的原因。 |
| `retried` | `int` | 其投影具有重试路径且已尝试重试的失败数。 |
| `resolved` | `int` | 重试成功并已标记为已解决的失败数。 |
| `abandoned` | `int` | 重试已放弃、现已标记为 abandoned 的失败数。 |

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