AI智能体诊断框架：像医生一样给Agent看病，五分钟定位问题根因

你的Agent病了，但你不知道该挂什么科

做过智能体的人都有这种经历：搭好的Agent突然变蠢了，输出质量断崖式下降，但你完全说不清"它到底哪里出了问题"。

于是你开始瞎折腾——换个提示词试试，加个规则试试，重启一下试试。就像一个人发烧了，先吃感冒药，不好再吃退烧药，再不好去挂个中医。

这不是解决问题，这是在碰运气。

我花了大半年时间反复调试不同类型的智能体，踩了无数坑之后，总结出了一套结构化的诊断框架。这套框架的核心思想很简单：把智能体当成一个病人，按照"症状→系统→病因"的路径，系统化地定位问题。

本文不讲原理，不讲概念，直接给你一个五分钟诊断表，拿来就能用。

第一步：症状分类——你的Agent到底哪里不对劲

智能体出问题，无非三种表现：不该做的做了、该做的没做、做了但做得不对。

这三种症状对应着完全不同的诊断方向：

• 不该做的做了——幻觉、过度发挥、自行添加步骤、编造不存在的信息。这类问题的根因通常是提示词约束不足或上下文中混入了干扰信息。
• 该做的没做——漏步骤、跳过关键环节、对指令选择性忽略。根因多半是指令过长被模型截断、优先级不清晰，或者任务描述太笼统。
• 做了但做得不对——格式错误、内容偏差、逻辑混乱、前后矛盾。这是最难诊断的一类，因为它的病因横跨提示词、记忆、工具调用、模型能力等多个维度。

诊断口诀：先分症状，再查系统。症状类型决定了你要往哪个方向挖。

第二步：系统排查——四个子系统逐个检查

一个智能体由四个子系统组成：输入层、理解层、执行层、输出层。问题出在哪一层，修复方案就完全不同。

输入层：垃圾进，垃圾出

输入层的问题最容易定位，也最容易被忽略。

常见病因：

• 用户输入含歧义或信息缺失，Agent只能猜
• 系统提示词过长，关键指令被淹没在大量文本中
• 记忆文件中混入了过时或错误的信息
• 上下文窗口被无关历史对话占满

快速检查方法：把Agent最近三次出错的对话导出来，单独看输入部分。如果输入里就存在歧义、矛盾或信息缺失，那问题不在Agent的"脑子"上，而在"耳朵"上。

理解层：听懂了，但理解歪了

理解层的问题最隐蔽，因为Agent表面上似乎"懂了"，但实际执行的时候方向完全跑偏。

常见病因：

• 提示词中的关键词存在歧义（比如"整理"是分类还是归档？）
• 多个指令之间存在隐含冲突（一边说"简洁"一边要求"详尽"）
• 上下文中的前后指令互相覆盖

快速检查方法：问自己一个问题——"如果换一个完全不了解背景的人来看这条指令，他会怎么理解？"如果答案是"可能理解错"，那理解层就有嫌疑。

执行层：理解对了，但执行走样

执行层是工具调用和任务编排的环节，也是出Bug最多的地方。

常见病因：

• 工具选择错误（该用搜索的用了生成，该用读文件的用了写文件）
• 执行顺序不对（先写结果再读数据，逻辑颠倒）
• 中间结果没有校验，错误一步步放大（这就是幻觉放大效应的根源）
• 工具返回异常但Agent没有处理，继续用错误数据往下跑

快速检查方法：打开Agent的执行日志，找到出错那一次的工具调用链。看每一步的输入输出是否匹配预期。大概率你会发现某一步的输出已经是错的，但Agent没有发现，继续往下跑了。

输出层：做对了，但表达有问题

输出层的问题最"冤枉"——Agent内部处理没问题，但最终呈现给用户的结果不对。

常见病因：

• 输出格式要求不明确（要表格给了列表，要摘要给了全文）
• 语言风格不对（要专业报告给了口语化回答）
• 输出截断（内容太长被截断，关键信息丢失）

快速检查方法：对比Agent的中间输出和最终输出。如果中间结果是对的，最终结果有问题，那大概率是输出层的格式约束没到位。

第三步：病因定位——七张"病历卡"对照自查

经过症状分类和系统排查，你已经把问题范围缩小了。接下来用这七张"病历卡"做最后确认：

病历卡1：提示词臃肿症
特征：系统提示词超过2000字，Agent经常"忘掉"某些指令。
处方：把提示词分层——核心规则放最前面，可选规则放后面，低频规则按需注入。参考我之前写的功能蔓延那篇，该砍的砍掉。

病历卡2：记忆污染症
特征：Agent越用越"笨"，早期表现好的能力逐渐退化。
处方：定期清理和压缩记忆文件，建立记忆分层机制（短期记忆自动过期，长期记忆人工审核）。这个问题的深度分析可以看上下文污染那篇。

