尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
inbox 操作
每个 inbox.* 操作接受和返回的确切字段。
每个操作在 HTTP 上都是 POST /v1/<op>,在 MCP 上对应工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,由令牌和 MCP 会话自动填充;对于单用户服务器上不带令牌的 HTTP 调用,会填入安装时的 org,适用于除 code.* 和 tracker.*(它们保留各自平面的值)之外的所有操作,而对于部分操作,其命名空间和 agent 也会自动填充;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。
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] |
可见的收件箱,按名称排序。 |
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] |
该收件箱的所有有效规则,按发布者、再按类型排序。 |
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。 |
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。 |
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。 |