--- title: 管家模式 updated: 2026-04-22 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 } impl ButlerRouterBackend for SemanticRouterAdapter { async fn classify(&self, query: &str) -> Option { ... } } ``` 这是 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>>) ### 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/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` | 方案建议列表 | ## 已知问题 - ✅ **行业 API 字段名不一致** — BUG-L1 已修复。`pain_seeds` vs `pain_seed_categories` - ✅ **industryStore 无组件导入** — V13-GAP-02 已修复 (已连接 ButlerPanel) - ✅ **行业选择 500** — 类型不匹配已修复 - ✅ **桌面端未接入 Knowledge Search** — V13-GAP-03 已修复 (saas-knowledge mixin) - ⚠️ **SkillIndex 条件注册** — 无技能时中间件不注册，长期观察