iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
d60d445cbf46fa8c8c808ff054a0ea74fd2b5af3
zclaw_openfang/docs/SYSTEM_ANALYSIS.md
iven d60d445cbf feat(phase4-5): add Workflow types and expand Skills ecosystem 
Phase 4: Type System Completion (P2)
- Add comprehensive Workflow type definitions:
  - WorkflowStepType: hand, skill, agent, condition, parallel, delay
  - WorkflowStep: individual step configuration
  - Workflow: complete workflow definition
  - WorkflowRunStatus: pending, running, completed, failed, cancelled, paused
  - WorkflowRun: execution instance tracking
  - Request/Response types for API operations
  - Control types for pause/resume/cancel
- Update types/index.ts with workflow exports

Phase 5: Skills Ecosystem Expansion (P2)
- Add 5 new Skills with SKILL.md definitions:
  - git: Git version control operations
  - file-operations: File system operations
  - web-search: Web search capabilities
  - data-analysis: Data analysis and visualization
  - shell-command: Shell command execution
- Skills coverage now at 9/60+ (15%)

Documentation:
- Update SYSTEM_ANALYSIS.md Phase 4 & 5 status
- Mark Phase 4 as completed
- Update Phase 5 progress tracking

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-15 01:51:45 +08:00

16 KiB
Raw Blame History

ZCLAW 系统偏离分析与演化路线图

分析日期: 2026-03-14 (更新: 2026-03-15) 分析版本: OpenFang v0.4.0 + ZClaw Desktop v0.2.0 目的: 识别系统当前偏离点，规划后续演化方向

一、执行摘要

1.1 项目定位

ZCLAW 是基于 OpenFang (Rust Agent OS) 的 AI Agent 桌面客户端，核心价值：

  • 真实连接 OpenFang Kernel
  • 真实驱动 Agents / Skills / Hands / Workflows
  • 真实读写 TOML 配置与工作区
  • 真实反映运行时状态与审计日志

1.2 当前状态概览

┌─────────────────────────────────────────────────────────────────┐
│                    ZCLAW 系统状态仪表盘                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  API 覆盖率     ██████████████████████░░  85% (53/62 端点)       │
│  UI 完成度      ██████████████████████░░  92% (23/25 组件)       │
│  Hands 配置     ████████████████████████  100% (7/7 有 TOML)     │
│  Skills 定义    ██░░░░░░░░░░░░░░░░░░░░░  7% (4/60+ 潜在)        │
│                                                                 │
│  整体对齐度     ██████████████████████░░  95%                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

二、系统偏离点分析

2.1 API 层偏离

已完成 (100% 实现)

模块 端点数 说明 状态
Session 管理 5 完整的 CRUD + 消息加载 ✅ 已完成

待实现 (0% 实现)

模块 端点数 影响 优先级
OpenAI 兼容 API 3 无法作为 OpenAI 代理使用 🟡 P2

严重不足 (< 50% 实现)

模块 覆盖率 缺失功能 优先级
Skills 管理 20% 创建/详情/更新/删除技能 🟡 P1 ✅ 已完成
Channels 管理 33% 添加/配置/删除通道 🟡 P1 ✅ 已完成
Trigger 管理 25% 创建/详情/删除触发器 🟡 P1 ✅ 已完成

部分实现 (50-80%)

模块 覆盖率 缺失功能 优先级
Agent 管理 75% 获取详情、启动 Agent 🟢 P1
Workflow 管理 100% 创建/更新/删除/执行/历史 ✅ 已完成
配置管理 60% 更新配置、热重载 🟢 P1

完全实现 (> 90%)

模块 覆盖率 说明
Hands 管理 100% 所有 CRUD + 触发 + 审批
安全与审计 100% 审计日志、安全状态、审批
统计与健康 100% 健康检查、用量统计、工作区

2.2 UI 层偏离

使用 Mock/Placeholder 数据的组件

组件 问题 影响 优先级 状态
HandTaskPanel.tsx 任务历史硬编码 已接入真实 API 🔴 P0 ✅ 已完成
WorkflowList.tsx 编辑器/删除/新建未实现 已实现完整 CRUD 🔴 P0 ✅ 已完成
WorkflowEditor.tsx 新建工作流编辑器 可视化工作流配置 🔴 P0 ✅ 已完成
WorkflowHistory.tsx 新建历史视图 查看执行历史 🔴 P0 ✅ 已完成
SecurityStatus.tsx 默认显示全 disabled 安全状态误导用户 🟡 P1 ✅ 已完成
ModelsAPI.tsx 模型列表硬编码 无法动态切换模型 🟡 P1 ✅ 已完成
SchedulerPanel.tsx 创建任务未实现 定时任务无法配置 🟡 P1 ✅ 已完成
About.tsx 版本检查未实现 更新提醒不可用 🟢 P2
Credits.tsx 积分数据硬编码 积分系统不可用 🟢 P2

中文化完成度

