| name | agent-architecture-audit |
| description | 智能体和 LLM 应用的全栈诊断。审计 12 层智能体堆栈,检查包装器回归、内存污染、工具纪律失败、隐藏修复循环和渲染损坏。生成按严重程度排序的发现和代码优先修复。对于构建智能体应用、自主循环或任何 LLM 驱动功能的开发者至关重要。 |
| origin | oh-my-agent-check |
| tools | Read, Write, Edit, Bash, Grep, Glob |
智能体架构审计
针对智能体系统的诊断工作流程,这些系统将失败隐藏在包装器层、过时内存、重试循环或传输/渲染变异之后。
何时激活
以下情况必须使用:
- 将任何智能体或 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
rg "completion|chat\.create|messages\.create|llm\.invoke"
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts
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:修复策略
默认修复顺序(代码优先,而非提示优先):
- 代码门控工具要求 — 在代码中强制执行,而不仅是提示文本
- 删除或缩小隐藏修复智能体 — 使回退具有明确合同
- 减少上下文重复 — 通过提示 + 历史 + 内存 + 蒸馏的相同信息
- 收紧内存准入 — 用户更正 > 智能体断言
- 收紧蒸馏触发器 — 不要压缩不应该压缩的内容
- 减少渲染变异 — 传递,不转换
- 转换为类型化 JSON 信封 — 结构化内部流,而非自由格式散文
严重性模型
| 级别 | 含义 | 操作 |
|---|
critical | 智能体可能自信地产生错误的操作行为 | 在下次发布前修复 |
high | 智能体频繁降低正确性或稳定性 | 本冲刺修复 |
medium | 正确性通常保持但输出脆弱或浪费 | 计划下一周期 |
low | 主要是化妆品或可维护性问题 | 积压工作 |
输出格式
按此顺序向用户展示发现:
- 按严重程度排序的发现(最关键在前)
- 架构诊断(哪一层破坏了什么以及为什么)
- 有序修复计划(代码优先,而非提示优先)
不要以赞美或摘要开头。如果系统损坏,直接说明。
快速诊断问题
审计智能体系统时,回答这些问题:
| # | 问题 | 如果是 → |
|---|
| 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",
相关技能
agent-introspection-debugging — 调试智能体运行时失败(循环、超时、状态错误)
agent-eval — 头对头基准测试智能体性能
security-review — 代码和配置的安全审计
autonomous-agent-harness — 设置自主智能体操作
agent-harness-construction — 从头开始构建智能体工具