XCClaw/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 触发 → 创建会话 → 执行 → 桌面通知 → 销毁/保留会话

配置示例：

{
  "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 服务启动

# 启动 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 会话调用示例

# 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 会话管理

// 创建会话
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 任务调度

// 提交任务
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 定时任务

// 创建定时任务
POST /api/xcclaw/schedule
{
  name: string,
  cron: string,
  prompt: string,
  sessionType: "ephemeral" | "persistent",
  notifyOnComplete: boolean
}

// 列出定时任务
GET /api/xcclaw/schedules

// 删除定时任务
DELETE /api/xcclaw/schedule/:id

---

---