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/butler.md

@@ -7,208 +7,144 @@ tags: [module, butler, interaction]
 
 # 管家模式 (Butler Mode)
 
-> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[memory]]
+> 从 [[index]] 导航。关联: [[chat]] [[middleware]] [[memory]] [[hands-skills]]
 
-## 设计思想
+## 1. 设计决策
 
 **核心问题: 非技术用户（如医院行政）不会写 prompt，需要 AI 主动引导。**
 
-设计决策:
-1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启
-2. **语义路由** — SemanticSkillRouter 用 TF-IDF 匹配 75 个技能，替代简单关键词
-3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议
-4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁
+| 决策 | WHY |
+|------|-----|
+| 默认激活 | 所有聊天都经过 ButlerRouter，无需用户手动开启。降低使用门槛到零 |
+| 语义路由 + 痛点积累 | SemanticSkillRouter 用 TF-IDF 匹配 75 个技能（详见 [[hands-skills]]），从对话中提取痛点并积累后生成方案建议 |
+| 双模式 UI | simple(纯聊天) / professional(完整功能)，渐进式解锁。简洁模式隐藏高级功能降低认知负担 |
+| ButlerRouter@80 中间件 | 在 Evolution@78 之后、Memory@150 之前执行。先路由增强 prompt，再检索记忆注入，最后技能索引 |
+| XML fencing `<butler-context>` | 结构化注入 system prompt，避免与用户消息混淆。LLM 可区分管家上下文和用户输入 |
+| 冷启动 4 阶段 hook | idle -> greeting_sent -> waiting_response -> completed，自动检测新用户并发送欢迎引导 |
+| 4 内置行业 + 自定义关键词 | 医疗/教育/制衣/电商开箱即用，ButlerRouter 动态行业关键词注入支持扩展 |
 
-## 代码逻辑
+## 2. 关键文件 + 数据流
 
-### 数据流
-
-```
-用户消息
-  → ButlerRouter 中间件 (middleware/butler_router.rs)
-    → 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 持久层)
-    → 全局 PAIN_STORAGE 单例
-  → SolutionGenerator
-    → 基于痛点生成解决方案提案
-```
-
-### 语义路由桥接（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`（lib/ 下有同名文件）
-
-```
-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 区: 洞察/方案/记忆 + 行业专长卡片)
-
-### 管家Tab记忆展示（2026-04-22 增强）
-
-> ButlerPanel 的 MemorySection 组件负责向用户展示管家了解的信息。
-
-```
-ButlerPanel (index.tsx)
-  ├── InsightsSection        — 痛点洞察
-  ├── ProposalsSection       — 方案建议
-  ├── MemorySection           — 记忆 + 用户画像 (增强后)
-  │   ├── 用户画像卡片        — agent_get → UserProfileStore (data.db)
-  │   │   ├── 行业/角色/沟通风格    (profile_store.update_field)
-  │   │   ├── 近期话题标签          (profile_store.add_recent_topic, 上限10)
-  │   │   └── 常用工具标签          (profile_store.add_preferred_tool, 上限10)
-  │   └── 记忆分组列表        — viking_ls + viking_read(L1) (memories.db)
-  │       ├── 偏好 (preferences)   — 默认展开
-  │       ├── 知识 (knowledge)     — 默认展开
-  │       ├── 经验 (experience)    — 折叠
-  │       └── 会话 (sessions)      — 折叠
-  └── 行业专长卡片           — industryStore
-
-数据源:
-  记忆列表: listVikingResources("agent://{agent_id}/") → viking_ls
-  记忆摘要: readVikingResource(uri, "L1") → viking_read → L1 摘要 (并行加载)
-  用户画像: agent_get(agentId) → kernel.memory() → UserProfileStore.get() → data.db
-
-关键文件:
-  desktop/src/components/ButlerPanel/MemorySection.tsx   记忆+画像展示组件
-  desktop/src/components/ButlerPanel/index.tsx           管家面板主组件
-  desktop/src/lib/viking-client.ts                      viking_ls/viking_read 客户端
-  desktop/src/lib/kernel-types.ts                       AgentInfo.userProfile 类型
-```
-
-### 行业配置 (V13 已接通)
-
-- `desktop/src/store/industryStore.ts` — 行业配置 Zustand Store (persist, 离线缓存)
-- ButlerPanel 展示行业专长卡片 + 自动拉取行业配置
-- SaaS API: `industry/list` / `industry/fullConfig` / `industry/accountIndustries`
-- 4 内置行业: 医疗/教育/制衣/电商 (keywords/prompt/pain_seed_categories)
-- ButlerRouter 动态行业关键词注入 (Arc<RwLock<Vec<IndustryKeywordConfig>>>)
-
-### 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 层文件结构 (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)
-├── 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          验证逻辑
-```
-
-## 功能清单
-
-| 功能 | 描述 | 入口文件 | 状态 |
-|------|------|----------|------|
-| 语义路由 | TF-IDF 匹配 75 技能关键词 | butler_router.rs | ✅ |
-| 管家主动引导 | 冷启动 4 阶段 + 追问 | use-cold-start.ts | ✅ |
-| 痛点积累 | 对话中提取痛点 → 方案建议 | pain_storage.rs | ✅ |
-| 双模式 UI | simple/professional 渐进式 | uiModeStore.ts | ✅ |
-| 行业配置 | 4 内置行业 + 自定义 | industryStore.ts | ✅ |
-| 跨会话连续 | 痛点回访 + 经验检索 | butlerStore.ts | ✅ |
-| ButlerContext 注入 | XML fencing 增强系统提示 | ButlerRouter@80 | ✅ |
-| 个性化检测 | personality_detector 自动分类 | personality_detector.rs | ✅ |
-| 方案生成 | 痛点 → 解决方案建议 | solution_generator.rs | ✅ |
-
-## 测试链路
-
-| 功能 | 测试文件 | 测试数 | 覆盖状态 |
-|------|---------|--------|---------|
-| 管家路由 | intelligence/butler_router.rs (middleware/) | 12 | ✅ |
-| 冷启动 | intelligence/cold_start_prompt.rs | 7 | ✅ |
-| 痛点聚合 | intelligence/pain_aggregator.rs | 9 | ✅ |
-| 痛点存储 | intelligence/pain_storage.rs | 11 | ✅ |
-| 方案生成 | intelligence/solution_generator.rs | 5 | ✅ |
-| 个性化 | intelligence/personality_detector.rs | 8 | ✅ |
-| 触发信号 | intelligence/triggers.rs | 7 | ✅ |
-| 用户画像 | intelligence/user_profiler.rs | 9 | ✅ |
-| 经验 | intelligence/experience.rs | 9 | ✅ |
-| 身份 | intelligence/identity.rs | 5 | ✅ |
-| 反思 | intelligence/reflection.rs | 4 | ✅ |
-| 压缩 | intelligence/trajectory_compressor.rs | 11 | ✅ |
-| 验证 | intelligence/validation.rs | 5 | ✅ |
-| 提取适配 | intelligence/extraction_adapter.rs | 3 | ✅ |
-| **合计** | 15 文件 | **99** | |
-
-## 关联模块
-
-- [[middleware]] — ButlerRouter 是中间件链中的第一层
-- [[chat]] — 消息流经过管家路由增强
-- [[memory]] — 痛点存储在 memory 子系统
-- [[hands-skills]] — 语义路由使用 75 个技能的 TF-IDF
-
-## 关键文件
+### 核心文件
 
 | 文件 | 职责 |
 |------|------|
 | `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` | 方案生成 |
