排查 MCP 访问、结果与不支持的任务
诊断 Off、Read-only、locked、ambiguous、no_match、pending 和 unknown 状态，并在产品不支持的边界停止或交接。
- 作者:
- Mqttable
- 更新:
本页目录7 个章节
加载中...
/docs/agent/troubleshooting
诊断 Off、Read-only、locked、ambiguous、no_match、pending 和 unknown 状态，并在产品不支持的边界停止或交接。
加载中...
解释失败任务前，先诊断当前实际连接的 Runtime。让 Agent 读取 Runtime info 并报告：
MCP 不报告桌面端版本，因此还要在 Mqttable 的 版本和运行时状态面板中核对 app version。复制的 URL、旧截图或上次会话都不能证明当前 Runtime identity。
如果缺少 Runtime identity、目标 Broker 或 entitlement，应在 capability search 或 mutation 前停止。不能根据源码或另一台机器猜测。
Mqttable 在设置 > MCP 中提供三个由用户控制的状态。
| UI 状态 | Runtime 行为 | 应对方式 |
|---|---|---|
| Off | /mcp endpoint 拒绝请求。本地客户端会收到 HTTP 403 和 MCP access is off。 | 在当前 Mqttable 中启用 MCP，再重新连接或只重试一次 read。 |
| Read-only | Read 仍可用。Mutable plan 返回 applyable: false、status: disabled 和 mutable_access_unavailable。 | 继续诊断，或请用户选择“允许变更”。绝不能通过其他 API 绕过。 |
| 允许变更 | Runtime info 报告 approved_changes，符合条件的 plan 可以创建和 Apply。 | Apply 前仍要核对精确目标、risk、validations 和 masked_diff。 |
Runtime 降级时，configured access 和 effective access 可能不同。应以 effective access 为准，并报告 degraded reason。不能把 Settings 选择状态当作 mutation 已经生效的证据。
未知业务操作只搜索一次，然后遵循 typed result。
| 状态 | 含义 | 安全的下一步 |
|---|---|---|
exact | 只有一个 typed capability 匹配。 | 读取这个精确 schema。 |
candidate | 返回一个可能匹配的 typed capability，但 summary 或 boundary 可能缩小了请求范围。 | 读取其 schema，确认它仍与所需操作一致。 |
ambiguous | 多个 typed capability 都可能匹配。 | 只有用户操作已经明确指向某个结果时才选择，否则先提问。不能仅凭相似度执行 mutation。 |
no_match | 没有 typed capability 匹配。fallback catalog 只是发现上下文，不是可执行 plan。 | 停止或交接。不要不断改写同义词，直到碰到一个看起来接近的操作。 |
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。
收到 Apply response 不等于 mutation 成功。应读取结构化状态，并遵循它给出的 recovery contract。
| 状态或字段 | 解释与处理 |
|---|---|
planned、applyable: true | 核对 expiry、target、preconditions、risk、validations、side effects 和 masked_diff。同一 Plan ID 最多 Apply 一次。 |
committed | 已报告 side effect。执行 Verify，并重新读取受影响 Resource。 |
state_matches_but_attribution_unproven | 当前状态与 plan 一致，但不能证明操作归因。必须保留这个边界。 |
reconcile_pending | 保存状态已变化，但 Runtime 同步仍待处理，常见于 Connection 已停止时。继续读取，直到所需终态可观察。 |
outcome_unknown 或 effect_possible | 不得重放 mutation。只执行 Verify，再做一次有界的权威读取。 |
带 no_effect_proven 的 failed | 只有 recovery contract 允许时，才修正经过校验的输入。 |
not_applicable | 未尝试 mutation，例如 schema、authorization 或 search 失败。 |
has_more: true 或 next cursor 非空 | 结果不完整。必须在同一有界 query context 中继续读取，才能声明完整性。 |
对于定时或持续运行的操作，pending、running、disconnecting、idle、completed 和 cancelled 表示生命周期中的不同阶段。应报告精确状态，并等待教程要求的终态。绝不能把 pending 改写成成功。
Compact surface 保持精简，typed Action、Resource 和 Workflow 则由 Registry 提供。
mqttable_runtime_info：读取 Runtime identity 和访问边界。mqttable_doctor：读取有界诊断，也可以执行显式 active probe。search_mqttable_capabilities：发现一个未知业务操作。get_mqttable_schema：读取一个精确 typed contract 和示例。execute_mqttable_read：运行 no-effect Action 或已注册 Workflow。read_mqttable_resource：读取一个有界 Resource URI。plan_mqttable_action：为一次 mutation 创建不可变 plan。apply_mqttable_plan：只 Apply 已审核的 Plan ID。verify_mqttable_plan：按该 Plan ID 重新读取状态。不要调用历史 business tool name。先发现 typed Action、读取 schema，再使用该 schema 指定的 compact tool。
遇到明确边界时应停止，不能虚构绕行路径：
Capability 处于 Pro-locked 时，不得从源码复制隐藏 schema，也不得靠推断拼接参数。应先获得 entitlement，再读取新暴露的 schema，并从头进行验证。
出现以下任一情况时，应停止并给用户精确交接：
no_match；masked_diff 不完整；交接信息应包括精确状态、最后一条安全证据、可能残留的对象，以及唯一允许的下一步。绝不能包含原始 secret，也不能鼓励重放结果不确定的 mutation。