Tool Catalog 与执行模型

MoleSignal 将 AI 可操作的产品能力建模为协议无关的 Tool Catalog。Mole Agent 与 Inbound MCP 共用 ToolSpec 契约和同一套服务端 Runtime，不在不同 Adapter 中重复实现业务逻辑。当前 Catalog 包含 190 个注册 Tool。每个 Tool 都声明稳定名称、Canonical description、输入与输出 Schema、所需 IAM 权限、风险等级、访问模式、Annotations 与允许暴露的 Surface。

产品级操作

Tool 表达查询日志、测试告警或更新一个 Dashboard Panel 等有界产品操作，而不是任意 HTTP 请求。

租户安全上下文

认证 Adapter 注入调用者与组织身份。user_id 和 org_id 不能选择执行租户。

渐进上下文

常用 Tool 固定可见，其他 Tool 仅在需要时搜索，控制模型上下文与 Token 消耗。

统一执行路径

权限、许可证、策略、超时、输出限制、幂等、审批、验证与审计都会在执行时再次强制检查。

Tool 颗粒度

良好的 MoleSignal Tool 只表达一个明确的运维意图，并返回一个有界结果。

一个 Tool 只执行一次原子读取、预检或变更。
list、get、create、update、delete、test、trigger、cancel 与 retry 分别建模。
暴露产品概念，不暴露原始 Route 或任意请求构造器。
返回适合模型处理与审计记录的结构化、有界结果。
凭证明文、二进制传输、原始 Intake、Shell 执行与浏览器控制不进入 Catalog。

这种颗粒度让 IAM 与 Tool Policy 可以控制具体操作，而不是为整组 HTTP Resource 提供宽泛权限。

Surface

每个 Runtime Surface 都有显式的 Tool exposure。

Surface	发现与执行方式
Mole Agent	常用 Tool，加上用于延迟发现内置 Tool 与已授权 Outbound MCP Tool 的 `tool_search → tools_call`。
Inbound MCP	常用只读与审批控制 Tool，加上 `tool_search → call_read_tool` 或 `call_managed_tool`。
Automation	默认不暴露内置 Tool；每个 Tool 必须显式加入 Automation Surface。

服务端在生成 Tool 列表和执行前都会检查 Surface exposure。绕过 tools/list 不能绕过该边界。

Inbound MCP 渐进发现

Inbound MCP 保持 tools/list 精简。授权后的响应可以包含：

7 个固定只读 Tool：query_logs、query_metrics、list_streams、 get_stream_schema、list_traces、get_trace 与 get_incident；
审批控制：list_agent_approvals、get_agent_approval 与 execute_agent_approval；
执行控制：list_agent_executions 与 get_agent_execution；
tool_search、call_read_tool 与 call_managed_tool。

IAM 与 Tool Policy 可以从列表中移除任意产品 Tool。

搜索已授权 Catalog

使用产品关键词或 Domain 调用 tool_search：

{
  "query": "status page incident",
  "limit": 10,
  "include_schema": true
}

结果只包含同时满足 Inbound MCP exposure、workspace Tool Policy 启用状态与凭证 IAM 授权的 Tool。请求 Schema 时，每个匹配项还会返回 Schema 与实际执行元数据。

执行读取或预检

将搜索到的名称与参数交给 call_read_tool：

{
  "name": "list_status_page_incidents",
  "arguments": {
    "status_page_id": "status-page-id",
    "lifecycle": "active"
  }
}

当 MCP 客户端声明 Tasks extension 时，可以将 as_task 设为 true，把读取转为持久任务，再使用 MCP Task 方法轮询、更新或取消。

执行受控变更

调用 call_managed_tool 时传入唯一幂等 Key：

{
  "name": "update_annotation",
  "arguments": {
    "annotation_id": "annotation-id",
    "text": "Deployment rollback started"
  },
  "idempotency_key": "8d7788d2-9b4e-44bd-bf35-61a5690f0064"
}

MoleSignal 会在创建审批或执行变更前，为当前认证 Principal 预占该 Key。重复相同请求会返回已保存结果或进行中状态；使用相同 Key 传入不同参数会被拒绝。

风险与执行策略

Tool 风险等级提供安全默认值，workspace Tool Policy 可以配置更严格的执行模式。

风险	默认模式	含义
L0	自动执行	有界只读操作。
L1	用户确认	低风险变更需要 MCP Host 确认，除非策略选择自动执行。
L2	单人审批	需要一名 MoleSignal 审批人。
L3	双人审批	需要两名 MoleSignal 审批人。
L4	禁用	高风险或破坏性远程操作默认不可用。

