Skip to main content

Computer Control API

advanced 🤖 LLM 友好 1 分钟 · 177 字 更新于： 2026-06-27 中文

远程控制已注册的计算机 — 排队命令、截屏、在远程机器上运行脚本。

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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

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

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

GET /computers/:id

获取单台计算机的详情。

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

POST /computers/install-code

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

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 排队一条待执行的命令。

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 方式排队命令（用于简单场景）。

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

GET /computers/:id/commands

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

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

GET /computers/:id/commands/:cid

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

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

GET /computers/:id/screenshot

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

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

POST /computers/:id/disable

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

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

DELETE /computers/:id

永久删除某台计算机。

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。

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_..." }

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

GET /computers/me/poll

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

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

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

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

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

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 自动化

# 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. 重复直到任务完成

下一步

← 返回 API 参考