Agent Architecture Audit

Audit agent system architecture across 12 layers for wrapper regression, memory pollution, tool discipline failures, and hidden fix loops. Use when diagnosing agent structural issues, detecting regressions, or producing severity-ranked discovery reports.

paudyyin@paudyyin

Install

openclaw skills install @paudyyin/agent-architecture-audit

Agent Architecture Audit �?12 层架构审�?

诊断 Agent 系统中隐藏故障的审计工作流�?

触发条件

必须使用�?- Agent 行为退化（"Agent 变差�?�?工具不稳�?�?- 模型�?playground 正常，但�?wrapper 中失�?- 添加�?prompt �?工具定义/记忆系统后，现有行为退�?- 调试 Agent 行为超过 15 分钟未找到根�?- 发布 Agent 应用�? 不适用�?- 通用代码调试 �?�?agent-introspection-debugging

代码审查 �?�?code-review
安全扫描 �?�?security-and-hardening
性能基准测试 �?�?performance-optimization

12 层架构栈

每个 Agent 系统都有这些层。任何一层都可能损坏答案�?

#	�?	可能的问�?
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	静默 fallback/retry agent 运行第二�?LLM 调用
12	Persistence	过期状态或缓存产物作为实时证据重用

5 种常见失败模�?

1. Wrapper 回归

基础模型产生正确答案，但 wrapper 层使其变差�? 症状�?- 模型�?playground 或直�?API 调用中正常，�?Agent 中失�?- 添加�?prompt 层后，现有行为退�?- Agent 听起来自信但自信地错�?- "之前还能用，更新后就不行�?

2. 记忆污染

旧话题通过 history、memory retrieval �?distillation 泄漏到新对话�? 症状�?- Agent 提起不相关的过去话题

用户纠正不持久（旧记忆覆盖新的）
同会话产物作为伪事实重新进入
记忆无限增长，降低响应质�?

3. 工具纪律失败

工具�?prompt 中声明但未在代码中强制执行。模型跳过或幻觉执行�? 症状�?- Prompt �?必须用工�?X"，但模型不调用就回答

工具结果看起来正确但从未实际执行
不同工具争夺同一职责
模型不该用工具时用了，该用时跳过�?

4. 渲染/传输损坏

Agent 内部答案正确，但平台层在传递时变异�? 症状�?- 日志显示正确答案，用户看到损坏输�?- Markdown 渲染、JSON 解析或流式传输片段损坏有效响�?- 隐藏 fallback agent 在传递前静默替换答案

终端�?UI 输出不同

5. 隐藏 Agent �?

静默修复、重试、摘要或召回 agent 在没有明确契约的情况下运行�? 症状�?- 输出在内部生成和用户传递之间变�?- "自动修复"循环运行用户不知道的第二�?LLM 调用

多个 agent 在没有协调的情况下修改同一输出
答案被不可见�?平滑"�?纠正"

审计工作�?

Phase 1: Scope（范围）

定义审计目标�?

目标系统 �?哪个 Agent 应用�?- *入口�? �?用户如何交互�?- *模型�? �?哪些 LLM 和提供商�?- 症状 �?用户报告什么？
时间窗口 �?何时开始？
*要审计的�? �?12 层中哪些适用�?

Phase 2: Evidence Collection（证据收集）

从代码库收集证据�?

*源代�? �?Agent 循环、工具路由、记忆准入、prompt 组装
日志 �?历史会话追踪、工具调用记�?- 配置 �?prompt 模板、工�?schema、提供商设置
记忆文件 �?SOP、知识库、会话归�? 搜索反模式：

bash

# 工具要求仅在 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 调用�?fallback 循环
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# 静默输出变异
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Phase 3: Failure Mapping（失败映射）

对每个发现，记录�?

症状 �?用户看到什�?- 机制 �?wrapper 如何导致
源层 �?12 层中的哪一�?- 根因 �?最深层原因
证据 �?file:line �?log:row 引用
*置信�? �?0.0 �?1.0

Phase 4: Fix Strategy（修复策略）

默认修复顺序（代码优先，�?prompt 优先）：

代码门控工具要求 �?在代码中强制，不仅在 prompt 文本
移除或收窄隐藏修�?agent �?�?fallback 明确带契�?3. *减少上下文重�? �?同一信息通过 prompt + history + memory + distillation
收紧记忆准入 �?用户纠正 > Agent 断言
收紧 distillation 触发 �?不压缩不应压缩的内容
减少渲染变异 �?直通，不转�?7. 转换为类型化 JSON 信封 �?结构化内部流，非自由文本

严重度模�?

级别	含义	行动
`critical`	Agent 可以自信地产生错误的操作行为	下次发布前修�?
`high`	Agent 经常降低正确性或稳定�?	�?sprint 修复
`medium`	正确性通常存活但输出脆弱或浪费	计划下一周期
`low`	主要是外观或可维护性问�?	Backlog

输出格式

按此顺序呈现发现�?

严重度排序的发现（最严重优先�?2. 架构诊断（哪层损坏了什么，为什么）
排序修复计划（代码优先，�?prompt 优先�? 不要以赞美或摘要开头。如果系统坏了，直接说�?

7 个快速诊断问�?

#	问题	如果�?�?
1	模型能跳过必需工具仍然回答吗？	工具未代码门�?
2	旧对话内容出现在新轮次吗�?	记忆污染
3	同一信息�?system prompt AND memory AND history 中？	上下文重�?
4	平台在传递前运行第二�?LLM 调用吗？	隐藏修复循环
5	输出在内部生成和用户传递之间不同吗�?	渲染损坏
6	"必须用工�?X" 规则仅在 prompt 文本中？	工具纪律失败
7	Agent 自己的独白能成为持久记忆吗？	记忆中毒

报告 Schema

审计应产出结构化报告�?

json

{
  "schema_version": "agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk | moderate | healthy",
    "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 (1-12)",
      "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`	运行时调试（工具循环、上下文漂移�?	互补：本技能管架构级审�?
`error-classifier`	错误分类 + 重试策略	互补：本技能管架构视角
`code-review`	代码级审�?	本技能更高层（架构级�?

反模�?

在证�?wrapper 层回归前，不要责怪模�?- 不要在没有显示污染路径的情况下责怪记�?- 不要让干净的当前状态抹去脏的历史事�?- 不要�?Markdown 文本视为可信的内部协�?- 不要接受"必须用工�?仅在 prompt 文本中而代码从未强�?- 保持发现直接、证据支持、严重度排序

*12 层架构审计：系统化诊�?Agent 系统的隐藏故障�?