07079293f4
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>
314 lines
7.2 KiB
Markdown
314 lines
7.2 KiB
Markdown
# ZCLAW 协作与实现规则
|
||
|
||
> 目标：把 ZCLAW 做成**真实可交付**的 OpenClaw 桌面客户端，而不是“看起来能用”的演示 UI。
|
||
|
||
## 1. 项目目标
|
||
|
||
ZCLAW 是基于 OpenClaw 的 AI Agent 桌面端，核心价值不是单纯聊天，而是：
|
||
|
||
- 真实连接 Gateway
|
||
- 真实驱动 Agent / Plugins / Skills
|
||
- 真实读写配置与工作区
|
||
- 真实反映运行时状态
|
||
|
||
判断标准：
|
||
|
||
> 一个页面或按钮如果**没有改变 OpenClaw Runtime 的真实行为 / 真实配置 / 真实路由 / 真实工作区上下文**，那它大概率还只是演示态，不算交付完成。
|
||
|
||
---
|
||
|
||
## 2. 项目结构
|
||
|
||
```text
|
||
ZClaw/
|
||
├── desktop/ # Tauri 桌面应用
|
||
│ ├── src/
|
||
│ │ ├── components/ # React UI
|
||
│ │ ├── store/ # Zustand stores
|
||
│ │ └── lib/ # Gateway client / helpers
|
||
│ └── src-tauri/ # Tauri Rust backend
|
||
├── src/gateway/ # Node Gateway 侧逻辑
|
||
├── plugins/ # OpenClaw 插件
|
||
├── skills/ # 自定义技能
|
||
├── config/ # 默认配置与 bootstrap 文件
|
||
├── docs/ # 架构、排障、知识库
|
||
└── tests/ # Vitest 回归测试
|
||
```
|
||
|
||
核心数据流：
|
||
|
||
```text
|
||
React UI → Zustand Store → GatewayClient → OpenClaw Gateway → Plugins / Skills / Runtime
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 工作风格
|
||
|
||
### 3.1 交付导向
|
||
|
||
- 先做**最高杠杆**问题
|
||
- 优先恢复真实能力，再考虑局部美化
|
||
- 不保留“假数据看起来正常”的占位实现
|
||
|
||
### 3.2 根因优先
|
||
|
||
- 先确认问题属于：
|
||
- 协议错配
|
||
- 状态管理错误
|
||
- UI 没接真实能力
|
||
- 配置解析 / 持久化错误
|
||
- 运行时 / 环境问题
|
||
- 不在根因未明时盲目堆补丁
|
||
|
||
### 3.3 闭环工作法
|
||
|
||
每次改动尽量形成完整闭环：
|
||
|
||
1. 定位问题
|
||
2. 建立最小可信心智模型
|
||
3. 实现最小有效修复
|
||
4. 跑自动化验证
|
||
5. 记录知识沉淀
|
||
|
||
---
|
||
|
||
## 4. 解决问题的标准流程
|
||
|
||
### 4.1 先看真实协议和真实运行时
|
||
|
||
当桌面端与 Gateway 行为不一致时：
|
||
|
||
- 先检查当前 runtime schema / RPC 能力
|
||
- 不要只相信旧前端封装或历史调用方式
|
||
- 如果源码与实际运行行为冲突，以**当前 runtime**为准
|
||
|
||
尤其是以下能力必须以真实 Gateway 为准：
|
||
|
||
- `agent`
|
||
- `models.list`
|
||
- `config.get`
|
||
- `config.apply`
|
||
- `channels.*`
|
||
- `heartbeat.tasks`
|
||
- ZCLAW 自定义 RPC
|
||
|
||
### 4.2 先打通读，再打通写
|
||
|
||
任何配置类页面都按这个顺序推进：
|
||
|
||
1. 先确认页面能读取真实配置
|
||
2. 再确认页面能显示真实当前值
|
||
3. 最后再接保存
|
||
|
||
禁止直接做“本地 state 假切换”冒充已完成。
|
||
|
||
### 4.3 区分“前端概念”和“运行时概念”
|
||
|
||
如果前端有自己的本地实体，例如：
|
||
|
||
- clone
|
||
- conversation
|
||
- temporary model selection
|
||
|
||
必须明确它是否真的对应 runtime 中的：
|
||
|
||
- agentId
|
||
- sessionKey
|
||
- default model
|
||
|
||
不要把本地 UI 标识直接当成 Gateway runtime 标识发送。
|
||
|
||
### 4.4 调试优先顺序
|
||
|
||
遇到问题时，优先按这个顺序排查：
|
||
|
||
1. 是否连到了正确的 Gateway
|
||
2. 是否握手成功
|
||
3. 请求方法名是否正确
|
||
4. 请求参数是否符合当前 schema
|
||
5. 返回结构是否与前端解析一致
|
||
6. 页面是否只是改了本地 state，没有写回 runtime
|
||
7. 是否存在旧 fallback / placeholder 掩盖真实错误
|
||
|
||
---
|
||
|
||
## 5. 实现规则
|
||
|
||
### 5.1 Gateway 通信
|
||
|
||
所有与 OpenClaw 的通信必须通过：
|
||
|
||
- `desktop/src/lib/gateway-client.ts`
|
||
|
||
禁止在组件内直接创建 WebSocket 或拼装协议帧。
|
||
|
||
### 5.2 状态管理
|
||
|
||
- UI 负责展示和交互
|
||
- Store 负责状态组织、流程编排
|
||
- GatewayClient 负责 RPC / 事件流通信
|
||
- 配置读写和协议适配逻辑放在 `lib/` 助手层
|
||
|
||
避免把协议细节散落在多个组件里。
|
||
|
||
### 5.3 React 组件
|
||
|
||
- 使用函数组件与 hooks
|
||
- 复杂副作用收敛到 store 或 helper
|
||
- 组件尽量保持“展示层”职责
|
||
- 一个组件里如果同时出现协议拼装、复杂状态机、配置改写逻辑，优先拆分
|
||
|
||
### 5.4 TypeScript
|
||
|
||
- 避免 `any`
|
||
- 优先 `unknown + 类型守卫`
|
||
- 外部返回结构必须做容错解析
|
||
- 不要假设 Gateway 响应永远只有一种 shape
|
||
|
||
### 5.5 配置处理
|
||
|
||
对 `config.get` 返回的 `raw`：
|
||
|
||
- 不要假设它一定是严格 JSON
|
||
- 先兼容 BOM / 注释 / 宽松对象语法
|
||
- 写回时以**可被 runtime 接受**为优先，必要时输出为标准 JSON
|
||
|
||
---
|
||
|
||
## 6. UI 完成度规则
|
||
|
||
### 6.1 允许存在的 UI
|
||
|
||
- 已接真实能力的 UI
|
||
- 明确标注“未实现 / 只读 / 待接入”的 UI
|
||
|
||
### 6.2 不允许存在的 UI
|
||
|
||
- 看似可编辑但不会生效的设置项
|
||
- 展示假状态却不对应真实运行时的面板
|
||
- 用 mock 数据掩盖未完成能力但不做说明
|
||
|
||
### 6.3 AutoClaw 参考策略
|
||
|
||
参考 HTML 原型时：
|
||
|
||
- 先提炼高价值结构和缺失能力
|
||
- 不机械复刻
|
||
- 只实现能带来真实系统收益的部分
|
||
|
||
---
|
||
|
||
## 7. 测试与验证规则
|
||
|
||
### 7.1 改动后必须验证
|
||
|
||
修改以下内容后，必须至少运行相关测试：
|
||
|
||
- chat / stream
|
||
- 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 测试设计原则
|
||
|
||
- 测根因，不只测表象
|
||
- 测协议参数是否正确
|
||
- 测状态是否在失败时保持一致
|
||
- 测真实边界条件：
|
||
- placeholder agent
|
||
- clone id
|
||
- sessionKey 生命周期
|
||
- 配置 raw 的宽松语法
|
||
|
||
### 7.3 人工验证
|
||
|
||
自动化通过后，关键链路仍应做手工 smoke：
|
||
|
||
- 能否连接 Gateway
|
||
- 能否发送消息并正常流式返回
|
||
- 模型切换是否真实生效
|
||
- 保存配置后是否真正影响新会话/运行时
|
||
|
||
---
|
||
|
||
## 8. 文档沉淀规则
|
||
|
||
凡是出现以下情况，应更新 `docs/openclaw-knowledge-base.md` 或相关文档：
|
||
|
||
- 新的协议坑
|
||
- 新的握手/配置/模型排障结论
|
||
- 真实 runtime 与旧实现不一致
|
||
- 某个问题的最短排障路径已经明确
|
||
|
||
原则：**修完就记，避免二次踩坑。**
|
||
|
||
---
|
||
|
||
## 9. 常见高风险点
|
||
|
||
- 把前端本地 id 当作 runtime `agentId`
|
||
- 只改 Zustand，不改 Gateway 配置
|
||
- 把旧协议字段继续发给新 runtime
|
||
- fallback 逻辑覆盖真实错误
|
||
- 直接 `JSON.parse(config.raw)`，忽略宽松配置语法
|
||
- 让 UI 显示“已完成”，实际只是 placeholder
|
||
|
||
---
|
||
|
||
## 10. 常用命令
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm 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
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 参考文档
|
||
|
||
- `docs/architecture-v2.md`
|
||
- `docs/DEVELOPMENT.md`
|
||
- `docs/openclaw-knowledge-base.md`
|
||
- `plugins/zclaw-ui/index.ts`
|
||
- `plugins/zclaw-chinese-models/index.ts`
|
||
|
||
---
|
||
|
||
## 12. 提交信息建议
|
||
|
||
```text
|
||
<type>(<scope>): <summary>
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
fix(chat): align agent request with current gateway schema
|
||
fix(models): persist gateway default model through config.apply
|
||
docs(knowledge-base): capture desktop gateway protocol mismatch case
|
||
```
|
||
|
||
推荐类型：
|
||
|
||
- `feat`
|
||
- `fix`
|
||
- `refactor`
|
||
- `test`
|
||
- `docs`
|
||
- `chore`
|
||
- `perf`
|