XCClaw/README.md

# XCClaw

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

## 核心理念

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

## 功能特性

- **多种会话类型**：即时会话、常驻会话、定时会话
- **任务调度**：支持即时执行、异步执行、定时执行
- **REST API**：完整的 Web API 接口
- **Cron 定时任务**：基于 APScheduler 的定时任务

## 快速开始

### 安装依赖

```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 监听端口 |

## API 文档

### 健康检查

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

### 任务管理

#### 创建任务

```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
```

### 定时任务

#### 创建定时任务

```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}
```

## 项目结构

```
xcclaw/
├── app/
│   ├── api/          # API 路由
│   ├── core/         # 配置、日志
│   ├── models/       # 数据模型
│   ├── services/     # 核心服务
│   │   ├── opencode_client.py   # OpenCode API 客户端
│   │   ├── scheduler.py          # 定时任务调度
│   │   └── session_manager.py   # 会话管理
│   └── main.py       # FastAPI 入口
├── docs/              # 文档
├── requirements.txt   # 依赖
└── README.md
```

## License

MIT