zclaw_openfang/docs/archive/old-analysis/CODE-LEVEL-TODO.md

ZCLAW 代码层面未完成工作分析

分析日期：2026-03-20 基于 git diff 和代码审查

一、当前重构状态

1.1 已完成的重构

模块	原始状态	当前状态	说明
gatewayStore.ts	1800+ 行巨型文件	~100 行 facade	已拆分为 7 个 domain stores
gateway-client.ts	65KB 单文件	模块化	拆分为 5 个文件
viking-*.ts	5 个文件	已删除	移至 docs/archive/
vector-memory.ts	385 行	已删除	功能移至 Rust 后端
context-builder.ts	409 行	已删除	功能移至 Rust 后端
session-persistence.ts	655 行	已删除	功能移至 Rust 后端

1.2 新增文件（未提交）

desktop/src/lib/gateway-api.ts      - REST API 方法实现
desktop/src/lib/gateway-auth.ts     - Ed25519 设备认证
desktop/src/lib/gateway-storage.ts  - URL/token 持久化
desktop/src/lib/gateway-types.ts    - 协议类型定义
desktop/src/store/securityStore.ts  - 安全状态管理
desktop/src/store/sessionStore.ts   - 会话状态管理

---

二、代码层面待完成工作

2.1 🔴 高优先级：Store 迁移

问题：App.tsx 和 34+ 个组件仍使用 useGatewayStore (兼容层)，而非新的 domain-specific stores。

待迁移组件清单：

# 查找所有使用 useGatewayStore 的文件
desktop/src/App.tsx                    # 核心入口
desktop/src/components/ChatArea.tsx
desktop/src/components/Sidebar.tsx
desktop/src/components/RightPanel.tsx
desktop/src/components/HandsPanel.tsx
desktop/src/components/HandApprovalModal.tsx
# ... 更多组件

迁移策略：

// 旧方式（兼容层，不推荐）
const { hands, triggers, approvals } = useGatewayStore();

// 新方式（推荐，按需导入）
import { useHandStore } from './store/handStore';
const { hands, triggers, approvals } = useHandStore();

收益：

• 减少 re-render（当前 useCompositeStore 订阅 40+ 状态）
• 更清晰的依赖关系
• 更好的代码分割

---

2.2 🔴 高优先级：useCompositeStore 性能优化

问题：store/index.ts 中的 useCompositeStore 订阅了所有 store 的几乎所有状态。

// 当前实现（有问题）
export function useCompositeStore() {
  // 订阅了 40+ 个状态
  const connectionState = useConnectionStore((s) => s.connectionState);
  const gatewayVersion = useConnectionStore((s) => s.gatewayVersion);
  // ... 40+ 个订阅
}

建议：

1. 废弃 useCompositeStore
2. 组件直接使用 domain-specific stores
3. 仅在确实需要跨域状态的场景使用 selector 模式

---

2.3 🟡 中优先级：测试文件更新

已删除测试文件：

tests/desktop/session-persistence.test.ts  (424 行)
tests/desktop/vector-memory.test.ts        (299 行)
tests/desktop/viking-adapter.test.ts       (446 行)

需更新测试文件：

tests/desktop/gatewayStore.test.ts         (190 行需更新)
tests/desktop/swarm-skills.test.ts         (6 行需更新)

缺失测试：

• securityStore.test.ts - 新 store 无测试
• sessionStore.test.ts - 新 store 无测试
• gateway-api.test.ts - 新模块无测试
• gateway-auth.test.ts - 新模块无测试

---

2.4 🟡 中优先级：类型定义清理

问题：gatewayStore.ts 仍定义了一些类型，这些应该移到各自的 store 或 types 文件。

// gatewayStore.ts 中定义的类型（应迁移）
export interface HandRunStore { ... }
export interface ScheduledJob { ... }
export interface EventTrigger { ... }
export interface RunHistoryEntry { ... }

建议：

1. HandRunStore → handStore.ts
2. ScheduledJob, EventTrigger, RunHistoryEntry → 新建 types/automation.ts

---

2.5 🟢 低优先级：组件集成度提升

存在但集成度低的组件：

组件	文件	问题
HeartbeatConfig	components/Settings/HeartbeatConfig.tsx	未在 Settings 页面使用
CreateTriggerModal	components/Automation/CreateTriggerModal.tsx	未在 Automation 面板集成
PersonalitySelector	components/Agent/PersonalitySelector.tsx	未在 Agent 创建流程使用
ScenarioTags	components/Agent/ScenarioTags.tsx	未在 Agent 编辑使用
DevQALoop	components/Dev/DevQALoop.tsx	开发调试组件，未集成

---

2.6 🟢 低优先级：文档与代码同步

