{"slug":"yan-labs-opencli","name":"opencli","description":"用 OpenCLI 驱动用户本机那个真实的、已登录的 Chrome，或调用它的 160+ 站点 adapter。任何需要登录态的页面操作都从这里开始——读登录后的后台、抓没有 API 的表格、填表提交、跑一个站点命令、把页面数据取回来。也覆盖会话命名与租约纪律（\"我的标签页被别人抢了\"）、批量取数与落盘、adapter 的编写与自修复、opencli doctor 排障。用户提到 opencli、浏览器自动化、用我的浏览器、驱动 Chrome、登录态、抓后台数据、抓表格、导出报表、填表、自动点击、截图、adapter、doctor 报错、session 撞名、标签页被抢、tab 泄漏，或说\"打开这个页面看看\"\"帮我登录后台查一下\"\"这个站没有 API\"时，务必使用本 Skill。只要动作会落在浏览器上，先读这里再动手。","long_description":"---\nname: opencli\ndescription: 用 OpenCLI 驱动用户本机那个真实的、已登录的 Chrome，或调用它的 160+ 站点 adapter。任何需要登录态的页面操作都从这里开始——读登录后的后台、抓没有 API 的表格、填表提交、跑一个站点命令、把页面数据取回来。也覆盖会话命名与租约纪律（\"我的标签页被别人抢了\"）、批量取数与落盘、adapter 的编写与自修复、opencli doctor 排障。用户提到 opencli、浏览器自动化、用我的浏览器、驱动 Chrome、登录态、抓后台数据、抓表格、导出报表、填表、自动点击、截图、adapter、doctor 报错、session 撞名、标签页被抢、tab 泄漏，或说\"打开这个页面看看\"\"帮我登录后台查一下\"\"这个站没有 API\"时，务必使用本 Skill。只要动作会落在浏览器上，先读这里再动手。\nmetadata:\n version: \"1.2.0\"\n---\n\n# OpenCLI\n\nOpenCLI 把任意网站、Electron 桌面应用和外部 CLI 收敛成一条 `opencli `，\n再加一条 `opencli browser ` 用来现场驱动浏览器。\n\n它走的是**用户本机那个真实的、已登录的 Chrome**（浏览器扩展 + 本地守护进程），\n不是无痕实例、不是沙箱。这一个事实决定了本 Skill 里几乎所有规则。\n\n本 Skill 面向的是我们自己维护的 fork（`yan-labs/OpenCLI`），和上游 `jackwener/opencli`\n有差异，差异清单见 [`references/our-fork.md`](references/our-fork.md)。\n\n---\n\n## 一、先判断：这件事该不该用浏览器\n\n**动手之前先走这条阶梯，命中即停。** 每一级往下的唯一理由是「上一级确实不存在」，\n不是「我对下一级更熟」。跳级的代价不是慢，是拿到看起来正常但内容不同的数据。\n\n| 级 | 手段 | 什么时候用 |\n|---|---|---|\n| 1 | **现成脚本** | 项目里、兄弟 Skill 里已经有的 `.mjs`。直接跑，不要现写等价实现 |\n| 2 | **HTTP / REST API**（`curl` / `fetch`） | 没脚本但服务有 API。先用 API，跑通后固化成脚本 |\n| 3 | **`opencli ` adapter** | 目标站已有 adapter。`opencli list \\| grep -i ` 一眼就知道 |\n| 4 | **`opencli browser ` 现场驱动** | 没有 adapter，或 adapter 不覆盖这个动作 |\n| 5 | 写一个新 adapter | 这个动作以后还要重复做。见 [`references/adapters.md`](references/adapters.md) |\n\n### 判据：无痕窗口打开，还是不是同一个东西？\n\n答案是「不是」，就**必须**走用户的真实浏览器（也就是 OpenCLI）。\n\n需要身份的一切——第三方数据面板、Search Console、社区后台、聊天式 AI 工具——\n用运行环境自带的沙箱浏览器打开，要么直接跳登录页，要么以匿名身份返回**看起来正常\n但内容不同**的结果（配额更低、字段更少、国家库不同）。这种失败会伪装成\n「这个工具没有这项数据」，而正确的结论其实是「你没登录」。\n\n反过来，**只是看一段公开文本就不要开浏览器**——先问有没有 `curl` 或公开 API。\n\n三个 driver 的取舍（为什么默认是 OpenCLI 而不是 agent-browser 或 Claude in Chrome，\n各自的实测泄漏数据）见 [`references/drivers.md`](references/drivers.md)。\n\n### 不在本 Skill 范围\n\n- **找信息、做调研、搜某个话题** → 用 `agent-reach`，它已经负责多平台路由。\n 本 Skill 只管「怎么把浏览器开对、把数据取回来」。\n\n---\n\n## 二、开工前：doctor\n\n```bash\nopencli doctor\n```\n\n`doctor` 只诊断**浏览器桥**（守护进程 + 扩展 + Chrome 连线）。\n`PUBLIC` / `LOCAL` 策略的 adapter、`opencli list`、外部 CLI 透传都不需要它绿。\n`COOKIE` / `INTERCEPT` / `UI` 策略和所有 `opencli browser *` 才需要。\n\n### 行为和这份文档对不上时，第一件事是查扩展版本\n\n**本 Skill 描述的默认行为全部住在扩展里**——后台默认、标签页开在用户当前窗口、\n不切走活动标签页、`--window isolated`、`sessions` 报 windowId。\n装成 Chrome 应用商店那个版本的话，**每条命令都照样成功，只是行为回到上游**：\n默认前台、自己开一个窗口、抢走用户正在看的标签页、`isolated` 被忽略。\n\n**这类失败没有报错，只有「怎么和文档说的不一样」。** 所以：\n\n| 观察到 | 该做什么 |\n|---|---|\n| 命令成功但窗口/焦点行为与本文档不符 | 跑 `opencli doctor`，看 `Extension` 那行的版本 |\n| 版本 < 1.0.32 | **告诉用户他装的是应用商店版**，需要换成 [yan-labs 的 Release](https://github.com/yan-labs/OpenCLI/releases/latest) 里的 zip，并把商店版移除或停用 |\n| `doctor` 自己就报了这条 | 照它说的做——它会打印下载地址和加载步骤 |\n\n`doctor` 会在扩展低于 1.0.32 时主动报这个问题，**不要跳过它的输出**。\n\n红了先看 [`references/troubleshooting.md`](references/troubleshooting.md)。\n排障的第一步永远是 **`npm ls -g @jackwener/opencli` 确认 CLI 是发布版还是本地源码 link**——\n这一步决定后面是查代码还是查环境，跳过它会浪费一整轮。\n\n**`doctor` 前两行绿、第三行红**是一个特定信号：守护进程和扩展这两个组件都活着，\n坏的是它们之间那条命令路径，重启守护进程通常没用。\n\n---\n\n## 三、会话纪律：本 Skill 最贵的一节\n\n`opencli browser ` 里的 `` **就是标签页的所有权声明**。\n同名会话共用同一个标签页，不同名之间互不干扰。所以「我的标签页被别人抢了」\n只有一个成因：**两个任务挑了同一个会话名**。\n\n症状极其阴险：导航报成功，随后读回来的却是**另一个任务打开的页面**——\n数据是别人的，而全程没有任何报错。\n\n### 四条法律（完整实测数据见 [`references/session-laws.md`](references/session-laws.md)）\n\n| # | 法律 | 一句话理由 |\n|---|---|---|\n| 1 | **一个会话一个标签页；N 个页面就要 N 个会话名** | 三个 agent 各用独立名字：跨 agent 抢占 0 次。共用 `work`：3 / 12 / 2 次，其中一个每次读都读错 |\n| 2 | **不要用 `tab new` / `tab select` / `open --tab` 在一个会话里放多个页面** | 三个都**静默**失败：命令报成功，下一次读回错误的页面。一次三 agent 运行把用户的 Chrome 从 11 个标签页涨到 30 个孤儿页 |\n| 3 | **绝不硬编码会话名** | `opencli browser --help` 的第一个例子就是 `work`，抄它的人全撞在一起 |\n| 4 | **开工前一次性把要用的会话全部开好、handle 全部拿到，再进工作循环** | 边创建边使用会把理论上的竞态变成可复现的竞态 |\n\n**法律 1 保护的是标签页身份，不是站点的服务端状态。** 所有会话共用同一个 Chrome\nprofile 和同一个登录身份，所以如果站点把「当前选中的项目/客户」存在服务端会话里，\n一个标签页切换目标，其它标签页刷新后会跟着变——会话名分得再开也拦不住。\n**判据：在站点里切换目标之后 URL 变不变？** 不变就先验证再并行，\n细节见 [`references/session-laws.md`](references/session-laws.md)。\n\n### `$$` 在脚本里安全，在 Bash tool 里不安全\n\n这是我们踩过的真实事故，必须区分：\n\n| 场景 | `$$` / `process.pid` 行为 | 正确做法 |\n|---|---|---|\n| **Node 脚本**（一个进程跑完全程） | 整个生命周期同一个 PID，安全 | `` let session = `ahs-${process.pid}` `` |\n| **Claude Code 的 Bash tool** | **每次调用都是新进程，PID 不同** | 用**描述性字面常量**（`naver-birthstone`、`bing-check-mysite`），或 `S=$(uuidgen \\| cut -c1-8)` 存进文件再读回 |\n\n已验证事故（2026-08-23）：sub agent 用 `S=\"naver-bs-$$\"` 连续调用 OpenCLI，\n每条命令都创建了新会话（新空白标签页），上一条打开的页面被遗弃。\nagent 看到的永远是空白页，以为页面没加载好不断重试，最终泄漏 9 个会话。\n\n**名字要描述工作**，不只是唯一：`backlink-probe-<后缀>` 胜过 `bl-1`。\n会话名是唯一存在的标识符，一个唯一但无意义的名字仍然回答不了「这是谁的标签页」。\n\nJS 里不要手搓后缀，用 `scripts/opencli-core.mjs` 的 `defaultSession(base)`。\n\n### 用完必须还回去\n\n```bash\nopencli browser close # 释放这一个\nopencli browser sessions # 看现在还有谁活着，以及各自在哪个窗口\nopencli browser cleanup # 释放**全部**——只有主线能跑，见下\n```\n\n**Sub agent 必须在 finally 块或退出前显式 close 自己的会话**——崩溃时不会自动清理。\n\n**`cleanup` 是主线专用。** 它释放的是**这台机器上全部**的租约，不是「我的」——\nsub agent 跑它会把兄弟 agent 正在用的标签页一起关掉，\n而那些 agent 只会看到自己的页面莫名其妙不见了。并行扇出时只有父级在全部收工后才跑它。\n留着的会话在用户 Chrome 里就是一个标签页，看起来和别人正在做的活儿一模一样。\n\n### 三个窗口模式，默认已经是不打扰的那个\n\n| `--window` | 行为 | 什么时候用 |\n|---|---|---|\n| `background` | **默认**。在用户当前那个窗口里开标签页，不抬窗口、不切活动标签页 | 几乎所有情况 |\n| `foreground` | 抬起窗口并选中标签页 | **只有**需要用户亲自完成验证码、或他明确说要看着的时候 |\n| `isolated` | 后台，且不在用户那个窗口里——**所有 isolated 会话共用一个自动化窗口** | 长时间批量作业，不想在用户标签栏里堆东西 |\n\n标志位置在**会话名和子命令之间**（放在子命令后面也能工作）：\n\n```bash\nopencli browser --window isolated open \"https://...\"\n```\n\n放在会话名**前面**会报 `unknown command: <你的会话名>`，读起来像装坏了，其实是语法错。\n\n**需要扩展 ≥ 1.0.32**（`opencli doctor` 那行就是判据）。旧扩展上默认仍是前台、\n`isolated` 会被静默忽略——那正是下面那张表里的坑。\n\n#### `isolated` 曾经有两条限制，两条都已修好\n\n**当前行为（2026-08-24 复测于扩展 1.0.30 + CLI 1.8.7，两条都 PASS）**：\n两个 isolated 会话可以并存，`sessions` 里都在、都可读，\n且**共用同一个自动化窗口**（`win379222152`），与用户窗口（`win379220956`）分开。\n注意是「共用一个窗口」而不是「一人一个窗口」——它隔离的是**用户 vs 自动化**，\n不是会话之间。会话之间的隔离靠会话名，那是上面四条法律的事。\n\n

\n

修好之前是什么样（留着，因为这两种失败形态会重复出现）

\n\n**一、第二个 isolated 会把第一个静默打掉**（扩展 1.0.27）。\n`w1` 开出独立窗口 → 再开 `w2` → `w2` 落回用户窗口，**且 `w1` 整条会话从 `sessions` 蒸发**，\n再访问 `session_not_found`，而创建 `w2` 的那一方毫无报错。跨 agent 同样会踩——\n一个 agent 开 isolated 就打掉兄弟 agent 已有的那个。\n\n**二、adapter 命令不接受 `isolated`**（CLI ≤ 1.8.7 的某个中间版本）。\n报 `--window must be one of: foreground, background`。真因是 adapter 走的是\n`src/execution.ts` 里**另一份白名单**，它只列了两个值，而紧挨着的 `src/help.ts`\n文案却在宣传 isolated——文档说一套、代码做一套，读起来像用户抄错了参数。\n\n两条的共同点：**失败都不报错，或者报的错指向错误的方向。** 所以下面那条自检值得每次都做。\n

\n\n背景模式跑的是用户真实的、已登录的 Chrome：`navigator.webdriver` 为 `false`、\nUA 不含 `Headless`、`plugins.length` 为 5。\n**「后台模式会被反爬识破」不是真问题**，每一项无头特征都是负的。\n\n### 绝不抢用户的浏览器焦点\n\n**这台机器上的 Chrome 是用户正在用的那一个。** 抢焦点不是「体验略差」，\n是直接打断他手上的活——他正在打字或看页面，窗口被抬起来、标签页被切走。\n\n| 错误做法 | 正确做法 | 为什么错 |\n|---|---|---|\n| `--window foreground`（除非用户要亲自操作） | 什么都不加（默认就是 background） | 实测会把用户的**活动标签页切走**（从第 1 个跳到第 3 个）。注意最前端**应用**不变，所以只查应用焦点的测量看不见它 |\n| 调 adapter 时用前台「方便看页面」 | `--keep-tab true` + `screenshot` / `state` | 调试是高频动作，一轮能打断十几次。标签页留着，用户想看自己切过去 |\n| 在旧扩展（< 1.0.32）上省略 `--window background` | 先看 `doctor` 的扩展版本；旧版就每条命令都显式带 | 旧版两层默认都是前台，省略等于每条命令都抬一次窗口 |\n| 给 `PUBLIC` / `LOCAL` 命令加 `--window` | 不加 | 它们不接受这个标志，会报 `unknown option '--window'`；这类命令本来也不开浏览器 |\n| 崩溃后不清理，留下一堆孤儿标签页 | `finally` 里 `close` | 泄漏的会话在用户窗口里就是一堆莫名其妙的标签页，比抢一次焦点更烦 |\n\n**实测（2026-08-23，macOS + Chrome）**：后台模式下 `open` / `eval` / `screenshot` /\n`click` / `type` 全程——用户窗口的**活动标签页索引不变**，标签数在 `close` 之后回到基线，\n页面侧 `document.hasFocus()` 恒为 `false`、`visibilityState` 恒为 `hidden`。\n**同一台机器上换成 `--window foreground`，活动标签页立刻从第 1 个被切到第 3 个。**\n\n**这条推翻了本 Skill 到 2026-08-22 为止的旧结论「两种模式都不抢焦点」**——\n旧测量只查了「最前端应用」（前台模式下它确实不变），漏掉了「活动标签页」这一轴。\n完整对照表见 [`references/session-laws.md`](references/session-laws.md)。\n\n> **这条曾经是坏的，2026-08-23 修好了**（扩展 1.0.32）。当时 `--window isolated`\n> 不新开窗口，行为与 `background` 一模一样，于是文档写下了「没办法把 agent 的标签页\n> 挪出用户窗口」。真因是四层各自静默地否决它：运行时白名单只认两个值把 `isolated`\n> 丢掉了；「这窗口是不是我的」靠猜（全是非 http 页面就算我的）而把用户随手开的空窗口\n> 认成了容器；窗口建对了之后分组收敛又把标签页搬回用户窗口；以及挑「用户在哪个窗口」\n> 用了 `focused`，而 Chrome 不在最前面时所有窗口的 `focused` 都是 false。\n> **每一层都不报错**，所以每修一层都以为好了。\n\n**怎么确认自己拿到的是修好的版本**：`opencli browser --window isolated open `\n之后跑 `opencli browser sessions`，它那一行的 `windowId` 应该与默认模式会话的不同。\n\n---\n\n## 四、发现能力：不要背命令表，去问\n\n有 160+ 站点 adapter，数量每周都在变。**任何写死在文档里的清单都会过期**，\n所以本 Skill 不列它们。\n\n```bash\nopencli list # 按站点分组的表格\nopencli list -f json # 机器可读，agent 用这个\nopencli list | grep -i twitter # 找某个站\nopencli --help # 这个站有哪些命令\nopencli --help # 位置参数、专属标志、输出列\n```\n\n`opencli list -f json` 每条给 `{site, name, aliases, description, strategy, browser, args, columns}`。\n**`strategy` 决定要不要浏览器**：\n\n| strategy | 需要什么 |\n|---|---|\n| `PUBLIC` | 什么都不要，纯 HTTP |\n| `COOKIE` | Chrome 已登录该站 + 装了扩展；命令从活会话里取凭据，不用重新登录 |\n| `INTERCEPT` | 同上，另外会开一个自动化窗口截取签名请求 |\n| `UI` | 同上，完整 DOM 交互 |\n| `LOCAL` | 不要浏览器，连本地/开发端点 |\n\n**在退回裸 `opencli browser` 之前，先查一下有没有 adapter 已经覆盖了这个工作流。**\n在高频改版的登录站上尤其值得——adapter 里封装过的坑，现场驱动要重踩一遍。\n\n### 通用标志（多数 adapter 命令有，浏览器相关的那几个例外）\n\n| 标志 | 作用 |\n|---|---|\n| `-f, --format ` | `table`（TTY 默认）· `yaml`（非 TTY 默认）· `json` · `plain` · `md` · `csv`。**agent 基本都要 `-f json`** |\n| `--trace ` | `off`（默认）· `on` · `retain-on-failure`。排障和写 adapter 时用 |\n| `-v, --verbose` | 调试日志 + 失败栈 |\n| `--window ` | `background`（默认）/ `foreground` / `isolated`。**`PUBLIC` / `LOCAL` 策略的命令不接受它**——加了直接报 `unknown option '--window'`，读起来像装坏了，其实是这类命令根本不开浏览器（实测 342 个 public + 25 个 local 命令）。先看 `strategy` 再决定加不加 |\n| `--site-session ` | `ephemeral`（默认）/ `persistent`，命令结束后是否留着会话标签页 |\n| `--keep-tab ` | 结束后是否保留标签页租约 |\n\n---\n\n## 五、现场驱动：最小闭环\n\n```bash\nS=\"recon-pricing\" # 描述性常量，Bash tool 里不要用 $$\nopencli browser \"$S\" open \"https://example.com/pricing\"\nopencli browser \"$S\" state # 拿到带 [N] 编号的快照\nopencli browser \"$S\" click 7\nopencli browser \"$S\" wait selector \"[data-loaded]\" --timeout 15000\nopencli browser \"$S\" state # 页面变了就必须重新 state\nopencli browser \"$S\" close\n```\n\n四条心智模型，够用来读懂所有返回：\n\n1. **选择器优先的目标契约**：每个交互命令接受**一个** ``，要么是 `state`/`find`\n 给的数字 ref，要么是 CSS 选择器。多个匹配时用 `--nth ` 消歧。\n2. **每个信封都报 `matches_n` 和 `match_level`**（`exact` / `stable` / `reidentified`）。\n CLI 已经替你救回了中等程度的 DOM 漂移，`match_level` 告诉你该有多信。\n3. **先要紧凑输出，需要时再要全量**：`state` 是预算感知的快照；`network` 先给形状预览，\n 再用 `--detail ` 取单条 body。吐一个巨大的 payload 等于白烧上下文。\n4. **错误是机器可读的**：失败返回 `{error: {code, message, hint?, candidates?}}`。\n **按 `code` 分支，不要匹配消息字符串。**\n\n完整命令表、目标契约、compound 表单控件、成本表、配方与坑，见\n[`references/browser-driving.md`](references/browser-driving.md)。\n\n### 三条最常被违反的规则\n\n- **动手之前先看。** 先 `state` 或 `find`。数字 ref 是**每次快照独有的**，\n 绝不要跨会话凭记忆写死。\n- **页面变了就重新 `state`。** 导航、表单提交、SPA 路由切换都会让旧 ref 失效——\n 失效还算好的，更糟的是 `reidentified` 到新页面上一个形状相似的元素。\n- **`eval` 是只读的，而且必须包 IIFE。** 本环境 eval 上下文跨调用持续，\n 重复声明会抛错**且那次调用根本没执行**。要改页面就用 `click`/`type`/`select`/`keys`，\n 它们有结构化输出和指纹，`eval` 没有。\n\n### batch：一次调用跑多步\n\n固定序列（open → wait → eval）**一律用 batch**，它复用一条 Page 连接，\n省掉每条命令各付一次的连接—解析—拆除开销。\n\n```bash\nopencli browser \"$S\" batch --commands '[\n {\"cmd\": \"open\", \"args\": [\"https://example.com\"]},\n {\"cmd\": \"wait\", \"args\": [\"selector\", \".loaded\"]},\n {\"cmd\": \"state\", \"args\": []}\n]'\n```\n\n返回 `{cmd, index, ok, result?, error?}` 数组；默认遇错继续，`--stop-on-error` 改为中止。\n**条件逻辑**（每一步决定下一步）用顺序调用，不要硬塞进 batch。\n\n---\n\n## 六、取数与落盘\n\n### 页面里没有 API 时的取数顺序\n\n1. **`network`** —— 页面的数据如果来自 JSON 接口，**接口几乎总比渲染后的 DOM 可靠**。\n 先 `network` 看形状，再 `--detail ` 取那一条。\n2. **`extract`** —— 长文正文，返回带 `next_start_char` 游标，循环到它为 `null`。\n3. **`eval`** —— 前两者都不合适时的定点提取。\n4. **滚动抓表** —— 兜底手段，不是默认手段。**开抓之前先花一分钟找那个免费导出按钮**。\n\n### 抓之前必须知道的三个坑\n\n- **同名控件陷阱**：同一个报表上常并排放着两个名字高度相似的导出控件，一个走付费配额、\n 一个免费导当前页，行为完全相反。**凡是要写下「某功能不可用」，先确认你点的不是同名的另一个控件。**\n- **同一个工具里不同报表的导出模型可以完全不同。** 在 A 报表验证出「只能一页页导」，\n 不构成 B 报表的结论。每换一个报表，重新看一眼导出面板。\n- **导出触发器常常是 `