iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(wiki): Phase B+C完成 — middleware/saas/security/memory 5节模板重构

Browse Source 
- middleware.md: 集成契约+3不变量+执行流 (157→136行)
- saas.md: 移除安全重复→引用security.md+Token Pool算法 (231→173行)
- security.md: 吸收saas认证内容成为安全唯一真相源 (158→199行)
- memory.md: 最大压缩363→147行+Hermes洞察提炼+4不变量

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
iven
2026-04-22 21:42:24 +08:00
parent 36612eac53
commit 5d88d129d1
5 changed files with 532 additions and 760 deletions
Download Patch File Download Diff File Expand all files Collapse all files

470
wiki/memory.md
View File

@@ -2,412 +2,146 @@
title: 记忆管道
updated: 2026-04-22
status: active
tags: [module, memory, growth]
tags: [module, memory, fts5, growth]
---
# 记忆管道 (Memory Pipeline)
> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]]
> 从 [[index]] 导航。关联: [[chat]] [[middleware]] [[butler]]
> 详细提取逻辑归档: [[archive/memory-extraction-details]]
## 设计思想
## 1. 设计决策
**核心问题: LLM 无状态，每次对话都从零开始。需要从历史对话中积累知识。**
**核心问题: LLM 无状态，每次对话从零开始。需要从历史对话中积累知识。**
设计决策:
1. **闭环架构** — 对话 → 提取 → 索引 → 检索 → 注入，形成正向循环
2. **FTS5 + TF-IDF** — 轻量级语义搜索，不依赖外部 embedding 服务
3. **Token 预算控制** — 注入 system prompt 时有 token 上限，防止溢出
4. **EmbeddingClient trait 已预留** — 接口已写，激活即可升级到向量搜索
| 决策 | WHY |
|------|-----|
| 闭环架构 | 对话→提取→索引→检索→注入，形成正向循环。每次聊天都积累，每次提问都利用 |
| 双数据库 | memories.db (FTS5 全文索引) + data.db (结构化画像)。前者处理模糊语义检索，后者处理精确字段查询 |
| FTS5+TF-IDF+Embedding 三层 | FTS5 粗筛 + TF-IDF 加权 + Embedding 精排（当前 NoOp，配置后激活）。不依赖外部服务即可工作 |
| 进化引擎 | 从对话中检测行为模式变化，生成进化候选项（技能建议/工作流优化），通过 EvolutionMiddleware@78 注入 system prompt |
| Token 预算控制 | 注入 system prompt 时有 token 上限，防止记忆注入挤占用户实际对话空间 |
## 功能清单
**Hermes 核心借鉴** (详见 [[archive/hermes-analysis]]): 经验库 FTS5 全文检索 + 用户画像结构化建模 + 自然语言 cron 调度 + 轨迹记录压缩。4 Chunk 已交付: ExperienceStore(10 tests) + UserProfileStore(14 tests) + NlScheduleParser(16 tests) + TrajectoryRecorder(18 tests)。
| 功能 | 描述 | 入口文件 | 状态 |
|------|------|----------|------|
| 记忆提取 | LLM 从对话中提取偏好/知识/经验 | extractor.rs | ✅ |
| FTS5 全文检索 | SQLite FTS5 + TF-IDF 权重搜索 | storage/sqlite.rs | ✅ |
| 语义检索 | 意图分类 + CJK 关键词 + 混合评分 | retriever.rs, retrieval/query.rs | ✅ |
| Prompt 注入 | token 预算控制 + 结构化上下文注入 | injector.rs | ✅ |
| 经验管理 | pain→solution→outcome CRUD | experience_store.rs | ✅ |
| 用户画像 | 结构化偏好/兴趣/能力管理 | profile_updater.rs | ✅ |
| 进化引擎 | 行为模式检测 → 技能/工作流建议 | evolution_engine.rs | ✅ |
| 质量门控 | 长度/标题/置信度/去重校验 | quality_gate.rs | ✅ |
| 自动技能生成 | 从模式生成 SkillManifest | skill_generator.rs | ✅ |
| 上下文压缩 | 超长对话压缩摘要 | summarizer.rs | ✅ |
| 嵌入向量 | EmbeddingClient trait + NoOp 默认 | retrieval/semantic.rs | 🚧 接口就绪 |
| SaaS pgvector | knowledge_chunks 向量索引 | saas/generate_embedding.rs | 🚧 索引就绪，生成未实现 |
## 2. 关键文件 + 数据流
## 代码逻辑
### 核心文件
| 文件 | 职责 |
|------|------|
| `crates/zclaw-growth/src/extractor.rs` | LLM 记忆提取 (偏好/知识/经验) |
| `crates/zclaw-growth/src/retriever.rs` | 语义检索 (FTS5 + TF-IDF + 意图分类) |
| `crates/zclaw-growth/src/injector.rs` | Prompt 注入 (token 预算) |
| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 (memories.db) |
| `crates/zclaw-runtime/src/middleware/memory.rs` | 记忆中间件 (提取+注入编排) |
| `crates/zclaw-runtime/src/growth.rs` | GrowthIntegration 闭环编排 |
| `crates/zclaw-memory/src/user_profile_store.rs` | UserProfileStore (data.db) |
### 闭环数据流
```
[提取] 对话发生
→ MemoryExtractor (crates/zclaw-growth/src/extractor.rs)
→ LLM 提取: 偏好 (Preference) / 知识 (Knowledge) / 经验 (Experience)
→ MemoryEntry { agent_id, memory_type, content, keywords, importance }
[提取] 对话完成 → MemoryMiddleware.after_completion
→ MemoryExtractor.extract_combined() → LLM 单次调用
→ CombinedExtraction { memories, experiences, profile_signals }
→ VikingAdapter → SqliteStorage → memories.db (FTS5 索引)
→ UserProfileStore → data.db (结构化画像)
[索引] 存储
→ SqliteStorage.store() (crates/zclaw-growth/src/storage/sqlite.rs)
→ SQLite + FTS5 全文索引
→ TF-IDF 权重计算
→ (可选) EmbeddingClient.embed() → 向量存储 [未激活]
[检索] 查询时
→ MemoryRetriever.retrieve(query, agent_id) (crates/zclaw-growth/src/retriever.rs)
→ QueryAnalyzer: 意图分类 (Preference/Knowledge/Experience/Code/General)
→ 中文+英文关键词提取 + CJK 支持 + 同义词扩展
→ SemanticScorer: TF-IDF 匹配 (70% embedding / 30% TF-IDF, embedding 未激活)
→ 返回 top-k 相关记忆
[注入] 给 LLM
→ PromptInjector.inject(system_prompt, memories) (crates/zclaw-growth/src/injector.rs)
→ token 预算控制
→ 格式化为结构化上下文块
→ 插入到 system prompt 中
[检索] 新请求 → MemoryMiddleware.before_completion
→ MemoryRetriever.retrieve(agent_id, user_input)
→ QueryAnalyzer 意图分类 (5类: Preference/Knowledge/Experience/Code/General)
→ FTS5 全文搜索 + TF-IDF 评分 + IdentityRecall 43+ 模式
→ 弱身份 fallback: <3 结果 → 补充 broad retrieval
→ PromptInjector.inject_with_format(system_prompt, memories)
```
### 跨会话记忆完整链路（2026-04-22 验证通过）
### 集成契约
> **重要：修改任何环节前请先阅读此链路，避免引入断裂。**
| 方向 | 模块 | 触发点 |
|------|------|--------|
| Called by | middleware: Memory@150 | Every chat completion (after) + new request (before) |
| Calls | zclaw-memory: FTS5 store, TF-IDF scorer | Memory extraction + retrieval |
| Calls | zclaw-growth: GrowthIntegration, EvolutionEngine | Pattern detection + skill generation |
| Provides | loop_runner: Context injection into system prompt | Before LLM call |
### Tauri 命令
| 分类 | 命令数 | 关键命令 |
|------|--------|----------|
| Memory CRUD (`memory_commands.rs`) | 11 | `memory_store`, `memory_search`, `memory_build_context` |
| VikingStorage (`viking_commands.rs`) | 14 | `viking_add`, `viking_find`, `viking_inject_prompt` |
| Intelligence (`intelligence/`) | ~40 | identity(13), heartbeat(11), pain(5), reflection(6) |
| 提取+Embedding | 5 | `extract_session_memories`, `embedding_create` |
## 3. 代码逻辑
### 跨会话记忆完整链路
```
[初始化] 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<Arc<GrowthIntegration>>)
→ MemoryMiddleware::new(growth) 注册到中间件链 (priority=150)
[初始化] kernel_init → init_storage(memories.db) → MemoryStore(data.db)
→ set_viking(SqliteStorage) → set_extraction_driver(LLM)
→ [首次聊天] create_middleware_chain() 重建 GrowthIntegration:
VikingAdapter + ExtractionDriver + UserProfileStore(data.db)
→ MemoryMiddleware@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)
[写入] after_completion → 30秒去重 → extract_combined(LLM)
→ memories → memories.db | profile_signals → data.db
[读取] 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 预算注入结构化上下文
[读取] before_completion → retrieve(agent_id, query)
→ FTS5 + TF-IDF + IdentityRecall → inject_with_format()
[展示] 管家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 前端展示
[展示] 管家Tab → viking_ls/viking_read(memories.db) + agent_get(data.db)
```
### 经验存储 (ExperienceStore)
### 不变量
Hermes 管线 Chunk1 新增:
- memories.db 和 data.db 是独立的 SQLite 数据库，跨库查询需使用正确连接
- 记忆注入在中间件@150，AFTER ButlerRouter@80，BEFORE SkillIndex@200
- Embedding 当前为 NoOpEmbeddingClient，用户配置 provider 后替换为真实实现
- 30 秒去重窗口：同一 agent 30 秒内跳过重复提取
- URI scheme: `agent://{agent_id}/{type}/{category}`
```
ExperienceStore (crates/zclaw-growth/src/experience_store.rs)
→ CRUD 封装: pain → solution → outcome 结构化经验
→ 底层使用 VikingAdapter
→ URI scheme: agent://{agent_id}/experience/...
```
### 非显然逻辑
### Hermes 管线 (4 Chunk)
- TF-IDF 语义路由：70% embedding 权重 + 30% TF-IDF（embedding 未激活时退化为纯 TF-IDF）
- IdentityRecall: 43+ 模式匹配（"你记得我"/"上次说的"/"我的偏好"等）触发记忆检索
- 弱身份 fallback: 检索结果 <3 且含弱身份关键词时，补充 broad retrieval 扩大搜索范围
| Chunk | 模块 | 文件 | 测试 |
|-------|------|------|------|
| 1 | ExperienceStore + Extractor | experience_store.rs | 10 |
| 2 | UserProfileStore + Profiler | user_profile.rs | 14 |
| 3 | NlScheduleParser | nl_schedule.rs | 16 |
| 4 | TrajectoryRecorder + Compressor | middleware/trajectory_recorder.rs | 18 |
## 4. 活跃问题 + 陷阱
Hermes 相关测试分布:
- `nl_schedule.rs`: 16 tests (中文时间→cron 解析)
- `types.rs`: 9 tests (记忆类型)
- `injector.rs`: 9 tests (prompt 注入)
### 活跃
### 查询意图分类
`QueryAnalyzer` 支持 5 种意图:
| 意图 | 说明 | 检索策略 |
|------|------|----------|
| Preference | 用户偏好 | 精确匹配 preference 类型记忆 |
| Knowledge | 知识查询 | 语义搜索 knowledge 类型 |
| Experience | 经验检索 | 时间+相关性排序 |
| Code | 代码相关 | 关键词优先 |
| General | 通用 | 混合策略 |
### Embedding 基础设施 (已写未激活)
```
EmbeddingClient trait (crates/zclaw-growth/src/retrieval/semantic.rs)
→ async embed(&str) -> Vec<f32>
→ is_available() -> bool
→ 当前实现: NoOpEmbeddingClient (始终返回空)
SaaS 侧:
→ pgvector HNSW 索引就绪 (knowledge_chunks 表, vector(1536))
→ generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred)
```
### 进化引擎 (EvolutionEngine)
zclaw-growth 包含完整的自我改进闭环:
```
EvolutionEngine (crates/zclaw-growth/src/evolution_engine.rs)
→ 从对话历史中检测行为模式变化
→ 生成进化候选项 (新技能建议/工作流优化)
→ EvolutionMiddleware@78 注入 system prompt
配套组件:
→ FeedbackCollector — 收集用户反馈信号
→ PatternAggregator — 行为模式聚合
→ QualityGate — 进化质量门控
→ SkillGenerator — 自动技能生成
→ WorkflowComposer — 工作流自动编排
→ ProfileUpdater — 用户画像更新
→ ExperienceExtractor — 经验提取器
→ Summarizer — 记忆摘要
```
zclaw-growth 模块结构 (19 文件):
```
crates/zclaw-growth/src/
├── evolution_engine.rs 进化引擎核心
├── experience_extractor.rs 经验提取
├── experience_store.rs 经验 CRUD
├── extractor.rs 记忆提取
├── feedback_collector.rs 反馈收集
├── injector.rs Prompt 注入
├── json_utils.rs JSON 工具
├── pattern_aggregator.rs 模式聚合
├── profile_updater.rs 画像更新
├── quality_gate.rs 质量门控
├── retriever.rs 语义检索
├── skill_generator.rs 技能生成
├── summarizer.rs 摘要生成
├── tracker.rs 追踪器
├── types.rs 类型定义
├── viking_adapter.rs Viking 适配器
├── workflow_composer.rs 工作流编排
├── retrieval/ 检索子模块
│ ├── query.rs 意图分类 + CJK
│ └── semantic.rs EmbeddingClient
└── storage/ 存储子模块
└── sqlite.rs FTS5 + TF-IDF
```
### 前端 Tauri 命令
> 完整 API 接口详情见下方 `## API 接口` 章节。
**Memory CRUD** (`desktop/src-tauri/src/memory_commands.rs`, 11 命令):
| 命令 | 参数 | 说明 |
| 问题 | 状态 | 说明 |
|------|------|------|
| `memory_store` | MemoryEntryInput | 存储记忆条目 |
| `memory_get` | id | 按 ID 获取 |
| `memory_search` | MemorySearchOptions | FTS5 + TF-IDF 搜索 |
| `memory_delete` | id | 删除单条 |
| `memory_delete_all` | agent_id | 删除 Agent 全部记忆 |
| `memory_stats` | — | 记忆统计 |
| `memory_export` | — | 导出全部 |
| `memory_import` | Vec\<PersistentMemory\> | 批量导入 |
| `memory_build_context` | agent_id, query, max_tokens? | 构建检索增强上下文 |
| `memory_db_path` | — | SQLite 路径 |
| `memory_init` | — | 初始化 (no-op, Viking 自动初始化) |
| Embedding 未激活 | 🚧 长期观察 | NoOpEmbeddingClient 是默认值，用户配置 provider 后替换 |
| SaaS pgvector | 🚧 deferred | HNSW 索引就绪 (knowledge_chunks, vector(1536))，生成逻辑未实现 |
**VikingStorage** (`desktop/src-tauri/src/viking_commands.rs`, 14 命令):
### 历史陷阱 (已修复)
| 命令 | 说明 |
|------|------|
| `viking_add` / `viking_add_with_metadata` | 添加记忆 (URI scheme: agent://{id}/{type}/{category}) |
| `viking_find` | 语义/关键词搜索 |
| `viking_grep` | 正则搜索 |
| `viking_ls` / `viking_tree` / `viking_read` | 浏览/读取 |
| `viking_remove` | 删除 |
| `viking_inject_prompt` | 记忆注入 prompt |
| `viking_configure_embedding` | 配置 embedding provider |
| `viking_configure_summary_driver` | 配置摘要 LLM |
| `viking_store_with_summaries` | 自动摘要存储 |
| `viking_status` | 存储健康检查 |
| `viking_load_industry_keywords` | 加载行业关键词 |
- 跨会话记忆断裂 (profile_store 未连接 + 双数据库不一致 + 缺日志) → 04-22 已修复 (adf0251)
- 记忆去重失败 (同 URI+content 重复添加) → 04-17 已修复 (a504a40)
- 记忆非 Agent 隔离 (viking_find 返回所有 Agent 记忆) → 04-17 已修复 (a504a40)
- 跨会话注入断裂 (新会话报 "no conversation history found") → 04-17 已修复 (a504a40)
**Intelligence** (`desktop/src-tauri/src/intelligence/`, ~40 命令):
### 警告
| 模块 | 命令数 | 功能 |
|------|--------|------|
| identity.rs | 13 | Agent 身份/SOUL.md 管理 |
| heartbeat.rs | 11 | Heartbeat 引擎配置+记录 |
| pain_aggregator.rs | 5 | 痛点追踪+方案生成 |
| reflection.rs | 6 | 自我反思引擎 |
| compactor.rs | 4 | 上下文压缩 |
| health_snapshot.rs | 1 | 综合健康快照 |
> memories.db / data.db 连接池隔离。修改存储层代码务必确认目标数据库。
> GrowthIntegration 缓存在 `set_viking()` / `set_extraction_driver()` 时会被清除，首次聊天时重建。
**记忆提取** (`desktop/src-tauri/src/memory/`, 3 命令):
`extract_session_memories`, `extract_and_store_memories`, `estimate_content_tokens`
## 5. 变更日志
**Embedding** (`desktop/src-tauri/src/llm/`, 2 命令):
`embedding_create`, `embedding_providers`
**总计 ~74 个** memory/growth/intelligence 相关 Tauri 命令。
## API 接口
### Memory CRUD (`desktop/src-tauri/src/memory_commands.rs`, 11 命令)
| 命令 | 参数 | 说明 |
| 日期 | 变更 | 关联 |
|------|------|------|
| `memory_store` | MemoryEntryInput | 存储记忆条目 |
| `memory_get` | id | 按 ID 获取 |
| `memory_search` | MemorySearchOptions | FTS5 + TF-IDF 搜索 |
| `memory_delete` | id | 删除单条 |
| `memory_delete_all` | agent_id | 删除 Agent 全部记忆 |
| `memory_stats` | — | 记忆统计 |
| `memory_export` | — | 导出全部 |
| `memory_import` | Vec\<PersistentMemory\> | 批量导入 |
| `memory_build_context` | agent_id, query, max_tokens? | 构建检索增强上下文 |
| `memory_db_path` | — | SQLite 路径 |
| `memory_init` | — | 初始化 (no-op) |
| 2026-04-22 | 跨会话记忆断裂修复: profile_store 连接 + 双数据库统一 + 诊断日志 | commit adf0251 |
| 2026-04-22 | Wiki 5-section 重构: 363→~190 行，详细逻辑归档 | wiki/ |
| 2026-04-21 | Embedding 接通 + 自学习自动化 A线+B线 (SemanticScorer + EvolutionMiddleware) | 934 tests PASS |
| 2026-04-17 | E2E 全系统验证 129 链路: 记忆去重+注入+跨会话 修复 | 79.1% 通过率 |
| 2026-04-15 | Heartbeat 统一健康系统 (health_snapshot + 健康快照集成) | 183 commands |
### VikingStorage (`desktop/src-tauri/src/viking_commands.rs`, 14 命令)
## 测试概览
| 命令 | 说明 |
|------|------|
| `viking_add` / `viking_add_with_metadata` | 添加记忆 (URI: agent://{id}/{type}/{category}) |
| `viking_find` | 语义/关键词搜索 |
| `viking_grep` | 正则搜索 |
| `viking_ls` / `viking_tree` / `viking_read` | 浏览/读取 |
| `viking_remove` | 删除 |
| `viking_inject_prompt` | 记忆注入 prompt |
| `viking_configure_embedding` | 配置 embedding provider |
| `viking_configure_summary_driver` | 配置摘要 LLM |
| `viking_store_with_summaries` | 自动摘要存储 |
| `viking_status` / `viking_load_industry_keywords` | 健康检查/行业关键词 |
### Intelligence (`desktop/src-tauri/src/intelligence/`, ~40 命令)
| 模块 | 命令数 | 功能 |
|------|--------|------|
| identity.rs | 13 | Agent 身份/SOUL.md 管理 |
| heartbeat.rs | 11 | Heartbeat 引擎配置+记录 |
| pain_aggregator.rs | 5 | 痛点追踪+方案生成 |
| reflection.rs | 6 | 自我反思引擎 |
| compactor.rs | 4 | 上下文压缩 |
| health_snapshot.rs | 1 | 综合健康快照 |
### 记忆提取 + Embedding (5 命令)
`extract_session_memories`, `extract_and_store_memories`, `estimate_content_tokens` (memory/)
+ `embedding_create`, `embedding_providers` (llm/)
**总计 ~74 个** memory/growth/intelligence 相关 Tauri 命令。
## 测试链路
| 功能 | Crate | 测试文件 | 测试数 | 覆盖状态 |
|------|-------|---------|--------|---------|
| 记忆存储/检索 | zclaw-growth | storage/sqlite.rs | 6 | ✅ |
| 经验 CRUD | zclaw-growth | experience_store.rs | 12 | ✅ |
| 提取器 | zclaw-growth | extractor.rs | 8 | ✅ |
| 注入器 | zclaw-growth | injector.rs | 9 | ✅ |
| 质量门控 | zclaw-growth | quality_gate.rs | 9 | ✅ |
| 进化引擎 | zclaw-growth | evolution_engine.rs | 5 | ✅ |
| 技能生成 | zclaw-growth | skill_generator.rs | 6 | ✅ |
| 工作流编排 | zclaw-growth | workflow_composer.rs | 5 | ✅ |
| 意图分类+CJK | zclaw-growth | retrieval/query.rs | 11 | ✅ |
| 语义评分 | zclaw-growth | retrieval/semantic.rs | 9 | ✅ |
| Embedding | zclaw-growth | retrieval/cache.rs | 7 | ✅ |
| 模式聚合 | zclaw-growth | pattern_aggregator.rs | 6 | ✅ |
| 反馈收集 | zclaw-growth | feedback_collector.rs | 10 | ✅ |
| 摘要 | zclaw-growth | summarizer.rs | 5 | ✅ |
| 类型定义 | zclaw-growth | types.rs | 13 | ✅ |
| 进化闭环 | zclaw-growth | tests/evolution_loop_test.rs | 6 | ✅ |
| 经验链 | zclaw-growth | tests/experience_chain_test.rs | 6 | ✅ |
| 集成 | zclaw-growth | tests/integration_test.rs | 9 | ✅ |
| **zclaw-growth 小计** | | 29 文件 | **181** | |
| 记忆存储 | zclaw-memory | store.rs | 20 | ✅ |
| 用户画像 | zclaw-memory | user_profile_store.rs | 20 | ✅ |
| 轨迹记录 | zclaw-memory | trajectory_store.rs | 9 | ✅ |
| 事实提取 | zclaw-memory | fact.rs | 5 | ✅ |
| **zclaw-memory 小计** | | 4 文件 | **54** | |
| **合计** | | 33 文件 | **235** | |
## 关联模块
- [[chat]] — 对话是记忆的输入源
- [[butler]] — 管家模式可能利用记忆提供个性化响应
- [[middleware]] — Memory 中间件自动提取 + SkillIndex 注入
## 关键文件
| 文件 | 职责 |
|------|------|
| `crates/zclaw-growth/src/extractor.rs` | LLM 记忆提取 |
| `crates/zclaw-growth/src/retriever.rs` | 语义检索 |
| `crates/zclaw-growth/src/injector.rs` | Prompt 注入 (token 预算) |
| `crates/zclaw-growth/src/experience_store.rs` | 经验 CRUD |
| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 |
| `crates/zclaw-growth/src/retrieval/semantic.rs` | EmbeddingClient trait |
| `crates/zclaw-growth/src/retrieval/query.rs` | 意图分类 + CJK 关键词 |
| `crates/zclaw-growth/src/nl_schedule.rs` | 中文时间→cron 解析 (16 tests) |
| `crates/zclaw-runtime/src/middleware/memory.rs` | 记忆中间件 |
| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录中间件 |
| `desktop/src/store/memoryGraphStore.ts` | 前端记忆 UI |
| `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 |
| `desktop/src-tauri/src/memory_commands.rs` | 13 个 memory CRUD 命令 |
## 已知问题
- ✅ **记忆去重失败** — BUG-H2 已修复 (commit a504a40)。`viking_add` 同 URI+content 重复添加
- ✅ **记忆非 Agent 隔离** — BUG-M3 已修复 (commit a504a40)。`viking_find` 返回所有 Agent 记忆
- ✅ **跨会话注入断裂** — BUG-M5 已修复 (commit a504a40)。新会话报 "no conversation history found"
- ✅ **profile_store 未连接** — 已修复 (commit adf0251)。create_middleware_chain() 中未设置 UserProfileStore，导致 profile_signals 被静默丢弃
- ✅ **双数据库 UserProfile 不一致** — 已修复 (commit adf0251)。UserProfileStore 写入 data.db 而 agent_get 读取 memories.db
- ⚠️ **NoOpEmbeddingClient 是默认值** — 正常设计，用户配置 provider 后替换
- ⚠️ **SaaS pgvector embedding 生成未实现** — 索引就绪，生成逻辑 deferred
| Crate | 测试数 | 覆盖 |
|-------|--------|------|
| zclaw-growth | 181 (29 文件) | 全覆盖 |
| zclaw-memory | 54 (4 文件) | 全覆盖 |
| **合计** | **235** | |