Files

iven c10e50d58e docs(wiki): Phase D完成 — 6模块页重构(routing/chat/butler/hands-skills/pipeline/data-model)

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

2026-04-22 21:53:17 +08:00

6.7 KiB

Raw Blame History

title, updated, status, tags

title

updated

status

管家模式 (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 注入：

活跃痛点: 从 PainStorage 加载未解决痛点
相关经验: 通过 ExperienceStore FTS5 检索
用户画像: UserProfileStore (data.db) 提供行业/角色/偏好
记忆展示: 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

6.7 KiB Raw Blame History Unescape Escape