XCClaw/README.md

# XCClaw

基于 OpenCode Agent 的本地 AI 任务调度系统。

## 核心理念

以 OpenCode 会话为最小执行单元，通过多种触发方式调度任务，实现本地化的 AI 任务执行系统。

## 功能特性

- **多种会话类型**：即时会话（Ephemeral）、持久会话（Persistent）、定时任务（Scheduled）
- **任务执行模式**：同步执行、异步执行
- **任务管理**：任务创建、执行、中止、历史记录查询
- **定时调度**：基于 APScheduler 的 Cron 定时任务
- **实时推送**：WebSocket 实时推送任务状态
- **数据持久化**：任务、定时调度、持久会话、历史记录自动持久化
- **REST API**：完整的 Web API 接口

## 快速开始

### 安装依赖

```bash
pip install -r requirements.txt
```

### 启动服务

1. 首先确保 OpenCode 服务已启动（默认端口 4096）：

```bash
opencode serve --port 4096 --hostname 127.0.0.1
```

2. 启动 XCClaw 服务（默认端口 3005）：

```bash
python -m app.main
```

或指定配置：

```bash
XCCLAW_OPENCODE_PORT=4096 XCCLAW_APP_PORT=3005 python -m app.main
```

### 配置说明

可通过环境变量配置：

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `XCCLAW_OPENCODE_HOST` | 127.0.0.1 | OpenCode 服务地址 |
| `XCCLAW_OPENCODE_PORT` | 4096 | OpenCode 服务端口 |
| `XCCLAW_OPENCODE_PASSWORD` | - | OpenCode 访问密码 |
| `XCCLAW_APP_HOST` | 0.0.0.0 | XCClaw 监听地址 |
| `XCCLAW_APP_PORT` | 3005 | XCClaw 监听端口 |
| `XCCLAW_DATA_DIR` | ~/Documents/XCDesktop/xcclaw | 数据存储目录 |

## API 文档

### 健康检查

```bash
GET /api/xcclaw/health
```

返回示例：
```json
{
  "status": "ok",
  "opencode": {"status": "ok", "version": "..."}
}
```

### WebSocket 实时推送

```bash
WS /api/xcclaw/ws
```

实时推送任务状态变化。

### 任务管理

#### 创建任务

```bash
POST /api/xcclaw/task
{
  "type": "ephemeral",  # ephemeral | persistent | scheduled
  "prompt": "你的任务描述"
}
```

#### 执行任务（同步）

```bash
POST /api/xcclaw/task/{task_id}/execute
```

#### 执行任务（异步）

```bash
POST /api/xcclaw/task/{task_id}/execute_async
```

#### 中止任务

```bash
POST /api/xcclaw/task/{task_id}/abort
```

#### 获取任务

```bash
GET /api/xcclaw/task/{task_id}
```

#### 获取任务列表

```bash
GET /api/xcclaw/task
```

### 定时任务

#### 创建定时任务

```bash
POST /api/xcclaw/schedule
{
  "id": "unique-id",
  "name": "任务名称",
  "cron": "0 9 * * *",  # Cron 表达式
  "prompt": "定时执行的提示词",
  "enabled": true
}
```

#### 列出定时任务

```bash
GET /api/xcclaw/schedule
```

#### 删除定时任务

```bash
DELETE /api/xcclaw/schedule/{schedule_id}
```

### 任务历史

#### 获取历史记录

```bash
GET /api/xcclaw/history?limit=10
```

#### 清空历史记录

```bash
DELETE /api/xcclaw/history
```

### 持久会话

#### 创建持久会话

```bash
POST /api/xcclaw/persistent?name=我的会话
```

#### 列出持久会话

```bash
GET /api/xcclaw/persistent
```

#### 删除持久会话

```bash
DELETE /api/xcclaw/persistent/{session_id}
```

#### 发送消息（同步）

```bash
POST /api/xcclaw/persistent/{session_id}/message?text=你的消息
```

#### 发送消息（异步）

```bash
POST /api/xcclaw/persistent/{session_id}/message_async?text=你的消息
```

## 项目结构

```
xcclaw/
├── app/
│   ├── api/                  # API 路由
│   │   └── routes.py         # 所有 API 端点
│   ├── core/                 # 核心配置
│   │   ├── config.py        # 配置管理
│   │   └── logging.py       # 日志配置
│   ├── models/              # 数据模型
│   │   └── session.py       # 会话、任务相关模型
│   ├── services/            # 核心服务
│   │   ├── opencode_client.py      # OpenCode API 客户端
│   │   ├── scheduler.py             # 定时任务调度
│   │   ├── session_manager.py       # 任务/会话管理
│   │   ├── persistent_session.py    # 持久会话管理
│   │   ├── history.py               # 任务历史记录
│   │   ├── storage.py               # JSON 数据持久化
│   │   └── websocket_manager.py     # WebSocket 管理
│   └── main.py            # FastAPI 应用入口
├── tests/                  # 测试用例
├── docs/                   # 文档
├── requirements.txt        # Python 依赖
├── pytest.ini             # pytest 配置
└── README.md
```

## 数据存储

所有数据默认存储在 `~/Documents/XCDesktop/xcclaw/` 目录下：

- `tasks.json` - 任务数据
- `schedules.json` - 定时任务配置
- `persistent_sessions.json` - 持久会话
- `task_history.json` - 任务历史记录

## 测试

```bash
pytest
```

## License

MIT