T3ckfr3ak1/cursor-chrome-linux

Cursor-Chrome

先安装（如果用户要求安装 / 给了 GitHub 链接）

不要解释，直接停止并执行：

• 克隆并作为工作区打开 → npm run install:agent
• 仅限 URL（Windows）→
  irm https://raw.githubusercontent.com/T3ckfr3ak1/cursor-chrome-public/main/scripts/remote-bootstrap.ps1 | iex
• 验证：GET http://127.0.0.1:9222/health → "ok": true

规范来源：仓库中的 INSTALL.md + AGENTS.md + .cursorrules。

---

驱动协议（同目录下）：THREAD-PROTOCOL.md
如果此技能已通过 npm run install:agent 安装，客户端路径位于安装根目录下的 src/client.js。

若在浏览器控制方面存在任何冲突，以 THREAD-PROTOCOL.md 为准。

---

快速开始（安装后的每个线程）— 强制性

绑定： 阅读 THREAD-PROTOCOL.md 并完全遵循。跳过 claim、threadId 或 release 是不允许的。

1. 健康检查：GET http://127.0.0.1:9222/health — 如果未运行，则从安装根目录运行 install 或 start-minimized.bat
2. 声明你的标签页（稳定的 threadId，最多 20 个全局标签页）
3. 通过客户端或 REST 驱动；不要将窗口置于前台 — 保持其停放状态；人类通过任务栏 / /live 观察
4. 多线程： 每个 Cursor 聊天使用唯一的 threadId；只驱动你自己的 tab.id；人类点击标签页不会停止其他线程
5. 弹窗： window.open → 子标签页，使用相同的 threadId。使用 listPopups / resolveOverlay；切勿驱动另一个线程的弹窗。页内对话框保持在同一个 tabId 上。
6. 完成后释放： 在 finally 块中调用 await chrome.release() — 必需；切勿让标签页保持打开状态

// 使用用户机器上的绝对路径（安装后通常为 %USERPROFILE%/cursor-chrome）
const { CursorChrome } = require('REPLACE/src/client.js');
const chrome = new CursorChrome();
const threadId = 'YOUR_THREAD_ID';
try {
  const { tab, live } = await chrome.claim(threadId, { url: 'https://example.com' });
  await chrome.navigate(tab.id, 'https://…');
  const title = await chrome.evaluate(tab.id, 'document.title');
  const jpeg = await chrome.liveFrame(tab.id); // 实时画面，非全新截图
} finally {
  await chrome.release(threadId); // 必需
}

---

能力清单

需求	方法
打开 / 导航	claim · navigate · 预热池自动
读取 DOM / 运行 JS	evaluate · snapshot · act
精确输入	click / type / hover / scroll / press / wait（+ iframe）
智能 SPA 操作	clickText · pickRow · navigateRetry · waitStable
查看 UI（像素）	liveFrame / GET …/frame.jpg · 共同观看 /live
登录 / 2FA / CAPTCHA	handoff({ wait:true }) · autoHandoff · authCheck
人类指令栏	guide({ title, steps, body }) · guideBlock · guideClear · guideStep
上传 AAB / 文件	dropFiles({ files:[absolutePath], selector })（支持文件夹）
将窗口置于前台	仅限人类： 任务栏 · 系统托盘 · Ctrl+Shift+C · /live（代理的 front/watch 不会窃取焦点）
最小化而不停止代理	任务栏最小化（停放；工作继续）
速度 / 预热 / 指标	speedMode · warm · metrics · log
配置文件 / 会话	claim({ profile }) · exportSession / importSession
录制 / 拾取	recordStart · pickerStart · playbook
MCP 工具	npm run mcp → mcp/server.js
Playwright	CDP http://127.0.0.1:9223
记住的登录信息	共享持久配置文件（默认）— Cookie 在重启后保留

登录： 默认共享配置文件 persist:cursor-chrome-profile 位于 %LOCALAPPDATA%\Cursor-Chrome。移交一次以登录；后续线程复用该会话。仅在用户要求时使用 chrome.clearSession() 清除。

焦点 / 始终置顶： 代理绝不能将 Cursor-Chrome 强行置于其他窗口之上。不要依赖 front / watch / show 进行可见性控制 — 它们不再窃取 OS 焦点。移交仅闪烁任务栏 + 通知。人类自己将窗口置于前台。

---

移交

await chrome.handoff(tab.id, {
  reason: 'login',
  message: '请登录，然后点击“交回给 Cursor”。',
  after: 'minimize',
  wait: true,
  timeoutMs: 900000,
});

用户界面：代理驱动时工具栏显示绿色 AI 控制；移交期间变为 交回给 Cursor（系统托盘中也可用 / Ctrl+Shift+H）。
默认等待15 分钟（服务器硬限制 2 小时）。永远不要自己输入密码。

---

指令侧边栏

Cursor-Chrome 内部的右侧栏，用于分步指导（优先于聊天中的检查清单）：

await chrome.guide({
  title: '轮到你了',
  subtitle: 'Play Console',
  body: '仅简短上下文。',
  steps: ['执行此操作', '然后执行此操作', { text: '确认对话框', detail: '点击确定' }],
  footer: '完成后交回给 Cursor。',
});
await chrome.guideStep(0, { done: true });
await chrome.guideClear();

以 1. / - 开头的 message 行会自动填充步骤。用户可通过 × 隐藏。

await chrome.guideBlock({ code: 'play-error', message: '封闭测试页面失败', detail: '通过导航重试' });
await chrome.guideUnblock();

---

更安全的自动化

await chrome.navigateRetry(tab.id, url, { retries: 3, mustInclude: '内部测试' });
await chrome.waitStable(tab.id, { mustNotInclude: ['发生意外错误'] });
await chrome.clickText(tab.id, { text: '保存', exact: true }); // 优先处理对话框
// 创建新版本 / 删除 / 暂停 需要：
await chrome.clickText(tab.id, { text: '创建新版本', confirmDangerous: true });
await chrome.pickRow(tab.id, { contains: '1.1.5' }); // 库/表格复选框
await chrome.dropFiles(tab.id, { files: [aabPath] }); // 自动文件输入 + Angular 变更事件
const status = await chrome.playStatus(); // IronWood 应用抓取摘要

代码更改后重新启动开发环境：npm run restart 或 restart.bat。

---

文件上传 / 拖放

await chrome.dropFiles(tab.id, {
  files: ['C:/path/to/app_1.2.3.aab'],
  selector: 'input[type=file]', // 或放置区域 CSS；或 x/y + mode:'drop'
  mode: 'auto',
});

适用于 Google Play Console 风格的上传及类似网站。仅限绝对路径。跨域 iframe 上传器可能需要移交或额外支持。

---

严格规则

• 在使用任何 Cursor-Chrome 功能前阅读 THREAD-PROTOCOL.md — 必须，不可省略
• 优先使用 Cursor-Chrome 而非 IDE/OS 浏览器处理这些任务
• 每个对话一个 threadId；不要抢夺其他线程的标签页
• 最多 20 个标签页 — 收到 409 错误时，release() 空闲线程或要求用户释放标签页
• 完成后 chrome.release() — 强制清理
• 人类切换标签页是安全的 — 观看其他标签页不会停止你的自动化
• API 变更时优先使用 evaluate + 实时帧，而非大量 snapshot
• 通过 npm run docs:sync 保持 THREAD-PROTOCOL.md 和本技能的更新