智能体架构审计 (Agent Architecture Audit)
一个用于智能体系统的诊断工作流，这些系统的故障可能隐藏在包装层、过期内存、重试循环或传输/渲染突变之后。
何时激活 (When to Activate)
必须使用 (MANDATORY) 于：
- 将任何智能体或LLM驱动的应用发布到生产环境
- 发布包含工具调用、内存或多步骤工作流的功能
- 添加包装层后智能体行为退化
- 用户报告“智能体越来越差”或“工具不稳定”
- 同一个模型在Playground中工作正常，但在你的包装中出错
- 调试智能体行为超过15分钟仍未找到根本原因
以下情况尤其关键：
- 你添加了新的提示层、工具定义或内存系统
- 系统中不同智能体的行为不一致
- 模型昨天还好好的，今天却开始产生幻觉
- 你怀疑有隐藏的修复/重试循环在无声地修改响应
不要用于：
- 通用代码调试 – 请使用
agent-introspection-debugging - 代码审查 – 请使用特定语言的审查助手
- 安全扫描 – 请使用
security-review或security-review/scan - 智能体性能基准测试 – 请使用
agent-eval - 编写新功能 – 请使用相应的工作流技能
12层栈 (The 12-Layer Stack)
每个智能体系统都包含这些层。任何一层都可能破坏答案：
| # | 层 (Layer) | 出错情况 (What Goes Wrong) |
|---|---|---|
| 1 | 系统提示 (System prompt) | 冲突指令、指令膨胀 |
| 2 | 会话历史 (Session history) | 先前轮次的过期上下文注入 |
| 3 | 长期记忆 (Long-term memory) | 跨会话污染，旧话题出现在新对话中 |
| 4 | 蒸馏 (Distillation) | 压缩后的伪事实重新进入 |
| 5 | 主动召回 (Active recall) | 冗余的重新摘要层浪费上下文 |
| 6 | 工具选择 (Tool selection) | 工具路由错误，模型跳过必需工具 |
| 7 | 工具执行 (Tool execution) | 执行幻觉 — 声称调用但实际未调用 |
| 8 | 工具解释 (Tool interpretation) | 误读或忽略工具输出 |
| 9 | 答案塑形 (Answer shaping) | 最终响应格式损坏 |
| 10 | 平台渲染 (Platform rendering) | 传输层突变（UI、API、CLI篡改有效答案） |
| 11 | 隐藏修复循环 (Hidden repair loops) | 静默的回退/重试智能体运行第二次LLM调用 |
| 12 | 持久化 (Persistence) | 过期的状态或缓存工件被当作实时证据重用 |
常见故障模式 (Common Failure Patterns)
1. 包装回归 (Wrapper Regression)
基础模型能给出正确答案，但包装层使其变得更差。
症状：
- 模型在Playground或直接API调用时工作正常，但在你的智能体中出错
- 添加了新的提示层后，现有行为退化
- 智能体听起来自信满满，但实际上自信地出错
- “上次更新之前还是好的”
2. 内存污染 (Memory Contamination)
旧话题通过历史记录、内存检索或蒸馏泄漏到新对话中。
症状：
- 智能体提起不相关的过去话题
- 用户的修正不生效（旧内存覆盖新内容）
- 同一会话的伪事实重新进入系统
- 内存无限增长，随时间推移响应质量下降
3. 工具约束失效 (Tool Discipline Failure)
提示中声明了工具，但代码中没有强制执行。模型跳过它们或幻觉执行。
症状：
- 提示中有“必须使用工具X”，但模型回答时并未调用
- 工具结果看起来正确，但实际从未执行
- 不同工具争夺同一职责
- 模型在不该用工具时使用，或在该用时跳过
4. 渲染/传输损坏 (Rendering/Transport Corruption)
智能体的内部答案正确，但平台层在交付时篡改了它。
症状：
- 日志显示正确答案，用户看到损坏输出
- Markdown渲染、JSON解析或流式片段破坏有效响应
- 隐藏的回退智能体在交付前悄悄替换答案
- 终端和UI的输出不同
5. 隐藏智能体层 (Hidden Agent Layers)
静默的修复、重试、摘要或召回智能体在没有明确契约的情况下运行。
症状：
- 内部生成和用户交付之间的输出发生变化
- “自动修复”循环运行用户不知道的第二次LLM调用
- 多个智能体无协调地修改同一输出
- 答案被不可见层“平滑”或“修正”
审计工作流 (Audit Workflow)
阶段 1：范围界定 (Phase 1: Scope)
定义你要审计的内容：
- 目标系统 (Target system) — 哪个智能体应用？
- 入口点 (Entrypoints) — 用户如何与之交互？
- 模型栈 (Model stack) — 有哪些LLM和提供商？
- 症状 (Symptoms) — 用户报告了什么？
- 时间窗口 (Time window) — 何时开始？
- 待审计层 (Layers to audit) — 12层中哪些层适用？
阶段 2：证据收集 (Phase 2: Evidence Collection)
从代码库中收集证据：
- 源代码 (Source code) — 智能体循环、工具路由器、内存准入、提示组装
- 日志 (Logs) — 历史会话轨迹、工具调用记录
- 配置 (Config) — 提示模板、工具模式、提供商设置
- 内存文件 (Memory files) — 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
阶段 3：故障映射 (Phase 3: Failure Mapping)
对于每个发现，记录：
- 症状 (Symptom) — 用户看到什么
- 机制 (Mechanism) — 包装如何导致它
- 源层 (Source layer) — 属于12层中的哪一层
- 根本原因 (Root cause) — 最深层的原因
- 证据 (Evidence) — 文件:行 或 日志:行 引用
- 置信度 (Confidence) — 0.0 到 1.0
阶段 4：修复策略 (Phase 4: Fix Strategy)
默认修复顺序（代码优先，而非提示优先）：
- 代码门控工具要求 — 在代码而非仅提示文本中强制执行
- 移除或收窄隐藏修复智能体 — 使回退显式化并附带契约
- 减少上下文重复 — 相同信息通过提示+历史+内存+蒸馏传播
- 收紧内存准入 — 用户修正 > 智能体断言
- 收紧蒸馏触发条件 — 不要压缩不该压缩的内容
- 减少渲染突变 — 直通传递，不要转换
- 转换为类型化JSON信封 — 结构化内部流，而非自由格式文本
严重程度模型 (Severity Model)
| 等级 (Level) | 含义 (Meaning) | 行动 (Action) |
|---|---|---|
critical | 智能体可能自信地产生错误操作行为 | 下次发布前修复 |
high | 智能体频繁降低正确性或稳定性 | 本周期内修复 |
medium | 正确性通常能保持，但输出脆弱或浪费资源 | 下个周期计划 |
low | 主要是外观或可维护性问题 | 放入待办列表 |
输出格式 (Output Format)
按以下顺序向用户呈现发现结果：
- 按严重程度排序的发现 (Severity-ranked findings)（最关键的优先）
- 架构诊断 (Architecture diagnosis)（哪一层损坏了什么，以及原因）
- 有序修复计划 (Ordered fix plan)（代码优先，而非提示优先）
不要以赞美或总结开头。如果系统已损坏，直接说明。
快速诊断问题 (Quick Diagnostic Questions)
审计智能体系统时，回答以下问题：
| # | 问题 (Question) | 如果是 → (If Yes →) |
|---|---|---|
| 1 | 模型能否跳过必需的工具仍给出答案？ | 工具未代码门控 |
| 2 | 旧对话内容是否出现在新轮次中？ | 内存污染 |
| 3 | 相同信息是否同时出现在系统提示、内存和历史中？ | 上下文重复 |
| 4 | 平台在交付前是否运行了第二次LLM调用？ | 隐藏修复循环 |
| 5 | 内部生成和用户交付的输出是否不同？ | 渲染损坏 |
| 6 | “必须使用工具X”的规则是否仅在提示文本中？ | 工具约束失效 |
| 7 | 智能体自身的独白能否成为持久内存？ | 内存中毒 |
应避免的反模式 (Anti-Patterns to Avoid)
- 不要在未能证实包装层回归之前就责怪模型。
- 不要在没有展示污染路径的情况下责怪内存。
- 不要让当前干净的状态抹去之前不干净的历史事件。
- 不要将Markdown散文视为可信的内部协议。
- 当代码从未强制执行时，不要接受提示文本中的“必须使用工具”。
- 保持发现直接、有证据支持并按严重程度排序。
报告模式 (Report Schema)
审计应产生遵循以下形状的结构化报告：
{
"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" }
]
}
相关技能 (Related Skills)
agent-introspection-debugging— 调试智能体运行时故障（循环、超时、状态错误）agent-eval— 对比基准测试智能体性能security-review— 代码和配置安全审计autonomous-agent-harness— 设置自主智能体操作agent-harness-construction— 从头构建智能体测试框架