docs(wiki): 同步知识库 — 04-21 经验积累+Skill工具调用修复

2026-04-21 01:12:51 +08:00
parent c1dea6e07a
commit 2f5e9f1755
10 changed files with 194 additions and 109 deletions
--- a/wiki/butler.md
+++ b/wiki/butler.md
@@ -1,6 +1,6 @@
 ---
 title: 管家模式
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [module, butler, interaction]
 ---
@@ -93,15 +93,26 @@ butler_list_proposals
 butler_update_proposal_status
 ```

-### Intelligence 层文件结构
+### Intelligence 层文件结构 (16 .rs 文件)

 ```
 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)
+├── 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)
+├── experience.rs          经验管理桥接
+├── extraction_adapter.rs  记忆提取适配器
+├── health_snapshot.rs     统一健康快照
+├── mod.rs                 模块入口
+├── pain_storage.rs        痛点持久化
+├── personality_detector.rs 人格检测
+├── solution_generator.rs  方案生成
+├── trajectory_compressor.rs 轨迹压缩
+├── triggers.rs            触发信号管理
+├── user_profiler.rs       用户画像
+└── validation.rs          验证逻辑
 ```

 ## 关联模块
--- a/wiki/chat.md
+++ b/wiki/chat.md
@@ -84,7 +84,7 @@ UI 选择模型 → conversationStore.currentModel = newModel
 - [[routing]] — 路由决定使用哪种 client
 - [[saas]] — Token Pool 提供模型和 API Key
 - [[butler]] — ButlerRouter 中间件增强 system prompt
- [[middleware]] — 消息经过 14 层 runtime 中间件处理
+- [[middleware]] — 消息经过 15 层 runtime 中间件处理
 - [[memory]] — 对话内容可能触发记忆提取

 ## 关键文件
--- a/wiki/development.md
+++ b/wiki/development.md
@@ -1,6 +1,6 @@
 ---
 title: 开发规范
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [development, conventions]
 ---
@@ -25,17 +25,17 @@ tags: [development, conventions]
 |------|------|
 | 新增 SaaS API 端点 | 已有 137 个 .route()，前端未全部接通 |
 | 新增 SKILL.md | 已有 75 个 |
-| 新增 Tauri 命令 | 已有 189 个，部分无前端调用 |
-| 新增中间件 | 已有 14 层 runtime + 10 层 SaaS HTTP |
-| 新增 Store | 已有 17 文件 + chat/4 子store |
+| 新增 Tauri 命令 | 已有 190 个，97 个标注 @reserved |
+| 新增中间件 | 已有 15 层 runtime + 10 层 SaaS HTTP |
+| 新增 Store | 已有 16 根 + chat/4 + saas/5 = 25 |
 | 新增 admin 页面 | 已有 17 页 |

 ## 分层职责

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

 禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过:
--- a/wiki/hands-skills.md
+++ b/wiki/hands-skills.md
@@ -1,6 +1,6 @@
 ---
 title: Hands + Skills + MCP
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [module, hands, skills, mcp]
 ---
@@ -20,7 +20,7 @@ tags: [module, hands, skills, mcp]

 ## 代码逻辑

-### Hands (9 启用)
+### Hands (7 注册: 6 TOML + 1 系统内部)

 每个 Hand 有独立的 `hands/<Name>.HAND.toml` 配置和 `crates/zclaw-hands/src/hands/` 下的 Rust 实现。

@@ -31,13 +31,20 @@ tags: [module, hands, skills, mcp]
 | 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` |
 | _reminder | 定时提醒 (系统内部) | — | — | 无 TOML（代码注册） |

