iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
07079293f48e09e291402171daace4bd0d33675d
zclaw_openfang/docs/archive/openclaw-legacy/zclaw-openclaw-roadmap.md
iven 07079293f4 feat(hands): restructure Hands UI with Chinese localization 
Major changes:
- Add HandList.tsx component for left sidebar
- Add HandTaskPanel.tsx for middle content area
- Restructure Sidebar tabs: 分身/HANDS/Workflow
- Remove Hands tab from RightPanel
- Localize all UI text to Chinese
- Archive legacy OpenClaw documentation
- Add Hands integration lessons document
- Update feature checklist with new components

UI improvements:
- Left sidebar now shows Hands list with status icons
- Middle area shows selected Hand's tasks and results
- Consistent styling with Tailwind CSS
- Chinese status labels and buttons

Documentation:
- Create docs/archive/openclaw-legacy/ for old docs
- Add docs/knowledge-base/hands-integration-lessons.md
- Update docs/knowledge-base/feature-checklist.md
- Update docs/knowledge-base/README.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 23:16:32 +08:00

9.9 KiB
Raw Blame History

ZCLAW 功能 -> OpenClaw 子系统落地路线图

日期: 2026-03-12
依据: docs/openclaw-deep-dive.md
目标: 把 ZCLAW 从“像 OpenClaw 的桌面 UI”推进为“真正围绕 OpenClaw Runtime 的 Tauri 封装层”。

一、总原则

后续所有功能都按同一条映射链设计与验收：

ZCLAW 功能 -> OpenClaw 子系统 -> 真实配置/文件/路由/运行时行为 -> 前端展示与操作

如果一个功能改完后：

  • 没有改变 OpenClaw 的真实配置
  • 没有改变 Agent 的真实身份/工作区/边界
  • 没有改变 Channel / Heartbeat / Skills / MCP / Gateway 的真实行为

那它仍然只是 UI 占位，不算真正落地。

二、路线图总览

阶段 主题 目标 结果
R0 Gateway 协议与连接 让 ZCLAW 成为一个可稳定连上 OpenClaw Gateway 的控制端 连接/重连/状态/错误 可用
R1 Agent 模型收敛 把 分身/快速配置/右侧 Agent 面板 收敛成真实 Agent Profile Clone -> Agent Profile
R2 配置控制面板化 把设置页从“本地状态”收敛为 OpenClaw 配置编辑器 config/get/patch/apply
R3 Workspace / Bootstrap 文件 让 Agent 身份、人格、用户上下文落到 workspace 文件 IDENTITY/SOUL/USER/AGENTS
R4 Channels / Bindings 让 IM 页面真正管理渠道输入与路由 channels + bindings
R5 Heartbeat / 定时任务 把“定时任务页”升级为 Heartbeat 控制台 heartbeat + HEARTBEAT.md
R6 Skills / MCP 让技能与工具能力成为真实可管理能力面 skills + mcp
R7 产品化壳层 完成 Tauri sidecar、安装、诊断、迁移与回归体系 可交付桌面产品

三、功能 -> OpenClaw 子系统映射

1. Gateway 连接

对应子系统

  • Gateway WebSocket Protocol
  • device auth
  • pairing
  • scopes
  • auth.token / auth.deviceToken

ZCLAW 当前功能

  • 设置页里的 Gateway URL
  • 右侧连接状态卡片
  • 自动连接逻辑

应落地到

  • desktop/src/lib/gateway-client.ts
  • 协议握手适配
  • 正确错误码展示
  • 后续可补 pairing required / token drift / device auth 诊断提示

验收标准

  • 能稳定连接本地 OpenClaw Gateway
  • 状态能从 disconnected -> connecting -> handshaking -> connected
  • 错误能区分：
    • token 问题
    • device auth 问题
    • mode/client id 问题
    • pairing 问题

优先级

  • 最高

2. 分身 / 快速配置 / 右侧 Agent 区域

对应子系统

  • agents.list[]
  • workspace / agentDir
  • IDENTITY.md
  • SOUL.md
  • USER.md
  • AGENTS.md

