iven/zclaw_openfang

Fork 0

Files

iven 2e5f63be32

CI / Lint & TypeCheck (push) Has been cancelled

Details

CI / Unit Tests (push) Has been cancelled

Details

CI / Build Frontend (push) Has been cancelled

Details

CI / Rust Check (push) Has been cancelled

Details

CI / Security Scan (push) Has been cancelled

Details

CI / E2E Tests (push) Has been cancelled

Details

docs: reorganize docs — archive outdated, create brainstorming folder

- 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

2026-04-07 09:54:30 +08:00

22 KiB

Raw Blame History

ZCLAW 系统全面代码分析与演化路线图

上下文 (Context)

目的: 对 ZCLAW 系统进行全面的代码层面现状分析，识别偏离点、潜在风险，制定分阶段演化路线图。

当前状态:

ZCLAW v0.4.0 + ZClaw Desktop v0.2.0
API 覆盖率: 93% (63/68 端点)
UI 完成度: 100% (30/30 组件)
Skills 定义: 68 个已完成
Phase 1-8 已完成

技术栈:

React 19.1.0 + TypeScript 5.8.3
Tauri 2.x (Rust 后端)
Zustand 5.0.11 (状态管理)
Vite 7.0.4 + Tailwind CSS 4.2.1

一、代码结构分析

1.1 项目结构

ZClaw_zclaw/
├── desktop/              # Tauri 桌面应用 (主要代码)
│   ├── src/
│   │   ├── components/   # React UI (46 组件)
│   │   ├── store/        # Zustand stores (3 个)
│   │   ├── lib/          # API 客户端和工具
│   │   ├── types/        # TypeScript 类型定义
│   │   └── App.tsx       # 主应用组件
│   └── src-tauri/        # Rust 后端
├── skills/               # 68 个 SKILL.md 定义
├── hands/                # 7 个 HAND.toml 配置
├── config/               # ZCLAW TOML 配置
├── tests/                # Vitest 测试
└── docs/                 # 文档

1.2 核心数据流

