docs(wiki): Phase D完成 — 6模块页重构(routing/chat/butler/hands-skills/pipeline/data-model)

- routing.md: 移除Store/lib列表+5节模板 (330→131行)
- chat.md: 添加集成契约+不变量 (180→134行)
- butler.md: 移除重复→引用memory/hands-skills (215→150行)
- hands-skills.md: 5节模板+契约+不变量 (281→170行)
- pipeline.md: 添加契约+重组 (157→154行)
- data-model.md: 添加契约+双库架构图 (181→153行)

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

wiki/routing.md

@@ -1,6 +1,6 @@
 ---
 title: 客户端路由
-updated: 2026-04-21
+updated: 2026-04-22
 status: active
 tags: [module, routing, connection]
 ---
@@ -9,318 +9,123 @@ tags: [module, routing, connection]
 
 > 从 [[index]] 导航。关联模块: [[chat]] [[saas]]
 
-## 设计思想
+## 1. 设计决策
 
-**核心决策: Tauri 桌面端通过 SaaS Token Pool 中转访问 LLM，不直连。**
+**核心: Tauri 桌面端通过 SaaS Token Pool 中转访问 LLM，不直连。**
 
-为什么？
-1. **集中密钥管理** — 用户不需要自己的 API Key，SaaS 维护共享 Key 池
-2. **用量追踪 + 计费** — 每次调用经过 SaaS，`record_usage` worker 记录 token 消耗
-3. **模型白名单** — Admin 配置哪些模型可用，`listModels()` 返回白名单
-4. **降级保障** — SaaS 挂了自动切本地 Kernel，桌面端不变砖
+| 决策 | 原因 |
+|------|------|
+| 5 分支路由 | 覆盖全部部署形态: Admin本地 / Tauri+SaaS / Browser+SaaS / Tauri本地 / 外部Gateway |
+| SaaS Relay 中转 | 集中密钥管理 — 用户无需自备 API Key；用量追踪计费 — 每次调用经 SaaS；模型白名单 — Admin 控制可用模型 |
+| 自动降级到本地 Kernel | SaaS 不可达时桌面端不变砖，无感切换，不需要用户干预 |
+| Kernel 不直连 LLM | 直连是降级后备。主路径经 SaaS Token Pool 做 RPM/TPM 轮换 + 故障转移 |
+| getClient() 全局单例 | 所有 Store 通过 `initializeStores()` 获取共享 client，避免重复连接 |
 
-## 功能清单
+## 2. 关键文件 + 数据流
 
-| 功能 | 描述 | 入口文件 | 状态 |
-|------|------|----------|------|
-| 连接管理 | 5 分支路由决策 + 自动降级 | connectionStore.ts | ✅ |
-| SaaS Relay 中转 | Tauri 通过 SaaS Token Pool 中转 LLM | connectionStore.ts | ✅ |
-| 浏览器模式 | SSE 连接 SaaS relay | saas-relay-client.ts | ✅ |
-| 本地 Kernel | Tauri 内置 Kernel 直连 LLM | kernel-client.ts | ✅ |
-| 外部 Gateway | WebSocket 独立进程 | gateway-client.ts | ✅ |
-| Gateway 进程管理 | 启动/停止/重启/状态/诊断 | gateway/commands.rs | ✅ |
-| 健康检查 | 端口检测 + 完整诊断 | health_check.rs | ✅ |
-| 设备配对 | 设备审批 + 公钥交换 | gateway/commands.rs | ✅ |
-| 模型路由 | 白名单验证 + fallback + 别名解析 | connectionStore.ts | ✅ |
+### 核心文件
 
-## 代码逻辑
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/store/connectionStore.ts` | 路由决策核心: 5 分支 + 降级 + 模型路由 |
+| `desktop/src/lib/kernel-chat.ts` | KernelClient ChatStream (Tauri Event) |
+| `desktop/src/lib/kernel-client.ts` | Kernel 客户端配置 (setConfig/boot) |
+| `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream (SSE) |
+| `desktop/src/lib/gateway-client.ts` | External Gateway ChatStream (WebSocket) |
+| `desktop/src/store/index.ts` | Store 协调器 + client 注入 |
 
