From f56ba5559de36b29f8b4794d53b06b1a4a41ea59 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Tue, 10 Mar 2026 18:28:38 +0800
Subject: [PATCH] docs: add README and docs folder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加 README.md 项目文档
- 创建 docs 文件夹存放系统设计文档
---
 README.md                                 | 147 ++++++++++++++++++++++
 opencode-api.md => docs/opencode-api.md   |   0
 xcclaw-system.md => docs/xcclaw-system.md |   0
 3 files changed, 147 insertions(+)
 create mode 100644 README.md
 rename opencode-api.md => docs/opencode-api.md (100%)
 rename xcclaw-system.md => docs/xcclaw-system.md (100%)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4ab2a51
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# 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
diff --git a/opencode-api.md b/docs/opencode-api.md
similarity index 100%
rename from opencode-api.md
rename to docs/opencode-api.md
diff --git a/xcclaw-system.md b/docs/xcclaw-system.md
similarity index 100%
rename from xcclaw-system.md
rename to docs/xcclaw-system.md