自动执行的受控变更仍会创建可审计的 Approval Record。确认模式可以使用 MCP 多轮输入；单人和双人审批模式会等待 MoleSignal 内的审核。达到所需审核数后，原请求方可以使用另一个 idempotency_key 调用 execute_agent_approval 完成操作。执行前，Runtime 会重新验证：

认证 Principal 与组织状态；
所需 IAM 权限与 Permission Mode；
许可证与功能可用性；
Surface exposure 与当前 Tool Policy；
输入 Schema、目标资源状态与风险；
超时、响应大小限制与幂等；
操作后验证与审计记录。

Catalog 覆盖范围

Catalog 覆盖适合 AI 调查与管理的安全产品操作。

Domain	代表能力
Logs、Metrics 与 Streams	查询遥测数据、检查 Schema 与设置、搜索相邻事件、探索指标 Label 或 Series。
Traces、APM、RUM 与 Profiles	检查 Trace、服务拓扑、Session、Error、Dependency、Flame Graph 与跨信号关联。
Alerts 与 Incidents	读取事件与值班状态；创建、更新、删除、测试或触发告警规则；确认或解决事件。
Dashboards、Reports 与 Annotations	管理 Dashboard、Folder、Panel、Annotation、Report Template、Schedule 与 Delivery。
Search Jobs 与 Saved Views	提交、检查、取消、重试或删除持久搜索，并管理 Saved View。
Pipelines、Functions、Enrichment 与 Connectors	检查定时运行、管理 Function、测试转换，并读取 Enrichment 或 Connector 元数据。
Synthetics 与 Status Pages	检查 Monitor 与结果、运行或暂停 Monitor，并管理 Status Page 生命周期与自动化。
Notifications	检查 Connector、Policy、Template 与 Delivery，并重试或确认投递。
IAM 与管理	读取用户、团队、角色、Capability、审计事件、Service Account 与 API Token 元数据；管理非 Secret 凭证状态。
Mole Agent 控制	检查 Investigation、Approval、Execution 与 Automation，并在授权后执行已批准操作。

使用 get_platform_capabilities 获取当前 Surface 过滤后的 Capability 摘要。使用 tool_search 获取当前已授权名称与 Schema，不要依赖静态列表。

身份与 Secret 边界

认证凭证提供调用者 user_id 与 org_id。
get_user_profile 与 get_user_preferences 的可选 target_user_id 只用于选择资源。读取其他成员需要 org.members.read，并验证目标属于当前组织。
读取和列表 Tool 只返回凭证元数据。
create_api_token 与 create_service_account 不在 Inbound MCP 上暴露，因为两者都会产生一次性明文；请在 Web UI 中创建。
已有 Service Account 与 API Token 仍可通过已授权的非 Secret Tool 列出、更新、启用、禁用、撤销或删除。

Catalog 明确排除登录、注册、密码重置、公开免登录 Route、原始 OTLP 或 Prometheus Intake、外部 Webhook、二进制上传下载、节点 Drain、Runtime Profiling、任意 HTTP、Shell 与浏览器执行。

MCP Resources、Prompts 与 Tasks

Inbound MCP 还会暴露经过 IAM 过滤的平台 Capability、Tool Catalog、Approval、Execution、 Search Job 与 Stream Schema Resource。内置、组织级与当前用户的 Mole Agent Prompt 可以通过 prompts/list 和 prompts/get 获取。长时间读取可以作为 MCP Task 执行。协商的 MCP 协议版本支持时，还可以使用进度通知、Resource 订阅与 Catalog 变更通知。

接入 MCP 客户端

启用端点，并通过 OAuth 2.1 或 API Token 建立连接。

Mole Agent

从内置运维智能体使用同一套受控 Catalog。

快速上手

观察

可靠性

AI 运维

数据

协作

管理

部署与运维

Tool Catalog 与执行模型

产品级操作

租户安全上下文

渐进上下文

统一执行路径

Tool 颗粒度

Surface

Inbound MCP 渐进发现

搜索已授权 Catalog

执行读取或预检

执行受控变更

风险与执行策略

Catalog 覆盖范围

身份与 Secret 边界

MCP Resources、Prompts 与 Tasks

接入 MCP 客户端

Mole Agent

产品级操作

租户安全上下文

渐进上下文

统一执行路径

​Tool 颗粒度

​Surface

​Inbound MCP 渐进发现

​搜索已授权 Catalog

​执行读取或预检

​执行受控变更

​风险与执行策略

​Catalog 覆盖范围

​身份与 Secret 边界

​MCP Resources、Prompts 与 Tasks

接入 MCP 客户端

Mole Agent

Tool 颗粒度

Surface

Inbound MCP 渐进发现

搜索已授权 Catalog

执行读取或预检

执行受控变更

风险与执行策略

Catalog 覆盖范围

身份与 Secret 边界

MCP Resources、Prompts 与 Tasks