docs(wiki): 全量代码验证驱动更新 — 10页基于实际扫描非文档推测

关键数字修正: - Rust 74.5K行(原66K), Tauri命令 183(原182), SaaS路由 121 - 前端组件 104, lib/ 85文件, Store 17+4子store - TODO/FIXME 仅 8 个(前端4+Rust4) 内容增强: - 中间件完整14层注册清单含注册条件和优先级分类 - Store完整目录结构, Pipeline完整目录树 - Hands测试分布, Memory 16个Tauri命令列表 - 管家模式: 关键词路由→语义路由(TF-IDF)修正 - 代码健康度指标新增
2026-04-11 01:05:15 +08:00
parent 36a1c87d87
commit b3f97d6525
12 changed files with 415 additions and 132 deletions
--- a/wiki/butler.md
+++ b/wiki/butler.md
@@ -15,7 +15,7 @@ tags: [module, butler, interaction]

 设计决策:
 1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启
-2. **4 域关键词分类** — healthcare / data_report / policy / meeting，自动增强 system prompt
+2. **语义路由** — SemanticSkillRouter 用 TF-IDF 匹配 75 个技能，替代简单关键词
 3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议
 4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁

@@ -26,9 +26,11 @@ tags: [module, butler, interaction]
 ```
 用户消息
  → ButlerRouter 中间件 (middleware/butler_router.rs)
-    → SemanticSkillRouter TF-IDF 匹配 75 个技能
-    → 4 域关键词分类
-    → 增强 system prompt (领域专用指令)
+    → ButlerRouterBackend trait → SemanticRouterAdapter
+      → SemanticSkillRouter (zclaw-skills/src/semantic_router.rs)
+        → TF-IDF 计算与 75 个技能的相似度
+        → 返回 RoutingHint { category, confidence, skill_id }
+    → 增强 system prompt (匹配的技能上下文)
  → LLM 响应
  → PainAggregator 提取痛点
    → PainStorage (内存 Vec 热缓存 + SQLite 持久层)
@@ -37,9 +39,21 @@ tags: [module, butler, interaction]
    → 基于痛点生成解决方案提案
 ```

+### 语义路由桥接（kernel 层）
+
+```rust
+// crates/zclaw-kernel/src/kernel/mod.rs:196-231
+struct SemanticRouterAdapter { router: Arc<SemanticSkillRouter> }
+impl ButlerRouterBackend for SemanticRouterAdapter {
+    async fn classify(&self, query: &str) -> Option<RoutingHint> { ... }
+}
+```
+
+这是 kernel 依赖 zclaw-runtime + zclaw-skills 的桥接点。
+
 ### 冷启动 (新用户引导)

-入口: `desktop/src/hooks/use-cold-start.ts`
+入口: `desktop/src/hooks/use-cold-start.ts`（lib/ 下有同名文件）

 ```
 idle → (检测新用户) → greeting_sent → waiting_response → completed
@@ -58,9 +72,33 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed
 简洁侧边栏: `desktop/src/components/SimpleSidebar.tsx`
 管家面板: `desktop/src/components/ButlerPanel.tsx` (3 区: 洞察/方案/记忆)

+### Tauri 命令
+
+5 个 butler 命令 (已标注 @reserved):
+
+```rust
+// desktop/src-tauri/src/intelligence/pain_aggregator.rs
+butler_list_pain_points
+butler_record_pain_point
+butler_generate_solution
+butler_list_proposals
+butler_update_proposal_status
+```
+
+### Intelligence 层文件结构
+
+```
+desktop/src-tauri/src/intelligence/
+├── compactor.rs      (5 commands: token estimation + compaction)
+├── heartbeat.rs      (10 commands: heartbeat engine CRUD)
+├── identity.rs       (16 commands: agent identity manager)
+├── pain_aggregator.rs (5 commands: butler pain points)
+└── reflection.rs     (7 commands: reflection engine)
+```
+
 ## 关联模块

- [[middleware]] — ButlerRouter 是中间件链中的一层
+- [[middleware]] — ButlerRouter 是中间件链中的第一层
 - [[chat]] — 消息流经过管家路由增强
 - [[memory]] — 痛点存储在 memory 子系统
 - [[hands-skills]] — 语义路由使用 75 个技能的 TF-IDF
@@ -69,15 +107,12 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed

 | 文件 | 职责 |
 |------|------|
-| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 (4域分类) |
+| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 + ButlerRouterBackend trait |
+| `crates/zclaw-skills/src/semantic_router.rs` | SemanticSkillRouter TF-IDF 实现 |
+| `crates/zclaw-kernel/src/kernel/mod.rs:196-231` | SemanticRouterAdapter 桥接 |
 | `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点双写 (内存+SQLite) |
 | `crates/zclaw-kernel/src/intelligence/solution_generator.rs` | 方案生成 |
 | `desktop/src/hooks/use-cold-start.ts` | 冷启动 4 阶段 |
 | `desktop/src/store/uiModeStore.ts` | 双模式切换 |
 | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 |
 | `desktop/src/components/ButlerPanel.tsx` | 管家面板 (洞察/方案/记忆) |
