XCClaw/docs/xcclaw-system.md

# 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
```

---

---