附录 A 排障案例集
来自《AI Agent 学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图
按章收录具体故障。每条写现象、根因(原文没给根因的写排查方向)和教训,正文只留规律并指向这里。
A.1 第 1 章 Agent 核心循环
A.1.1 Pi 一直“思考”却一句话不说
- 现象:Agent 长时间只显示“思考中”,没有正文。
- 排查方向:先分清五种情况:模型还没出正文、整轮只有 toolCall、工具仍在执行、UI 没渲染、任务已被中止。
- 教训:查看真实事件序列和终态,不要把消息显示问题误判成模型推理慢。
A.1.2 pi-goal 自动续跑重复工具结果,400 一直重试
- 现象:自动续跑后请求持续返回 400,并且一直在重试。
- 根因:自动续跑把同一个 toolResult 重复写进消息历史,触发确定性的 Duplicate function_call_output 400。这是无效协议,不是瞬时网络失败。
- 教训:坏历史要先止损:停止循环、备份上下文、恢复合法的 callId 配对,必要时开新会话凭交接继续,不要反复重放坏请求。
A.3 第 3 章 Tool、Skill、MCP
A.3.1 MCP 一个方法 -32601,文档检索仍可用
- 现象:2026-09-19 核对
openaiDeveloperDocs接入时,resources/list返回-32601: Method not found。 - 根因:该服务没有实现资源列表方法,但工具能力正常。随后通过工具发现加载
search_openai_docs、fetch_openai_doc,文档检索仍能正常调用。 - 教训:按能力分别判断,先确认服务声明了哪些工具或资源,再验证对应调用;不能用一个未实现的方法给整项服务判故障。
- 来源:旧库
90-归档/20-个人/20-草稿箱/AI规范优化收件箱-20260923-最终封存.md第 645—650 行。这是当时的接入记录,不代表当前工具名称或客户端流程始终不变。
A.3.2 本机 Qwen“说执行了”但没有真的执行
- 现象:让模型运行
netstat,有的回合直接猜出“eth0”,有的只贴了一段 Bash 代码块。 - 根因:JSONL 里没有
toolCall,模型并没有调用工具;换成固定字符串的echo对照,才看见真实的toolCall和对应的toolResult。 - 教训:评测工具能力要检查调用 ID、参数、退出状态和结果。这只是 2026-08 的几场小样本,不代表新版模型的通用成功率。
A.3.3 工具结果消息类型漏认、重复送出
- 现象:模型发了 Tool Call 却拿不到返回;另一个 Pi 长任务持续收到确定性的 400。
- 根因:旧 Codex 中转只认
custom_tool_call_output,漏了桌面端的function_call_output;Pi 长任务则把相同call_id的结果重复送出。 - 教训:优先校验“一次调用、一次结果、正确配对”;协议历史损坏时先停自动重试,不要把这种 400 归类为网络波动。
A.3.4 旧 Hook 卡片里的规则互相矛盾
- 现象:同一张《CC-Hooks钩子》一边写“allow 不能绕过 deny/ask”,一边写“allow 绕过权限系统直接执行”。
- 根因:两句不能同时成立。2026-10-22 查到 Claude Code 官方说明:
allow可以跳过相应的权限提示,但 deny/ask 规则仍会评估;Hook 改写工具输入后,权限判断针对改写后的输入。 - 教训:旧笔记冲突时以官方当前文档为准。教学示例里
返回非 None 就拦截是它自己的回调约定,不能代替真实产品的 JSON 协议。
A.3.5 VPN fake-IP 触发 SSRF 拦截
- 现象:搜索摘要拿到了,原文抓取却被 SSRF 防护拒绝。
- 根因:VPN 的 fake-IP 可能把公网域名映射成安全工具认为是保留或内部的地址。
- 教训:先核对 DNS、代理模式和实际目的地址,保留安全边界;搜索摘要成功不能冒充抓到了官方原文。
A.3.6 Skill 加载失败的三种原因
- 现象:Skill 文件在,却没有生效或行为异常。
- 根因:有一次 YAML
description里的内层引号让整个 Skill 解析失败;另一次两个有效目录里有同名 Skill,最终加载哪个由配置顺序决定;还有一次已安装的 Extension 又用-e启动,导致工具重复注册。 - 教训:按“文件语法 → 实际加载胜出的路径 → 是否进入可见集 → 实际选用与执行”逐层查。
A.4 第 4 章 Prompt 与模型调用
A.4.1 AIHOT 2153 条处理失败,实为推理吃光输出预算
- 现象:AIHOT 有 2153 条处理失败,JSON parser 报“没有 JSON”,看起来像模型不会输出 JSON。
- 根因:一次模型把 1024 的输出预算全部用于推理,正文为空;“没有 JSON”只是下游现象。
- 教训:解析失败先看原始 content、reasoning_tokens、output_tokens 和停止原因。关闭思考参数是否有效,要按具体 provider 实测,不能跨模型照抄。
A.4.2 档位没传对、消息太多报 400
- 现象:旧 Pi 选 Medium 思考,思考占比却异常低;另一次第三方 DeepSeek 通道在约 800 条历史消息时报 400。
- 根因:前者是兼容层没按预期传档位。后者缩短消息数后改善,但错误里的
512 candidates不能直接理解为所有模型最多 512 条消息。 - 教训:界面档位、实际下发参数和供应商限制分开验证,切通道前保留同一请求的完整证据。
A.4.3 Codex Provider 配对了却一直 401
- 现象:Provider 已经配对,请求仍然一直 401。
- 根因:多个 provider 共用 OPENAI_API_KEY,后配置的工具覆写了前一个通道的值,请求拿错了认证值。
- 教训:每个 provider 用独立变量;跨客户端同步时,不能把取值命令当成 Key 字符串写进磁盘。
A.5 第 5 章 Context、Memory 与 RAG
A.5.1 多模态会话压缩后切到纯文本模型报 400
- 现象:多模态会话做完 compact,切换到纯文本模型后,接口返回不支持该输入类型的 400。
- 根因:compact 之后不一定清掉了所有图像内容,真实历史消息里仍有 image/file blocks。
- 教训:切换前检查真实历史消息;必要时开一个新的纯文本会话,交接可复用的结论。
A.5.2 33 万 Token 未满窗口,却报“最多 512 candidates”
- 现象:上下文只有约 33 万 Token,还没到窗口上限,模型路由就报 candidates 上限的 400。
- 根因:模型支持的上下文 Token 上限,不等于上游路由对消息条数、路径展开或请求候选数没有别的限制。
- 教训:先用缩减输入、多次重放、改变消息数量来分离原因,不能只凭错误文字猜是文件路径问题。
A.5.3 “保存 100 条聊天历史”只是屏幕上见过的 100 条
- 现象:OCR/屏幕助手声称记住了最近 100 条聊天。
- 根因:它只可能记住实际看见并识别出的 100 条,不能推断它能读取整个聊天数据库;头像、昵称过滤的阈值太粗,还会漏掉对方的消息。
- 教训:检验双方消息的召回率、滚动造成的重复和跨会话范围。
A.6 第 6 章 服务化与多 Agent 协作
A.6.1 云端模型能用,Mac 离线后机器人仍收不到消息
- 现象:模型在云端,能正常调用,但 Mac 关机后本地 Bot 收不到消息。
- 根因:消息入口和执行进程仍在本机,换了云端模型并没有把它们搬走。
- 教训:沿“消息入口 → 执行进程 → 模型 → 回复通道”检查每一环的运行位置;目标是离线可用,就要把关键的常驻环节放到常在线环境,而不是只换模型。
A.6.2 生图页面恢复任务后永远转圈
- 现象:历史生图页面重新打开后,一直处于 pending 状态轮询。
- 根因:页面从浏览器本地存储恢复了任务 ID,但服务端已经没有这个任务;前端只认 pending,于是永远轮询。
- 教训:设过期和失败终态、总时限和重试上限,给出重新提交或查询的入口。“每 3 秒、最多 30 次”是旧业务参数,不是所有异步任务的固定标准。
A.6.3 任务已执行,后置评分失败却被 Snapshot 归档
- 现象:任务已经派发执行,后置评分失败后,Snapshot 把它改回 backlog 或直接不显示。
- 根因:评分结果和执行状态混在一起,评分异常覆盖了执行事实;旧的 blocked 记录还可能吞掉真实的完成事件。
- 教训:派发、评分、执行、终态各自保留事实,评分异常单列,按 runId 更新后续状态。
A.7 第 7 章 可观测性与评估
A.7.1 “新 Prompt 不生效”实为走了旧分支
- 现象:改了 Prompt,线上表现没有变化。
- 根因:一次业务调用传错了路由参数,静默走到了旧分支;同时短文本还可能命中直接返回的捷径,模型调用根本没有发生。
- 教训:先核对实际请求参数、匹配的分支和快捷返回条件,再对照 Trace 的请求 ID 和时间窗口。
A.7.2 业务错误被统一记成 LLM ERROR
- 现象:日志显示 LLM ERROR,但 LLM 调用其实已经成功。
- 根因:后面的解析、数据库或下游接口失败了,代码却把整段放在同一个
try/except里,最后统一打成 LLM ERROR。 - 教训:按调用、解析、业务判断、下游消费拆开观察边界,在每个 Observation 里写明状态和原因。
A.7.3 管道跑通了,任务却没完成
- 现象:旧 project-intelligence 已经跑通采集、候选分发、Hermes 执行和结果导入。
- 根因:实际任务两次都在 40 轮执行预算内没通过测试验收。E2E 连通不等于问题解决。随后另一次学生端学习计划的修复产生了 PR,但“有 PR”和“已发布给真实用户”仍是两道门槛。
- 教训:复现、执行、测试、审查、最终效果分别留证据,不把管道连通写成任务完成。
A.7.4 代码检查通过,手机页面仍有黑色遮挡
- 现象:Workbench 代码检查全部通过,手机页面上却出现黑色遮挡。
- 根因:检查只覆盖了代码层面,没有在真实视口里看过页面。
- 教训:UI 问题必须在真实视口截图和交互中验证,不能让用户替 Agent 做基础自测。
A.7.5 rpiv-todo 测试把超时中断算成模型失败
- 现象:测试把“没有标 completed”记为模型失败。
- 根因:测试端超时中断了任务。这不证明模型在时间足够时必然会忘记收尾。
- 教训:记录 Abort/Timeout/Finish 等真实终止原因,再判断是谁的问题。
A.7.6 英语老师能回文字,却始终不发语音
- 现象:英语老师 Agent 能做文字纠错,但从不发语音;提示词里写了“必须调用工具”。
- 排查方向:按顺序查 TTS schema 是否传给了模型 → 是否有真实的结构化 toolCall → 执行器是否产出了媒体 → 客户端是否收到可播放的语音。
- 教训:只在回答里写出工具调用的文本不算调用,不能先认定语音服务故障。
A.7.7 评测平台显示调高推理反而变差
- 现象:在评测平台里,同一模型调高推理强度,准确率反而下降、平均耗时反而变短。
- 根因方向:平台走代理模型,实际请求的参数不一定是界面上选的。改为直连官方 API 复测后,同一模型关推理 76%、开高推理 92%,结论相反。
- 教训:评测结果反常时,先核对实际发出的请求和参数,不要直接相信平台汇总。详见提示词自动优化。
A.8 第 8 章 自进化与成本
A.8.1 底栏 CH0.0% 被误认成命令清空了缓存
- 现象:2026-08-30 的截图里,工具正在执行
pi list; jq ...,底栏显示CH0.0%。 - 根因:底栏对应的是生成这次工具调用的上一轮模型请求;工具本身还没触发下一轮请求,不能因为它显示在旁边,就说是这条命令把缓存清零了。
- 教训:按“用户消息 → 模型请求 → 工具执行 → 下一次模型请求”对齐指标,再比较每次请求的前缀和用量。
- 来源:旧库
90-归档/20-个人/20-草稿箱/AI规范优化收件箱-已归档.md第 1088—1092 行。底栏行为只对应当时的 Pi 环境,不推定所有客户端都这样显示。
A.8.2 Codex Fast 模式没有提速
- 现象:2026-07-31 的记录里,保持同一组任务、模型和推理强度,两组单次 A/B 都没看到 Fast 提速:Standard/Fast 分别为 155/157 秒、33/37 秒。
- 根因:服务端响应的
service_tier仍是默认档,说明当时经过特定代理的链路并没有证明 Fast 生效。 - 教训:看真实响应字段,不只看本地开关;这不能断言 Fast 模式对所有用户都无效。
A.9 第 9 章 源码阅读
A.9.1 Codegraph 的“3 个调用方”只有 1 个是产品调用
- 现象:查账单分类函数时,Codegraph 显示 3 个调用方。
- 根因:三条关联里混入了文件级和测试边,点进源码才确认产品调用点只有一处;另有一个离线账单导入脚本维护着独立的分类实现。
- 教训:区分业务入口、函数级调用边、脚本和测试边,确认是否故意分离两套逻辑,再决定改几个文件。