zclaw_openfang/wiki/middleware.md

title, updated, status, tags

title	updated	status	tags
中间件链	2026-04-17	active	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 决策来中断流程

代码逻辑

15 层 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	DataMasking	90	middleware/data_masking.rs	手机号/身份证等敏感数据脱敏	始终
4	Compaction	100	middleware/compaction.rs	超阈值时压缩对话历史	compaction_threshold > 0
5	Memory	150	middleware/memory.rs	对话后自动提取记忆 + 进化检查	始终
6	Title	180	middleware/title.rs	自动生成会话标题	始终
7	SkillIndex	200	middleware/skill_index.rs	注入技能索引到 system prompt	!skill_index.is_empty()
8	DanglingTool	300	middleware/dangling_tool.rs	修复缺失的工具调用结果	始终
9	ToolError	350	middleware/tool_error.rs	格式化工具错误供 LLM 恢复	始终
10	ToolOutputGuard	360	middleware/tool_output_guard.rs	工具输出安全检查	始终
11	Guardrail	400	middleware/guardrail.rs	shell_exec/file_write/web_fetch 安全规则	始终
12	LoopGuard	500	middleware/loop_guard.rs	防止工具调用无限循环	始终
13	SubagentLimit	550	middleware/subagent_limit.rs	限制并发子 agent	始终
14	TrajectoryRecorder	650	middleware/trajectory_recorder.rs	轨迹记录 + 压缩	始终
15	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, DataMasking
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()

核心接口

// 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() 方法，15 次 chain.register()（含 2 个条件注册: SkillIndex, Compaction）。注册顺序与执行顺序不同，chain 按 priority 升序排列后执行。

关联模块

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

关键文件

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