/docs/agent/troubleshooting

排查 MCP 访问、结果与不支持的任务

诊断 MCP 启用、运行健康、locked、ambiguous、no_match、pending 和 unknown 状态，并在产品不支持的边界停止或交接。

本页目录7 个章节

加载中...

先确认当前 Runtime

解释失败任务前，先诊断当前实际连接的 Runtime。让 Agent 读取 Runtime info 并报告：

MCP 不报告桌面端版本，因此还要在 Mqttable 的 版本和运行时状态面板中核对 app version。复制的 URL、旧截图或上次会话都不能证明当前 Runtime identity。

如果缺少 Runtime identity、目标 Broker 或 entitlement，应在 capability search 或 mutation 前停止。不能根据源码或另一台机器猜测。

设置 > MCP 只有一个启用开关，与运行健康状态分开。

状态	Runtime 行为	应对方式
关闭	`/mcp` 拒绝请求，返回 HTTP 403 和 `MCP access is off`。	用户在当前 Mqttable 中启用 MCP。
启用且健康	`enabled: true`、`runtime_health: ready`，允许受支持的读写。	执行前明确目标和参数，检查可用的资源版本。
启用但变更服务不可用	`enabled: true`、`runtime_health: unavailable`，拒绝写入，可用诊断读取保留。	报告 `runtime_health_reason`，不得绕过失败门禁。

旧访问级别配置需要用户重新启用 MCP。开关开启不证明某次变更已执行，仍以操作结果为准。

未知业务操作只搜索一次，然后遵循 typed result。

状态	含义	安全的下一步
`exact`	只有一个 typed capability 匹配。	读取这个精确 schema。
`candidate`	返回一个可能匹配的 typed capability，但 summary 或 boundary 可能缩小了请求范围。	读取其 schema，确认它仍与所需操作一致。
`ambiguous`	多个 typed capability 都可能匹配。	只有用户操作已经明确指向某个结果时才选择，否则先提问。不能仅凭相似度执行 mutation。
`no_match`	没有 typed capability 匹配。fallback catalog 只是发现上下文，不代表执行授权。	停止或交接。不要不断改写同义词，直到碰到一个看起来接近的操作。
`locked`	Capability 存在，但当前 entitlement 不提供可执行 schema。	报告 `required_plan`、summary 和指定 fallback。Fallback 只能提供它本身的较窄结果，不能冒充等价能力。

Free 会话可以证明 Pro action 处于 locked，但不能证明 Pro workflow 执行成功。例如，draft-only PCAP Replay candidate 不会解锁 Replay execution，Free Trace 也不能代替 PCAP analysis。

执行时使用稳定的幂等键。响应超时不证明消息、订阅或故障没有发生。

effect_state 单独说明副作用没有发生、可能发生或已确认发生。用 operation ID 或原幂等键查询 operation.read。查不到记录或没有读取权限，都不等于没有执行过。

Compact surface 保持精简，typed Action、Resource 和 Workflow 则由 Registry 提供。

find_mqttable_capabilities：发现一个未知业务能力。
describe_mqttable_capability：读取一个精确 typed contract 和示例。
query_mqttable：运行 no-effect Action 或 Workflow、读取 Resource URI，或执行仅含 Action 的有界 batch。
execute_mqttable_action：执行一个已授权的有副作用 action，并提供持久防重。
diagnose_mqttable：读取 Mqttable 有界诊断，也可以执行显式 active probe。

已删除的 tool name 不是 alias。先发现 typed Action、读取契约，再使用该契约指定的当前 tool。

遇到明确边界时应停止，不能虚构绕行路径：

Capability 处于 Pro-locked 时，不得从源码复制隐藏 schema，也不得靠推断拼接参数。应先获得 entitlement，再读取新暴露的 schema，并从头进行验证。

出现以下任一情况时，应停止并给用户精确交接：

交接信息应包括精确状态、最后一条安全证据、可能残留的对象，以及唯一允许的下一步。绝不能包含原始 secret，也不能鼓励重放结果不确定的 mutation。