# Agent 报错时先读什么：状态、约定与重试边界

一次失败的 Agent 调用只说明某个环节没有按约定完成，不说明牌阵或命盘本身有问题。本文用一张分诊表，教你先看状态、再核对输入字段与计算约定，最后才决定重试、改输入还是停下。

Updated: 2026-11-04 · Wenbu AI-assisted editorial

先读终止状态，再读错误消息，最后才看内容。MCP 的成功结果会声明 outputSchema 并返回 structuredContent，所以第一步是检查 isError；REST 的错误带有稳定的 code 和可读消息，422 通常指字段或时刻无效，429 指短时限流或 AI 额度不足。agent 命令则要看 done 事件的 status：complete 表示本回合完成，waiting 表示还需用户补充，limited 表示预算已用完；error 或没有终止事件的断流都不算完成，已收到的内容可以保留，是否重试由用户决定。判断顺序是：状态是否成功 → 输入字段是否落在约定范围内 → 这次失败是否触及随机抽取或计次。只有确认输入有误才改输入；只有确认是限流才退避；AI 已开始的请求即使失败也可能计次，不要自动重试。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

- 先看终止状态与 isError，再看错误消息，最后才评价内容质量。

- 422 类错误先核对字段与时刻，429 类错误先退避，两者不要混为一谈。

- 断流与 error 都不是完成；已收到的内容可以保留，重试由用户决定。

- 随机抽取的塔罗与起卦结果应保留，重抽是新的抽取，不是修复。

- AI 已开始的请求即使失败也可能计次，不要写自动重试循环。

## 一次失败调用的分诊流程

1. **读终止状态** — MCP 先看 isError；agent 命令看 done 事件的 status 是否为 complete、waiting、limited 或 error。

2. **读错误消息** — REST 错误带有稳定的 code 和可读消息；422 指向字段或时刻，429 指向限流或额度不足。

3. **核对输入约定** — 日期范围、时区、换日规则、六爻取值、塔罗张数与紫微输入，逐项对照公开约定。

4. **评估计次风险** — AI 已开始的请求即使失败也可能计次，不要自动重试；纯计算工具修正输入后可重发。

5. **决定动作并如实告知** — 改输入、退避等待、请用户补充，或保留已收到内容并停下；不承诺额度恢复时间。

从终止状态出发，依次判断协议层、输入层与计次风险，最后才决定重试、改输入还是停下。每一步只使用文档明确写出的信号，不引入未声明的错误码或重试策略。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

## 先分清三种“失败”：协议失败、输入失败、内容不理想

Agent 调用失败时，最容易犯的错是把三种情况混在一起：协议层没有返回成功、输入没有落在约定范围内、以及结果返回了但读起来不满意。前两种是工程问题，第三种是解释问题。MCP 为成功结果声明 outputSchema 并返回 structuredContent，所以先检查 isError 就能把协议层的问题单独拎出来；REST 接口的成功结果是 JSON，错误则包含稳定的 code 和用户可读消息，这两条信息足以区分“没成功”和“成功了但我不喜欢”。