+| `crates/zclaw-kernel/src/kernel/mod.rs:196-231` | SemanticRouterAdapter 桥接 (kernel -> skills) |
+| `desktop/src-tauri/src/intelligence/pain_storage.rs` | 痛点双写 (内存 Vec + SQLite) |
+| `desktop/src-tauri/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/index.tsx` | 管家面板主组件 (洞察/方案/记忆/行业) |
-| `desktop/src/components/ButlerPanel/MemorySection.tsx` | 记忆展示+用户画像卡片 (viking_read L1 + agent_get) |
-| `desktop/src/components/ButlerPanel/InsightsSection.tsx` | 痛点洞察列表 |
-| `desktop/src/components/ButlerPanel/ProposalsSection.tsx` | 方案建议列表 |
+| `desktop/src/store/industryStore.ts` | 行业配置 (persist, 离线缓存) |
+| `desktop/src/components/ButlerPanel/index.tsx` | 管家面板 (洞察/方案/记忆/行业) |
+| `desktop/src/components/ButlerPanel/MemorySection.tsx` | 记忆展示 + 用户画像卡片 |
 
-## 已知问题
+### ButlerRouter 数据流
 
-- ✅ **行业 API 字段名不一致** — BUG-L1 已修复。`pain_seeds` vs `pain_seed_categories`
-- ✅ **industryStore 无组件导入** — V13-GAP-02 已修复 (已连接 ButlerPanel)
-- ✅ **行业选择 500** — 类型不匹配已修复
-- ✅ **桌面端未接入 Knowledge Search** — V13-GAP-03 已修复 (saas-knowledge mixin)
-- ⚠️ **SkillIndex 条件注册** — 无技能时中间件不注册，长期观察
+```
+用户消息
+  -> ButlerRouter@80 (middleware/butler_router.rs)
+    -> SemanticRouterAdapter -> SemanticSkillRouter (TF-IDF)
+      -> 返回 RoutingHint { category, confidence, skill_id }
+    -> 增强 system prompt (匹配技能上下文 + <butler-context> XML fencing)
+  -> LLM 响应
+  -> PainAggregator 提取痛点 -> PainStorage (内存+SQLite)
+  -> SolutionGenerator 基于痛点生成方案
+```
+
+### 集成契约
+
+| 方向 | 模块 | 接口 / 触发点 |
+|------|------|---------------|
+| Registered as | middleware: ButlerRouter@80 | `kernel/mod.rs:create_middleware_chain()` |
+| Calls -> | hands-skills: SemanticSkillRouter | TF-IDF 技能路由，返回 RoutingHint |
+| Calls -> | memory: ExperienceStore, UserProfileStore | 痛点/经验检索，pre_hook 注入活跃痛点 |
+| Called by <- | middleware chain | Every chat request |
+
+### Intelligence 层 (16 .rs 文件)
+
+`desktop/src-tauri/src/intelligence/` 包含: compactor(5 cmd), heartbeat(10 cmd), identity(16 cmd), pain_aggregator(5 cmd), reflection(7 cmd), experience, extraction_adapter, health_snapshot, pain_storage, personality_detector, solution_generator, trajectory_compressor, triggers, user_profiler, validation。
+
+管家相关 Tauri 命令 (5 个, @reserved): `butler_list_pain_points`, `butler_record_pain_point`, `butler_generate_solution`, `butler_list_proposals`, `butler_update_proposal_status`。
+
+## 3. 代码逻辑
+
+### 语义关键词匹配
+
+ButlerRouter 维护行业关键词配置 (`Arc<RwLock<Vec<IndustryKeywordConfig>>>`)：
+- 4 内置行业: 医疗/教育/制衣/电商，各有 keywords/prompt/pain_seed_categories
+- 动态注入: SaaS `industry/fullConfig` 端点拉取自定义行业
+- 匹配流程: message -> 关键词命中 -> 识别行业 -> 注入行业 prompt 增强
+
+### XML fencing 注入格式
+
+```
+<butler-context>
+  <active-pain-points>...</active-pain-points>
+  <related-experience>...</related-experience>
+  <industry>医疗</industry>
+  <routing-hint confidence="0.85">data-analysis</routing-hint>
+</butler-context>
+```
+
+### 跨会话连续性 (pre_hook)
+
+新会话开始时，ButlerRouter 的 pre_hook 注入：
+1. 活跃痛点: 从 PainStorage 加载未解决痛点
+2. 相关经验: 通过 ExperienceStore FTS5 检索
+3. 用户画像: UserProfileStore (data.db) 提供行业/角色/偏好
+4. 记忆展示: ButlerPanel -> MemorySection -> viking_ls + viking_read(L1) (详见 [[memory]])
+
+### 冷启动 4 阶段
+
+```
+idle -> (检测新用户) -> greeting_sent -> waiting_response -> completed
+```
+
+自动检测 -> 发送欢迎消息 -> 等待响应 -> 完成引导。入口: `use-cold-start.ts`。
+
+### 不变量
+
+- ButlerRouter@80 在所有能力类中间件之前执行，确保 routing hint 可被后续中间件利用
+- PainStorage 双写: 内存 Vec 热缓存 + SQLite 持久层，通过全局 PAIN_STORAGE 单例
+- UI 双模式: simple(默认) 隐藏高级功能，professional 完整面板。切换: `uiModeStore.ts`
+
+## 4. 活跃问题 + 陷阱
+
+### 活跃
+
+| 问题 | 状态 | 说明 |
+|------|------|------|
+| SkillIndex 条件注册 | 长期观察 | 无技能时中间件不注册，需关注空技能场景一致性 |
+
+### 历史 (已修复)
+
+| 问题 | 修复 |
+|------|------|
+| 行业 API 字段名不一致 (pain_seeds vs pain_seed_categories) | BUG-L1 已修复 |
+| industryStore 无组件导入 | V13-GAP-02 已修复，ButlerPanel 已连接 |
+| 行业选择 500 | 类型不匹配已修复 |
+| 桌面端未接入 Knowledge Search | V13-GAP-03 已修复 |
+| DataMasking 中间件过度匹配 | 04-22 移除整个中间件 |
+
+## 5. 变更日志
+
+| 日期 | 变更 | 关联 |
+|------|------|------|
+| 2026-04-22 | Wiki 5-section 重构: 215->~190 行，移除重复内容引用 [[memory]]/[[hands-skills]] | wiki/ |
+| 2026-04-22 | 跨会话记忆断裂修复: profile_store 连接 + 双数据库统一 | commit adf0251 |
+| 2026-04-17 | E2E 全系统验证 129 链路: 7 项 Bug 修复含行业字段/记忆去重 | 79.1% 通过率 |
+| 2026-04-12 | 行业配置+管家主动性全栈: 4内置行业+动态关键词+跨会话连续性+XML fencing | 全栈 5 Phase |
+| 2026-04-09 | 管家模式 6 交付物完成: ButlerRouter+冷启动+简洁UI+桥测试+文档 | 43 tests PASS |
+
+### 测试概览
+
+| 功能 | 测试文件 | 测试数 |
+|------|---------|--------|
+| 管家路由 | intelligence/butler_router.rs | 12 |
+| 冷启动 | cold_start_prompt.rs | 7 |
+| 痛点聚合+存储 | pain_aggregator + pain_storage | 20 |
+| 方案生成 | solution_generator.rs | 5 |
+| 个性化 | personality_detector.rs | 8 |
+| 其他 (触发/画像/经验/身份/反思/压缩/验证/提取) | 8 文件 | 47 |
+| **合计** | **15 文件** | **99** |