# 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。

**待迁移组件清单**：

```bash
# 查找所有使用 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
# ... 更多组件
```

**迁移策略**：

```typescript
// 旧方式（兼容层，不推荐）
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 的几乎所有状态。

```typescript
// 当前实现（有问题）
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 文件。

```typescript
// 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 迁移。