From 14f2f497b65c354809cdbf293bea3d7a02b91a86 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 22 Apr 2026 19:13:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E8=AE=B0=E5=BD=95=E8=B7=A8?= =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E8=AE=B0=E5=BF=86=E9=93=BE=E8=B7=AF=20+=20?= =?UTF-8?q?=E7=AE=A1=E5=AE=B6Tab=E8=AE=B0=E5=BF=86=E5=B1=95=E7=A4=BA?= =?UTF-8?q?=E6=9E=B6=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - memory.md: 添加"跨会话记忆完整链路"章节，覆盖初始化/写入/读取/展示/数据库架构/关键文件地图 - butler.md: 添加"管家Tab记忆展示"章节，记录MemorySection数据源和组件结构 --- wiki/butler.md | 39 ++++++++++++++++++++++-- wiki/memory.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 116 insertions(+), 3 deletions(-) diff --git a/wiki/butler.md b/wiki/butler.md index 7864a48..7918f08 100644 --- a/wiki/butler.md +++ b/wiki/butler.md @@ -1,6 +1,6 @@ --- title: 管家模式 -updated: 2026-04-21 +updated: 2026-04-22 status: active tags: [module, butler, interaction] --- @@ -72,6 +72,38 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed 简洁侧边栏: `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, 离线缓存) @@ -168,7 +200,10 @@ desktop/src-tauri/src/intelligence/ | `desktop/src/hooks/use-cold-start.ts` | 冷启动 4 阶段 | | `desktop/src/store/uiModeStore.ts` | 双模式切换 | | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 | -| `desktop/src/components/ButlerPanel.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` | 方案建议列表 | ## 已知问题 diff --git a/wiki/memory.md b/wiki/memory.md index 647d550..b073d2c 100644 --- a/wiki/memory.md +++ b/wiki/memory.md @@ -1,6 +1,6 @@ --- title: 记忆管道 -updated: 2026-04-21 +updated: 2026-04-22 status: active tags: [module, memory, growth] --- @@ -66,6 +66,84 @@ tags: [module, memory, growth] → 插入到 system prompt 中 ``` +### 跨会话记忆完整链路（2026-04-22 验证通过） + +> **重要：修改任何环节前请先阅读此链路，避免引入断裂。** + +``` +[初始化] kernel_init (desktop/src-tauri/src/kernel_commands/lifecycle.rs) + ① viking_commands::init_storage() → 初始化 SqliteStorage → memories.db + ② Kernel::boot(config) → 创建 MemoryStore (data.db) + in-memory VikingAdapter + ③ viking_commands::get_storage() → SqliteStorage 包装为 VikingAdapter → kernel.set_viking() + ↑ 此时 GrowthIntegration 缓存被清除 + ④ TauriExtractionDriver::new(driver, model) → kernel.set_extraction_driver() + ↑ GrowthIntegration 缓存再次清除 + ⑤ [首次聊天时] create_middleware_chain() 重建 GrowthIntegration: + - GrowthIntegration::new(self.viking.clone()) ← 持久化 SqliteStorage + - .with_llm_driver(extraction_driver) ← LLM 提取能力 + - .with_profile_store(UserProfileStore::new(memory.pool())) ← data.db 画像持久化 + - .configure_embedding(embedding_client) ← 语义检索（可选） + → 缓存到 kernel.growth (Mutex>) + → MemoryMiddleware::new(growth) 注册到中间件链 (priority=150) + +[写入] after_completion — 记忆提取 (crates/zclaw-runtime/src/middleware/memory.rs) + MemoryMiddleware.after_completion(ctx) + → 30秒去重: should_extract(agent_id) — 同一 agent 30秒内跳过 + → growth.extract_combined(agent_id, messages, session_id) + → MemoryExtractor.extract_combined() (crates/zclaw-growth/src/extractor.rs) + → LLM 单次调用 (COMBINED_EXTRACTION_PROMPT + 对话文本) + → 返回 CombinedExtraction { memories, experiences, profile_signals } + → extractor.store_memories(agent_id, memories) + → VikingAdapter → SqliteStorage.store() → memories.db (FTS5 索引) + → experience_extractor.persist_experiences(agent_id, combined) + → agent://{agent_id}/experience/... URI + → profile_updater.collect_updates(combined) + → UserProfileStore.update_field/add_recent_topic/add_pain_point/add_preferred_tool + → 写入 data.db.user_profiles 表 (user_id = agent_id) + +[读取] before_completion — 记忆检索+注入 (每个新请求) + MemoryMiddleware.before_completion(ctx) + → growth.enhance_prompt(agent_id, system_prompt, user_input) + → retriever.retrieve(agent_id, user_input) + → 按 agent_id 构建搜索范围: agent://{agent_id}/{type} + → QueryAnalyzer 意图分析 + IdentityRecall 43+ 模式匹配 + → FTS5 全文搜索 + TF-IDF 评分 + 语义重排序 + → 弱身份 fallback: <3 结果 + weak_identity → 补充 broad retrieval + → injector.inject_with_format(system_prompt, memories) + → 按 token 预算注入结构化上下文 + +[展示] 管家Tab — 前端读取 (desktop/src/components/ButlerPanel/) + MemorySection.tsx: + → listVikingResources("agent://{agent_id}/") → viking_ls → memories.db + → readVikingResource(uri, "L1") → viking_read → L1 摘要 + → 按类型分组: 偏好/知识/经验/会话 + → agent_get(agentId) → kernel.memory() → UserProfileStore.get() → data.db + → 用户画像卡片: 行业/角色/沟通风格/近期话题/常用工具 + +[数据库架构] + memories.db (SqliteStorage, viking_commands 管理) + → memories 表: URI + memory_type + content + FTS5 索引 + → memories_fts 虚拟表: FTS5 trigram tokenizer (CJK 支持) + data.db (MemoryStore, kernel 管理) + → user_profiles 表: user_id + industry + role + recent_topics(JSON) + ... + → agents 表: agent 配置 + → sessions 表: 会话数据 + +[关键文件地图] + crates/zclaw-kernel/src/kernel/mod.rs create_middleware_chain() + memory() + crates/zclaw-runtime/src/middleware/memory.rs MemoryMiddleware before/after + crates/zclaw-runtime/src/growth.rs GrowthIntegration 闭环编排 + crates/zclaw-growth/src/extractor.rs extract_combined() LLM 提取 + crates/zclaw-growth/src/retriever.rs retrieve() FTS5+TF-IDF 检索 + crates/zclaw-growth/src/injector.rs inject_with_format() prompt 注入 + crates/zclaw-growth/src/storage/sqlite.rs SqliteStorage (memories.db) + crates/zclaw-memory/src/user_profile_store.rs UserProfileStore (data.db) + desktop/src-tauri/src/viking_commands.rs viking_ls/viking_read Tauri 命令 + desktop/src-tauri/src/kernel_commands/agent.rs agent_get (读取 UserProfile) + desktop/src-tauri/src/kernel_commands/lifecycle.rs kernel_init (初始化链路) + desktop/src/components/ButlerPanel/MemorySection.tsx 前端展示 +``` + ### 经验存储 (ExperienceStore) Hermes 管线 Chunk1 新增: