docs(wiki): 重构为模块化知识库 — 按模块组织而非按文档类型

问题: 旧 wiki 按文档类型组织（architecture/data-flows/file-map），修复 Butler Router 需要读 4 个文件才能拼凑全貌。且 SaaS Relay 主路径 vs 本地降级的优先级描述不准确。重构为模块化结构，每个模块页自包含： - 设计思想: 为什么这样设计 - 代码逻辑: 数据流 + 关键代码 - 关联模块: 依赖关系新增模块页: - routing.md: 客户端路由 (明确 SaaS Relay 是主路径，不是本地模式) - chat.md: 聊天系统 (3种实现 + Token Pool 中转机制) - butler.md: 管家模式 (路由/冷启动/痛点/双模式UI) - memory.md: 记忆管道 (提取→FTS5→检索→注入) - saas.md: SaaS平台 (认证/Token池/计费/Admin) - middleware.md: 中间件链 (14层 + 优先级) - hands-skills.md: Hands(9) + Skills(75) - pipeline.md: Pipeline DSL 删除旧文件: architecture.md, data-flows.md, module-status.md, file-map.md (内容已分布到对应模块页中) 添加 .gitignore 排除 Obsidian 工作区状态文件
2026-04-11 00:36:26 +08:00
parent 9772d6ec94
commit 36a1c87d87
18 changed files with 839 additions and 627 deletions
--- a/wiki/.gitignore
+++ b/wiki/.gitignore
@@ -0,0 +1,4 @@
+.obsidian/workspace.json
+.obsidian/workspace-mobile.json
+.obsidian/plugins/
+.trash/
--- a/wiki/.obsidian/app.json
+++ b/wiki/.obsidian/app.json
@@ -0,0 +1 @@
+{}
--- a/wiki/.obsidian/appearance.json
+++ b/wiki/.obsidian/appearance.json
@@ -0,0 +1 @@
+{}
--- a/wiki/.obsidian/core-plugins.json
+++ b/wiki/.obsidian/core-plugins.json
@@ -0,0 +1,33 @@
+{
+  "file-explorer": true,
+  "global-search": true,
+  "switcher": true,
+  "graph": true,
+  "backlink": true,
+  "canvas": true,
+  "outgoing-link": true,
+  "tag-pane": true,
+  "footnotes": false,
+  "properties": true,
+  "page-preview": true,
+  "daily-notes": true,
+  "templates": true,
+  "note-composer": true,
+  "command-palette": true,
+  "slash-command": false,
+  "editor-status": true,
+  "bookmarks": true,
+  "markdown-importer": false,
+  "zk-prefixer": false,
+  "random-note": false,
+  "outline": true,
+  "word-count": true,
+  "slides": false,
+  "audio-recorder": false,
+  "workspaces": false,
+  "file-recovery": true,
+  "publish": false,
+  "sync": true,
+  "bases": true,
+  "webviewer": false
+}
--- a/wiki/architecture.md
+++ b/wiki/architecture.md
@@ -1,147 +0,0 @@
---
-title: 系统架构
-updated: 2026-04-11
-status: active
-tags: [architecture, core]
---
-
-# 系统架构
-
-> 从 [[index]] 导航到此处。详细架构参考: `docs/ARCHITECTURE_BRIEF.md`
-
-## Crate 依赖关系
-
-```
-zclaw-types          (L1: 基础类型, 无依赖)
-    ↑
-zclaw-memory         (L2: SQLite, KV, 会话)
-    ↑
-zclaw-runtime        (L3: 4 Driver, 7 工具, 14 中间件)
-    ↑
-zclaw-kernel         (L4: 182 Tauri 命令, 核心协调)
-    ↑
-zclaw-saas           (独立: Axum + PostgreSQL, 端口 8080)
-    ↑
-desktop/src-tauri    (集成: kernel + skills + hands + protocols)
-```
-
-并行 crates (不依赖 runtime):
- `zclaw-skills` — 75 SKILL.md 解析 + 语义路由
- `zclaw-hands` — 9 自主能力
- `zclaw-protocols` — MCP 完整 + A2A feature-gated
- `zclaw-pipeline` — Pipeline DSL v1/v2 + DAG 执行器
- `zclaw-growth` — 记忆增长 (FTS5 + TF-IDF + Embedding trait)
-
-## 客户端路由 (4 分支)
-
-```
-getClient()
-  ├── [1] Admin 路由: localStorage llm_routing → relay/local
-  ├── [2] SaaS Relay: SaaS不可达→降级到本地 Kernel
-  ├── [3] Local Kernel: Tauri 内置 (桌面端默认)
-  └── [4] External Gateway: WebSocket/REST fallback
-```
-
-关键文件: `desktop/src/store/connectionStore.ts:844`
-
-## 聊天流 (3 种实现)
-
-| 实现 | 传输 | 场景 |
-|------|------|------|
-| GatewayClient | WebSocket | 外部 Gateway 进程 |
-| KernelClient | Tauri Event | 内置 Kernel (默认) |
-| SaaSRelay | HTTP SSE | 浏览器端 SaaS 中继 |
-
-统一回调: `{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }`
-5 分钟超时守护: `desktop/src/lib/kernel-chat.ts:76`
-
-## LLM 驱动 (4 + 3)
-
-### Rust Driver
-
-| Driver | 文件 | 协议 |
-|--------|------|------|
-| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages |
-| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat |
-| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini |
-| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama |
-
-### 国内兼容 (通过 OpenAI 协议 + base_url)
-
-| Provider | base_url |
-|----------|----------|
-| DeepSeek | `https://api.deepseek.com` |
-| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-| Moonshot | `https://api.moonshot.cn/v1` |
-
-API Key → OS keyring (`secure-storage.ts`)
-
-## 管家模式 (默认激活)
-
-```
-用户消息 → ButlerRouter (4域关键词分类) → 增强 system prompt → LLM
-                                                              ↓
-                                              PainAggregator → PainStorage (内存+SQLite)
-                                                              ↓
-                                              SolutionGenerator (痛点→方案)
-```
-
- 冷启动: idle → greeting_sent → waiting_response → completed
- UI 双模式: simple (纯聊天, 默认) / professional (完整功能)
- ButlerRouter 文件: `crates/zclaw-runtime/src/middleware/butler_router.rs`
-
-## 记忆管道 (闭环)
-
-```
-对话 → extraction_adapter (LLM 提取)
-     → FTS5 全文索引 + TF-IDF 权重
-     → 检索 (查询时召回)
-     → 注入 system prompt (token 预算控制)
-```
-
- EmbeddingClient trait 已定义但未激活
- zclaw-saas 有 pgvector HNSW 索引就绪，embedding 生成 deferred
-
-## SaaS 认证
-
-| 数据 | 存储 |
-|------|------|
-| JWT Token | OS Keyring |
-| 账户信息 | localStorage |
-| Cookie | HttpOnly + Secure + SameSite=Strict |
-
- JWT password_version: 改密码→所有旧 JWT 失效
- Token 池: RPM/TPM 限流轮换
- SaaS unreachable → 自动降级本地 Kernel
-
-## 中间件链 (14 层)
-
-关键中间件:
- DataMasking@90 — 请求前数据脱敏
- ButlerRouter — 4域关键词分类 + system prompt 增强
- TrajectoryRecorder@650 — 轨迹记录压缩
-
-## 关键文件速查
-
-### 前端
-
-| 文件 | 职责 |
-|------|------|
-| `desktop/src/store/connectionStore.ts` | 客户端路由 |
-| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
-| `desktop/src/store/chat/conversationStore.ts` | 会话管理 |
-| `desktop/src/store/saasStore.ts` | SaaS 认证 |
-| `desktop/src/store/uiModeStore.ts` | 简洁/专业模式 |
-| `desktop/src/hooks/use-cold-start.ts` | 管家冷启动 |
-
-### 后端
-
-| 文件 | 职责 |
-|------|------|
-| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动 |
-| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 |
-| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证 |
-| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 |
-
-→ 数据流细节见 [[data-flows]]
-→ 模块状态见 [[module-status]]
--- a/wiki/butler.md
+++ b/wiki/butler.md
@@ -0,0 +1,83 @@
+---
+title: 管家模式
+updated: 2026-04-11
+status: active
+tags: [module, butler, interaction]
+---
+
+# 管家模式 (Butler Mode)
+
+> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[memory]]
+
+## 设计思想
+
+**核心问题: 非技术用户（如医院行政）不会写 prompt，需要 AI 主动引导。**
+
+设计决策:
+1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启
+2. **4 域关键词分类** — healthcare / data_report / policy / meeting，自动增强 system prompt
+3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议
+4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁
+
+## 代码逻辑
+
+### 数据流
+
+```
+用户消息
+  → ButlerRouter 中间件 (middleware/butler_router.rs)
+    → SemanticSkillRouter TF-IDF 匹配 75 个技能
+    → 4 域关键词分类
+    → 增强 system prompt (领域专用指令)
+  → LLM 响应
+  → PainAggregator 提取痛点
+    → PainStorage (内存 Vec 热缓存 + SQLite 持久层)
+    → 全局 PAIN_STORAGE 单例
+  → SolutionGenerator
+    → 基于痛点生成解决方案提案
+```
+
+### 冷启动 (新用户引导)
+
+入口: `desktop/src/hooks/use-cold-start.ts`
+
+```
+idle → (检测新用户) → greeting_sent → waiting_response → completed
+```
+
+4 个阶段，自动检测用户是否需要引导，发送欢迎消息，等待响应后完成。
+
+### UI 双模式
+
+| 模式 | Store | 特点 |
+|------|-------|------|
+| simple (默认) | `uiModeStore.ts` | 纯聊天界面，隐藏高级功能 |
+| professional | `uiModeStore.ts` | 完整功能面板 |
+
+切换文件: `desktop/src/store/uiModeStore.ts`
+简洁侧边栏: `desktop/src/components/SimpleSidebar.tsx`
+管家面板: `desktop/src/components/ButlerPanel.tsx` (3 区: 洞察/方案/记忆)
+
+## 关联模块
+
+- [[middleware]] — ButlerRouter 是中间件链中的一层
+- [[chat]] — 消息流经过管家路由增强
+- [[memory]] — 痛点存储在 memory 子系统
+- [[hands-skills]] — 语义路由使用 75 个技能的 TF-IDF
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 (4域分类) |
+| `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
@@ -0,0 +1,92 @@
+---
+title: 聊天系统
+updated: 2026-04-11
+status: active
+tags: [module, chat, stream]
+---
+
+# 聊天系统
+
+> 从 [[index]] 导航。关联模块: [[routing]] [[saas]] [[butler]]
+
+## 设计思想
+
+**核心问题: 3 种运行环境需要 3 种 ChatStream 实现。**
+
+| 环境 | 实现 | 传输 | 为什么 |
+|------|------|------|--------|
+| 桌面端 (Tauri) | KernelClient | Tauri Event | 内置 Kernel，但 baseUrl 可指向 SaaS relay |
+| 桌面端 (Tauri + SaaS) | KernelClient + relay | Tauri Event → SaaS | 主路径: Token Pool 中转 |
+| 浏览器端 | SaaSRelayGatewayClient | HTTP SSE | 无 Tauri 运行时 |
+| 外部 Gateway | GatewayClient | WebSocket | 独立进程部署 |
+
+**统一接口**: 3 种实现共享同一套回调:
+
+```ts
+{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }
+```
+
+## 代码逻辑
+
+### 发送消息流
+
+入口: `streamStore.sendMessage(content)` → `streamStore.ts`
+
+```
+sendMessage(content)
+  → effectiveSessionKey = conversationStore.sessionKey || uuid()
+  → effectiveAgentId = resolveGatewayAgentId(currentAgent)
+  → client.chatStream(content, callbacks, { sessionKey, agentId, chatMode })
+    → KernelClient: Tauri invoke('kernel_chat', ...)
+      → Kernel → loop_runner → LLM Driver
+        → 如果 baseUrl 指向 SaaS relay → 请求发往 Token Pool → LLM
+        → 如果 baseUrl 指向 LLM 直连 → 请求直接发往 LLM
+      → Tauri Event emit('chat-response-delta', ...)
+        → onDelta(text) → streamStore 追加 delta
+        → onTool(tool) → toolStore 更新
+        → onHand(hand) → handStore 更新
+        → onComplete() → conversationStore 持久化
+    → SaaSRelay: HTTP POST /api/v1/relay/chat/completions → SSE
+    → GatewayClient: WebSocket send → onmessage
+  → 5 分钟超时守护 (kernel-chat.ts:76) 防止流挂起
+```
+
+### Store 拆分 (4 Store)
+
+原来 908 行的 ChatStore 已拆分为:
+
+| Store | 文件 | 职责 |
+|-------|------|------|
+| streamStore | `store/chat/streamStore.ts` | 流式消息编排、发送、取消 |
+| conversationStore | `store/chat/conversationStore.ts` | 会话管理、当前模型 |
+| messageStore | `store/chat/messageStore.ts` | 消息持久化 |
+| chatStore | `store/chat/chatStore.ts` | 聊天通用状态 |
+
+### 模型切换
+
+```
+UI 选择模型 → conversationStore.currentModel = newModel
+  → 下次 sendMessage 时，connectionStore 读取 currentModel
+  → SaaS 模式: relay 白名单验证 → 可用则切换
+  → 本地模式: 直接使用用户配置的模型
+```
+
+## 关联模块
+
+- [[routing]] — 路由决定使用哪种 client
+- [[saas]] — Token Pool 提供模型和 API Key
+- [[butler]] — ButlerRouter 中间件增强 system prompt
+- [[middleware]] — 消息经过 14 层中间件处理
+- [[memory]] — 对话内容可能触发记忆提取
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
+| `desktop/src/store/chat/conversationStore.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) |
+| `desktop/src/components/ChatArea.tsx` | 聊天区域 UI |
+| `crates/zclaw-runtime/src/loop_runner.rs` | Rust 主聊天循环 |
--- a/wiki/data-flows.md
+++ b/wiki/data-flows.md
@@ -1,148 +0,0 @@
---
-title: 核心数据流
-updated: 2026-04-11
-status: active
-tags: [data-flow, architecture]
---
-
-# 核心数据流
-
-> 从 [[index]] 导航到此处。架构细节见 [[architecture]]
-
-## 主数据流
-
-```
-用户操作 → React UI → Zustand Store → Tauri invoke() → zclaw-kernel → LLM/Tools/Skills/Hands
-```
-
-这是 ZCLAW 最核心的一条数据通路。所有用户交互都经过这条链路。
-
-## 聊天消息流
-
-```
-用户输入
-  → streamStore.sendMessage(content)
-    → effectiveSessionKey = conversationStore.sessionKey || uuid()
-    → effectiveAgentId = resolveGatewayAgentId(currentAgent)
-    → client.chatStream(content, callbacks, options)
-      → [KernelClient] Tauri invoke('kernel_chat', ...)
-        → Kernel → loop_runner → LLM Driver
-        → Tauri Event emit('chat-response-delta', ...)
-          → onDelta(text) → streamStore 追加 delta
-          → onTool(tool) → toolStore 更新
-          → onHand(hand) → handStore 更新
-          → onComplete() → conversationStore 持久化
-      → [SaaSRelay] HTTP POST /api/v1/relay/chat → SSE stream
-      → [GatewayClient] WebSocket send → onmessage 回调
-  → 5 分钟超时守护 (kernel-chat.ts:76)
-```
-
-## 客户端路由决策流
-
-```
-connectionStore.connect(url?, token?)
-  │
-  ├── Admin 模式? → localStorage('zclaw-saas-account').llm_routing
-  │     ├── "relay" → SaaS Relay
-  │     └── "local" → Kernel (adminForcedLocal=true)
-  │
-  ├── SaaS 模式? → localStorage('zclaw-connection-mode') === 'saas'
-  │     → health check SaaS
-  │       ├── 可达 → Tauri: KernelClient + SaaS baseUrl
-  │       │         Browser: SaaSRelayGatewayClient (SSE)
-  │       └── 不可达 → 降级到本地 Kernel
-  │
-  ├── Tauri 桌面? → isTauriRuntime() === true
-  │     → KernelClient + 自定义模型配置
-  │
-  └── Fallback → GatewayClient via WebSocket/REST
-```
-
-## 记忆管道流
-
-```
-对话发生
-  → extraction_adapter (LLM 提取: 偏好/知识/经验)
-    → MemoryEntry { agent_id, memory_type, content, keywords }
-    → SqliteStorage.store()
-      → FTS5 全文索引 + TF-IDF 权重计算
-      → (可选) EmbeddingClient.embed() → 向量存储 [未激活]
-
-查询时:
-  → MemoryRetriever.retrieve(query, agent_id)
-    → QueryAnalyzer: 意图分类 + 关键词提取 + 同义词扩展 (CJK)
-    → SemanticScorer: TF-IDF 匹配 + (可选) embedding 相似度
-    → 返回 top-k 相关记忆
-
-注入时:
-  → PromptInjector.inject(system_prompt, memories)
-    → token 预算控制
-    → 格式化为结构化上下文块
-    → 插入到 system prompt 中
-```
-
-## SaaS 认证流
-
-```
-用户登录
-  → POST /api/v1/auth/login { email, password }
-  → 验证 (Argon2id + OsRng 盐)
-  → 签发 JWT (Claims: user_id, role, pwv)
-  → set_auth_cookies():
-      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
-      zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly)
-  → 前端: saasStore 存储 → OS keyring 存 JWT
-
-Token 刷新:
-  → POST /api/v1/auth/refresh
-  → 验证 refresh_token (单次使用，旧 token 撤销到 DB)
-  → 签发新 access + refresh token
-
-密码修改:
-  → 更新 password_version (pwv)
-  → 所有旧 JWT 自动失效 (Claims.pwv != DB.pwv)
-```
-
-## 管家模式流
-
-```
-用户消息
-  → ButlerRouter 中间件
-    → 关键词 4 域分类: healthcare / data_report / policy / meeting
-    → 增强 system prompt (领域专用指令)
-  → LLM 响应
-  → PainAggregator 提取痛点
-    → PainStorage (内存 Vec 热缓存 + SQLite 持久)
-  → SolutionGenerator
-    → 基于痛点生成解决方案提案
-
-冷启动:
-  idle → (检测新用户) → greeting_sent → waiting_response → completed
-```
-
-## Pipeline 执行流
-
-```
-YAML Pipeline 定义
-  → PipelineExecutor.load(yaml)
-  → 构建 DAG (按依赖排序)
-  → 逐步执行:
-    → ActionRegistry.resolve(action_type)
-    → 执行 action → PipelineRun.step_results
-    → 全部完成 → PipelineRun.status = Completed
-  → 17 个行业模板在 pipelines/ 目录
-```
-
-## Hands 触发流
-
-```
-UI 触发 → handStore.trigger(handName, params)
-  → Tauri invoke('hand_trigger', { handName, params })
-    → Kernel → Hand 执行
-    → needs_approval? → 等待 approvalStore 确认
-    → 执行结果 → Tauri Event emit
-    → handStore 更新状态 + 记录日志
-```
-
-→ 架构组件见 [[architecture]]
-→ 模块状态见 [[module-status]]
--- a/wiki/file-map.md
+++ b/wiki/file-map.md
@@ -1,149 +0,0 @@
---
-title: 文件地图
-updated: 2026-04-11
-status: active
-tags: [files, reference]
---
-
-# 文件地图
-
-> 从 [[index]] 导航到此处。找什么去哪里。
-
-## 项目顶层
-
-```
-ZCLAW/
-├── CLAUDE.md          → AI 协作规范（唯一入口）
-├── wiki/              → 编译后知识库（新会话入口）
-├── docs/              → 原始文档（raw 层）
-├── skills/            → 75 个 SKILL.md
-├── hands/             → HAND.toml 配置
-├── config/            → TOML 配置模板
-├── pipelines/         → 17 个 YAML Pipeline 模板
-├── saas-config.toml   → SaaS 后端配置
-├── docker-compose.yml → PostgreSQL 容器
-```
-
-## Rust Crates
-
-```
-crates/
-├── zclaw-types/       → L1 基础类型 (AgentId, Message, Error)
-│   └── src/types.rs
-│
-├── zclaw-memory/      → L2 存储层
-│   └── src/sqlite.rs, session_manager.rs
-│
-├── zclaw-runtime/     → L3 运行时
-│   ├── src/driver/       → 4 LLM Driver (anthropic/openai/gemini/local.rs)
-│   ├── src/middleware/    → 14 层中间件
-│   │   ├── butler_router.rs    → 管家路由
-│   │   ├── data_masking.rs     → 数据脱敏
-│   │   └── trajectory_recorder.rs → 轨迹记录
-│   ├── src/loop_runner.rs  → 主聊天循环
-│   └── src/tools/         → 7 个工具
-│
-├── zclaw-kernel/      → L4 核心协调
-│   ├── src/kernel/mod.rs    → Kernel 启动序列
-│   ├── src/config.rs        → LLM 配置 + Driver 工厂
-│   └── src/intelligence/    → 管家/痛点/方案/人格
-│       ├── pain_storage.rs
-│       ├── solution_generator.rs
-│       └── personality_detector.rs
-│
-├── zclaw-skills/      → 技能系统
-│   └── src/semantic_router.rs → TF-IDF 语义路由
-│
-├── zclaw-hands/       → 自主能力
-│   └── src/ (Browser/Collector/Researcher/...)
-│
-├── zclaw-protocols/   → 协议 (MCP + A2A feature-gated)
-│
-├── zclaw-pipeline/    → Pipeline DSL
-│   └── src/executor.rs → DAG 执行器
-│
-├── zclaw-growth/      → 记忆增长
-│   ├── src/extractor.rs       → LLM 记忆提取
-│   ├── src/retriever.rs       → 语义检索
-│   ├── src/injector.rs        → Prompt 注入
-│   ├── src/experience_store.rs → 经验 CRUD
-│   └── src/storage/sqlite.rs  → FTS5 + TF-IDF
-│       └── src/retrieval/semantic.rs → EmbeddingClient trait
-│
-└── zclaw-saas/        → SaaS 后端 (Axum + PostgreSQL)
-    ├── src/auth/         → 认证 (JWT + Cookie + TOTP)
-    ├── src/knowledge/    → 知识库 (23 API + pgvector)
-    ├── src/billing/      → 计费 (Alipay/WeChat)
-    ├── src/workers/      → 7 后台 Worker
-    └── migrations/       → SQL 迁移 (34 表)
-```
-
-## 前端 (desktop/src/)
-
-```
-desktop/src/
-├── store/                → 18 Zustand Store
-│   ├── connectionStore.ts  → 客户端路由 (844行, 核心中枢)
-│   ├── saasStore.ts        → SaaS 认证
-│   ├── uiModeStore.ts      → 简洁/专业模式
-│   └── chat/               → 4 Store (stream/conversation/message/chat)
-│       ├── streamStore.ts
-│       └── conversationStore.ts
-│
-├── components/           → ~135 React 组件
-│   ├── ChatArea.tsx        → 聊天区域
-│   ├── SimpleSidebar.tsx   → 简洁模式侧边栏
-│   └── ButlerPanel.tsx     → 管家面板
-│
-├── hooks/                → React Hooks
-│   └── use-cold-start.ts   → 管家冷启动
-│
-├── lib/                  → 通信和工具
-│   ├── gateway-client.ts   → WebSocket 客户端
-│   ├── kernel-chat.ts      → Tauri 内核聊天
-│   ├── saas-relay-client.ts → SaaS SSE 中继
-│   ├── tauri-gateway.ts    → Tauri 原生命令
-│   ├── pipeline-client.ts  → Pipeline 客户端
-│   ├── secure-storage.ts   → OS keyring 存储
-│   └── webmcp-tools.ts     → WebMCP 调试工具
-│
-└── store/index.ts        → Store 协调器 + client 注入
-```
-
-## Admin V2 (admin-v2/)
-
-```
-admin-v2/src/
-├── pages/    → 15 页面 (Dashboard/Agents/Knowledge/Billing/...)
-├── services/ → SaaS API 调用封装
-└── tests/    → 17 测试文件 (61 tests)
-```
-
-## 文档 (docs/)
-
-```
-docs/
-├── TRUTH.md              → 数字的唯一真相源
-├── ARCHITECTURE_BRIEF.md → 架构参考
-├── features/             → 功能文档
-│   ├── README.md           → 功能索引
-│   ├── AUDIT_TRACKER.md    → 审计进度
-│   └── audit-v12/          → V12 模块化审计报告
-├── knowledge-base/       → 技术知识库
-├── superpowers/
-│   ├── specs/            → 设计规格文档
-│   ├── plans/            → 实施计划
-│   └── reports/          → 测试报告
-└── archive/              → 归档文档 (~70+ 文件)
-```
-
-## Memory (.claude/projects/)
-
-```
-.claude/projects/g--ZClaw-openfang/memory/
-├── MEMORY.md             → memory 索引
-└── 47 个 .md 文件        → 会话间工作记录
-```
-
-→ 架构见 [[architecture]]
-→ 开发规范见 [[development]]
--- a/wiki/hands-skills.md
+++ b/wiki/hands-skills.md
@@ -0,0 +1,90 @@
+---
+title: Hands + Skills
+updated: 2026-04-11
+status: active
+tags: [module, hands, skills]
+---
+
+# Hands + Skills
+
+> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]]
+
+## 设计思想
+
+**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层)**
+
+- Hands: 浏览器自动化、数据收集、Twitter 操作等 — **执行动作**
+- Skills: 75 个 SKILL.md 文件 — **语义路由匹配**，增强 LLM 的领域知识
+- 触发: 用户请求 → LLM 判断需要执行 → 选择 Hand/Skill → 执行
+
+## 代码逻辑
+
+### Hands (9 启用 + 2 禁用)
+
+| 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 实现 |
+
+### 触发流
+
+```
+UI 触发 → handStore.trigger(handName, params)
+  → Tauri invoke('hand_trigger', { handName, params })
+    → Kernel → Hand 执行
+    → needs_approval? → 等待 approvalStore 确认
+    → 执行结果 → Tauri Event emit
+    → handStore 更新状态 + 记录日志
+```
+
+### Skills (75 个)
+
+```
+skills/
+├── SKILL_001_数据分析.md
+├── SKILL_002_报告生成.md
+├── ... (75 个 SKILL.md 文件)
+```
+
+每个 SKILL.md 定义:
+- 技能名称和描述
+- 触发条件
+- 执行步骤
+- 输入/输出格式
+
+### 语义路由
+
+`crates/zclaw-skills/src/semantic_router.rs`
+
+```
+用户消息 → SemanticSkillRouter
+  → TF-IDF 计算消息与 75 个技能的相似度
+  → 返回最匹配的技能
+  → ButlerRouter 使用此结果增强 system prompt
+```
+
+## 关联模块
+
+- [[chat]] — 消息流中可能触发 Hand/Skill
+- [[butler]] — ButlerRouter 使用语义路由匹配技能
+- [[middleware]] — 技能注入通过中间件实现
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-hands/src/` | 9 个 Hand 实现 |
+| `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 |
+| `skills/*.md` | 75 个技能定义 |
+| `hands/*/HAND.toml` | Hand 配置 |
+| `desktop/src/store/handStore.ts` | 前端 Hand 状态 |
+| `desktop/src/store/approvalStore.ts` | 审批状态 |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -7,90 +7,56 @@ status: active
 # ZCLAW 项目知识库

 > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。
+> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。

-## 一句话画像
+## 项目画像

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

 ## 关键数字

-| 维度 | 数量 |
-|------|------|
-| Rust Crates | 10 |
-| Rust 代码 | ~66,000 行 |
-| Rust 测试 | 822 (684 workspace + 138 SaaS) |
-| Tauri 命令 | 182 (92 有前端调用, 20 @reserved, 70 孤儿) |
-| SaaS API | 140 端点 |
-| SaaS 数据表 | 34 |
-| Zustand Store | 18 |
-| React 组件 | ~135 |
-| 中间件层 | 14 |
-| SKILL.md | 75 |
-| Hands | 9 启用 + 2 禁用 |
-| Pipeline 模板 | 17 YAML |
-| LLM Provider | 8 |
+Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17

-## 核心架构 → [[architecture]]
-
- **客户端路由**: Admin / SaaS Relay / Local Kernel / External Gateway
- **聊天流**: GatewayClient(WS) / KernelClient(Tauri Event) / SaaSRelay(HTTP SSE)
- **LLM 驱动**: Anthropic / OpenAI / Gemini / Local + 国内 3 家(DeepSeek/Qwen/Moonshot)
- **管家模式**: ButlerRouter 4域分类 + 冷启动 4阶段 + 双模式UI
-
-## 子系统状态 → [[module-status]]
-
-| 子系统 | 状态 | 说明 |
-|--------|------|------|
-| 管家模式 (Butler) | 活跃 | ButlerRouter + 冷启动 + 简洁UI + 痛点持久化 |
-| Hermes 管线 | 活跃 | ExperienceStore + UserProfiler + NlScheduleParser + TrajectoryRecorder |
-| 聊天流 (ChatStream) | 稳定 | 3 种实现，5min 超时守护 |
-| 记忆管道 (Memory) | 稳定 | 对话→提取→FTS5+TF-IDF→检索→注入 |
-| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 |
-| Pipeline DSL | 稳定 | 17 模板 + DAG 执行器 |
-| Hands 系统 | 稳定 | 9 启用 |
-| 技能系统 | 稳定 | 75 SKILL.md + 语义路由 |
-| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) |
-
-## 核心数据流 → [[data-flows]]
+## 模块导航树

 ```
-用户操作 → React UI → Zustand Store → Tauri Commands → Kernel → LLM/Tools/Skills/Hands
+ZCLAW
+├── [[routing]]        客户端路由 — 4分支决策，SaaS Relay是主路径
+│   └── [[chat]]       聊天系统 — 3种ChatStream，SaaS Token Pool是主路径
+│
+├── [[saas]]           SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
+│   ├── 认证           JWT + Cookie + Token池 RPM/TPM轮换
+│   ├── 计费           配额实时递增 + Alipay/WeChat
+│   └── Admin V2       15页管理后台
+│
+├── [[butler]]         管家模式 — 默认交互范式，4域路由+冷启动+痛点
+│
+├── [[middleware]]     中间件链 — 14层，DataMasking→ButlerRouter→TrajectoryRecorder
+│
+├── [[memory]]         记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
+│
+├── [[hands-skills]]   Hands(9) + Skills(75) — 自主能力+语义技能路由
+│
+├── [[pipeline]]       Pipeline DSL — YAML+DAG执行器+17行业模板
+│
+├── [[development]]    开发规范 — 闭环工作法/验证命令/提交规范
+├── [[known-issues]]   已知问题 — P0/P1已修复，P2待处理
+└── [[log]]            变更日志 — append-only
 ```

