agent-architecture-audit

Agent 架构审计

检查原始模型调用与用户可见输出之间的每一层，诊断 Agent 系统中的故障。

契约

输入：

• Agent 或 LLM 应用代码库、失败的运行、跟踪记录、日志或症状
• 可选的模型／提供商列表、工具定义、记忆文件和 UI 输出

输出：

• 按严重程度排序且附有证据引用的发现
• 逐层故障诊断
• 有序的修复计划，优先采用代码门控，而非仅修改提示词

创建／修改：

• 审计模式下不创建或修改任何内容
• 仅在明确要求时进行后续修复

外部副作用：

• 默认无
• 仅在已有授权时使用外部日志、可观测性工具或生产系统

需要确认：

• 更改提示词、记忆、工具契约、持久化、生产配置或用户数据之前

委派给：

• 普通软件缺陷交给 debug
• 基准测试设计交给 evaluation（包括其 LLM 作为评审者模式）
• 提示注入、机密信息、身份验证或特权工具风险交给 security-audit

适用场景

• Agent 在模型游乐场或直接 API 调用中正常工作，但在应用中失败。
• 添加封装层、编排层、记忆系统或工具路由器后，质量出现退化。
• 模型跳过必需工具、声称使用了实际未调用的工具，或误读工具输出。
• 旧对话中的事实、过时记忆或压缩后的摘要泄漏到新任务中。
• 日志显示答案正确，但 CLI、API、UI、流式传输层或渲染器呈现了不同结果。
• 隐藏的重试、回退、修复或摘要循环可能正在篡改输出。

不要用于一般代码审查——仅在故障可能出现在 Agent 技术栈中时使用。

分层模型

从源指令到最终输出，审计整个技术栈：

层	可能出现的故障
系统提示词	冲突、冗长、规则过时、优先级不明确
会话历史	旧轮次占据主导地位或与当前任务相矛盾
长期记忆	跨项目信息泄漏、偏好过时、Agent 写入的事实
摘要提炼	压缩过程将猜测变成了伪事实
主动召回	冗余摘要浪费上下文，或重新引入旧上下文
工具选择	代码中将必需工具设为可选，未强制执行
工具执行	调用缺失、调用失败、参数未经验证
工具解读	输出被忽略、过度信任或解读反了
答案整形	推理后格式、架构、Markdown 或 JSON 被更改
传输／渲染	流式传输、API、CLI 或 UI 篡改了有效内容
隐藏的修复循环	第二次模型调用在静默中改写答案
持久化	缓存产物或过期状态被当作实时证据重用

审计流程

1. 确定系统范围

识别：

• 用户入口点和输出界面
• 模型提供商、模型等级以及重试／回退行为
• 提示词组装路径和指令来源
• 记忆、检索、压缩和持久化路径
• 工具架构、工具路由和执行验证
• 已知症状，以及这些症状首次出现时的版本发布或提交

2. 收集证据

搜索：

• 提示词模板和指令注入点
• 工具架构、路由器、验证器和执行日志
• 记忆准入、检索和压缩代码
• 主 Agent 循环之外的提供商调用
• 回退、重试、修复或输出改写环节
• 响应序列化、Markdown 渲染、JSON 解析和流处理

优先提供文件和行号证据。如果有日志，请比较原始模型输出、后处理输出、传输后的输出和渲染后的输出。

3. 梳理故障机制

针对每个疑似问题，记录：

• 症状：用户看到的内容
• 层：问题从哪一层引入
• 机制：该层如何改变行为
• 根本原因：代码、配置、提示词、记忆、传输或流程
• 证据：文件、行号、跟踪 ID、日志行或复现的运行
• 置信度：高、中或低

4. 优先修复项

优先按以下顺序修复：

1. 在代码中强制要求使用工具。
2. 移除或公开隐藏的修复 Agent 和备用 Agent。
3. 减少提示词、记忆、历史记录和摘要之间的重复上下文。
4. 收紧记忆准入规则，让用户更正优先于 Agent 的断言。
5. 缩小压缩触发范围，并保留不确定性标记。
6. 对已经有效的输出直接透传，而不是重写。
7. 在内部协议边界使用类型化封装。
8. 添加追踪测试，对比原始、处理后、传输后和渲染后的输出。

不要仅通过加强提示词措辞来解决工具使用规范、记忆安全或传输损坏问题。

严重性

严重性	含义
严重	系统可能自信地执行错误或不安全的操作
高	在正常使用中，正确性或稳定性经常下降
中	Agent 通常能够正常工作，但技术栈脆弱、浪费资源或难以调试
低	可维护性、可观测性或输出外观问题

输出格式

先列出发现：

## Findings

| Severity | Layer | Finding | Evidence | Fix |
| --- | --- | --- | --- | --- |
| High | Tool selection | Required retrieval is prompt-only and can be skipped | `src/agent/router.ts:42` | Gate final answer on retrieval result |

## Diagnosis

[Explain which layer corrupts the behavior and why.]

## Fix Plan

1. [Code-first fix]
2. [Validation]
3. [Follow-up hardening]

如果没有发现问题，请明确说明，并列出已检查的证据和仍然存在的盲点。

反模式

• 未测试封装层行为就归咎于模型。
• 在没有代码强制要求的情况下，接受“必须使用工具”这类提示词文本。
• 将压缩后的摘要视为事实依据。
• 允许隐藏的模型调用在没有追踪记录的情况下重写最终输出。
• 未对比内部输出与交付输出就报告状态正常。