# XCClaw 控制台使用指南

## 访问地址

```
http://localhost:8888/console.html
```

## 界面概览

控制台采用 Tab 切换设计，包含以下模块：

| Tab | 功能 |
|-----|------|
| 任务管理 | 创建、执行一次性任务 |
| 定时任务 | 创建和管理 Cron 循环调度任务 |
| 历史记录 | 查看任务执行历史 |
| 持久会话 | 创建和管理多轮对话会话 |
| 实时日志 | WebSocket 实时推送的任务状态 |

---

## 1. 任务管理

> 用于创建一次性执行的任务。任务创建后不会自动执行，需要手动点击「执行」按钮。

### 任务类型

| 类型 | 说明 | 使用场景 |
|------|------|----------|
| **Ephemeral (即时任务)** | 一次性任务，执行完成后结束 | 临时性的 AI 问答、代码生成等 |
| **Persistent (持久任务)** | 可多轮交互的任务会话 | 需要多轮对话才能完成的任务 |

### 创建任务

1. 选择任务类型（即时任务/持久任务）
2. 输入任务描述 (Prompt)
3. 可选：勾选「创建后自动执行」
4. 点击「创建任务」

> 💡 **提示**：默认勾选「创建后自动执行」，任务创建后会立即执行。如果需要手动控制执行，取消勾选即可。

### 执行任务

创建任务后，在任务列表中可以执行以下操作：

| 按钮 | 功能 |
|------|------|
| 详情 | 查看任务的完整信息，包括 Session ID、错误信息等 |
| 执行 | 同步执行任务，等待完成 |
| 异步 | 异步执行任务，立即返回 |
| 中止 | 终止正在执行的任务 |

### 任务详情

点击「详情」按钮可以查看任务的完整信息：

- **任务ID**：任务的唯一标识
- **类型**：即时任务/持久任务
- **状态**：任务的当前状态
- **Session ID**：OpenCode 会话 ID，可用于在 OpenCode 界面查看对话详情
- **提示词**：任务的完整描述
- **错误信息**：任务失败时的错误原因
- **创建/开始/完成时间**：任务的时间线

---

## 2. 定时任务

> 用于创建**循环执行**的定时调度任务。基于 Cron 表达式，在指定时间自动执行任务。

### 与「任务管理」的区别

| 功能 | 任务管理 | 定时任务 |
|------|----------|----------|
| 执行方式 | 手动点击执行 | 自动执行 |
| 执行次数 | 一次 | 循环执行 |
| 配置方式 | 创建后手动执行 | 配置 Cron 表达式，自动触发 |

### 创建定时任务

| 字段 | 说明 |
|------|------|
| 任务ID | 唯一标识符，如 `daily_task` |
| 任务名称 | 显示名称，如「每日任务」 |
| Cron 表达式 | 执行时间，如 `0 9 * * *` (每天9点) |
| 执行内容 | 定时执行的 Prompt |
| 启用 | 是否启用此定时任务（未启用则不会执行） |

### 定时任务列表

表格显示所有定时任务，包含以下信息：

| 列 | 说明 |
|-----|------|
| ID | 任务唯一标识 |
| 名称 | 任务显示名称 |
| Cron | 执行时间表达式 |
| 状态 | 已启用 / 已禁用 |
| 提示词 | 执行内容摘要 |

### 常用 Cron 示例

| 表达式 | 含义 |
|--------|------|
| `0 9 * * *` | 每天 9:00 |
| `0 */2 * * *` | 每隔 2 小时 |
| `0 9 * * 1-5` | 工作日 9:00 |
| `*/30 * * * *` | 每隔 30 分钟 |

---

## 3. 历史记录

> 查看所有已完成的任务执行历史记录。

### 功能说明

- **查看历史**：显示所有任务的执行记录，包括类型、描述、状态、时间等
- **显示条数**：可自定义显示的记录数量
- **清空历史**：一键清空所有历史记录

### 任务状态说明

| 状态 | 说明 |
|------|------|
| `pending` | 待执行 |
| `running` | 执行中 |
| `completed` | 已完成 |
| `failed` | 执行失败 |
| `aborted` | 已中止 |

---

## 4. 持久会话

> 创建可**多轮交互**的对话会话。与「任务管理」中的即时任务不同，持久会话可以多次发送消息，保持上下文连贯。

### 与即时任务的区别

| 特性 | 即时任务 | 持久会话 |
|------|----------|----------|
| 交互次数 | 单次 | 多次 |
| 上下文 | 不保持 | 自动保持 |
| 适用场景 | 简单问答 | 复杂任务、多轮对话 |

### 使用流程

1. **创建会话**：输入会话名称（可选），点击「创建」
2. **发送消息**：点击会话的「发消息」按钮
3. **选择发送方式**：
   - **同步发送**：等待 AI 响应返回后再操作
   - **异步发送**：立即返回，任务在后台执行

---

## 5. 实时日志

> 通过 WebSocket 实时显示任务状态和系统消息。

### 显示内容

- 任务创建、执行、完成的实时通知
- WebSocket 连接状态变化
- 操作日志和错误信息

### 连接状态

页面左上角显示 WebSocket 连接状态：
- **已连接** - 绿色圆点，正常接收消息
- **未连接** - 红色圆点，需要刷新页面重连

---

## 快速参考

### 功能对比

| 需求 | 推荐功能 |
|------|----------|
| 临时性的 AI 问答 | 任务管理 → 即时任务 |
| 需要多轮对话的复杂任务 | 任务管理 → 持久任务 |
| 每天定时执行某任务 | 定时任务 |
| 查看任务执行历史 | 历史记录 |
| 实时监控任务状态 | 实时日志 |

---

## 故障排查

| 问题 | 解决方法 |
|------|----------|
| 页面无法访问 | 确认 HTTP 服务运行在 8888 端口 |
| API 请求失败 | 确认 XCClaw 服务运行在 3005 端口 |
| WebSocket 未连接 | 检查网络连接，刷新页面 |
| 任务执行失败 | 查看健康检查确认 OpenCode 服务正常 |