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

# `blacklist` 操作

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


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

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个 op 都是 HTTP 上的 `POST /v1/<op>`，也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）在传输层能够提供时，会根据令牌和 MCP 会话填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自平面的 org）之外，所有 op 都使用该安装的 org，而在[部分 op](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)说明了角色、种类以及 MCP 的 `all` 列表。未知的输入字段会被正常处理，并在 `ignored_args` 中列出。

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

<a id="blacklistadd"></a>

## `blacklist.add`

拒绝之后值与某个模式匹配的记忆写入。

`POST /v1/blacklist.add` · MCP `loom_blacklist_add` · 角色 `writer` · 幂等 · 已审计

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `pattern` | `str` | 必填 | 要拒绝的文本，对已存储的值区分大小写进行匹配：可以是子串，也可以是不超过 256 个字符的正则表达式。 |
| `pattern_type` | `Literal['substring', 'regex']` | `'substring'` | `substring`（纯文本）或 `regex`（RE2，用于写入和清扫；在添加时会检查长度上限）。 |
| `scope` | `Literal['namespace', 'org', 'global']` | `'namespace'` | 作用范围：`namespace`（仅此命名空间）、`org`（所有命名空间；需要 org 管理员）或 `global`（所有租户；需要平台管理员）。 |
| `reason` | `str` | `''` | 该模式存在的原因；会被存储并在列表中显示。 |
| `created_by` | `str` | `''` | 仅当调用没有可用于标记的已认证主体时，才记录该作者。 |
| `sweep` | `bool` | `False` | 同时将该模式已匹配的有效行标记为墓碑：范围为此 org 内部，对于命名空间范围的模式则限于该命名空间内。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `pattern_id` | `str` | 新模式的 id，供 `blacklist.sweep` 和 `blacklist.remove` 使用。 |
| `created_at` | `datetime` | 模式被存储的时间（UTC）。 |
| `swept` | `int` | 清扫标记为墓碑的行数；未使用 `sweep` 时为 0。 |
| `swept_truncated` | `bool` | 匹配的行数超过一次清扫所能处理的数量时为 True；请调用 `blacklist.sweep`。 |
| `sweep_error` | `str` | 清扫完成时为 ""，否则说明原因（无论哪种情况模式都已存储）：`<code>: <message>`（用 blacklist.sweep 重新运行）、正则无法运行时 RE2 给出的原因（未执行任何查询），或匹配查询失败的错误类型。 |

<a id="blacklistlist"></a>

## `blacklist.list`

列出抑制记忆存储的模式。

`POST /v1/blacklist.list` · MCP `loom_blacklist_list` · 角色 `viewer` · 读取 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `scope` | `Literal['namespace', 'org', 'global'] \| None` | `None` | scope=None 会返回适用于此 (org, namespace) 的所有模式，其中也包括更高范围（org 范围、global）的模式，即有效规则集，而不仅是字面上固定在此范围的模式。 |
| `limit` | `int` | `100` | 最多返回这么多个模式，范围 1-1000，按最新优先排序。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_BlacklistRow]` | 符合范围过滤条件的有效模式，按最新优先排序。 |

<a id="blacklistremove"></a>

## `blacklist.remove`

移除先前添加的黑名单模式。

`POST /v1/blacklist.remove` · MCP `loom_blacklist_remove` · 角色 `admin` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `pattern_id` | `str` | 必填 | 要标记为墓碑的模式；调用方权限范围之外的命名空间模式会返回 `removed=false`。 |
| `removed_by` | `str` | `''` | 仅记录在黑名单缓存的版本标记上，不记录在模式行上。 |
| `reason` | `str` | `''` | 接受但不存储。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `removed` | `bool` | 调用方看不到具有该 id 的有效模式时为 False。 |
| `removed_at` | `datetime \| None` | 模式被标记为墓碑的时间（UTC）；未移除任何内容时为 null。 |

<a id="blacklistsweep"></a>

## `blacklist.sweep`

将现有模式匹配的有效行标记为墓碑。

`POST /v1/blacklist.sweep` · MCP `loom_blacklist_sweep` · 角色 `writer` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `pattern_id` | `str` | 必填 | 用于清扫的有效模式；未知的 id 或调用方权限范围之外的 id 会返回 404。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `pattern_id` | `str` | 用于清扫的模式，原样返回。 |
| `matched` | `int` | 本次调用中该模式匹配的有效行数：在 ClickHouse 中最多 5,000 行，在 Postgres 权威存储下，再加上本次调用标记为墓碑的暂存头部。 |
| `tombstoned` | `int` | 本次调用标记为墓碑的行数。 |
| `truncated` | `bool` | 匹配的行数超过一次调用所能处理的数量时为 True；请再次调用。 |
| `error` | `str` | 清扫完成时为 ""，否则为 `<code>: <message>`（此时可能已有行被写入，请再次调用）、正则无法运行时 RE2 给出的原因（未执行任何查询），或匹配查询失败的错误类型；在此之前发生的失败属于该调用本身的错误。 |

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