---
title: "`conflicts` 操作"
---

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

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

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

<!-- 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.*`（它们保留各自平面的组织）之外，所有操作都使用该安装的组织，而在[部分操作](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="conflictsallowlist_list"></a>

## `conflicts.allowlist_list`

列出被标记为已知不冲突的 (memory_key, memory_key) 对，使冲突 worker 不再标记它们。

`POST /v1/conflicts.allowlist_list` · MCP `loom_conflicts_allowlist_list` · 角色 `viewer` · 读取 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `limit` | `int` | `100` | 最多返回这么多对，范围 1-1000，最新的在前。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_AllowlistRow]` | 当前有效的允许键对（`memory_key_a` 排在 `memory_key_b` 之前），最新的在前。 |

<a id="conflictsallowlist_remove"></a>

## `conflicts.allowlist_remove`

撤销一项允许决定；该键对在之后的写入中会重新被标记。

`POST /v1/conflicts.allowlist_remove` · MCP `loom_conflicts_allowlist_remove` · 角色 `admin` · 幂等 · 已审计 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `memory_key_a` | `str` | 必填 | 被允许键对中的一个键；两个键的顺序无关紧要。 |
| `memory_key_b` | `str` | 必填 | 键对中的另一个键。 |
| `removed_by` | `str` | `''` | 撤销者；会与 `reason` 一起追加到该键对已存储的原因中。 |
| `reason` | `str` | `''` | 原因；会追加到该键对已存储的原因中。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `removed` | `bool` | 没有匹配到有效的允许键对时为 False。 |

<a id="conflictslist"></a>

## `conflicts.list`

列出两条记忆互相矛盾、尚未解决的冲突。

`POST /v1/conflicts.list` · MCP `loom_conflicts_list` · 角色 `viewer` · 读取 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `limit` | `int` | `50` | 最多返回这么多行，范围 1-500，最新版本在前。 |
| `before_version` | `int \| None` | `None` | Keyset 游标：传入上一次响应中最早的版本即可翻页。 |
| `count_only` | `bool` | `False` | 徽标只需要数字，不需要具体行。 |
| `fresh` | `bool` | `False` | 与 count_only 一起使用时，立即计数，而不是读取有效期一分钟的缓存；默认关闭。 |
| `keys_only` | `bool` | `False` | 记忆视图会标出存在冲突的卡片，只需要键。 |
| `fields` | `list[str] \| None` | `None` | 调用方要读取的输出字段（白名单，会对照行模型解析；未知名称会返回 422）；未设置时返回所有字段。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_ConflictRow]` | 存在冲突的记忆，最新版本在前；在 `count_only` 或 `keys_only` 调用中为空。 |
| `next_before_version` | `int \| None` | 作为下一页的 `before_version` 传入；最后一页为 null。 |
| `total` | `int \| None` | 该命名空间当前有效的冲突数量；在 count_only 调用中设置。 |
| `keys` | `list[str] \| None` | 该命名空间中存在冲突的记忆键；在 keys_only 调用中设置。 |

<a id="conflictspropose_revision"></a>

## `conflicts.propose_revision`

返回非破坏性的 revise/contract/allow 建议。

`POST /v1/conflicts.propose_revision` · MCP `loom_conflicts_propose_revision` · 角色 `viewer` · 读取 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `memory_id` | `str` | 必填 | 要给出建议的存在冲突的记忆（组织范围内的 id）。 |
| `peer_id` | `str \| None` | `None` | 将建议限定为其 `conflict_with` 中的这一个对端；None 表示考虑所有对端。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `found` | `bool` | 当该记忆或它指向的所有行在 `namespace` 中都不是有效状态时为 False。 |
| `memories` | `list[_ConflictCandidateMemory]` | 目标在最前（`local_id` 为 1），随后是它的有效对端，最新的在前。 |
| `suggestions` | `list[_ConflictRevisionSuggestion]` | 最多一条建议的 `conflicts.resolve`，使用本地 id：目标被固定或与某个对端共用同一个键时建议 revise，某个对端被固定时建议 contract，否则建议 allow。 |
| `note` | `str` | 始终说明没有应用任何更改：此操作只提供建议。 |

<a id="conflictsresolve"></a>

## `conflicts.resolve`

选出冲突的胜出方（保留 A、保留 B、两者都保留、合并）。

`POST /v1/conflicts.resolve` · MCP `loom_conflicts_resolve` · 角色 `admin` · 幂等 · 已审计 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `memory_id` | `str` | 必填 | 该决定所针对的存在冲突的记忆（组织范围内的 id）；它必须位于 `namespace` 中。 |
| `decision` | `Literal['revise', 'contract', 'allow']` | 必填 | `revise` 保留它并将对端标记为墓碑；`contract` 将它标记为墓碑并重新激活对端；`allow` 重新激活全部记忆，并将每个键对加入允许列表。 |
| `peer_id` | `str \| None` | `None` | 可选：将解决范围限定为某一个特定对端（仅针对该对端执行 revise）。 |
| `reason` | `str` | `''` | 原因；会追加到被标记为墓碑的行的 `source_trace` 中，并存储在允许列表行上（前 512 个字符）。 |
| `resolved_by` | `str` | `''` | 解决者，与 `reason` 一起记录（前 128 个字符）；不会与令牌核对。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `resolved` | `bool` | 当该记忆或指定的对端未知，或该记忆不在 `namespace` 中时为 False；此时不会写入任何内容。 |
| `decision` | `Literal['revise', 'contract', 'allow']` | 原样返回的决定。 |
| `affected_memory_ids` | `list[str]` | 本次调用标记为墓碑或重新激活的所有记忆 id。 |
| `resolved_at` | `datetime \| None` | 解决操作的执行时间（UTC）；未解决任何内容时为 null。 |
| `total` | `int \| None` | 在调用方读取范围内该命名空间的冲突数量，在写入之后统计；未解决任何内容或计数失败时为 null。 |

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