> Source: https://clickhouse.github.io/loom/zh-CN/reference/operations/inbox/ (Markdown: https://clickhouse.github.io/loom/zh-CN/reference/operations/inbox.md)

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

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

# `inbox` 操作

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

<!-- 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 调用，会填入安装时的 org，适用于除 `code.*` 和 `tracker.*`（它们保留各自平面的值）之外的所有操作，而对于[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)，其命名空间和 agent 也会自动填充；参见[身份与命名空间](https://clickhouse.github.io/loom/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="inboxlist"></a>

## `inbox.list`

调用方可以看到的收件箱：包括由 ``namespace``（已授权的命名空间）拥有的收件箱，以及在使用 ``mine_everywhere`` 时，组织内调用方可以向其投递的所有收件箱：即所属命名空间为调用方…

`POST /v1/inbox.list` · MCP `loom_inbox_list` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在该操作允许时匹配任意 agent。 |
| `mine_everywhere` | `bool` | `False` | 同时列出调用方可以向其投递的所有组织收件箱（对其所属命名空间有写权限，或被列为投递者）；为 false 时只列出由 `namespace` 拥有的收件箱。 |
| `limit` | `int` | `200` | 最多读取这么多行收件箱记录，范围 1-500（使用 `mine_everywhere` 时，在可见性过滤之前计数）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `inboxes` | `list[InboxPayload]` | 可见的收件箱，按名称排序。 |

<a id="inboxpolicy_list"></a>

## `inbox.policy_list`

列出收件箱的信任策略。

`POST /v1/inbox.policy_list` · MCP `loom_inbox_policy_list` · 角色 `viewer` · 读操作 · 不在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许的情况下可为任意 agent。 |
| `inbox` | `str` | 必填 | 要列出规则的收件箱；调用方无权读取的收件箱会返回 404。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `policies` | `list[PolicyPayload]` | 该收件箱的所有有效规则，按发布者、再按类型排序。 |

<a id="inboxpolicy_set"></a>

## `inbox.policy_set`

设置收件箱所有者为某个发布者和任务类型选定的信任模式（Loom 只负责存储，从不修改）。

`POST /v1/inbox.policy_set` · MCP `loom_inbox_policy_set` · 角色 `admin` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `inbox` | `str` | 必填 | 规则所属的收件箱；调用方必须是其所有者命名空间的管理员。 |
| `poster` | `str` | 必填 | 规则适用的对象：一个主体、一个 agent 标签，或用 `*` 表示所有发布者。 |
| `kind` | `str` | `'*'` | 规则适用的任务类型；`*` 表示所有类型。 |
| `mode` | `Literal['deny', 'review', 'auto']` | 必填 | `deny` 拒绝该发布（403），`review` 将其放入 `triage`，`auto` 将其放入 `todo`。 |
| `require_evidence` | `list[str]` | *(计算得出)* | 必须存在的简报字段（创建时的结构检查），例如 ["inputs.finding_id"]。 |
| `remove` | `bool` | `False` | 为 True 时删除该（poster，kind）规则，而不是设置它。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `policy` | `PolicyPayload \| None` | 已存储的规则；当 `remove` 删除了它时为 null。 |
| `removed` | `bool` | 规则已被删除时为 True。 |

<a id="inboxprincipals"></a>

## `inbox.principals`

Loom 在组织内已知的身份，是发布者选择器的数据来源。

`POST /v1/inbox.principals` · MCP `loom_inbox_principals` · 角色 `admin` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `inbox` | `str` | 必填 | 其发布者会被标记为 `listed` 的收件箱；如果名称未注册或不可读，则按 `namespace` 作答，且没有任何人被标记为 listed。 |
| `query` | `str` | `''` | 对 subject 和 label 做不区分大小写的子串匹配；"" 返回所有人。 |
| `limit` | `int` | `200` | 最多返回这么多个 principal，范围 1-500；`truncated` 表示还有更多匹配项。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `principals` | `list[Principal]` | 先列人员，再列服务账号，最后是其他类型，每类按 label 排序。 |
| `truncated` | `bool` | 匹配的 principal 数量超过 `limit` 时为 True。 |

<a id="inboxregister"></a>

## `inbox.register`

``namespace`` 是所属命名空间（调用方必须是其管理员）。

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

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 写入或读取的 agent；在操作允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `inbox` | `str` | 必填 | 收件箱名称，在 org 内唯一；注册已存在的名称会编辑其设置。 |
| `owner_agent` | `str` | 必填 | 处理该收件箱的 agent：未指定 `agent` 的拉取或认领将以它的身份认领。 |
| `description` | `str` | `''` | 随收件箱显示的自由文本；Loom 不会解释它。 |
| `posters` | `list[str]` | *（计算得出）* | 除所属命名空间的写入者外，允许投递任务的主体；此处的 agent 标签只允许不带令牌的调用方。 |
| `accept_disclosure` | `list[Literal['confidential', 'internal', 'public_ok']]` | *（计算得出）* | 任务要进入此处所能携带的 `disclosure` 级别；使用其他级别的创建或重新分配会被拒绝（422）。 |
| `default_lease_seconds` | `int` | `1800` | 调用未指定 `lease_seconds` 时，认领或心跳持有租约的秒数。 |
| `max_attempts` | `int` | `3` | 任务可达到的租约过期次数；超过后，清理程序会将其阻塞并等待人工处理，而不是退回 `todo`。 |
| `max_defers` | `int` | `5` | 任务可以推迟的次数；再次调用 `task.defer` 会将其阻塞并等待人工处理。 |
| `triage_escalate_after_seconds` | `int` | `14400` | 任务在 `triage` 中可等待的秒数，超过后清理程序会在其上记录一个 `triage_escalated` 事件。 |
| `webhook_url` | `str` | `''` | 以 POST 方式发送带签名的唤醒通知（事件类型和任务 id，绝不包含任务文本）的地址：公共主机上的 http(s) URL（每次投递时会再次检查）；"" 表示不发送。 |
| `webhook_secret_ref` | `str` | `''` | 保存 webhook 签名密钥的环境变量名称（不会被存储）：`LOOM_WEBHOOK_SECRET_<ORG>__<NAME>`，ORG 为 org id，其中 a-z 转为大写，数字保留，其他任何字节写作 `_` 加两位十六进制数字（`acme-corp` →… |
| `if_match_version` | `int \| None` | `None` | 本次编辑所依据的收件箱 `version`；当前版本不同则返回 409。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `inbox` | `InboxPayload` | 写入后的收件箱。 |
| `created` | `bool` | 本次调用注册了新收件箱时为 true；仅编辑设置时为 false。 |

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