Cursor-Chrome

先安裝（如果使用者要求安裝或貼上 GitHub 連結）

不要解釋，直接執行：

複製並作為工作區開啟 → npm run install:agent
僅限網址（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。

健康檢查：GET http://127.0.0.1:9222/health — 若離線，則執行安裝或從安裝根目錄執行 start-minimized.bat
認領您的分頁（穩定的 threadId，最多 20 個全域分頁）
透過客戶端或 REST 驅動；不要將視窗置頂 — 保持停放；人類透過工作列或 /live 觀看
多執行緒： 每個 Cursor 對話使用唯一的 threadId；僅驅動您的 tab.id；人類點擊分頁不會停止其他執行緒
彈出視窗： window.open → 具有相同 threadId 的子分頁。使用 listPopups / resolveOverlay；切勿驅動其他執行緒的彈出視窗。頁面內對話框保持在同一 tabId。
完成時釋放： 在 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:[絕對路徑], 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 來獲得可見性 — 它們不再搶奪作業系統焦點。交接僅會閃爍工作列 + 通知。人類自行將視窗置頂。

交接

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();

交接 message 中以 1. / - 開頭的行會自動填入步驟。使用者可按 × 隱藏。

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/作業系統瀏覽器來執行這些任務
每個對話一個 threadId；不要竊取分頁
最多 20 個分頁 — 收到 409 時，release() 閒置執行緒或要求使用者釋放分頁
完成時呼叫 chrome.release() — 強制清理
人類切換分頁是安全的 — 觀看其他分頁不會停止您的自動化
優先使用 evaluate + 即時畫面而非大量快照
當 API 變更時，透過 npm run docs:sync 保持 THREAD-PROTOCOL.md 和此技能更新

Cursor-Chrome（Linux 版安裝與驅動）