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

**分析日期**: 2026-03-14 (更新: 2026-03-15)
**分析版本**: OpenFang v0.4.0 + ZClaw Desktop v0.2.0
**目的**: 识别系统当前偏离点，规划后续演化方向
**Skills 集成**: ✅ agency-agents 仓库迁移完成！

---

## 一、执行摘要

### 1.1 项目定位

ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核心价值：
- 真实连接 OpenFang Kernel
- 真实驱动 Agents / Skills / Hands / Workflows
- 真实读写 TOML 配置与工作区
- 真实反映运行时状态与审计日志

### 1.2 当前状态概览

```
┌─────────────────────────────────────────────────────────────────┐
│                    ZCLAW 系统状态仪表盘                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  API 覆盖率     ██████████████████████░░  89% (55/62 端点)       │
│  UI 完成度      ███████████████████████░  92% (23/25 组件)       │
│  Hands 配置     ████████████████████████  100% (7/7 有 TOML)     │
│  Skills 定义    ████████████████████████  100% (60/60 已创建)    │
│                                                                 │
│  多 Agent 协作框架:                                              │
│  ├── 协作协议     ████████████████████████  100%                 │
│  ├── Playbooks    ████████████████████████  100% (7 个阶段)      │
│  └── Skill 模板   ████████████████████████  100%                 │
│                                                                 │
│  agency-agents 集成进度:                                         │
│  ├── Engineering  ████████████████████████  100% (7/7)          │
│  ├── Testing      ████████████████████████  100% (8/8)          │
│  ├── Support      ████████████████████████  100% (6/6)          │
│  ├── Design       ████████████████████████  100% (7/7)          │
│  ├── Product      ████████████████████████  100% (3/3)          │
│  ├── Marketing    ████████████████████████  100% (7/7)          │
│  ├── PM           ████████████████████████  100% (5/5)          │
│  ├── Spatial      ████████████████████████  100% (6/6)          │
│  └── Specialized  ████████████████████████  100% (6/6)          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 二、系统偏离点分析

### 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 目录，集成 agency-agents 仓库

**时间**: 持续进行

**来源**: https://github.com/msitarzewski/agency-agents

#### 原始技能 (9 个)

| 技能 | 触发词 | 状态 |
|------|--------|------|
| 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 | ✅ 已定义 |

#### agency-agents 集成 (60+ Skills 完成)

| 类别 | 数量 | 状态 | Skills |
|------|------|------|--------|
| **Engineering** | 7 | ✅ 完成 | ai-engineer, backend-architect, frontend-developer, devops-automator, security-engineer, senior-developer, rapid-prototyper |
| **Testing** | 8 | ✅ 完成 | api-tester, evidence-collector, performance-benchmarker, accessibility-auditor, reality-checker, test-results-analyzer, tool-evaluator, workflow-optimizer |
| **Support** | 6 | ✅ 完成 | support-responder, executive-summary-generator, finance-tracker, infrastructure-maintainer, legal-compliance-checker, analytics-reporter |
| **Design** | 7 | ✅ 完成 | ux-architect, ux-researcher, visual-storyteller, brand-guardian, image-prompt-engineer, whimsy-injector, ui-designer |
| **Product** | 3 | ✅ 完成 | feedback-synthesizer, sprint-prioritizer, trend-researcher |
| **Marketing** | 7 | ✅ 完成 | growth-hacker, content-creator, social-media-strategist, tiktok-strategist, reddit-community-builder, app-store-optimizer, 以及中国平台专家 |
| **Project Management** | 5 | ✅ 完成 | studio-producer, project-shepherd, studio-operations, experiment-tracker, senior-pm |
| **Spatial Computing** | 6 | ✅ 完成 | visionos-spatial-engineer, macos-spatial-metal-engineer, terminal-integration-specialist, xr-cockpit-interaction-specialist, xr-immersive-developer, xr-interface-architect |
| **Specialized** | 6 | ✅ 完成 | agents-orchestrator, agentic-identity-trust, lsp-index-engineer, report-distribution-agent, sales-data-extraction-agent, data-consolidation-agent |

**当前 Skills 总数**: 63 ✅
**agency-agents 集成进度**: 100% ✅

#### 协作框架 (新增)

| 组件 | 文件 | 状态 |
|------|------|------|
| Skill 模板 | `.templates/skill-template.md` | ✅ 完成 |
| 交接模板 | `.coordination/handoff-templates.md` | ✅ 完成 |
| 激活提示 | `.coordination/agent-activation.md` | ✅ 完成 |
| Phase 0-6 Playbooks | `.playbooks/phase-*.md` | ✅ 完成 |

---

## 五、技术债务清单

### 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 完成标准

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

### 6.2 Phase 2 完成标准

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

### 6.3 Phase 3 完成标准

- [x] 创建 OpenFang config.toml
- [x] 迁移 OpenClaw JSON 配置到 TOML
- [x] OpenClaw JSON 配置已归档到 docs/archive/openclaw-legacy/
- [x] 默认路径从 ~/.openclaw 更新为 ~/.openfang
- [x] 默认端口从 18789 更新为 50051

### 6.4 Phase 4 完成标准

- [x] Agent 类型定义完整
- [x] Session 类型定义完整
- [x] Settings 类型定义完整
- [x] 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-4 已完成 ✅*
*Phase 5 已完成 ✅*
  * 基础 Skills: 9 个 ✅
  * agency-agents 集成: 60+ Skills ✅
  * 多 Agent 协作框架: 完整 ✅
    * 协作协议 (Handoff Templates)
    * Agent 激活提示
    * 7 阶段 Playbooks (Discovery → Operate)
*下一步: 多 Agent Team 协作功能实现*