agent-architecture-audit

用途

Agent Architecture Audit 是一个面向智能体（Agent）与 LLM 应用的全栈诊断工作流，专门用于排查那些被包装层、陈旧记忆、重试循环或传输/渲染变更所掩盖的故障。它不用于通用代码调试、代码审查、安全扫描、性能基准测试或编写新功能，而是聚焦于智能体系统架构层面的失效诊断。

主要能力

该技能围绕“12 层智能体栈”展开审计，每一层都可能污染最终答案：

系统提示（System prompt）：指令冲突、指令膨胀
会话历史（Session history）：上一轮注入的陈旧上下文
长期记忆（Long-term memory）：跨会话污染、旧话题进入新对话
蒸馏（Distillation）：压缩产物作为伪事实重新进入
主动召回（Active recall）：冗余的再摘要层浪费上下文
工具选择（Tool selection）：工具路由错误、模型跳过必需工具
工具执行（Tool execution）：幻觉执行——声称调用但实际未调用
工具解读（Tool interpretation）：误读或忽略工具输出
答案塑形（Answer shaping）：最终响应格式损坏
平台渲染（Platform rendering）：传输层变更（UI、API、CLI 篡改有效答案）
隐藏修复循环（Hidden repair loops）：静默回退/重试智能体运行第二次 LLM 调用
持久化（Persistence）：过期状态或缓存产物被当作实时证据复用

技能还归纳了五类常见失败模式：包装层回归（Wrapper Regression）、记忆污染（Memory Contamination）、工具纪律失效（Tool Discipline Failure）、渲染/传输损坏（Rendering/Transport Corruption）、隐藏智能体层（Hidden Agent Layers），并给出各自的症状描述。

使用方式

审计按四个阶段推进：

阶段 1：范围界定（Scope）——明确目标系统、入口点、模型栈、症状、时间窗口以及需要审计的层。

阶段 2：证据收集（Evidence Collection）——从代码库收集源码（智能体循环、工具路由、记忆准入、提示组装）、日志、配置、记忆文件，并使用 rg 搜索反模式，例如：

# Tool requirements expressed only in prompt text (not code)
rg "must.*tool|必须.*工具|required.*call" --type md

# Tool execution without validation
rg "tool_call|toolCall|tool_use" --type py --type ts

# Hidden LLM calls outside main agent loop
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Memory admission without user-correction priority
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Fallback loops that run additional LLM calls
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Silent output mutation
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

阶段 3：故障映射（Failure Mapping）——对每个发现记录症状、机制、来源层、根因、证据（file:line 或 log:row）以及置信度（0.0 到 1.0）。

阶段 4：修复策略（Fix Strategy）——默认修复顺序为代码优先而非提示词优先：用代码门控工具要求；移除或收窄隐藏修复智能体；减少上下文重复；收紧记忆准入（用户纠正优先于智能体断言）；收紧蒸馏触发条件；减少渲染变更（直通而非转换）；转换为类型化 JSON 信封。

技能还提供严重度模型（critical/high/medium/low 及对应行动）、输出格式（按严重度排序的发现、架构诊断、有序修复计划，不先给赞美或总结）、快速诊断问题清单、应避免的反模式，以及结构化报告 Schema（ecc.agent-architecture-audit.report.v1），包含 executive_verdict、scope、findings、ordered_fix_plan 等字段。

适用场景

该技能标记为强制（MANDATORY）用于：将任何智能体或 LLM 应用发布到生产环境；发布带工具调用、记忆或多步工作流的功能；添加包装层后智能体行为退化；用户报告“智能体越来越差”或“工具不稳定”；同一模型在 playground 正常但在包装内失效；调试智能体行为超过 15 分钟未找到根因。

在以下情况尤为关键：新增提示层、工具定义或记忆系统；系统中不同智能体行为不一致；模型昨天正常今天却产生幻觉；怀疑存在隐藏的修复/重试循环在静默篡改响应。

限制

该技能不适用于通用代码调试（应使用 agent-introspection-debugging）、代码审查（应使用语言特定的 reviewer 智能体）、安全扫描（应使用 security-review 或 security-review/scan）、智能体性能基准测试（应使用 agent-eval）以及编写新功能（应使用相应的工作流技能）。

技能介绍

用途

主要能力

使用方式

适用场景

限制

相关技能