文档声称完成但代码未验证：

功能	文档状态	代码状态
身份演化	✅ 完成	❓ 未验证与后端集成
上下文压缩	✅ 完成	❓ 未验证触发条件
心跳巡检	✅ 完成	❓ 未验证实际执行
记忆持久化	✅ 完成	❓ 依赖 localStorage

---

三、Tauri Rust 后端状态

3.1 已实现的 Rust 模块

模块	文件	功能	状态
ZCLAW 集成	lib.rs	Gateway 生命周期管理	✅ 完整
Viking Server	viking_server.rs	本地向量数据库	✅ 完整
Viking Commands	viking_commands.rs	Viking CLI 封装	✅ 完整
Browser Automation	browser/*.rs	Fantoccini 浏览器控制	✅ 完整
Memory Extraction	memory/*.rs	记忆提取、上下文构建	✅ 完整
LLM Integration	llm/mod.rs	LLM 调用封装	✅ 完整
Secure Storage	secure_storage.rs	OS keyring/keychain	✅ 完整

3.2 Rust 后端与前端对齐问题

问题：前端 lib/ 下有大量智能逻辑（记忆、反思、心跳），与 Rust 后端功能重叠。

前端文件	Rust 对应	建议
agent-memory.ts	memory/extractor.rs	统一到 Rust 端
context-compactor.ts	memory/context_builder.rs	统一到 Rust 端
heartbeat-engine.ts	无	迁移到 Rust 端
reflection-engine.ts	无	迁移到 Rust 端
agent-identity.ts	无	迁移到 Rust 端

收益：

• 后端持久运行（关闭浏览器不中断）
• 多端共享 Agent 状态
• 更可靠的数据持久化

---

四、技术债务清单

4.1 代码质量

问题	位置	严重度
使用 any 类型	多处	中
空 catch 块	sessionStore.ts:119	低
硬编码字符串	多处	低
重复的类型定义	gatewayStore.ts vs 各 store	中

4.2 架构问题

问题	说明	建议
前端承担后端职责	记忆/反思/心跳在前端	迁移到 Rust
Store 过度订阅	useCompositeStore 订阅 40+ 状态	按需订阅
兼容层膨胀	gatewayStore.ts 作为 facade	逐步移除

---

五、行动建议

本周必做

1. 提交当前重构 - gateway-client 模块化、store 拆分已完成
2. 更新测试 - 为新 store 和 gateway 模块添加测试
3. 迁移 App.tsx - 从 useGatewayStore 迁移到 domain stores

两周内

1. 移除 useCompositeStore - 组件直接使用 domain stores
2. 清理类型定义 - 统一到各自的 store 或 types 文件
3. 集成低使用率组件 - HeartbeatConfig, CreateTriggerModal 等

一个月内

1. 前端智能层迁移 - 将记忆/反思/心跳迁移到 Rust 后端
2. 端到端测试 - Playwright + Tauri driver 验证核心流程
3. 性能优化 - 减少不必要的 re-render

---

六、代码变更统计

当前未提交变更：
 21 files changed, 578 insertions(+), 7324 deletions(-)

删除的文件（已归档）：
 - desktop/src/lib/context-builder.ts       (409 行)
 - desktop/src/lib/session-persistence.ts   (655 行)
 - desktop/src/lib/vector-memory.ts         (385 行)
 - desktop/src/lib/viking-adapter.ts        (734 行)
 - desktop/src/lib/viking-client.ts         (353 行)
 - desktop/src/lib/viking-local.ts          (144 行)
 - desktop/src/lib/viking-memory-adapter.ts (408 行)
 - desktop/src/lib/viking-server-manager.ts (231 行)

新增的文件：
 + desktop/src/lib/gateway-api.ts           (新建)
 + desktop/src/lib/gateway-auth.ts          (新建)
 + desktop/src/lib/gateway-storage.ts       (新建)
 + desktop/src/lib/gateway-types.ts         (新建)
 + desktop/src/store/securityStore.ts       (新建)
 + desktop/src/store/sessionStore.ts        (新建)

---

七、总结

重构进度：约 70% 完成

• ✅ Store 拆分完成
• ✅ Gateway Client 模块化完成
• ✅ Viking 相关代码清理完成
• ⏳ 组件迁移进行中（仍使用兼容层）
• ⏳ 测试更新待完成
• ❌ 前端智能层迁移未开始

最大风险：

1. useCompositeStore 性能问题（40+ 状态订阅）
2. 前端智能逻辑（记忆/反思）依赖 localStorage，不可靠
3. 缺少端到端测试验证

建议策略： 先完成当前重构（提交、测试、组件迁移），再启动前端智能层向 Rust 迁移。