2e5f63be32
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7) - Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/ - Archive superseded analysis docs to docs/archive/old-analysis/ - Archive completed session plans to docs/archive/old-plans/ - Archive old test reports/validations to respective archive folders - Remove empty directories left after moves - Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
278 lines
8.8 KiB
Markdown
278 lines
8.8 KiB
Markdown
# 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 迁移。
|