agent-architecture-audit

Agent Architecture Audit

一套专为 Agent 系统打造的诊断工作流。专门排查那些隐藏在外壳封装层（wrapper）、过时记忆、重试死循环或传输/渲染篡改背后的隐蔽故障。

触发时机（When to Activate）

必须激活（MANDATORY for）：

• 准备将任何 Agent 或 LLM 驱动的应用发布到生产环境时
• 上线包含工具调用（tool calling）、记忆系统或多步工作流的功能时
• 增加外壳封装层（wrapper layers）后 Agent 表现反而退化时
• 用户反馈“Agent 效果变差了”或“工具调用经常掉链子”时
• 同样的模型在 Playground 测试正常，但放到你的包装层（wrapper）里就崩掉时
• 排查 Agent 异常行为超过 15 分钟却毫无头绪、找不到根本原因时

以下情况尤为关键：

• 新增了 Prompt 包装层、工具定义或记忆系统
• 系统中不同 Agent 表现参差不齐、不一致
• 模型昨天表现良好，今天却开始胡说八道/产生幻觉
• 怀疑系统内部存在隐蔽的修复/重试循环，在暗中悄悄篡改响应结果

无需使用（Do not use for）：

• 通用代码调试 —— 请使用 agent-introspection-debugging
• 代码 Review —— 请使用特定语言的 Reviewer Agent
• 安全扫描 —— 请使用 security-review 或 security-review/scan
• Agent 性能基准测试 —— 请使用 agent-eval
• 编写新功能 —— 请使用对应的 workflow skill

12 层 Agent 堆栈（The 12-Layer Stack）

每个 Agent 系统都包含以下 12 个层级。任何一层出问题，都可能导致最终输出被污染或篡改：

#	堆栈层级	常见故障/踩坑点
1	System prompt（系统提示词）	存在相互冲突的指令、指令过载膨胀
2	Session history（会话历史）	注入了来自先前轮次的过时上下文
3	Long-term memory（长期记忆）	跨 Session 记忆污染，新对话中带入旧话题
4	Distillation（提炼/压缩）	被压缩提取的信息重新作为“虚假事实”混入上下文
5	Active recall（主动召回）	存在冗余的二次摘要层，白白浪费上下文长度
6	Tool selection（工具路由/选择）	工具路由分发错误，或模型直接漏掉/跳过必须调用的工具
7	Tool execution（工具执行）	伪造执行（幻觉）—— 声明调用了工具但实际根本没执行
8	Tool interpretation（工具输出解读）	误读或完全忽略了工具返回的真实结果
9	Answer shaping（回答塑形）	最终 Response 的输出格式损坏
10	Platform rendering（平台层渲染）	传输层篡改（UI、API 或 CLI 篡改了模型原本正确的回答）
11	Hidden repair loops（隐式修复循环）	静默的兜底/重试 Agent 在后台跑了第二次 LLM Pass
12	Persistence（持久化）	过期状态或缓存产物被误当成实时证据重复使用

常见失效模式（Common Failure Patterns）

1. 外壳封装退化（Wrapper Regression）

基础模型本身能给出正确答案，但由于添加了外壳封装层，反而把效果搞砸了。

典型症状：

• 模型在 Playground 或直接调用 API 时表现良好，但在你的 Agent 框架里就报错或失灵
• 新加了一层 Prompt 包装后，原本正常的功能效果变差
• Agent 语气极其自信，但给出的结果却是彻头彻尾的错误
• “明明在上一次更新前还能正常用”

2. 记忆交叉污染（Memory Contamination）

旧话题通过会话历史（history）、记忆检索（retrieval）或提炼压缩（distillation）静默渗漏到新对话中。

典型症状：

• Agent 莫名提及毫不相关的历史话题
• 用户的纠错无法生效（旧记忆覆盖了新纠错）
• 同一 Session 产生的临时产物被当成“伪事实”重新混入
• 记忆无底线膨胀，导致 Response 质量随时间推移持续劣化

3. 工具约束失效（Tool Discipline Failure）

在 Prompt 里声明了工具，但在代码层面却没有强制约束。导致模型跳过工具直接瞎编，或者产生“虚假执行”的幻觉。

典型症状：

• Prompt 里写了“必须使用工具 X”，但模型不调工具直接给出答复
• 工具返回结果看起来没问题，但日志里根本没有实际执行记录
• 不同的工具之间职责不清、相互抢占
• 不需要用工具时瞎用，必须用工具时反而跳过

4. 渲染/传输层篡改（Rendering/Transport Corruption）

Agent 内部生成的原始答案完全正确，但在交付给用户的平台传输/渲染阶段被损坏了。

典型症状：

• 日志显示回答完全正确，但前端用户界面看到的却是损坏的输出
• Markdown 渲染、JSON 解析或流式传输切片（streaming fragments）损坏了合法的响应内容
• 隐蔽的兜底 Agent 在最终交付前静默替换了答案
• Terminal 命令行终端与 UI 界面呈现的输出不一致

5. 隐蔽的 Agent 层（Hidden Agent Layers）

未经显式契约约束，悄悄运行着兜底修复、失败重试、自动摘要或召回 Agent。

典型症状：

• 内部生成的原始输出与最终交付给用户的输出不一致
• 触发了用户根本不知情的二次 LLM 自动修复/重试循环
• 多个 Agent 在缺乏协调的情况下同时修改同一份输出
• 答复内容被某些“看不见”的隐式层给默默“平滑”或“修正”了

审计工作流（Audit Workflow）

阶段 1：确定审计范围（Scope）

明确你需要审计的对象：

