zclaw_openfang/docs/knowledge-base/semantic-memory-audit.md

# 语义记忆 vs OpenViking 差距审计记录

**审计日期**: 2026-03-26
**审计范围**: ZCLAW 语义记忆子系统 vs OpenViking 原始设计
**审计结果**: 发现 2 个核心差距，已全部修复

---

## 一、审计背景与方法

### 1.1 审计动机

ZCLAW 的记忆系统基于 OpenViking 设计构建，但在实际落地过程中可能存在功能缺失或实现降级。本次审计目的是系统性比对 ZCLAW 实现与 OpenViking 设计规格之间的差距。

### 1.2 审计方法（可复用模板）

本次采用的五步审计流程可作为其他功能点的审计模板：

```
Step 1: 文档对齐 — 将 OpenViking 设计文档与 ZCLAW 实际代码逐一比对
Step 2: 追踪数据流 — 从前端 UI 到后端存储，确认每个环节是否连通
Step 3: 识别 dead_code — 搜索 #[allow(dead_code)]、#![allow(dead_code)]、未注册的命令
Step 4: 检查 trait 实现 — 确认 trait 方法是否被实际调用（而非仅定义）
Step 5: 验证端到端 — 从用户操作角度验证功能是否真正可用
```

### 1.3 关键发现

ZCLAW 存在**两套并行存储系统**，这是很多差距的根因：

| 存储系统 | 代码位置 | 使用场景 | 调用入口 |
|----------|----------|----------|----------|
| `SqliteStorage` | `crates/zclaw-growth/src/storage/sqlite.rs` | VikingPanel 记忆管理 | VikingCommands |
| `PersistentMemoryStore` | `desktop/src-tauri/src/memory/persistent.rs` | 聊天流程记忆 | MemoryCommands |

两套系统功能不对等，导致某些功能在一个路径可用但另一个不可用。

---

## 二、发现的差距与修复

### 差距 1: 向量嵌入搜索未启用

**严重程度**: 高
**差距描述**: OpenViking 设计中包含向量嵌入语义搜索，ZCLAW 代码中 `EmbeddingClient` trait、`index_entry_with_embedding()`、`score_similarity_with_embedding()` 已写好但从未被调用。搜索仅依赖 TF-IDF。

**根因分析**:
- `llm::EmbeddingClient` HTTP 客户端存在，Settings 页面有测试按钮
- 但前端保存 Embedding 配置后未调用 `viking_configure_embedding` 将配置传递到后端
- `SqliteStorage.store()` 未在存储时自动生成 embedding
- `SqliteStorage.find()` 未使用混合评分（embedding + TF-IDF）

**修复方案**:
1. 创建 `embedding_adapter.rs` — 将 `llm::EmbeddingClient` 适配为 `zclaw_growth::EmbeddingClient` trait
2. `SqliteStorage` 添加 `configure_embedding()` 方法
3. 修改 `store()` — embedding 可用时自动生成向量
4. 修改 `find()` — 混合评分（70% embedding + 30% TF-IDF），降级到纯 TF-IDF
5. 前端 `ModelsAPI.tsx` 保存后调用 `viking_configure_embedding`
6. `App.tsx` bootstrap 阶段自动恢复配置

**经验教训**:
> **"代码写好不等于功能可用"** — trait 实现、适配器、前端接入、启动恢复，任何一环缺失都会导致功能不可用。审计时不能只看代码是否存在，必须追踪完整调用链。

---

### 差距 2: L0/L1/L2 分层加载未接入

**严重程度**: 高
**差距描述**: OpenViking 设计了三层记忆加载策略以节省 token：
- L0（Quick Scan）: ~100 tokens，3-5 个关键词
- L1（Standard）: ~200 tokens，1-2 句话摘要
- L2（Deep）: 完整内容

ZCLAW 中 `context_builder.rs` 已有完整 L0→L1→L2 加载逻辑，但整个模块标记为 `#![allow(dead_code)]`，从未接入实际聊天流程。

**根因分析**:
- `MemoryEntry` 缺少 `overview` 和 `abstract_summary` 字段
- 没有 LLM 驱动来生成摘要
- `ContextBuilder.build_context()` 未被任何 Tauri 命令调用
- `chatStore.ts` 使用简单的 `memory.search()` + 手动拼接，无分层概念