-### 5 分支 + 降级决策树
-
-入口: `connectionStore.ts` → `connect(url?, token?)`
+### 5 分支决策树
 
 ```
 connect()
-  │
-  ├── [1] Admin 强制本地: adminRouting === 'local' && isTauri()
-  │     → 直接走 Kernel 模式，跳过 SaaS
-  │
-  ├── [2] SaaS Relay (Tauri 路径): savedMode === 'saas' && isTauri()
-  │     → KernelClient + baseUrl = saasUrl/api/v1/relay
-  │     → apiKey = SaaS JWT (不是 LLM Key!)
-  │     → SaaS 不可达 → 降级到本地 Kernel
-  │
-  ├── [3] SaaS Relay (Browser 路径): savedMode === 'saas' && !isTauri()
-  │     → SaaSRelayGatewayClient (SSE)
-  │     → SaaS 不可达 → 降级到本地 Kernel
-  │
-  ├── [4] 本地 Kernel: isTauriRuntime() && 非 SaaS 模式
-  │     → KernelClient + 用户自定义模型配置
-  │     → 用户需要自己的 API Key
-  │
-  └── [5] External Gateway (fallback): !isTauri()
-        → GatewayClient via WebSocket/REST
+  ├─ [1] Admin强制本地: adminRouting=local && isTauri → Kernel 直连
+  ├─ [2] SaaS+Tauri: savedMode=saas && isTauri → KernelClient + baseUrl=SaaS relay
+  │     └─ SaaS不可达 → 降级 [4]
+  ├─ [3] SaaS+Browser: savedMode=saas && !isTauri → SaaSRelayClient (SSE)
+  │     └─ SaaS不可达 → 降级 [4]
+  ├─ [4] 本地Kernel: isTauriRuntime && 非SaaS → KernelClient + 用户自配 Key
+  └─ [5] 外部Gateway: !isTauri → GatewayClient (WebSocket)
 ```
 
-### SaaS Relay 主路径 (Tauri 桌面端)
+### 集成契约
 
-关键代码: `connectionStore.ts:482-535`
+| 方向 | 模块 | 接口 | 说明 |
+|------|------|------|------|
+| Calls -> | saas | relay URL + JWT | Chat relay, model list, 用量上报 |
+| Calls -> | kernel | Tauri invoke | Kernel boot, chat, config |
+| Called by <- | all stores | `getClient()` | 每个 API 调用都经过路由决策 |
+| Provides -> | UI | Connection status, model list | 所有聊天依赖组件消费 |
+
+## 3. 代码逻辑
+
+### 模型路由链 (SaaS Relay 主路径)
 
-```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。
+前端选择模型 → preferredModel || fallbackId
+  → kernelClient.setConfig({ model, apiKey: JWT, baseUrl: saasUrl/api/v1/relay })
+    → Tauri invoke kernel_init → Kernel::boot(config)
+      → loop_runner → POST {base_url}/chat/completions
+        → SaaS Relay → cache 精确匹配 model_id → Key Pool 轮换 → 真实 LLM
+          → SSE 流式返回
+```
 
 ### SaaS 降级流程
 
