27b98cae6f
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
关键数字修正: - Rust 77K行(274 .rs)、Tauri 189命令、SaaS 137 routes - Admin V2 17页、SaaS 16模块(含industry)、@reserved 22 - SQL 20迁移/42表、TODO/FIXME 4个、dead_code 16 内容更新: - known-issues: V13-GAP 全部标记已修复 + 三端联调测试结果 - middleware: 14层 runtime + 10层 SaaS HTTP 完整清单 - saas: industry模块、路由模块13个、数据表42个 - routing: Store含industryStore、21个Store文件 - butler: 行业配置接入ButlerPanel、4内置行业 - log: 三端联调+V13修复记录追加
127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
---
|
||
title: 管家模式
|
||
updated: 2026-04-14
|
||
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_seeds)
|
||
- 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 层文件结构
|
||
|
||
```
|
||
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)
|
||
```
|
||
|
||
## 关联模块
|
||
|
||
- [[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` | 管家面板 (洞察/方案/记忆) |
|