-
-## Tauri 命令
-
-6 个 butler 专属命令 (已标注 @reserved):
-`butler_get_pain_points`, `butler_get_solutions`, `butler_delegate_task`, 等
--- a/wiki/chat.md
+++ b/wiki/chat.md
@@ -30,7 +30,7 @@ tags: [module, chat, stream]

 ### 发送消息流

-入口: `streamStore.sendMessage(content)` → `streamStore.ts`
+入口: `streamStore.sendMessage(content)` → `store/chat/streamStore.ts`

 ```
 sendMessage(content)
@@ -51,7 +51,7 @@ sendMessage(content)
  → 5 分钟超时守护 (kernel-chat.ts:76) 防止流挂起
 ```

-### Store 拆分 (4 Store)
+### Store 拆分 (5 Store)

 原来 908 行的 ChatStore 已拆分为:

@@ -61,6 +61,14 @@ sendMessage(content)
 | conversationStore | `store/chat/conversationStore.ts` | 会话管理、当前模型 |
 | messageStore | `store/chat/messageStore.ts` | 消息持久化 |
 | chatStore | `store/chat/chatStore.ts` | 聊天通用状态 |
+| artifactStore | `store/chat/artifactStore.ts` | 聊天产物/附件 |
+
+### 前端 Tauri 命令映射
+
+```
+kernel_chat / agent_chat / agent_chat_stream  → 发送消息
+cancel_stream                                  → 取消流式响应
+```

 ### 模型切换

@@ -85,6 +93,7 @@ UI 选择模型 → conversationStore.currentModel = newModel
 |------|------|
 | `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
 | `desktop/src/store/chat/conversationStore.ts` | 会话管理 |
+| `desktop/src/store/chat/artifactStore.ts` | 聊天产物管理 |
 | `desktop/src/lib/kernel-chat.ts` | Kernel ChatStream (Tauri) |
 | `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream |
 | `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) |
--- a/wiki/development.md
+++ b/wiki/development.md
@@ -23,23 +23,26 @@ tags: [development, conventions]

 | 禁止 | 原因 |
 |------|------|
-| 新增 SaaS API 端点 | 已有 140 个，前端未全部接通 |
+| 新增 SaaS API 端点 | 已有 121 个 .route()，前端未全部接通 |
 | 新增 SKILL.md | 已有 75 个 |
-| 新增 Tauri 命令 | 已有 182 个，70 个孤儿 |
-| 新增中间件/Store | 已有 14 层中间件 + 18 个 Store |
+| 新增 Tauri 命令 | 已有 183 个，部分无前端调用 |
+| 新增中间件 | 已有 14 层 |
+| 新增 Store | 已有 17 文件 + chat/4 子store |
 | 新增 admin 页面 | 已有 15 页 |

 ## 分层职责

 ```