-关键代码: `connectionStore.ts:446-468`
-
 ```
 listModels() 失败
-  → 401 → session 过期 → logout → 要求重新登录
-  → 其他错误 → saasDegraded = true
-    → saasStore.saasReachable = false
-    → 降级到本地 Kernel 模式
+  → 401 → session 过期 → logout
+  → 其他 → saasDegraded=true → 降级本地 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 中继 |
+| 客户端 | 传输 | 用途 |
+|--------|------|------|
+| GatewayClient | WebSocket + REST | 外部 Gateway 进程 |
+| KernelClient | Tauri invoke() | 内置 Kernel (桌面端) |
+| SaaSRelayGatewayClient | HTTP SSE | 浏览器端 SaaS 中继 |
 
-`getClient()` 定义: `connectionStore.ts:844`
-所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。
+### 不变量
 
-### Store 层 (16 根文件 + chat/4 + saas/5 = 25)
-
-```
-desktop/src/store/
-├── index.ts              Store 协调器 + client 注入
-├── agentStore.ts         Agent 分身管理
-├── browserHandStore.ts   浏览器 Hand 状态
-├── chatStore.ts          聊天通用状态
-├── classroomStore.ts     课堂模式
-├── configStore.ts        配置读写
-├── connectionStore.ts    路由决策核心
-├── handStore.ts          Hand 状态管理
-├── industryStore.ts      行业配置 (已接通 ButlerPanel)
-├── memoryGraphStore.ts   记忆图谱
-├── offlineStore.ts       离线队列
-├── saasStore.ts          SaaS 认证 (re-export barrel)
-├── securityStore.ts      安全状态
-├── sessionStore.ts       会话管理
-├── uiModeStore.ts        双模式 UI
-├── workflowStore.ts      工作流状态
-├── chat/
-│   ├── artifactStore.ts  聊天产物
-│   ├── conversationStore.ts  会话管理
-│   ├── messageStore.ts   消息持久化
-│   └── streamStore.ts    流式编排
-└── saas/                 (拆分子模块, 04-17 refactor)
-    ├── index.ts          子模块入口
-    ├── auth.ts           认证逻辑
-    ├── billing.ts        计费逻辑
-    ├── shared.ts         共享状态/工具
-    └── types.ts          类型定义
-```
-
-### lib/ 工具层 (75 个 .ts 文件)
-
-关键分类:
-
-| 类别 | 文件 | 数量 |
-|------|------|------|
-| Kernel 通信 | kernel-client/kernel-chat/kernel-agent/kernel-skills/kernel-triggers/kernel-hands/... | 8 |
-| SaaS 通信 | saas-client/saas-auth/saas-billing/saas-relay/saas-industry/saas-knowledge/... | 12 |
-| Gateway | gateway-client/gateway-api/gateway-auth/gateway-config/... | 9 |
-| Intelligence | intelligence-backend/intelligence-client/embedding-client/memory-extractor | 4 |
-| Viking | viking-client | 1 |
-| Pipeline | pipeline-client/pipeline-recommender | 2 |
-| Security | crypto-utils/secure-storage/security-audit/security-index/api-key-storage | 5 |
-| 工具 | config-parser/logger/utils/error-types/error-utils/json-utils/... | 10+ |
-| Tauri 集成 | safe-tauri/tauri-gateway | 2 |
-| 工作流 | workflow-builder/ (index + types + yaml-converter) | 3 |
-
-## 模型路由
-
-### 完整链路 (Tauri SaaS Relay 主路径)
-
-```
-前端模型选择
-  │
-  ├─ conversationStore.currentModel (用户上次选择的模型)
-  │     持久化到 IndexedDB，跨会话保留
-  │
-  ├─ connectionStore 连接时获取 SaaS 可用模型
-  │     saasClient.listModels() → [{id: "deepseek-chat"}, {id: "GLM-4.7"}, ...]
-  │     relayModels[0]?.id 作为 fallback
-  │
-  └─ 最终: preferredModel || fallbackId
-        │
-        ▼
-kernelClient.setConfig({ model: modelToUse })
-  │
-  ▼
-kernel_init (Tauri Command)
-  │  KernelConfigRequest { model, api_key, base_url }
-  │  base_url = "https://saas-host/api/v1/relay"
-  │  api_key = SaaS JWT (不是 LLM Key!)
-  │
-  ▼
-Kernel::boot(config)
-  │  config.llm.model = modelToUse
-  │  config.llm.base_url = SaaS relay URL
-  │
-  ▼
-loop_runner → LLM Driver (OpenAI compatible)
-  │  POST {base_url}/chat/completions
-  │  body: { model: modelToUse, messages: [...] }
-  │  header: Authorization: Bearer {SaaS JWT}
-  │
-  ▼
-SaaS Relay Handler (handlers.rs)
-  │  cache.get_model(model_name) → 精确匹配 model_id
-  │  ⚠️ 无别名解析! "glm-4-flash" ≠ "deepseek-chat"
-  │  找不到 → 400 "模型 xxx 不存在或未启用"
-  │
-  ▼
-Key Pool 轮换
-  │  priority ASC → last_used_at ASC → cooldown 检查 → RPM/TPM 滑动窗口
-  │
-  ▼
-真实 LLM API
-  │  429 → mark cooldown → 切换 key
-  │  5xx → exponential backoff
-  │  model_group → 跨 Provider 故障转移
-  │
-  ▼
-响应 → SSE 流式返回 → 前端
-```
-
-### 辅助 LLM 调用 (非聊天主路径)
-
-这些 Rust 端组件也通过同一个 relay 发起 LLM 请求：
-
-| 组件 | 文件 | 模型来源 | 触发时机 |
-|------|------|----------|----------|
-| 记忆摘要 | `summarizer_adapter.rs` | kernel_init 传入的 model | 定期 L0/L1 摘要生成 |
-| 记忆提取 | `extraction_adapter.rs` | kernel_init 传入的 model | 中间件触发提取 |
-| 管家路由 | ButlerRouter via loop_runner | 同聊天模型 | 聊天中间件链 |
-
-**关键**: `summarizer_adapter.rs` 和 `extraction_adapter.rs` 在 `kernel_init` 时配置，
-使用与聊天相同的 `model` 和 `base_url`。未配置时会明确报错，不会静默 fallback 到错误模型。
-
-### SaaS Relay 模型匹配规则
-
-```
-前端发送 model: "deepseek-chat"
-  → SaaS cache 按 model_id 精确匹配
-  → 匹配: cache.models["deepseek-chat"] → 命中
-  → 不匹配: cache.models["glm-4-flash"] → null → 400 错误
-
-⚠️ config.toml 中的 [llm.aliases] 仅用于本地 Kernel，SaaS relay 不解析别名！
-```
-
-### Browser 模式模型路由
-
-```
-createSaaSRelayGatewayClient(saasUrl, getModel)
-  │  getModel() 回调 → conversationStore.currentModel || relayModels[0]?.id
-  │
-  ▼
-chatStream() → saasClient.chatCompletion({ model: getModel() })
-  │  未获取到模型时 → onError 报错，不发请求
-  │
-  ▼
-POST /api/v1/relay/chat/completions → SSE 流
-```
-
-## API 接口
+- `getClient()` 是全局单例，所有 Store 通过 `initializeStores()` 获取共享 client
+- SaaS 不可达时自动降级到本地 Kernel，不需要用户干预
+- SaaS Relay 按 `model_id` 精确匹配，不解析别名 (`config.toml [llm.aliases]` 仅本地 Kernel)
+- Provider Key 解密失败时 warn+skip，不 500 (`key_pool.rs`)
 
 ### Tauri 命令
 
-**Gateway 管理** (`desktop/src-tauri/src/gateway/commands.rs`):
-
-| 命令 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `zclaw_status` | — | `LocalGatewayStatus` | Kernel 运行状态 |
-| `zclaw_start` | — | `LocalGatewayStatus` | 启动 Kernel |
-| `zclaw_stop` | — | `LocalGatewayStatus` | 停止 Kernel |
-| `zclaw_restart` | — | `LocalGatewayStatus` | 重启 Kernel |
-| `zclaw_local_auth` | — | `LocalGatewayAuth` | 获取本地认证 token |
-| `zclaw_prepare_for_tauri` | — | `LocalGatewayPrepareResult` | 更新 Tauri allowed origins |
-| `zclaw_approve_device_pairing` | device_id, public_key_base64, url? | `PairingApprovalResult` | 设备配对审批 |
-| `zclaw_doctor` | — | `String` | 诊断报告 |
-| `zclaw_process_list` | — | `ProcessListResponse` | 进程列表 |
-| `zclaw_process_logs` | pid?, lines? | `ProcessLogsResponse` | 进程日志 |
-| `zclaw_version` | — | `VersionResponse` | 版本信息 |
-
-**健康检查** (`desktop/src-tauri/src/health_check.rs`):
-
-| 命令 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `zclaw_health_check` | port?, timeout_ms? | `HealthCheckResponse` | 完整健康检查 |
-| `zclaw_ping` | — | `bool` | 快速端口检测 |
-
-### SaaS Relay 路由 (`crates/zclaw-saas/src/relay/`)
-
-| 方法 | 路径 | 权限 | 说明 |
-|------|------|------|------|
-| POST | `/api/v1/relay/chat/completions` | 认证+配额 | 主聊天中转 |
-| GET | `/api/v1/relay/models` | 认证 | 可用模型列表 |
-| GET | `/api/v1/relay/tasks` | 认证 | 任务列表 |
-| GET | `/api/v1/relay/tasks/:id` | 认证 | 任务详情 |
-| POST | `/api/v1/relay/tasks/:id/retry` | admin | 重试失败任务 |
-
-### Provider Key 管理 (`crates/zclaw-saas/src/relay/handlers.rs`)
-
-| 方法 | 路径 | 权限 | 说明 |
-|------|------|------|------|
-| GET | `/api/v1/providers/:id/keys` | admin | 列出 Provider Key |
-| POST | `/api/v1/providers/:id/keys` | admin | 添加加密 Key |
-| PUT | `/api/v1/providers/:id/keys/:kid/toggle` | admin | 启停 Key |
-| DELETE | `/api/v1/providers/:id/keys/:kid` | admin | 删除 Key |
-
-## 测试链路
-
-| 功能 | 测试文件 | 测试数 | 覆盖状态 |
-|------|---------|--------|---------|
-| Admin 路由解析 | `tests/desktop/connectionStore.adminRouting.test.ts` | — | ✅ parseAdminRouting() 纯函数 |
-| 连接流程 | `tests/desktop/gatewayStore.test.ts` | — | ✅ connect() + 数据加载 |
-| GatewayClient | `tests/gateway/ws-client.test.ts` | — | ✅ WS 连接/事件/断连 |
-| Mock Server | `tests/fixtures/zclaw-mock-server.ts` | — | ✅ HTTP+WS 模拟 |
-
-## 关联模块
-
-- [[chat]] — 路由决定使用哪种 ChatStream
-- [[saas]] — Token Pool、认证、模型管理
-- [[middleware]] — 请求经过中间件链处理
-- [[butler]] — 管家模式通过 ButlerRouter 中间件介入
-
-## 关键文件
-
-| 文件 | 职责 |
+| 命令 | 说明 |
 |------|------|
-| `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 注入 |
+| `kernel_init` | 初始化 Kernel 配置 (model, apiKey, baseUrl) |
+| `zclaw_start` / `zclaw_stop` / `zclaw_restart` | Kernel 生命周期管理 |
+| `zclaw_health_check` / `zclaw_ping` | 健康检查 + 端口检测 |
+| `zclaw_doctor` | 完整诊断报告 |
 
