268 lines
5.5 KiB
Markdown
268 lines
5.5 KiB
Markdown
# XCClaw
|
||
|
||
基于 OpenCode Agent 的本地 AI 任务调度系统。
|
||
|
||
## 核心理念
|
||
|
||
以 OpenCode 会话为最小执行单元，通过多种触发方式调度任务，实现本地化的 AI 任务执行系统。
|
||
|
||
## 功能特性
|
||
|
||
- **多种会话类型**：即时会话（Ephemeral）、持久会话（Persistent）、定时任务（Scheduled）
|
||
- **任务执行模式**：同步执行、异步执行
|
||
- **任务管理**：任务创建、执行、中止、历史记录查询
|
||
- **定时调度**：基于 APScheduler 的 Cron 定时任务
|
||
- **实时推送**：WebSocket 实时推送任务状态
|
||
- **数据持久化**：任务、定时调度、持久会话、历史记录自动持久化
|
||
- **REST API**：完整的 Web API 接口
|
||
|
||
## 快速开始
|
||
|
||
### 启动前端控制台
|
||
|
||
XCClaw 提供 Web 前端控制台，可视化管理任务、会话和定时调度。
|
||
|
||
1. 启动 HTTP 服务（控制台页面）：
|
||
|
||
```bash
|
||
python -m http.server 8888
|
||
```
|
||
|
||
2. 打开浏览器访问：http://localhost:8888/console.html
|
||
|
||
控制台功能：
|
||
- 任务管理：创建、执行、中止任务
|
||
- 定时任务：创建和管理 Cron 定时任务
|
||
- 历史记录：查看任务执行历史
|
||
- 持久会话：创建和管理多轮对话会话
|
||
- 实时日志：WebSocket 实时推送任务状态
|
||
|
||
详细使用说明见 [控制台使用指南](docs/console-guide.md)
|
||
|
||
### 安装依赖
|
||
|
||
```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/ # 文档
|
||
│ └── console-guide.md # 控制台使用指南
|
||
├── console.html # Web 前端控制台
|
||
├── 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
|