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/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,409 @@
+# ZCLAW 协作与实现规则
+
+> 目标：把 ZCLAW 做成**真实可交付**的 OpenFang 桌面客户端，而不是"看起来能用"的演示 UI。
+
+## 1. 项目目标
+
+ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面端，核心价值不是单纯聊天，而是：
+
+- 真实连接 OpenFang Kernel
+- 真实驱动 Agents / Skills / Hands / Workflows
+- 真实读写 TOML 配置与工作区
+- 真实反映运行时状态与审计日志
+
+判断标准：
+
+> 一个页面或按钮如果**没有改变 OpenFang Runtime 的真实行为 / 真实配置 / 真实路由 / 真实工作区上下文**，那它大概率还只是演示态，不算交付完成。
+
+---
+
+## 2. 项目结构
+
+```text
+ZClaw/
+├── desktop/              # Tauri 桌面应用
+│   ├── src/
+│   │   ├── components/   # React UI
+│   │   ├── store/        # Zustand stores
+│   │   └── lib/          # OpenFang client / helpers
+│   └── src-tauri/        # Tauri Rust backend
+├── skills/               # SKILL.md 技能定义
+├── hands/                # HAND.toml 自主能力包
+├── config/               # OpenFang TOML 配置
+├── docs/                 # 架构、排障、知识库
+└── tests/                # Vitest 回归测试
+```
+
+核心数据流：
+
+```text
+React UI → Zustand Store → OpenFangClient → OpenFang Kernel → Skills / Hands / Channels
+```
+
+**OpenFang vs OpenClaw 关键差异**：
+
+| 方面 | OpenClaw | OpenFang |
+|------|----------|----------|
+| 语言 | TypeScript/Node.js | Rust |
+| 端口 | 18789 | 4200 |
+| 配置 | YAML/JSON | TOML |
+| 插件 | TypeScript | SKILL.md + WASM |
+| 安全 | 3 层 | 16 层纵深防御 |
+
+---
+
+## 3. 工作风格
+
+### 3.1 交付导向
+
+- 先做**最高杠杆**问题
+- 优先恢复真实能力，再考虑局部美化
+- 不保留"假数据看起来正常"的占位实现
+
+### 3.2 根因优先
+
+- 先确认问题属于：
+  - 协议错配 (WebSocket vs REST)
+  - 状态管理错误
+  - UI 没接真实能力
+  - 配置解析 / 持久化错误 (TOML 格式)
+  - 运行时 / 环境问题
+- 不在根因未明时盲目堆补丁
+
+### 3.3 闭环工作法
+
+每次改动尽量形成完整闭环：
+
+1. 定位问题
+2. 建立最小可信心智模型
+3. 实现最小有效修复
+4. 跑自动化验证
+5. 记录知识沉淀
+
+---
+
+## 4. 解决问题的标准流程
+
+### 4.1 先看真实协议和真实运行时
+
+当桌面端与 OpenFang 行为不一致时：
+
+- 先检查当前 REST API schema / WebSocket 事件格式
+- 不要只相信旧前端封装或历史调用方式
+- 如果源码与实际运行行为冲突，以**当前 OpenFang Kernel**为准
+
+尤其是以下能力必须以真实 OpenFang 为准：
+
+- `/api/chat` (聊天)
+- `/api/agents` (Agent 管理)
+- `/api/hands/*` (Hands 触发)
+- `/api/workflows/*` (工作流)
+- `/api/config` (TOML 配置)
+- `/api/audit/logs` (审计日志)
+- WebSocket 事件 (`stream`, `hand`, `workflow`)
+
+### 4.2 先打通读，再打通写
+
+任何配置类页面都按这个顺序推进：
+
+1. 先确认页面能读取真实配置
+2. 再确认页面能显示真实当前值
+3. 最后再接保存
+
+禁止直接做"本地 state 假切换"冒充已完成。
+
+### 4.3 区分"前端概念"和"运行时概念"
+
+如果前端有自己的本地实体，例如：
+
+- agent / clone
+- conversation / session
+- temporary model selection
+
+必须明确它是否真的对应 OpenFang 中的：
+
+- `agent_id`
+- `session_id`
+- `default_model`
+
+不要把本地 UI 标识直接当成 OpenFang runtime 标识发送。
+
+### 4.4 调试优先顺序
+
+遇到问题时，优先按这个顺序排查：
+
+1. 是否连到了正确的 OpenFang (端口 4200)
+2. 是否握手/认证成功
+3. 请求方法名是否正确 (REST endpoint / WebSocket message type)
+4. 请求参数是否符合当前 schema
+5. 返回结构是否与前端解析一致
+6. 页面是否只是改了本地 state，没有写回 runtime
+7. 是否存在旧 fallback / placeholder 掩盖真实错误
+
+---
+
+## 5. 实现规则
+
+### 5.1 Gateway 通信
+
+IMPORTANT: 所有与 OpenFang 的通信必须通过：
+
+- `desktop/src/lib/openfang-client.ts` (OpenFang)
+- `desktop/src/lib/gateway-client.ts` (OpenClaw 兼容层)
+
+禁止在组件内直接创建 WebSocket 或拼装协议帧。
+
+### 5.2 后端切换
+
+通过环境变量或 localStorage 切换后端：
+
+```typescript
+// 环境变量
+const USE_OPENFANG = import.meta.env.VITE_USE_OPENFANG === 'true';
+
+// localStorage
+const backendType = localStorage.getItem('zclaw-backend') || 'openclaw';
+```
+
+### 5.3 状态管理
+
+- UI 负责展示和交互
+- Store 负责状态组织、流程编排
+- OpenFangClient 负责 REST / WebSocket 通信
+- 配置读写和协议适配逻辑放在 `lib/` 助手层
+
+避免把协议细节散落在多个组件里。
+
+### 5.4 React 组件
+
+- 使用函数组件与 hooks
+- 复杂副作用收敛到 store 或 helper
+- 组件尽量保持"展示层"职责
+- 一个组件里如果同时出现协议拼装、复杂状态机、配置改写逻辑，优先拆分
+
+### 5.5 TypeScript
+
+- 避免 `any`
+- 优先 `unknown + 类型守卫`
+- 外部返回结构必须做容错解析
+- 不要假设 OpenFang 响应永远只有一种 shape
+
+### 5.6 配置处理 (TOML)
+
+OpenFang 使用 **TOML** 配置格式：
+
+```toml
+# ~/.openfang/config.toml
+
+[server]
+host = "127.0.0.1"
+port = 4200
+
+[agent]
+default_model = "gpt-4"
+
+[[llm.providers]]
+name = "openai"
+api_key = "${OPENAI_API_KEY}"
+```
+
+对配置的处理：
+
+- 使用 TOML 解析器，不要手动解析
+- 写回时保持 TOML 格式
+- 支持环境变量插值 `${VAR_NAME}`
+
+---
+
+## 6. UI 完成度规则
+
+### 6.1 允许存在的 UI
+
+- 已接真实能力的 UI
+- 明确标注"未实现 / 只读 / 待接入"的 UI
+
+### 6.2 不允许存在的 UI
+
+- 看似可编辑但不会生效的设置项
+- 展示假状态却不对应真实运行时的面板
+- 用 mock 数据掩盖未完成能力但不做说明
+
+### 6.3 OpenFang 新特性 UI
+
+以下 OpenFang 特有功能需要新增 UI：
+
+- **Hands 面板**: 触发和管理 7 个自主能力包
+- **Workflow 编辑器**: 多步骤工作流编排
+- **Trigger 管理器**: 事件触发器配置
+- **审计日志**: Merkle 哈希链审计查看
+
+---
+
+## 7. 测试与验证规则
+
+### 7.1 改动后必须验证
+
+修改以下内容后，必须至少运行相关测试：
+
+- chat / stream
+- openfang client / gateway store
+- settings / config
+- protocol helpers
+
+优先命令：
+
+```bash
+pnpm vitest run tests/desktop/chatStore.test.ts tests/desktop/gatewayStore.test.ts tests/desktop/general-settings.test.tsx
+pnpm tsc --noEmit
+```
+
+如果新增了独立 helper，应补最小回归测试。
+
+### 7.2 测试设计原则
+
+- 测根因，不只测表象
+- 测协议参数是否正确 (REST endpoint / WebSocket type)
+- 测状态是否在失败时保持一致
+- 测真实边界条件：
+  - agent_id 生命周期
+  - session_id 作用域
+  - TOML 配置语法容错
+  - Hand 触发与审批
+
+### 7.3 人工验证
+
+自动化通过后，关键链路仍应做手工 smoke：
+
+- 能否连接 OpenFang (端口 4200)
+- 能否发送消息并正常流式返回
+- 模型切换是否真实生效
+- Hand 触发是否正常执行
+- 保存配置后是否真正影响新会话/运行时
+
+---
+
+## 8. 文档沉淀规则
+
+凡是出现以下情况，应更新 `docs/openfang-knowledge-base.md` 或相关文档：
+
+- 新的协议坑 (REST/WebSocket)
+- 新的握手/配置/模型排障结论
+- 真实 runtime 与旧实现不一致
+- OpenFang 特有问题 (Hands, Workflows, 安全层)
+- 某个问题的最短排障路径已经明确
+
+原则：**修完就记，避免二次踩坑。**
+
+---
+
+## 9. 常见高风险点
+
+- 把前端本地 id 当作 OpenFang `agent_id`
+- 只改 Zustand，不改 OpenFang 配置
+- 把 OpenClaw 协议字段发给 OpenFang
+- fallback 逻辑覆盖真实错误
+- 直接手动解析 TOML，忽略格式容错
+- 让 UI 显示"已完成"，实际只是 placeholder
+- 混淆 OpenClaw 端口 (18789) 和 OpenFang 端口 (4200)
+
+---
+
+## 10. OpenFang 特有注意事项
+
+### 10.1 Hands 系统
+
+OpenFang 提供 7 个自主能力包：
+
+| Hand | 功能 | 触发方式 |
+|------|------|----------|
+| Clip | 视频处理、竖屏生成 | 手动/自动 |
+| Lead | 销售线索发现 | 定时 |
+| Collector | 数据收集聚合 | 定时/事件 |
+| Predictor | 预测分析 | 手动 |
+| Researcher | 深度研究 | 手动 |
+| Twitter | Twitter 自动化 | 定时/事件 |
+| Browser | 浏览器自动化 | 手动/工作流 |
+
+触发 Hand 时必须：
+- 检查 RBAC 权限
+- 处理 `needs_approval` 状态
+- 记录审计日志
+
+### 10.2 安全层
+
+OpenFang 有 16 层安全防护，前端需要：
+
+- 正确处理认证失败 (Ed25519 + JWT)
+- 尊重 RBAC 能力门控
+- 显示审计日志入口
+- 处理速率限制错误
+
+
+```
+
+---
+
+## 11. 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm tauri:dev
+pnpm build
+pnpm setup
+pnpm vitest run tests/desktop/chatStore.test.ts tests/desktop/gatewayStore.test.ts tests/desktop/general-settings.test.tsx
+pnpm tsc --noEmit
+```
+
+---
+
+## 12. 参考文档
+
+- `docs/openfang-technical-reference.md` - OpenFang 技术参考
+- `docs/openclaw-to-openfang-migration-brainstorm.md` - 迁移分析
+- `docs/DEVELOPMENT.md` - 开发指南
+- `skills/` - SKILL.md 技能示例
+- `hands/` - HAND.toml 配置示例
+
+---
+
+## 13. 提交信息建议
+
+```text
+<type>(<scope>): <summary>
+```
+
+示例：
+
+```text
+feat(openfang): add OpenFangClient with WebSocket support
+feat(hands): add researcher hand trigger UI
+fix(chat): align stream events with OpenFang protocol
+fix(config): handle TOML format correctly
+perf(gateway): optimize connection pooling
+docs(knowledge-base): capture OpenFang RBAC permission issues
+```
+
+推荐类型：
+
+- `feat`
+- `fix`
+- `refactor`
+- `test`
+- `docs`
+- `chore`
+- `perf`
+
+---
+
+## 14. 迁移检查清单
+
+从 OpenClaw 迁移到 OpenFang 时，确保：
+
+- [ ] 端口从 18789 改为 4200
+- [ ] 配置格式从 YAML/JSON 改为 TOML
+- [ ] WebSocket URL 添加 `/ws` 路径
+- [ ] RPC 方法改为 REST API 或新 WebSocket 协议
+- [ ] 插件从 TypeScript 改为 SKILL.md
+- [ ] 添加 Hands/Workflow 相关 UI
+- [ ] 处理 16 层安全防护的交互