cloud-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Agents

Manage Cursor Cloud Agents through the REST API at

https://api.cursor.com/v0

通过

https://api.cursor.com/v0

的REST API管理Cursor Cloud Agents。

Prerequisites

前提条件

```
CURSOR_API_KEY
```
environment variable must be set
```
jq
```
must be installed (used by the helper script)
If the key is not set, ask the user to provide it or set it:
```
export CURSOR_API_KEY=<key>
```
Keys are created at https://cursor.com/settings

必须设置
```
CURSOR_API_KEY
```
环境变量
必须安装
```
jq
```
（辅助脚本会用到）
如果未设置密钥，请让用户提供或进行设置：
```
export CURSOR_API_KEY=<key>
```
密钥可在https://cursor.com/settings创建

Inferring the Repository

推断仓库信息

When the user does not specify a repo URL, infer it from the current working directory:

bash

git remote get-url origin

This gives you the GitHub URL to pass to

launch

. Also infer the current branch with

git branch --show-current

to use as the

ref

unless the user specifies otherwise.

当用户未指定仓库URL时，从当前工作目录推断：

bash

git remote get-url origin

这会得到可传递给

launch

命令的GitHub URL。此外，除非用户另有指定，否则使用

git branch --show-current

推断当前分支作为

ref

参数。

Error Handling

错误处理

If any step fails (API call, git operation, image encoding, etc.), do not attempt to automatically fix or retry. Instead, clearly report the error to the user: what command failed, the error message, and suggest what they can do about it. Let the user decide the next step.

如果任何步骤失败（API调用、Git操作、图片编码等），请勿尝试自动修复或重试。相反，应向用户清晰报告错误：哪个命令失败、错误信息，并建议他们可以采取的措施。让用户决定下一步操作。

Helper Script

辅助脚本

All API calls go through

scripts/cloud-agent.sh

(relative to this skill directory). Execute it via the Shell tool.

bash

SKILL_DIR="$HOME/.cursor/skills/cloud-agents"
"$SKILL_DIR/scripts/cloud-agent.sh" <command> [args...]

所有API调用都通过

scripts/cloud-agent.sh

（相对于此技能目录）执行。通过Shell工具运行它。

bash

SKILL_DIR="$HOME/.cursor/skills/cloud-agents"
"$SKILL_DIR/scripts/cloud-agent.sh" <command> [args...]

Commands Reference

命令参考

List agents

列出代理

bash

"$SKILL_DIR/scripts/cloud-agent.sh" list          # default 20
"$SKILL_DIR/scripts/cloud-agent.sh" list 50        # up to 100

Pipe through jq for readable output:

bash

"$SKILL_DIR/scripts/cloud-agent.sh" list | jq '.agents[] | {id, name, status, branch: .target.branchName, pr: .target.prUrl}'

bash

"$SKILL_DIR/scripts/cloud-agent.sh" list          # 默认显示20个
"$SKILL_DIR/scripts/cloud-agent.sh" list 50        # 最多显示100个

通过jq管道处理以获得易读的输出：

bash

"$SKILL_DIR/scripts/cloud-agent.sh" list | jq '.agents[] | {id, name, status, branch: .target.branchName, pr: .target.prUrl}'

Check agent status

检查代理状态

bash

"$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq .

Statuses:

CREATING

RUNNING

FINISHED

STOPPED

ERROR

bash

"$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq .

状态值：

CREATING

RUNNING

FINISHED

STOPPED

ERROR

Get conversation history

获取对话历史

bash

"$SKILL_DIR/scripts/cloud-agent.sh" conversation <agent_id> | jq '.messages[] | {type, text}'

bash

"$SKILL_DIR/scripts/cloud-agent.sh" conversation <agent_id> | jq '.messages[] | {type, text}'

Launch a new agent

启动新代理

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Your prompt here" \
  main \       # ref (optional, default: main)
  true \       # auto-create PR (optional, default: false)
  "" \         # model (optional, empty = auto)
  "my-branch"  # custom branch name (optional)

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Your prompt here" \
  main \       # ref（可选，默认值：main）
  true \       # 自动创建PR（可选，默认值：false）
  "" \         # 模型（可选，留空表示自动选择）
  "my-branch"  # 自定义分支名称（可选）

Launch agent on an existing PR

在现有PR上启动代理

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch-pr \
  "https://github.com/org/repo/pull/123" \
  "Fix the failing tests"

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch-pr \
  "https://github.com/org/repo/pull/123" \
  "Fix the failing tests"

Send follow-up

发送跟进指令

bash

"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> "Also add tests"

bash

"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> "Also add tests"

Attaching images

附加图片

Images can be appended as trailing file paths to

launch

launch-pr

, and

followup

(max 5). The script base64-encodes them and extracts dimensions via

sips

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Implement this design" \
  main false "" "" \
  /path/to/mockup.png /path/to/reference.jpg

bash

