# ZCLAW 协作与实现规则 > **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**，专注于提供真实可用的 AI 能力，而不是演示 UI。 ## 1. 项目定位 ### 1.1 ZCLAW 是什么 ZCLAW 是面向中文用户的 AI Agent 桌面端，核心能力包括： - **智能对话** - 多模型支持、流式响应、上下文管理 - **自主能力** - 8 个 Hands（浏览器、数据采集、研究、预测等） - **技能系统** - 可扩展的 SKILL.md 技能定义 - **工作流编排** - 多步骤自动化任务 - **安全审计** - 完整的操作日志和权限控制 ### 1.2 决策原则 **任何改动都要问：这对 ZCLAW 有用吗？对 ZCLAW 有影响吗？** - ✅ 对 ZCLAW 用户有价值的功能 → 优先实现 - ✅ 提升 ZCLAW 稳定性和可用性 → 必须做 - ❌ 只为兼容其他系统的妥协 → 谨慎评估 - ❌ 增加复杂度但无实际价值 → 不做 --- ## 2. 项目结构 ```text 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 核心数据流 ```text 用户操作 → 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 验证命令 ```bash # TypeScript 类型检查 pnpm tsc --noEmit # 单元测试 pnpm vitest run # 启动开发环境 pnpm start:dev ``` ### 7.3 人工验证清单 - [ ] 能否正常连接后端服务 - [ ] 能否发送消息并获得流式响应 - [ ] 模型切换是否生效 - [ ] Hand 触发是否正常执行 - [ ] 配置保存是否持久化 --- ## 8. 文档管理 ### 8.1 文档结构 ```text 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. 常用命令 ```bash # 安装依赖 pnpm install # 开发模式 pnpm start:dev # 仅启动桌面端 pnpm desktop # 构建生产版本 pnpm build # 类型检查 pnpm tsc --noEmit # 运行测试 pnpm vitest run # 停止所有服务 pnpm start:stop ``` --- ## 11. 提交规范 ``` (): ``` **类型:** - `feat` - 新功能 - `fix` - 修复问题 - `refactor` - 重构 - `docs` - 文档更新 - `test` - 测试相关 - `chore` - 杂项 **示例:** ``` feat(hands): 添加参数预设保存功能 fix(chat): 修复流式响应中断问题 refactor(store): 统一 Store 数据获取方式 ``` --- ## 12. 安全注意事项 - 不在代码中硬编码密钥 - 用户输入必须验证 - 敏感操作需要确认 - 保留操作审计日志