zclaw_openfang/plans/abstract-finding-forest.md

ZCLAW 智能层统一实现计划

Context

ZCLAW 项目存在前后端智能层代码重复问题。TypeScript 前端实现了记忆、反思、心跳、压缩等智能层功能，同时 Rust 后端也完整实现了相同功能。这导致：

1. 维护成本加倍（两份代码需同步更新）
2. 功能受限（前端 localStorage 在应用关闭后无法运行）
3. 数据不持久（localStorage 有 5MB 限制）

解决方案：删除前端 TS 智能层代码，统一使用 Rust 后端 + TypeScript 适配器 (intelligence-backend.ts)。

---

关键文件

已有的 Rust 后端（保留）

• desktop/src-tauri/src/intelligence/heartbeat.rs - 心跳引擎
• desktop/src-tauri/src/intelligence/compactor.rs - 上下文压缩
• desktop/src-tauri/src/intelligence/reflection.rs - 自我反思
• desktop/src-tauri/src/intelligence/identity.rs - 身份管理
• desktop/src-tauri/src/memory/persistent.rs - 记忆持久化
• desktop/src/lib/intelligence-backend.ts - TypeScript 适配器（已完整实现）

需要删除的 TS 实现

• desktop/src/lib/agent-memory.ts (~487行)
• desktop/src/lib/agent-identity.ts (~351行)
• desktop/src/lib/reflection-engine.ts (~678行)
• desktop/src/lib/heartbeat-engine.ts (~347行)
• desktop/src/lib/context-compactor.ts (~443行)
• desktop/src/lib/memory-index.ts (~150行)

需要修改的消费者文件

文件	使用的旧模块
desktop/src/store/chatStore.ts	memory, identity, compactor, reflection
desktop/src/store/memoryGraphStore.ts	memory
desktop/src/components/MemoryPanel.tsx	memory
desktop/src/components/ReflectionLog.tsx	reflection, identity
desktop/src/components/HeartbeatConfig.tsx	heartbeat
desktop/src/lib/memory-extractor.ts	memory, identity
desktop/src/lib/agent-swarm.ts	memory
desktop/src/lib/skill-discovery.ts	memory

---

Implementation Plan

Phase 0: 创建统一客户端（约 2h）

目标: 创建环境检测机制，支持 Tauri/浏览器双环境

新建文件: desktop/src/lib/intelligence-client.ts

实现内容:

import { intelligence } from './intelligence-backend';

// 检测是否在 Tauri 环境中
const isTauriEnv = typeof window !== 'undefined' && '__TAURI__' in window;

// 降级策略：非 Tauri 环境使用 localStorage 模拟
const fallbackMemory = {
  store: async (entry) => { /* localStorage 模拟 */ },
  search: async (options) => { /* localStorage 模拟 */ },
  // ... 其他方法
};

export const intelligenceClient = {
  memory: isTauriEnv ? intelligence.memory : fallbackMemory,
  heartbeat: isTauriEnv ? intelligence.heartbeat : fallbackHeartbeat,
  compactor: isTauriEnv ? intelligence.compactor : fallbackCompactor,
  reflection: isTauriEnv ? intelligence.reflection : fallbackReflection,
  identity: isTauriEnv ? intelligence.identity : fallbackIdentity,
};

验证:

• pnpm tsc --noEmit 编译通过
• Tauri 环境检测正确

---

Phase 1: 迁移 Memory 模块（约 4h）

优先级: 最高（其他模块都依赖 Memory）

修改文件:

1. chatStore.ts

// 修改前
import { getMemoryManager } from '../lib/agent-memory';
const memoryMgr = getMemoryManager();
const relevantMemories = await memoryMgr.search(content, { agentId, limit: 8 });

// 修改后
import { intelligenceClient } from '../lib/intelligence-client';
const relevantMemories = await intelligenceClient.memory.search({
  agent_id: agentId,
  query: content,
  limit: 8,
});

