docs: add README and docs folder
- 添加 README.md 项目文档 - 创建 docs 文件夹存放系统设计文档
This commit is contained in:
332
docs/xcclaw-system.md
Normal file
332
docs/xcclaw-system.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# XCClaw 系统设计
|
||||
|
||||
## 一、系统定位
|
||||
|
||||
XCClaw 基于 OpenCode Agent，是桌面本地的个人 AI 助手
|
||||
|
||||
**核心理念**：以 OpenCode 会话为最小执行单元，通过多种触发方式调度任务，实现本地化的 AI 任务执行系统。
|
||||
|
||||
---
|
||||
|
||||
## 二、核心概念
|
||||
|
||||
### 最小执行单元：OpenCode 会话
|
||||
|
||||
1 个会话 = 1 个独立的工作空间 + 1 个对话上下文 + 执行能力
|
||||
|
||||
```
|
||||
会话生命周期：
|
||||
创建 → 加载上下文 → 执行 Prompt → 流式输出 → 返回结果 → 销毁/保留
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、调度模式
|
||||
|
||||
| 模式 | 描述 | 触发方式 | 适用场景 |
|
||||
|------|------|----------|----------|
|
||||
| **即时模式** | 立即创建会话，执行完销毁 | 快捷键/按钮 | 简单询问、快速任务 |
|
||||
| **常驻模式** | 启动持久会话，可多次交互 | 托盘/面板 | 持续对话、复杂任务 |
|
||||
| **定时模式** | 定时创建会话执行 | Cron 配置 | 定期数据抓取、报告生成 |
|
||||
| **队列模式** | 任务进入队列，依次执行 | API/面板 | 批量处理、长链任务 |
|
||||
|
||||
---
|
||||
|
||||
## 四、会话类型
|
||||
|
||||
### 1. 即时会话（Ephemeral Session）
|
||||
|
||||
- 每次任务创建新会话
|
||||
- 执行完成后自动销毁
|
||||
- 适合：简单任务、一次性操作
|
||||
- 资源占用：低
|
||||
|
||||
### 2. 常驻会话（Persistent Session）
|
||||
|
||||
- 启动后保持运行状态
|
||||
- 可多次交互，累积上下文
|
||||
- 适合：复杂项目、多轮对话
|
||||
- 资源占用：高
|
||||
|
||||
### 3. 定时会话（Scheduled Session）
|
||||
|
||||
- 由定时器触发创建
|
||||
- 可配置是否保留会话
|
||||
- 适合：周期性任务
|
||||
- 资源占用：按需
|
||||
|
||||
---
|
||||
|
||||
## 五、任务调度
|
||||
|
||||
### 5.1 即时任务调度
|
||||
|
||||
```
|
||||
用户触发 → 创建会话 → 执行 → 返回结果 → 销毁会话
|
||||
```
|
||||
|
||||
**示例**：
|
||||
- 用户按下 Ctrl+Shift+C 快捷键
|
||||
- 弹出输入框，输入 "帮我整理桌面文件"
|
||||
- 系统创建即时会话执行
|
||||
- 完成后显示结果，自动销毁会话
|
||||
|
||||
### 5.2 定时任务调度
|
||||
|
||||
```
|
||||
Cron 触发 → 创建会话 → 执行 → 桌面通知 → 销毁/保留会话
|
||||
```
|
||||
|
||||
**配置示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "晨间新闻摘要",
|
||||
"trigger": "0 9 * * *",
|
||||
"prompt": "帮我抓取今天的技术新闻摘要",
|
||||
"sessionType": "ephemeral",
|
||||
"notifyOnComplete": true
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 任务链调度
|
||||
|
||||
```
|
||||
任务A → 结果传递给任务B → 结果传递给任务C → 汇总结果
|
||||
```
|
||||
|
||||
**示例场景**：整理项目代码结构
|
||||
|
||||
```
|
||||
Step 1: 会话A执行 "列出 src 目录下所有文件"
|
||||
Step 2: 会话B继承上下文 "分析 main.ts 的核心逻辑"
|
||||
Step 3: 会话C继承上下文 "生成代码结构文档"
|
||||
Step 4: 汇总结果 → 桌面通知用户
|
||||
```
|
||||
|
||||
**关键设计点**：
|
||||
|
||||
- 链式调用：会话 N 的输出作为会话 N+1 的输入
|
||||
- 上下文传递：可选择继承上一个会话的上下文，或开启全新会话
|
||||
- 错误处理：某步骤失败可选择重试或跳过
|
||||
|
||||
### 5.4 队列调度
|
||||
|
||||
```
|
||||
用户提交多个任务
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 任务队列 │
|
||||
│ [1] [2] [3]... │ ← 按优先级/时间排序
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼ 串行/并行执行
|
||||
┌─────────────────┐
|
||||
│ 执行单元 │ ← OpenCode 会话
|
||||
│ 会话A → 完成 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 任务2 开始 │
|
||||
│ 会话B → ... │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、触发入口
|
||||
|
||||
| 入口 | 操作 | 行为 |
|
||||
|------|------|------|
|
||||
| **快捷键** | 按下 Ctrl+Shift+C | 弹出输入框 → 创建即时会话 |
|
||||
| **托盘图标** | 点击"新对话" | 创建常驻会话 |
|
||||
| **Web 面板** | 点击"执行"按钮 | 根据配置创建会话 |
|
||||
| **定时任务** | Cron 触发 | 创建临时会话，执行完销毁 |
|
||||
| **外部 API** | POST /api/task | 根据 payload 创建会话 |
|
||||
|
||||
---
|
||||
|
||||
## 七、OpenCode 服务集成
|
||||
|
||||
### 7.1 服务启动
|
||||
|
||||
```bash
|
||||
# 启动 OpenCode HTTP 服务
|
||||
opencode serve --port 4096 --hostname 127.0.0.1
|
||||
```
|
||||
|
||||
服务默认端口 4096，支持参数：
|
||||
- `--port`: 端口号
|
||||
- `--hostname`: 监听地址
|
||||
- `--cors`: 允许跨域访问（可多次指定）
|
||||
|
||||
### 7.2 会话管理 API
|
||||
|
||||
OpenCode 服务器提供 REST API 进行会话管理：
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| `GET` | `/api/xcclaw/session` | 列出所有会话 |
|
||||
| `POST` | `/api/xcclaw/session` | 创建新会话 (`{ parentID?, title? }`) |
|
||||
| `GET` | `/api/xcclaw/session/:id` | 获取会话详情 |
|
||||
| `DELETE` | `/api/xcclaw/session/:id` | 删除会话 |
|
||||
| `PATCH` | `/api/xcclaw/session/:id` | 更新会话属性 |
|
||||
| `GET` | `/api/xcclaw/session/:id/children` | 获取子会话 |
|
||||
| `POST` | `/api/xcclaw/session/:id/abort` | 中止运行中的会话 |
|
||||
| `POST` | `/api/xcclaw/session/:id/fork` | 叉一个会话 |
|
||||
|
||||
### 7.3 消息交互 API
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| `POST` | `/api/xcclaw/session/:id/message` | 发送消息并等待响应 |
|
||||
| `POST` | `/api/xcclaw/session/:id/prompt_async` | 异步发送消息（不等待响应） |
|
||||
| `GET` | `/api/xcclaw/session/:id/message` | 列出消息 (`?limit=50`) |
|
||||
| `GET` | `/api/xcclaw/session/:id/message/:messageID` | 获取消息详情 |
|
||||
| `POST` | `/api/xcclaw/session/:id/command` | 执行 slash 命令 |
|
||||
| `POST` | `/api/xcclaw/session/:id/shell` | 运行 shell 命令 |
|
||||
|
||||
### 7.4 会话调用示例
|
||||
|
||||
```bash
|
||||
# 1. 创建会话
|
||||
curl -X POST http://localhost:4096/api/xcclaw/session \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "整理桌面文件"}'
|
||||
|
||||
# 2. 发送消息执行任务
|
||||
curl -X POST http://localhost:4096/api/xcclaw/session/{session-id}/message \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"parts": [{"type": "text", "text": "帮我整理桌面文件"}]}'
|
||||
|
||||
# 3. 异步任务（不等待响应）
|
||||
curl -X POST http://localhost:4096/api/xcclaw/session/{session-id}/prompt_async \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"parts": [{"type": "text", "text": "执行复杂任务"}]}'
|
||||
|
||||
# 4. 查询会话状态
|
||||
curl http://localhost:4096/api/xcclaw/session/status
|
||||
|
||||
# 5. 中止会话
|
||||
curl -X POST http://localhost:4096/api/xcclaw/session/{session-id}/abort
|
||||
```
|
||||
|
||||
### 7.5 任务调度与 OpenCode 会话映射
|
||||
|
||||
```
|
||||
即时任务 → POST /api/xcclaw/session → POST /api/xcclaw/session/:id/message → 销毁
|
||||
常驻任务 → POST /api/xcclaw/session → 保留 sessionID → 多次 POST /api/xcclaw/session/:id/message
|
||||
定时任务 → Cron → POST /api/xcclaw/session → POST /api/xcclaw/session/:id/prompt_async → 通知
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、结果反馈
|
||||
|
||||
| 任务类型 | 反馈方式 |
|
||||
|----------|----------|
|
||||
| 简单任务 | 面板直接显示 |
|
||||
| 耗时任务 | 进度条 + 实时输出 |
|
||||
| 定时任务 | 桌面通知 |
|
||||
| 长链任务 | 每个步骤结果 + 最终汇总 |
|
||||
|
||||
---
|
||||
|
||||
## 九、持久化设计
|
||||
|
||||
```
|
||||
~/Documents/XCDesktop/xcclaw/
|
||||
├── tasks/
|
||||
│ ├── pending.json # 待执行任务
|
||||
│ ├── running.json # 正在执行
|
||||
│ └── history.json # 执行历史
|
||||
├── sessions/
|
||||
│ ├── {session-id}.json # 会话上下文
|
||||
│ └── config.json # 会话配置
|
||||
├── schedules/
|
||||
│ └── crontasks.json # 定时任务配置
|
||||
├── workspace/ # 工作目录
|
||||
│ ├── AGENTS.md
|
||||
│ ├── TOOLS.md
|
||||
│ └── SOUL.md
|
||||
└── config.json # 系统配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、核心 API 设计
|
||||
|
||||
### 10.1 会话管理
|
||||
|
||||
```typescript
|
||||
// 创建会话
|
||||
POST /api/xcclaw/session
|
||||
{
|
||||
type: "ephemeral" | "persistent" | "scheduled",
|
||||
prompt?: string,
|
||||
context?: object,
|
||||
options?: {
|
||||
model?: string,
|
||||
tools?: string[]
|
||||
}
|
||||
}
|
||||
|
||||
// 获取会话状态
|
||||
GET /api/xcclaw/session/:id
|
||||
|
||||
// 发送消息
|
||||
POST /api/xcclaw/session/:id/message
|
||||
{
|
||||
content: string
|
||||
}
|
||||
|
||||
// 终止会话
|
||||
POST /api/xcclaw/session/:id/abort
|
||||
```
|
||||
|
||||
### 10.2 任务调度
|
||||
|
||||
```typescript
|
||||
// 提交任务
|
||||
POST /api/xcclaw/task
|
||||
{
|
||||
type: "immediate" | "persistent" | "scheduled",
|
||||
prompt: string,
|
||||
schedule?: string, // cron 表达式
|
||||
chain?: ChainConfig, // 任务链配置
|
||||
options?: TaskOptions
|
||||
}
|
||||
|
||||
// 获取任务状态
|
||||
GET /api/xcclaw/task/:id
|
||||
|
||||
// 取消任务
|
||||
DELETE /api/xcclaw/task/:id
|
||||
```
|
||||
|
||||
### 10.3 定时任务
|
||||
|
||||
```typescript
|
||||
// 创建定时任务
|
||||
POST /api/xcclaw/schedule
|
||||
{
|
||||
name: string,
|
||||
cron: string,
|
||||
prompt: string,
|
||||
sessionType: "ephemeral" | "persistent",
|
||||
notifyOnComplete: boolean
|
||||
}
|
||||
|
||||
// 列出定时任务
|
||||
GET /api/xcclaw/schedules
|
||||
|
||||
// 删除定时任务
|
||||
DELETE /api/xcclaw/schedule/:id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user