-UI 组件 → 只负责展示和交互
-Store   → 负责状态组织和流程编排
-Client  → 负责网络通信和协议转换
+UI 组件 → 只负责展示和交互 (104 个 .tsx/.ts)
+Store   → 负责状态组织和流程编排 (17 文件 + 4 子store)
+Client  → 负责网络通信和协议转换 (85 个 lib/ 文件)
 ```

 禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过:
 - `desktop/src/lib/gateway-client.ts` — 主要通信客户端
 - `desktop/src/lib/tauri-gateway.ts` — Tauri 原生命令
+- `desktop/src/lib/kernel-client.ts` — Kernel 客户端
+- `desktop/src/lib/saas-client.ts` — SaaS API 客户端

 ## 验证命令

@@ -86,8 +89,9 @@ pnpm start:dev
 - 组件保持"展示层"职责

 **Rust:**
- 错误处理: 禁止 `let _ =`，改为 `log::warn!` 或更高级别
+- 错误处理: 禁止 `let _ =`，改为 `tracing::warn!` 或更高级别
 - 输入验证: 系统边界必须验证
+- 中间件: 实现 `AgentMiddleware` trait，4 个 hook 点

 ## WebMCP 调试工具

@@ -106,10 +110,7 @@ pnpm start:dev

 完成工作后，检查 wiki/ 是否需要更新：
 - 修复 bug → 更新 [[known-issues]]
- 架构变更 → 更新 [[architecture]] + [[data-flows]]
- 文件结构变化 → 更新 [[file-map]]
- 模块状态变化 → 更新 [[module-status]]
+- 架构变更 → 更新对应模块页 + [[middleware]]/[[routing]]
+- 文件结构变化 → 更新 [[routing]] Store 列表
+- 模块状态变化 → 更新 [[index]] 关键数字
 - 每次更新 → 在 [[log]] 追加记录
-
-→ 架构见 [[architecture]]
-→ 文件位置见 [[file-map]]
--- a/wiki/hands-skills.md
+++ b/wiki/hands-skills.md
@@ -7,7 +7,7 @@ tags: [module, hands, skills]

 # Hands + Skills

-> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]]
+> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[butler]]

 ## 设计思想

@@ -19,40 +19,60 @@ tags: [module, hands, skills]

 ## 代码逻辑

-### Hands (9 启用 + 2 禁用)
+### Hands (9 启用)

-| Hand | 功能 | 依赖 | 配置 |
-|------|------|------|------|
-| Browser | 浏览器自动化 | WebDriver | `hands/Browser/HAND.toml` |
-| Collector | 数据收集聚合 | — | `hands/Collector/HAND.toml` |
-| Researcher | 深度研究 | LLM | `hands/Researcher/HAND.toml` |
-| Clip | 视频处理 | FFmpeg | `hands/Clip/HAND.toml` |
-| Twitter | Twitter 自动化 | OAuth 1.0a | `hands/Twitter/HAND.toml` |
-| Whiteboard | 白板演示 | — | `hands/Whiteboard/HAND.toml` |
-| Slideshow | 幻灯片生成 | — | `hands/Slideshow/HAND.toml` |
-| Speech | 语音合成 | Browser TTS | `hands/Speech/HAND.toml` |
-| Quiz | 测验生成 | — | `hands/Quiz/HAND.toml` |
-| Predictor | 预测分析 | **禁用** | 无 TOML/无 Rust 实现 |
-| Lead | 销售线索 | **禁用** | 无 TOML/无 Rust 实现 |
+每个 Hand 有独立的 `hands/<Name>.HAND.toml` 配置和 `crates/zclaw-hands/src/hands/` 下的 Rust 实现。
+
+| Hand | 功能 | 依赖 | 测试数 | 配置 |
+|------|------|------|--------|------|
+| Browser | 浏览器自动化 (23 Tauri命令) | WebDriver | 8 | `hands/browser.HAND.toml` |
+| Collector | 数据收集聚合 | — | 8 | `hands/collector.HAND.toml` |
+| Researcher | 深度研究 | LLM | 22 | `hands/researcher.HAND.toml` |
+| Clip | 视频处理 | FFmpeg | 30 | `hands/clip.HAND.toml` |
+| Twitter | Twitter 自动化 (12 API v2) | OAuth 1.0a | 25 | `hands/twitter.HAND.toml` |
+| Whiteboard | 白板演示 | — | — | `hands/whiteboard.HAND.toml` |
+| Slideshow | 幻灯片生成 | — | 13 | `hands/slideshow.HAND.toml` |
+| Speech | 语音合成 | Browser TTS | — | `hands/speech.HAND.toml` |
+| Quiz | 测验生成 | — | — | `hands/quiz.HAND.toml` |
+
+Hands 测试分布（前 5）: Clip(30), Twitter(25), Researcher(22), Slideshow(13), Browser(8)
+
+### 禁用 Hands
+
+| Hand | 状态 | 说明 |
+|------|------|------|
+| Predictor | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 |
+| Lead | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 |

 ### 触发流

 ```
 UI 触发 → handStore.trigger(handName, params)
-  → Tauri invoke('hand_trigger', { handName, params })
+  → Tauri invoke('hand_execute', { handName, params })
    → Kernel → Hand 执行
    → needs_approval? → 等待 approvalStore 确认
    → 执行结果 → Tauri Event emit
    → handStore 更新状态 + 记录日志
 ```

-### Skills (75 个)
+Hand 相关 Tauri 命令 (8 个):
+`hand_list, hand_execute, hand_approve, hand_cancel, hand_get, hand_run_status, hand_run_list, hand_run_cancel`
+
+### Skills (75 个目录)

 ```
 skills/
-├── SKILL_001_数据分析.md
-├── SKILL_002_报告生成.md
-├── ... (75 个 SKILL.md 文件)
+├── accessibility-auditor/       api-tester/
+├── agentic-identity-trust/      app-store-optimizer/
+├── agents-orchestrator/         backend-architect/
+├── ai-engineer/                 brand-guardian/
+├── analytics-reporter/          chart-visualization/
+├── chinese-writing/             classroom-generator/
+├── code-review/                 consulting-analysis/
+├── content-creator/             data-analysis/
+├── data-consolidation-agent/    deep-research/
+├── devops-automator/            evidence-collector/
+├── ... (75 个目录，每个含 SKILL.md)
 ```

 每个 SKILL.md 定义:
@@ -68,23 +88,27 @@ skills/
 ```
 用户消息 → SemanticSkillRouter
  → TF-IDF 计算消息与 75 个技能的相似度
-  → 返回最匹配的技能
-  → ButlerRouter 使用此结果增强 system prompt
+  → 返回 { skill_id, confidence }
+  → ButlerRouter 使用 RoutingHint 增强 system prompt
 ```

+在 kernel 中通过 `SemanticRouterAdapter` 桥接到 `ButlerRouterBackend` trait。
+
 ## 关联模块

 - [[chat]] — 消息流中可能触发 Hand/Skill
 - [[butler]] — ButlerRouter 使用语义路由匹配技能
- [[middleware]] — 技能注入通过中间件实现
+- [[middleware]] — SkillIndex 中间件注入技能索引

 ## 关键文件

 | 文件 | 职责 |
 |------|------|
-| `crates/zclaw-hands/src/` | 9 个 Hand 实现 |
+| `crates/zclaw-hands/src/hands/` | 9 个 Hand 实现 |
 | `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 |
