zclaw_openfang/wiki/butler.md

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

# 管家模式 (Butler Mode)

> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[memory]]

## 设计思想

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

设计决策:
1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启
2. **语义路由** — SemanticSkillRouter 用 TF-IDF 匹配 75 个技能，替代简单关键词
3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议
4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁

## 代码逻辑

### 数据流

```
用户消息
  → 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 区: 洞察/方案/记忆 + 行业专长卡片)

### 行业配置 (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` | 方案生成 |
| `desktop/src/hooks/use-cold-start.ts` | 冷启动 4 阶段 |
| `desktop/src/store/uiModeStore.ts` | 双模式切换 |
| `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 |
| `desktop/src/components/ButlerPanel.tsx` | 管家面板 (洞察/方案/记忆) |

## 已知问题

- ✅ **行业 API 字段名不一致** — BUG-L1 已修复。`pain_seeds` vs `pain_seed_categories`
- ✅ **industryStore 无组件导入** — V13-GAP-02 已修复 (已连接 ButlerPanel)
- ✅ **行业选择 500** — 类型不匹配已修复
- ✅ **桌面端未接入 Knowledge Search** — V13-GAP-03 已修复 (saas-knowledge mixin)
- ⚠️ **SkillIndex 条件注册** — 无技能时中间件不注册，长期观察