-Hands 测试分布（前 5）: Clip(30), Twitter(25), Researcher(22), Slideshow(13), Browser(8)
+Hands 测试分布（前 5）: Clip(30), Twitter(25), Researcher(22), Browser(8), Collector(8)
+
+### 已删除 Hands (04-17 Phase 5 空壳清理)
+
+| Hand | 原状态 | 删除原因 |
+|------|--------|----------|
+| Whiteboard | 有 HAND.toml + Rust (422行) | 空壳实现，无真实功能，已删除 |
+| Slideshow | 有 HAND.toml + Rust (797行) | 空壳实现，无真实功能，已删除 |
+| Speech | 有 HAND.toml + Rust (442行) | 空壳实现，无真实功能，已删除 |
+
+净减 ~5400 行。

 ### 禁用 Hands

@@ -194,12 +201,12 @@ MCP 工具在 ToolRegistry 中使用限定名 `service_name.tool_name` 避免冲

 | 文件 | 职责 |
 |------|------|
-| `crates/zclaw-hands/src/hands/` | 10 个 Hand 实现 (含 _reminder) |
+| `crates/zclaw-hands/src/hands/` | 7 个 Hand 实现 (6 有 TOML + _reminder 系统内部) |
 | `crates/zclaw-runtime/src/nl_schedule.rs` | 中文时间→cron 解析器 |
 | `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 |
 | `crates/zclaw-skills/src/` | 技能解析和索引 |
 | `skills/*/SKILL.md` | 75 个技能定义 |
-| `hands/*.HAND.toml` | 9 个 Hand 配置 |
+| `hands/*.HAND.toml` | 6 个 Hand 配置 |
 | `crates/zclaw-protocols/src/mcp_tool_adapter.rs` | MCP 工具适配器 + 服务管理 |
 | `crates/zclaw-protocols/src/mcp.rs` | MCP 协议类型 + BasicMcpClient |
 | `crates/zclaw-runtime/src/tool/builtin/mcp_tool.rs` | McpToolWrapper (Tool trait 桥接) |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -1,52 +1,55 @@
 ---
 title: ZCLAW 项目知识库
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 ---

 # ZCLAW 项目知识库

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

 ## 项目画像

 | 维度 | 值 |
 |------|-----|
 | 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
-| 技术栈 | Rust 10 crates + src-tauri (~78K行, 275 .rs文件) + React 19 + TypeScript + PostgreSQL |
+| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs文件) + React 19 + TypeScript + PostgreSQL |
 | 阶段 | 发布前稳定化，功能冻结中 |

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

 | 指标 | 值 | 验证方式 |
 |------|-----|----------|
 | Rust Crates | 10 + src-tauri | `ls crates/zclaw-*/Cargo.toml` |
-| Rust 代码 | 77,811 行 (275 .rs文件) | `find crates/ src-tauri/ -name "*.rs"` |
-| Rust 测试 | 734 (425 #[test] + 309 #[tokio::test]) | `grep '#\[test\]' / '#\[tokio::test\]'` (TRUTH.md 04-18) |
-| Tauri 命令 | 190 定义 (103 src-tauri + 76 crates + 内部) | `grep '#\[tauri::command\]'` (TRUTH.md 04-16) |
-| 前端 invoke 调用 | 104 处 | `grep invoke( desktop/src/` (TRUTH.md 04-16) |
-| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` |
-| SaaS 模块 | 17 个目录 | `ls crates/zclaw-saas/src/*/` |
+| Rust 代码 | 101,967 行 (80,754 crates + 21,213 src-tauri, 357 .rs文件) | `wc -l` (2026-04-19 验证) |
+| Rust 测试 | 987 (640 #[test] + 347 #[tokio::test]) | `grep '#\[test\]'` 含 src-tauri (2026-04-19 验证) |
+| Rust 测试通过 | 797 workspace (sqlx 0.8 升级后) | `cargo test --workspace --exclude zclaw-saas` |
+| Tauri 命令 | 190 定义 | `grep '#\[.*tauri::command'` (2026-04-16 验证) |
+| 前端 invoke 调用 | 104 处 / 91 唯一命令 | `grep invoke( desktop/src/` (2026-04-19 验证) |
+| @reserved 标注 | 97 个 (孤儿命令 ~0) | `grep @reserved src-tauri/` (2026-04-19 验证) |
+| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` (2026-04-16 验证) |
+| SaaS 模块 | 16 个目录 | `ls crates/zclaw-saas/src/*/` (2026-04-19 验证) |
 | SKILL 目录 | 75 个 | `ls -d skills/*/` |
 | HAND 配置 | 6 TOML + 1 系统内部 (_reminder) = 7 注册 | `ls hands/*.HAND.toml` + kernel registry |
-| Pipeline YAML | 18 个 | `find pipelines/ -name "*.yaml"` |
-| Zustand Store | 26 个 (.ts, 含子目录) | `find desktop/src/store/` |
-| React 组件 | 105 个 (.tsx/.ts) | `find desktop/src/components/` (TRUTH.md 04-16) |
-| Admin V2 页面 | 17 个 (.tsx) | `ls admin-v2/src/pages/` |
-| 中间件 | 14 层 runtime + 10 层 SaaS HTTP | `kernel/mod.rs` + `zclaw-saas middleware` |
-| 前端 lib/ | 76 个 .ts (顶层 ~73 + 子目录) | `find desktop/src/lib/` (TRUTH.md 04-16) |
-| SQL 迁移 | 20 文件 / 104 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` |
-| @reserved 标注 | 89 个 (孤儿命令 0) | `grep @reserved desktop/src-tauri/src/` (TRUTH.md 04-16) |
-| Cargo Warnings | 0 (非 SaaS, 仅 sqlx 外部) | `cargo check --workspace --exclude zclaw-saas` |
-| TODO/FIXME | 前端 1 + Rust 3 = 4 | `grep TODO/FIXME` |
+| Pipeline YAML | 18 个 (8 目录) | `find pipelines/ -name "*.yaml"` (2026-04-19 验证) |
+| Zustand Store | 25 个 (.ts, 含子目录 saas/5) | `find desktop/src/store/` (2026-04-19 验证) |
+| React 组件 | 102 个 (.tsx/.ts, 11 子目录) | `find desktop/src/components/` (2026-04-19 验证) |
+| Admin V2 页面 | 17 个 (.tsx) | `ls admin-v2/src/pages/` (2026-04-19 验证) |
+| 中间件 | 15 层 runtime + 10 层 SaaS HTTP | `chain.register` 计数 (2026-04-19 验证) |
+| 前端 lib/ | 75 个 .ts (71 顶层 + workflow-builder/3 + __tests__/1) | `find desktop/src/lib/` (2026-04-19 验证) |
+| SQL 迁移 | 38 文件 (21 up + 17 down) / 42 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` (2026-04-19 验证) |
+| Intelligence | 16 个 .rs 文件 | `ls src-tauri/src/intelligence/` (2026-04-19 验证) |
+| Cargo Warnings | 0 (非 SaaS) | `cargo check --workspace --exclude zclaw-saas` |
+| TODO/FIXME | 前端 1 + Rust 1 = 2 | `grep TODO/FIXME` (2026-04-19 验证) |
+| dead_code | 0 个 | `grep '#\[dead_code\]'` (2026-04-19 验证) |

 ## 模块导航树

 ```
 ZCLAW
-├── [[routing]]        客户端路由 — 4分支决策，SaaS Relay是主路径
+├── [[routing]]        客户端路由 — 5分支+降级，SaaS Relay是主路径
 │   └── [[chat]]       聊天系统 — 3种ChatStream，Store拆为4+1
 │
 ├── [[saas]]           SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
@@ -56,13 +59,13 @@ ZCLAW
 │
 ├── [[butler]]         管家模式 — 默认交互范式，语义路由+冷启动+痛点
 │
-├── [[middleware]]     中间件链 — 14层runtime + 10层SaaS HTTP
+├── [[middleware]]     中间件链 — 15层runtime + 10层SaaS HTTP
 │
-├── [[memory]]         记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
+├── [[memory]]         记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入+进化引擎
 │
-├── [[hands-skills]]   Hands(9) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议
+├── [[hands-skills]]   Hands(7注册) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议
 │
-├── [[pipeline]]       Pipeline DSL — YAML+DAG执行器+17行业模板
+├── [[pipeline]]       Pipeline DSL — YAML+DAG执行器+18模板
 │
 ├── [[development]]    开发规范 — 闭环工作法/验证命令/提交规范
 ├── [[known-issues]]   已知问题 — P0/P1已修复，P2待处理
@@ -80,7 +83,10 @@ ZCLAW
 **Q: 为什么管家模式是默认？**
 → 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。

-**Q: 为什么中间件是14层runtime？**
-→ 按优先级分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 仅在有技能时注册。另有 10 层 SaaS HTTP 中间件 (限流/认证/配额/CORS/日志等)。
+**Q: 为什么中间件是15层runtime？**
+→ 按优先级分6类: 78进化(Evolution) → 80-99路由+脱敏(Butler/DataMasking) → 100-199上下文(Compaction/Memory/Title) → 200-399能力(SkillIndex/DanglingTool/ToolError/ToolOutputGuard) → 400-599安全(Guardrail/LoopGuard/SubagentLimit) → 600-799遥测(TrajectoryRecorder/TokenCalibration)。另有 10 层 SaaS HTTP 中间件 (限流/认证/配额/CORS/日志等)。
+
+**Q: zclaw-growth 的进化引擎做什么？**
+→ EvolutionEngine 负责从对话历史中检测行为模式变化，生成进化候选项（如新技能建议、工作流优化），通过 EvolutionMiddleware@78 注入 system prompt。配合 FeedbackCollector、PatternAggregator、QualityGate、SkillGenerator、WorkflowComposer 形成自我改进闭环。

 > 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准
--- a/wiki/memory.md
+++ b/wiki/memory.md
@@ -1,6 +1,6 @@
 ---
 title: 记忆管道
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [module, memory, growth]
 ---
@@ -99,6 +99,54 @@ SaaS 侧:
  → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred)
 ```

+### 进化引擎 (EvolutionEngine)
+
+zclaw-growth 包含完整的自我改进闭环:
+
+```
+EvolutionEngine (crates/zclaw-growth/src/evolution_engine.rs)
+  → 从对话历史中检测行为模式变化
+  → 生成进化候选项 (新技能建议/工作流优化)
+  → EvolutionMiddleware@78 注入 system prompt
+
+配套组件:
+  → FeedbackCollector    — 收集用户反馈信号
+  → PatternAggregator   — 行为模式聚合
+  → QualityGate         — 进化质量门控
+  → SkillGenerator      — 自动技能生成
+  → WorkflowComposer     — 工作流自动编排
+  → ProfileUpdater      — 用户画像更新
+  → ExperienceExtractor  — 经验提取器
+  → Summarizer          — 记忆摘要
+```
+
+zclaw-growth 模块结构 (19 文件):
+```
+crates/zclaw-growth/src/
+├── evolution_engine.rs      进化引擎核心
+├── experience_extractor.rs  经验提取
+├── experience_store.rs      经验 CRUD
+├── extractor.rs             记忆提取
+├── feedback_collector.rs    反馈收集
+├── injector.rs              Prompt 注入
+├── json_utils.rs            JSON 工具
+├── pattern_aggregator.rs    模式聚合
+├── profile_updater.rs       画像更新
+├── quality_gate.rs          质量门控
+├── retriever.rs             语义检索
+├── skill_generator.rs       技能生成
+├── summarizer.rs            摘要生成
+├── tracker.rs               追踪器
+├── types.rs                 类型定义
+├── viking_adapter.rs        Viking 适配器
+├── workflow_composer.rs     工作流编排
+├── retrieval/               检索子模块
+│   ├── query.rs             意图分类 + CJK
+│   └── semantic.rs          EmbeddingClient
+└── storage/                 存储子模块
+    └── sqlite.rs            FTS5 + TF-IDF
+```
+
 ### 前端 Tauri 命令

 Memory 相关命令 (13 个，来自 `memory_commands.rs` + `memory/`):
--- a/wiki/pipeline.md
+++ b/wiki/pipeline.md
@@ -15,7 +15,7 @@ tags: [module, pipeline, dsl]

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

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

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

 ```
 pipelines/
@@ -67,6 +67,8 @@ pipelines/
 │   └── meeting-summary.yaml
 └── research/           (1 模板)
    └── literature-review.yaml
+
+注: 共 18 个 YAML, 总数 = 2+4+4+3+1+1+1+1+1 = 18
 ```

 ### 前端集成
@@ -104,6 +106,6 @@ Pipeline Tauri 命令 (12 个):
 |------|------|
 | `crates/zclaw-pipeline/src/executor.rs` | DAG 执行器 |
 | `crates/zclaw-pipeline/src/parser_v2.rs` | YAML 解析 (11 tests) |
-| `pipelines/` | 17 个 YAML 模板 (8 目录) |
+| `pipelines/` | 18 个 YAML 模板 (8 目录) |
 | `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 |
 | `desktop/src-tauri/src/pipeline_commands/` | 12 个 Tauri 命令 (4 文件) |
--- a/wiki/routing.md
+++ b/wiki/routing.md
@@ -1,6 +1,6 @@
 ---
 title: 客户端路由
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [module, routing, connection]
 ---
@@ -21,29 +21,31 @@ tags: [module, routing, connection]

 ## 代码逻辑

-### 4 分支决策树
+### 5 分支 + 降级决策树

-入口: `connectionStore.ts:349` → `connect(url?, token?)`
+入口: `connectionStore.ts` → `connect(url?, token?)`

 ```
 connect()
  │
-  ├── [1] Admin 强制路由: localStorage llm_routing
-  │     ├── "relay" → 强制 SaaS Relay 模式
-  │     └── "local" → 强制本地 Kernel (adminForceLocal=true)
+  ├── [1] Admin 强制本地: adminRouting === 'local' && isTauri()
+  │     → 直接走 Kernel 模式，跳过 SaaS
  │
-  ├── [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
+  ├── [2] SaaS Relay (Tauri 路径): savedMode === 'saas' && isTauri()
+  │     → KernelClient + baseUrl = saasUrl/api/v1/relay
+  │     → apiKey = SaaS JWT (不是 LLM Key!)
+  │     → SaaS 不可达 → 降级到本地 Kernel
  │
-  ├── [3] 本地 Kernel: isTauriRuntime() === true
-  │     KernelClient + 用户自定义模型配置
-  │     用户需要自己的 API Key
+  ├── [3] SaaS Relay (Browser 路径): savedMode === 'saas' && !isTauri()
+  │     → SaaSRelayGatewayClient (SSE)
+  │     → SaaS 不可达 → 降级到本地 Kernel
  │
-  └── [4] External Gateway (fallback)
-        GatewayClient via WebSocket/REST
+  ├── [4] 本地 Kernel: isTauriRuntime() && 非 SaaS 模式
+  │     → KernelClient + 用户自定义模型配置
+  │     → 用户需要自己的 API Key
+  │
+  └── [5] External Gateway (fallback): !isTauri()
+        → GatewayClient via WebSocket/REST
 ```

 ### SaaS Relay 主路径 (Tauri 桌面端)
@@ -86,7 +88,7 @@ listModels() 失败
 `getClient()` 定义: `connectionStore.ts:844`
 所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。

-### Store 层 (17 文件 + chat/4 = 21)
+### Store 层 (16 根文件 + chat/4 + saas/5 = 25)

 ```
 desktop/src/store/
@@ -98,34 +100,43 @@ desktop/src/store/
 ├── configStore.ts        配置读写
 ├── connectionStore.ts    路由决策核心
 ├── handStore.ts          Hand 状态管理
-├── industryStore.ts      行业配置 (V13 新增，已接通 ButlerPanel)
+├── industryStore.ts      行业配置 (已接通 ButlerPanel)
 ├── memoryGraphStore.ts   记忆图谱
 ├── offlineStore.ts       离线队列
-├── saasStore.ts          SaaS 认证
+├── saasStore.ts          SaaS 认证 (re-export barrel)
 ├── securityStore.ts      安全状态
 ├── sessionStore.ts       会话管理
 ├── uiModeStore.ts        双模式 UI
-├── workflowBuilderStore.ts  工作流构建器
 ├── workflowStore.ts      工作流状态
-└── chat/
-    ├── artifactStore.ts  聊天产物
-    ├── conversationStore.ts  会话管理
-    ├── messageStore.ts   消息持久化
-    └── streamStore.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/ 工具层 (76 个文件)
+### lib/ 工具层 (75 个 .ts 文件)

 关键分类:

 | 类别 | 文件 | 数量 |
 |------|------|------|
-| Kernel 通信 | kernel-chat/kernel-client/kernel-agent/... | 7 |
-| SaaS 通信 | saas-client/saas-auth/saas-billing/saas-relay/... | 12 |
-| Gateway | gateway-client/gateway-api/gateway-auth/... | 6 |
-| Intelligence | intelligence-backend/intelligence-client | 2 |
-| 工具 | config-parser/crypto-utils/logger/utils | 10+ |
-| Tauri 集成 | safe-tauri/tauri-gateway/secure-storage | 3 |
+| 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 |

 ## 模型路由

--- a/wiki/saas.md
+++ b/wiki/saas.md
@@ -1,6 +1,6 @@
 ---
 title: SaaS 平台
-updated: 2026-04-17
+updated: 2026-04-19
 status: active
 tags: [module, saas, auth, billing]
 ---
@@ -85,11 +85,9 @@ knowledge/  migration/  model_config/  models/  prompt/
 relay/  role/  scheduled_task/  tasks/  telemetry/  workers/
 ```

-实际 `ls` 显示 17 个目录（含上述 16 + distill_knowledge 等 workers 子模块）。
-
 ### SaaS API 分布

-137 个 `.route()` 调用，13 个路由模块 (main.rs `.merge()` 注册):
+137 个 `.route()` 调用，13 个路由模块 (main.rs `.merge()` 注册)。

 | 模块 | 路由注册 | 说明 |
 |------|----------|------|
@@ -107,9 +105,9 @@ relay/  role/  scheduled_task/  tasks/  telemetry/  workers/
 | industry | industry/ | 行业配置管理 (V13 新增) |
 | migration | migration/ | Schema 迁移 |

-### 数据表 (104 CREATE TABLE)
+### 数据表 (42 CREATE TABLE)

-20 个 SQL 迁移文件，104 个 `CREATE TABLE` 语句（含临时表、索引表等）。
+38 个 SQL 迁移文件 (21 up + 17 down)，42 个 `CREATE TABLE` 语句。

 核心表: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version, user_profiles, trajectory_records, industries, account_industries

@@ -141,7 +139,7 @@ relay/  role/  scheduled_task/  tasks/  telemetry/  workers/
 | `crates/zclaw-saas/src/billing/` | 计费 |
 | `crates/zclaw-saas/src/knowledge/` | 知识库 |
 | `crates/zclaw-saas/src/workers/` | 7 个后台 Worker |
-| `crates/zclaw-saas/migrations/` | SQL 迁移 (20 文件) |
+| `crates/zclaw-saas/migrations/` | SQL 迁移 (38 文件) |
 | `admin-v2/src/pages/` | 17 页管理后台（含 Dashboard/Accounts/Billing/Industries/Knowledge/Prompts/Roles/ScheduledTasks/Config 等） |
 | `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 |
 | `desktop/src/store/saasStore.ts` | SaaS 认证状态 |