zclaw_openfang/wiki/butler.md

title, updated, status, tags

title	updated	status	tags
管家模式	2026-04-21	active	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 层）

// 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>>)

Tauri 命令

5 个 butler 命令 (已标注 @reserved):

// 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 条件注册 — 无技能时中间件不注册，长期观察