Files

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

3.1 KiB

Raw Blame History

ZClaw 项目指南

基于 OpenClaw 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React 19 构建。

WHAT - 项目结构

ZClaw/
├── desktop/              # Tauri 桌面应用
│   ├── src/              # React 前端
│   │   ├── components/   # UI 组件
│   │   ├── store/        # Zustand 状态
│   │   └── lib/          # gateway-client 等
│   └── src-tauri/        # Rust 后端
├── src/gateway/          # Node.js Gateway 管理
├── plugins/              # OpenClaw 插件 (zclaw-*)
├── skills/               # 自定义技能 (SKILL.md)
├── config/               # OpenClaw 配置
└── tests/                # Vitest 测试

WHY - 核心架构

React UI → Zustand Store → GatewayClient → OpenClaw Gateway → Plugins/Skills

数据流:

UI 调用 Store action
Store 通过 GatewayClient 发送 WebSocket 请求
Gateway 调用 Plugin/Skill 处理
结果通过事件流式返回 UI

HOW - 开发命令

pnpm install          # 安装依赖
pnpm dev              # 前端开发
pnpm tauri:dev        # Tauri 开发
pnpm build            # 构建
pnpm test             # 运行测试
pnpm lint             # 代码检查
pnpm setup            # 首次设置

关键规则

Gateway 通信

IMPORTANT: 所有与 OpenClaw 的通信必须通过 GatewayClient (desktop/src/lib/gateway-client.ts)

// ✓ 正确：通过 GatewayClient
const client = useGatewayStore((s) => s.client)
await client.request('agent', { message })

// ✗ 错误：直接 WebSocket
new WebSocket('ws://...')

状态管理

IMPORTANT: 使用 Zustand 选择器避免不必要的重渲染

// ✓ 正确：选择器
const isStreaming = useChatStore((s) => s.isStreaming)

// ✗ 错误：解构整个 store
const { isStreaming, messages, ... } = useChatStore()

插件开发

插件目录必须包含 openclaw.plugin.json。详见 plugins/zclaw-chinese-models/ 作为参考。

React 组件

使用函数组件 + hooks
组件文件 < 300 行
复杂逻辑提取到自定义 hook

TypeScript

严格模式已启用
使用 interface 定义类型
避免 any，使用 unknown + 类型守卫

测试

IMPORTANT: 修改核心模块后必须运行测试

pnpm test                           # 全部测试
pnpm test -- --grep "GatewayClient" # 单个测试

覆盖率要求: 总体 ≥ 80%，核心模块 ≥ 90%

常见问题

问题	解决方案
Gateway 连接失败	检查 OpenClaw 是否运行: `~/.openclaw`
构建内存不足	`NODE_OPTIONS=--max-old-space-size=4096`
测试超时	增加 Vitest timeout 或使用 mock

详细文档

需要时阅读以下文档：

架构设计: docs/architecture-v2.md
开发指南: docs/DEVELOPMENT.md
插件 API: 参考 plugins/zclaw-ui/index.ts

Git 提交格式

<type>(<scope>): <description>

# 示例
feat(gateway): add exponential backoff for reconnection
fix(ui): resolve message duplication in ChatArea

类型: feat, fix, refactor, test, docs, chore, perf

3.1 KiB Raw Blame History