状态 组件数 说明
✅ 完全中文 23 所有用户可见文本已本地化
⚠️ 部分英文 2 部分技术术语保留英文

2.3 配置层偏离

Skills 目录

技能 状态 触发词
chinese-writing ✅ 已定义 写一篇, 帮我写, 撰写
feishu-docs ✅ 已定义 飞书文档, 创建文档
code-review ✅ 已定义 审查代码, code review
translation ✅ 已定义 翻译, translate

偏离: OpenFang 内置 60+ 技能，ZClaw 仅定义 4 个。

Hands 目录

Hand TOML 配置 TypeScript 定义 状态
researcher ✅ ✅ 完整
browser ✅ ✅ 完整
lead ✅ ✅ 完整
clip ❌ ✅ 缺配置
collector ❌ ✅ 缺配置
predictor ❌ ✅ 缺配置
twitter ❌ ✅ 缺配置

偏离: 4/7 Hands 缺少 TOML 配置文件。

配置文件格式

文件 格式 用途 状态
chinese-providers.toml TOML LLM 提供商配置 ✅ OpenFang
openclaw.default.json JSON OpenClaw 遗留配置 ⚠️ 待迁移
SOUL.md / AGENTS.md Markdown Agent 人格定义 ✅
USER.md Markdown 用户偏好 ✅

偏离: 保留 OpenClaw JSON 配置，需迁移到 OpenFang TOML。

2.4 类型定义偏离

类型文件 状态 缺失类型
types/hands.ts ✅ 完整 -
types/agent.ts ✅ 完整 -
types/session.ts ✅ 完整 -
types/settings.ts ✅ 完整 -
Workflow 类型 ⚠️ 部分 WorkflowStep 详细定义

三、根因分析

3.1 为什么存在这些偏离？

┌─────────────────────────────────────────────────────────────────┐
│                      偏离根因分析                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. OpenFang API 不完整 (30%)                                   │
│     ├── /api/audit/logs 返回 404                               │
│     ├── /api/security/status 返回 404                          │
│     └── 部分端点未在 v0.4.0 实现                                │
│                                                                 │
│  2. 时间优先级 (40%)                                            │
│     ├── 核心聊天功能优先                                        │
│     ├── Hands/Workflows 基础功能已完成                          │
│     └── 高级功能（编辑器、创建器）延后                          │
│                                                                 │
│  3. 设计决策 (20%)                                              │
│     ├── 使用 Mock 数据便于 UI 开发                              │
│     ├── 保留 OpenClaw 兼容性                                    │
│     └── 逐步迁移而非一次性重写                                  │
│                                                                 │
│  4. 技术债务 (10%)                                              │
│     ├── 类型定义分散                                           │
│     ├── 配置格式混合                                           │
│     └── 部分 TODO 未清理                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

3.2 可接受的偏离 vs 需要修正的偏离

可接受的偏离（不修正）

  1. OpenAI 兼容 API 缺失 - 非核心功能，第三方集成用
  2. Credits 页面硬编码 - 依赖 OpenFang 积分系统 API
  3. About 版本检查 - 可延后实现

需要修正的偏离（必须修正）

  1. HandTaskPanel Mock 数据 - 用户看不到真实执行历史
  2. Workflow 编辑器缺失 - 核心功能不完整
  3. Session 管理缺失 - 会话无法持久化
  4. 4 个 Hands 缺 TOML 配置 - 功能定义不完整

四、演化路线图

Phase 1: 核心功能补全 (P0)

目标: 修复影响核心用户体验的偏离

时间: 1-2 周

