cursor-cloud-agents

Cursor Cloud Agents Skill 是一个基于 Bash 的命令行工具，专为将 Cursor AI 的智能编程能力扩展到 GitHub 仓库而设计。该技能通过封装 Cursor Cloud Agents HTTP API，允许用户将编码任务委派给云端 AI Agent，实现代码生成、测试编写、文档创建和自动 Pull Request 提交等自动化工作流。

核心用法方面，该工具提供了四种主要工作模式：Fire-and-Forget 模式适合独立运行的探索性任务；Supervised Dispatch 模式支持轮询监控并在完成后报告结果；Iterative Collaboration 模式允许通过多次 follow-up 指令精化输出；Background Mode 则专为长时间运行的任务设计，支持后台执行和日志追踪。用户通过简单的 CLI 命令即可启动 Agent，指定目标仓库、任务描述、模型选择和分支管理，系统会自动处理认证、状态监控和结果获取。

显著优点包括：完善的异步执行机制避免阻塞终端，支持 GPT-5.2、Claude-4 等多种模型选择，本地实施 1req/s 的速率限制保护 API 配额，内置 60 秒缓存机制提升重复查询性能，以及健全的错误处理体系（定义了 6 种标准退出码）。背景任务功能特别适合 CI/CD 集成，可设置最大运行时间防止资源无限占用。

潜在缺点与局限性不容忽视：首先，该技能仅支持 GitHub 仓库，无法处理本地文件或私有 Git 托管平台；其次，依赖用户的 Cursor 订阅等级，免费版仅支持 1 个并发 Agent 和基础模型；此外，缓存数据以明文形式存储在 ~/.cache/cursor-api/，虽方便调试但存在隐私泄露风险；最后，作为 T3 级社区来源工具，虽然代码质量通过安全审计，但长期维护稳定性仍需观察。

适合的目标群体主要包括：需要批量处理代码重构或生成任务的中大型开发团队、寻求 CI/CD 自动化集成的 DevOps 工程师、希望获得"第二意见"代码审查的独立开发者，以及需要异步处理复杂编程任务（如全库重构）的技术负责人。

使用风险方面，除 API 密钥泄露的常规风险外，需特别注意：未加密的本地缓存可能包含代码片段或仓库结构信息；长时间后台任务可能持续消耗 Cursor 订阅配额；网络依赖性强，完全依赖 Cursor 云服务可用性；以及并发限制可能导致大规模自动化任务排队等待。建议生产环境使用时定期清理缓存、监控配额使用，并为关键任务设置合理的最大运行时间限制。

核心用法

Cursor Cloud Agents Skill 是 OpenClaw 的封装层，用于调用 Cursor Cloud Agents HTTP API。核心工作流程围绕 launch-status-followup 循环展开：

# 启动代理（默认使用 gpt-5.2）
cursor-api.sh launch --repo owner/repo --prompt "为 auth 模块添加测试"

# 监控状态
cursor-api.sh status <agent-id>

# 查看完整对话历史
cursor-api.sh conversation <agent-id>

# 迭代优化
cursor-api.sh followup <agent-id> --prompt "补充边界条件测试"

支持四种工作模式：Fire-and-Forget（异步委托）、Supervised Dispatch（轮询监控）、Iterative Collaboration（多轮迭代）以及 Background Mode（后台长时间任务，支持 --max-runtime 超时控制）。

---

显著优点

1. 深度 GitHub 集成

• 原生支持仓库访问验证、自动 PR 创建、分支管理
• 无需本地克隆，直接在云端完成代码变更

2. 灵活的模型选择

• 默认 GPT-5.2，支持 Claude-4-opus 等模型切换
• 按任务复杂度智能匹配算力

3. 企业级运维特性

• 本地速率限制（1 req/sec）避免 API 限流
• 60 秒缓存机制 + --no-cache 强制刷新
• 标准化退出码（0-5 对应 Success/Error/Auth/RateLimit/RepoAccess/Args）

4. 极简依赖

• 仅依赖 bash、curl、jq、base64 四个系统标准工具
• 零第三方库，供应链攻击风险极低

5. 并发与配额管理

• 清晰的分层限制：Free(1)/Pro(3)/Ultra(5) 并发代理
• cursor-api.sh usage 实时监控消耗

---

潜在缺点与局限性

1. GitHub 仓库强制依赖

• 不支持本地文件系统操作，必须通过 owner/repo 格式
• 需预先安装 Cursor GitHub App 并授权仓库

2. 异步非实时

• 代理启动需 1-2 分钟，复杂任务可能耗时数小时
• 不支持流式输出，需轮询或后台模式获取结果

3. API Key 多源暴露面

• 支持 5 处配置读取（环境变量、3 个 .env 文件、~/.cursor/config.json）
• 虽优先级设计合理（环境变量优先），但配置分散增加泄露风险

4. 缓存未加密

• ~/.cache/cursor-api/ 以明文存储 API 响应
• 多用户系统需手动设置 700 权限

5. 背景任务 PID 竞争

• 使用 kill -0 检测进程存在性，极端情况下存在 PID 复用风险

---

适合人群

• 独立开发者：已有 Cursor Pro/Ultra 订阅，希望将重复编码任务自动化
• 中小团队 Tech Lead：需要批量生成测试、文档或执行标准化重构
• DevOps 工程师：CI/CD 流水线中集成 AI 代码审查或补丁生成
• 开源维护者：处理 Issue 标签驱动的自动化 PR 提交

---

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 代码注入 | 低 | 输入经正则验证，`set -euo pipefail` 严格模式 |

| 密钥泄露 | 中 | 建议 `chmod 600` 保护配置文件，优先使用环境变量 |

| 网络劫持 | 低 | HTTPS/TLS 1.2+，仅访问官方 api.cursor.com |

| 供应链攻击 | 极低 | 无第三方依赖，纯系统工具链 |

| 并发超限 | 中 | 需监控 `usage` 输出，避免 HTTP 429 |

| 背景任务失控 | 低 | 建议始终设置 `--max-runtime`，默认 24 小时上限 |

关键建议：生产环境启用 --max-runtime 限制，定期清理 ~/.cache/cursor-api/，敏感仓库优先使用环境变量注入 CURSOR_API_KEY。