zclaw_openfang/CLAUDE.md

ZCLAW 协作与实现规则

ZCLAW 是一个独立成熟的 AI Agent 桌面客户端，专注于提供真实可用的 AI 能力，而不是演示 UI。

1. 项目定位

1.1 ZCLAW 是什么

ZCLAW 是面向中文用户的 AI Agent 桌面端，核心能力包括：

• 智能对话 - 多模型支持、流式响应、上下文管理
• 自主能力 - 8 个 Hands（浏览器、数据采集、研究、预测等）
• 技能系统 - 可扩展的 SKILL.md 技能定义
• 工作流编排 - 多步骤自动化任务
• 安全审计 - 完整的操作日志和权限控制

1.2 决策原则

任何改动都要问：这对 ZCLAW 有用吗？对 ZCLAW 有影响吗？

• ✅ 对 ZCLAW 用户有价值的功能 → 优先实现
• ✅ 提升 ZCLAW 稳定性和可用性 → 必须做
• ❌ 只为兼容其他系统的妥协 → 谨慎评估
• ❌ 增加复杂度但无实际价值 → 不做

---

2. 项目结构

ZCLAW/
├── desktop/              # Tauri 桌面应用
│   ├── src/
│   │   ├── components/   # React UI 组件
│   │   ├── store/        # Zustand 状态管理
│   │   └── lib/          # 客户端通信 / 工具函数
│   └── src-tauri/        # Tauri Rust 后端
├── skills/               # SKILL.md 技能定义
├── hands/                # HAND.toml 自主能力配置
├── config/               # TOML 配置文件
├── docs/                 # 架构文档和知识库
└── tests/                # Vitest 回归测试

2.1 核心数据流

用户操作 → React UI → Zustand Store → Gateway Client → 后端服务 → Skills / Hands

2.2 技术栈

层级	技术
前端框架	React 18 + TypeScript
状态管理	Zustand
桌面框架	Tauri 2.x
样式方案	Tailwind CSS
配置格式	TOML
后端服务	Rust (端口 50051)

---

3. 工作风格

3.1 交付导向

• 先做最高杠杆问题 - 解决用户最痛的点
• 真实能力优先 - 不做假数据占位
• 完整闭环 - 每个功能都要能真正使用

3.2 根因优先

遇到问题时，先确认属于哪一类：

1. 协议问题 - API 端点、请求格式、响应解析
2. 状态问题 - Store 更新、组件同步
3. UI 问题 - 交互逻辑、样式显示
4. 配置问题 - TOML 解析、环境变量
5. 运行时问题 - 服务启动、端口占用

不在根因未明时盲目堆补丁。

3.3 闭环工作法

每次改动形成完整闭环：

1. 定位问题 → 2. 建立心智模型 → 3. 最小修复 → 4. 自动验证 → 5. 记录沉淀

---

4. 实现规则

4.1 通信层

所有与后端的通信必须通过统一的客户端层：

• desktop/src/lib/gateway-client.ts - 主要通信客户端
• desktop/src/lib/tauri-gateway.ts - Tauri 原生命令

禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。

4.2 状态管理

UI 组件 → 只负责展示和交互
Store   → 负责状态组织和流程编排
Client  → 负责网络通信
lib/    → 工具函数和协议适配

4.3 代码规范

TypeScript:

• 避免 any，优先 unknown + 类型守卫
• 外部数据必须做容错解析
• 不假设 API 响应永远只有一种格式

React:

• 使用函数组件 + hooks
• 复杂副作用收敛到 store
• 组件保持"展示层"职责

配置处理:

• 使用 TOML 解析器
• 支持环境变量插值 ${VAR_NAME}
• 写回时保持格式一致

---

5. UI 完成度标准

5.1 允许存在的 UI

• 已接入真实后端能力的 UI
• 明确标注"开发中 / 只读"的 UI
• 有降级方案的 UI

5.2 不允许存在的 UI

• 看似可编辑但不会生效的设置
• 展示假状态的面板
• 用 mock 数据掩盖未完成能力

5.3 核心功能 UI

功能	状态	说明
聊天界面	✅ 完成	流式响应、多模型切换
分身管理	✅ 完成	创建、配置、切换 Agent
自动化面板	✅ 完成	Hands 触发、参数配置
技能市场	🚧 进行中	技能浏览和安装
工作流编辑	📋 计划中	多步骤任务编排

---

6. 自主能力系统 (Hands)

ZCLAW 提供 8 个自主能力包：

Hand	功能	状态
Browser	浏览器自动化	✅ 可用
Collector	数据收集聚合	✅ 可用
Researcher	深度研究	✅ 可用
Predictor	预测分析	✅ 可用
Lead	销售线索发现	✅ 可用
Trader	交易分析	✅ 可用
Clip	视频处理	⚠️ 需 FFmpeg
Twitter	Twitter 自动化	⚠️ 需 API Key

触发 Hand 时：

1. 检查依赖是否满足
2. 收集必要参数
3. 处理 needs_approval 状态
4. 记录执行日志

---

7. 测试与验证

7.1 必测场景

修改以下内容后必须验证：

• 聊天 / 流式响应
• Store 状态更新
• 配置读写
• Hand 触发

7.2 验证命令

# TypeScript 类型检查
pnpm tsc --noEmit

# 单元测试
pnpm vitest run

# 启动开发环境
pnpm start:dev

7.3 人工验证清单

• 能否正常连接后端服务
• 能否发送消息并获得流式响应
• 模型切换是否生效
• Hand 触发是否正常执行
• 配置保存是否持久化

---

8. 文档管理

8.1 文档结构

docs/
├── features/           # 功能文档
│   ├── README.md       # 功能索引
│   └── */              # 各功能详细文档
├── knowledge-base/     # 技术知识库
│   ├── troubleshooting.md
│   └── *.md
└── archive/            # 归档文档

8.2 文档更新原则

• 修完就记 - 解决问题后立即更新文档
• 面向未来 - 文档要帮助未来的开发者快速理解
• 中文优先 - 所有面向用户的文档使用中文

---

9. 常见问题排查

9.1 连接问题

1. 检查后端服务是否启动（端口 50051）
2. 检查 Vite 代理配置
3. 检查防火墙设置

9.2 状态问题

1. 检查 Store 是否正确订阅
2. 检查组件是否在正确的 Store 获取数据
3. 检查是否有多个 Store 实例

9.3 配置问题

1. 检查 TOML 语法
2. 检查环境变量是否设置
3. 检查配置文件路径

---

10. 常用命令

# 安装依赖
pnpm install

# 开发模式
pnpm start:dev

# 仅启动桌面端
pnpm desktop

# 构建生产版本
pnpm build

# 类型检查
pnpm tsc --noEmit

# 运行测试
pnpm vitest run

# 停止所有服务
pnpm start:stop

---

11. 提交规范

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

类型:

• feat - 新功能
• fix - 修复问题
• refactor - 重构
• docs - 文档更新
• test - 测试相关
• chore - 杂项

示例:

feat(hands): 添加参数预设保存功能
fix(chat): 修复流式响应中断问题
refactor(store): 统一 Store 数据获取方式

---

12. 安全注意事项

• 不在代码中硬编码密钥
• 用户输入必须验证
• 敏感操作需要确认
• 保留操作审计日志