工具调用排障手册：四层定位法附日志样例

AI 接了工具之后，失败是常态。有效率的做法不是换模型，而是先定位失败在哪一层。本文给出四层定位法与可直接抄的日志格式。

一、四层模型

层	症状	处理方向
权限	401、无权限、权限不足	查 Key 与鉴权头
参数	必填缺失、类型不符、URL 无效	查任务句与调用参数
服务	超时、限流、上游 5xx	退避重试，别连打
内容	拿到正文但结论错	抽查来源、核对数字

顺序很重要：先权限、再参数、后服务、最后内容。反过来查通常白花半小时。

二、日志样例

json 复制代码

{
  "step": 3,
    "tool": "web_search",
      "args": { "query": "...", "limit": 5 },
        "ok": true,
          "latency_ms": 812,
            "result_len": 4210
            }
            ```
有这份记录，你能回答三个问题：有没有真的调用、参数是什么、回包多大。

## 三、四种典型形态与动作

### 1. 对话很流畅，调用记录为零

说明工具没暴露，或任务句太像闲聊。检查 `tools/list` 与权限。

### 2. 调用记录正常，结果为空

多为无效 URL 或反爬。换来源，别在原地重试。

### 3. 积分/额度异常消耗

在循环重试。先停，再查是谁在打。

### 4. 结果"看起来对"

最危险的一类。抽查链接、核对数字与单位，缺值是否被猜。

## 四、值班手册模板

1. 现象：____
2. 层判定：权限 / 参数 / 服务 / 内容
3. 证据：调用记录第 N 条 + 错误码
4. 动作：改条件 / 缩权限 / 退避 / 换来源
5. 复盘：下次如何提前发现

## 五、报错反馈的正确姿势

带客户端版本、工具名、打码后的错误文本去官方 Issues。**不要贴完整请求头**------那里面可能有凭证。

## 小结

排障能力的上限，取决于你能否把失败分类。分类固定了，处理动作就固定了。
## 六、把排障前移到设计阶段

多数失败在设计时就埋下了，三个前移动作最有效：

1. **任务句写约束**：时间范围、条数、必须带 URL。约束越具体，参数类失败越少。
2. **权限按用途分**：权限层失败在接入当天就能暴露，不要等到线上。
3. **给重能力设上限**：服务类失败（限流）最怕连打，配额本身就是刹车。

## 七、复盘模板

时间：____

任务：____

现象：____

层判定：____

证据：调用记录第 N 条 / 错误码 ____

根因：____

改进：____（写进说明书或权限配置）

复制代码

复盘的目的不是找谁的错，而是让下一次的停止更快。