ZCLAW 当前功能

  • 左侧分身列表
  • 快速配置弹层
  • 右侧 Agent 标签页

正确语义

  • 分身 = Agent 实例
  • 快速配置 = 新建 / 更新 Agent Profile
  • 右侧 Agent 区域 = 当前 Agent 的身份与上下文可视化

应落地到

  • 插件层：zclaw-ui 中的 Agent Profile RPC
  • 数据层：从 CloneConfig 升级为 AgentProfile
  • 前端层：CloneManager / RightPanel / chatStore
  • 工作区层：为每个 Agent 生成/更新 bootstrap 文件

验收标准

  • 创建 Agent 后，左侧、聊天头部、右侧 Agent 面板一致
  • Agent 的身份字段有统一来源
  • 不再依赖单纯前端本地 fallback agent

优先级

  • 最高

3. 工作区设置

对应子系统

  • agents.defaults.workspace
  • agents.list[].workspace
  • sandbox
  • tools allow/deny
  • bootstrap files

ZCLAW 当前功能

  • 工作目录
  • 文件限制
  • 自动保存上下文
  • 文件监听

正确语义

工作区不是 UI 里的一个路径输入框，而是：

  • Agent 的上下文根目录
  • bootstrap 文件所在位置
  • 文件访问边界
  • 工具执行边界的基础

应落地到

  • config.patch/apply
  • workspace info RPC
  • Agent 级与 defaults 级区分

验收标准

  • 改动工作区后，OpenClaw 配置能真实更新
  • 右侧 Agent 面板能展示当前 Agent 的工作目录与边界

优先级

  • 高

4. IM 频道页

对应子系统

  • channels.*
  • channels.<channel>.accounts
  • bindings
  • mention / allowlist / route target

正确语义

IM 页不是“集成列表”，而是：

  • 管理消息从哪里进入系统
  • 管理这些消息如何路由到哪个 Agent

应落地到

  • channels.list/status + 插件探测
  • 后续补 bindings 可视化
  • 账号级与渠道级配置区分

验收标准

  • 至少能看清当前有哪些 channel/account
  • 至少能表达“这个输入源会进入哪个 Agent”

优先级

  • 高

5. 定时任务页

对应子系统

  • agents.defaults.heartbeat
  • agents.list[].heartbeat
  • HEARTBEAT.md

正确语义

不是单纯 cron 列表，而是：

  • 哪些 Agent 会被定期唤醒
  • 唤醒后看什么
  • 没事时如何 ack
  • 结果发去哪里

应落地到

  • heartbeat.tasks 读取
  • heartbeat 配置编辑
  • HEARTBEAT.md 管理入口

验收标准

  • UI 中明确 Heartbeat 是 Agent turn，不是普通定时脚本

优先级

  • 中高

6. 技能页

对应子系统

  • skills
  • SKILL.md
  • extra skill dirs

正确语义

技能页的目标是：

  • 告诉用户 Agent 会做什么
  • 告诉用户这些能力从哪些 skill 目录和手册里来

应落地到

  • 真实技能目录扫描
  • openclaw skills list/info/check 对应能力
  • extraDirs 与当前 Agent 能力面关联

验收标准

  • 不只是维护一个字符串数组
  • 能看到技能来源与状态

优先级

  • 中高

7. MCP 服务页

对应子系统

  • MCP / RPC adapters / 外部工具能力面

正确语义

不是前端模板收藏，而是：

  • Agent 当前能调用哪些外部能力
  • 这些能力如何被配置、启用与管理

优先级

  • 中高

8. 用量统计 / 会话 / 系统信息

对应子系统

  • sessions
  • usage
  • plugin status
  • gateway health

目标

  • 提供可观察性
  • 让用户知道 Agent 是否真的在运行、运行了多少、谁在消耗成本

优先级

  • 中

四、阶段化执行方案

Phase A：把“分身系统”收敛成 Agent Profile 层

目标

先把最接近用户感知的核心链路做对：

  • 左侧分身
  • 快速配置
  • 右侧 Agent 面板
  • 聊天头部 Agent 名称