-## 已知问题
+### SaaS Relay 路由
 
-- ✅ **Tauri invoke 参数名 snake_case vs camelCase** — P1 已修复 (commit f6c5dd2)。Tauri 2.x 默认 `rename_all = "camelCase"`，所有 invoke 调用必须用 camelCase
-- ✅ **Provider Key 解密失败导致 relay 500** — P1 已修复 (commit b69dc61)。`key_pool.rs` 现在 decrypt 失败时 warn+skip 到下一个 key，启动时 `heal_provider_keys()` 自动重新加密有效 key
+| 路径 | 说明 |
+|------|------|
+| `POST /api/v1/relay/chat/completions` | 主聊天中转 (认证+配额) |
+| `GET /api/v1/relay/models` | 可用模型列表 |
+
+## 4. 活跃问题 + 注意事项
+
+| 问题 | 状态 | 说明 |
+|------|------|------|
+| Tauri invoke 参数名 snake_case | ✅ 已修复 (f6c5dd2) | Tauri 2.x 默认 `rename_all="camelCase"`，invoke 必须用 camelCase |
+| Provider Key 解密致 relay 500 | ✅ 已修复 (b69dc61) | decrypt 失败 warn+skip，启动时 `heal_provider_keys()` 自动重新加密 |
+| Tauri 命令孤儿 | ~0 (差异来自内部调用) | 190 定义 / 104 invoke / 97 @reserved |
+
+**注意事项:**
+- `summarizer_adapter.rs` 和 `extraction_adapter.rs` 在 `kernel_init` 时配置，使用与聊天相同的 model+base_url。未配置时明确报错，不静默 fallback
+- Browser 模式 `getModel()` 未获取到模型时 onError 报错，不发请求
+
+## 5. 变更日志
+
+| 日期 | 变更 |
+|------|------|
+| 04-22 | Wiki 重写: 5 节模板，移除 Store/lib 全量列表 |
+| 04-21 | 上一轮更新 |
+| 04-19 | TRUTH.md 数字校准: 190 命令 / 104 invoke / 97 @reserved |
+| 04-16 | Provider Key 解密修复 (b69dc61) |
+| 04-16 | Tauri invoke 参数名修复 (f6c5dd2) |