**修复方案**:
1. `MemoryEntry` 添加 `overview: Option<String>` 和 `abstract_summary: Option<String>`
2. 两套存储系统均做 schema migration（`ALTER TABLE ADD COLUMN`）
3. 新建 `summarizer.rs` — `SummaryLlmDriver` trait + prompt 模板
4. 新建 `summarizer_adapter.rs` — 用 OpenAI 兼容 API 实现摘要生成
5. 添加 `memory_build_context` Tauri 命令 — 优先使用 L1 overview，尊重 token 预算
6. `chatStore.ts` 替换为调用 `buildContext()` 获取分层上下文
7. `VikingPanel.tsx` 支持 L1→L2 展开
8. `extract_and_store_memories` 存储后异步生成 L0/L1

**经验教训**:
> **"#![allow(dead_code) 是最大的技术债信号"** — 完整的功能实现被标记为死代码，说明设计阶段考虑周全但集成阶段被跳过。审计时应优先搜索 `dead_code` 标记。
>
> **"后台异步生成 + 即时存储"模式** — L2 完整内容同步存储（不阻塞），L0/L1 摘要通过 `tokio::spawn` 后台异步生成并回写。这保证了用户体验不受影响。

---

## 三、集成审计中发现的 5 个 GAP

在修复核心差距后，进行了端到端集成审计，发现以下连通性问题：

| GAP | 描述 | 状态 |
|-----|------|------|
| GAP 1 | Settings 保存 Embedding 配置后未通知后端 | 已修复 |
| GAP 2 | Bootstrap 阶段未自动恢复 Embedding 配置 | 已修复 |
| GAP 3 | `extract_and_store_memories` 未触发 L0/L1 生成 | 已修复 |
| GAP 4 | Summary Driver 需要单独配置 | 不需要 — 已改为自动从活跃 LLM 配置 |
| GAP 5 | `context_builder.rs` 仍标记 dead_code | 已清理注释说明现状 |

---

## 四、遗留问题（后续工作）

### 4.1 双存储系统统一

当前 SqliteStorage 和 PersistentMemoryStore 功能不对等：

| 能力 | SqliteStorage | PersistentMemoryStore |
|------|--------------|----------------------|
| FTS5 全文搜索 | 有 | 无（仅 LIKE 查询） |
| TF-IDF 语义评分 | 有 | 无 |
| L0 abstract_summary | 有 | 无 |
| L0/L1 自动生成 | 有 | 无 |
| 导出/导入 | 无 | 有 |
| 记忆统计 | 无 | 有 |

**建议**: 长期应统一为一套存储系统，或在 PersistentMemoryStore 补齐缺失能力。

### 4.2 测试覆盖不足

| 模块 | 测试状态 |
|------|----------|
| `embedding_adapter.rs` | 无测试 |
| `memory_commands.rs` | 无测试 |
| `persistent.rs`（store/search/embedding） | 仅 1 个 ID 生成测试 |
| 端到端 embedding + 搜索流程 | 无集成测试 |
| 端到端 L0/L1 生成流程 | 无集成测试 |

### 4.3 ContextBuilder 完整版未启用

`context_builder.rs` 中的完整 L0→L1→L2 渐进加载逻辑仍是 dead_code。当前聊天流程使用简化的 `memory_build_context`。完整版预留了 retrieval trace、分阶段 token 预算等高级能力，待后续启用。

### 4.4 Intelligence 子系统大面积 dead_code

以下模块均为 `#![allow(dead_code)]`：
- `validation.rs` — 验证函数
- `identity.rs` — 身份管理
- `recommender.rs` — 推荐系统
- `heartbeat.rs` — 心跳引擎
- `pattern_detector.rs` — 模式检测
- `persona_evolver.rs` — 人格演化
- `compactor.rs` — 记忆压缩
- `trigger_evaluator.rs` — 触发评估
- `mesh.rs` — Agent 群体
- `reflection.rs` — 自我反思

---

## 五、审计方法论总结（供后续复用）

### 5.1 通用审计清单

