# ZCLAW 用户操作手册

**版本:** 0.1.0
**更新日期:** 2026-03-15

---

## 目录

1. [快速开始](#快速开始)
2. [界面概览](#界面概览)
3. [聊天功能](#聊天功能)
4. [分身管理](#分身管理)
5. [Hands 能力包](#hands-能力包)
6. [工作流调度](#工作流调度)
7. [团队协作](#团队协作)
8. [设置配置](#设置配置)
9. [常见问题](#常见问题)

---

## 快速开始

### 启动应用

1. 确保已安装 Node.js 18+ 和 pnpm
2. 在项目根目录运行：
   ```bash
   cd desktop
   pnpm install
   pnpm dev
   ```
3. 浏览器访问 `http://localhost:1420`

### 连接 Gateway

1. 确保 Gateway 服务已启动（默认端口 50051）
2. 应用会自动连接到 `ws://127.0.0.1:50051/ws`
3. 连接状态显示在右侧面板顶部

---

## 界面概览

ZCLAW 界面分为三个区域：

```
┌─────────────┬──────────────────────┬─────────────┐
│   左侧边栏   │      中间主区域       │   右侧面板   │
│             │                      │             │
│  - 分身     │   聊天/任务/团队      │  - 状态     │
│  - Hands    │                      │  - 文件     │
│  - 工作流   │                      │  - Agent    │
│  - 团队     │                      │             │
│             │                      │             │
│  [设置按钮] │                      │             │
└─────────────┴──────────────────────┴─────────────┘
```

### 左侧边栏标签

| 标签 | 功能 |
|------|------|
| 分身 | Agent 分身管理 |
| Hands | 自主能力包 |
| 工作流 | 定时任务和触发器 |
| 团队 | 多 Agent 协作团队 |

---

## 聊天功能

### 发送消息

1. 在底部输入框输入消息
2. 点击 **发送消息** 按钮或按 `Enter` 键发送
3. Agent 会流式返回回复

### 开始新对话

- 点击 **开始新对话** 按钮清空当前对话历史

### 选择模型

1. 点击输入框旁的模型选择按钮
2. 从下拉列表选择模型
3. 当前模型显示在右侧面板

### 添加附件

- 点击 **添加附件** 按钮上传文件

---

## 分身管理

### 查看分身列表

在左侧边栏点击 **分身** 标签，可看到所有已创建的 Agent 分身。

### 创建新分身

1. 点击 **快速配置新 Agent** 按钮
2. 填写表单：
   - **名称** (必填): 分身名称
   - **角色**: 如"代码助手"、"写作助手"
   - **昵称**: 分身对你的称呼
   - **场景标签**: 用逗号分隔，如"编程, 调试"
   - **工作目录**: 默认 `~/.openfang/zclaw-workspace`
   - **你的名字**: 用户名称
   - **你的角色**: 用户角色
   - **限制文件访问范围**: 建议开启
   - **加入优化计划**: 可选
3. 点击 **完成配置**

### 删除分身

1. 将鼠标悬停在分身上
2. 点击出现的 **X** 按钮
3. 确认删除

### 切换当前分身

- 点击分身列表中的任意分身即可切换

---

## Hands 能力包

### 可用能力包

| 能力包 | 工具数 | 状态 | 用途 |
|--------|--------|------|------|
| 🌐 Browser Hand | 18 | 就绪 | 网页自动化浏览 |
| 🎬 Clip Hand | 7 | 需配置 | 视频剪辑生成 |
| 🔍 Collector Hand | 15 | 就绪 | 情报收集监控 |
| 📊 Lead Hand | 14 | 就绪 | 销售线索发现 |
| 🔮 Predictor Hand | 14 | 就绪 | 未来预测分析 |
| 🧪 Researcher Hand | 15 | 就绪 | 深度研究调查 |
| 📈 Trading Hand | 15 | 就绪 | 市场交易分析 |
| 𝕏 Twitter Hand | 15 | 需配置 | Twitter 自动化 |

### 使用能力包

1. 点击左侧 **Hands** 标签
2. 点击要使用的能力包
3. 在右侧详情页点击 **执行任务**
4. 配置任务参数并开始执行

### 查看任务历史

- 在能力包详情页可查看历史执行记录

---

## 工作流调度

### 访问调度器

1. 点击左侧 **工作流** 标签
2. 主区域显示调度器面板

### 调度器标签

| 标签 | 功能 |
|------|------|
| 定时任务 | Heartbeat 引擎管理的定时任务 |
| 事件触发器 | 基于事件的自动触发规则 |
| 运行历史 | 任务执行历史记录 |

### 创建定时任务

1. 点击 **新建任务** 或 **创建定时任务**
2. 配置任务参数
3. 设置执行周期
4. 保存任务

---

## 团队协作

### 访问团队页面

1. 点击左侧 **团队** 标签
2. 显示团队列表和创建按钮

### 创建团队

1. 点击 **Create Team** 按钮
2. 配置团队成员和角色
3. 设置协作模式

### 团队协作模式

- 多个 Agent 可以组成团队
- 支持不同的协作角色分配
- 可追踪团队任务执行状态

---

## 设置配置

点击左下角 **设置** 按钮进入设置页面。

### 设置分类

| 分类 | 功能 |
|------|------|
| 通用 | Gateway 连接、外观与行为 |
| 用量统计 | API 调用统计 |
| 积分详情 | 积分余额和使用 |
| 模型与 API | 模型选择和 API 配置 |
| MCP 服务 | MCP 服务器配置 |
| 技能 | 技能包管理 |
| IM 频道 | 即时通讯集成 |
| 工作区 | 项目目录配置 |
| 数据与隐私 | 数据处理设置 |
| 安全状态 | 安全配置状态 |
| 审计日志 | 操作审计记录 |
| 定时任务 | 定时任务管理 |
| 提交反馈 | 反馈提交 |
| 关于 | 版本信息 |

### Gateway 连接

1. 输入 Gateway URL (默认: `ws://127.0.0.1:50051/ws`)
2. 输入认证 Token (可选)
3. 点击 **保存连接设置**
4. 点击 **重新连接**

### 模型切换

1. 进入 **模型与 API** 设置
2. 浏览可用模型列表
3. 点击 **切换到此模型** 按钮

### 工作区配置

1. 进入 **工作区** 设置
2. 设置默认项目目录
3. 配置文件访问限制
4. 开启/关闭自动保存和文件监听

---

## 常见问题

### Q: Gateway 连接失败

**解决方案:**
1. 检查 Gateway 服务是否运行
2. 确认端口 50051 未被占用
3. 检查防火墙设置

### Q: 模型切换后不生效

**解决方案:**
1. 点击 **重新连接** 按钮
2. 刷新页面
3. 开始新对话

### Q: 分身创建失败

**解决方案:**
1. 检查 Gateway 连接状态
2. 确保所有必填字段已填写
3. 检查后端日志

### Q: Hands 任务执行无响应

**解决方案:**
1. 检查能力包配置状态
2. 确认相关 API Key 已配置
3. 查看控制台错误信息

### Q: 工作区路径显示"未解析"

**解决方案:**
1. 检查路径格式是否正确
2. 确保目录存在
3. 使用绝对路径

---

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行 |
| `Escape` | 关闭弹窗 |

---

## 技术支持

如遇问题，请：
1. 查看浏览器控制台 (F12)
2. 检查 Gateway 服务日志
3. 提交反馈至开发团队

---

*本手册基于 ZCLAW v0.1.0 编写*