Agent 架构审计¶

面向将失败隐藏在包装器层、陈旧记忆、重试循环以及传输/渲染变异背后的 Agent 系统的诊断工作流。

启动时机¶

必须使用时： - 在将 Agent 或 LLM 驱动的应用程序发布到生产环境之前 - 在发布包含工具调用、记忆或多阶段工作流的功能之前 - 在添加包装器层后 Agent 行为出现退化时 - 当用户报告“Agent 变差了”或“工具不稳定”时 - 当同一模型在 Playground 中正常运行但在包装器内出错时 - 当在未找到根本原因的情况下对 Agent 行为调试超过 15 分钟时

尤其重要时： - 在添加新的 Prompt 层、工具定义或记忆系统时 - 当系统中不同 Agent 的表现不一致时 - 当昨天还正常的模型今天开始产生幻觉时 - 当怀疑存在静默变异响应的隐藏修复/重试循环时

不要使用： - 通用代码调试 — 使用 agent-introspection-debugging - 代码审查 — 使用语言特定的审查 Agent - 安全扫描 — 使用 security-review 或 security-review/scan - Agent 性能基准测试 — 使用 agent-eval - 创建新功能 — 使用适当的工作流技能

12 层堆栈¶

所有 Agent 系统都有这些层。任何一层都可能破坏答案：

常见故障模式¶

1. 包装器回归¶

基础模型能生成正确答案，但包装器层将其劣化。

症状： - 在 Playground 或直接 API 调用中正常，但在 Agent 内出错 - 添加新的 Prompt 层后既有行为退化 - Agent 自信满满，但自信地犯错 - “上次更新之前还是好的”

2. 记忆污染¶

旧话题通过历史、记忆检索或蒸馏泄漏到新对话中。

症状： - Agent 提起无关的旧话题 - 用户的修正无法固化（旧记忆覆盖新记忆） - 同一会话中的产物被作为伪事实重新注入 - 记忆无限增长，响应质量随时间下降

3. 工具纪律失效¶

工具在 Prompt 中声明但未在代码中强制。模型会跳过工具，或幻觉式声称已执行。

症状： - Prompt 中写着“必须使用工具 X”，但模型不调用工具就作答 - 工具结果看起来正确，但实际从未执行 - 不同工具争夺同一职责 - 模型在不该用时使用工具，在该用时却跳过

4. 渲染与传输损坏¶

Agent 的内部答案正确，但平台层在交付过程中使其变异。

症状： - 日志显示正确答案，但用户看到的是损坏的输出 - Markdown 渲染、JSON 解析或流式片段破坏有效响应 - 隐藏的回退 Agent 在交付前静默替换答案 - 输出在终端与 UI 中不同

5. 隐藏 Agent 层¶

没有明确契约的情况下，静默的修复、重试、摘要或召回 Agent 被执行。

症状： - 输出在内部生成与用户交付之间发生变化 - “自动修复”循环在用户不知情的情况下执行第二次 LLM 传递 - 多个 Agent 在没有协调的情况下修正同一输出 - 答案被不可见层“抛光”或“修正”

审计工作流¶

阶段 1：范围¶

定义审计对象：

• 目标系统 — 哪个 Agent 应用程序？
• 入口点 — 用户如何交互？
• 模型栈 — 哪些 LLM 和提供商？
• 症状 — 用户报告了什么？
• 时间窗口 — 从什么时候开始的？
• 审计层 — 12 层中哪些适用？

阶段 2：证据收集¶

从代码库收集证据：

• 源代码 — Agent 循环、工具路由器、记忆准入、Prompt 组装
• 日志 — 过往会话跟踪、工具调用记录
• 配置 — Prompt 模板、工具 Schema、提供商设置
• 记忆文件 — 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 层中的哪一层
• 根本原因 — 最深层次的原因
• 证据 — 文件:行 或 日志:行 引用
• 置信度 — 0.0 到 1.0

阶段 4：修正策略¶

默认修正顺序（代码优先，而非 Prompt 优先）：

1. 将工具要求代码门控 — 在代码中强制实施，而非仅靠 Prompt 文本
2. 删除或缩减隐藏修复 Agent — 通过契约使回退显式化
3. 减少上下文重复 — 同一信息重复出现在 Prompt、历史、记忆与蒸馏中
4. 严格化记忆准入 — 用户修正 > Agent 断言
5. 严格化蒸馏触发条件 — 不该压缩的不压缩
6. 减少渲染变异 — 直通传递，不做转换
7. 迁移到类型化 JSON 信封 — 结构化内部流程，而非自由形式的散文

严重程度模型¶

输出格式¶

按以下顺序向用户呈现发现：

1. 按严重程度排序的发现（从最重要开始）
2. 架构诊断（哪一层破坏了什么，以及为什么）
3. 带优先级的修复计划（代码优先，而非 Prompt 优先）

不要以奉承或摘要开头。如果系统坏了，直接说出来。

快速诊断问题¶

审计 Agent 系统时，回答以下问题：

应避免的反模式¶

• 在否定包装器层回归之前，不要先责怪模型。
• 在没有展示污染路径的情况下，不要责怪记忆。
• 不允许当前干净的状态抹去被污染的过往事件。
• 不要将 Markdown 散文当作可信的内部协议。
• 不要接受 Prompt 文本中的“必须使用工具” — 除非代码强制执行。
• 保持发现直接、基于证据、按严重程度排序。

报告 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" }
  ]
}

相关技能¶

• agent-introspection-debugging — 调试 Agent 运行时故障（循环、超时、状态错误）
• agent-eval — Agent 性能的对决基准测试
• security-review — 代码与配置的安全审计
• autonomous-agent-harness — 设置自主 Agent 操作
• agent-harness-construction — 从零构建 Agent Harness