AI Agent 出问题时，不要只看最终回答：一次请求级调试的思路
这两年 AI 编程工具变化很快。
从 Copilot 式的代码补全，到 Claude Code、Codex、OpenCode、Cursor、Cline 这类 Agent 工具，AI 已经不只是“帮你补几行代码”了。它可以读项目、改文件、跑命令、调用工具、分析报错，然后继续下一轮。
但 Agent 越像一个“会干活的人”，问题也越明显：
它出错的时候，你很难判断它到底错在哪里。
很多人遇到 AI 编程工具跑偏时，第一反应是改 prompt。
比如：
你要更认真一点。
不要偷懒。
必须先读代码再修改。
不要乱改无关文件。
这些提示有时有用，但更多时候只是把问题往后推。
因为真正的问题可能根本不在你写给它的那句话里，而在它实际发给模型的完整请求里。
为什么只看最终回答不够？
一个 AI Agent 完成任务，通常不是一次请求结束。
它的流程更像这样：
用户提出任务
-> 模型收到 system prompt、上下文、工具列表
-> 模型决定调用某个工具
-> 本地执行工具，比如读文件、搜索代码、运行命令
-> 工具结果再进入下一轮模型请求
-> 模型继续判断
-> 直到给出最终回答或修改代码
我们在终端或编辑器里看到的，通常只是这个过程的一小部分。
最终回答只能告诉你“它做了什么”，但很难告诉你“它为什么这么做”。
比如下面这些问题，只看最终回答基本看不出来：
- 它到底有没有看到关键文件？
- 它看到的是完整上下文，还是被截断后的上下文？
- system prompt 里有没有某条规则影响了它？
- 工具 schema 是不是描述不清，导致它选错工具？
- tool result 有没有进入下一轮？
- 哪一轮开始 token 暴涨？
- provider 返回的 400 到底是模型问题，还是请求格式问题？
- 它是不是每一轮都重复带入了大量无效上下文？
这些都属于“请求级问题”。
AI Agent 的常见问题，其实可以分层看
我现在更倾向于把 AI Agent 的问题分成几层，而不是笼统地说“模型不行”。
第一层：模型没有看到该看的东西
这是最常见的问题之一。
你以为 Agent 已经读了某个文件，但实际发给模型的请求里没有那段内容。
或者它读过，但后续请求里没有保留。
于是模型只能基于不完整上下文做判断，结果自然不稳定。
这种时候继续强调“请仔细阅读代码”没有太大意义。你真正要确认的是：
关键上下文有没有进入下一轮请求？
第二层：工具列表或工具描述有问题
Agent 能调用工具，并不代表它会正确调用工具。
模型看到的是一组工具 schema，包括工具名、描述、参数结构。
如果工具描述太模糊，模型可能不知道什么时候该用。
如果参数结构太复杂，模型可能生成错误参数。
如果工具太多，模型也可能选错。
这类问题在 MCP、插件、子任务工具越来越多以后会更明显。
第三层：tool call 和 tool result 没有正确闭环
一个正常的工具调用闭环应该是：
assistant: tool_use
tool: tool_result
assistant: 根据 tool_result 继续
如果中间某一环丢了，Agent 就会开始出现奇怪行为。
比如：
- 工具没有真正执行，但模型以为执行了
- tool result 太长，进入下一轮后污染上下文
- 多个 tool_result 顺序错了
- tool_use 和 tool_result 没有正确配对
- provider 要求的消息格式和客户端保存的格式不一致
这类 bug 最难靠肉眼看最终回答判断。
你必须看到真实的请求和响应。
第四层：token 和成本问题
很多人用 AI 编程工具时，一开始只关心效果。
但一旦使用频率上来，token 成本就会变成实际问题。
尤其是 Agent 场景里，token 并不只花在最终回答上。
大量 token 可能花在：
- system prompt
- 工具 schema
- 历史消息
- 文件内容
- 搜索结果
- 命令输出
- tool result
- 子 Agent 的上下文
有时一次任务很贵，不是因为最终回答很长，而是因为某一轮请求带了巨大的上下文。
所以看 session 总成本还不够，最好能看到每一次请求的 token 使用。
请求级调试应该看什么？
如果一个 AI Agent 跑偏，我通常会先看这几类信息。
1. system prompt
system prompt 是 Agent 行为的底层约束。
很多看似“模型自己决定”的行为，其实是 system prompt 影响的。
比如：
- 它为什么总是先写计划？
- 它为什么不直接执行命令？
- 它为什么遇到某类文件不修改？
- 它为什么要反复确认？
这些可能都和 system prompt 有关。
2. messages
messages 决定模型当前能看到什么。
重点不是“这个 Agent 曾经读过什么”，而是：
当前这一轮请求里到底包含了什么？
这两个问题不一样。
Agent 本地读过一个文件，不代表后续每一轮模型请求都带着这个文件。
3. tools schema
如果 Agent 没有调用你期望的工具，先不要急着骂模型。
可以先看：
- 工具是否真的出现在 tools 里？
- 工具描述是否清楚？
- 参数 schema 是否合理？
- 是否有多个类似工具让模型混淆？
- provider 是否支持这种 schema？
4. tool call / tool result
这一层最适合排查 Agent 为什么做错。
你可以看：
- 模型选择了哪个工具
- 传入了什么参数
- 工具返回了什么
- 返回结果有没有进入下一轮
- 下一轮模型有没有基于这个结果继续
如果这里断了，后面再怎么调 prompt 都不稳定。
5. token / cache / cost / latency
这些指标能帮你判断问题发生在哪一轮。
比如：
- 哪一轮 input token 突然升高？
- 哪一轮 tool result 特别大？
- cache 有没有命中？
- 哪个模型最贵？
- 哪个请求延迟最高？
- 失败请求有没有 usage 信息？
这比只看“今天花了多少钱”有用得多。
ccglass 解决的就是这一层
最近我发现了一个开源工具：ccglass。
项目地址：
https://github.com/jianshuo/ccglass
它不是另一个 AI 编程助手，而是一个本地观测工具。
简单说，它会在本地启动一个代理和 Dashboard，让你看到 Claude Code、Codex、OpenCode、CodeBuddy、Qoder 等工具实际发给模型的请求。
你可以看到：
- system prompt
- messages
- tools schema
- tool calls
- tool results
- request / response body
- token / cache / cost
- latency
- turn-to-turn diff
也就是说，它关心的不是“再帮你写一段代码”，而是“让你看清 Agent 到底是怎么工作的”。
一个典型使用场景
假设你让 Claude Code 修一个 bug。
它最后确实改了代码，但你觉得改得很奇怪。
这时你可以不急着重跑，而是打开 ccglass 看这几件事：
- 第一轮请求里有没有带上相关文件？
- system prompt 有没有影响它的修改策略？
- 它调用了哪些工具？
- 每个工具返回了什么？
- 哪个 tool result 进入了下一轮？
- 修改代码前，它是否真的看到了测试失败信息？
- token 是不是在某一轮突然暴涨？
如果你能回答这些问题，调试 Agent 就从“感觉不对”变成了“证据链不对”。
它和普通抓包工具有什么区别？
很多人会问：这是不是 Charles、mitmproxy、Proxyman 也能做？
某些情况下可以，但 AI 编程 Agent 有几个麻烦点：
- 不一定遵守系统代理
- 有些客户端走自定义 base URL
- 有些使用 OpenAI / Anthropic 兼容接口
- 有些 provider 的 streaming 格式不一样
- 有些工具调用信息需要按 Agent 语义展示，而不是只看 HTTP 包
ccglass 的目标不是替代通用抓包工具，而是专门围绕 AI Agent 请求结构做展示。
它会把 system、messages、tools、tool call、tool result、usage、cost、diff 这些东西整理成适合调试 Agent 的视图。
为什么我觉得这件事会越来越重要？
AI 编程工具的发展方向很明显：Agent 会越来越自动。
它们会读更多文件，调用更多工具，跑更长任务，甚至调度子 Agent。
这当然会提高效率。
但如果没有观测能力，复杂度也会一起上升。
以后我们遇到的问题可能不再是：
这段代码补全得对不对？
而是：
为什么这个 Agent 在第 7 轮调用了这个工具？
为什么它把这个 tool result 带到了后面 12 轮？
为什么这次任务花了 30 万 token？
为什么同样的任务换 provider 就失败？
为什么上下文压缩后它丢了关键约束？
这些问题都需要请求级视角。
结语
我觉得 AI 编程工具接下来的一个重要方向，不只是让 Agent 更强，而是让 Agent 更可观察。
只看最终回答，就像只看程序崩溃后的最后一行日志。
真正要调试复杂系统，还是要看输入、输出、中间状态和调用链。
AI Agent 也是一样。
如果你也在用 Claude Code、Codex、OpenCode、CodeBuddy、Qoder 这类工具，可以试试 ccglass：
https://github.com/jianshuo/ccglass
它解决的不是“让 AI 更聪明”，而是让使用者更清楚地知道：
AI 到底看到了什么，又基于什么做出了下一步。