-| `skills/*.md` | 75 个技能定义 |
-| `hands/*/HAND.toml` | Hand 配置 |
+| `crates/zclaw-skills/src/` | 技能解析和索引 |
+| `skills/*/SKILL.md` | 75 个技能定义 |
+| `hands/*.HAND.toml` | 9 个 Hand 配置 |
 | `desktop/src/store/handStore.ts` | 前端 Hand 状态 |
-| `desktop/src/store/approvalStore.ts` | 审批状态 |
+| `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 |
+| `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -8,34 +8,51 @@ status: active

 > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。
 > **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
+> **数据来源**: 2026-04-11 代码全量扫描验证，非文档推测。

 ## 项目画像

 | 维度 | 值 |
 |------|-----|
 | 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
-| 技术栈 | Rust 10 crates (~66K行) + React 19 + TypeScript + PostgreSQL |
+| 技术栈 | Rust 10 crates (~74.5K行) + React 19 + TypeScript + PostgreSQL |
 | 阶段 | 发布前稳定化，功能冻结中 |

-## 关键数字
+## 关键数字（2026-04-11 代码验证）

-Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17
+| 指标 | 值 | 验证方式 |
+|------|-----|----------|
+| Rust Crates | 10 | `ls crates/zclaw-*/Cargo.toml` |
+| Rust 代码 | 74,487 行 | `find crates/ -name "*.rs" \| xargs wc -l` |
+| Rust #[test] | 431 个 | `grep '#\[test\]' crates/**/*.rs` |
+| Tauri 命令 | 183 (含5 feature-gated) | `lib.rs generate_handler![]` 注册 |
+| 前端 invoke 调用 | 105 处 | `grep invoke( desktop/src/` |
+| SaaS .route() | 121 个 | `grep .route( crates/zclaw-saas/` |
+| SKILL 目录 | 75 个 | `ls -d skills/*/` |
+| HAND 配置 | 9 个 (TOML) | `ls hands/*.HAND.toml` |
+| Pipeline YAML | 17 个 | `find pipelines/ -name "*.yaml"` |
+| Zustand Store | 17 文件 + chat/4子store = 21 | `ls desktop/src/store/` |
+| React 组件 | 104 个 (.tsx/.ts) | `find desktop/src/components/` |
+| Admin V2 页面 | 15 个 (.tsx) | `ls admin-v2/src/pages/` |
+| 中间件 | 14 层 (含1个条件注册) | `kernel/mod.rs create_middleware_chain` |
+| 前端 lib/ | 85 个 .ts | `find desktop/src/lib/` |
+| TODO/FIXME | 前端 4 + Rust 4 = 8 | `grep TODO/FIXME` |

 ## 模块导航树

 ```
 ZCLAW
 ├── [[routing]]        客户端路由 — 4分支决策，SaaS Relay是主路径
-│   └── [[chat]]       聊天系统 — 3种ChatStream，SaaS Token Pool是主路径
+│   └── [[chat]]       聊天系统 — 3种ChatStream，Store拆为4+1
 │
 ├── [[saas]]           SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
 │   ├── 认证           JWT + Cookie + Token池 RPM/TPM轮换
 │   ├── 计费           配额实时递增 + Alipay/WeChat
 │   └── Admin V2       15页管理后台
 │
-├── [[butler]]         管家模式 — 默认交互范式，4域路由+冷启动+痛点
+├── [[butler]]         管家模式 — 默认交互范式，语义路由+冷启动+痛点
 │
-├── [[middleware]]     中间件链 — 14层，DataMasking→ButlerRouter→TrajectoryRecorder
+├── [[middleware]]     中间件链 — 14层，按优先级分类注册
 │
 ├── [[memory]]         记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
 │
@@ -54,9 +71,12 @@ ZCLAW
 → 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。

 **Q: 为什么有3种 ChatStream？**
-→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。
+→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。

 **Q: 为什么管家模式是默认？**
-→ 面向医院行政等非技术用户，4域关键词分类+痛点积累+方案生成，降低使用门槛。
+→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。

-> 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准
+**Q: 为什么中间件是14层？**
+→ 按优先级分4类: 100-199上下文(compaction/memory) → 200-399能力(skill/guardrail) → 400-599安全(loop_guard/data_masking) → 600-799遥测(token/title/trajectory)。Kernel `create_middleware_chain()` 条件注册，skill_index 仅在有技能时注册。
+
+> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准
--- a/wiki/known-issues.md
+++ b/wiki/known-issues.md
@@ -18,13 +18,36 @@ tags: [issues, bugs]
 | P1.5 (代码质量) | 7 | 全部已修复 |
 | P2 (代码质量) | 10 | 待处理 |

+## 代码健康度指标（2026-04-11 扫描）
+
+| 指标 | 值 | 说明 |
+|------|-----|------|
+| TODO/FIXME 前端 | 4 | 非常少 |
+| TODO/FIXME Rust | 4 | 非常少 |
+| @reserved 标注 | 33 | 无前端调用的命令已标注 |
+| 前端孤立 invoke | 0 | 已清理 |
+
 ## 长期观察项

 | 问题 | 说明 | 位置 |
 |------|------|------|
-| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | `desktop/src-tauri/src/lib.rs` |
+| Tauri 命令孤儿 | 注册 183 命令，前端调用 105 处，@reserved 33 个，剩余可能为内部调用 | `desktop/src-tauri/src/lib.rs` |
 | Embedding 未激活 | EmbeddingClient trait 已写但 NoOp | `zclaw-growth/src/retrieval/semantic.rs` |
 | SaaS embedding deferred | pgvector 索引就绪，生成未实现 | `zclaw-saas/src/workers/generate_embedding.rs` |
-| webhook 死代码 | 5 路由定义但未挂载 | `zclaw-saas/src/webhook/` |
+| SkillIndex 条件注册 | 无技能时 skill_index 中间件不注册 | `kernel/mod.rs:289` |
+| Hermes Schema | v4 新增 user_profiles + trajectory 表 | `zclaw-saas/migrations/` |

-→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]]
+## 已修复的关键问题（历史记录）
+
+| ID | 问题 | 修复日期 |
+|----|------|----------|
+| SEC2-P0-01 | skill_execute 反序列化崩溃 | 04-02 |
+| SEC2-P0-02 | TaskTool::default() panic | 04-02 |
+| SEC2-P1-01~09 | 9 项功能失效 (FactStore/路径/监听/...) | 04-02 |
+| SEC2-P1.5-01~07 | 7 项代码质量修复 | 04-02 |
+| P0-2/P0-3 | usage 端点 + refresh token 类型 | 04-10 |
+| P1-02 | 浏览器聊天 SaaS fixture | 04-10 |
+| P1-04 | AuthGuard 竞态条件 | 04-10 |
+| BREAKS 全部 | 全部 P0/P1/P2 已修复 | 04-10 |
+
+→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]] [[middleware]]
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -9,6 +9,19 @@ tags: [log, history]

 > Append-only 操作记录。格式: `## [日期] 类型 | 描述`

