# Computer Control API

Computer Control API 让你能够远程控制已注册的计算机。目标机器上会运行一个小型 Agent（`screen-remote-agent`），轮询命令、执行命令并回传结果。这使 LLM 驱动的 GUI 自动化成为可能。

## 架构

```
┌─────────────┐  排队命令   ┌──────────┐  轮询  ┌─────────────────┐
│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │
│ (用户侧)    │              │  Server  │ ──────▶│ (在目标 PC 上) │
└─────────────┘              └──────────┘ 结果   └─────────────────┘
                                     ▲
                                     │
                              ┌─────────────┐
                              │  Human UI   │
                              │ (浏览器)    │
                              └─────────────┘
```

## 用户侧端点（Mind Key 或 JWT）

### GET /computers/list

列出所有已注册的计算机。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/list
```

### GET /computers/:id

获取单台计算机的详情。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

### POST /computers/install-code

为注册新计算机生成一个安装码。

```bash
curl -X POST https://synapse.schaefer.zone/computers/install-code \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"computer_name": "office-mac"}'
```

响应：`{ "install_code": "ic_xyz789", "expires_at": "..." }`

### POST /computers/:id/commands

为远程 Agent 排队一条待执行的命令。

```bash
curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "payload": {}
  }'
```

响应：`{ "command_id": "cmd_001", "status": "queued" }`

### GET /computers/:id/command（通过查询参数）

通过 GET 方式排队命令（用于简单场景）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"
```

### GET /computers/:id/commands

列出某台计算机最近的命令。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"
```

### GET /computers/:id/commands/:cid

获取某条具体命令的状态与结果。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001
```

### GET /computers/:id/screenshot

一次性操作：排队截图命令并等待最多 30 秒拿结果。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png
```

### POST /computers/:id/disable

禁用某台计算机（吊销其令牌，保留记录以备审计）。

```bash
curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/disable
```

### DELETE /computers/:id

永久删除某台计算机。

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

## Agent 侧端点（Computer Token）

以下端点由运行在目标机器上的 `screen-remote-agent` 使用。它们使用 Computer Token（由 `/computers/register` 返回），而不是 Mind Key。

### POST /computers/register

兑换安装码并获取 Computer Token。

```bash
curl -X POST https://synapse.schaefer.zone/computers/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ic_xyz789",
    "computer_name": "office-mac",
    "platform": "darwin",
    "platform_release": "14.5.0",
    "python": "3.12.4"
  }'
```

响应：`{ "computer_id": "comp_001", "computer_token": "ct_..." }`

> [!CRITICAL]
> 请妥善保存 `computer_token` — 它只显示一次，且所有 Agent 侧端点都需要它。

### GET /computers/me/poll

长轮询新命令。Agent 会在循环中调用此端点。

```bash
curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
     "https://synapse.schaefer.zone/computers/me/poll?wait=30"
```

如果有待执行命令，则立即返回；否则等待 `wait` 秒后返回。

### POST /computers/me/commands/:cid/result

提交某条命令的执行结果。

```bash
curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \
  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "result": { "screenshot_b64": "iVBORw0KG..." }
  }'
```

## 命令类型

| 类型 | Payload | 说明 |
|------|---------|-------------|
| `screenshot` | `{}` | 截屏为 PNG（base64） |
| `click` | `{x, y}` | 在指定坐标点击 |
| `move` | `{x, y}` | 将鼠标移动到指定坐标 |
| `type` | `{text}` | 在光标处输入文本 |
| `key` | `{keys: ["Ctrl","c"]}` | 按下组合键 |
| `scroll` | `{deltaX, deltaY}` | 滚动滚轮 |
| `drag` | `{fromX, fromY, toX, toY}` | 拖拽 |

## 常见模式：LLM 驱动的 GUI 自动化

```python
# LLM Agent 工作流
1. 列出计算机：GET /computers/list
2. 截屏：GET /computers/:id/screenshot
3. 分析截图（视觉模型）
4. 排队点击：POST /computers/:id/commands {type:"click", payload:{x,y}}
5. 等待结果：GET /computers/:id/commands/:cid
6. 重新截屏验证
7. 重复直到任务完成
```

## 下一步

- [Browser 代理](/docs/api/browser) — 用于浏览器自动化的独立服务
- [自托管 Agent 指南](/docs/guides/self-hosted-agents)