具体动作

  1. 引入统一 AgentProfile 类型
  2. 插件层 CloneConfig 升级为更完整 profile
  3. store 层把 clones 视为 agentProfiles
  4. chatStore.currentAgent 不再自带孤立 fallback 逻辑
  5. quick config 默认值与 workspace/profile 字段打通

阶段验收

  • 创建出来的 Agent，在所有 UI 位置是一致实体
  • 刷新后仍能从持久化数据恢复

Phase B：让 Quick Config 不再只是 JSON 临时缓存

目标

把 quick config 从：

  • zclaw.config.quick 的一份附加偏好

收敛到：

  • Agent 创建向导 / 最近一次 Agent 草稿

具体动作

  1. 区分 quickConfigDraft 与 agentProfiles
  2. 保存快速配置时，不再误导成“系统总配置”
  3. 后续为 bootstrap 文件生成预留字段映射

阶段验收

  • quick config 有清晰职责
  • 不和真实 Agent Profile 混淆

Phase C：把 Agent Profile 继续落到 workspace/bootstrap 文件

目标

让 Agent 的身份不是只活在 zclaw-data.json 里。

具体动作

  1. 为 Agent 生成独立 workspace 或 profile 目录
  2. 写入/更新：
    • IDENTITY.md
    • USER.md
    • SOUL.md
    • AGENTS.md
  3. 让右侧 Agent 面板字段与这些文件的内容有映射关系

阶段验收

  • Agent 真正拥有可审计、可读、可迁移的文本身份

Phase D：设置页全面收敛为 OpenClaw 配置控制台

目标

把现有 Settings 页从 local state 管理升级为：

  • OpenClaw config 编辑器
  • Gateway runtime 控制台

关键动作

  • 优先用 config.get / patch / apply
  • 区分：
    • defaults
    • per-agent
    • per-channel/account

五、当前代码库的立即修正项

1. 数据模型不一致

当前前端 Clone 已经包含：

  • workspaceDir
  • restrictFiles
  • privacyOptIn
  • userName
  • userRole

但插件层 CloneConfig 仍未完整持久化这些字段。

立即动作

  • 插件层升级 CloneConfig
  • create/update/list 全链路透传这些字段

2. chatStore 与 gatewayStore 双重 Agent 模型并存

当前问题：

  • chatStore.agents/currentAgent 仍是 UI 型实体
  • gatewayStore.clones 是更接近真实 profile 的实体

立即动作

  • 让 currentAgent 选择依赖真实 profile id
  • 补一个从 profile 派生 chat agent 的适配层

3. quickConfig 语义仍不清晰

立即动作

  • 在代码与文档中明确：
    • 它是草稿 / 最近一次快速配置输入
    • 它不是 Agent 全量真源

六、下一步开发顺序

立即执行

  1. 修 Agent Profile 数据模型一致性
  2. 收敛 Quick Config 与 Agent Profile 的职责边界
  3. 让右侧 Agent 面板只读真实 profile 数据

之后执行

  1. Gateway 协议继续收口
  2. Workspace / bootstrap 文件生成
  3. IM / Heartbeat / Skills / MCP 分页逐个真实化

七、完成定义

当下面这些条件满足时，才能认为 ZCLAW 已经真正开始 OpenClaw 化：

  • 分身不再只是 UI 列表，而是 Agent 实体
  • 快速配置不再只是表单，而是 Agent 创建向导
  • 右侧 Agent 面板展示真实 Agent Profile
  • 设置页改的是 OpenClaw 真实运行配置
  • Heartbeat / Channels / Skills / MCP 不再是占位页
  • Gateway 连接协议稳定可诊断

八、本轮执行建议

本轮优先做：

  • Agent Profile 统一模型
  • 插件层持久化字段补齐
  • 前端选择/展示逻辑收敛

原因：

  • 这条链最贴近用户感知
  • 能直接验证 openclaw-deep-dive.md 的核心判断
  • 也是后续 workspace/bootstrap/channel/binding 的前置基础