zclaw_openfang/wiki/middleware.md

---
title: 中间件链
updated: 2026-04-21
status: active
tags: [module, middleware, runtime]
---

# 中间件链

> 从 [[index]] 导航。关联模块: [[chat]] [[butler]] [[memory]]

## 设计思想

**中间件是请求处理的管道，按优先级顺序执行。**

- 优先级 0-999，数值越小越先执行（`middleware.rs` 按升序排列）
- 每层中间件实现 `AgentMiddleware` trait，4个 hook 点: `before_completion` / `before_tool_call` / `after_tool_call` / `after_completion`
- 所有消息流（聊天、管家）都经过完整中间件链
- 中间件可返回 `Stop`/`Block`/`AbortLoop` 决策来中断流程

## 代码逻辑

### 14 层 Runtime 中间件（注册顺序见 `kernel/mod.rs:248-361`，执行按 priority 升序）

| # | 中间件 | 优先级 | 文件 | 职责 | 注册条件 |
|---|--------|--------|------|------|----------|
| 1 | EvolutionMiddleware | 78 | `middleware/evolution.rs` | 推送进化候选项到 system prompt | 始终 |
| 2 | ButlerRouter | 80 | `middleware/butler_router.rs` | 语义技能路由 + system prompt 增强 | 始终 |
| 3 | Compaction | 100 | `middleware/compaction.rs` | 超阈值时压缩对话历史 | `compaction_threshold > 0` |
| 4 | Memory | 150 | `middleware/memory.rs` | 对话后自动提取记忆 + 进化检查 | 始终 |
| 5 | Title | 180 | `middleware/title.rs` | 自动生成会话标题 | 始终 |
| 6 | SkillIndex | 200 | `middleware/skill_index.rs` | 注入技能索引到 system prompt | `!skill_index.is_empty()` |
| 7 | DanglingTool | 300 | `middleware/dangling_tool.rs` | 修复缺失的工具调用结果 | 始终 |
| 8 | ToolError | 350 | `middleware/tool_error.rs` | 格式化工具错误供 LLM 恢复 | 始终 |
| 9 | ToolOutputGuard | 360 | `middleware/tool_output_guard.rs` | 工具输出安全检查 | 始终 |
| 10 | Guardrail | 400 | `middleware/guardrail.rs` | shell_exec/file_write/web_fetch 安全规则 | 始终 |
| 11 | LoopGuard | 500 | `middleware/loop_guard.rs` | 防止工具调用无限循环 | 始终 |
| 12 | SubagentLimit | 550 | `middleware/subagent_limit.rs` | 限制并发子 agent | 始终 |
| 13 | TrajectoryRecorder | 650 | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 | 始终 |
| 14 | TokenCalibration | 700 | `middleware/token_calibration.rs` | Token 用量校准 | 始终 |

> **注意**: 注册顺序（代码中的 chain.register 调用顺序）与执行顺序不同。Chain 按 priority 升序排列后执行。

### 10 层 SaaS HTTP 中间件（`zclaw-saas/src/main.rs`）

| # | 中间件 | 职责 | 层级 |
|---|--------|------|------|
| 1 | public_rate_limit_middleware | 公共端点限流 (20次/分钟/IP) | 公共路由 |
| 2 | api_version_middleware | API 版本校验 | 公共 + 认证路由 |
| 3 | request_id_middleware | 请求 ID 注入 | 公共 + 认证路由 |
| 4 | rate_limit_middleware | 认证端点限流 (5次/分钟/IP) | 认证路由 |
| 5 | auth_middleware | JWT 认证 + 权限校验 | 认证路由 |
| 6 | TimeoutLayer | 请求超时 15s | 认证路由 |
| 7 | api_version_middleware (relay) | API 版本校验 | Relay 路由 |
| 8 | request_id_middleware (relay) | 请求 ID 注入 | Relay 路由 |
| 9 | quota_check_middleware | 配额检查 | Relay 路由 |
| 10 | CORS / 其他 layer | 跨域等 | 全局 |

### 优先级分类（Runtime，来自 `middleware.rs` 头注释）

| 范围 | 类别 | 包含的中间件 |
|------|------|-------------|
| 70-79 | 进化 | EvolutionMiddleware |
| 80-99 | 路由 | ButlerRouter |
| 100-199 | 上下文塑造 | Compaction, Memory |
| 200-399 | 能力 | SkillIndex, DanglingTool, ToolError, ToolOutputGuard |
| 400-599 | 安全 | Guardrail, LoopGuard, SubagentLimit |
| 600-799 | 遥测 | TrajectoryRecorder, TokenCalibration, Title |