React UI → Zustand Store → GatewayClient → ZCLAW Kernel (端口 50051)
                         ↓
              WebSocket (ws://127.0.0.1:50051/ws)
              REST API (http://127.0.0.1:50051/api/*)

二、架构问题分析

2.1 Store 层问题 (高优先级)

问题	位置	影响
gatewayStore 巨型化	`store/gatewayStore.ts`	50+ 字段、40+ actions 在单一 store
持久化策略不一致	所有 stores	chatStore 用 Zustand persist，teamStore 手动 localStorage
Agent/Clone ID 混淆	`chatStore.ts`	前端 `clone_` 前缀与后端 ID 不一致

2.2 安全问题 (关键)

问题	位置	严重程度
Token 存储在 localStorage	`gateway-client.ts:103`	HIGH
Ed25519 密钥无加密	`gateway-client.ts:157-188`	HIGH
JSON.parse 无保护	`HandParamsForm.tsx:409`, `WorkflowEditor.tsx:167`	HIGH
默认使用 ws://	`gateway-client.ts:20-22`	MEDIUM

2.3 代码质量问题

问题	数量	主要位置
`any` 类型滥用	60+ 处	`gatewayStore.ts` (~35), `gateway-client.ts` (~12)
错误处理不完整	多处	部分 catch 块静默忽略错误
测试覆盖不足	-	`gateway-client.ts`, `toml-utils.ts` 无测试
代码重复	30+ 处	错误处理模式重复

2.4 性能问题

问题	位置	影响
消息数组频繁 map	`chatStore.ts`	长对话性能下降
无消息分页	`chatStore.ts`	内存持续增长
无 WebSocket 批处理	`gateway-client.ts`	高频消息处理效率低

三、分阶段演化路线图

Phase 9: 安全加固 (1 周) - 3 代理并行

目标: 修复关键安全漏洞

并行执行架构

┌─────────────────────────────────────────────────────────────┐
│ Agent A: JSON 安全          │ Agent B: Token 迁移           │
│ ├── lib/json-utils.ts       │ ├── gateway-client.ts        │
│ ├── HandParamsForm.tsx      │ ├── gatewayStore.ts          │
│ └── WorkflowEditor.tsx      │ └── 迁移工具                  │
├─────────────────────────────┼───────────────────────────────┤
│ Agent C: 加密增强            │ 完成后合并 → 文档更新 → 推送  │
│ ├── secure-storage.ts       │ ├── docs/SYSTEM_ANALYSIS.md  │
│ ├── secure_storage.rs       │ ├── PROGRESS.md              │
│ └── WSS 配置                │ └── git commit + push        │
└─────────────────────────────┴───────────────────────────────┘

任务	文件	工作量	代理
创建 `safeJsonParse<T>()`	`lib/json-utils.ts`	4h	A
替换不安全 JSON.parse	`HandParamsForm.tsx`, `WorkflowEditor.tsx`	3h	A
Token 迁移到 secure-storage	`gateway-client.ts`, `gatewayStore.ts`	6h	B
Ed25519 密钥加密	`secure-storage.ts`, `secure_storage.rs`	4h	C
添加 WSS 配置	`gateway-client.ts`	2h	C

完成后同步:

# 1. 更新文档
git add docs/SYSTEM_ANALYSIS.md PROGRESS.md
git commit -m "docs: update Phase 9 security hardening progress"
git push origin main

# 2. 代码提交
git add . && git commit -m "security(phase-9): complete security hardening

- Add safeJsonParse utility with schema validation
- Migrate tokens to OS keyring storage
- Add Ed25519 key encryption at rest
- Enable WSS configuration option

Co-Authored-By: Claude <noreply@anthropic.com>"
git push origin main

验收标准:

所有 JSON.parse 有 try-catch 保护
Token 存储在 OS keyring
TypeScript 编译通过
现有测试通过
文档已更新并推送

Phase 10: 类型安全强化 (1 周) - 3 代理并行

目标: 减少 any 使用，提升类型安全

并行执行架构

┌─────────────────────────────────────────────────────────────┐
│ Agent A: API 类型            │ Agent B: Store 类型           │
│ ├── types/api-responses.ts   │ ├── store/gatewayStore.ts    │
│ ├── types/errors.ts          │ └── 35 处 any 替换           │
│ └── 所有 API 响应类型化      │                               │
├─────────────────────────────┼───────────────────────────────┤
│ Agent C: Client 类型         │ 完成后 → 统计 any 减少 → 推送 │
│ ├── lib/gateway-client.ts    │ grep -r ": any" | wc -l      │
│ └── 12 处 any 替换           │ git commit + push            │
└─────────────────────────────┴───────────────────────────────┘

任务	文件	工作量	代理
创建 API 响应类型	`types/api-responses.ts`	4h	A
创建错误类型层级	`types/errors.ts`	2h	A
替换 gatewayStore any	`store/gatewayStore.ts` (35处)	8h	B
替换 gateway-client any	`lib/gateway-client.ts` (12处)	4h	C

完成后同步:

# 统计并提交
echo "## Phase 10 类型安全 (完成)" >> docs/SYSTEM_ANALYSIS.md
git add . && git commit -m "refactor(phase-10): reduce any usage by 50%" && git push

验收标准:

any 使用减少 50% (从 60+ 降到 30)
所有 API 响应有类型定义
TypeScript strict mode 通过
文档已更新并推送

Phase 11: Store 重构 (2 周) - 分步并行

目标: 分解巨型 gatewayStore (1500+ 行)

目标架构:

gatewayStore (协调器, <100 行)
├── connectionStore (WebSocket, 认证, ~200 行)
├── agentStore (分身, 配置文件, ~200 行)
├── handStore (Hands, 触发器, ~200 行)
├── workflowStore (工作流, 执行历史, ~200 行)
└── configStore (设置, 工作区, ~200 行)

分步并行执行

Step 1 (阻塞): 创建所有 store 接口定义 (1 天)
           ↓
Step 2 (并行): 同时提取 connectionStore, agentStore, handStore (3 天)
           ↓
Step 3 (并行): 同时提取 workflowStore, configStore (2 天)
           ↓
Step 4 (阻塞): 创建协调层 + 更新组件导入 (3 天)
           ↓
Step 5 (同步): 测试 + 文档更新 + 推送 (1 天)

任务	工作量	执行方式
创建 store 接口定义	1 天	阻塞
提取 connectionStore	3 天	并行 A
提取 agentStore	3 天	并行 B
提取 handStore	3 天	并行 C
提取 workflowStore	2 天	并行 A
提取 configStore	2 天	并行 B
创建协调层 + 组件更新	3 天	阻塞

完成后同步:

git add . && git commit -m "refactor(phase-11): decompose gatewayStore

- Extract connectionStore (WebSocket, auth)
- Extract agentStore (clones, profiles)
- Extract handStore (hands, triggers)
- Extract workflowStore (workflows, runs)
- Extract configStore (settings, workspace)
- Add coordinator layer

Each store now < 300 lines with clear separation of concerns.

Co-Authored-By: Claude <noreply@anthropic.com>"
git push origin main

验收标准:

每个 store < 300 行
清晰的关注点分离
所有组件正常工作
文档已更新并推送

Phase 12: 性能优化 (1 周) - 2 代理并行

目标: 优化消息处理和渲染

并行执行架构

┌─────────────────────────────────────────────────────────────┐
│ Agent A: 消息渲染优化         │ Agent B: WebSocket 优化       │
│ ├── ChatArea.tsx 虚拟化      │ ├── gateway-client.ts        │
│ ├── chatStore.ts 分页        │ ├── 消息批处理               │
│ └── lib/message-cache.ts     │ └── 节流/防抖                │
└─────────────────────────────┴───────────────────────────────┘

任务	文件	工作量	代理
实现消息虚拟化	`ChatArea.tsx`	8h	A
添加消息分页	`chatStore.ts`	6h	A
实现 LRU 消息缓存	`lib/message-cache.ts`	4h	A
WebSocket 消息批处理	`gateway-client.ts`	4h	B

完成后同步:

git add . && git commit -m "perf(phase-12): optimize message handling

- Add message virtualization for long conversations
- Implement message pagination in chatStore
- Add LRU cache for rendered messages
- Add WebSocket message batching

Handles 10k+ messages without performance degradation.

Co-Authored-By: Claude <noreply@anthropic.com>"
git push origin main

验收标准:

支持 10,000+ 消息无性能下降
内存使用保持稳定
滚动流畅
文档已更新并推送

Phase 13: 测试覆盖 (1 周) - 3 代理并行

目标: 建立完整测试体系，达到 80% 覆盖率

并行执行架构

┌─────────────────────────────────────────────────────────────┐
│ Agent A: 核心模块测试         │ Agent B: 工具模块测试         │
│ ├── gateway-client.test.ts   │ ├── secure-storage.test.ts   │
│ ├── 连接生命周期测试          │ ├── toml-utils.test.ts       │
│ └── 消息帧解析测试            │ └── json-utils.test.ts       │
├─────────────────────────────┼───────────────────────────────┤
│ Agent C: 集成测试            │ 完成后 → 覆盖率报告 → 推送    │
│ ├── chat-flow.test.ts        │ pnpm vitest --coverage      │
│ └── React 组件测试           │ git commit + push           │
└─────────────────────────────┴───────────────────────────────┘

任务	文件	工作量	代理
gateway-client 单元测试	`tests/desktop/gateway-client.test.ts`	6h	A
secure-storage 单元测试	`tests/desktop/secure-storage.test.ts`	2h	B
toml-utils 单元测试	`tests/desktop/toml-utils.test.ts`	2h	B
json-utils 单元测试	`tests/desktop/json-utils.test.ts`	2h	B
聊天流程集成测试	`tests/desktop/integration/chat-flow.test.ts`	4h	C
React 组件测试	`tests/desktop/components/`	8h	C

完成后同步:

# 生成覆盖率报告
pnpm vitest run --coverage

git add . && git commit -m "test(phase-13): achieve 80% test coverage

- Add gateway-client unit tests
- Add secure-storage, toml-utils, json-utils tests
- Add chat flow integration tests
- Add React component tests

Coverage: 80%+ for core modules.

Co-Authored-By: Claude <noreply@anthropic.com>"
git push origin main

验收标准:

核心模块测试覆盖率 > 80%
关键用户流程有集成测试
CI/CD 流水线通过
文档已更新并推送

四、关键文件清单

需要修改的文件

优先级	文件路径	修改类型
P0	`desktop/src/lib/gateway-client.ts`	安全修复, 类型安全
P0	`desktop/src/store/gatewayStore.ts`	重构分解, 类型安全
P0	`desktop/src/components/HandParamsForm.tsx`	JSON 解析安全
P0	`desktop/src/components/WorkflowEditor.tsx`	JSON 解析安全
P1	`desktop/src/store/chatStore.ts`	性能优化
P1	`desktop/src/lib/secure-storage.ts`	密钥加密
P1	`desktop/src-tauri/src/secure_storage.rs`	Rust 安全存储

需要创建的文件

文件路径	用途
`desktop/src/lib/json-utils.ts`	安全 JSON 解析
`desktop/src/types/api-responses.ts`	API 响应类型
`desktop/src/types/errors.ts`	错误类型定义
`desktop/src/lib/message-cache.ts`	消息 LRU 缓存
`desktop/src/store/connectionStore.ts`	连接状态管理
`desktop/src/store/agentStore.ts`	Agent 管理
`desktop/src/store/handStore.ts`	Hand 管理
`desktop/src/store/workflowStore.ts`	工作流管理
`tests/desktop/gateway-client.test.ts`	客户端测试

五、多代理并行执行策略

5.1 并行执行原则

核心原则: 独立任务并行执行，依赖任务顺序执行

┌─────────────────────────────────────────────────────────────────┐
│                    多代理并行执行架构                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Phase 9 (安全修复) - 并行执行:                                   │
│  ├── Agent A: JSON 安全包装 + 输入验证                           │
│  ├── Agent B: Token 迁移到 secure-storage                       │
│  └── Agent C: WSS 配置 + 密钥加密                                │
│                                                                 │
│  Phase 10 (类型安全) - 并行执行:                                  │
│  ├── Agent A: API 响应类型定义                                   │
│  ├── Agent B: gatewayStore any 替换                             │
│  └── Agent C: gateway-client any 替换                           │
│                                                                 │
│  Phase 11 (Store 重构) - 顺序执行 + 并行提取:                     │
│  ├── Step 1: 创建接口定义 (阻塞)                                 │
│  ├── Step 2: 并行提取 connectionStore, agentStore, handStore    │
│  ├── Step 3: 并行提取 workflowStore, configStore                │
│  └── Step 4: 协调层 + 组件更新                                   │
│                                                                 │
│  Phase 12-13 (性能+测试) - 并行执行:                              │
│  ├── Agent A: 消息虚拟化 + 分页                                  │
│  ├── Agent B: WebSocket 批处理优化                               │
│  └── Agent C: 测试编写 (与 A/B 同步)                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5.2 代理分工

代理类型	职责	适用阶段
Security Engineer	安全修复、加密、Token 迁移	Phase 9
Senior Developer	类型定义、Store 重构	Phase 10-11
Frontend Developer	UI 组件、性能优化	Phase 12
Test Engineer	单元测试、集成测试	Phase 13
Documentation Writer	文档更新、CHANGELOG	所有阶段

5.3 每阶段完成后的同步动作

# 每个阶段完成后必须执行:

# 1. 更新相关文档
# - docs/SYSTEM_ANALYSIS.md (添加 Phase 进度)
# - docs/DEVELOPMENT.md (如有新开发指南)
# - PROGRESS.md (进度追踪)

# 2. 提交到仓库
git add .
git commit -m "feat(phase-N): 完成阶段任务描述

- 具体改动 1
- 具体改动 2

Co-Authored-By: Claude <noreply@anthropic.com>"

# 3. 推送到远程
git push origin main

5.4 文档更新检查清单

每个阶段完成后必须更新:

docs/SYSTEM_ANALYSIS.md - 添加 Phase 完成记录
PROGRESS.md - 更新进度百分比
CLAUDE.md - 如有新的开发规范
README.md - 如有新功能或依赖变更

六、资源需求 (多代理优化后)

时间估算对比

阶段	串行执行	3代理并行	节省
Phase 9 (安全)	2 周	1 周	50%
Phase 10 (类型)	2 周	1 周	50%
Phase 11 (Store重构)	3 周	2 周	33%
Phase 12 (性能)	2 周	1 周	50%
Phase 13 (测试)	2 周	1 周	50%
总计	11 周	6 周	45%

代理配置

阶段	所需代理	技能要求
Phase 9	3 并行	Security Engineer, Backend Dev, Rust Dev
Phase 10	3 并行	TypeScript Expert, Frontend Dev
Phase 11	3 并行 → 顺序	Senior Developer, State Management Expert
Phase 12	2 并行	Frontend Dev, Performance Engineer
Phase 13	3 并行	Test Engineer, Integration Specialist

技能矩阵

技能	Phase 9	Phase 10	Phase 11	Phase 12	Phase 13
TypeScript	高	高	高	高	高
React	中	中	高	高	中
Tauri/Rust	高	低	低	低	低
WebSocket	高	中	中	高	中
状态管理	中	中	高	高	中
安全	高	中	中	低	中
测试	中	中	高	中	高

七、风险评估

风险	概率	影响	缓解措施
Store 重构破坏现有功能	中	高	重构前完善测试覆盖
持久化迁移丢失数据	低	严重	迁移工具, 回滚能力
ID 标准化破坏 API 通信	中	高	集成测试验证
性能优化引入新 bug	中	中	渐进式发布, 功能开关

七、成功指标

Phase 9-10 指标

零安全漏洞 (静态分析)
any 使用减少 50%
所有 Token 在安全存储中

Phase 11 指标

所有 store < 300 行
清晰的关注点分离
持久化策略一致

Phase 12-13 指标

10k+ 消息无性能下降
UI 响应时间 < 100ms
测试覆盖率 > 80%

八、验证计划

自动化验证

# TypeScript 类型检查
pnpm tsc --noEmit

# 单元测试
pnpm vitest run

# 安全审计
pnpm audit

手动验证

连接 ZCLAW (端口 50051)
发送消息并验证流式返回
触发 Hand 并验证执行
保存配置并验证持久化
测试长对话性能 (>1000 消息)

九、执行时间表 (6 周计划)

周次    Phase      任务                        代理数    交付物
─────────────────────────────────────────────────────────────────
W1      Phase 9    安全加固                    3 并行    安全修复完成 + 文档
W2      Phase 10   类型安全强化                3 并行    类型定义 + any 减少 50%
W3-4    Phase 11   Store 重构                  3 → 顺序  5 个子 Store + 协调层
W5      Phase 12   性能优化                    2 并行    消息虚拟化 + 批处理
W6      Phase 13   测试覆盖                    3 并行    80% 覆盖率 + CI 通过
─────────────────────────────────────────────────────────────────
        完成       全部 Phase 9-13                        文档更新 + 推送

计划创建: 2026-03-15 多代理并行执行: 3 代理同时工作 预计完成: 6 周 (从 11 周优化 45%) 每阶段完成后: 文档更新 + Git 推送

22 KiB Raw Blame History Unescape Escape

ZCLAW 系统全面代码分析与演化路线图

上下文 (Context)

一、代码结构分析

1.1 项目结构

1.2 核心数据流

二、架构问题分析

2.1 Store 层问题 (高优先级)

2.2 安全问题 (关键)

2.3 代码质量问题

2.4 性能问题

三、分阶段演化路线图

Phase 9: 安全加固 (1 周) - 3 代理并行

并行执行架构

Phase 10: 类型安全强化 (1 周) - 3 代理并行

并行执行架构

Phase 11: Store 重构 (2 周) - 分步并行

分步并行执行

Phase 12: 性能优化 (1 周) - 2 代理并行

并行执行架构

Phase 13: 测试覆盖 (1 周) - 3 代理并行

并行执行架构

四、关键文件清单

需要修改的文件

需要创建的文件

五、多代理并行执行策略

5.1 并行执行原则

5.2 代理分工

5.3 每阶段完成后的同步动作

5.4 文档更新检查清单

六、资源需求 (多代理优化后)

时间估算对比

代理配置

技能矩阵

七、风险评估

七、成功指标

Phase 9-10 指标

Phase 11 指标

Phase 12-13 指标

八、验证计划

自动化验证

手动验证

九、执行时间表 (6 周计划)

22 KiB

Raw Blame History