+## [2026-04-11] docs | Wiki 全面更新 — 代码验证驱动
+
+- 全部 10 个 wiki 页面基于代码扫描验证更新（非文档推测）
+- 关键数字修正: Rust 74.5K行(原66K)、Tauri命令 183(原182)、SaaS路由 121、前端组件 104、lib/ 85 文件
+- 新增中间件完整注册清单（14层含注册条件和优先级分类）
+- 新增 Store 完整目录结构（17 文件 + chat/4 子store）
+- 新增 Pipeline 模板完整目录树（17 YAML, 8 行业目录）
+- 新增 Hands 测试数分布
+- 新增 memory Tauri 命令完整列表（16 个）
+- 新增代码健康度指标（TODO/FIXME 仅 8 个）
+- 修正管家模式描述: 关键词路由 → 语义路由(TF-IDF)
+- 新增 artifactStore 到 chat Store 拆分列表
+
 ## [2026-04-11] init | 创建 wiki 知识库

 - 从 TRUTH.md / ARCHITECTURE_BRIEF.md / CLAUDE.md 编译 8 个 wiki 页面
--- a/wiki/memory.md
+++ b/wiki/memory.md
@@ -60,6 +60,20 @@ ExperienceStore (crates/zclaw-growth/src/experience_store.rs)
  → URI scheme: agent://{agent_id}/experience/...
 ```

+### Hermes 管线 (4 Chunk)
+
+| Chunk | 模块 | 文件 | 测试 |
+|-------|------|------|------|
+| 1 | ExperienceStore + Extractor | experience_store.rs | 10 |
+| 2 | UserProfileStore + Profiler | user_profile.rs | 14 |
+| 3 | NlScheduleParser | nl_schedule.rs | 16 |
+| 4 | TrajectoryRecorder + Compressor | middleware/trajectory_recorder.rs | 18 |
+
+Hermes 相关测试分布:
+- `nl_schedule.rs`: 16 tests (中文时间→cron 解析)
+- `types.rs`: 9 tests (记忆类型)
+- `injector.rs`: 9 tests (prompt 注入)
+
 ### 查询意图分类

 `QueryAnalyzer` 支持 5 种意图:
@@ -85,11 +99,21 @@ SaaS 侧:
  → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred)
 ```

+### 前端 Tauri 命令
+
+Memory 相关命令 (13 个，来自 `memory_commands.rs` + `memory/`):
+`memory_init, memory_store, memory_get, memory_search, memory_delete, memory_delete_all, memory_stats, memory_export, memory_import, memory_db_path, memory_configure_embedding, memory_is_embedding_configured, memory_build_context`
+
+加上 `memory/extractor.rs` 的 2 个: `extract_session_memories, extract_and_store_memories`
+和 `memory/context_builder.rs` 的 1 个: `estimate_content_tokens`
+
+总计 16 个 memory 相关 Tauri 命令。
+
 ## 关联模块

 - [[chat]] — 对话是记忆的输入源
 - [[butler]] — 管家模式可能利用记忆提供个性化响应
