docs(wiki): Phase B+C完成 — middleware/saas/security/memory 5节模板重构

- middleware.md: 集成契约+3不变量+执行流 (157→136行)
- saas.md: 移除安全重复→引用security.md+Token Pool算法 (231→173行)
- security.md: 吸收saas认证内容成为安全唯一真相源 (158→199行)
- memory.md: 最大压缩363→147行+Hermes洞察提炼+4不变量

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

wiki/middleware.md

@@ -1,94 +1,105 @@
 ---
 title: 中间件链
-updated: 2026-04-21
+updated: 2026-04-22
 status: active
 tags: [module, middleware, runtime]
 ---
 
 # 中间件链
 
-> 从 [[index]] 导航。关联模块: [[chat]] [[butler]] [[memory]]
+> 从 [[index]] 导航。关联模块: [[chat]] [[butler]] [[memory]] [[hands-skills]]
 
-## 设计思想
+## 1. 设计决策
 
-**中间件是请求处理的管道，按优先级顺序执行。**
+**中间件是请求处理的管道，每条聊天消息都经过完整链路。**
 
-- 优先级 0-999，数值越小越先执行（`middleware.rs` 按升序排列）
-- 每层中间件实现 `AgentMiddleware` trait，4个 hook 点: `before_completion` / `before_tool_call` / `after_tool_call` / `after_completion`
-- 所有消息流（聊天、管家）都经过完整中间件链
-- 中间件可返回 `Stop`/`Block`/`AbortLoop` 决策来中断流程
+- **WHY 优先级排序 (0-999)**: 数值越小越先执行。宽范围设计允许在任意位置插入新中间件而无需重新编号。
+- **WHY 注册顺序 != 执行顺序**: `kernel/mod.rs` 中 14 次 `chain.register()` 的代码顺序与运行时顺序无关，chain 按 `priority()` 升序排列后执行。
+- **WHY 6 类 14 层**: 进化(70-79) -> 路由(80-99) -> 上下文(100-199) -> 能力(200-399) -> 安全(400-599) -> 遥测(600-799)，优先级范围即执行阶段。
+- **WHY Stop/Block/AbortLoop**: 细粒度流控 -- Stop 中断 LLM 循环，Block 阻止单次工具调用，AbortLoop 终止整个 Agent 循环。命中后跳过所有后续中间件。
 
-## 代码逻辑
+## 2. 关键文件 + 数据流
 
-### 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 用量校准 | 始终 |
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-runtime/src/middleware.rs` | `AgentMiddleware` trait + `MiddlewareChain` 执行引擎 |
+| `crates/zclaw-runtime/src/middleware/` | 14 个中间件实现 (.rs) |
+| `crates/zclaw-kernel/src/kernel/mod.rs:248-361` | `create_middleware_chain()` 注册入口 (14 次 register) |
+| `crates/zclaw-saas/src/main.rs` | SaaS HTTP 中间件注册 (10 层) |
 
-> **注意**: 注册顺序（代码中的 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()
+用户消息 -> AgentLoop
+  -> chain.run_before_completion(ctx)
+    -> [按 priority 升序] 每层 middleware.before_completion()
+      -> Continue: 下一层 | Stop(reason): 中断循环
+  -> LLM 调用
+  -> (工具调用时) chain.run_before_tool_call()
+    -> Allow | Block(msg) | ReplaceInput | AbortLoop
+  -> 工具执行
+  -> chain.run_after_tool_call()
+  -> chain.run_after_completion()
 ```
 
