cursor-bridge：OpenClaw ↔ Cursor 桥接

将 OpenClaw 的自然语言任务转交本地 Cursor 执行（Playwright + CDP），利用本地/付费模型完成编码，缓解云端额度与限流问题。

---

项目愿景与背景

• 目标：完整 Cursor 自动化桥接，使 OpenClaw 能调用本地 Cursor 完成编码任务。
• 方案：Playwright + CDP 连接 Cursor（--remote-debugging-port=9222），通过唯一入口 npm start 启动 HTTP API，使用 npm run cli 或直接调用 API 提交任务。
• 前置：Cursor 须从系统终端以调试端口启动，不可用 Cursor 内置终端。

---

项目结构

cursor-bridge/
├── config.json          # 运行配置（workspace、debug_port、mode_shortcuts 等）
├── package.json
├── package-lock.json
├── README.md            # 本文档
├── SKILL.md             # OpenClaw 技能定义（供斜杠命令发现）
├── src/
│   ├── server.js        # 唯一入口：HTTP API（/api/task、/api/batch、/api/health）
│   ├── cli.js           # CLI 客户端（调用上述 API）
│   ├── TaskExecutor.js  # 任务执行（上下文、验证、自动修复）
│   ├── CursorAutomation.js
│   ├── contextManager.js
│   ├── resultVerifier.js
│   ├── batchExecutor.js
│   ├── pipelineSteps.js
│   ├── selectors.js     # 界面选择器（随 Cursor 版本可调）
│   └── utils.js
└── examples/
    ├── example_task.md  # 示例任务描述
    └── batch-example.json

---

安装与前置条件

1. Node.js 18+，在项目根目录执行：

   npm install
   npx playwright install chromium

2. Cursor 用调试端口启动（在系统 PowerShell/cmd 执行，勿用 Cursor 内置终端）：

   & "d:\Cursor\resources\app\bin\cursor.cmd" --remote-debugging-port=9222

3. 在 config.json 中可配置 debug_port（默认 9222），或环境变量 CURSOR_DEBUG_PORT。

---

快速开始（单一入口）

入口：仅需启动服务 npm start，所有能力通过 HTTP API 或 CLI（CLI 内部调用同一 API）使用。

1. 系统终端：启动 Cursor（见上条命令），保持窗口不关。
2. 启动桥接（唯一进程入口）：

   npm start

   看到 🚀 Cursor Bridge API 运行在 http://localhost:3000 即成功。
3. 提交任务（任选其一）：
   • CLI：npm run cli -- agent "创建一个 Python 计算器"
   • 或 HTTP：POST http://localhost:3000/api/task，Body { "task": "任务描述", "mode": "agent" }

可选：指定端口时用 PORT=3001 npm start，CLI 用 CURSOR_BRIDGE_URL=http://localhost:3001 npm run cli -- agent "任务"。

---

配置

config.json 示例：

{
  "cursor_path": "cursor",
  "workspace": "D:\\Openclaw_project",
  "plan_output": "plan.md",
  "timeout_seconds": 900,
  "debug_port": 9222,
  "mode_shortcuts": {
    "agent": "Control+i",
    "plan": ["Control+p", "l"],
    "ask": ["Control+a", "Control+k"],
    "debug": ""
  }
}

• workspace：Cursor 工作目录
• plan_output：Plan 模式生成计划文件路径
• mode_shortcuts：模式切换快捷键（Playwright 格式，如 Control+Shift+a）。在 Cursor 中通过命令面板查看各模式快捷键后填入。
• debug_log_path（可选）：调试日志文件路径；为空或未配置时不写日志文件；配置为非空字符串时写入该路径（相对 process.cwd() 或绝对路径）。
• enable_telemetry（可选）：是否启用对外埋点请求；默认不配置或为 false，不发起对外请求。

