148 lines
2.7 KiB
Markdown
148 lines
2.7 KiB
Markdown
# 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
|