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

# 中间件链

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

## 设计思想

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

- 优先级 0-100，数值越大越先执行
- 每层中间件可以: 修改请求 / 拦截响应 / 记录日志 / 注入上下文
- 所有消息流（聊天、管家）都经过完整中间件链

## 代码逻辑

### 14 层中间件

关键中间件（按优先级排序）:

| 优先级 | 中间件 | 文件 | 职责 |
|--------|--------|------|------|
| 90 | DataMasking | `middleware/data_masking.rs` | 请求发送前数据脱敏 (手机号/身份证) |
| ~500 | ButlerRouter | `middleware/butler_router.rs` | 4域关键词分类 + system prompt 增强 |
| 650 | TrajectoryRecorder | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 |

其他 11 层: 认证、速率限制、日志、技能注入、记忆注入等。

### 中间件执行流

```
用户消息
  → [优先级 90] DataMasking — 脱敏敏感数据
  → [优先级 ~500] ButlerRouter — 关键词分类 + prompt 增强
  → [优先级 650] TrajectoryRecorder — 记录请求轨迹
  → [其他层] 认证/限流/日志/技能/记忆
  → LLM 调用
  → 响应原路返回
```

### 注册位置

中间件在 `crates/zclaw-runtime/` 中注册，Kernel 启动时加载。

## 关联模块

- [[butler]] — ButlerRouter 是管家模式的核心
- [[chat]] — 每条消息经过完整中间件链
- [[memory]] — 记忆注入层从 FTS5 检索并注入 system prompt

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-runtime/src/middleware/` | 所有中间件实现 |
| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 |
| `crates/zclaw-runtime/src/middleware/data_masking.rs` | 数据脱敏 |
| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录 |