- [[middleware]] — 记忆注入通过中间件或 hook 实现
+- [[middleware]] — Memory 中间件自动提取 + SkillIndex 注入

 ## 关键文件

@@ -102,5 +126,9 @@ SaaS 侧:
 | `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 |
 | `crates/zclaw-growth/src/retrieval/semantic.rs` | EmbeddingClient trait |
 | `crates/zclaw-growth/src/retrieval/query.rs` | 意图分类 + CJK 关键词 |
-| `desktop/src/store/memoryStore.ts` | 前端记忆 UI |
+| `crates/zclaw-growth/src/nl_schedule.rs` | 中文时间→cron 解析 (16 tests) |
+| `crates/zclaw-runtime/src/middleware/memory.rs` | 记忆中间件 |
+| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录中间件 |
+| `desktop/src/store/memoryGraphStore.ts` | 前端记忆 UI |
 | `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 |
+| `desktop/src-tauri/src/memory_commands.rs` | 13 个 memory CRUD 命令 |
--- a/wiki/middleware.md
+++ b/wiki/middleware.md
@@ -13,51 +13,88 @@ tags: [module, middleware, runtime]

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

- 优先级 0-100，数值越大越先执行
- 每层中间件可以: 修改请求 / 拦截响应 / 记录日志 / 注入上下文
+- 优先级 0-999，数值越小越先执行（`middleware.rs` 按升序排列）
+- 每层中间件实现 `AgentMiddleware` trait，4个 hook 点: `before_completion` / `before_tool_call` / `after_tool_call` / `after_completion`
 - 所有消息流（聊天、管家）都经过完整中间件链
+- 中间件可返回 `Stop`/`Block`/`AbortLoop` 决策来中断流程

 ## 代码逻辑

-### 14 层中间件
+### 14 层中间件（注册顺序见 `kernel/mod.rs:190-345`）

-关键中间件（按优先级排序）:
+| # | 中间件 | 文件 | 职责 | 注册条件 |
+|---|--------|------|------|----------|
+| 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` | 轨迹记录 + 压缩 | 始终 |

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

-其他 11 层: 认证、速率限制、日志、技能注入、记忆注入等。
+| 范围 | 类别 | 包含的中间件 |
+|------|------|-------------|
+| 100-199 | 上下文塑造 | Compaction, Memory |
+| 200-399 | 能力 | SkillIndex, Guardrail |
+| 400-599 | 安全 | LoopGuard, DataMasking |
+| 600-799 | 遥测 | TokenCalibration, Title, TrajectoryRecorder |

 ### 中间件执行流

 ```
-用户消息
-  → [优先级 90] DataMasking — 脱敏敏感数据
-  → [优先级 ~500] ButlerRouter — 关键词分类 + prompt 增强
-  → [优先级 650] 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-runtime/` 中注册，Kernel 启动时加载。
+`crates/zclaw-kernel/src/kernel/mod.rs:190-345` — `create_middleware_chain()` 方法，13 次 `chain.register()` + 1 个条件注册。

 ## 关联模块

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

 ## 关键文件

 | 文件 | 职责 |
 |------|------|
-| `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` | 轨迹记录 |
+| `crates/zclaw-runtime/src/middleware.rs` | AgentMiddleware trait + MiddlewareChain |
+| `crates/zclaw-runtime/src/middleware/` | 14 个中间件实现 (14个 .rs 文件) |
+| `crates/zclaw-kernel/src/kernel/mod.rs:190-345` | 注册入口 |
--- a/wiki/pipeline.md
+++ b/wiki/pipeline.md
@@ -15,7 +15,7 @@ tags: [module, pipeline, dsl]

 - YAML 定义 Pipeline 结构（步骤、依赖、输入/输出）
 - DAG 执行器按依赖拓扑排序执行
- 17 个行业模板覆盖 10 大行业
+- 17 个 YAML 模板覆盖 8 大行业目录
 - 前端已接通 8 个 Tauri invoke 调用

 ## 代码逻辑
@@ -38,33 +38,72 @@ YAML Pipeline 定义
 enum RunStatus { Pending, Running, Completed, Failed, Cancelled }
 ```

-### 模板 (17 个 YAML)
+### 模板分布 (17 个 YAML)

-位于 `pipelines/` 目录，覆盖:
- 汕头玩具行业、服装设计、医疗
- 数据分析、报告生成
- 教育、营销
- 等 10 大行业
+```
+pipelines/
+├── _templates/         (2 模板)
+│   ├── article-summary.yaml
+│   └── competitor-analysis.yaml
+├── design-shantou/     (4 模板) — 汕头玩具/服装行业
+│   ├── client-communication.yaml
+│   ├── competitor-research.yaml
+│   ├── supply-chain-collect.yaml
+│   └── trend-to-design.yaml
+├── education/          (4 模板)
+│   ├── classroom.yaml
+│   ├── lesson-plan.yaml
+│   ├── research-to-quiz.yaml
+│   └── student-analysis.yaml
+├── healthcare/         (3 模板)
+│   ├── data-report.yaml
+│   ├── meeting-minutes.yaml
+│   └── policy-compliance.yaml
+├── legal/              (1 模板)
+│   └── contract-review.yaml
+├── marketing/          (1 模板)
+│   └── campaign.yaml
+├── productivity/       (1 模板)
+│   └── meeting-summary.yaml
+└── research/           (1 模板)
+    └── literature-review.yaml
+```

 ### 前端集成

 | 组件 | 文件 |
 |------|------|
 | PipelineClient | `desktop/src/lib/pipeline-client.ts` |
