c10e50d58e
- 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>
151 lines
6.7 KiB
Markdown
151 lines
6.7 KiB
Markdown
---
|
||
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** |
|