环境变量：CURSOR_BRIDGE_CURSOR_PATH、CURSOR_BRIDGE_WORKSPACE、CURSOR_BRIDGE_TIMEOUT、CURSOR_DEBUG_PORT、CURSOR_BRIDGE_URL（CLI 请求的 API 基地址）。

---

HTTP API

• POST /api/task
  Body: { "task": "任务描述", "mode": "agent"|"plan"|"ask", "contextFiles"?: string[], "contextDirs"?: string[], "continueConversation"?: boolean, "runVerification"?: boolean, "verificationCommand"?: string, "autoFixRetries"?: number, "workspace"?: string }
  Response: { "status": "success"|"error", "result?", "files?", "verification?", "error?", "timestamp" }
• POST /api/batch
  Body: { "tasks": [ { "task", "mode?", "contextFiles?", "contextDirs?", "dependsOn"?: number[] }, ... ], "stopOnError"?: boolean }
  Response: { "status", "results": [...], "summary": { total, success, failed }, "timestamp" }
• GET /api/health
  健康检查

---

CLI 用法与示例

# Agent / Plan / Ask
npm run cli -- agent "创建一个 Python 计算器"
npm run cli -- plan "创建一个 Python 计算器"
npm run cli -- ask "解释这段代码的作用"

# 输出到文件
npm run cli -- agent "任务" -o result.json
npm run cli -- agent "任务" -o result.md

# 上下文、验证、自动修复
npm run cli -- agent "为 index.js 添加错误处理" -f src/index.js -d src/lib --verify --auto-fix 2

# 批量任务
npm run cli -- batch examples/batch-example.json

选项：-f/--context-file、-d/--context-dir、--verify、--verification-command、--auto-fix N、--continue、-w/--workspace、-o/--output。

---

高级功能

能力	说明	API / CLI
上下文	为任务附带 @file / @folder	contextFiles、contextDirs；CLI：-f、-d
续聊	在现有对话后追加消息	continueConversation: true；CLI：--continue
结果验证	任务后自动跑测试（npm test / pytest 或自定义）	runVerification、verificationCommand；CLI：--verify、--verification-command
自动修复	验证失败时把错误反馈给 Cursor 并重试	autoFixRetries；CLI：--auto-fix N
批量任务	按顺序执行多任务，支持 dependsOn、遇错即停	POST /api/batch；CLI：batch <json-file>

批量 JSON 格式见 examples/batch-example.json。

扩展流水线：任务执行由可插拔的流水线步骤驱动（见 src/pipelineSteps.js）。需要新增步骤（如执行前拉模板、执行后提交）时，可在该文件中增加 step 并加入 defaultSteps，或通过 new TaskExecutor({ pipelineSteps: [...defaultSteps, myStep] }) 注入；步骤间通过上下文对象 ctx 传递数据，设置 ctx.return 即结束并返回。

---

故障排查

现象	处理
并发	同一时间仅支持一个任务在执行，多客户端请串行或自行排队，避免同时调用 /api/task 或 /api/batch
ECONNREFUSED 127.0.0.1:9222	用系统终端重新启动 Cursor（--remote-debugging-port=9222）
请求失败 / ECONNRESET	确认终端 A 的 npm start 在运行
未找到发送按钮	检查 src/selectors.js 中发送按钮选择器，或重启 server
Cursor 升级后无法定位输入框/发送按钮/回复内容	检查并更新 src/selectors.js
等待助手回复超时	确认 Cursor 有回复；可查看根目录 debug-*.log（若生成）
端口被占用	使用环境变量 PORT、CURSOR_BRIDGE_URL 换端口

---

OpenClaw 集成

• 将本目录挂载为 OpenClaw 技能，确保 SKILL.md 被识别。
• 调用方式：斜杠命令传入任务，或 HTTP POST /api/task。技能说明与参数见 SKILL.md。

---

约定说明

示例任务「创建一个 Python 计算器」用于测试 Cursor Bridge 功能（连接、输入、发送、回复提取），非要求实际生成计算器。