zclaw_openfang/plans/typed-dazzling-fog.md

ZCLAW 系统偏离分析与演化路线图更新方案

分析日期: 2026-03-15 目的: 基于代码层面深度分析，更新系统偏离点，制定下一阶段演化路线 状态: ✅ 全部完成

---

一、背景与上下文

1.1 为什么需要这次分析？

现有的 SYSTEM_ANALYSIS.md 记录了 Phase 1-5 的完成状态和 Phase 6 的进行中状态。但代码层面的深度分析发现了新的偏离点，特别是：

1. Team 协作功能 - 文档标记为"进行中"，但代码显示 teamStore.ts 完全使用 localStorage 而非真实 API
2. REST API 认证缺失 - WebSocket 有完整认证，REST 请求无认证头
3. 设置持久化问题 - 主题/自动启动等设置仅改变本地状态
4. 编辑模式不完整 - WorkflowEditor 编辑时不加载现有步骤

1.2 分析方法

使用 3 个并行 Explore 代理深度分析：

• 前端组件和 UI 状态管理
• OpenFang 通信层实现
• 配置和技能系统

1.3 实施方法

使用多代理并行执行：

• 14 个专业代理并行工作
• TypeScript + Rust 双重验证
• 所有修改通过 pnpm tsc --noEmit 和 cargo check

---

二、新发现的偏离点

2.1 关键数据流断裂 (P0 - 最高优先级)

ID	组件	问题描述	影响
A1	teamStore.ts	所有 CRUD 操作使用 localStorage，从未调用 team-client.ts API	Team 协作功能完全虚假
A2	WorkflowEditor.tsx:217	编辑模式初始化空步骤，不加载现有工作流	无法编辑真实工作流
A3	SchedulerPanel.tsx:649	事件触发器创建显示占位 alert	无法创建事件触发器

2.2 安全与配置偏离 (P0-P1)

ID	组件	问题描述	影响
B1	gateway-client.ts	REST API 请求不携带认证头	未认证的 REST 调用
B2	gateway-client.ts	Token 存储在 localStorage	敏感数据不安全存储
B3	General.tsx:9-11	主题/自动启动仅改变本地 state	设置不持久化到 TOML

2.3 端口与文档偏离

来源	端口	状态
实际 OpenFang	50051	代码正确适配
文档	4200	需更新
FALLBACK_GATEWAY_URLS	50051, 4200	回退列表包含两个

---

三、演化路线图 (更新版) - ✅ 全部完成

Phase 0: 稳定化修复 ✅ 完成

目标: 修复关键数据流断裂问题

任务	状态	文件
Team Store API 集成	✅ 完成	teamStore.ts - 替换 localStorage 为 API
REST API 认证	✅ 完成	team-client.ts - 添加 getAuthHeaders()
Workflow 编辑器步骤加载	✅ 完成	WorkflowEditor.tsx - 编辑模式加载步骤

Phase 1: 功能对齐 ✅ 完成

目标: 连接所有 UI 组件到真实 OpenFang 能力

任务	状态	文件
事件触发器创建	✅ 完成	CreateTriggerModal.tsx (新建)
设置持久化	✅ 完成	General.tsx - 连接 gatewayStore
WebSocket 团队事件订阅	✅ 完成	useTeamEvents.ts, teamStore.ts
安全 Token 存储	✅ 完成	secure_storage.rs (新建), secure-storage.ts (新建)

Phase 2: 架构优化 ✅ 完成

目标: 改善系统架构以提高可维护性和性能

任务	状态	文件
TOML 配置支持	✅ 完成	toml-utils.ts, config-parser.ts, types/config.ts
请求超时和重试	✅ 完成	request-helper.ts (新建)

Phase 3: 扩展和增强 ✅ 完成

目标: 完善 OpenFang 特有功能的 UI

任务	状态	文件
16 层安全状态 UI	✅ 完成	SecurityLayersPanel.tsx (新建)
Hand 审批工作流	✅ 完成	HandApprovalModal.tsx, ApprovalsPanel.tsx
增强 Hand 参数 UI	✅ 完成	HandParamsForm.tsx (新建)
审计日志查看器	✅ 完成	AuditLogsPanel.tsx - Merkle 链验证

