zclaw_openfang/docs/SYSTEM_ANALYSIS.md

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% (11/11)        │
│  ├── 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	11	✅ 完成	growth-hacker, content-creator, social-media-strategist, tiktok-strategist, reddit-community-builder, app-store-optimizer, twitter-engager, instagram-curator, wechat-official-account, xiaohongshu-specialist, zhihu-strategist
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 总数: 68 ✅ 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 完成标准

• 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 配置已归档到 docs/archive/openclaw-legacy/
• 默认路径从 ~/.openclaw 更新为 ~/.openfang
• 默认端口从 18789 更新为 50051

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-4 已完成 ✅ Phase 5 已完成 ✅

• 基础 Skills: 9 个 ✅
• agency-agents 集成: 68 Skills ✅
• 多 Agent 协作框架: 完整 ✅
  • 协作协议 (Handoff Templates)
  • Agent 激活提示
  • 7 阶段 Playbooks (Discovery → Operate) Phase 6 进行中 🔄
• 多 Agent Team 协作 UI 实现:
  • ✅ 类型定义 (types/team.ts)
  • ✅ Team Store (store/teamStore.ts)
  • ✅ Agent 编排器 UI (components/TeamOrchestrator.tsx)
  • ✅ Dev↔QA 循环界面 (components/DevQALoop.tsx)
  • ✅ 实时协作状态 (components/TeamCollaborationView.tsx)
• 待完成:
  • 组件集成到主应用
  • WebSocket 实时事件同步
  • 与 OpenFang API 对接 下一步: 组件集成与 API 对接