+### 集成契约
+
+| 方向 | 模块 | 接口 | 触发时机 |
+|------|------|------|----------|
+| Called by <- | kernel | `kernel/mod.rs:create_middleware_chain()` | Kernel 启动 |
+| Calls -> | runtime | `MiddlewareChain::run_before_completion()` | 每条聊天请求 |
+| Called by <- | saas | HTTP relay handler | SaaS relay 路由 |
+| Provides -> | all | `AgentMiddleware` trait | 14 个实现 |
+
+## 3. 代码逻辑
+
+### 14 层 Runtime 中间件
+
+| 优先级 | 中间件 | 文件 | 职责 | 注册条件 |
+|--------|--------|------|------|----------|
+| @78 | EvolutionMiddleware | `evolution.rs` | 推送进化候选项到 system prompt | 始终 |
+| @80 | ButlerRouter | `butler_router.rs` | 语义技能路由 + system prompt 增强 + XML fencing | 始终 |
+| @100 | Compaction | `compaction.rs` | 超阈值时压缩对话历史 | `compaction_threshold > 0` |
+| @150 | Memory | `memory.rs` | 对话后自动提取记忆 + 注入检索结果 | 始终 |
+| @180 | Title | `title.rs` | 自动生成会话标题 | 始终 |
+| @200 | SkillIndex | `skill_index.rs` | 注入技能索引到 system prompt | `!skill_index.is_empty()` |
+| @300 | DanglingTool | `dangling_tool.rs` | 修复缺失的工具调用结果 | 始终 |
+| @350 | ToolError | `tool_error.rs` | 格式化工具错误供 LLM 恢复 | 始终 |
+| @360 | ToolOutputGuard | `tool_output_guard.rs` | 工具输出安全检查 | 始终 |
+| @400 | Guardrail | `guardrail.rs` | shell_exec/file_write/web_fetch 安全规则 | 始终 |
+| @500 | LoopGuard | `loop_guard.rs` | 防止工具调用无限循环 | 始终 |
+| @550 | SubagentLimit | `subagent_limit.rs` | 限制并发子 agent | 始终 |
+| @650 | TrajectoryRecorder | `trajectory_recorder.rs` | 轨迹记录 + 压缩 | 始终 |
+| @700 | TokenCalibration | `token_calibration.rs` | Token 用量校准 | 始终 |
+
+> 注册顺序 (代码) 与执行顺序 (priority) 不同。Chain 按 priority 升序排列后执行。
+
+### 10 层 SaaS HTTP 中间件
+
+| 层级 | 中间件 | 职责 |
+|------|--------|------|
+| 公共路由 | `public_rate_limit_middleware` | 20次/分钟/IP |
+| 公共+认证 | `api_version_middleware` | API 版本校验 |
+| 公共+认证 | `request_id_middleware` | 请求 ID 注入 |
+| 认证路由 | `rate_limit_middleware` | 5次/分钟/IP |
+| 认证路由 | `auth_middleware` | JWT 认证 + 权限 |
+| 认证路由 | `TimeoutLayer` | 请求超时 15s |
+| Relay 路由 | `api_version_middleware` | 版本校验 |
+| Relay 路由 | `request_id_middleware` | 请求 ID |
+| Relay 路由 | `quota_check_middleware` | 配额检查 |
+| 全局 | CORS / 其他 layer | 跨域等 |
+
+### 不变量
+
+- Priority 升序: 0-999, 数值越小越先执行
+- 注册顺序 != 执行顺序; chain 按 priority 运行时排序
+- Stop/Block/AbortLoop 立即中断, 不执行后续中间件
+
 ### 核心接口
 
 ```rust
-// crates/zclaw-runtime/src/middleware.rs
 trait AgentMiddleware: Send + Sync {
     fn name(&self) -> &str;
     fn priority(&self) -> i32 { 500 }
@@ -99,58 +110,27 @@ trait AgentMiddleware: Send + Sync {
 }
 ```
 
-### 注册位置
+## 4. 活跃问题 + 陷阱
 
-`crates/zclaw-kernel/src/kernel/mod.rs:248-361` — `create_middleware_chain()` 方法，14 次 `chain.register()`（含 2 个条件注册: SkillIndex, Compaction）。注册顺序与执行顺序不同，chain 按 priority 升序排列后执行。
+### 活跃问题
 
-## 功能清单
+- **11/14 中间件无独立测试** (P2): 仅 `butler_router`(12) / `evolution`(4) / `trajectory_recorder`(4) 有测试，共 20 个。其余 11 层依赖集成测试覆盖。
+- **SkillIndex 条件注册** (长期观察): 无技能时不注册，非 bug 但需关注空技能场景下的行为一致性。
 
-| 优先级 | 中间件 | 功能 | 状态 |
-|--------|--------|------|------|
-| @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 校准 | ✅ |
+### 历史陷阱
 
-## 测试链路
+| 问题 | 根因 | 修复 |
+|------|------|------|
+| TrajectoryRecorder 未注册 | V13-GAP-01: 遗漏 `chain.register()` 调用 | 已在 @650 注册 |
+| Admin 端点 404 而非 403 | admin_guard_middleware 返回码错误 | 已修复为 403 |
+| DataMasking 中间件 | 增加延迟但无实际安全收益 | 04-22 移除 |
 
-| 功能 | 测试文件 | 测试数 | 覆盖状态 |
-|------|---------|--------|---------|
-| 管家路由 | middleware/butler_router.rs | 12 | ✅ |
-| 进化中间件 | middleware/evolution.rs | 4 | ✅ |
-| 轨迹记录 | middleware/trajectory_recorder.rs | 4 | ✅ |
-| 其余 11 层 | — | 0 | ⚠️ 无独立测试 |
-| **合计** | 3/14 文件有测试 | **20** | |
+## 5. 变更日志
 
-## 关联模块
-
-- [[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 有测试
+| 日期 | 变更 | 影响 |
+|------|------|------|
+| 04-22 | DataMasking 中间件移除 | 14->14 层 (替换为无), 减少 1 层无收益处理 |
+| 04-22 | 跨会话记忆修复 | Memory 中间件去重+跨会话注入修复 |
+| 04-22 | Wiki 一致性校准 | 数字与代码验证对齐 |
+| 04-21 | Embedding 接通 | SkillIndex 路由 TF-IDF->Embedding+LLM fallback |
+| 04-15 | Heartbeat 统一健康系统 | TrajectoryRecorder 痛点感知增强 |