iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
62f182785f36c00c32ea084350998ce07878f765
zclaw_openfang/docs/SYSTEM_ANALYSIS.md
iven 62f182785f docs: create comprehensive system analysis report 
Replace partial alignment analysis with full SYSTEM_ANALYSIS.md containing:

- Complete deviation analysis (API 60%, UI 80%, Hands 43%, Skills 7%)
- Root cause analysis of gaps
- 5-phase evolution roadmap with clear milestones
- Technical debt inventory
- Acceptance criteria per phase

Key findings:
- Session management API completely missing (0%)
- 4/7 Hands missing TOML configurations
- Workflow editor/delete/create using placeholder alerts
- HandTaskPanel using hardcoded mock data

Updates:
- Archive README updated with clear pointer to new report
- deviation-analysis.md marked as deprecated with comparison table
- knowledge-base README updated to reference SYSTEM_ANALYSIS.md
- Removed partial openfang-alignment-analysis.md

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

14 KiB
Raw Blame History

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

分析日期: 2026-03-14 分析版本: 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 覆盖率     ████████████░░░░░░░░  60% (37/62 端点)         │
│  UI 完成度      ████████████████░░░░  80% (20/25 组件)         │
│  Hands 配置     ████░░░░░░░░░░░░░░░░  43% (3/7 有 TOML)        │
│  Skills 定义    ██░░░░░░░░░░░░░░░░░░  7% (4/60+ 潜在)          │
│                                                                 │
│  整体对齐度     ████████████████░░░░  80%                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

二、系统偏离点分析

2.1 API 层偏离

完全缺失 (0% 实现)

模块 端点数 影响 优先级
Session 管理 5 会话无法持久化，历史记录丢失 🔴 P0
OpenAI 兼容 API 3 无法作为 OpenAI 代理使用 🟡 P2

严重不足 (< 50% 实现)

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

部分实现 (50-80%)

模块 覆盖率 缺失功能 优先级
Agent 管理 75% 获取详情、启动 Agent 🟢 P1
Workflow 管理 71% 创建工作流、执行历史 🟢 P1
配置管理 60% 更新配置、热重载 🟢 P1

完全实现 (> 90%)

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

2.2 UI 层偏离

使用 Mock/Placeholder 数据的组件

组件 问题 影响 优先级
HandTaskPanel.tsx 任务历史硬编码 用户看不到真实执行历史 🔴 P0
WorkflowList.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 ✅ 完整 -
Agent 类型 ❌ 缺失 Agent, AgentConfig, AgentStatus
Session 类型 ❌ 缺失 Session, SessionMessage
Settings 类型 ❌ 缺失 Settings, QuickConfig 完整定义
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 🔴 待开始

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 内置技能

时间: 持续进行

技能类别 示例技能 优先级
开发工具 git, docker, kubernetes 高
数据处理 csv, json, yaml, excel 高
文档生成 markdown, pdf, docx 中
网络工具 http, curl, websocket 中
AI 增强 embedding, rag, memory 中

五、技术债务清单

5.1 代码层面

债务 位置 影响 清理方案
MockTask 接口 HandTaskPanel.tsx 数据不真实 移除，使用真实 API
AVAILABLE_MODELS 硬编码 ModelsAPI.tsx 模型列表不动态 从 API 获取
DEFAULT_LAYERS 全 false SecurityStatus.tsx 误导用户 等待 API 或移除默认值
alert() 占位 多个文件 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 显示真实数据

6.3 Phase 3 完成标准

  • 无 OpenClaw JSON 配置文件
  • 所有配置使用 TOML 格式
  • 无 OpenClaw 兼容层代码

七、风险与缓解

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

八、附录

A. API 覆盖率详细统计

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

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

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

文档创建: 2026-03-14 下次审查: Phase 1 完成后