"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> \
  "The button should look like this instead" \
  /path/to/screenshot.png

When the user attaches an image in the conversation, resolve its absolute file path and pass it as a trailing argument.

图片可作为

launch

、

launch-pr

和

followup

命令的末尾文件路径参数（最多5张）。脚本会将其进行base64编码，并通过

sips

提取尺寸信息。

bash

"$SKILL_DIR/scripts/cloud-agent.sh" launch \
  "https://github.com/org/repo" \
  "Implement this design" \
  main false "" "" \
  /path/to/mockup.png /path/to/reference.jpg

bash

"$SKILL_DIR/scripts/cloud-agent.sh" followup <agent_id> \
  "The button should look like this instead" \
  /path/to/screenshot.png

当用户在对话中附加图片时，解析其绝对文件路径并作为末尾参数传递。

Stop / Delete

停止/删除代理

bash

"$SKILL_DIR/scripts/cloud-agent.sh" stop <agent_id>
"$SKILL_DIR/scripts/cloud-agent.sh" delete <agent_id>

bash

"$SKILL_DIR/scripts/cloud-agent.sh" stop <agent_id>
"$SKILL_DIR/scripts/cloud-agent.sh" delete <agent_id>

Utility

实用命令

bash

"$SKILL_DIR/scripts/cloud-agent.sh" me       # API key info
"$SKILL_DIR/scripts/cloud-agent.sh" models   # available models
"$SKILL_DIR/scripts/cloud-agent.sh" repos    # accessible GitHub repos (rate-limited: 1/min)

bash

"$SKILL_DIR/scripts/cloud-agent.sh" me       # 查看API密钥信息
"$SKILL_DIR/scripts/cloud-agent.sh" models   # 查看可用模型
"$SKILL_DIR/scripts/cloud-agent.sh" repos    # 查看可访问的GitHub仓库（调用频率限制：1次/分钟）

Pulling Agent Changes Locally

将代理变更拉取到本地

After an agent finishes (or while it's running), pull its changes into the local repo.

代理完成后（或运行中），可将其变更拉取到本地仓库。

Step 1: Get the agent's branch name

步骤1：获取代理的分支名称

bash

BRANCH=$("$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq -r '.target.branchName')

bash

BRANCH=$("$SKILL_DIR/scripts/cloud-agent.sh" status <agent_id> | jq -r '.target.branchName')

Step 2: Fetch and checkout

步骤2：拉取并切换分支

bash

git fetch --all
git checkout "$BRANCH"
git pull origin "$BRANCH"

bash

git fetch --all
git checkout "$BRANCH"
git pull origin "$BRANCH"

Step 3: Cherry-pick onto current branch (alternative)

步骤3：樱桃拣选到当前分支（替代方案）

If the user wants to apply agent commits onto their current branch instead of switching:

bash

git fetch --all
CURRENT=$(git branch --show-current)

如果用户希望将代理的提交应用到当前分支而非切换分支：

bash

git fetch --all
CURRENT=$(git branch --show-current)

Find commits the agent made (commits on agent branch not on current)

找出代理创建的提交（代理分支上有但当前分支没有的提交）

COMMITS=$(git log --oneline "$CURRENT".."origin/$BRANCH" --reverse --format='%H')

for commit in $COMMITS; do git cherry-pick "$commit" done

undefined

COMMITS=$(git log --oneline "$CURRENT".."origin/$BRANCH" --reverse --format='%H')

for commit in $COMMITS; do git cherry-pick "$commit" done

undefined

Step 4: Merge (alternative)

步骤4：合并（替代方案）

bash

git fetch --all
git merge "origin/$BRANCH"

bash

git fetch --all
git merge "origin/$BRANCH"

Step 5: Diff review

步骤5：差异审查

bash

git fetch --all
git diff HEAD..."origin/$BRANCH"

bash

git fetch --all
git diff HEAD..."origin/$BRANCH"

Workflow: Launch and Monitor

工作流：启动与监控

Launch the agent
Poll status every 15-30 seconds until
```
FINISHED
```
or
```
ERROR
```
If
```
FINISHED
```
, show summary and ask user how to apply changes (checkout / cherry-pick / merge)
If
```
ERROR
```
, show conversation to diagnose

启动代理
每15-30秒轮询一次状态，直到变为
```
FINISHED
```
或
```
ERROR
```
如果状态为
```
FINISHED
```
，显示摘要并询问用户如何应用变更（切换分支/樱桃拣选/合并）
如果状态为
```
ERROR
```
，显示对话历史以排查问题

Workflow: Review Running Agents

工作流：查看运行中的代理

List agents, filter by
```
RUNNING
```
status
For each, show id, name, branch, time since creation
Offer to check conversation, send follow-up, or stop

列出代理，筛选出
```
RUNNING
```
状态的代理
为每个代理显示ID、名称、分支、创建时长
提供查看对话历史、发送跟进指令或停止代理的选项