跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

blacklist 操作

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

每个 op 都是 HTTP 上的 POST /v1/<op>,也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)在传输层能够提供时,会根据令牌和 MCP 会话填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们沿用各自平面的 org)之外,所有 op 都使用该安装的 org,而在部分 op 上还会填充其命名空间和 agent;参见身份与命名空间。操作索引说明了角色、种类以及 MCP 的 all 列表。未知的输入字段会被正常处理,并在 ignored_args 中列出。

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 给出的原因(未执行任何查询),或匹配查询失败的错误类型。

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] 符合范围过滤条件的有效模式,按最新优先排序。

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。

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 给出的原因(未执行任何查询),或匹配查询失败的错误类型;在此之前发生的失败属于该调用本身的错误。