对任何功能点进行审计时，按以下维度检查：

```
[ ] 代码存在性 — trait/struct/function 是否已定义
[ ] 实现完整性 — trait 方法是否有具体实现（非空/panic）
[ ] 调用链连通 — 从 UI 触发到后端执行的完整路径是否打通
[ ] 配置传递 — 前端配置是否能传递到后端生效
[ ] 启动恢复 — 应用重启后配置/状态是否能自动恢复
[ ] 降级策略 — 依赖不可用时是否有合理降级
[ ] 数据流闭环 — 写入的数据能否被正确读取和使用
[ ] dead_code 清理 — 无 dead_code 或有明确原因保留
[ ] 双系统一致性 — 多套实现是否功能对等
[ ] 测试覆盖 — 关键路径是否有测试
```

### 5.2 常见差距模式

本次审计中发现的差距模式可归纳为：

1. **"写了没接"** — 代码已实现但未接入实际流程（ContextBuilder、EmbeddingClient）
2. **"接了没传"** — 后端命令存在但前端未调用（viking_configure_embedding）
3. **"传了没存"** — 配置保存了但未持久化或恢复（Embedding 配置丢失）
4. **"存了没用"** — 数据已存储但读取时未使用（overview 字段未被搜索返回）
5. **"双系统不同步"** — 一套系统有功能另一套没有（SqliteStorage vs PersistentMemoryStore）

### 5.3 审计命令速查

```bash
# 搜索 dead_code 标记
rg "allow\(dead_code\)" --type rust

# 搜索未使用的函数
rg "#\[allow(dead_code)\]" crates/ desktop/src-tauri/src/

# 搜索未注册的 Tauri 命令
rg "#\[tauri::command\]" desktop/src-tauri/src/ -l
# 对比 lib.rs 中的 .invoke_handler() 注册列表

# 搜索 TODO/FIXME
rg "TODO|FIXME" --type rust --type ts

# 搜索前端 invoke 调用
rg "invoke\(" desktop/src/ --type ts -l

# 编译检查
cargo check 2>&1 | grep -i "warning\|error"

# 测试
cargo test -p zclaw-growth 2>&1 | tail -5
```

---

## 六、关键文件索引

| 文件 | 职责 | 审计阶段 |
|------|------|----------|
| `crates/zclaw-growth/src/types.rs` | MemoryEntry 数据模型 | Phase 2.1 |
| `crates/zclaw-growth/src/storage/sqlite.rs` | SqliteStorage 存储 | Phase 1.3, 2.1 |
| `crates/zclaw-growth/src/retrieval/semantic.rs` | TF-IDF + Embedding 评分 | Phase 1 |
| `crates/zclaw-growth/src/summarizer.rs` | L0/L1 摘要生成 trait | Phase 2.2 |
| `crates/zclaw-growth/src/injector.rs` | Prompt 注入器 | Phase 2.3 |
| `desktop/src-tauri/src/embedding_adapter.rs` | Embedding 适配器 | Phase 1.2 |
| `desktop/src-tauri/src/summarizer_adapter.rs` | 摘要 LLM 驱动 | Phase 2.2 |
| `desktop/src-tauri/src/viking_commands.rs` | Viking Tauri 命令 | Phase 1.4, 2.4 |
| `desktop/src-tauri/src/memory_commands.rs` | Memory Tauri 命令 | Phase 2.3 |
| `desktop/src-tauri/src/memory/persistent.rs` | PersistentMemoryStore | Phase 1.6, 2.1 |
| `desktop/src-tauri/src/memory/context_builder.rs` | L0/L1/L2 渐进加载 | Phase 2.3 |
| `desktop/src-tauri/src/memory/extractor.rs` | 会话记忆提取 | Phase 2.2 |
| `desktop/src/lib/intelligence-client.ts` | 前端记忆客户端 | Phase 2.3 |
| `desktop/src/store/chatStore.ts` | 聊天状态管理 | Phase 2.3 |
| `desktop/src/components/VikingPanel.tsx` | 记忆管理面板 | Phase 2.4 |
| `desktop/src/App.tsx` | 应用启动引导 | Phase 1.5, 2.2 |