病历卡3：工具滥用症
特征：Agent疯狂调工具，一个简单任务调七八个接口，但产出很少。
处方：在提示词中设定工具调用的"预算"（如单任务最多调用3个工具），强制Agent先思考再动手。

病历卡4：决策疲劳症
特征：Agent在连续处理多个任务后，后面的任务质量明显下降。
处方：每处理完一个复杂任务后插入"重置"步骤，清除中间状态的累积影响。

病历卡5：语义漂移症
特征：长对话中，Agent对同一个词的理解逐渐偏离原意。
处方：在关键节点插入"理解确认"步骤，让Agent用自己的话复述理解，发现偏差立即纠正。关于这个问题，语义漂移那篇有更详细的分析。

病历卡6：静默故障症
特征：Agent看起来正常运行，实际输出内容是错的，但不报任何错误。
处方：给关键环节加校验步骤，不要信任Agent的"自我感觉"。每一步的输出都要有明确的验证条件。

病历卡7：人设崩塌症
特征：Agent的语气、风格、专业度在对话中逐渐跑偏。
处方：在人设文件的开头和结尾都放一句强化指令，并且在每次重要输出前触发一次人设校准。

一张图搞懂：诊断决策树

把上面的框架浓缩成一个决策树，你可以打印出来贴在工位上：

Agent表现异常？
├─ 做了不该做的 → 检查提示词约束 → 检查上下文干扰
├─ 没做该做的 → 检查指令长度 → 检查优先级 → 检查任务描述
├─ 做了但不准确 →
│ ├─ 输入层：检查用户输入和系统提示词
│ ├─ 理解层：检查指令歧义和冲突
│ ├─ 执行层：检查工具调用链和中间结果
│ └─ 输出层：检查格式约束和截断
└─ 时好时坏 → 检查记忆污染 → 检查语义漂移 → 检查上下文窗口

实战案例：一次五分钟诊断全过程

上个月我搭了一个自动写博客的智能体（就是你现在看到这个博客背后的系统）。有一天它突然开始输出重复内容——同一篇文章发两遍，而且第二遍的标题还变了。

按照诊断框架：

症状分类：做了不该做的（重复发布）。

系统排查：执行层有嫌疑。打开日志一看，发现问题出在发布接口的返回值处理上——接口返回了成功，但Agent没有正确记录"已发布"状态，导致下一轮判断时认为"还没发过"，于是又发了一遍。

病因定位：病历卡6（静默故障症）——发布成功了，Agent也继续运行了，但状态记录环节静默失败。

处方：在发布后加了一个状态校验步骤——发布完成后读取已发布列表，确认新文章确实在列表里，再标记为"已完成"。

修复耗时：5分钟。如果不用框架，我可能要花半小时猜。

三个核心理念

理念一：诊断先于治疗。大多数人在Agent出问题时第一反应是"改提示词"，这就像医生还没检查就开药。先搞清楚问题在哪一层，再决定怎么改。

理念二：可观测性大于一切。如果Agent出了问题你连日志都看不到，那任何诊断框架都是摆设。从搭Agent的第一天起，就要确保每一步操作都有日志、有中间状态可查。

理念三：同样的症状可能有不同的病因。"Agent输出不准确"这个症状，可能是因为提示词不够清晰，可能是因为模型能力不够，可能是因为工具返回了错误数据，可能是因为记忆里混入了脏数据。不要凭直觉猜，要按系统一层一层排查。

常见问题

问：这套框架适用于所有类型的智能体吗？
答：适用于所有基于大语言模型的智能体。无论你用的是GPT、Claude、豆包还是本地模型，这套"症状→系统→病因"的诊断逻辑都是通用的。差异只在于具体工具链不同。

问：怎么区分"模型本身能力不够"和"我的设计有问题"？
答：一个简单的判断方法——换一个更强大的模型测试同样的场景。如果问题消失了，那是模型能力不够；如果问题还在，那是你的设计有问题。大部分情况下，是设计问题。

问：诊断框架需要每次都完整走一遍吗？
答：不需要。熟练之后，你会在前两步（症状分类+系统排查）就能锁定80%的问题。七张病历卡是给你做交叉验证用的，不是强制流程。

总结

搭智能体不难，难的是维护。而维护的核心能力不是"写更多代码"，而是"快速定位问题"。

这套诊断框架的本质，是把一个模糊的"感觉Agent不对劲"，变成一个可操作的"我知道问题在哪一层、大概是哪个病因、应该从哪里下手"。

Agent不会自己看病，但你可以学会给它当医生。

当你能在五分钟内定位问题的时候，你就不再是"调提示词碰运气的人"了，而是"能系统化解决智能体问题的工程师"。

这个差距，就是业余和专业的分界线。