xuanchi/XCClaw

Fork 0

Files

ssdfasd 7d3bdb8793 docs: 更新 README 添加前端控制台说明

2026-03-10 19:39:04 +08:00

5.5 KiB

Raw Permalink Blame History

XCClaw

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

核心理念

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

功能特性

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

快速开始

启动前端控制台

XCClaw 提供 Web 前端控制台，可视化管理任务、会话和定时调度。

启动 HTTP 服务（控制台页面）：

python -m http.server 8888

打开浏览器访问：http://localhost:8888/console.html

控制台功能：

任务管理：创建、执行、中止任务
定时任务：创建和管理 Cron 定时任务
历史记录：查看任务执行历史
持久会话：创建和管理多轮对话会话
实时日志：WebSocket 实时推送任务状态

详细使用说明见控制台使用指南

安装依赖

pip install -r requirements.txt

启动服务

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

opencode serve --port 4096 --hostname 127.0.0.1

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

python -m app.main

或指定配置：

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 文档

健康检查

GET /api/xcclaw/health

返回示例：

{
  "status": "ok",
  "opencode": {"status": "ok", "version": "..."}
}

WebSocket 实时推送

WS /api/xcclaw/ws

实时推送任务状态变化。

任务管理

创建任务

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

执行任务（同步）

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

执行任务（异步）

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

中止任务

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

获取任务

GET /api/xcclaw/task/{task_id}

获取任务列表

GET /api/xcclaw/task

定时任务

创建定时任务

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

列出定时任务

GET /api/xcclaw/schedule

删除定时任务

DELETE /api/xcclaw/schedule/{schedule_id}

任务历史

获取历史记录

GET /api/xcclaw/history?limit=10

清空历史记录

DELETE /api/xcclaw/history

持久会话

创建持久会话

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

列出持久会话

GET /api/xcclaw/persistent

删除持久会话

DELETE /api/xcclaw/persistent/{session_id}

发送消息（同步）

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

发送消息（异步）

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 - 任务历史记录

测试

pytest

License

MIT

5.5 KiB Raw Permalink Blame History Unescape Escape