+| WorkflowBuilderStore | `desktop/src/store/workflowBuilderStore.ts` |
+| Pipeline UI | `desktop/src/components/pipeline/` |
 | Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` |

-8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用。
+Pipeline Tauri 命令 (12 个):
+
+| 文件 | 命令数 | 命令 |
+|------|--------|------|
+| discovery.rs | 8 | list/get/run/progress/cancel/result/runs/refresh |
+| crud.rs | 3 | create/update/delete |
+| intent_router.rs | 1 | route_intent |
+| presentation.rs | 2 | analyze_presentation/pipeline_templates |
+
+前端 invoke 匹配: 8 个调用对应 8 个 discovery 命令，完整可用。
+
+### 测试
+
+`parser_v2.rs`: 11 tests — YAML 解析和 DAG 构建验证。

 ## 关联模块

 - [[hands-skills]] — Pipeline 步骤可能调用 Hand/Skill
+- [[chat]] — Pipeline 可通过聊天触发

 ## 关键文件

 | 文件 | 职责 |
 |------|------|
 | `crates/zclaw-pipeline/src/executor.rs` | DAG 执行器 |
-| `crates/zclaw-pipeline/src/` | Pipeline DSL 解析 |
-| `pipelines/` | 17 个 YAML 模板 |
+| `crates/zclaw-pipeline/src/parser_v2.rs` | YAML 解析 (11 tests) |
+| `pipelines/` | 17 个 YAML 模板 (8 目录) |
 | `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 |
-| `desktop/src-tauri/src/pipeline_commands/` | Tauri 命令桥接 |
+| `desktop/src-tauri/src/pipeline_commands/` | 12 个 Tauri 命令 (4 文件) |
--- a/wiki/routing.md
+++ b/wiki/routing.md
@@ -86,6 +86,46 @@ listModels() 失败
 `getClient()` 定义: `connectionStore.ts:844`
 所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。

+### Store 层 (17 文件 + chat/4)
+
+```
+desktop/src/store/
+├── index.ts              Store 协调器 + client 注入
+├── agentStore.ts         Agent 分身管理
+├── browserHandStore.ts   浏览器 Hand 状态
+├── chatStore.ts          聊天通用状态
+├── classroomStore.ts     课堂模式
+├── configStore.ts        配置读写
+├── connectionStore.ts    路由决策核心
+├── handStore.ts          Hand 状态管理
+├── memoryGraphStore.ts   记忆图谱
+├── offlineStore.ts       离线队列
+├── saasStore.ts          SaaS 认证
+├── securityStore.ts      安全状态
+├── sessionStore.ts       会话管理
+├── uiModeStore.ts        双模式 UI
+├── workflowBuilderStore.ts  工作流构建器
+├── workflowStore.ts      工作流状态
+└── chat/
+    ├── artifactStore.ts  聊天产物
+    ├── conversationStore.ts  会话管理
+    ├── messageStore.ts   消息持久化
+    └── streamStore.ts    流式编排
+```
+
+### lib/ 工具层 (85 个文件)
+
+关键分类:
+
+| 类别 | 文件 | 数量 |
+|------|------|------|
+| Kernel 通信 | kernel-chat/kernel-client/kernel-agent/... | 7 |
+| SaaS 通信 | saas-client/saas-auth/saas-billing/... | 9 |
+| Gateway | gateway-client/gateway-api/gateway-auth/... | 6 |
+| Intelligence | intelligence-client/ + 5 fallback | 7 |
+| 工具 | config-parser/crypto-utils/logger/utils | 10+ |
+| Tauri 集成 | safe-tauri/tauri-gateway/secure-storage | 3 |
+
 ## 关联模块

 - [[chat]] — 路由决定使用哪种 ChatStream
@@ -97,9 +137,10 @@ listModels() 失败

 | 文件 | 职责 |
 |------|------|
-| `desktop/src/store/connectionStore.ts` | 路由决策核心 (844行) |
+| `desktop/src/store/connectionStore.ts` | 路由决策核心 |
 | `desktop/src/lib/gateway-client.ts` | WebSocket 客户端 |
 | `desktop/src/lib/kernel-chat.ts` | Tauri 内核聊天 |
+| `desktop/src/lib/kernel-client.ts` | Kernel 客户端配置 |
 | `desktop/src/lib/saas-relay-client.ts` | SaaS SSE 中继 |
 | `desktop/src/lib/saas-client.ts` | SaaS API 客户端 |
 | `desktop/src/store/index.ts` | Store 协调器 + client 注入 |