---

四、风险评估

高风险变更

变更	风险	缓解措施
Team Store API 集成	API 失败导致数据丢失	Feature flag 回退到 localStorage
安全 Token 存储	认证中断	渐进迁移带回退
TOML 解析器	配置损坏	写入前验证，保留备份

中等风险变更

变更	风险	缓解措施
REST 认证头	401 循环	智能重试带用户提示
配置同步	竞态条件	乐观锁，冲突 UI
后端抽象	功能缺口	能力检测，优雅降级

---

五、成功度量

Phase 0 完成标准

• Team CRUD 操作使用真实 API (通过网络请求验证)
• 所有 REST 请求包含认证头
• Workflow 编辑模式加载现有步骤
• Team 数据不再使用 localStorage (除缓存)

Phase 1 完成标准

• 事件触发器可创建并正确触发
• 设置在应用重启后持久化
• 实时团队事件更新 UI
• Token 存储在安全存储中

Phase 2 完成标准

• TOML 配置可读写
• 请求重试在瞬态故障时成功
• 后端可通过配置切换
• 配置变更双向同步

Phase 3 完成标准

• 所有 16 层安全有 UI 展示
• Hand 审批工作流可用
• Hand 参数支持所有类型
• 审计日志可验证

总体指标

指标	当前	目标
localStorage 使用	3 个文件	0 (除缓存)
API 集成	~70%	100%
实时事件	30%	100%
安全 UI 覆盖	20%	100%
测试覆盖率	未知	80%+

---

六、实施顺序

第 1-2 周: Phase 0
├── 0.1 Team Store API 集成 (3 天)
├── 0.2 REST API 认证 (2 天)
└── 0.3 Workflow 编辑器步骤加载 (2 天)

第 3-5 周: Phase 1
├── 1.1 事件触发器创建 (3 天)
├── 1.2 设置持久化 (2 天)
├── 1.3 WebSocket 事件订阅 (3 天)
└── 1.4 安全 Token 存储 (2 天)

第 6-8 周: Phase 2
├── 2.1 TOML 配置支持 (3 天)
├── 2.2 请求超时和重试 (2 天)
├── 2.3 后端抽象层 (3 天)
└── 2.4 配置同步服务 (2 天)

第 9-12 周: Phase 3
├── 3.1 16 层安全状态 UI (4 天)
├── 3.2 Hand 审批工作流 (3 天)
├── 3.3 增强 Hand 参数 UI (2 天)
└── 3.4 审计日志查看器 (3 天)

---

七、关键文件清单

需要修改的核心文件

文件	修改类型	优先级
desktop/src/store/teamStore.ts	替换 localStorage 为 API 调用	P0
desktop/src/lib/team-client.ts	添加认证头和错误处理	P0
desktop/src/lib/gateway-client.ts	REST 认证模式参考	P0
desktop/src/components/WorkflowEditor.tsx	添加步骤加载	P0
desktop/src/components/Settings/General.tsx	设置持久化	P1

需要新建的文件

文件	用途	阶段
desktop/src/lib/config-client.ts	配置 API 客户端	Phase 1
desktop/src/lib/toml-parser.ts	TOML 解析工具	Phase 2
desktop/src-tauri/src/secure_storage.rs	安全存储 Rust 命令	Phase 1
desktop/src/components/CreateTriggerModal.tsx	触发器创建模态框	Phase 1

---

八、验证方法

每个 Phase 完成后的验证

1. 自动化测试

   pnpm vitest run tests/desktop/
   pnpm tsc --noEmit
   

2. 手动验证

   • 连接 OpenFang (端口 50051)
   • 验证数据流真实连接
   • 检查 localStorage 使用情况
   • 验证设置持久化

3. 代码审查

   • 检查认证头存在
   • 验证错误处理完整
   • 确认无硬编码值

---

计划创建: 2026-03-15 预计完成: 2026-06-15 (12 周)