agent-architecture-audit

智能体架构审计

针对智能体系统的诊断工作流程，这些系统将失败隐藏在包装器层、过时内存、重试循环或传输/渲染变异之后。

何时激活

以下情况必须使用：

• 将任何智能体或 LLM 驱动的应用程序发布到生产环境
• 发布具有工具调用、内存或多步工作流的功能
• 添加包装器层后智能体行为下降
• 用户报告"智能体变差了"或"工具不稳定"
• 同一模型在 playground 中有效但在包装器中失效
• 调试智能体行为超过 15 分钟仍未找到根本原因

以下情况特别关键：

• 您添加了新的提示层、工具定义或内存系统
• 系统中的不同智能体行为不一致
• 模型昨天正常但今天出现幻觉
• 您怀疑隐藏的修复/重试循环悄悄修改响应

不要用于：

• 一般代码调试 — 使用 agent-introspection-debugging
• 代码审查 — 使用特定语言的审查智能体
• 安全扫描 — 使用 security-review 或 security-review/scan
• 智能体性能基准测试 — 使用 agent-eval
• 编写新功能 — 使用适当的工作流技能

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 传递
• 多个智能体在没有协调的情况下修改同一输出
• 答案被不可见层"平滑"或"纠正"

审计工作流程

阶段 1：范围

定义您要审计的内容：

• 目标系统 — 什么智能体应用？
• 入口点 — 用户如何与之交互？
• 模型堆栈 — 哪些 LLM 和提供商？
• 症状 — 用户报告什么？
• 时间窗口 — 何时开始？
• 要审计的层 — 12 层中哪些适用？

阶段 2：证据收集

从代码库收集证据：

• 源代码 — 智能体循环、工具路由器、内存准入、提示组装
• 日志 — 历史会话跟踪、工具调用记录
• 配置 — 提示模板、工具架构、提供商设置
• 内存文件 — 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：失败映射

对于每个发现，记录：

• 症状 — 用户看到什么
• 机制 — 包装器如何导致它
• 源层 — 12 层中的哪一层
• 根本原因 — 最深层的原因
• 证据 — file:line 或 log:row 引用
• 置信度 — 0.0 到 1.0

阶段 4：修复策略

默认修复顺序（代码优先，而非提示优先）：

1. 代码门控工具要求 — 在代码中强制执行，而不仅是提示文本
2. 删除或缩小隐藏修复智能体 — 使回退具有明确合同
3. 减少上下文重复 — 通过提示 + 历史 + 内存 + 蒸馏的相同信息
4. 收紧内存准入 — 用户更正 > 智能体断言
5. 收紧蒸馏触发器 — 不要压缩不应该压缩的内容
6. 减少渲染变异 — 传递，不转换
7. 转换为类型化 JSON 信封 — 结构化内部流，而非自由格式散文

严重性模型

级别	含义	操作
critical	智能体可能自信地产生错误的操作行为	在下次发布前修复
high	智能体频繁降低正确性或稳定性	本冲刺修复
medium	正确性通常保持但输出脆弱或浪费	计划下一周期
low	主要是化妆品或可维护性问题	积压工作

输出格式

按此顺序向用户展示发现：

1. 按严重程度排序的发现（最关键在前）
2. 架构诊断（哪一层破坏了什么以及为什么）
3. 有序修复计划（代码优先，而非提示优先）

不要以赞美或摘要开头。如果系统损坏，直接说明。

快速诊断问题

审计智能体系统时，回答这些问题：

#	问题	如果是 →
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 — 从头开始构建智能体工具