- 4 种 LLM Driver，国内兼容通过 base_url
- SaaS unreachable 时自动降级到本地 Kernel
- 记忆闭环: 对话 → extraction → FTS5+TF-IDF → 检索 → 注入 system prompt
+## 核心架构决策（为什么这样设计）

-## 开发须知 → [[development]]
+**Q: 为什么 Tauri 不直连 LLM？**
+→ 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。

- **闭环工作法**: 定位→修复→验证→提交→文档，每步不可跳过
- **功能冻结**: 禁止新增 SaaS API / SKILL.md / Tauri 命令 / 中间件 / admin 页面
- **验证命令**: `cargo check --workspace` / `pnpm tsc --noEmit` / `pnpm vitest run`
+**Q: 为什么有3种 ChatStream？**
+→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。

-## 已知问题 → [[known-issues]]
-
- 所有 P0/P1 已修复
- 10 项 P2 代码质量问题待处理
- 70 个 Tauri 命令孤儿（无前端调用且无 @reserved）
-
-## 文件地图 → [[file-map]]
-
-关键路径速查，按 `crates/` / `desktop/src/` / `admin-v2/` 组织。
-
-## 变更日志 → [[log]]
-
-Append-only 操作记录。
-
---
-
-## 给新会话的快速引导
-
-1. 先读本文件 (你正在读)
-2. 需要了解架构 → 读 [[architecture]]
-3. 需要了解某模块状态 → 读 [[module-status]]
-4. 需要了解数据流 → 读 [[data-flows]]
-5. 需要开发 → 读 [[development]]
-6. 需要知道有哪些 bug → 读 [[known-issues]]
-7. 需要找文件 → 读 [[file-map]]
+**Q: 为什么管家模式是默认？**
+→ 面向医院行政等非技术用户，4域关键词分类+痛点积累+方案生成，降低使用门槛。

 > 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准
