62f182785f
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>
361 lines
14 KiB
Markdown
361 lines
14 KiB
Markdown
# 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 完成后*
|