### 中间件执行流

```
用户消息 → AgentLoop
  → chain.run_before_completion(ctx)
    → [按优先级升序] 每层 middleware.before_completion()
      → Continue: 继续下一层
      → Stop(reason): 中断循环，返回 reason
  → LLM 调用
  → (工具调用时) chain.run_before_tool_call()
      → Allow: 允许执行
      → Block(msg): 阻止，返回错误给 LLM
      → ReplaceInput: 替换参数后允许
      → AbortLoop: 立即终止整个循环
  → chain.run_after_tool_call()
  → chain.run_after_completion()
```

### 核心接口

```rust
// crates/zclaw-runtime/src/middleware.rs
trait AgentMiddleware: Send + Sync {
    fn name(&self) -> &str;
    fn priority(&self) -> i32 { 500 }
    async fn before_completion(&self, ctx: &mut MiddlewareContext) -> Result<MiddlewareDecision>;
    async fn before_tool_call(&self, ctx: &MiddlewareContext, tool_name: &str, tool_input: &Value) -> Result<ToolCallDecision>;
    async fn after_tool_call(&self, ctx: &mut MiddlewareContext, tool_name: &str, result: &Value) -> Result<()>;
    async fn after_completion(&self, ctx: &MiddlewareContext) -> Result<()>;
}
```

### 注册位置

`crates/zclaw-kernel/src/kernel/mod.rs:248-361` — `create_middleware_chain()` 方法，14 次 `chain.register()`（含 2 个条件注册: SkillIndex, Compaction）。注册顺序与执行顺序不同，chain 按 priority 升序排列后执行。

## 功能清单

| 优先级 | 中间件 | 功能 | 状态 |
|--------|--------|------|------|
| @78 | EvolutionMiddleware | 进化引擎注入 | ✅ |
| @80 | ButlerRouter | 管家语义路由 + XML fencing | ✅ |
| @100 | Compaction | 上下文压缩 (条件注册) | ✅ |
| @150 | Memory | 记忆自动提取 + 注入 | ✅ |
| @180 | Title | 对话标题生成 | ✅ |
| @200 | SkillIndex | 技能索引注入 (条件注册) | ✅ |
| @300 | DanglingTool | 悬空工具清理 | ✅ |
| @350 | ToolError | 工具错误处理 | ✅ |
| @360 | ToolOutputGuard | 工具输出守卫 | ✅ |
| @400 | Guardrail | 安全护栏 | ✅ |
| @500 | LoopGuard | 循环检测 (防无限) | ✅ |
| @550 | SubagentLimit | 子代理数量限制 | ✅ |
| @650 | TrajectoryRecorder | 轨迹记录+压缩 | ✅ |
| @700 | TokenCalibration | Token 校准 | ✅ |

## 测试链路

| 功能 | 测试文件 | 测试数 | 覆盖状态 |
|------|---------|--------|---------|
| 管家路由 | middleware/butler_router.rs | 12 | ✅ |
| 进化中间件 | middleware/evolution.rs | 4 | ✅ |
| 轨迹记录 | middleware/trajectory_recorder.rs | 4 | ✅ |
| 其余 11 层 | — | 0 | ⚠️ 无独立测试 |
| **合计** | 3/14 文件有测试 | **20** | |

## 关联模块

- [[butler]] — ButlerRouter 是管家模式的核心
- [[chat]] — 每条消息经过完整中间件链
- [[memory]] — Memory 中间件从对话提取记忆
- [[hands-skills]] — SkillIndex 中间件注入技能索引

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-runtime/src/middleware.rs` | AgentMiddleware trait + MiddlewareChain |
| `crates/zclaw-runtime/src/middleware/` | 14 个中间件实现 (14个 .rs 文件) |
| `crates/zclaw-kernel/src/kernel/mod.rs:248-361` | 注册入口 |
| `crates/zclaw-saas/src/main.rs` | SaaS HTTP 中间件注册 (10 层) |

## 已知问题

- ✅ **TrajectoryRecorder 未注册** — V13-GAP-01 已修复 (在 @650 注册)
- ✅ **Admin 端点 404 而非 403** — admin_guard_middleware 已修复
- ⚠️ **SkillIndex 条件注册** — 无技能时不注册，长期观察
- ⚠️ **11/14 中间件无独立测试** — 仅 butler_router/evolution/trajectory_recorder 有测试