# XCClaw 控制台使用指南

## 访问地址

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

## 界面概览

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

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

---

## 1. 任务管理

### 创建任务

1. 选择任务类型：
   - **Ephemeral (即时任务)**：一次性任务，执行后结束
   - **Persistent (持久任务)**：可多轮交互的任务
   - **Scheduled (定时任务)**：需要配合定时任务模块使用

2. 输入任务描述 (Prompt)

3. 点击「创建任务」

### 执行任务

创建任务后，在任务列表中可以：

| 按钮 | 功能 |
|------|------|
| 执行 | 同步执行任务，等待完成 |
| 异步 | 异步执行任务，立即返回 |
| 中止 | 终止正在执行的任务 |

### 任务状态

- `pending` - 待执行
- `running` - 执行中
- `completed` - 已完成
- `failed` - 执行失败
- `aborted` - 已中止

---

## 2. 定时任务

### 创建定时任务

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

### 常用 Cron 示例

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

---

## 3. 历史记录

- 查看所有已完成的任务记录
- 支持限制显示条数
- 可清空历史记录

---

## 4. 持久会话

### 创建会话

输入会话名称（可选），点击「创建」

### 发送消息

1. 在列表中找到目标会话
2. 点击「发消息」按钮
3. 输入消息内容
4. 选择发送方式：
   - **同步发送**：等待响应返回
   - **异步发送**：立即返回，任务在后台执行

---

## 5. 实时日志

通过 WebSocket 实时显示：

- 任务状态变化
- WebSocket 连接状态
- 操作日志

---

## 快捷操作

- **自动刷新**：健康检查和任务列表每 5 秒自动刷新
- **WebSocket**：页面左上角显示连接状态

---

## 故障排查

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