任务 文件 状态
实现 HandTaskPanel 真实任务历史 HandTaskPanel.tsx ✅ 已完成
实现 Workflow 编辑器 WorkflowEditor.tsx (新建) ✅ 已完成
实现 Workflow 删除功能 WorkflowList.tsx ✅ 已完成
实现 Session 管理 API gatewayStore.ts ✅ 已完成
补充 4 个 Hands TOML 配置 hands/*.HAND.toml ✅ 已完成
实现 Workflow 创建/编辑 UI WorkflowEditor.tsx ✅ 已完成
实现 Workflow 历史视图 WorkflowHistory.tsx (新建) ✅ 已完成

Phase 2: 功能增强 (P1)

目标: 提升功能完整性和用户体验

时间: 2-3 周

任务 文件 状态
实现 Channels 完整 CRUD gatewayStore.ts ✅ 已完成
实现 Triggers 完整 CRUD gatewayStore.ts ✅ 已完成
实现 Skills 完整 CRUD gatewayStore.ts ✅ 已完成
动态获取模型列表 ModelsAPI.tsx ✅ 已完成
实现定时任务创建 SchedulerPanel.tsx ✅ 已完成
SecurityStatus 真实数据 SecurityStatus.tsx ✅ 已完成

Phase 3: 配置迁移 (P1)

目标: 完成从 OpenClaw 到 OpenFang 的配置迁移

时间: 1 周

任务 说明 状态
迁移 openclaw.default.json 转换为 config.toml ✅ 已完成
补充主 config.toml OpenFang 服务器配置 ✅ 已完成
清理 OpenClaw 遗留代码 移除兼容层 🔴 待开始

Phase 4: 类型系统完善 (P2)

目标: 建立完整的 TypeScript 类型定义

时间: 1 周

任务 文件 状态
Agent 类型定义 types/agent.ts ✅ 已完成
Session 类型定义 types/session.ts ✅ 已完成
Settings 类型定义 types/settings.ts ✅ 已完成
Workflow 详细类型 types/workflow.ts ✅ 已完成

Phase 5: Skills 生态扩展 (P2)

目标: 扩展 Skills 目录，对标 OpenFang 内置技能

时间: 持续进行

技能 触发词 状态
chinese-writing 写一篇, 帮我写, 撰写 ✅ 已定义
feishu-docs 飞书文档, 创建文档 ✅ 已定义
code-review 审查代码, code review ✅ 已定义
translation 翻译, translate ✅ 已定义
git git, 提交, commit, push, pull ✅ 已定义
file-operations 读取文件, 写入文件, 创建文件 ✅ 已定义
web-search 搜索, 查找, web search ✅ 已定义
data-analysis 分析数据, 统计, 图表 ✅ 已定义
shell-command 执行命令, 运行, shell ✅ 已定义

当前 Skills 覆盖: 9/60+ 潜在 (15%)

五、技术债务清单

5.1 代码层面

债务 位置 影响 清理方案 状态
MockTask 接口 HandTaskPanel.tsx 数据不真实 移除，使用真实 API ✅ 已清理
AVAILABLE_MODELS 硬编码 ModelsAPI.tsx 模型列表不动态 从 API 获取 ✅ 已清理
DEFAULT_LAYERS 全 false SecurityStatus.tsx 误导用户 等待 API 或移除默认值 ✅ 已清理
alert() 占位 SchedulerPanel.tsx UX 差 实现真实功能或 Toast 提示 ✅ 已清理

5.2 配置层面

债务 位置 影响 清理方案 状态
OpenClaw JSON 配置 config/openclaw.default.json 配置格式混合 迁移到 TOML ✅ 已清理
缺少主配置文件 config/ OpenFang 配置不完整 创建 config.toml ✅ 已清理

5.3 类型层面

债务 影响 清理方案
类型定义分散 维护困难 集中到 types/ 目录
部分 any 类型 类型安全差 补充具体类型
缺少 API 响应类型 API 调用不安全 定义 Response 类型

六、验收标准

6.1 Phase 1 完成标准

  • HandTaskPanel 显示真实任务历史（无 MockTask）
  • Workflow 可创建、编辑、删除
  • Session 可持久化，刷新后历史保留
  • 7 个 Hands 全部有 TOML 配置

6.2 Phase 2 完成标准

  • Channels 可完整 CRUD
  • Triggers 可完整 CRUD
  • Skills 可完整 CRUD
  • 模型列表从 API 动态获取
  • SecurityStatus 显示真实数据
  • SchedulerPanel 可创建定时任务

6.3 Phase 3 完成标准

  • 创建 OpenFang config.toml
  • 迁移 OpenClaw JSON 配置到 TOML
  • 无 OpenClaw JSON 配置文件 (保留 openclaw.default.json 作为参考)
  • 无 OpenClaw 兼容层代码

6.4 Phase 4 完成标准

  • Agent 类型定义完整
  • Session 类型定义完整
  • Settings 类型定义完整
  • Workflow 详细类型定义

七、风险与缓解

风险 概率 影响 缓解措施
OpenFang API 变更 中 高 版本锁定，变更日志跟踪
Session API 未实现 高 高 使用 localStorage 临时方案
安全层 API 未实现 高 中 UI 显示"等待 API"状态
工作流编辑器复杂度高 中 中 先实现简化版，逐步增强

八、附录

A. API 覆盖率详细统计

类别 端点数 已实现 覆盖率
Agent 管理 8 6 75%
Session 管理 5 5 100%
Skills 管理 5 5 100%
Hands 管理 8 8 100%
Channels 管理 6 6 100%
Workflow 管理 7 7 100%
Trigger 管理 4 4 100%
配置管理 5 3 60%
安全与审计 5 5 100%
统计与健康 6 6 100%
OpenAI 兼容 3 0 0%
总计 62 55 89%

B. UI 组件完成度详细统计

类别 组件数 完全实现 部分实现 未实现
核心功能 5 5 0 0
OpenFang 特有 10 6 4 0
设置页面 10 6 2 2
总计 25 17 6 2

文档创建: 2026-03-14 最后更新: 2026-03-15 Phase 1 & 2 已完成 Phase 3 进行中 (2/3) Phase 4 已完成 Phase 5 进行中 (9/60+ Skills) 下次审查: Phase 3 完成后