中间件架构原理
什么是中间件
中间件（Middleware）是一种用于拦截、修改、控制和增强 Agent 执行流程的机制。
允许开发者在模型调用前后、Agent 启动前后或工具调用前后插入自定义逻辑，从而实现日志记录、权限控制、上下文压缩等功能，而无需修改 Agent 的核心业务逻辑。
借鉴了 Web 开发（如 Express/Django）中的中间件模式。
核心设计目标
- 关注点分离：每个中间件只处理单一功能
- 可组合性：多个中间件可链式调用
- 可测试性：支持独立单元测试
- 生产就绪：内置隐私保护、成本管控等企业级能力
核心设计理念
中间件的设计严格遵循了 SOLID 原则，这些原则不仅仅是理论概念，而是实际指导开发的行动准则。
单一职责原则（SRP）
每一个中间件都专注于解决一个具体问题。例如，SummarizationMiddleware 只负责上下文压缩，ToolRetryMiddleware 只处理重试逻辑。这种设计使得中间件易于理解、测试和维护。
开闭原则（OCP）
ModelSelectorMiddleware 展示了开闭原则的应用。它对扩展开放（可以添加新的模型选择策略），对修改封闭（核心逻辑无需改变）。开发者可以通过配置或子类化来扩展行为，而无需修改源代码。
里氏替换原则（LSP）
子类必须能够替换其父类而不破坏程序的正确性。中间件系统中的所有中间件都可以替换 BaseMiddleware，而不影响整体功能。
装饰器模式
通过 wrap_model_call、wrap_tool_call 等方法，装饰器模式允许在运行时动态添加功能。这使得可以在不修改核心 Agent 逻辑的情况下，为其添加各种增强功能。
责任链模式
多个中间件的顺序处理体现了责任链模式。每个中间件都有机会处理请求，也可以将处理权传递给下一个中间件。这种设计使得中间件可以灵活组合，形成不同的处理流程。
洋葱模 型
借助中间件，一个React Agent的运行模型，就可以由这种：
变为这种：
中间件能做什么
| 功能 | 说明 |
|---|---|
| 日志记录 | 记录请求/响应 |
| 权限控制 | 验证用户身份 |
| 上下文压缩 | 减少 token 消耗 |
| 重试机制 | 处理临时失败 |
| 成本管控 | 限制 API 调用 |
| 安全过滤 | PII 数据脱敏 |
解决的问题
中间件主要解决了 Agent 在生产环境落地时的"不可控"问题：
| 风险类型 | 问题 | 解决方案 |
|---|---|---|
| 成本风险 | 对话历史过长导致 Token 溢出 | 自动摘要中间件压缩上下文 |
| 成本风险 | 简单问题消耗高级模型资源 | 根据问题复杂度智能选择模型 |
| 安全风险 | 泄露 PII（手机号、身份证号等） | PII 脱敏中间件过滤敏感信息 |
| 安全风险 | 恶意工具调用 | 审批中间件人工审核 |
| 调试黑盒 | Agent 思考过程难以追踪 | 监控中间件记录完整执行链 |
| 死循环 | Agent 工具调用无限循环 | 熔断中间件自动触发保护 |