3ff08faa56
## Major Features ### Streaming Response System - Implement LlmDriver trait with `stream()` method returning async Stream - Add SSE parsing for Anthropic and OpenAI API streaming - Integrate Tauri event system for frontend streaming (`stream:chunk` events) - Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error ### MCP Protocol Implementation - Add MCP JSON-RPC 2.0 types (mcp_types.rs) - Implement stdio-based MCP transport (mcp_transport.rs) - Support tool discovery, execution, and resource operations ### Browser Hand Implementation - Complete browser automation with Playwright-style actions - Support Navigate, Click, Type, Scrape, Screenshot, Wait actions - Add educational Hands: Whiteboard, Slideshow, Speech, Quiz ### Security Enhancements - Implement command whitelist/blacklist for shell_exec tool - Add SSRF protection with private IP blocking - Create security.toml configuration file ## Test Improvements - Fix test import paths (security-utils, setup) - Fix vi.mock hoisting issues with vi.hoisted() - Update test expectations for validateUrl and sanitizeFilename - Add getUnsupportedLocalGatewayStatus mock ## Documentation Updates - Update architecture documentation - Improve configuration reference - Add quick-start guide updates Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
8.3 KiB
8.3 KiB
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/
├── crates/ # Rust Workspace (核心能力)
│ ├── zclaw-types/ # L1: 基础类型 (AgentId, Message, Error)
│ ├── zclaw-memory/ # L2: 存储层 (SQLite, KV, 会话管理)
│ ├── zclaw-runtime/ # L3: 运行时 (LLM驱动, 工具, Agent循环)
│ ├── zclaw-kernel/ # L4: 核心协调 (注册, 调度, 事件, 工作流)
│ ├── zclaw-skills/ # 技能系统 (SKILL.md解析, 执行器)
│ ├── zclaw-hands/ # 自主能力 (Hand/Trigger 注册管理)
│ ├── zclaw-channels/ # 通道适配器 (Telegram, Discord, Slack)
│ └── zclaw-protocols/ # 协议支持 (MCP, A2A)
├── desktop/ # Tauri 桌面应用
│ ├── src/
│ │ ├── components/ # React UI 组件
│ │ ├── store/ # Zustand 状态管理
│ │ └── lib/ # 客户端通信 / 工具函数
│ └── src-tauri/ # Tauri Rust 后端 (集成 Kernel)
├── skills/ # SKILL.md 技能定义
├── hands/ # HAND.toml 自主能力配置
├── config/ # TOML 配置文件
├── docs/ # 架构文档和知识库
└── tests/ # Vitest 回归测试
2.1 核心数据流
用户操作 → React UI → Zustand Store → Tauri Commands → zclaw-kernel → LLM/Tools/Skills/Hands
2.2 技术栈
| 层级 | 技术 |
|---|---|
| 前端框架 | React 18 + TypeScript |
| 状态管理 | Zustand |
| 桌面框架 | Tauri 2.x |
| 样式方案 | Tailwind CSS |
| 配置格式 | TOML |
| 后端核心 | Rust Workspace (8 crates) |
2.3 Crate 依赖关系
zclaw-types (无依赖)
↑
zclaw-memory (→ types)
↑
zclaw-runtime (→ types, memory)
↑
zclaw-kernel (→ types, memory, runtime)
↑
desktop/src-tauri (→ kernel, skills, hands, channels, protocols)
3. 工作风格
3.1 交付导向
- 先做最高杠杆问题 - 解决用户最痛的点
- 真实能力优先 - 不做假数据占位
- 完整闭环 - 每个功能都要能真正使用
3.2 根因优先
遇到问题时，先确认属于哪一类：
- 协议问题 - API 端点、请求格式、响应解析
- 状态问题 - Store 更新、组件同步
- UI 问题 - 交互逻辑、样式显示
- 配置问题 - TOML 解析、环境变量
- 运行时问题 - 服务启动、端口占用
不在根因未明时盲目堆补丁。
3.3 闭环工作法
每次改动形成完整闭环：
- 定位问题 → 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 → 负责网络通信和```
---
### 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 文档结构
docs/
├── features/ # 功能文档
│ ├── README.md # 功能索引
│ └── */ # 各功能详细文档
├── knowledge-base/ # 技术知识库
│ ├── troubleshooting.md
│ └── *.md
└── archive/ # 归档文档
8.2 文档更新原则
- 修完就记 - 解决问题后立即更新文档
- 面向未来 - 文档要帮助未来的开发者快速理解
- 中文优先 - 所有面向用户的文档使用中文
9. 常见问题排查
9.1 连接问题
- 检查后端服务是否启动（端口 50051）
- 检查 Vite 代理配置
- 检查防火墙设置
9.2 状态问题
- 检查 Store 是否正确订阅
- 检查组件是否在正确的 Store 获取数据
- 检查是否有多个 Store 实例
9.3 配置问题
- 检查 TOML 语法
- 检查环境变量是否设置
- 检查配置文件路径
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. 安全注意事项
- 不在代码中硬编码密钥
- 用户输入必须验证
- 敏感操作需要确认
- 保留操作审计日志