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

-- 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 命令

// 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

// 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

// 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 前端适配器

// 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%（Rust 模块已有测试）
• E2E 测试全部通过
• 文档更新完成

---

八、参考资料

• Tauri Commands
• SQLite in Rust
• ZCLAW Deep Analysis

---

文档版本: 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	性能优化	📋 计划中	基准测试和优化