Agent 调试与可观测性：出了问题怎么排查

Agent 出了问题怎么排查？

5 个常见症状 × 诊断方法 × 修复手段

症状一：Agent 读错了文件 / 漏了文件
"我明明上传了数据文件，它怎么没用？"
Agent 产出的内容里缺少某个文件的信息，或者引用了不存在的文件。你不确定它到底读了哪些文件。
查
直接问 Agent："你刚才读了哪些文件？列出来。" 大部分框架的 Agent 能回忆自己的操作记录。
查
查看会话日志——Agent 的每次文件读取都会被记录。
# Claude Code — 查看当前会话的操作记录
> 你这次会话里读了哪些文件？用了哪些工具？

# Claude Code — 查看成本和 token 消耗（间接看活动量）
> /cost

# Codex — 会话记录在本地文件
$ cat ~/.codex/sessions/2026/05/26/rollout-*.jsonl

# Hermes — 会话搜索
> /session search "读取文件"
修
文件名问题：Agent 可能因为文件名看不出内容而跳过了。改成更描述性的名字。
修
目录太深：Agent 默认只扫描 1-2 层目录。文件藏太深可能没被发现。
修
明确指定：在指令里说"请务必读取 data/sales.csv 文件"——别让 Agent 猜。
症状二：Skill 没有被触发
"我装了技能但 Agent 好像没用"
查
确认技能被加载了没：
# Claude Code
> /skills # 列出已加载技能
> 你当前加载了哪些技能？有没有 make-pptx？

# Codex
$ codex --ask-for-approval never "列出当前所有指令和技能"

# Hermes
$ hermes skills list # 列出所有已安装技能
> /skills # 会话内查看
修
description 不匹配：你说"帮我做 PPT"，但技能 description 里只写了"制作演示文稿"——关键词没覆盖。把"PPT""幻灯片""演示"都写进 description。
修
文件位置错：技能没放在正确的 skills/ 目录下。用 ls ~/.claude/skills/ 确认。
修
手动触发：如果自动匹配不准，直接说"用 make-pptx 技能来做"。
症状三：Agent 输出的数据不对
"CSV 里写的是 342 万，它给我写了 432 万"
Agent 产出的数字跟原始数据不一致——它可能在"编造"，也可能是前面读取阶段就错了。
查
验证读取：让 Agent 把它读到的原始数据打印出来看。
> 你从 CSV 里读到的原始数据是什么？把前 5 行打印给我看。
> 你是怎么算出"全平台增粉 16,480"这个数字的？列出计算过程。
查
检查 context 溢出：如果对话已经很长了，Agent 可能"遗忘"了早先读取的数据而开始凭记忆编造。
# Claude Code — 查看 context 使用量
> /status # 显示当前 token 消耗和 context 占用
> /cost # 查看本次会话的 token 和费用
修
要求用程序计算：在 Skill 或指令里写"数据必须用 Python/pandas 从 CSV 计算，不要凭记忆估算"。
修
Context 满了：开新会话，让 Agent 重新读取文件。或者用子 Agent 做数据分析，主 Agent 只收摘要。
症状四：Agent 选了错误的方案
"我想让它用方法 A，它偏偏用了方法 B"
Agent 有多种方法可以完成任务，但它选了你不想要的那种。比如你想用 pandas 分析数据，它用了纯文本处理；你想生成 Word，它生成了 Markdown。
查
让 Agent 解释决策：
> 你为什么选择用 Markdown 而不是 Word？解释你的判断过程。
> 在做这个任务之前，你考虑了哪些方案？为什么选了当前这个？
查
检查指令优先级冲突：可能 CLAUDE.md 里写了"默认输出 Markdown"，跟你的口头指令冲突了。
# 查看当前生效的所有指令
> 列出你当前遵守的所有规则，包括 CLAUDE.md、技能、和我的对话指令

# Claude Code — 查看记忆里是否有冲突的规则
> /memory
修
在指令里明确说："用 Word 格式，不要用 Markdown"——显式指定比让 Agent 自己判断更可靠。
修
更新 Skill / CLAUDE.md：如果这是反复出现的偏好问题，写进配置文件一劳永逸。
症状五：Agent 突然"变笨了"
"之前好好的，今天怎么越做越差？"
Agent 之前表现正常，但在同一个对话里越往后越差——开始重复、遗忘、编造。
查
99% 的原因是 context 快满了。查看使用量：
# Claude Code
> /status
Context: 182,400 / 200,000 tokens (91%) ← 快满了！
Messages: 47 ← 对话轮次太多
Files read: 12
Tools used: 34

# Hermes
> /status # 类似输出
修
开新会话：最直接的解决方法。Agent 在新会话里重新读文件就能恢复。
修
用子 Agent 分担：把占 context 大的操作（文件分析、大段生成）交给子 Agent，主 Agent 只收摘要。
修
减少单次对话的任务量：做完一件事开新会话再做下一件，别在同一个会话里堆 5 个不相关的任务。
⚙
各框架的调试工具一览
我想查什么
Claude Code
Codex
Hermes
context 用了多少
/status
显示 token 数和百分比
/status
显示 context 预算
/status
含 context + 记忆统计
花了多少钱
/cost
本次会话费用明细
API 控制台查看
/cost
含分 provider 统计
加载了哪些指令/技能
/skills
/memory
codex "列出指令"
/skills
hermes skills list
Agent 做了什么操作
对话中直接可见
每步都会显示
~/.codex/sessions/
JSONL 完整记录
/session search
~/.hermes/logs/
为什么做了某个决策
直接问 Agent
"解释你的判断"
直接问 Agent
或查 session log
直接问 Agent
/debug 模式
历史会话记录
~/.claude/projects/
按项目存储
~/.codex/sessions/
按日期存储
/session search
跨会话搜索
✓
快速排查清单：Agent 出了问题先查这 5 项
1Context 满了没？ → /status 查占用率。超过 80% 就该开新会话了。
2文件读对了没？ → 问 Agent "你读了哪些文件"。文件名不直观就手动指定。
3技能加载了没？ → /skills 确认。没加载就检查文件位置和 description。
4指令有冲突没？ → 问 Agent "你当前遵守哪些规则"。检查 CLAUDE.md、Skill、口头指令是否矛盾。
5数据是算出来的还是编出来的？ → 让 Agent 打印计算过程。Skill 里写"必须用代码计算"。
最实用的调试技巧：直接问 Agent。"你为什么这么做？""你读了哪些文件？""你当前 context 里有什么？"——Agent 能回答关于自己行为的大部分问题。不需要翻日志文件，先问它。只有它答不上来或者答案可疑时，再去查底层日志。