27b98cae6f
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
关键数字修正: - Rust 77K行(274 .rs)、Tauri 189命令、SaaS 137 routes - Admin V2 17页、SaaS 16模块(含industry)、@reserved 22 - SQL 20迁移/42表、TODO/FIXME 4个、dead_code 16 内容更新: - known-issues: V13-GAP 全部标记已修复 + 三端联调测试结果 - middleware: 14层 runtime + 10层 SaaS HTTP 完整清单 - saas: industry模块、路由模块13个、数据表42个 - routing: Store含industryStore、21个Store文件 - butler: 行业配置接入ButlerPanel、4内置行业 - log: 三端联调+V13修复记录追加
117 lines
5.2 KiB
Markdown
117 lines
5.2 KiB
Markdown
---
|
||
title: 中间件链
|
||
updated: 2026-04-14
|
||
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`）
|
||
|
||
| # | 中间件 | 文件 | 职责 | 注册条件 |
|
||
|---|--------|------|------|----------|
|
||
| 1 | ButlerRouter | `middleware/butler_router.rs` | 语义技能路由 + system prompt 增强 | 始终 |
|
||
| 2 | DataMasking | `middleware/data_masking.rs` | 手机号/身份证等敏感数据脱敏 | 始终 |
|
||
| 3 | Compaction | `middleware/compaction.rs` | 超阈值时压缩对话历史 | `compaction_threshold > 0` |
|
||
| 4 | Memory | `middleware/memory.rs` | 对话后自动提取记忆 | 始终 |
|
||
| 5 | LoopGuard | `middleware/loop_guard.rs` | 防止工具调用无限循环 | 始终 |
|
||
| 6 | TokenCalibration | `middleware/token_calibration.rs` | Token 用量校准 | 始终 |
|
||
| 7 | SkillIndex | `middleware/skill_index.rs` | 注入技能索引到 system prompt | `!skill_index.is_empty()` |
|
||
| 8 | Title | `middleware/title.rs` | 自动生成会话标题 | 始终 |
|
||
| 9 | DanglingTool | `middleware/dangling_tool.rs` | 修复缺失的工具调用结果 | 始终 |
|
||
| 10 | ToolError | `middleware/tool_error.rs` | 格式化工具错误供 LLM 恢复 | 始终 |
|
||
| 11 | ToolOutputGuard | `middleware/tool_output_guard.rs` | 工具输出安全检查 | 始终 |
|
||
| 12 | Guardrail | `middleware/guardrail.rs` | shell_exec/file_write/web_fetch 安全规则 | 始终 |
|
||
| 13 | SubagentLimit | `middleware/subagent_limit.rs` | 限制并发子 agent | 始终 |
|
||
| 14 | TrajectoryRecorder | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 | 始终 (V13-FIX-01 已注册) |
|
||
|
||
### 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` 头注释）
|
||
|
||
| 范围 | 类别 | 包含的中间件 |
|
||
|------|------|-------------|
|
||
| 100-199 | 上下文塑造 | Compaction, Memory |
|
||
| 200-399 | 能力 | SkillIndex, Guardrail |
|
||
| 400-599 | 安全 | LoopGuard, DataMasking |
|
||
| 600-799 | 遥测 | TokenCalibration, Title, TrajectoryRecorder |
|
||
|
||
### 中间件执行流
|
||
|
||
```
|
||
用户消息 → 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()` + 1 个条件注册 (SkillIndex)。
|
||
|
||
## 关联模块
|
||
|
||
- [[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 层) |
|