diff --git a/CDP.md b/CDP.md index a833d88..186cf3c 100644 --- a/CDP.md +++ b/CDP.md @@ -1,6 +1,6 @@ # Connecting OpenCLI via CDP (Remote/Headless Servers) -If you cannot use the Playwright MCP Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**. +If you cannot use the opencli Browser Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**. Because CDP binds to `localhost` by default for security reasons, accessing it from a remote server requires an additional networking tunnel. diff --git a/CDP.zh-CN.md b/CDP.zh-CN.md index 5641ed6..bf27409 100644 --- a/CDP.zh-CN.md +++ b/CDP.zh-CN.md @@ -1,6 +1,6 @@ # 通过 CDP 远程连接 OpenCLI (服务器/无头环境) -如果你无法使用 Playwright MCP Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。 +如果你无法使用 opencli Browser Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。 出于安全考虑，CDP 默认仅绑定在 `localhost` 的本地端口。所以，若是想让**远程服务器**调用本地的 CDP 服务，我们需要依靠一层额外的网络隧道。 diff --git a/CLI-ELECTRON.md b/CLI-ELECTRON.md index 5d752a1..ec298b9 100644 --- a/CLI-ELECTRON.md +++ b/CLI-ELECTRON.md @@ -8,7 +8,7 @@ Based on the successful automation of **Cursor**, **Codex**, **Antigravity**, ** ## Core Concept -Electron apps are essentially local Chromium browser instances. By exposing a debugging port (CDP — Chrome DevTools Protocol) at launch time, we can use Playwright to pierce through the UI layer, accessing and controlling all underlying state including React/Vue components and Shadow DOM. +Electron apps are essentially local Chromium browser instances. By exposing a debugging port (CDP — Chrome DevTools Protocol) at launch time, we can use the Browser Bridge to pierce through the UI layer, accessing and controlling all underlying state including React/Vue components and Shadow DOM. > **Note:** Not all desktop apps are Electron. WeChat (native Cocoa) and Feishu/Lark (custom Lark Framework) embed Chromium but do NOT expose CDP. For those apps, use the AppleScript + clipboard approach instead (see [Non-Electron Pattern](#non-electron-pattern-applescript)). @@ -109,7 +109,7 @@ Core techniques: ## Pitfalls & Gotchas 1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports: Codex=9222, ChatGPT=9224, Cursor=9226, ChatWise=9228, Notion=9230, Discord=9232 -2. **IPage abstraction**: OpenCLI wraps Playwright Page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT `page.keyboard.press()` +2. **IPage abstraction**: OpenCLI wraps the browser page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT direct DOM APIs 3. **Timing**: Always add `await page.wait(0.5)` to `1.0` after DOM mutations. Returning too early disconnects prematurely 4. **AppleScript requires Accessibility**: Terminal app must be granted permission in System Settings → Privacy & Security → Accessibility diff --git a/CLI-EXPLORER.md b/CLI-EXPLORER.md index 73191ed..b619c05 100644 --- a/CLI-EXPLORER.md +++ b/CLI-EXPLORER.md @@ -9,12 +9,12 @@ --- -## AI Agent 开发者必读：用 Playwright MCP Bridge 探索 +## AI Agent 开发者必读：用浏览器探索 > [!CAUTION] -> **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！** +> **你（AI Agent）必须通过浏览器打开目标网站去探索！** > 不要只靠 `opencli explore` 命令或静态分析来发现 API。 -> 你拥有 Playwright MCP 工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。 +> 你拥有浏览器工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。 ### 为什么？ @@ -36,7 +36,7 @@ | ❌ 错误做法 | ✅ 正确做法 | |------------|------------| -| 只用 `opencli explore` 命令，等结果自动出来 | 用 MCP Bridge 打开浏览器，主动浏览页面 | +| 只用 `opencli explore` 命令，等结果自动出来 | 用浏览器工具打开页面，主动浏览 | | 直接在代码里 `fetch(url)`，不看浏览器实际请求 | 先在浏览器中确认 API 可用，再写代码 | | 页面打开后直接抓包，期望所有 API 都出现 | 模拟点击交互（展开评论/切换标签/加载更多） | | 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 | diff --git a/TESTING.md b/TESTING.md index 59fd647..688441b 100644 --- a/TESTING.md +++ b/TESTING.md @@ -105,10 +105,10 @@ npx vitest src/ ### 浏览器命令本地测试须知 -- 无 `PLAYWRIGHT_MCP_EXTENSION_TOKEN` 时，opencli 自动启动一个独立浏览器实例 +- opencli 通过 Browser Bridge 扩展连接已运行的 Chrome 浏览器 - `browser-public.test.ts` 使用 `tryBrowserCommand()`，站点反爬导致空数据时 warn + pass - `browser-auth.test.ts` 验证 **graceful failure**（不 crash 不 hang 即通过） -- 如需测试完整登录态，保持 Chrome 登录态 + 设置 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`，手动跑对应测试 +- 如需测试完整登录态，保持 Chrome 登录态并安装 Browser Bridge 扩展，手动跑对应测试 --- @@ -202,12 +202,12 @@ steps: ## 浏览器模式 -opencli 根据 `PLAYWRIGHT_MCP_EXTENSION_TOKEN` 环境变量自动选择模式： +opencli 通过 Browser Bridge 扩展连接浏览器： -| 条件 | 模式 | MCP 参数 | 使用场景 | -|---|---|---|---| -| Token 已设置 | Extension 模式 | `--extension` | 本地用户，连接已登录的 Chrome | -| Token 未设置 | Standalone 模式 | （无特殊 flag） | CI 或无扩展环境，自启浏览器 | +| 条件 | 模式 | 使用场景 | +|---|---|---| +| 扩展已安装 | Extension 模式 | 本地用户，连接已登录的 Chrome | +| 扩展未安装 | CLI 报错提示安装 | 需要安装 Browser Bridge 扩展 | CI 中使用 `OPENCLI_BROWSER_EXECUTABLE_PATH` 指定真实 Chrome 路径： diff --git a/src/clis/chatgpt/README.md b/src/clis/chatgpt/README.md index 7d9b0d0..7d491e2 100644 --- a/src/clis/chatgpt/README.md +++ b/src/clis/chatgpt/README.md @@ -35,7 +35,7 @@ export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224" ## How It Works - **AppleScript mode**: Uses `osascript` and `pbcopy`/`pbpaste` for clipboard-based text transfer. No remote debugging port needed. -- **CDP mode**: Connects via Playwright to the Electron renderer process for direct DOM manipulation. +- **CDP mode**: Connects via Chrome DevTools Protocol to the Electron renderer process for direct DOM manipulation. ## Limitations diff --git a/src/clis/chatgpt/README.zh-CN.md b/src/clis/chatgpt/README.zh-CN.md index cf30a16..4a65698 100644 --- a/src/clis/chatgpt/README.zh-CN.md +++ b/src/clis/chatgpt/README.zh-CN.md @@ -35,7 +35,7 @@ export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224" ## 工作原理 - **AppleScript 模式**：使用 `osascript` 和 `pbcopy`/`pbpaste` 进行剪贴板文本传输，无需远程调试端口。 -- **CDP 模式**：通过 Playwright 连接到 Electron 渲染进程，直接操作 DOM。 +- **CDP 模式**：通过 Chrome DevTools Protocol 连接到 Electron 渲染进程，直接操作 DOM。 ## 限制