Agent 架构审计
一个用于诊断智能体系统的诊断工作流，这些系统的问题可能隐藏在包装层、陈旧内存、重试循环或传输/渲染变更背后。
何时激活
必须使用于：
- 将任何智能体或 LLM 驱动的应用程序发布到生产环境
- 发布包含工具调用、内存或多步骤工作流的特性
- 添加包装层后智能体行为退化
- 用户报告“智能体越来越差”或“工具不稳定”
- 相同模型在 Playground 中工作正常，但在你的包装器内出错
- 调试智能体行为超过 15 分钟仍未找到根本原因
以下情况尤其关键：
- 你添加了新的提示层、工具定义或内存系统
- 系统中的不同智能体行为不一致
- 昨天模型还好好的，今天却开始产生幻觉
- 你怀疑存在静默修改响应的隐藏修复/重试循环
不要用于：
- 通用代码调试——请使用
agent-introspection-debugging - 代码审查——请使用特定语言的审查智能体
- 安全扫描——请使用
security-review或security-review/scan - 智能体性能基准测试——请使用
agent-eval - 编写新特性——请使用适当的工作流 skill
12层堆栈
每个智能体系统都包含这些层。任何一层都可能破坏最终答案：
| # | 层 | 可能出问题的地方 |
|---|---|---|
| 1 | 系统提示 | 指令冲突，指令膨胀 |
| 2 | 会话历史 | 先前交互的陈旧上下文注入 |
| 3 | 长期记忆 | 跨会话污染，旧话题出现在新对话中 |
| 4 | 蒸馏 | 压缩后的产品作为伪事实重新进入系统 |
| 5 | 主动召回 | 冗余的重新摘要层浪费上下文 |
| 6 | 工具选择 | 工具路由错误，模型跳过必需工具 |
| 7 | 工具执行 | 幻觉执行——声称调用但实际未执行 |
| 8 | 工具结果解释 | 误解或忽略工具输出 |
| 9 | 答案塑造 | 最终响应中的格式损坏 |
| 10 | 平台渲染 | 传输层变更（UI、API、CLI 修改正确答案） |
| 11 | 隐藏修复循环 | 静默运行二次 LLM 调用的回退/重试智能体 |
| 12 | 持久化 | 将过期的状态或缓存的工件作为实时证据重用 |
常见故障模式
1. 包装回归
基础模型产生正确答案，但包装层使输出变差。
症状：
- 模型在 Playground 或直接 API 调用中表现良好，但在你的智能体中出错
- 添加了新的提示层后，现有行为退化
- 智能体听起来自信但实际上是自信地犯错
- “上次更新之前还是好的”
2. 内存污染
旧话题通过历史记录、内存检索或蒸馏泄露到新对话中。
症状：
- 智能体提及无关的过往话题
- 用户修正不生效（旧内存覆盖新信息）
- 同会话的工件作为伪事实重新进入系统
- 内存无限制增长，随时间降低响应质量
3. 工具纪律失效
工具在提示中声明但未在代码中强制使用。模型跳过它们或幻觉执行。
症状：
- 提示中有“必须使用工具 X”，但模型未调用工具就直接回答
- 工具结果看起来正确但从未真正执行过
- 不同工具争夺同一职责
- 模型在不该用时使用工具，或在必须用时跳过
4. 渲染/传输损坏
智能体内部的回答正确，但平台层在交付过程中进行了修改。
症状：
- 日志显示正确答案，用户却看到损坏的输出
- Markdown 渲染、JSON 解析或流式片段破坏了有效响应
- 隐藏的回退智能体在交付前悄悄替换了答案
- 终端和 UI 的输出不一致
5. 隐藏的智能体层
静默修复、重试、摘要或召回智能体在没有明确契约的情况下运行。
症状：
- 内部生成和用户交付之间的输出发生变化
- “自动修复”循环运行了用户不知道的二次 LLM 调用
- 多个智能体在无协调的情况下修改同一输出
- 答案被不可见的层“平滑”或“修正”
审计工作流
阶段一：范围界定
定义你正在审计的内容：
- 目标系统——哪个智能体应用程序？
- 入口点——用户如何与之交互？
- 模型堆栈——使用哪些 LLM 和提供商？
- 症状——用户报告了什么？
- 时间窗口——问题何时开始？
- 待审计层——12 层中哪些层适用？
阶段二：证据收集
从代码库中收集证据：
- 源代码——智能体循环、工具路由器、内存准入、提示组装
- 日志——历史会话追踪、工具调用记录
- 配置——提示模板、工具模式、提供商设置
- 内存文件——SOP、知识库、会话档案
使用 rg 搜索反模式：
# 仅在提示文本中表达的工具需求（而非代码）
rg "must.*tool|必须.*工具|required.*call" --type md
# 无验证的工具执行
rg "tool_call|toolCall|tool_use" --type py --type ts
# 主智能体循环之外的隐藏 LLM 调用
rg "completion|chat\.create|messages\.create|llm\.invoke"
# 无用户修正优先级的记忆准入
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts
# 执行额外 LLM 调用的回退循环
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts
# 静默输出变更
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts
阶段三：故障映射
对于每个发现，记录：
- 症状——用户看到了什么
- 机制——包装层如何导致该问题
- 源层——属于 12 层中的哪一层
- 根本原因——最深层次的原因
- 证据——文件名:行号 或 日志:行号 引用
- 置信度——0.0 到 1.0
阶段四：修复策略
默认修复顺序（代码优先，而非提示优先）：
- 代码强制工具需求——在代码中强制，而不仅仅是提示文本
- 移除或缩小隐藏的修复智能体——通过契约显式化回退行为
- 减少上下文重复——相同信息通过提示 + 历史 + 记忆 + 蒸馏多次传入
- 收紧记忆准入——用户修正 > 智能体断言
- 收紧蒸馏触发器——不要压缩不该压缩的内容
- 减少渲染变更——透传，不转换
- 转换到类型化 JSON 信封——结构化内部流，而非自由格式文本
严重程度模型
| 级别 | 含义 | 行动 |
|---|---|---|
critical | 智能体可能自信地产生错误的操作行为 | 下次发布前修复 |
high | 智能体频繁降低正确性或稳定性 | 本迭代周期内修复 |
medium | 正确性通常幸存但输出脆弱或浪费 | 规划下个周期 |
low | 主要是外观或可维护性问题 | 放入待办事项 |
输出格式
按以下顺序向用户呈现发现结果：
- 按严重程度排序的发现结果（最严重优先）
- 架构诊断（哪一层破坏了什么，以及原因）
- 有序的修复计划（代码优先，而非提示优先）
不要以赞美或摘要开头。如果系统损坏，直接说明。
快速诊断问题
审计智能体系统时，回答这些问题：
| # | 问题 | 如果是 → |
|---|---|---|
| 1 | 模型能否跳过必需工具仍然回答？ | 工具未通过代码强制 |
| 2 | 旧对话内容是否出现在新一轮交互中？ | 内存污染 |
| 3 | 相同信息是否同时存在于系统提示、内存和历史中？ | 上下文重复 |
| 4 | 平台在交付前是否运行了第二次 LLM 调用？ | 隐藏修复循环 |
| 5 | 内部生成和用户交付的输出是否不同？ | 渲染损坏 |
| 6 | “必须使用工具 X”的规则是否仅存在于提示文本中？ | 工具纪律失效 |
| 7 | 智能体自身的独白能否成为持久化记忆？ | 内存中毒 |
应避免的反模式
- 不要在没有证伪包装层回归之前就归咎于模型。
- 不要在没有展示污染路径的情况下归咎于内存。
- 不要因为当前状态看起来干净而抹去历史上发生过的问题。
- 不要将 Markdown 文本视作可信赖的内部协议。
- 当代码从未强制执行时，不要接受提示文本中的“必须使用工具”。
- 保持发现结果直接、基于证据并按严重程度排序。
报告模式
审计应生成符合以下形式的结构化报告：
{
"schema_version": "ecc.agent-architecture-audit.report.v1",
"executive_verdict": {
"overall_health": "high_risk",
"primary_failure_mode": "string",
"most_urgent_fix": "string"
},
"scope": {
"target_name": "string",
"model_stack": ["string"],
"layers_to_audit": ["string"]
},
"findings": [
{
"severity": "critical|high|medium|low",
"title": "string",
"mechanism": "string",
"source_layer": "string",
"root_cause": "string",
"evidence_refs": ["file:line"],
"confidence": 0.0,
"recommended_fix": "string"
}
],
"ordered_fix_plan": [
{ "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
]
}
相关技能
agent-introspection-debugging— 调试智能体运行时故障（循环、超时、状态错误）agent-eval— 头对头基准测试智能体性能security-review— 代码和配置的安全审计autonomous-agent-harness— 设置自主智能体操作agent-harness-construction— 从零构建智能体测试框架