内容不理想不属于报错。塔罗与在线起卦由程序随机抽取，页面会保留原始结果；计算能按约定复现，不代表解释已经得到科学验证。因此当牌面或卦象与预期不符时，正确的动作是保留结果并重新组织问题，而不是把它当作一次失败调用去重试。把“结果不合心意”写进错误处理逻辑，会让重试变成对随机结果的反复索取。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · calculation conventions](https://wenbu.app/methodology/)

## 输入字段：422 之前先自查的四件事

REST 的 422 通常表示字段或时刻无效，所以在改代码之前，先按约定逐项核对输入。八字需要 1901 至 2099 年的公历日期、出生地钟表时间，以及 IANA 时区名称或明确的 UTC 偏移；省略时区会回落到 Asia/Shanghai 并返回警告，这属于“能跑但需注意”，不是报错。日柱默认 00:00 换日，也可选 23:00 子初换日；出生时间未知时不生成时柱，年、月柱以当地中午暂定，交节日会提示不确定性。

第二组要核对的是工具自身的参数形状。六爻每爻取 6、7、8 或 9，六爻自下而上排列，6 与 9 是动爻；塔罗只接受 1 张或 3 张，并从 78 张牌中不放回抽取。紫微输入出生地公历日期与已知钟表时间，不自动换算时区或校正太阳时。把这些字段当作契约来读，很多“调用失败”其实在发出请求前就能被发现，也就不必消耗一次可能计次的请求。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · calculation conventions](https://wenbu.app/methodology/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

## 限流与计次：429 之后该做什么、不该假设什么

接口每个网络每分钟有请求限制，遇到 429 请退避；429 表示短时限流或 AI 额度不足，具体是哪一种要读错误消息。文档没有给出重置时间、退避曲线或重试次数，所以不要凭空写“等 60 秒再试三次”这类策略，也不要向读者承诺额度何时恢复。能确定的是：先读消息，再决定是等待还是停下，并把这次失败如实告诉用户。

更需要注意的是 AI 计次。AI 已开始的请求即使失败也可能计次，文档明确要求不要自动重试。这条规则改变了错误处理的默认方向：对纯计算工具，输入修正后重发是合理的；对已经进入 AI 阶段的请求，重发可能重复消耗额度，应由用户确认。至于 MCP 计算、日签与资料阅读，公开说明指出它们不调用模型，因此不应把它们和 AI 请求的计次规则混为一谈。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

## 断流、waiting 与 limited：把“没完成”说准确

agent 命令输出逐行 JSON 事件，最后检查 done 事件的 status：complete 表示本回合完成，waiting 表示还需用户补充，limited 表示预算已用完。error 或没有终止事件的断流都不是完成；已收到的内容可以保留，重试需由用户决定。这里的关键是把四种状态分开表述：waiting 不是失败，而是缺信息；limited 不是故障，而是预算边界；断流不是空结果，而是传输中断。

因此，面向读者的措辞应当精确。说“这次没有完成，已收到部分内容，是否继续由你决定”，比说“服务出错请重试”更诚实，也更符合文档。若状态是 waiting，正确动作是补上缺失的上下文，例如用户愿意分享的那部分资料；若状态是 limited，正确动作是说明预算已用完，而不是换个说法再发一次。断流时保留已收到的内容，也避免让用户误以为什么都没发生。

[Wenbu · agent integrations](https://wenbu.app/agents/)

## 五类 Agent 结果的分诊表

| 结果类型 | 先查什么 | 可以得出什么 | 不要据此断定 |
| --- | --- | --- | --- |
| 字段无效（422 类） | 错误消息指向的字段；日期范围、时区、换日规则、六爻取值、塔罗张数 | 这次请求的输入没有落在公开约定内 | 牌阵或命盘本身有问题，或工具不可用 |
| 限流或额度不足（429 类） | 错误消息区分短时限流与 AI 额度不足；当前是否已进入 AI 阶段 | 需要退避或停下，具体策略以消息为准 | 额度何时恢复、应重试几次；文档未给出这些数字 |
| 流中断（无终止事件） | 是否收到 done 事件；已收到的内容是否完整 | 本回合没有完成，已收到内容可保留 | 结果是空的，或必须立刻重发 |
| 预算受限（limited） | done 事件的 status 与用户是否愿意继续 | 本回合预算已用完，是否继续由用户决定 | 服务故障，或换个措辞就能绕过 |
| 成功但内容为空或不理想 | isError 与 structuredContent；输入是否完整、问题是否清楚 | 调用在协议层成功，问题出在解释或提问 | 随机抽取出错，或需要重抽直到满意 |

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

## 假设案例：一次“没返回解读”的塔罗调用

以下为虚构情境，用于演示分诊顺序，不涉及任何真实用户资料，也不是实际计算出的牌阵。假设一位读者用 Agent 请求三张塔罗牌并附解读，界面只显示“出错了”，没有牌面。

1. 第一步，先看终止信号而不是内容：如果是 MCP 调用，检查 isError 与是否返回 structuredContent；如果是 agent 命令，检查有没有 done 事件以及 status 的值。没有终止事件就按断流处理，不当作空结果。

2. 第二步，读错误消息。若消息指向字段，就核对张数是否为 1 或 3、是否误传了其他参数；若消息指向限流或额度，就按 429 处理并退避，不自行设定重试次数。

3. 第三步，判断是否已进入 AI 阶段。若请求已开始生成解读，即使失败也可能计次，此时不自动重发，而是把已收到的内容与状态告诉读者，由读者决定是否继续。

4. 第四步，若调用其实成功、只是解读为空或不合预期，则保留返回的牌面，重新组织问题或补充上下文，而不是重抽。重抽是新的随机抽取，可能碰巧重复某张牌，但不能按需复现上一次结果。

这个案例的结论不是“服务坏了”，而是“先确认是哪一层没完成”。协议层失败就修请求；输入层失败就改字段；计次风险存在就交给用户决定；内容不理想就保留结果、改问题。四种动作对应四种证据，不能互相替代。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json) · [Wenbu · calculation conventions](https://wenbu.app/methodology/)

## FAQ

### MCP 调用返回了内容，但我不确定它算不算成功，怎么办？

先检查 isError，再看是否返回了声明 outputSchema 的 structuredContent。MCP 为成功结果声明 outputSchema 并同时返回 structuredContent 与文本 JSON；先检查 isError 是文档给出的顺序。若 isError 为真，内容只是错误信息，不应拿来解读。

[Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

### 遇到 429，是不是等一会儿自动重试就好？

文档只说接口每个网络每分钟有请求限制、遇到 429 请退避，并提示 429 可能是短时限流或 AI 额度不足，需要读错误消息。文档没有给出重置时间或重试次数，所以不要写死等待时长；若请求已进入 AI 阶段，失败也可能计次，更不应自动重试。

[Wenbu · agent integrations](https://wenbu.app/agents/)

### Agent 说“没完成”，和报错是一回事吗？

不完全一样。done 事件的 status 有三个取值：complete、waiting 和 limited。只有 complete 表示本回合完成；waiting 表示还需用户补充，limited 表示预算已用完，两者都不是完成。error 或没有终止事件的断流同样不是完成。把 waiting 说成故障会误导用户去重试，而正确动作是补充上下文。

[Wenbu · agent integrations](https://wenbu.app/agents/)

### 牌面不合心意，可以重抽到满意为止吗？

塔罗从 78 张牌中等概率抽取，同一次抽取不会重复，结果应保留以便追问。重抽是一次新的随机过程，可能碰巧重复某张牌，但不能按需复现上一次结果。把重抽当作“修复”会掩盖真正的问题：通常是提问方式或上下文需要调整。

[Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json) · [Wenbu · calculation conventions](https://wenbu.app/methodology/)

## Glossary

- **isError**: MCP 结果中用于标记本次调用是否出错的字段。文档建议先检查它，再读取 structuredContent 或文本 JSON。 [Wenbu · agent integrations](https://wenbu.app/agents/)

- **structuredContent**: MCP 成功结果中与 outputSchema 配套返回的结构化内容，便于宿主按字段读取，而不是从自由文本里猜。 [Wenbu · agent integrations](https://wenbu.app/agents/) · [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

- **done 事件**: agent 命令逐行 JSON 输出中的终止事件，其 status 为 complete、waiting 或 limited 时才表示本回合有明确结局。 [Wenbu · agent integrations](https://wenbu.app/agents/)

- **退避**: 遇到 429 时先等待再决定是否重发。文档要求退避，但未给出具体等待时长或重试次数。 [Wenbu · agent integrations](https://wenbu.app/agents/)

## Evidence notes

- MCP 的成功结果会声明 outputSchema 并返回 structuredContent，因此应先检查 isError 再读内容。 — “先检查 isError” (fact); [Wenbu · agent integrations](https://wenbu.app/agents/)

- REST 错误带有稳定的 code 和可读消息，422 与 429 指向不同的排查方向。 — “错误包含稳定的 code 和用户可读消息” (fact); [Wenbu · agent integrations](https://wenbu.app/agents/)

- 塔罗抽取是明确记录的随机过程，结果应保留而不是为得到某个答案重抽。 — “Keep the returned cards for follow-up” (editorial); [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json)

## Sources

- [Wenbu · agent integrations](https://wenbu.app/agents/) — Current first-party product documentation; fetched 2026-11-04T01:00:34.845Z; complete response

- [Wenbu · versioned public capabilities](https://wenbu.app/capabilities.json) — First-party current tool, convention and privacy contract; not external endorsement or predictive validation; fetched 2026-11-04T01:00:34.853Z; complete response

- [Wenbu · calculation conventions](https://wenbu.app/methodology/) — First-party implementation; not evidence of predictive accuracy; fetched 2026-11-04T01:00:34.850Z; complete response

[运行 CLI doctor 检查连接与版本](https://wenbu.app/agent/)