docs: 更新 README.md 完善功能说明和 API 文档

README.md

@@ -8,10 +8,13 @@
 
 ## 功能特性
 
-- **多种会话类型**：即时会话、常驻会话、定时会话
-- **任务调度**：支持即时执行、异步执行、定时执行
+- **多种会话类型**：即时会话（Ephemeral）、持久会话（Persistent）、定时任务（Scheduled）
+- **任务执行模式**：同步执行、异步执行
+- **任务管理**：任务创建、执行、中止、历史记录查询
+- **定时调度**：基于 APScheduler 的 Cron 定时任务
+- **实时推送**：WebSocket 实时推送任务状态
+- **数据持久化**：任务、定时调度、持久会话、历史记录自动持久化
 - **REST API**：完整的 Web API 接口
-- **Cron 定时任务**：基于 APScheduler 的定时任务
 
 ## 快速开始
 
@@ -52,6 +55,7 @@ XCCLAW_OPENCODE_PORT=4096 XCCLAW_APP_PORT=3005 python -m app.main
 | `XCCLAW_OPENCODE_PASSWORD` | - | OpenCode 访问密码 |
 | `XCCLAW_APP_HOST` | 0.0.0.0 | XCClaw 监听地址 |
 | `XCCLAW_APP_PORT` | 3005 | XCClaw 监听端口 |
+| `XCCLAW_DATA_DIR` | ~/Documents/XCDesktop/xcclaw | 数据存储目录 |
 
 ## API 文档
 
@@ -61,6 +65,22 @@ XCCLAW_OPENCODE_PORT=4096 XCCLAW_APP_PORT=3005 python -m app.main
 GET /api/xcclaw/health
 ```
 
+返回示例：
+```json
+{
+  "status": "ok",
+  "opencode": {"status": "ok", "version": "..."}
+}
+```
+
+### WebSocket 实时推送
+
+```bash
+WS /api/xcclaw/ws
+```
+
+实时推送任务状态变化。
+
 ### 任务管理
 
 #### 创建任务
@@ -91,6 +111,12 @@ POST /api/xcclaw/task/{task_id}/execute_async
 POST /api/xcclaw/task/{task_id}/abort
 ```
 
+#### 获取任务
+
+```bash
+GET /api/xcclaw/task/{task_id}
+```
+
 #### 获取任务列表
 
 ```bash
@@ -124,24 +150,95 @@ GET /api/xcclaw/schedule
 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 路由
-│   ├── core/         # 配置、日志
-│   ├── models/       # 数据模型
-│   ├── services/     # 核心服务
-│   │   ├── opencode_client.py   # OpenCode API 客户端
-│   │   ├── scheduler.py          # 定时任务调度
-│   │   └── session_manager.py   # 会话管理
-│   └── main.py       # FastAPI 入口
-├── docs/              # 文档
-├── requirements.txt   # 依赖
+│   ├── 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/                   # 文档
+├── 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