--- a/wiki/known-issues.md
+++ b/wiki/known-issues.md
@@ -7,51 +7,24 @@ tags: [issues, bugs]

 # 已知问题

-> 从 [[index]] 导航到此处。完整缺陷清单见 `docs/TRUTH.md §3`
+> 从 [[index]] 导航。完整清单见 `docs/TRUTH.md §3`

-## P0 — 必然崩溃
+## 当前状态

-| ID | 问题 | 状态 |
-|----|------|------|
-| SEC2-P0-01 | skill_execute 反序列化崩溃 | 已修复 |
-| SEC2-P0-02 | TaskTool::default() panic | 已修复 |
-
-## P1 — 功能失效
-
-| ID | 问题 | 状态 |
-|----|------|------|
-| SEC2-P1-01 | FactStore trait 零实现 | 已修复 |
-| SEC2-P1-02 | agent-templates 路径错误 (缺 /api/v1) | 已修复 |
-| SEC2-P1-03 | hand-execution-complete 无监听 | 已修复 |
-| SEC2-P1-04 | InMemoryStorage RwLock unwrap 级联 | 已修复 |
-| SEC2-P1-05~07 | HandRun 持久化静默忽略 (3处) | 已修复 |
-| SEC2-P1-08 | FTS 索引更新静默失败 | 已修复 |
-| SEC2-P1-09 | Worker dispatch 静默失败 | 已修复 |
-
-## P1.5 — 代码质量
-
-| ID | 问题 | 状态 |
-|----|------|------|
-| SEC2-P1.5-01 | Capability _ => false 通配符 | 已修复 |
-| SEC2-P1.5-02 | billing let _ = ... 冗余 | 已修复 |
-| SEC2-P1.5-03 | relay SSE 错误路径 send 失败未记录 | 已修复 |
-| SEC2-P1.5-04 | WASM runner 缺少状态注解 | 已修复 |
-| SEC2-P1.5-05 | Tauri 命令无连接状态标注 | 已修复 |
-| SEC2-P1.5-06 | extract_token_usage 静默丢弃解析错误 | 已修复 |
-| SEC2-P1.5-07 | relay current_key_id 防御性 unwrap | 已修复 |
-
-## P2 — 代码质量（待处理）
-
-10 项代码质量问题 (SEC2-P2-01~10)，非阻塞性。详见 `docs/TRUTH.md §3.3`
+| 级别 | 数量 | 状态 |
+|------|------|------|
+| P0 (崩溃) | 2 | 全部已修复 |
+| P1 (功能失效) | 9 | 全部已修复 |
+| P1.5 (代码质量) | 7 | 全部已修复 |
+| P2 (代码质量) | 10 | 待处理 |

 ## 长期观察项

