---
title: 管家模式
updated: 2026-04-22
status: active
tags: [module, butler, interaction]
---

# 管家模式 (Butler Mode)

> 从 [[index]] 导航。关联: [[chat]] [[middleware]] [[memory]] [[hands-skills]]

## 1. 设计决策

**核心问题: 非技术用户（如医院行政）不会写 prompt，需要 AI 主动引导。**

| 决策 | 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. 关键文件 + 数据流

### 核心文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 + ButlerRouterBackend trait |
| `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/store/industryStore.ts` | 行业配置 (persist, 离线缓存) |
| `desktop/src/components/ButlerPanel/index.tsx` | 管家面板 (洞察/方案/记忆/行业) |
| `desktop/src/components/ButlerPanel/MemorySection.tsx` | 记忆展示 + 用户画像卡片 |

### ButlerRouter 数据流

```
用户消息
  -> 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** |