2. memoryGraphStore.ts - 替换 getMemoryManager()
3. MemoryPanel.tsx - 替换 getMemoryManager()
4. memory-extractor.ts - 替换 getMemoryManager()
5. agent-swarm.ts - 替换 getMemoryManager()
6. skill-discovery.ts - 替换 getMemoryManager()

类型适配层 (添加到 intelligence-client.ts):

function toFrontendMemory(backend: PersistentMemory): MemoryEntry {
  return {
    id: backend.id,
    agentId: backend.agent_id,
    type: backend.memory_type as MemoryType,
    tags: JSON.parse(backend.tags || '[]'),
    // ...
  };
}

验证:

• pnpm vitest run 测试通过
• 桌面端启动，发送消息，检查记忆存储
• MemoryPanel 正确显示记忆列表

---

Phase 2: 迁移 Compactor 模块（约 1h）

修改文件: chatStore.ts

// 修改前
import { getContextCompactor } from '../lib/context-compactor';
const compactor = getContextCompactor();
const check = compactor.checkThreshold(messages);

// 修改后
import { intelligenceClient } from '../lib/intelligence-client';
const check = await intelligenceClient.compactor.checkThreshold(
  messages.map(m => ({ role: m.role, content: m.content }))
);

验证:

• 发送大量消息触发 compaction
• 检查压缩后消息正常显示

---

Phase 3: 迁移 Reflection + Identity 模块（约 3h）

修改文件:

1. chatStore.ts

// 修改前
import { getReflectionEngine } from '../lib/reflection-engine';
const reflectionEngine = getReflectionEngine();
reflectionEngine.recordConversation();

// 修改后
import { intelligenceClient } from '../lib/intelligence-client';
await intelligenceClient.reflection.recordConversation();

2. ReflectionLog.tsx - 替换 ReflectionEngine 和 getAgentIdentityManager()
3. memory-extractor.ts - 替换 getAgentIdentityManager()

验证:

• 完成多轮对话后检查 reflection 触发
• ReflectionLog 组件正确显示历史
• 身份变更提案审批流程正常

---

Phase 4: 迁移 Heartbeat 模块（约 1h）

修改文件: HeartbeatConfig.tsx

// 修改前
import { HeartbeatEngine } from '../lib/heartbeat-engine';
const engine = new HeartbeatEngine(agentId, config);
engine.start();

// 修改后
import { intelligenceClient } from '../lib/intelligence-client';
await intelligenceClient.heartbeat.init(agentId, config);
await intelligenceClient.heartbeat.start(agentId);

验证:

• HeartbeatConfig 面板启用心跳
• 等待心跳触发，检查 alert 生成

---

Phase 5: 清理遗留代码（约 1h）

删除文件:

• desktop/src/lib/agent-memory.ts
• desktop/src/lib/agent-identity.ts
• desktop/src/lib/reflection-engine.ts
• desktop/src/lib/heartbeat-engine.ts
• desktop/src/lib/context-compactor.ts
• desktop/src/lib/memory-index.ts

更新文档:

• 更新 CLAUDE.md 架构说明

---

Verification

每个阶段完成后执行:

# 1. TypeScript 编译检查
pnpm tsc --noEmit

# 2. 单元测试
pnpm vitest run

# 3. 启动桌面端
pnpm tauri:dev

# 4. 功能验证
# - 发送消息，检查记忆存储
# - 触发长对话，检查压缩
# - 检查心跳和反思功能

---

Risk & Mitigation

风险	缓解措施
Tauri invoke 失败	fallback 到 localStorage
类型不匹配	类型转换层隔离差异
数据迁移	提供 localStorage → SQLite 迁移工具
回滚困难	使用 feature flag 快速切换

---

Estimated Time

阶段	时间
Phase 0: 创建客户端	2h
Phase 1: Memory 迁移	4h
Phase 2: Compactor 迁移	1h
Phase 3: Reflection+Identity	3h
Phase 4: Heartbeat 迁移	1h
Phase 5: 清理代码	1h
测试与修复	3h
总计	约 15h（2个工作日）