-| 问题 | 说明 | 行动 |
+| 问题 | 说明 | 位置 |
 |------|------|------|
-| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | 逐步标注或清理 |
-| Embedding 未激活 | EmbeddingClient trait 已写但未调用 | 发布后迭代 |
-| SaaS embedding deferred | pgvector 索引就绪，生成未实现 | 发布后迭代 |
-| webhook 死代码 | 5 路由定义但未挂载 | 待删除 |
+| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | `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/` |

-→ 模块状态见 [[module-status]]
-→ 开发规范见 [[development]]
+→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]]
--- a/wiki/memory.md
+++ b/wiki/memory.md
@@ -0,0 +1,106 @@
+---
+title: 记忆管道
+updated: 2026-04-11
+status: active
+tags: [module, memory, growth]
+---
+
+# 记忆管道 (Memory Pipeline)
+
+> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]]
+
+## 设计思想
+
+**核心问题: LLM 无状态，每次对话都从零开始。需要从历史对话中积累知识。**
+
+设计决策:
+1. **闭环架构** — 对话 → 提取 → 索引 → 检索 → 注入，形成正向循环
+2. **FTS5 + TF-IDF** — 轻量级语义搜索，不依赖外部 embedding 服务
+3. **Token 预算控制** — 注入 system prompt 时有 token 上限，防止溢出
+4. **EmbeddingClient trait 已预留** — 接口已写，激活即可升级到向量搜索
+
+## 代码逻辑
+
+### 闭环数据流
+
+```
+[提取] 对话发生
+  → MemoryExtractor (crates/zclaw-growth/src/extractor.rs)
+    → LLM 提取: 偏好 (Preference) / 知识 (Knowledge) / 经验 (Experience)
+    → MemoryEntry { agent_id, memory_type, content, keywords, importance }
+
+[索引] 存储
+  → SqliteStorage.store() (crates/zclaw-growth/src/storage/sqlite.rs)
+    → SQLite + FTS5 全文索引
+    → TF-IDF 权重计算
+    → (可选) EmbeddingClient.embed() → 向量存储 [未激活]
+
+[检索] 查询时
+  → MemoryRetriever.retrieve(query, agent_id) (crates/zclaw-growth/src/retriever.rs)
+    → QueryAnalyzer: 意图分类 (Preference/Knowledge/Experience/Code/General)
+    → 中文+英文关键词提取 + CJK 支持 + 同义词扩展
+    → SemanticScorer: TF-IDF 匹配 (70% embedding / 30% TF-IDF, embedding 未激活)
+    → 返回 top-k 相关记忆
+
+[注入] 给 LLM
+  → PromptInjector.inject(system_prompt, memories) (crates/zclaw-growth/src/injector.rs)
+    → token 预算控制
+    → 格式化为结构化上下文块
+    → 插入到 system prompt 中
+```
+
+### 经验存储 (ExperienceStore)
+
+Hermes 管线 Chunk1 新增:
+
+```
+ExperienceStore (crates/zclaw-growth/src/experience_store.rs)
+  → CRUD 封装: pain → solution → outcome 结构化经验
+  → 底层使用 VikingAdapter
+  → URI scheme: agent://{agent_id}/experience/...
+```
+
+### 查询意图分类
+
+`QueryAnalyzer` 支持 5 种意图:
+
+| 意图 | 说明 | 检索策略 |
+|------|------|----------|
+| Preference | 用户偏好 | 精确匹配 preference 类型记忆 |
+| Knowledge | 知识查询 | 语义搜索 knowledge 类型 |
+| Experience | 经验检索 | 时间+相关性排序 |
+| Code | 代码相关 | 关键词优先 |
+| General | 通用 | 混合策略 |
+
+### Embedding 基础设施 (已写未激活)
+
+```
+EmbeddingClient trait (crates/zclaw-growth/src/retrieval/semantic.rs)
+  → async embed(&str) -> Vec<f32>
+  → is_available() -> bool
+  → 当前实现: NoOpEmbeddingClient (始终返回空)
+
+SaaS 侧:
+  → pgvector HNSW 索引就绪 (knowledge_chunks 表, vector(1536))
+  → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred)
+```
+
+## 关联模块
+
+- [[chat]] — 对话是记忆的输入源
+- [[butler]] — 管家模式可能利用记忆提供个性化响应
+- [[middleware]] — 记忆注入通过中间件或 hook 实现
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-growth/src/extractor.rs` | LLM 记忆提取 |
+| `crates/zclaw-growth/src/retriever.rs` | 语义检索 |
+| `crates/zclaw-growth/src/injector.rs` | Prompt 注入 (token 预算) |
+| `crates/zclaw-growth/src/experience_store.rs` | 经验 CRUD |
+| `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 |
+| `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 |
--- a/wiki/middleware.md
+++ b/wiki/middleware.md
@@ -0,0 +1,63 @@
+---
+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` | 轨迹记录 |
--- a/wiki/module-status.md
+++ b/wiki/module-status.md
@@ -1,70 +0,0 @@
---
-title: 子系统状态
-updated: 2026-04-11
-status: active
-tags: [status, modules]
---
-
-# 子系统状态
-
-> 从 [[index]] 导航到此处。数字真相源: `docs/TRUTH.md`
-
-## 活跃子系统
-
-| 子系统 | 状态 | 最新变更 | 关键文件 |
-|--------|------|----------|----------|
-| 管家模式 (Butler) | 活跃 | 04-09 ButlerRouter + 双模式UI + 痛点持久化 + 冷启动 | `middleware/butler_router.rs`, `pain_storage.rs` |
-| Hermes 管线 | 活跃 | 04-09 4 Chunk: 自我改进+用户建模+NL Cron+轨迹压缩 | `experience_store.rs`, `user_profiler.rs`, `nl_schedule_parser.rs` |
-| 聊天流 (ChatStream) | 稳定 | 04-02 ChatStore 拆分为 4 Store | `streamStore.ts`, `conversationStore.ts` |
-| 记忆管道 (Memory) | 稳定 | 04-02 闭环: 对话→提取→FTS5+TF-IDF→检索→注入 | `crates/zclaw-growth/` |
-| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 | `saas/auth/handlers.rs` |
-| Pipeline DSL | 稳定 | 04-01 17 YAML 模板 + DAG 执行器 | `crates/zclaw-pipeline/` |
-| Hands 系统 | 稳定 | 9 启用 (详见下方) | `crates/zclaw-hands/` |
-| 技能系统 (Skills) | 稳定 | 75 SKILL.md + 语义路由 | `crates/zclaw-skills/` |
-| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) | `crates/zclaw-runtime/src/middleware/` |
-
-## Hands 详细状态
-
-| Hand | 功能 | 状态 | 依赖 |
-|------|------|------|------|
-| Browser | 浏览器自动化 | 可用 | WebDriver |
-| Collector | 数据收集聚合 | 可用 | — |
-| Researcher | 深度研究 | 可用 | LLM |
-| Clip | 视频处理 | 需 FFmpeg | FFmpeg |
-| Twitter | Twitter 自动化 | 可用 | OAuth 1.0a (写操作) |
-| Whiteboard | 白板演示 | 可用 | 导出开发中 |
-| Slideshow | 幻灯片生成 | 可用 | — |
-| Speech | 语音合成 | 可用 | Browser TTS |
-| Quiz | 测验生成 | 可用 | — |
-| Predictor | 预测分析 | 禁用 | 无 Rust 实现 |
-| Lead | 销售线索发现 | 禁用 | 无 Rust 实现 |
-
-## Tauri 命令分布
-
-| 类别 | 数量 | 说明 |
-|------|------|------|
-| 有前端调用 | 92 | 正常使用中 |
-| @reserved | 20 | 已标注保留 |
-| 孤儿 | 70 | 无前端调用且无标注 |
-
-## 测试覆盖
-
-| 层级 | 数量 | 状态 |
-|------|------|------|
-| Rust workspace | 684 | 全通过 |
-| SaaS 集成 | 138 | 全通过 (需 PostgreSQL) |
-| 前端 vitest | 330 | 330 passed + 1 skipped |
-| Admin V2 | 61 | 17 文件 |
-
-## SaaS API 分布
-
-12 个路由模块: account / agent_template / auth / billing / knowledge / migration / model_config / prompt / relay / role / scheduled_task / telemetry
-
-总计 140 端点 (138 标准 + 2 dev-only)
-
-## 数据表 (34 个)
-
-核心表: users, agents, conversations, messages, knowledge_*, billing_*, agent_templates, model_configs, roles, permissions, scheduled_tasks, telemetry
-
-→ 架构细节见 [[architecture]]
-→ 已知问题见 [[known-issues]]
--- a/wiki/pipeline.md
+++ b/wiki/pipeline.md
@@ -0,0 +1,70 @@
+---
+title: Pipeline DSL
+updated: 2026-04-11
+status: active
+tags: [module, pipeline, dsl]
+---
+
+# Pipeline DSL
+
+> 从 [[index]] 导航。关联模块: [[hands-skills]]
+
+## 设计思想
+
+**Pipeline = 可编排的工作流，按 DAG 依赖顺序执行步骤。**
+
+- YAML 定义 Pipeline 结构（步骤、依赖、输入/输出）
+- DAG 执行器按依赖拓扑排序执行
+- 17 个行业模板覆盖 10 大行业
+- 前端已接通 8 个 Tauri invoke 调用
+
+## 代码逻辑
+
+### 架构
+
+```
+YAML Pipeline 定义
+  → PipelineExecutor (crates/zclaw-pipeline/src/executor.rs)
+  → 构建 DAG (按依赖排序)
+  → 逐步执行:
+    → ActionRegistry.resolve(action_type)
+    → 执行 action → PipelineRun.step_results
+    → 全部完成 → PipelineRun.status = Completed
+```
+
+### 运行状态
+
+```rust
+enum RunStatus { Pending, Running, Completed, Failed, Cancelled }
+```
+
+### 模板 (17 个 YAML)
+
+位于 `pipelines/` 目录，覆盖:
+- 汕头玩具行业、服装设计、医疗
+- 数据分析、报告生成
+- 教育、营销
+- 等 10 大行业
+
+### 前端集成
+
+| 组件 | 文件 |
+|------|------|
+| PipelineClient | `desktop/src/lib/pipeline-client.ts` |
+| Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` |
+
+8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用。
+
+## 关联模块
+
+- [[hands-skills]] — Pipeline 步骤可能调用 Hand/Skill
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-pipeline/src/executor.rs` | DAG 执行器 |
+| `crates/zclaw-pipeline/src/` | Pipeline DSL 解析 |
+| `pipelines/` | 17 个 YAML 模板 |
+| `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 |
+| `desktop/src-tauri/src/pipeline_commands/` | Tauri 命令桥接 |
--- a/wiki/routing.md
+++ b/wiki/routing.md
@@ -0,0 +1,105 @@
+---
+title: 客户端路由
+updated: 2026-04-11
+status: active
+tags: [module, routing, connection]
+---
+
+# 客户端路由
+
+> 从 [[index]] 导航。关联模块: [[chat]] [[saas]]
+
+## 设计思想
+
+**核心决策: Tauri 桌面端通过 SaaS Token Pool 中转访问 LLM，不直连。**
+
+为什么？
+1. **集中密钥管理** — 用户不需要自己的 API Key，SaaS 维护共享 Key 池
+2. **用量追踪 + 计费** — 每次调用经过 SaaS，`record_usage` worker 记录 token 消耗
+3. **模型白名单** — Admin 配置哪些模型可用，`listModels()` 返回白名单
+4. **降级保障** — SaaS 挂了自动切本地 Kernel，桌面端不变砖
+
+## 代码逻辑
+
+### 4 分支决策树
+
+入口: `connectionStore.ts:349` → `connect(url?, token?)`
+
+```
+connect()
+  │
+  ├── [1] Admin 强制路由: localStorage llm_routing
+  │     ├── "relay" → 强制 SaaS Relay 模式
+  │     └── "local" → 强制本地 Kernel (adminForceLocal=true)
+  │
+  ├── [2] SaaS Relay 模式: localStorage('zclaw-connection-mode') === 'saas'
+  │     ├── Tauri: KernelClient + baseUrl = saasUrl/api/v1/relay
+  │     │         apiKey = SaaS JWT (不是 LLM Key!)
+  │     ├── Browser: SaaSRelayGatewayClient (SSE)
+  │     └── SaaS 不可达 → 降级到本地 Kernel
+  │
+  ├── [3] 本地 Kernel: isTauriRuntime() === true
+  │     KernelClient + 用户自定义模型配置
+  │     用户需要自己的 API Key
+  │
+  └── [4] External Gateway (fallback)
+        GatewayClient via WebSocket/REST
+```
+
+### SaaS Relay 主路径 (Tauri 桌面端)
+
+关键代码: `connectionStore.ts:482-535`
+
+```ts
+kernelClient.setConfig({
+  provider: 'custom',
+  model: modelToUse,                          // 从 SaaS listModels() 获取
+  apiKey: session.token,                      // SaaS JWT，不是 LLM Key
+  baseUrl: `${session.saasUrl}/api/v1/relay`, // 指向 SaaS relay
+  apiProtocol: 'openai',
+});
+```
+
+**注意**: Kernel 仍然执行 LLM 调用逻辑，但请求发往 SaaS relay 而非直连 LLM。
+SaaS relay 接到请求后，从 Token Pool 中取一个可用 Key，转发给真实 LLM。
+
+### SaaS 降级流程
+
+关键代码: `connectionStore.ts:446-468`
+
+```
+listModels() 失败
+  → 401 → session 过期 → logout → 要求重新登录
+  → 其他错误 → saasDegraded = true
+    → saasStore.saasReachable = false
+    → 降级到本地 Kernel 模式
+```
+
+### 客户端类型
+
+| 客户端 | 传输 | 文件 | 用途 |
+|--------|------|------|------|
+| GatewayClient | WebSocket + REST | `lib/gateway-client.ts` | 外部 Gateway 进程 |
+| KernelClient | Tauri invoke() | `lib/kernel-chat.ts` | 内置 Kernel (桌面端) |
+| SaaSRelayGatewayClient | HTTP SSE | `lib/saas-relay-client.ts` | 浏览器端 SaaS 中继 |
+
+`getClient()` 定义: `connectionStore.ts:844`
+所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。
+
+## 关联模块
+
+- [[chat]] — 路由决定使用哪种 ChatStream
+- [[saas]] — Token Pool、认证、模型管理
+- [[middleware]] — 请求经过中间件链处理
+- [[butler]] — 管家模式通过 ButlerRouter 中间件介入
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/store/connectionStore.ts` | 路由决策核心 (844行) |
+| `desktop/src/lib/gateway-client.ts` | WebSocket 客户端 |
+| `desktop/src/lib/kernel-chat.ts` | Tauri 内核聊天 |
+| `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
@@ -0,0 +1,139 @@
+---
+title: SaaS 平台
+updated: 2026-04-11
+status: active
+tags: [module, saas, auth, billing]
+---
+
+# SaaS 平台
+
+> 从 [[index]] 导航。关联模块: [[routing]] [[chat]]
+
+## 设计思想
+
+**核心定位: SaaS 是 Tauri 桌面端的中枢，不是独立 Web 应用。**
+
+关键决策:
+1. **Token Pool** — 桌面端不持有 LLM API Key，SaaS 维护共享 Key 池，RPM/TPM 轮换
+2. **JWT + Cookie 双通道** — Tauri 用 OS keyring 存 JWT，浏览器用 HttpOnly cookie
+3. **计费闭环** — 配额实时递增 → 聚合器调度 → mock 支付路由
+4. **Admin V2** — 15 页管理后台，管理模型/用户/计费/知识库
+
+## 代码逻辑
+
+### 认证流
+
+```
+用户登录 (POST /api/v1/auth/login)
+  → Argon2id + OsRng 盐验证密码
+  → 签发 JWT (Claims: user_id, role, pwv)
+  → set_auth_cookies():
+      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
+      zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly)
+      Secure: dev=false, prod=true | SameSite=Strict
+
+前端存储:
+  → Tauri: OS keyring → saasStore.token
+  → 浏览器: HttpOnly Cookie (JS 不可读)
+  → localStorage: saasUrl + account 信息 (非敏感)
+```
+
+### Token 池 + 限流
+
+```
+SaaS Relay 收到 LLM 请求 (POST /api/v1/relay/chat/completions)
+  → 验证 JWT → 提取 user_id
+  → 从 Token Pool 选择可用 Key (RPM/TPM 轮换)
+  → 转发请求到真实 LLM API
+  → 记录 usage (record_usage worker)
+  → 返回响应
+
+限流规则:
+  → /api/auth/login: 5次/分钟/IP (防暴力) + 持久化到 PostgreSQL
+  → /api/auth/register: 3次/小时/IP (防刷注册)
+  → 公共端点: 20次/分钟/IP
+```
+
+### 密码安全
+
+```
+JWT password_version (pwv):
+  → JWT Claims 含 pwv 字段
+  → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv
+  → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效
+
+密码存储: Argon2id + OsRng 随机盐
+TOTP 加密: AES-256-GCM + 随机 Nonce
+```
+
+### Token 刷新
+
+```
+POST /api/v1/auth/refresh
+  → 验证 refresh_token (单次使用)
+  → 旧 refresh_token 撤销到 DB (rotation 校验)
+  → 签发新 access + refresh token
+```
+
+### SaaS API 分布
+
+12 个路由模块，140 端点:
+
+| 模块 | 端点数 | 说明 |
+|------|--------|------|
+| 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 迁移 |
+
+### 数据表 (34 个)
+
+核心: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version
+
+### 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) |
+
+## 关联模块
+
+- [[routing]] — SaaS Relay 是 Tauri 的主路径
+- [[chat]] — 聊天请求经过 SaaS relay 中转
+- [[memory]] — knowledge_chunks 表有 pgvector 索引
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `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/workers/` | 7 个后台 Worker |
+| `crates/zclaw-saas/migrations/` | SQL 迁移 (34 表) |
+| `admin-v2/src/pages/` | 15 页管理后台 |
+| `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 |
+| `desktop/src/store/saasStore.ts` | SaaS 认证状态 |
+
+## 安全
+
+完整审计: `docs/features/SECURITY_PENETRATION_TEST_V1.md`
+- CORS 白名单 (生产缺失拒绝启动)
+- Cookie Secure (dev=false, prod=true)
+- JWT 签名密钥 >= 32 字符 (release fallback 拒绝启动)
+- 独立 TOTP 加密密钥