--- a/wiki/saas.md
+++ b/wiki/saas.md
@@ -25,7 +25,7 @@ tags: [module, saas, auth, billing]

 ```
 用户登录 (POST /api/v1/auth/login)
-  → Argon2id + OsRng 盐验证密码
+  → Argon2id + OsRg 盐验证密码
  → 签发 JWT (Claims: user_id, role, pwv)
  → set_auth_cookies():
      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
@@ -62,7 +62,7 @@ JWT password_version (pwv):
  → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv
  → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效

-密码存储: Argon2id + OsRng 随机盐
+密码存储: Argon2id + OsRg 随机盐
 TOTP 加密: AES-256-GCM + 随机 Nonce
 ```

@@ -75,40 +75,52 @@ POST /api/v1/auth/refresh
  → 签发新 access + refresh token
 ```

+### SaaS 模块结构（代码验证）
+
+15 个模块目录 (`crates/zclaw-saas/src/`):
+
+```
+account/  agent_template/  auth/  billing/  knowledge/
+migration/  model_config/  models/  prompt/  relay/
+role/  scheduled_task/  tasks/  telemetry/  workers/
+```
+
 ### SaaS API 分布

-12 个路由模块，140 端点:
+121 个 `.route()` 调用，12 个路由模块 (main.rs `.merge()` 注册):

-| 模块 | 端点数 | 说明 |
-|------|--------|------|
-| auth | ~10 | 登录/注册/刷新/2FA |
-| relay | ~5 | 聊天中转/模型列表/任务 |
-| billing | 10 | 配额/订阅/支付 |
-| knowledge | 23 | 知识库 CRUD + pgvector |
-| model_config | ~8 | Provider + 模型管理 |
-| account | ~8 | 用户管理 |
-| agent_template | ~8 | Agent 模板 |
-| role | 11 | 角色 + 权限 |
-| telemetry | ~5 | 用量统计 |
-| prompt | ~5 | Prompt 模板 |
-| scheduled_task | 5 | 定时任务 CRUD |
-| migration | ~2 | Schema 迁移 |
+| 模块 | 路由注册 | 说明 |
+|------|----------|------|
+| auth | handlers.rs | 登录/注册/刷新/2FA |
+| relay | relay/ | 聊天中转/模型列表/任务 |
+| billing | billing/ + callback_routes | 配额/订阅/支付 |
+| knowledge | knowledge/ | 知识库 CRUD + pgvector (最大模块) |
+| model_config | model_config/ | Provider + 模型管理 |
+| account | account/ | 用户管理 |
+| agent_template | agent_template/ | Agent 模板 |
+| role | role/ | 角色 + 权限 |
+| telemetry | telemetry/ | 用量统计 |
+| prompt | prompt/ | Prompt 模板 |
+| scheduled_task | scheduled_task/ | 定时任务 CRUD |
+| migration | migration/ | Schema 迁移 |

-### 数据表 (34 个)
+### 数据表 (38 CREATE TABLE)

-核心: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version
+32 个 SQL 迁移文件，38 个 `CREATE TABLE` 语句。
+
+核心表: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version, user_profiles, trajectory_records

 ### Workers (7 个)

-| Worker | 职责 |
-|--------|------|
-| log_operation | 操作日志 |
-| cleanup_rate_limit | 限流记录清理 |
-| cleanup_refresh_tokens | 刷新 token 清理 |
-| record_usage | 用量记录 |
-| update_last_used | 模型最后使用更新 |
-| aggregate_usage | 用量聚合 |
-| generate_embedding | 内容分块 (Phase 2 embedding deferred) |
+| Worker | 文件 | 职责 |
+|--------|------|------|
+| log_operation | workers/ | 操作日志 |
+| cleanup_rate_limit | workers/ | 限流记录清理 |
+| cleanup_refresh_tokens | workers/ | 刷新 token 清理 |
+| record_usage | workers/ | 用量记录 |
+| update_last_used | workers/ | 模型最后使用更新 |
+| aggregate_usage | workers/ | 用量聚合 |
+| generate_embedding | workers/ | 内容分块 (embedding deferred) |

 ## 关联模块

@@ -120,12 +132,13 @@ POST /api/v1/auth/refresh

 | 文件 | 职责 |
 |------|------|
+| `crates/zclaw-saas/src/main.rs` | 路由注册入口 (12个 .merge()) |
 | `crates/zclaw-saas/src/auth/handlers.rs` | 认证端点 |
 | `crates/zclaw-saas/src/relay/` | 聊天中转 |
 | `crates/zclaw-saas/src/billing/` | 计费 |
-| `crates/zclaw-saas/src/knowledge/` | 知识库 (23 API) |
+| `crates/zclaw-saas/src/knowledge/` | 知识库 |
 | `crates/zclaw-saas/src/workers/` | 7 个后台 Worker |
-| `crates/zclaw-saas/migrations/` | SQL 迁移 (34 表) |
+| `crates/zclaw-saas/migrations/` | SQL 迁移 (32 文件) |
 | `admin-v2/src/pages/` | 15 页管理后台 |
 | `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 |
 | `desktop/src/store/saasStore.ts` | SaaS 认证状态 |