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
parent 67e1da635d
commit 07079293f4
126 changed files with 36229 additions and 1035 deletions
--- a/docs/archive/openclaw-legacy/zclaw-openclaw-roadmap.md
+++ b/docs/archive/openclaw-legacy/zclaw-openclaw-roadmap.md
@@ -0,0 +1,479 @@
+# 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 数据**
+
+### 之后执行
+
+4. Gateway 协议继续收口
+5. Workspace / bootstrap 文件生成
+6. 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 的前置基础