• 目标系统 —— 具体是哪一款 Agent 应用？
• 入口点 —— 用户通过什么方式与其交互（UI/API/CLI）？
• 模型堆栈 —— 使用了哪些 LLM 及 Provider 供应商？
• 故障症状 —— 用户反馈的具体问题是什么？
• 时间节点 —— 问题是从什么时候开始出现的？
• 审计层级 —— 12 层堆栈中涵盖哪些层？

阶段 2：证据收集（Evidence Collection）

从代码库中收集审计证据：

• 源码 —— Agent 主循环、工具路由器、记忆准入机制、Prompt 组装逻辑
• 日志 —— 历史 Session Trace 追踪日志、工具调用记录
• 配置 —— Prompt 模板、工具 Schema 定义、Provider 供应商参数配置
• 记忆文件 —— SOP 文档、知识库、Session 归档记录

使用 rg（ripgrep）搜索常见的反模式代码（anti-patterns）：

# 仅在 Prompt 文本中写了工具要求（代码层面未强约束）
rg "must.*tool|必须.*工具|required.*call" --type md

# 未进行校验就直接执行工具
rg "tool_call|toolCall|tool_use" --type py --type ts

# Agent 主循环之外的隐藏 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：故障映射（Failure Mapping）

为排查出的每一项问题整理如下文档要素：

• 故障症状（Symptom） —— 用户层面观察到的现象
• 作用机制（Mechanism） —— 包装层是如何引发该问题的
• 归属层级（Source layer） —— 对应 12 层堆栈中的哪一层
• 根本原因（Root cause） —— 最底层的引发原因
• 代码/日志证据（Evidence） —— 指向 file:line 或 log:row
• 置信度（Confidence） —— 评估分值（0.0 至 1.0）

阶段 4：修复策略（Fix Strategy）

默认修复优先级顺序（代码优先，而非仅改 Prompt）：

1. 代码级拦截工具要求（Code-gate tool requirements） —— 在代码层面强校验工具调用，不能只依赖 Prompt 提示
2. 移除或收紧隐式修复 Agent —— 明确兜底契约，避免无意识的二次调用
3. 减少上下文冗余重复 —— 避免同一份信息同时混进 Prompt + 历史 + 记忆 + 提炼压缩中
4. 收紧记忆写入准入（Memory admission） —— 确保“用户纠错 > Agent 自行推断”
5. 收紧提炼/压缩触发条件 —— 切勿对不该压缩的内容强行压缩
6. 减少渲染层篡改 —— 采用直通（pass-through）模式，避免二次加工转换
7. 重构成 Typed JSON 信封结构 —— 内部流程统一采用结构化传输，替代自由格式文本

严重程度模型（Severity Model）

级别	含义说明	处理动作
critical	Agent 在业务操作中会自信地做出错误行为	下个版本发布前必须修复
high	频繁导致 Agent 正确性或稳定性严重下降	本个迭代 Sprint 内必须修复
medium	正确性基本不受影响，但输出内容脆弱或造成严重上下文浪费	排入下一个迭代计划
low	大多属于样式展示或代码可维护性问题	放进 Backlog 需求池

输出格式（Output Format）

请严格按照以下顺序向用户呈现诊断结论：

1. 按严重程度排序的问题列表（最高危问题放在最前）
2. 架构层面诊断结论（具体是哪一层损坏了什么，以及为什么）
3. 按优先级排列的修复计划（代码优先，而非调整 Prompt）

直奔主题，切勿以寒暄客套或软绵绵的总结开头。如果系统有硬伤，请直接严厉指出。

诊断快速自查清单（Quick Diagnostic Questions）

在审计 Agent 系统时，请逐一回答以下问题：

#	自查问题	若回答“是” →
1	模型是否能直接绕过/跳过必选工具给出答复？	工具未在代码层实现关卡拦截（Code-gated）
2	旧对话中的内容是否重新出现在了新轮次中？	记忆交叉污染
3	同一份信息是否同时存在于 System prompt、记忆和历史记录中？	上下文冗余重复
4	平台在最终交付前是否在后台跑了第二次 LLM Pass？	存在隐式修复循环（Hidden repair loop）
5	内部生成的回答与最终呈现给用户的回答是否不同？	渲染/传输层篡改
6	“必须使用工具 X”的规则是否仅仅存在于 Prompt 文本中？	工具约束失效
7	Agent 自己的独白/内心活动是否会被写入长期记忆？	长期记忆下毒/污染

严禁踩坑的反模式（Anti-Patterns to Avoid）

• 在未排除外壳包装层（wrapper）回归退化之前，切勿直接怪罪 LLM 模型本身能力不行。
• 在未给出具体污染路径和链条证据前，切勿直接推给记忆模块。
• 切勿因为当前环境运行干净，就抹去或忽略历史上发生过的脏异常事件。
• 切勿将 Markdown 文本格式当成内部模块间传输的可信协议。
• 当代码层面没有任何校验约束时，切勿接受 Prompt 文本里写有“必须使用工具”这种虚假承诺。
• 保证诊断结论直面硬伤、证据确凿，并按严重程度严密排序。

报告 Schema（Report Schema）

审计完成后应生成符合以下 JSON 结构的标准报告：

{
  "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" }
  ]
}

相关 Skill（Related Skills）

• agent-introspection-debugging —— 调试 Agent 运行时异常（死循环、超时、状态错误等）
• agent-eval —— 对 Agent 进行面对面的基准性能评估（Benchmark）
• security-review —— 代码与配置文件的安全审计
• autonomous-agent-harness —— 搭建自主 Agent 运行环境
• agent-harness-construction —— 从零构建 Agent 测试/运行 Harness 框架