zclaw_openfang/docs/plans/INTELLIGENCE-LAYER-MIGRATION.md

# 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 功能验收

- [x] 所有记忆数据存储在 SQLite
- [x] 关闭 UI 后心跳继续运行（后台线程）
- [ ] 前端 API 保持兼容（需要适配器）
- [ ] 数据迁移工具可用

### 7.2 性能验收

- [ ] 记忆检索 < 20ms（1000+ 条）
- [ ] 心跳间隔精度 > 99%
- [ ] 内存占用 < 100MB

### 7.3 质量验收

- [x] 单元测试覆盖率 > 80%（Rust 模块已有测试）
- [ ] E2E 测试全部通过
- [x] 文档更新完成

---

## 八、参考资料

- [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.1
**创建日期**: 2026-03-21
**最后更新**: 2026-03-21
**状态**: Phase 2-3 完成，Phase 4 进行中

---

## 九、实施进度

### 9.1 已完成工作

| 阶段 | 模块 | 状态 | 说明 |
|------|------|------|------|
| Phase 1 | SQLite 存储 | ✅ 完成 | `memory/persistent.rs` |
| Phase 1 | Tauri 命令 | ✅ 完成 | `memory_commands.rs` (10 命令) |
| Phase 2 | Heartbeat Engine | ✅ 完成 | `intelligence/heartbeat.rs` |
| Phase 2 | Context Compactor | ✅ 完成 | `intelligence/compactor.rs` |
| Phase 3 | Reflection Engine | ✅ 完成 | `intelligence/reflection.rs` |
| Phase 3 | Agent Identity | ✅ 完成 | `intelligence/identity.rs` |

### 9.2 已实现的 Tauri 命令

**Memory (Phase 1):**
- `memory_init`, `memory_store`, `memory_get`, `memory_search`
- `memory_delete`, `memory_delete_all`, `memory_stats`
- `memory_export`, `memory_import`, `memory_db_path`

**Heartbeat (Phase 2):**
- `heartbeat_init`, `heartbeat_start`, `heartbeat_stop`, `heartbeat_tick`
- `heartbeat_get_config`, `heartbeat_update_config`, `heartbeat_get_history`

**Compactor (Phase 2):**
- `compactor_estimate_tokens`, `compactor_estimate_messages_tokens`
- `compactor_check_threshold`, `compactor_compact`

**Reflection (Phase 3):**
- `reflection_init`, `reflection_record_conversation`, `reflection_should_reflect`
- `reflection_reflect`, `reflection_get_history`, `reflection_get_state`

**Identity (Phase 3):**
- `identity_get`, `identity_get_file`, `identity_build_prompt`
- `identity_update_user_profile`, `identity_append_user_profile`
- `identity_propose_change`, `identity_approve_proposal`, `identity_reject_proposal`
- `identity_get_pending_proposals`, `identity_update_file`
- `identity_get_snapshots`, `identity_restore_snapshot`
- `identity_list_agents`, `identity_delete_agent`

### 9.3 待完成工作

| 阶段 | 模块 | 状态 | 说明 |
|------|------|------|------|
| Phase 3 | Agent Swarm | 🚧 待定 | 评估是否需要迁移 |
| Phase 4 | 前端适配器 | 📋 计划中 | TypeScript 调用 Tauri 命令 |
| Phase 4 | E2E 测试 | 📋 计划中 | 验证完整数据流 |
| Phase 4 | 性能优化 | 📋 计划中 | 基准测试和优化 |