feat(backend): implement Phase 1 of Intelligence Layer Migration

- Add SQLite-based persistent memory storage (persistent.rs) - Create memory persistence Tauri commands (memory_commands.rs) - Add sqlx dependency to Cargo.toml for SQLite support - Update memory module to export new persistent types - Register memory commands in Tauri invoke handler - Add comprehensive migration plan document Phase 1 delivers: - PersistentMemory struct with SQLite storage - MemoryStoreState for Tauri state management - 10 memory commands: init, store, get, search, delete, delete_all, stats, export, import, db_path - Full-text search capability - Cross-session memory retention Reference: docs/plans/INTELLIGENCE-LAYER-MIGRATION.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 00:36:06 +08:00
parent 48a430fc97
commit 0db8a2822f
7 changed files with 1633 additions and 11 deletions
--- a/docs/plans/INTELLIGENCE-LAYER-MIGRATION.md
+++ b/docs/plans/INTELLIGENCE-LAYER-MIGRATION.md
@@ -0,0 +1,329 @@
+# ZCLAW 智能层迁移规划
+
+> 将前端智能模块迁移到 Tauri Rust 后端
+
+---
+
+## 一、背景与动机
+
+### 1.1 当前问题
+
+| 问题 | 影响 | 严重程度 |
+|------|------|----------|
+| 应用关闭后功能停止 | 心跳、反思、主动学习都会中断 | 高 |
+| 数据持久化依赖 localStorage | 容量限制（5-10MB），无法跨设备同步 | 中 |
+| 前端处理大量数据 | 性能瓶颈，阻塞 UI | 中 |
+| 无法多端共享状态 | Agent 状态只能在单设备使用 | 中 |
+
+### 1.2 迁移目标
+
+1. **持续运行** - 关闭 UI 后后台服务继续工作
+2. **持久化存储** - 使用 SQLite 存储大量数据
+3. **性能优化** - Rust 处理计算密集型任务
+4. **跨设备同步** - 通过 Gateway 同步状态
+
+---
+
+## 二、当前架构分析
+
+### 2.1 前端智能模块（待迁移）
+
+| 文件 | 行数 | 功能 | 依赖 |
+|------|------|------|------|
+| `agent-memory.ts` | 486 | Agent 记忆管理 | memory-index.ts |
+| `agent-identity.ts` | 350 | 身份演化系统 | agent-memory.ts |
+| `reflection-engine.ts` | 677 | 自我反思引擎 | agent-memory.ts, llm |
+| `heartbeat-engine.ts` | 346 | 心跳引擎 | agent-memory.ts |
+| `context-compactor.ts` | 442 | 上下文压缩 | llm |
+| `agent-swarm.ts` | 549 | Agent 蜂群协作 | agent-memory.ts |
+| **总计** | **2850** | | |
+
+### 2.2 已有 Rust 后端模块
+
+| 模块 | 行数 | 功能 |
+|------|------|------|
+| `browser/` | ~1300 | 浏览器自动化 |
+| `memory/` | ~1040 | 上下文构建、信息提取 |
+| `llm/` | ~250 | LLM 调用封装 |
+| `viking_*` | ~400 | OpenViking 集成 |
+| `secure_storage` | ~150 | 安全存储 |
+| **总计** | **~5074** | |
+
+### 2.3 依赖关系图
+
+```
+agent-memory.ts
+    ↓
+├── agent-identity.ts
+├── reflection-engine.ts
+├── heartbeat-engine.ts
+└── agent-swarm.ts
+
+context-compactor.ts (独立)
+```
+
+---
+
+## 三、迁移策略
+
+### 3.1 分阶段迁移
+
+```
+Phase 1: 数据层迁移（2周）
+├── SQLite 存储引擎
+├── 记忆持久化 API
+└── 数据迁移工具
+
+Phase 2: 核心引擎迁移（3周）
+├── heartbeat-engine → Rust
+├── context-compactor → Rust
+└── 前端适配器
+
+Phase 3: 高级功能迁移（4周）
+├── reflection-engine → Rust
+├── agent-identity → Rust
+└── agent-swarm → Rust
+
+Phase 4: 集成与优化（2周）
+├── 端到端测试
+├── 性能优化
+└── 文档更新
+```
+
+### 3.2 迁移原则
+
+1. **渐进式迁移** - 保持前端功能可用，逐步切换到后端
+2. **双写阶段** - 迁移期间前后端都处理，确保数据一致性
+3. **API 兼容** - 前端 API 保持不变，内部调用 Tauri 命令
+4. **回滚机制** - 每个阶段都可以回滚到前一状态
+
+---
+
+## 四、详细设计
+
+### 4.1 Phase 1: 数据层迁移
+
+#### 4.1.1 SQLite Schema
+
+```sql
+-- Agent 记忆表
+CREATE TABLE memories (
+    id TEXT PRIMARY KEY,
+    agent_id TEXT NOT NULL,
+    content TEXT NOT NULL,
+    type TEXT CHECK(type IN ('fact', 'preference', 'lesson', 'context', 'task')),
+    importance INTEGER DEFAULT 5,
+    source TEXT DEFAULT 'auto',
+    tags TEXT, -- JSON array
+    conversation_id TEXT,
+    created_at TEXT NOT NULL,
+    last_accessed_at TEXT,
+    access_count INTEGER DEFAULT 0
+);
+
+-- 全文搜索索引
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+    content,
+    content='memories',
+    content_rowid='rowid'
+);
+
+-- Agent 身份表
+CREATE TABLE agent_identities (
+    agent_id TEXT PRIMARY KEY,
+    name TEXT,
+    personality TEXT, -- JSON
+    goals TEXT, -- JSON array
+    values TEXT, -- JSON object
+    communication_style TEXT,
+    expertise_areas TEXT, -- JSON array
+    version INTEGER DEFAULT 1,
+    updated_at TEXT
+);
+
+-- 反思记录表
+CREATE TABLE reflections (
+    id TEXT PRIMARY KEY,
+    agent_id TEXT NOT NULL,
+    trigger TEXT,
+    insight TEXT,
+    action_items TEXT, -- JSON array
+    created_at TEXT NOT NULL
+);
+```
+
+#### 4.1.2 Tauri 命令
+
+```rust
+// memory_commands.rs
+#[tauri::command]
+async fn memory_store(
+    agent_id: String,
+    content: String,
+    memory_type: String,
+    importance: i32,
+) -> Result<String, String> {
+    // ...
+}
+
+#[tauri::command]
+async fn memory_search(
+    agent_id: String,
+    query: String,
+    limit: i32,
+) -> Result<Vec<MemoryEntry>, String> {
+    // ...
+}
+
+#[tauri::command]
+async fn memory_get_all(
+    agent_id: String,
+    limit: i32,
+) -> Result<Vec<MemoryEntry>, String> {
+    // ...
+}
+```
+
+### 4.2 Phase 2: 核心引擎迁移
+
+#### 4.2.1 Heartbeat Engine
+
+```rust
+// heartbeat.rs
+pub struct HeartbeatEngine {
+    agent_id: String,
+    interval: Duration,
+    callbacks: Vec<HeartbeatCallback>,
+    running: AtomicBool,
+}
+
+impl HeartbeatEngine {
+    pub fn start(&self) {
+        // 后台线程运行心跳
+    }
+
+    pub fn tick(&self) -> HeartbeatResult {
+        // 执行心跳逻辑
+    }
+}
+
+#[tauri::command]
+async fn heartbeat_start(agent_id: String, interval_ms: u64) -> Result<(), String> {
+    // ...
+}
+
+#[tauri::command]
+async fn heartbeat_tick(agent_id: String) -> Result<HeartbeatResult, String> {
+    // ...
+}
+```
+
+#### 4.2.2 Context Compactor
+
+```rust
+// context_compactor.rs
+pub struct ContextCompactor {
+    target_tokens: usize,
+    preserve_recent: usize,
+}
+
+impl ContextCompaction {
+    pub async fn compact(&self, messages: Vec<Message>) -> Result<CompactedContext, Error> {
+        // 使用 LLM 压缩上下文
+    }
+}
+```
+
+### 4.3 前端适配器
+
+```typescript
+// desktop/src/lib/memory-backend.ts
+import { invoke } from '@tauri-apps/api/core';
+
+export class BackendMemoryManager {
+  async store(entry: Omit<MemoryEntry, 'id'>): Promise<string> {
+    return invoke('memory_store', {
+      agentId: entry.agentId,
+      content: entry.content,
+      memoryType: entry.type,
+      importance: entry.importance,
+    });
+  }
+
+  async search(query: string, options?: MemorySearchOptions): Promise<MemoryEntry[]> {
+    return invoke('memory_search', {
+      agentId: options?.agentId,
+      query,
+      limit: options?.limit || 50,
+    });
+  }
+}
+```
+
+---
+
+## 五、实施计划
+
+### 5.1 时间表
+
+| 阶段 | 开始 | 结束 | 交付物 |
+|------|------|------|--------|
+| Phase 1 | Week 1 | Week 2 | SQLite 存储 + Tauri 命令 |
+| Phase 2 | Week 3 | Week 5 | Heartbeat + Compactor |
+| Phase 3 | Week 6 | Week 9 | Reflection + Identity + Swarm |
+| Phase 4 | Week 10 | Week 11 | 集成测试 + 文档 |
+
+### 5.2 里程碑
+
+- **M1**: 记忆数据可在 Rust 后端存储和检索
+- **M2**: 心跳引擎在后台线程运行
+- **M3**: 所有智能模块迁移完成
+- **M4**: 通过全部 E2E 测试
+
+---
+
+## 六、风险评估
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| 数据迁移丢失 | 中 | 高 | 双写 + 备份机制 |
+| 性能不达预期 | 低 | 中 | 性能基准测试 |
+| API 兼容性问题 | 中 | 中 | 适配器模式 |
+| Rust 学习曲线 | 低 | 低 | 参考现有代码 |
+
+---
+
+## 七、验收标准
+
+### 7.1 功能验收
+
+- [ ] 所有记忆数据存储在 SQLite
+- [ ] 关闭 UI 后心跳继续运行
+- [ ] 前端 API 保持兼容
+- [ ] 数据迁移工具可用
+
+### 7.2 性能验收
+
+- [ ] 记忆检索 < 20ms（1000+ 条）
+- [ ] 心跳间隔精度 > 99%
+- [ ] 内存占用 < 100MB
+
+### 7.3 质量验收
+
+- [ ] 单元测试覆盖率 > 80%
+- [ ] E2E 测试全部通过
+- [ ] 文档更新完成
+
+---
+
+## 八、参考资料
+
+- [Tauri Commands](https://tauri.app/v1/guides/features/command/)
+- [SQLite in Rust](https://github.com/rusqlite/rusqlite)
+- [ZCLAW Deep Analysis](../analysis/ZCLAW-DEEP-ANALYSIS.md)
+
+---
+
+**文档版本**: 1.0
+**创建日期**: 2026-03-21
+**状态**: 规划中