commit 66499305936ea57cf0a439006094e6319f8c6187
Author: Kinneyzhang <kinneyzhang666@gmail.com>
Date:   Fri Oct 2 09:26:18 2026 +0800

    release v0.1.0

diff --git a/MANIFEST.json b/MANIFEST.json
new file mode 100644
index 0000000..ca9fcac
--- /dev/null
+++ b/MANIFEST.json
@@ -0,0 +1,221 @@
+{
+  "manifest_version": 1,
+  "name": "cdp-page-control",
+  "summary": "驱动受控浏览器操作任意网站页面（导航、填表、点击、读文本、截图、抓网络）",
+  "tier": 1,
+  "status": "stable",
+  "version": "2d2f88d",
+  "source": {
+    "path": "skills/cdp-page-control",
+    "commit": "2d2f88d",
+    "describe": "2d2f88d",
+    "dirty": false,
+    "packed_at": "2026-10-02T01:26:18.193Z"
+  },
+  "platforms": [
+    "all"
+  ],
+  "entry": {
+    "path": "scripts/cdpctl.mjs"
+  },
+  "commands": [
+    "launch",
+    "nav",
+    "snapshot",
+    "wait",
+    "find",
+    "click",
+    "type",
+    "fill",
+    "press",
+    "drag",
+    "select",
+    "hover",
+    "upload",
+    "insert-text",
+    "text",
+    "html",
+    "eval",
+    "net",
+    "console",
+    "shot",
+    "pdf",
+    "cookies",
+    "import-cookies",
+    "persist-cookies",
+    "targets",
+    "open",
+    "close",
+    "status",
+    "stop"
+  ],
+  "errors": [
+    "usage",
+    "auth",
+    "notfound",
+    "blocked",
+    "timeout",
+    "external",
+    "internal"
+  ],
+  "aliases": [
+    "cdpctl"
+  ],
+  "admin": [],
+  "depends_on": [],
+  "requires": [],
+  "config": [],
+  "external_imports": [],
+  "contract": {
+    "version": 1,
+    "skill": "cdp-page-control",
+    "tier": 1,
+    "platforms": [
+      "all"
+    ],
+    "commands": {
+      "click": {
+        "destructive": false
+      },
+      "close": {
+        "destructive": false
+      },
+      "console": {
+        "destructive": false
+      },
+      "cookies": {
+        "destructive": false
+      },
+      "drag": {
+        "destructive": false
+      },
+      "eval": {
+        "destructive": false
+      },
+      "fill": {
+        "destructive": false
+      },
+      "find": {
+        "destructive": false
+      },
+      "hover": {
+        "destructive": false
+      },
+      "html": {
+        "destructive": false
+      },
+      "import-cookies": {
+        "destructive": false
+      },
+      "insert-text": {
+        "destructive": false
+      },
+      "launch": {
+        "destructive": false
+      },
+      "nav": {
+        "destructive": false
+      },
+      "net": {
+        "destructive": false
+      },
+      "open": {
+        "destructive": false
+      },
+      "pdf": {
+        "destructive": false
+      },
+      "persist-cookies": {
+        "destructive": false
+      },
+      "press": {
+        "destructive": false
+      },
+      "select": {
+        "destructive": false
+      },
+      "shot": {
+        "destructive": false
+      },
+      "snapshot": {
+        "destructive": false
+      },
+      "status": {
+        "destructive": false
+      },
+      "stop": {
+        "destructive": false
+      },
+      "targets": {
+        "destructive": false
+      },
+      "text": {
+        "destructive": false
+      },
+      "type": {
+        "destructive": false
+      },
+      "upload": {
+        "destructive": false
+      },
+      "wait": {
+        "destructive": false
+      }
+    },
+    "errors": [
+      "auth",
+      "blocked",
+      "external",
+      "internal",
+      "notfound",
+      "timeout",
+      "usage"
+    ],
+    "aliases": [
+      "cdpctl"
+    ],
+    "adminAliases": []
+  },
+  "files": [
+    {
+      "path": "REFERENCE.md",
+      "bytes": 17940,
+      "sha256": "b60993234ed6ecb7"
+    },
+    {
+      "path": "SKILL.md",
+      "bytes": 9387,
+      "sha256": "e438232d7f407ddd"
+    },
+    {
+      "path": "VERSION",
+      "bytes": 6,
+      "sha256": "e9dd8507f4bf0c6f"
+    },
+    {
+      "path": "contract.lock.json",
+      "bytes": 1686,
+      "sha256": "7f9826fd24a0edba"
+    },
+    {
+      "path": "interface.json",
+      "bytes": 3336,
+      "sha256": "01936140a778d16f"
+    },
+    {
+      "path": "scripts/cdp-channel.mjs",
+      "bytes": 37344,
+      "sha256": "87d7b2ff6bdda7c9"
+    },
+    {
+      "path": "scripts/cdpctl.mjs",
+      "bytes": 66823,
+      "sha256": "d1130b829b1fd42b"
+    }
+  ],
+  "leak_scan": {
+    "errors": 0,
+    "warnings": 0,
+    "findings": []
+  }
+}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..04bcc06
--- /dev/null
+++ b/README.md
@@ -0,0 +1,14 @@
+# cdp-page-control
+
+驱动受控浏览器操作任意网站页面（导航、填表、点击、读文本、截图、抓网络）
+
+以 Pi package（技能形态）发布。
+技能本体在 `skills/cdp-page-control/`，用法见其 `SKILL.md` 与 `REFERENCE.md`。
+
+## 安装
+
+```sh
+pi install git:gitea.vhkd.top/geekinney/cdp-page-control.git@v0.1.0
+```
+
+装完 `pi-skill list` 能看到 `cdp-page-control`，`pi-skill cdp-page-control check` 会告诉还缺什么。
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..7ca7c01
--- /dev/null
+++ b/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "cdp-page-control",
+  "version": "0.1.0",
+  "description": "驱动受控浏览器操作任意网站页面（导航、填表、点击、读文本、截图、抓网络）"
+}
diff --git a/skills/cdp-page-control/REFERENCE.md b/skills/cdp-page-control/REFERENCE.md
new file mode 100644
index 0000000..9e24316
--- /dev/null
+++ b/skills/cdp-page-control/REFERENCE.md
@@ -0,0 +1,168 @@
+# cdp-page-control 参考
+
+## 分层
+
+| 层 | 文件 | 职责 |
+|---|---|---|
+| 通道层 | `scripts/cdp-channel.mjs` | CDP 传输、浏览器生命周期、选择器解析、cookie DB 定位 |
+| 原语层 | `scripts/cdpctl.mjs` | 每个子命令 = 一个原子操作，参数化，不含站点逻辑 |
+| 场景层 | `SKILL.md` 配方表 | 多步骤组合只写在文档里，不进代码 |
+
+新增需求 = 用现成原语组合；某个组合反复出现 = 在 SKILL.md 配方表加一行，**不要**往原语层塞场景分支。
+
+新加一个原语的四步：① `cdp-channel.mjs` 里加必要传输（多数情况下不需要）→ ② `cdpctl.mjs` 的 `switch` 加一个 case → ③ `CMD_HELP` 加条目（`usage 正文与注册表一致性` 测试会自动校验，漏注册会失败）→ ④ 在 `tests/smoke.test.mjs` 或对应专题测试（如 `tests/inspect.test.mjs`）里加断言。
+
+## 为什么必须用独立 profile
+
+Chrome 136 起，**默认 user-data-dir 会直接忽略 `--remote-debugging-port`**（官方为防 Cookie 窃取做的加固）。所以「连上你正在用的那个 Chrome」在不重启、不换 profile 的前提下做不到。本技能的方案是另起一个带独立 profile 的实例，与你日常浏览器完全隔离、可并存。
+
+必须带的启动参数：`--user-data-dir=<非默认>`、`--remote-debugging-port=<端口>`、`--remote-allow-origins=*`（否则 WebSocket 握手 403）。
+
+## 登录态持久化：实测结论
+
+DeepSeek Platform 的实测数据（2026-09，Chrome 153，macOS）：
+
+| 观察 | 结果 |
+|---|---|
+| 站点把会话放哪 | **localStorage 的 `userToken`**；cookie 里没有会话凭证，IndexedDB 也没有 |
+| `ds_session_id` 的属性 | `expires_utc=0`、`has_expires=0` → **会话 cookie** |
+| 会话 cookie 跨重启 | **被 Chrome 删除**（实测：重启后 DB 里消失） |
+| 改成持久 cookie 后 | **连续两次重启都存活**（实测通过） |
+| 对照实验 | 同一份密文只改元数据：会话版被删，持久版存活 → 差异只来自元数据 |
+
+`persist-cookies` 就是把 `has_expires=0` 的行改成 `expires_utc=13537929600000000`（2030-01-01，WebKit 1601 纪元微秒）、`has_expires=1`、`is_persistent=1`。**密文不变，不解密、不改值。**
+
+注意：`session.restore_on_startup=1`（「继续浏览上次打开的网页」）**不可靠** —— Chrome 退出时会把它改回 `None`，且没有可恢复会话数据时照样清会话 cookie。别依赖它。
+
+局限：这只保证**浏览器侧不丢凭证**。服务端会话是否仍有效由站点决定，站点判过期就得重新登录。
+
+## 复用日常 Chrome 的登录态：`import-cookies`
+
+不想为自动化再登录一遍时，不用重启日常 Chrome、不用导出密码，直接把它的 Cookies 库复制过来：
+
+```bash
+pi-skill cdp-page-control import-cookies                        # 预览（默认 profile）
+pi-skill cdp-page-control import-cookies --profile "Profile 1"  # 指定日常 Chrome 的另一个 profile
+pi-skill cdp-page-control import-cookies --yes                  # 执行：关浏览器 → 备份目标库 → 覆盖 → 回读计数
+pi-skill cdp-page-control launch                                # 再用浏览器
+```
+
+为什么可行：Chrome 136+ 只是不允许给**默认** user-data-dir 开调试端口，并没有换 cookie 加密密钥；同机同 Chrome 的 cookie 由同一份 Keychain「Chrome Safe Storage」派生密钥保护，**文件级复制即可解密**（实测：把日常 profile 的 Cookies 拷进自动化 profile 后，日常已登录的站点直接可用）。
+
+边界与安全（重要）：
+
+- 复制的是**整个 profile 的全部站点登录态**，不是只挑几个域；等于把一份浏览器身份带进自动化实例。
+- 自动化实例的调试端口只绑 `127.0.0.1`，但本机任何进程都能连上它读该 profile 的全部凭证；不用时 `stop`。
+- 目标库原内容会被移到同目录的 `Cookies.bak-<时间戳>`，回滚就是拷回去。
+- 属于本机私有数据，不要提交/同步（profile 目录在共享仓库之外）。
+
+## 快照引用（@N）
+
+`snapshot` 在页面里给「可见的交互 + 结构元素」打 `data-cdpctl-ref`，输出缩进文本树；所有命令的选择器都认 `@N`（`selectorExpr` 转成穿透 shadow root 的查找表达式）。
+
+- 引用是一次性的：每次 snapshot 先清掉旧引用再重新编号；SPA 重渲染会把节点连同属性一起换掉，旧 `@N` 失效——`click`/`wait` 的报错会提示重跑 `snapshot`。
+- 为什么用页面属性而不是 Node 侧存映射：无状态、跨进程可用（每条命令都是独立进程）、复用现有全部元素命令（含 `--frame` 内的解析）；代价是页面上会留下属性（重拍即清理，无业务副作用）。
+- shadow DOM：open shadow root 里的元素也编号；查找表达式递归进 shadowRoot（`querySelector` 不穿透）。closed shadow root 仍拿不到。
+- 挑选规则：`a/button/input/select/textarea/summary/iframe`、各级标题、`main/nav/header/footer/aside/form/table/details`、`contenteditable`、常见交互 role；带可见文本的叶子节点只在 `--all` 时纳入。`--max` 默认 250（0=不限，超出部分只计数不显示）。
+
+## 对话框：实测行为与策略
+
+Chrome 153 实测（探针脚本 + `tests/inspect.test.mjs` 守着）：
+
+- 对话框打开期间，**后续 CDP 调用全部挂起**：`Page.enable`、`Runtime.evaluate`、`Input.*` 都不返回；连触发弹窗那次 `mouseReleased` 的响应也要等对话框被处理。
+- **残留对话框无法从新连接抢救**：新连接收不到 `javascriptDialogOpening`，`Page.handleJavaScriptDialog` 报 "No dialog is showing"，`Page.enable` 直接超时。唯一恢复是 `cdpctl stop && cdpctl launch`（浏览器级 `Browser.close` 不受阻塞影响）。
+- 因此 `connectPage` 默认在**任何动作之前**装上处理器：`Page.enable` + 监听 `Page.javascriptDialogOpening` → 自动 `handleJavaScriptDialog`。策略 `CDPCTL_DIALOG=accept|dismiss|ignore`（默认 accept），prompt 文本 `CDPCTL_DIALOG_TEXT`（缺省用页面 defaultPrompt）。
+- 兜底超时：`Page.enable` 5s、evaluate/waitForElement 5s、Input 15s；把「永久挂死」变成带 `cdpctl stop && cdpctl launch` 提示的报错。`CDPCTL_DIALOG=ignore` 保留原生行为，风险自负。
+
+## console：历史回放实测
+
+- `Runtime.enable` **会回放**当前文档保留的 `console.*` 消息与未捕获异常（`Runtime.consoleAPICalled` / `Runtime.exceptionThrown`），所以不加 `--reload` 也能看到页面之前报过的错。
+- `Log.enable` 不回放缓存条目；它补的是浏览器日志（网络错误/安全告警等）。两个域都挂上，按时间戳排序输出（Log 的 timestamp 是秒，需 ×1000）。
+- 对象参数用 `Runtime.callFunctionOn` 在页面里 `JSON.stringify` 后回传，截断 400 字符；避免 `[object Object]`。
+- `--reload` 先丢弃旧页面的回放，再刷新并收集到 load 后 `--seconds` 秒，专抓加载期一次性报错。
+
+## 新命令实现要点
+
+- `fill`：JSON 对象逐字段分派——`<select>` 走原生 setter + input/change；checkbox/radio 用真实点击并回读校验；其余走 `type` 的受控输入路径。失败的字段逐条报告、成功的保留，整体退出码 1。字段级 `waitForElement` 复用全局 `--timeout`。
+- `drag`：`mousePressed` → 10 步 `mouseMoved`（每步留 10ms）→ `mouseReleased`。分步是必须的：JS 拖拽库和浏览器原生 HTML5 拖放都依赖过程事件。要求两端同屏（拖拽中途无法滚动），暂不支持 `--frame`。
+- `nav --back/--forward`：`Page.getNavigationHistory` + `Page.navigateToHistoryEntry`；`--reload` 用 `Page.reload`，比 `eval location.reload()` 可靠（不受页面重写/覆盖影响）。
+- `shot <out.png> [选择器] [--full] [--clip x,y,w,h [--scale N]]`：
+  - 带选择器：`boxExpr` 拿元素边界 + 当前 `scrollX/Y` 作为 `clip`，`captureBeyondViewport: true`；坐标换算已包含 `--frame` 的宿主页面偏移。
+  - `--clip x,y,w,h`：页面坐标（CSS px）矩形，`captureBeyondViewport: false` —— **只 raster 视口内已绘制的区域**，
+    所以视口外的部分是空白；要截比视口大的区域得自己按视口分块 `--clip` 再拼（见下面那条坑）。
+  - 互斥：`选择器 + --full`、`选择器 + --clip`、`--full + --clip` 都直接报错；`--scale` 只能配 `--clip`（默认 1）。
+- **`pdf <out.pdf> --size WxH [--media screen|print]`**（2026-09-27 加）：走 `Page.printToPDF`，纸面尺寸 = `W/96 × H/96` 英寸、四边 margin 0、`printBackground: true`；`--media screen` 会先 `Emulation.setEmulatedMedia{screen}` 以保持屏幕上那套版式。**这是「大画布上怎么一次拿到整页」的正解**：16 栏 7472×786 实测 0.77s 出 PDF，再用 `qlmanage -t -s 2×max(W,H) -o <目录> <pdf>` 矢量重栅格 → 14944×1573 的 PNG（0.48s）。注意 `sips` 不行（按 1pt=1px 出图，等于 0.75× CSS）。
+- **`captureBeyondViewport: true`（`--full` / 元素截图）在大画布上是死循环**（2026-09-27 实测）：
+  宽多栏文本页（6544×896）20s/45s 不返回；纯 `<img>` 拼图页也一样；普通小页（321ms）与纯色页正常。
+  卡住后**同一个标签页后续命令也可能一起变慢/挂死**，重启浏览器才能清干净。
+  「把视口放大到整页再一次截」（`Emulation.setDeviceMetricsOverride` + 普通截图）同样 20s 无响应；
+  要整页图就用上一段的 `pdf`（首选），或退而求其次：把区域切成 ≤ 视口的块，逐块滚动
+  （`behavior:'instant'` + 等两个 rAF）`--clip`，再自己拼（参考 `longtext-web` 的
+  `capture_page` + `lib/png_stitch.mjs`：16 栏 / 7472×786 → 6 块 → 14944×1572，约 5s）。
+  分块前记得在受控副本里藏掉滚动条（`::-webkit-scrollbar{display:none}`）。
+
+## 容易踩的协议细节
+
+- **`Network.requestWillBeSent` 常常不带 `Cookie` 头**。真实 Cookie 在 `Network.requestWillBeSentExtraInfo` 事件里。只看前者会误判成「cookie 没发出去」。`net` 命令已正确处理这个映射。
+- `Runtime.evaluate` 要传 `userGesture: true`，否则部分 API 认为没有用户手势。
+- 真实鼠标事件要发三个：`mouseMoved` → `mousePressed` → `mouseReleased`。`buttons` 只在 pressed 时置 1。
+- 键盘：有可见字符的键用 `keyDown` + `text`；功能键用 `rawKeyDown`。收尾都要发 `keyUp`。
+- `rateLimit`/`--enable-automation` 不要加，会触发「正在被自动化软件控制」提示条。
+- 文件上传只能走 `DOM.setFileInputFiles`（支持 `nodeId` 或 `objectId`），这也是**页面 JS 做不到**的操作之一。用 `objectId` 时同一套代码能覆盖主文档与同源 iframe。
+- 同源 iframe：主文档的 `querySelector`/XPath 不穿透 frame，必须拿 `iframe.contentDocument` 当根。坐标要先取 iframe 的 `getBoundingClientRect()`，再加 `clientLeft/clientTop`（边框宽度）才等于内容区原点；否则点击会偏。
+- `Page.captureScreenshot` 加 `captureBeyondViewport: true` 才是整页截图 —— 但大画布上它会卡死（见「新命令实现要点」里的 `shot`）。
+
+- **`text=` 的可见性优先级**：同一个文本常有多份副本（折叠菜单、移动端导航、隐藏弹窗），取「第一个最内层」会选中看不见的那个，`click`/`wait` 静默失败。现在的规则：最内层候选中**优先取可见的**（有尺寸且 visibility/display 正常）；若全部不可见，退回改动前行为（返回第一个最内层，由后续可见性检查决定成败）。夹具 `tests/fixtures/text-visibility.html` + `tests/selector.test.mjs` 守着这条。
+- **`--timeout` 的单位是秒**（默认 15）。历史上代码按毫秒用，传 20 会变成 20ms（静默秒退）；现在超过 600 秒直接报错并提示除以 1000。派生技能直接传秒即可（`dmp-submit`、`site-session-keeper` 已统一）。
+- **`launch` 的端口竞态**：`stop` 之后端口可能还没释放，新 Chrome 会「活着但 CDP 不通」，干等超时还留下孤儿进程。现在：超时→杀掉本次启的进程→确认端口释放→重试一次；若是别人占着端口则报错并给出 `lsof` 命令。
+- **`--target` 精确定位**：编排多个标签页时用 targetId（`status`/`targets`/`open` 都能拿到），比 `--match` 的 URL 片段稳定：重定向不失配、同域名多页不歧义。
+- **`eval` 的 stdout 是「二次编码的 JSON」**：入口统一 `console.log(JSON.stringify(value))`，所以表达式返回字符串时（典型：自己写了 `JSON.stringify(obj)`，想拿到 JSON 文本）命令行拿到的是「JSON 里再套一层 JSON 字符串」，直接 `JSON.parse` 只会得到字符串。两种正确用法：
+  - 表达式直接返回值对象（不要自己 `JSON.stringify`）；或
+  - 调用方解两层：`let v = JSON.parse(raw); if (typeof v === 'string') v = JSON.parse(v);`（`skills/chatgpt-connectors` 的 `evalJson` 就是后者，并带导航竞态重试）。
+  与此相关：页面正在导航时 `Runtime.evaluate` 可能返回 `undefined` 或报上下文销毁，取页面状态要允许重试，别把一次空结果当成「未登录/列表为空」。
+
+## 排查表
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `连不上 CDP 127.0.0.1:9222` | 没启动。`launch`。先 `status` 看端口 |
+| 多个页面无法自动选择 | 用 `--match`；`targets` 或 `status` 列出现有页面 |
+| `等待超时：找不到可见可点击的元素` | 元素还没渲染 / 选择器不对 / 在跨域 iframe 内。用 `text`、`html`、`find` 现场看；同源 iframe 加 `--frame` |
+| `无法访问 --frame ... 内部：跨域 iframe` | 该 iframe 与宿主不同源（含 file:// 页面），只能操作其宿主元素 |
+| 填了输入框但提交是空的 | 用 `eval` 直接赋值了。必须用 `type` |
+| 点击没反应 | 元素被遮挡或需要先滚动。`find` 看几何；先 `click` 触发展开再点目标 |
+| `--match` 命中多个 | 片段写长一点，或改用 URL 全路径；能用 id 就改用 `--target <targetId>` |
+| 启动后 30s 未就绪 | 看 `<profile>/chrome-launch.log`。若日志里没有端口报错、进程却还活着，多半是刚 `stop` 过、端口还没释放（新 Chrome 绑不上调试端口）。现在会自动清理并重试一次；等待上限用 `CDPCTL_LAUNCH_TIMEOUT_MS` 调 |
+| 报「CDP 端口被别的进程占着」 | 跑 `lsof -nP -iTCP:<端口> -sTCP:LISTEN` 看占用者，或换个端口（`CDPCTL_PORT`） |
+| 找不到 Chrome | `CDPCTL_CHROME=/绝对/路径` |
+| 登录态重启就丢 | 跑 `persist-cookies --domain <域名>` |
+| `@N` 找不到 / 报「引用可能已失效」 | 页面重渲染过。重跑 `snapshot` 拿新引用 |
+| 页面所有命令都无响应（`Page.enable` 超时） | 多半是残留对话框或页面死循环。`stop && launch` 重启（残留对话框无法从新连接抢救） |
+| 快照输出太长或元素太多 | `snapshot --max 100`（0=不限）；先看 `--max 50`，需要正文再 `--all` |
+
+## 安全
+
+- 调试端口只绑 `127.0.0.1`，但**本机任何进程都能连上它并读取该 profile 的全部数据**（cookie 值、localStorage、页面内容）。不用时 `stop` 掉。
+- 该 profile 会累积登录态凭证，等价于一份浏览器身份。要彻底清理：`stop` 后删除 profile 目录（macOS 默认 `~/Library/Application Support/Chrome-CDP-Automation`）。**这个过程不可逆，删了就要重新登录。**
+- profile 永不放进共享仓库（有测试 `默认 profile 路径…不在共享仓库内` 守着这条）。
+- `cookies` 只打印长度不打印值；`net` 只打印 cookie 名。避免凭证进日志/上下文。
+- `eval` 是在目标页面上下文里执行任意 JS，等同于该页面的权限。跨域、HttpOnly、同源策略照旧生效，绕不过。
+
+## 验证状态
+
+已实测（在技能目录下 `node --test "tests/**/*.test.mjs"`）：
+
+> 坑：`node --test tests/`（目录形式）在 Node 21+ 会直接失败——不再扫描目录，而是把目录当模块 `import`。
+> 必须用显式 glob 或 `node --test` 无参数形式。`tests/entrypoints.test.mjs` 里有测试守着这条。
+
+- 入口契约：`help` 不需要 Chrome、不创建任何目录、退出码 0；每个已注册命令都有 `help`；usage 正文与注册表不漂移；未知命令/缺参数退出码 1 且不抛裸 JS 异常；未启动时报错含 `cdpctl launch`
+- 路径策略：`CDPCTL_PROFILE` / `CDPCTL_CHROME` 覆盖生效；默认 profile 落在用户数据目录且不在共享仓库内；找不到 Chrome 时列出已尝试路径
+- 端到端（真实 Chrome + 临时 profile + headless）：`launch` 幂等 → `wait` → `type` 触发受控组件 state 更新 → `click` 触发监听器 → contenteditable 输入 → `eval`/`find` → `press` → `shot` 落盘 → `cookies` → `persist-cookies` → `stop`
+- 端到端（`tests/inspect.test.mjs`）：`snapshot`/`@引用`（含 shadow DOM）→ dialog accept/dismiss/prompt → `fill` 五字段 + 失败逐条报告 → `console` 回放/过滤/`--reload` → `drag`（JS + 原生 HTML5）→ 元素截图尺寸 → `nav --back/--forward/--reload` → 失效引用的报错提示
+- 测试辨别力：直接 `el.value=` 赋值时夹具镜像**不更新**，`cdpctl type` 时更新 → 证明 `type` 的受控组件路径是被真实验证的，不是空跑
+
+未验证（不要当成已支持）：
+
+- Windows / Linux 的浏览器探测与启动分支（代码已写，本地无法验证）
+- headless 模式下的登录类流程（部分站点对 headless 有反自动化策略，登录建议用可见模式）
+- 非 Chromium 内核浏览器
diff --git a/skills/cdp-page-control/SKILL.md b/skills/cdp-page-control/SKILL.md
new file mode 100644
index 0000000..cff1d0b
--- /dev/null
+++ b/skills/cdp-page-control/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: cdp-page-control
+description: 用 Chrome DevTools Protocol 驱动一个受控浏览器操作任意网站页面：页面快照取 @N 元素引用、导航/回退/刷新、等元素、填表、点击、拖拽、按键、读文本、截图（整页或元素）、读控制台报错、抓网络请求、跨重启保持登录态。用户要求在某个网站上填表/提交/点击/翻页/拖拽/抓数据/截图/排查前端报错，或需要复用已登录的浏览器会话做页面自动化时使用。
+platforms: all
+compatibility: 需要 node >=22（用内置 WebSocket，零第三方依赖）。浏览器自动探测 Chrome/Chromium/Edge，可用 CDPCTL_CHROME 覆盖。macOS 已完整验证；Windows/Linux 的浏览器探测与启动分支已实现但未验证。
+---
+
+# 浏览器页面控制（CDP 原语）
+
+失败 → 动作：`error=usage` 读 `pi-skill cdp-page-control help`；`error=deps` 补依赖；`error=auth` 跑本技能的登录/检查命令；
+`error=notfound` 先 `status`/`targets` 重新定位；`error=conflict` 先 `status`；其它非零按输出里的 `hint=` 执行。
+
+入口（路径相对本技能目录）：`node scripts/cdpctl.mjs <命令> [参数]`
+
+**不要重新发明轮子**：不要临时写 Puppeteer/Playwright/selenium 脚本，不要用 AppleScript 发 JS，不要手动拼 CDP 协议。先 `cdpctl help <命令>`，再执行。
+
+## 最小工作流
+
+```bash
+pi-skill cdp-page-control launch --url "<URL>"     # 1. 确保受控浏览器在跑（幂等，可反复调）
+pi-skill cdp-page-control snapshot                 # 2. 不认识的页面先快照，直接拿到 @N 引用
+pi-skill cdp-page-control wait "<选择器>"           # 3. 等页面元素出现（别用 sleep）
+pi-skill cdp-page-control click "<选择器>"          # 4. 交互（snapshot 给的 @N 可以直接当选择器）
+pi-skill cdp-page-control type  "<选择器>" "文本"    #    （受控组件安全输入）
+pi-skill cdp-page-control text  "<选择器>"          # 5. 读取结果验证
+```
+
+出任何问题，**第一件事跑 `status`**（端口 / profile / 当前页面列表全在里面）。
+
+## 选择器（所有命令通用）
+
+| 写法 | 含义 |
+|---|---|
+| `#id` `.class` `[data-x="y"]` | 标准 CSS |
+| `text=提交` | 文本内容完全相等（元素没有稳定 class 时最好用；多个候选时取最内层里可见的那个） |
+| `xpath=//div[3]/button` | XPath |
+| `@3` | `snapshot` 输出的引用编号（穿透 open shadow DOM；页面重渲染后失效，重跑 snapshot） |
+
+同源 iframe 内部：加 `--frame "<iframe的CSS选择器>"`（所有命令通用），坐标自动换算回宿主页面。跨域 iframe 进不去。
+
+多标签页时用 `--match "<URL或标题片段>"` 指定目标；只有一个页面时会自动选中。
+**要精确复用某个标签页用 `--target <targetId>`**（id 从 `status`/`targets`/`open` 拿）：
+重定向会让 `--match` 失配，同域名的其他标签页会让它歧义，编排类脚本应当用 `--target`。
+
+## 五条稳定性铁律
+
+0. **不认识的页面先 `snapshot`。** 一次拿到全部可交互/结构元素与 `@N` 引用，直接 `click "@3"`，省掉逐个猜选择器的多轮试探。网页对话框（alert/confirm/prompt/beforeunload）会被自动应答（默认接受），不会卡住后续命令。
+1. **等元素，不要 sleep。** `wait`、`click`、`type` 内部都会轮询等待可见可点击（默认 15 秒，`--timeout 秒` 改；写毫秒值会被拒绝）。固定 `sleep` 是自动化最大的不稳定来源。
+2. **填普通输入框只用 `type`，绝不用 `eval` 直接赋值。** React/Vue 受控组件下 `el.value = x` 不会更新框架状态，提交上去还是空值。`type` 走原生 value setter + `input`/`change` 事件，是唯一可靠路径。这条已用夹具页面反证验证过。
+   例外：**自绘编辑器**（Monaco / ProseMirror / CodeMirror / 各类 chat 输入框）不是 input/textarea，`type` 改不动它们；改用 `click "<编辑区>"` 聚焦 → `insert-text "<文本>"`（浏览器原生编辑管线，会发真 beforeinput/input）。清空这类编辑器要用真实按键：`press ctrl+a` 然后 `press backspace`（`execCommand('delete')` 会被它们忽略）。
+3. **点击用 `click`（真实鼠标事件）**，比 `el.click()` 更接近人操作。`text=` 定位按钮文字通常最稳。
+4. **操作完立刻验证。** 用 `text` / `eval` 读回状态确认生效，不要假设成功。
+
+## 配方表
+
+| 需求 | 命令 |
+|---|---|
+| 打开网站 | `launch --url "<URL>"` |
+| 跳转已有页面 | `nav "<URL>"` |
+| 刷新 / 回退 / 前进 | `nav --reload` / `nav --back` / `nav --forward` |
+| 搜索框输入并回车 | `type "<选择器>" "关键词"` 然后 `press enter` |
+| 逐字段填表 | 对每个字段一次 `type`；选择器优先用 `input[placeholder="..."]` 或 `input[name=...]` |
+| 往 Monaco／聊天输入框这类自绘编辑器输入 | `click "<编辑区>"` 聚焦 → `insert-text "<文本>"`（长文本用 `insert-text --file 文本.txt`），然后 `click` 发送按钮或 `press enter`；清空用 `press ctrl+a` + `press backspace` |
+| 点按钮 | `click "text=提交"` |
+| 勾选/切换 | `click "<选择器>"` |
+| 看不懂页面 / 找不到元素 | `snapshot`（`--all` 连正文文本一起看；`--max` 限条数） |
+| 一次填完整张表 | `fill --file fields.json`（`{"选择器": 值}`：字符串输入/选下拉，布尔值填勾选框） |
+| 页面点不动 / 报错排查 | `console`（含历史回放与未捕获异常）；抓加载期报错用 `console --reload` |
+| 拖拽（JS 与原生 HTML5 拖放） | `drag "<来源选择器>" "<目标选择器>"` |
+| 抓列表/表格数据 | `eval` 返回 JSON，如 `[...document.querySelectorAll(".row")].map(e=>e.innerText)` |
+| 滚动加载更多 | `eval "window.scrollTo(0,document.body.scrollHeight)"` 然后 `wait` 新元素 |
+| 截图存证 | `shot /tmp/x.png`（带上选择器只截那个元素；视口内区域用 `--clip x,y,w,h`）；**大页面/整页**用 `pdf /tmp/x.pdf --size WxH --media screen` + `qlmanage -t -s 2*max(W,H)`（`--full` 在大画布上会卡死，见 REFERENCE） |
+| 上传文件 | `upload "input[type=file]" /绝对/路径` |
+| 展开被折叠的内容 | `click` 对应按钮/tab，再 `wait` 目标元素 |
+| **让登录态活过浏览器重启** | `persist-cookies --domain <域名片段>` |
+| **复用日常 Chrome 已有登录态** | `import-cookies --profile Default`（默认预览；`--yes` 执行；全量复制） |
+| 查站点到底靠什么维持登录 | `net --grep "/api"`（打印每个请求携带的 cookie 名，不打印值） |
+| 查元素到底存不存在/在哪 | `find "<选择器>"`（返回几何与可见性） |
+| 复杂 JS | 写成文件再 `eval --file probe.js`，避免 shell 引号地狱 |
+| 操作同源 iframe 内的表单 | 任意命令加 `--frame "#inner"`（如 `click "text=提交" --frame "#inner"`） |
+
+组合多个动作时用 `&&` 串成一条 bash 调用，减少往返。
+
+## 登录态与身份
+
+- 受控浏览器用**独立 profile**（默认 `~/Library/Application Support/Chrome-CDP-Automation`），**不会碰你日常用的 Chrome**。profile 持久保留，登录一次可长期复用。
+- `launch` 幂等：已经在跑就直接复用，所以在任何流程里都可以放心先调一次。
+- **会话 cookie 默认活不过浏览器重启**（Chrome 会删）。想免二次登录就执行 `persist-cookies --domain <域名>`：它只把 cookie 的过期时间元数据改到 2030 年，密文一字不改。注意它会先关掉浏览器。
+- 站点把凭证放 localStorage（很常见，例如 `userToken`）时，localStorage 本身跨重启持久，无需额外处理。
+- **不能保证**登录态永久有效：服务端会话过期由站点决定，浏览器侧只能保证不丢凭证。
+
+## 能力边界（做不到的事，别浪费轮次）
+
+- 跨域 iframe 内部：受同源策略限制，进不去（同源 iframe 用 `--frame` 可以）。
+- closed shadow DOM 内部：能拿到宿主，拿不到内部节点。
+- 真人验证（验证码/风控挑战）、passkey、支付确认：必须人来做。
+- HttpOnly cookie 的**值**：`cookies` 只报长度；页面 JS 也读不到。
+- 服务端逻辑、签名、token 校验：前端绕不过。
+- 通过 `eval` 直接调用的合成事件 `isTrusted=false`；需要可信事件时用 `click`/`type`/`press`。
+
+## 排查
+
+先 `status`，再看 `help <命令>`。故障排查、持久化原理、安全说明、扩展方式见 **REFERENCE.md**。
+
+环境变量：`CDPCTL_PORT`（默认 9222）、`CDPCTL_PROFILE`、`CDPCTL_CHROME`、`CDPCTL_HEADLESS=1`、
+`CDPCTL_DIALOG`（对话框策略 accept/dismiss/ignore，默认 accept）、`CDPCTL_DIALOG_TEXT`（prompt 应答文本）。
+
+改动本技能后必须跑测试：`node --test "tests/**/*.test.mjs"`（入口契约 + 真实端到端冒烟）。
+注意别写成 `node --test tests/`：Node 21+ 不再把目录参数当目录扫描，而是当模块 `import`，会直接报 `Cannot find module .../tests`。
+
+**外部真实站点测试**（`tests/realworld.test.mjs`，默认跳过）会跑 saucedemo 的完整下单流程；
+那个公共演示站连续跑会被限流，所以只有显式开启时才跑：
+
+```bash
+CDPCTL_TEST_REALWORLD=1 node --test tests/realworld.test.mjs
+```
diff --git a/skills/cdp-page-control/VERSION b/skills/cdp-page-control/VERSION
new file mode 100644
index 0000000..6e8bf73
--- /dev/null
+++ b/skills/cdp-page-control/VERSION
@@ -0,0 +1 @@
+0.1.0
diff --git a/skills/cdp-page-control/contract.lock.json b/skills/cdp-page-control/contract.lock.json
new file mode 100644
index 0000000..7af641b
--- /dev/null
+++ b/skills/cdp-page-control/contract.lock.json
@@ -0,0 +1,107 @@
+{
+  "version": 1,
+  "skill": "cdp-page-control",
+  "tier": 1,
+  "platforms": [
+    "all"
+  ],
+  "commands": {
+    "click": {
+      "destructive": false
+    },
+    "close": {
+      "destructive": false
+    },
+    "console": {
+      "destructive": false
+    },
+    "cookies": {
+      "destructive": false
+    },
+    "drag": {
+      "destructive": false
+    },
+    "eval": {
+      "destructive": false
+    },
+    "fill": {
+      "destructive": false
+    },
+    "find": {
+      "destructive": false
+    },
+    "hover": {
+      "destructive": false
+    },
+    "html": {
+      "destructive": false
+    },
+    "import-cookies": {
+      "destructive": false
+    },
+    "insert-text": {
+      "destructive": false
+    },
+    "launch": {
+      "destructive": false
+    },
+    "nav": {
+      "destructive": false
+    },
+    "net": {
+      "destructive": false
+    },
+    "open": {
+      "destructive": false
+    },
+    "persist-cookies": {
+      "destructive": false
+    },
+    "press": {
+      "destructive": false
+    },
+    "select": {
+      "destructive": false
+    },
+    "shot": {
+      "destructive": false
+    },
+    "snapshot": {
+      "destructive": false
+    },
+    "status": {
+      "destructive": false
+    },
+    "stop": {
+      "destructive": false
+    },
+    "targets": {
+      "destructive": false
+    },
+    "text": {
+      "destructive": false
+    },
+    "type": {
+      "destructive": false
+    },
+    "upload": {
+      "destructive": false
+    },
+    "wait": {
+      "destructive": false
+    }
+  },
+  "errors": [
+    "auth",
+    "blocked",
+    "external",
+    "internal",
+    "notfound",
+    "timeout",
+    "usage"
+  ],
+  "aliases": [
+    "cdpctl"
+  ],
+  "adminAliases": []
+}
diff --git a/skills/cdp-page-control/interface.json b/skills/cdp-page-control/interface.json
new file mode 100644
index 0000000..9783046
--- /dev/null
+++ b/skills/cdp-page-control/interface.json
@@ -0,0 +1,146 @@
+{
+  "summary": "驱动受控浏览器操作任意网站页面（导航、填表、点击、读文本、截图、抓网络）",
+  "useWhen": "要在某个网站的页面上点击/填表/翻页/取文本/截图/抓接口，或用已登录的浏览器会话做页面自动化时",
+  "tier": 1,
+  "entry": {
+    "path": "scripts/cdpctl.mjs"
+  },
+  "aliases": [
+    "cdpctl"
+  ],
+  "commands": [
+    {
+      "name": "launch",
+      "summary": "启动/复用受控浏览器"
+    },
+    {
+      "name": "nav",
+      "summary": "打开 URL / 前进 / 后退 / 刷新"
+    },
+    {
+      "name": "snapshot",
+      "summary": "页面结构快照：可见交互元素 + @N 引用"
+    },
+    {
+      "name": "wait",
+      "summary": "等元素/条件出现"
+    },
+    {
+      "name": "find",
+      "summary": "找元素，返回定位器"
+    },
+    {
+      "name": "click",
+      "summary": "点击元素"
+    },
+    {
+      "name": "type",
+      "summary": "输入文本"
+    },
+    {
+      "name": "fill",
+      "summary": "按 JSON 批量填表（输入/下拉/勾选）"
+    },
+    {
+      "name": "press",
+      "summary": "按键/组合键"
+    },
+    {
+      "name": "drag",
+      "summary": "真实鼠标拖拽（含原生 HTML5 拖放）"
+    },
+    {
+      "name": "select",
+      "summary": "下拉选择"
+    },
+    {
+      "name": "hover",
+      "summary": "悬停元素"
+    },
+    {
+      "name": "upload",
+      "summary": "上传文件"
+    },
+    {
+      "name": "insert-text",
+      "summary": "向焦点元素插入文本（自绘编辑器）"
+    },
+    {
+      "name": "text",
+      "summary": "读元素文本"
+    },
+    {
+      "name": "html",
+      "summary": "读元素 HTML"
+    },
+    {
+      "name": "eval",
+      "summary": "在页面里执行 JS"
+    },
+    {
+      "name": "net",
+      "summary": "抓网络请求"
+    },
+    {
+      "name": "console",
+      "summary": "读控制台消息（含历史回放与异常）"
+    },
+    {
+      "name": "shot",
+      "summary": "截图（整页或单个元素）"
+    },
+    {
+      "name": "pdf",
+      "summary": "整页导出 PDF（打印管线，一次调用拿到全部内容，不受视口限制）：pdf <out.pdf> --size WxH [--media screen|print]；要 PNG 再用 qlmanage -t -s <2*max(W,H)> 矢量重栅格"
+    },
+    {
+      "name": "cookies",
+      "summary": "读写 cookie"
+    },
+    {
+      "name": "import-cookies",
+      "summary": "把日常 Chrome 的登录态复制进受控浏览器（默认预览，--yes 执行）"
+    },
+    {
+      "name": "persist-cookies",
+      "summary": "把会话 cookie 改成持久 cookie（跨重启保登录）"
+    },
+    {
+      "name": "targets",
+      "summary": "列出标签页"
+    },
+    {
+      "name": "open",
+      "summary": "新开标签页"
+    },
+    {
+      "name": "close",
+      "summary": "关闭标签页"
+    },
+    {
+      "name": "status",
+      "summary": "浏览器状态"
+    },
+    {
+      "name": "stop",
+      "summary": "关闭受控浏览器"
+    }
+  ],
+  "errors": [
+    "usage",
+    "auth",
+    "notfound",
+    "blocked",
+    "timeout",
+    "external",
+    "internal"
+  ],
+  "helpListsCommands": true,
+  "publish": {
+    "package_repo": "https://gitea.vhkd.top/geekinney/cdp-page-control.git"
+  },
+  "catalog": {
+    "layer": "core",
+    "why": "别的技能建在它上面"
+  }
+}
diff --git a/skills/cdp-page-control/scripts/cdp-channel.mjs b/skills/cdp-page-control/scripts/cdp-channel.mjs
new file mode 100644
index 0000000..3fb5ca0
--- /dev/null
+++ b/skills/cdp-page-control/scripts/cdp-channel.mjs
@@ -0,0 +1,815 @@
+// 通道层：CDP 传输 + 浏览器生命周期 + 选择器解析。
+// 只做「把参数变成协议调用」，不含任何站点业务逻辑。
+
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readSync, statSync } from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PROFILE_NAME = 'Chrome-CDP-Automation';
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/** 页面无响应时统一的提示：对话框阻塞是最常见原因，且残留后无法从新连接救援。 */
+export const DIALOG_HINT = '页面可能被 JavaScript 对话框（alert/confirm/prompt/beforeunload）或死循环阻塞；残留的对话框无法从新连接处理，需 cdpctl stop && cdpctl launch 重启浏览器。';
+
+/** 固定端口，可用 CDPCTL_PORT 覆盖。 */
+export function port() {
+  return Number(process.env.CDPCTL_PORT || 9222);
+}
+
+/** 本机自动化 profile 目录（持久，含登录态）。绝不放共享仓库内。 */
+export function profileDir() {
+  if (process.env.CDPCTL_PROFILE) return process.env.CDPCTL_PROFILE;
+  const home = os.homedir();
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', PROFILE_NAME);
+  }
+  if (process.platform === 'win32') {
+    const base = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    return path.join(base, PROFILE_NAME);
+  }
+  const base = process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+  return path.join(base, PROFILE_NAME);
+}
+
+function which(bin) {
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const p = path.join(dir, bin + ext);
+      if (existsSync(p)) return p;
+    }
+  }
+  return null;
+}
+
+/** 默认的 Chrome 候选路径（按平台）。可单独调用来排查探测问题。 */
+export function chromeCandidates() {
+  const tried = [];
+  const add = (...p) => tried.push(...p.filter(Boolean));
+
+  if (process.platform === 'darwin') {
+    add('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+        '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser');
+  } else if (process.platform === 'win32') {
+    for (const root of [process.env['ProgramFiles'], process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA]) {
+      add(root && path.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+          root && path.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+    }
+  } else {
+    for (const b of ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser', 'microsoft-edge']) {
+      add(which(b));
+    }
+  }
+  return tried;
+}
+
+/**
+ * Chrome/Chromium/Edge 可执行文件。
+ * CDPCTL_CHROME 优先；否则依次检查 chromeCandidates()。
+ * candidates 参数是可注入接缝，便于独立测试「找不到」的错误分支。
+ */
+export function chromePath(candidates = chromeCandidates()) {
+  if (process.env.CDPCTL_CHROME) return process.env.CDPCTL_CHROME;
+  for (const p of candidates) if (existsSync(p)) return p;
+  throw new Error(
+    '找不到 Chrome/Chromium 可执行文件。\n  用 CDPCTL_CHROME=<绝对路径> 指定。\n  已尝试:\n    ' + candidates.join('\n    ')
+  );
+}
+
+export async function httpJson(route, method = 'GET') {
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${port()}${route}`, { method });
+  } catch (e) {
+    throw new Error(
+      `连不上 CDP 127.0.0.1:${port()}（${e.cause?.code || e.message}）。\n` +
+      `  先启动: cdpctl launch --url <URL>\n` +
+      `  看状态: cdpctl status`
+    );
+  }
+  if (!res.ok) throw new Error(`CDP 返回 HTTP ${res.status}: ${route}`);
+  const text = await res.text();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+/** 浏览器是否在跑；返回 version 对象或 null。 */
+export async function version(timeoutMs = 1500) {
+  try {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), timeoutMs);
+    const res = await fetch(`http://127.0.0.1:${port()}/json/version`, { signal: ctl.signal });
+    clearTimeout(t);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch { return null; }
+}
+
+/** 列出所有调试目标；未启动时给出可操作的报错。 */
+export async function listTargets() {
+  return (await httpJson('/json/list')) || [];
+}
+
+/**
+ * 选页面目标。
+ * 无 match 时：优先排除 about:blank，唯一命中才自动采用，否则报错并列出候选。
+ */
+export function pickPage(targets, match, target) {
+  const pages = targets.filter(t => t.type === 'page');
+  if (!pages.length) throw new Error('没有 page 目标。先运行: cdpctl launch --url <URL>');
+
+  // 按 targetId 精确定位：编排多个标签页时比 --match 可靠
+  // （--match 命中 URL/标题片段，重定向后会失配，同名页面会歧义）。
+  if (target) {
+    const hit = pages.find(t => t.id === target);
+    if (!hit) {
+      throw new Error(`--target "${target}" 不存在（页面可能已关闭或被导航走）。当前页面:\n` +
+        pages.map(t => `  id=${t.id}  ${t.title || '(无标题)'}  ${t.url}`).join('\n') +
+        '\n用 cdpctl status 或 targets 取最新的 id。');
+    }
+    return hit;
+  }
+
+  if (match) {
+    const hit = pages.filter(t => (t.url || '').includes(match) || (t.title || '').includes(match));
+    if (!hit.length) {
+      throw new Error(`--match "${match}" 无命中。当前页面:\n` + pages.map(t => `  ${t.title}  ${t.url}`).join('\n'));
+    }
+    if (hit.length > 1) {
+      throw new Error(`--match "${match}" 命中 ${hit.length} 个，请写得更精确:\n` + hit.map(t => `  ${t.url}`).join('\n'));
+    }
+    return hit[0];
+  }
+
+  const real = pages.filter(t => !/^about:blank$/.test(t.url || ''));
+  const pool = real.length ? real : pages;
+  if (pool.length === 1) return pool[0];
+  throw new Error(
+    `有 ${pages.length} 个页面，无法自动选择。用 --match <URL或标题片段> 指定:\n` +
+    pages.map(t => `  ${t.title || '(无标题)'}  ${t.url}`).join('\n')
+  );
+}
+
+/** 最小 CDP 客户端（零依赖，用 Node 内置 WebSocket）。 */
+export class CDP {
+  constructor(wsUrl) {
+    this.wsUrl = wsUrl;
+    this.seq = 0;
+    this.pending = new Map();
+    this.listeners = new Set();
+  }
+
+  static connect(wsUrl) {
+    return new Promise((resolve, reject) => {
+      const c = new CDP(wsUrl);
+      c.ws = new WebSocket(wsUrl);
+      const to = setTimeout(() => reject(new Error('WebSocket 连接超时: ' + wsUrl)), 10000);
+      c.ws.onopen = () => { clearTimeout(to); resolve(c); };
+      c.ws.onerror = () => { clearTimeout(to); reject(new Error('WebSocket 连接失败: ' + wsUrl)); };
+      c.ws.onmessage = ev => {
+        const m = JSON.parse(ev.data);
+        if (m.id && c.pending.has(m.id)) {
+          const { resolve: res, reject: rej } = c.pending.get(m.id);
+          c.pending.delete(m.id);
+          m.error ? rej(new Error(`${m.error.message} ${JSON.stringify(m.error.data ?? '')}`))
+                  : res(m.result);
+          return;
+        }
+        if (m.method) for (const fn of c.listeners) fn(m);
+      };
+    });
+  }
+
+  on(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+
+  /**
+   * 发一条 CDP 命令。timeoutMs>0 时超时会拒绝并带上 timeoutHint——
+   * 页面被对话框/死循环阻塞时 CDP 调用会永久挂起，超时兜底把「挂死」变成可操作的报错。
+   */
+  send(method, params = {}, { timeoutMs = 0, timeoutHint = '' } = {}) {
+    const id = ++this.seq;
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          if (!this.pending.has(id)) return;
+          this.pending.delete(id);
+          reject(new Error(`CDP ${method} ${timeoutMs}ms 无响应${timeoutHint ? '。' + timeoutHint : ''}`));
+        }, timeoutMs);
+      }
+      this.pending.set(id, {
+        resolve: v => { if (timer) clearTimeout(timer); resolve(v); },
+        reject: e => { if (timer) clearTimeout(timer); reject(e); },
+      });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  close() { try { this.ws.close(); } catch { /* 已关闭 */ } }
+}
+
+/** 连到浏览器级 endpoint（用于 Browser.close / 新建目标）。 */
+export async function connectBrowser() {
+  const v = await version();
+  if (!v?.webSocketDebuggerUrl) throw new Error(`CDP 未就绪于 127.0.0.1:${port()}。先运行: cdpctl launch`);
+  return CDP.connect(v.webSocketDebuggerUrl);
+}
+
+/**
+ * 对话框自动处理。实测结论（Chrome 153）：
+ * - 对话框打开会阻塞后续 CDP 调用：Page.enable / Runtime.evaluate / Input.* 全部挂起，
+ *   连触发弹窗那次 mouseReleased 的响应都要等对话框被处理后才返回；
+ * - 对话框残留后，新连接既收不到事件也 handle 不掉（Page.enable 先挂死）——
+ *   所以必须在动作之前装好处理器，绝不能让它残留。
+ * mode: accept（默认，自动化合理默认）| dismiss | ignore（不装处理器，保留原生行为）。
+ * prompt 的自动应答文本用 CDPCTL_DIALOG_TEXT 指定，缺省用页面给的 defaultPrompt。
+ */
+export function installDialogHandler(cdp, mode = 'accept') {
+  if (!['accept', 'dismiss', 'ignore'].includes(mode)) {
+    throw new Error(`CDPCTL_DIALOG 只支持 accept / dismiss / ignore，收到 "${mode}"`);
+  }
+  if (mode === 'ignore') return { enable: Promise.resolve() };
+  const enable = cdp.send('Page.enable', {}, { timeoutMs: 5000, timeoutHint: DIALOG_HINT });
+  enable.catch(() => {}); // 让 connectPage 的警告提示接管错误
+  cdp.on(m => {
+    if (m.method !== 'Page.javascriptDialogOpening') return;
+    const p = { accept: mode === 'accept' };
+    if (p.accept && m.params.type === 'prompt') {
+      p.promptText = process.env.CDPCTL_DIALOG_TEXT ?? m.params.defaultPrompt ?? '';
+    }
+    cdp.send('Page.handleJavaScriptDialog', p).catch(() => {});
+  });
+  return { enable };
+}
+
+/** 连到某个页面；默认自动装对话框处理器。 */
+export async function connectPage(match, target, { dialogs = process.env.CDPCTL_DIALOG || 'accept' } = {}) {
+  const t = pickPage(await listTargets(), match, target);
+  const cdp = await CDP.connect(t.webSocketDebuggerUrl);
+  const h = installDialogHandler(cdp, dialogs);
+  await h.enable.catch(e => {
+    console.error('警告: 对话框保护未就绪 — ' + e.message);
+  });
+  return { cdp, target: t };
+}
+
+/** 在页面执行 JS。timeoutMs>0 时超时拒绝（用于页面被阻塞时快速报错）。 */
+export async function evaluate(cdp, expression, { awaitPromise = true, userGesture = true, timeoutMs = 0 } = {}) {
+  const r = await cdp.send('Runtime.evaluate', {
+    expression, awaitPromise, returnByValue: true, userGesture, includeCommandLineAPI: true,
+  }, timeoutMs ? { timeoutMs, timeoutHint: DIALOG_HINT } : {});
+  if (r.exceptionDetails) {
+    const d = r.exceptionDetails;
+    throw new Error('页面内异常: ' + (d.exception?.description || d.text));
+  }
+  return r.result.value;
+}
+
+/** 等待页面 load 事件。 */
+export function waitLoad(cdp, timeout = 30000) {
+  return new Promise(resolve => {
+    let off = () => {};
+    const t = setTimeout(() => { off(); resolve('timeout'); }, timeout);
+    off = cdp.on(m => {
+      if (m.method === 'Page.loadEventFired') { clearTimeout(t); off(); resolve('load'); }
+    });
+    cdp.send('Page.enable').catch(() => {});
+  });
+}
+
+/**
+ * 选择器语法 -> 返回元素的 JS 表达式。支持三种：
+ *   css        querySelector 语法
+ *   text=文本  文本内容完全相等（取最内层匹配，避免命中外层容器）
+ *   xpath=表达式
+ * root 是解析起点：主文档用 'document'，iframe 内用其 contentDocument 变量名。
+ * win  是该 realm 的 window：主文档 'window'，iframe 内 'w'（跨 realm 调 getComputedStyle 会抛错）。
+ */
+export function selectorExpr(sel, root = 'document', win = 'window') {
+  if (sel.startsWith('@')) {
+    // 快照引用：snapshot 给元素打的 data-cdpctl-ref。
+    // 引用可能落在 open shadow root 里，querySelector 不穿透，所以用 JS 递归查找。
+    const n = sel.slice(1);
+    if (!/^\d+$/.test(n)) {
+      throw new Error(`快照引用格式是 @数字（如 @3），收到 "${sel}"。跑 cdpctl snapshot 获取当前页面的引用。`);
+    }
+    return `(() => {
+      const find = r => {
+        const hit = r.querySelector('[data-cdpctl-ref="${n}"]');
+        if (hit) return hit;
+        for (const e of r.querySelectorAll('*')) if (e.shadowRoot) { const h = find(e.shadowRoot); if (h) return h; }
+        return null;
+      };
+      return find(${root});
+    })()`;
+  }
+  if (sel.startsWith('text=')) {
+    return `(() => {
+      const want = ${JSON.stringify(sel.slice(5))};
+      const tt = s => (s || '').trim().replace(/\\s+/g, ' ');
+      const all = [...${root}.querySelectorAll('*')].filter(e => tt(e.textContent) === want);
+      if (!all.length) return null;
+      // 必须取最内层：外层容器（如包着按钮的 div）的 textContent 也相等，
+      // 选中它会让点击落在容器空白处，静默不生效。
+      const inner = all.filter(e => !all.some(o => o !== e && e.contains(o)));
+      // 真页面上常有隐藏的重复项（折叠菜单、移动端导航副本）排在前面（DeepSeek 实测）；
+      // 只看「第一个最内层」会选中不可见元素，导致 wait/click 静默失败。优先取可见的。
+      const visible = e => {
+        const r = e.getBoundingClientRect();
+        if (r.width <= 0 || r.height <= 0) return false;
+        const cs = ${win}.getComputedStyle(e);
+        return cs.visibility !== 'hidden' && cs.display !== 'none';
+      };
+      return inner.find(visible) || inner[0] || all[0];
+    })()`;
+  }
+  if (sel.startsWith('xpath=')) {
+    return `${root}.evaluate(${JSON.stringify(sel.slice(6))}, ${root}, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`;
+  }
+  return `${root}.querySelector(${JSON.stringify(sel)})`;
+}
+
+/**
+ * 页面结构快照：把可见的「交互 + 结构」元素打上 data-cdpctl-ref，返回缩进文本树。
+ * 所有命令的选择器都支持 @N（见 selectorExpr），一次调用看懂整页。
+ * all=true 额外纳入带可见文本的叶子节点；max 限制输出节点数（0=不限）。
+ * 引用会在页面重渲染后失效，届时重跑 snapshot 即可。
+ */
+export function snapshotExpr({ all = false, max = 250 } = {}) {
+  const limit = Number(max) > 0 ? Math.floor(Number(max)) : Number.MAX_SAFE_INTEGER;
+  return `(() => {
+    const REF = 'data-cdpctl-ref';
+    const MAX = ${limit};
+    const ALL = ${all ? 'true' : 'false'};
+    const txt = (s, n) => String(s == null ? '' : s).trim().replace(/\\s+/g, ' ').slice(0, n);
+    const TAG = new Set(['A','BUTTON','INPUT','SELECT','TEXTAREA','SUMMARY','IFRAME']);
+    const STRUCT = new Set(['MAIN','NAV','HEADER','FOOTER','ASIDE','FORM','TABLE','DETAILS']);
+    const ROLES = new Set(['button','link','textbox','searchbox','combobox','listbox','checkbox','radio','switch','slider','spinbutton','menuitem','menuitemcheckbox','menuitemradio','tab','option','treeitem','dialog','alertdialog','alert','status','progressbar']);
+    const isField = el => el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
+    const visible = el => {
+      const r = el.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) return false;
+      const cs = getComputedStyle(el);
+      return cs.display !== 'none' && cs.visibility !== 'hidden';
+    };
+    const nameOf = el => {
+      const aria = el.getAttribute('aria-label');
+      if (aria) return txt(aria, 90);
+      const by = el.getAttribute('aria-labelledby');
+      if (by) {
+        const t = by.split(/\\s+/).map(id => { const x = document.getElementById(id); return x ? (x.innerText || x.textContent) : ''; }).join(' ');
+        if (txt(t, 90)) return txt(t, 90);
+      }
+      if (isField(el)) {
+        const l = el.labels && el.labels[0];
+        if (l) return txt(l.innerText || l.textContent, 90);
+        if (el.placeholder) return 'placeholder: ' + txt(el.placeholder, 70);
+        if (el.title) return txt(el.title, 90);
+        if (['submit','reset','button'].includes((el.type || '').toLowerCase())) return txt(el.value, 90);
+        return '';
+      }
+      if (el.tagName === 'IMG') return txt(el.alt, 90);
+      if (STRUCT.has(el.tagName) || el.tagName === 'IFRAME') return txt(el.title, 90);
+      let direct = '';
+      for (const n of el.childNodes) if (n.nodeType === 3) direct += n.textContent;
+      return txt(direct.trim() ? direct : (el.innerText || el.textContent), 90);
+    };
+    const keep = el => {
+      const tag = el.tagName;
+      if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'NOSCRIPT' || tag === 'TEMPLATE') return false;
+      if (tag === 'INPUT' && (el.type || '').toLowerCase() === 'hidden') return false;
+      if (TAG.has(tag) || /^H[1-6]$/.test(tag) || STRUCT.has(tag)) return true;
+      if (el.isContentEditable) return true;
+      if (tag === 'IMG') return !!el.alt;
+      if (ROLES.has((el.getAttribute('role') || '').toLowerCase())) return true;
+      if (ALL) for (const n of el.childNodes) if (n.nodeType === 3 && n.textContent.trim()) return true;
+      return false;
+    };
+    const describe = el => {
+      const tag = el.tagName.toLowerCase();
+      const type = (el.type || '').toLowerCase();
+      const head = tag === 'a' ? 'link' : (tag === 'input' ? 'input[' + (type || 'text') + ']' : tag);
+      const nm = nameOf(el);
+      let s = head + (nm ? ' "' + nm + '"' : '');
+      if (tag === 'a' && el.href) s += ' → ' + txt(el.href, 110);
+      if (tag === 'iframe' && el.src) s += ' → ' + txt(el.src, 110);
+      if (tag === 'input') {
+        if (type === 'checkbox' || type === 'radio') { if (el.checked) s += ' [checked]'; }
+        else if (type === 'password') { if (el.value) s += ' [len=' + el.value.length + ']'; }
+        else if (el.value) s += ' [value=' + JSON.stringify(txt(el.value, 60)) + ']';
+      }
+      if (tag === 'textarea' && el.value) s += ' [len=' + el.value.length + ']';
+      if (tag === 'select' && el.selectedOptions && el.selectedOptions[0]) s += ' [selected=' + JSON.stringify(txt(el.selectedOptions[0].textContent, 50)) + ']';
+      if (el.disabled) s += ' [disabled]';
+      return s;
+    };
+    const clear = root => {
+      for (const e of root.querySelectorAll('[' + REF + ']')) e.removeAttribute(REF);
+      for (const e of root.querySelectorAll('*')) if (e.shadowRoot) clear(e.shadowRoot);
+    };
+    clear(document);
+    const lines = [];
+    let ref = 0, kept = 0, truncated = 0;
+    const walk = (el, depth) => {
+      let d = depth;
+      if (keep(el) && visible(el)) {
+        kept++;
+        if (kept <= MAX) {
+          el.setAttribute(REF, String(++ref));
+          lines.push('  '.repeat(Math.min(depth, 12)) + '@' + ref + ' ' + describe(el));
+          d = depth + 1;
+        } else truncated++;
+      }
+      for (const c of el.children) walk(c, d);
+      if (el.shadowRoot) for (const c of el.shadowRoot.children) walk(c, d);
+    };
+    walk(document.body || document.documentElement, 0);
+    return { url: location.href, title: document.title, kept, truncated, lines };
+  })()`;
+}
+
+/**
+ * 元素几何（页面坐标，左上角）。命中返回 {x,y,w,h,tag}；不存在/不可见返回 null。
+ * frameSel 非空时先在 iframe 内解析，再把坐标换算成宿主页面的坐标；iframe 跨域返回 {frameError}。
+ *
+ * 必须是纯同步求值（见 visibleRectExpr 的禁用 rAF 说明），
+ * 求值返回的是本次布局的坐标，所以紧接着派发鼠标事件是安全的。
+ */
+export function boxExpr(sel, frameSel) {
+  if (!frameSel) {
+    return `(() => {
+      const el = ${selectorExpr(sel)};
+      if (!el) return null;
+      const measure = () => { const r = el.getBoundingClientRect(); return { x: r.x, y: r.y, w: r.width, h: r.height, tag: el.tagName }; };
+      const first = measure();
+      if (first.w === 0 || first.h === 0) return null;
+      const cs = getComputedStyle(el);
+      if (cs.visibility === 'hidden' || cs.display === 'none') return null;
+      // 只在确实看不见时才滚动：已可见的元素保持原布局，
+      // 否则「滚动改变布局 → 坐标过期 → 点空」会在真实站点上静默发生。
+      let box = first;
+      const cx = box.x + box.w / 2, cy = box.y + box.h / 2;
+      if (cx < 0 || cy < 0 || cx > innerWidth || cy > innerHeight) {
+        el.scrollIntoView({ block: 'center', inline: 'center' });
+        box = measure();
+      }
+      const c2x = box.x + box.w / 2, c2y = box.y + box.h / 2;
+      return { ...box, inView: c2x >= 0 && c2y >= 0 && c2x <= innerWidth && c2y <= innerHeight };
+    })()`;
+  }
+  return `(() => {
+    const f = document.querySelector(${JSON.stringify(frameSel)});
+    if (!f) return null;
+    if (!f.contentDocument) return { frameError: 'cross-origin' };
+    const d = f.contentDocument;
+    const w = f.contentWindow;
+    const el = ${selectorExpr(sel, 'd', 'w')};
+    if (!el) return null;
+    // clientLeft/Top = iframe 边框宽度，加上它才是内容区原点
+    const measure = () => {
+      const r = el.getBoundingClientRect();
+      const fr = f.getBoundingClientRect();
+      return { x: fr.left + f.clientLeft + r.x, y: fr.top + f.clientTop + r.y, w: r.width, h: r.height, tag: el.tagName, inFrameY: r.y };
+    };
+    const first = measure();
+    if (first.w === 0 || first.h === 0) return null;
+    const cs = f.contentWindow.getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none') return null;
+    // 内层先居中：iframe 常常比宿主视口高，元素落在 iframe 中部才好对齐。
+    // 之后迭代收敛：每轮重新量一次坐标再滚一次，因为 iframe 内的 scrollIntoView
+    // 可能连带滚动宿主容器（跨 frame 滚动链），单次计算的 delta 会过期。
+    el.scrollIntoView({ block: 'center', inline: 'center' });
+    let box = measure();
+    const inView = b => {
+      const x = b.x + b.w / 2, y = b.y + b.h / 2;
+      return x >= 0 && y >= 0 && x <= innerWidth && y <= innerHeight;
+    };
+    for (let i = 0; i < 4 && !inView(box); i++) {
+      const delta = (innerHeight / 2 - (box.inFrameY + box.h / 2)) - f.getBoundingClientRect().top;
+      if (Math.abs(delta) < 1) break;
+      let sc = f.parentElement;
+      while (sc && sc !== document.body && sc !== document.documentElement) {
+        const c2 = getComputedStyle(sc);
+        if (/(auto|scroll)/.test(c2.overflowY) && sc.scrollHeight > sc.clientHeight) break;
+        sc = sc.parentElement;
+      }
+      if (sc && sc !== document.body && sc !== document.documentElement) {
+        const before = sc.scrollTop;
+        sc.scrollTop = before + delta;
+        if (sc.scrollTop === before) break;
+      } else {
+        const before = window.scrollY;
+        window.scrollBy(0, delta);
+        if (window.scrollY === before) break;
+      }
+      box = measure();
+    }
+    return { x: box.x, y: box.y, w: box.w, h: box.h, tag: box.tag, inView: inView(box) };
+  })()`;
+}
+
+/** 把 boxExpr 的跨域标记转成可读异常，其余原样返回。 */
+export function assertFrameAccess(box, frameSel) {
+  if (box && typeof box === 'object' && box.frameError) {
+    const why = box.frameError === 'cross-origin' ? '跨域 iframe，受同源策略限制' : box.frameError;
+    throw new Error(`无法访问 --frame "${frameSel}" 内部：${why}。跨域 iframe 只能操作其外部宿主元素。`);
+  }
+  return box;
+}
+
+/**
+ * 真实鼠标点击（isTrusted=true）。
+ * box 来自 visibleRectExpr/waitForElement 的同步求值结果，因此紧接着派发是安全的。
+ */
+const INPUT_OPTS = { timeoutMs: 15000, timeoutHint: DIALOG_HINT };
+
+export async function clickAt(cdp, box) {
+  for (const type of ['mouseMoved', 'mousePressed', 'mouseReleased']) {
+    await cdp.send('Input.dispatchMouseEvent', {
+      type, x: box.x, y: box.y, button: 'left', clickCount: 1,
+      buttons: type === 'mousePressed' ? 1 : 0,
+    }, INPUT_OPTS);
+  }
+}
+
+/**
+ * 真实鼠标拖拽：按下 -> 分步移动 -> 松开。
+ * 分步是为了让页面的 mousemove 监听与浏览器原生 HTML5 拖拽控制器都能收到过程事件。
+ * 两端坐标必须已在同一视口内（调用方负责检查）。
+ */
+export async function dragBetween(cdp, from, to, steps = 10) {
+  await cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: from.x, y: from.y, buttons: 0 }, INPUT_OPTS);
+  await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: from.x, y: from.y, button: 'left', clickCount: 1, buttons: 1 }, INPUT_OPTS);
+  for (let i = 1; i <= steps; i++) {
+    await cdp.send('Input.dispatchMouseEvent', {
+      type: 'mouseMoved', button: 'left', buttons: 1,
+      x: from.x + (to.x - from.x) * (i / steps),
+      y: from.y + (to.y - from.y) * (i / steps),
+    }, INPUT_OPTS);
+    await sleep(10); // 给原生拖拽控制器消化过程事件的时间
+  }
+  await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: to.x, y: to.y, button: 'left', clickCount: 1, buttons: 0 }, INPUT_OPTS);
+}
+
+/**
+ * 把文本插入**当前焦点元素**（CDP Input.insertText，走浏览器原生编辑管线）。
+ * 这是自绘编辑器（Monaco / ProseMirror / CodeMirror / React contenteditable）唯一可靠的输入方式，
+ * 因为那些控件不是 input/textarea，原生 value setter 那套（setInputValue）对它们无效。
+ * 前置条件：页面里已经有焦点元素——先自己 clickAt 聚焦，或让调用方负责。
+ */
+export async function insertText(cdp, text) {
+  await cdp.send('Input.insertText', { text }, INPUT_OPTS);
+}
+
+/** 按键表：真实键盘事件用。单字符可直接写，修饰键用 ctrl+a / cmd+enter 形式。 */
+export const KEYS = {
+  enter: { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
+  tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+  escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
+  esc: { key: 'Escape', code: 'Escape', keyCode: 27 },
+  backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+  delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
+  space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+  arrowup: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+  arrowdown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+  arrowleft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+  arrowright: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+  home: { key: 'Home', code: 'Home', keyCode: 36 },
+  end: { key: 'End', code: 'End', keyCode: 35 },
+  pageup: { key: 'PageUp', code: 'PageUp', keyCode: 33 },
+  pagedown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },
+};
+const MOD_BITS = { alt: 1, ctrl: 2, control: 2, meta: 4, cmd: 4, command: 4, shift: 8 };
+
+/** 'ctrl+a' / 'enter' / 'a' → 协议参数。 */
+export function parseKey(spec) {
+  const parts = spec.toLowerCase().split('+');
+  const base = parts.pop();
+  let modifiers = 0;
+  for (const p of parts) {
+    if (!(p in MOD_BITS)) throw new Error(`未知修饰键 "${p}" (可用 ctrl/cmd/shift/alt)`);
+    modifiers |= MOD_BITS[p];
+  }
+  const k = KEYS[base] || (base.length === 1 ? { key: base, code: `Key${base.toUpperCase()}`, keyCode: base.toUpperCase().charCodeAt(0), text: base } : null);
+  if (!k) throw new Error(`未知按键 "${base}"。可用: ${Object.keys(KEYS).join(', ')}，或单字符，或 ctrl+a 形式`);
+  return { ...k, modifiers };
+}
+
+/**
+ * 发真实按键（keyDown + keyUp）。这是让目标控件自己的按键处理生效的唯一方式：
+ * 清空自绘编辑器（ctrl+a 后 backspace）、回车提交、Esc 关弹层等。
+ * 注意修饰键组合也带 text（如 ctrl+a 带 text:'a'），浏览器靠 modifiers 判定为快捷键，不会插入字符。
+ */
+export async function pressKey(cdp, spec) {
+  const k = parseKey(spec);
+  const base = { modifiers: k.modifiers, key: k.key, code: k.code, windowsVirtualKeyCode: k.keyCode, nativeVirtualKeyCode: k.keyCode };
+  await cdp.send('Input.dispatchKeyEvent', { ...base, type: k.text ? 'keyDown' : 'rawKeyDown', text: k.text, unmodifiedText: k.text }, INPUT_OPTS);
+  await cdp.send('Input.dispatchKeyEvent', { ...base, type: 'keyUp' }, INPUT_OPTS);
+}
+
+/**
+ * 元素是否可见可交互。
+ *
+ * 必须是纯同步求值：不得包含 requestAnimationFrame / await / 定时器。
+ * 实测结论（见 REFERENCE.md「禁用 rAF 探针」）：在页面里跑 rAF 会让 Chrome
+ * 永久丢弃此后所有 Input.dispatchMouseEvent 的 mousePressed/mouseReleased，
+ * 只保留 mouseMoved，导致不合成 click——表现为「点击报成功但毫无效果」。
+ */
+export function visibleRectExpr(sel, frameSel) {
+  return `(() => {
+    const b = ${boxExpr(sel, frameSel)};
+    if (!b) return null;
+    if (b.frameError) return b;
+    return { x: b.x + b.w / 2, y: b.y + b.h / 2, w: b.w, h: b.h, tag: b.tag, inView: b.inView };
+  })()`;
+}
+
+/**
+ * 轮询等待元素可见可交互。
+ * 返回值来自最后一次「同步求值」，因此紧接着派发鼠标事件是安全的。
+ * 等待发生在 Node 侧（setTimeout），不让页面让出渲染帧。
+ */
+export async function waitForElement(cdp, sel, timeoutMs = 15000, intervalMs = 150, frameSel) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    // 单次求值 5s 兜底：页面被对话框/死循环阻塞时，这里会报「无响应」而不是永久挂起。
+    const box = assertFrameAccess(await evaluate(cdp, visibleRectExpr(sel, frameSel), { timeoutMs: 5000 }), frameSel);
+    // inView=false 表示元素可见但不在宿主视口内，此时派发鼠标事件会落空。
+    if (box && box.inView !== false) return box;
+    if (Date.now() >= deadline) {
+      throw new Error(`等待超时(${timeoutMs}ms)：找不到可见可点击的元素 ${sel}${frameSel ? `（--frame ${frameSel}）` : ''}\n` +
+        (String(sel).startsWith('@') ? `提示：@ 引用可能已失效（页面重渲染后旧引用会被清掉）。跑 cdpctl snapshot 拿新引用。\n` : '') +
+        `提示：用 cdpctl snapshot 看页面结构；用 cdpctl text / html 查看当前页面文本，或 cdpctl eval 检查是否还在 loading。`);
+    }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+}
+
+/**
+ * 打开一个新标签页（PUT /json/new?url）。
+ * 只在确实需要新页面时调用；不要把 about:blank 当占位符 ——
+ * 那会在用户的窗口里留下一个空白标签页，每次运行都多一个。
+ */
+export async function openTab(url) {
+  return httpJson(`/json/new?${encodeURIComponent(url)}`, 'PUT');
+}
+
+/**
+ * 启动浏览器（幂等）。已在跑则直接复用，并按需新开页面。
+ *
+ * 关键：不带 url 时**不再**传 '--new-window' / 'about:blank'。
+ * 传了会让 Chrome 在恢复上次会话之外**再**开一个空窗口，用户每次都看到
+ * 多余的 about:blank（实测：launch 后立刻有 2 个 page 目标，其中一个是空的）。
+ * 需要页面时用 url 参数新开一个已有内容的标签页，不留空页。
+ *
+ * 失败处理：刚 stop 过时端口可能还没释放，新 Chrome 会因绑不上调试端口
+ * 而「活着但 CDP 不通」——干等超时还留下孤儿进程（实测遇到过）。
+ * 所以：超时就杀掉本次启的进程、确认端口释放、重试一次，失败给可操作的错误。
+ */
+export async function launch({ url, headless = false } = {}) {
+  const existing = await version();
+  if (existing && url) await openTab(url);
+  if (existing) return { started: false, version: existing };
+
+  const exe = chromePath();
+  const dir = profileDir();
+  mkdirSync(dir, { recursive: true });
+  const logPath = path.join(dir, 'chrome-launch.log');
+  const waitMs = Number(process.env.CDPCTL_LAUNCH_TIMEOUT_MS || 30000);
+
+  const attempt = async () => {
+    const log = openSync(logPath, 'a');
+    const args = [
+      `--user-data-dir=${dir}`,
+      `--remote-debugging-port=${port()}`,
+      '--remote-allow-origins=*',
+      '--no-first-run',
+      '--no-default-browser-check',
+      // 关掉翻译气泡：中英混排页面 + 英文 UI 时 Chrome 会反复弹「要不要翻译」，
+      // 对自动化毫无用处，只会挡住页面。
+      '--disable-features=Translate,TranslateUI',
+      ...(headless ? ['--headless=new'] : []),
+      // 只有显式给了 url 才开窗口；否则让 Chrome 自己恢复会话，避免空标签页。
+      ...(url ? ['--new-window', url] : []),
+    ];
+    const child = spawn(exe, args, { detached: true, stdio: ['ignore', log, log] });
+    child.unref();
+
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+      const v = await version();
+      if (v) return { started: true, pid: child.pid, version: v };
+      if (child.exitCode !== null || child.signalCode !== null) return { failed: 'exited', child };
+      await new Promise(r => setTimeout(r, 400));
+    }
+    return { failed: 'timeout', child };
+  };
+
+  const first = await attempt();
+  if (!first.failed) return first;
+  await killAndWait(first.child);
+
+  // 端口是不是被别的进程占着（而不是我们刚杀掉的那个）
+  let freed = false;
+  for (let i = 0; i < 25; i++) {
+    if (!(await portInUse(port()))) { freed = true; break; }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  if (!freed) {
+    throw new Error(
+      `CDP 端口 ${port()} 被别的进程占着，自动化浏览器起不来。\n` +
+      `  处理: 关掉占用者，或用 CDPCTL_PORT 换一个端口。\n` +
+      `  查看占用: lsof -nP -iTCP:${port()} -sTCP:LISTEN`
+    );
+  }
+  if (first.failed === 'exited') {
+    throw new Error(
+      `Chrome 启动即退出。\n  可执行文件: ${exe}\n  profile: ${dir}\n` +
+      `  日志尾部:\n${logTail(logPath)}\n  完整日志: ${logPath}`
+    );
+  }
+
+  // 端口刚释放，重试一次
+  const second = await attempt();
+  if (!second.failed) return second;
+  await killAndWait(second.child);
+  const tail = logTail(logPath);
+  throw new Error(
+    `启动后 ${Math.round(waitMs / 1000)}s 内 CDP 仍未就绪（已重试 1 次，未就绪的进程已清理）。\n` +
+    `  可执行文件: ${exe}\n  profile: ${dir}\n  端口: ${port()}\n` +
+    (tail ? `  日志尾部:\n${tail}\n` : '') +
+    `  完整日志: ${logPath}`
+  );
+}
+
+/** 端口上有没有人在监听（不判断对方是不是 Chrome）。 */
+function portInUse(p) {
+  return new Promise(resolve => {
+    const s = net.connect({ host: '127.0.0.1', port: p });
+    const done = v => { s.destroy(); resolve(v); };
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+    s.setTimeout(1000, () => done(false));
+  });
+}
+
+/** 优雅结束我们自己启的进程（先 SIGTERM，最多等 5s，再 SIGKILL）。 */
+async function killAndWait(child, ms = 5000) {
+  if (!child || !child.pid) return;
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try { process.kill(child.pid, 'SIGTERM'); } catch { return; }
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    try { process.kill(child.pid, 0); } catch { return; }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  try { process.kill(child.pid, 'SIGKILL'); } catch { /* 已经退了 */ }
+}
+
+/** 日志尾部若干字节，失败时用来解释原因（日志会一直追加，所以只读末尾）。 */
+function logTail(logPath, bytes = 800) {
+  try {
+    const size = statSync(logPath).size;
+    const start = Math.max(0, size - bytes);
+    const fd = openSync(logPath, 'r');
+    const buf = Buffer.alloc(size - start);
+    readSync(fd, buf, 0, buf.length, start);
+    closeSync(fd);
+    return buf.toString('utf8').trim().split('\n').slice(-6).join('\n');
+  } catch { return ''; }
+}
+
+/**
+ * 优雅关闭自动化浏览器（走 CDP Browser.close，跨平台且无需记录 PID）。
+ * 不会影响用户自己开的 Chrome（不同 user-data-dir / 端口）。
+ */
+export async function stop() {
+  const v = await version();
+  if (!v) return { stopped: false, reason: '未在运行' };
+  const b = await connectBrowser();
+  await b.send('Browser.close').catch(() => {});
+  b.close();
+  const deadline = Date.now() + 20000;
+  while (Date.now() < deadline) {
+    if (!(await version())) return { stopped: true };
+    await new Promise(r => setTimeout(r, 400));
+  }
+  return { stopped: false, reason: '20s 内未退出' };
+}
+
+/** 自动化 profile 的 Cookies 数据库路径（兼容新旧布局）。 */
+export function cookiesDbPath() {
+  const base = profileDir();
+  for (const rel of ['Default/Network/Cookies', 'Default/Cookies', 'Cookies']) {
+    const p = path.join(base, rel);
+    if (existsSync(p)) return p;
+  }
+  throw new Error(`找不到 Cookies 数据库。profile=${base}\n提示：先 launch 一次让 Chrome 建立 profile。`);
+}
diff --git a/skills/cdp-page-control/scripts/cdpctl.mjs b/skills/cdp-page-control/scripts/cdpctl.mjs
new file mode 100644
index 0000000..33a2b94
--- /dev/null
+++ b/skills/cdp-page-control/scripts/cdpctl.mjs
@@ -0,0 +1,1240 @@
+#!/usr/bin/env node
+// 原语层：每个子命令 = 一个可独立验证的原子操作，参数化，不含站点业务逻辑。
+// 场景组合见 SKILL.md 的配方表；本文件不写任何「某网站专用」分支。
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, copyFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  assertFrameAccess, boxExpr, clickAt, DIALOG_HINT, dragBetween,
+  chromePath, cookiesDbPath, connectPage, evaluate, httpJson, insertText,
+  launch, listTargets, port, profileDir, pressKey, selectorExpr, snapshotExpr, stop, version,
+  visibleRectExpr, waitForElement, waitLoad,
+} from './cdp-channel.mjs';
+
+// ---------------------------------------------------------------- 参数解析
+
+const KNOWN_FLAGS = new Set([
+  '--match', '--target', '--timeout', '--url', '--file', '--clear', '--append', '--full', '--headless',
+  '--domain', '--seconds', '--grep', '--frame', '--no-await', '--no-gesture', '--raw',
+  '--save', '--bodies', '--bodies-all', '--sanitize',
+  '--from', '--profile', '--yes', '--apply',
+  '--all', '--max', '--steps', '--types', '--reload', '--back', '--forward',
+  '--clip', '--scale', '--size', '--media',
+]);
+
+function splitArgs(argv) {
+  const flags = new Map();
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (KNOWN_FLAGS.has(a)) {
+      if (a.startsWith('--no-')) { flags.set(a.slice(5), false); continue; }
+      if (['--clear', '--append', '--full', '--headless', '--raw', '--bodies', '--bodies-all', '--sanitize', '--all', '--reload', '--back', '--forward', '--yes', '--apply'].includes(a)) { flags.set(a.slice(2), true); continue; }
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} 缺少参数值`);
+      flags.set(a.slice(2), v);
+    } else {
+      pos.push(a);
+    }
+  }
+  return { flags, pos };
+}
+
+const num = (v, d) => (v === undefined ? d : Number(v));
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+/**
+ * --timeout 的单位是**秒**（帮助文本一直这么写），内部一律换算成毫秒。
+ *
+ * 历史上代码把 --timeout 当毫秒用：传 20 会变成 20ms（静默秒退，比挂住更难查）。
+ * 现在加 600 秒上限：万一有人还按毫秒传（如 20000），直接报错并告诉他除以 1000。
+ */
+function timeoutMs(flags) {
+  const raw = flags.get('timeout');
+  if (raw === undefined) return 15000;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds <= 0) throw new Error(`--timeout 需要正的秒数，收到 "${raw}"`);
+  if (seconds > 600) {
+    throw new Error(`--timeout ${seconds} 秒超过上限 600 秒。--timeout 的单位是秒；如果你手里是毫秒，除以 1000 再传。`);
+  }
+  return Math.round(seconds * 1000);
+}
+
+// ---------------------------------------------------------------- 页面操作原语
+
+/**
+ * React/Vue 受控输入：必须走原型上的原生 setter + input/change 事件，
+ * 直接改 el.value 框架不会同步（这是最常见的「填了等于没填」原因）。
+ * 自绘编辑器不适用，那种情况用 insert-text（内部走 cdp-channel 的 insertText）。
+ */
+async function setInputValue(cdp, sel, text, { clear, append }, frameSel) {
+  // 在 iframe 内求值时，根对象与构造器都必须来自该 iframe 的 realm，
+  // 否则 desc.set.call(el, ...) 会因跨 realm 报 Illegal invocation。
+  const core = (root, win) => `(() => {
+    const el = ${selectorExpr(sel, root, win)};
+    if (!el) return { ok: false, reason: '元素不存在' };
+    el.focus();
+    if (el.isContentEditable) {
+      if (${!!clear}) { const r = ${root}.createRange(); r.selectNodeContents(el); const s = ${win}.getSelection(); s.removeAllRanges(); s.addRange(r); }
+      ${root}.execCommand('insertText', false, ${JSON.stringify(text)});
+      el.dispatchEvent(new ${win}.Event('input', { bubbles: true }));
+      return { ok: true, value: el.textContent, kind: 'contenteditable' };
+    }
+    const proto = el.tagName === 'TEXTAREA' ? ${win}.HTMLTextAreaElement.prototype : ${win}.HTMLInputElement.prototype;
+    const desc = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (!desc?.set) return { ok: false, reason: '元素不是可输入控件: ' + el.tagName };
+    const cur = el.value ?? '';
+    const next = ${!!append} ? cur + ${JSON.stringify(text)} : (${!!clear} ? ${JSON.stringify(text)} : ${JSON.stringify(text)});
+    desc.set.call(el, next);
+    el.dispatchEvent(new ${win}.Event('input', { bubbles: true }));
+    el.dispatchEvent(new ${win}.Event('change', { bubbles: true }));
+    return { ok: true, value: el.value, kind: el.tagName.toLowerCase() };
+  })()`;
+  return evaluate(cdp, frameSel ? inFrame(frameSel, core('d', 'w')) : core('document', 'window'));
+}
+
+/** 把「以 iframe 内 document 为根」的表达式包成先定位 iframe 的表达式。 */
+function inFrame(frameSel, expr) {
+  return `(() => {
+    const f = document.querySelector(${JSON.stringify(frameSel)});
+    if (!f) return { frameError: 'not-found' };
+    if (!f.contentDocument) return { frameError: 'cross-origin' };
+    const d = f.contentDocument;
+    const w = f.contentWindow;
+    return (${expr});
+  })()`;
+}
+
+/**
+ * 把另一个 Chrome profile 的 Cookies 数据库复制进自动化 profile（登录态迁移）。
+ * 只做文件级复制：不解密、不解析、不改值。
+ * 同机同 Chrome 直接可用：cookie 密文由同一份 Keychain「Chrome Safe Storage」派生的密钥保护。
+ * apply=false 时只回统计（干跑）；调用方负责在覆盖前关闭受控浏览器。
+ */
+async function importCookies({ fromDir, profile, apply }) {
+  const srcProfile = path.join(fromDir, profile);
+  const srcDb = ['Network/Cookies', 'Cookies'].map(r => path.join(srcProfile, r)).find(p => existsSync(p));
+  if (!srcDb) {
+    throw new Error(`源 profile 里找不到 Cookies 数据库：${srcProfile}\n提示：--from 传 Chrome 的「用户数据目录」（含 Default/ 的上一层），--profile 传 Default 或 "Profile 1"`);
+  }
+  const dstDb = cookiesDbPath();
+  const stamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  const backup = `${dstDb}.bak-${stamp}`;
+  const tmp = path.join(os.tmpdir(), `cdpctl-cookies-${process.pid}.db`);
+  // 源库可能正被 Chrome 持有：先复制到临时文件再读，避开锁与写放大。
+  copyFileSync(srcDb, tmp);
+
+  let sqlite = null;
+  try { sqlite = await import('node:sqlite'); } catch { /* 回退到 sqlite3 CLI */ }
+  const stats = async (dbPath) => {
+    const totalSql = 'SELECT COUNT(*) FROM cookies';
+    const topSql = 'SELECT host_key, COUNT(*) AS n FROM cookies GROUP BY host_key ORDER BY n DESC LIMIT 5';
+    if (sqlite) {
+      const db = new sqlite.DatabaseSync(dbPath, { readOnly: true });
+      const total = Number(db.prepare(totalSql).get()['COUNT(*)']);
+      const top = db.prepare(topSql).all().map(r => ({ host_key: r.host_key, n: Number(r.n) }));
+      db.close();
+      return { total, top };
+    }
+    const { execFileSync } = await import('node:child_process');
+    const total = Number(execFileSync('sqlite3', [dbPath, totalSql], { encoding: 'utf8' }).trim());
+    const raw = execFileSync('sqlite3', ['-json', dbPath, topSql], { encoding: 'utf8' }).trim();
+    return { total, top: raw ? JSON.parse(raw).map(r => ({ host_key: r.host_key, n: Number(r.n) })) : [] };
+  };
+
+  const src = await stats(tmp);
+  if (!apply) { unlinkSync(tmp); return { srcDb, dstDb, backup, src, applied: false }; }
+  copyFileSync(dstDb, backup);
+  copyFileSync(tmp, dstDb);
+  chmodSync(dstDb, 0o600);
+  unlinkSync(tmp);
+  const dst = await stats(dstDb);
+  return { srcDb, dstDb, backup, src, dst, applied: true };
+}
+
+function defaultChromeDataDir() {
+  const home = os.homedir();
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Google', 'Chrome');
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Google', 'Chrome', 'User Data');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'google-chrome');
+}
+
+/** 选原生 <select> 的选项（先 value 后显示文本）。返回 {ok, value, text, reason}。 */
+async function selectOption(cdp, sel, want, frameSel) {
+  const core = (root, win) => `(() => {
+    const el = ${selectorExpr(sel, root, win)};
+    if (!el) return { ok: false, reason: '元素不存在' };
+    if (el.tagName !== 'SELECT') return { ok: false, reason: '不是 <select>，实际是 ' + el.tagName };
+    const opts = [...el.options];
+    const want = ${JSON.stringify(want)};
+    const opt = opts.find(o => o.value === want) || opts.find(o => (o.textContent || '').trim() === want);
+    if (!opt) return { ok: false, reason: '没有匹配项 "' + want + '"，可选: ' + opts.map(o => o.value + '/' + o.textContent.trim()).join(', ') };
+    const set = Object.getOwnPropertyDescriptor(${win}.HTMLSelectElement.prototype, 'value').set;
+    set.call(el, opt.value);
+    el.dispatchEvent(new ${win}.Event('input', { bubbles: true }));
+    el.dispatchEvent(new ${win}.Event('change', { bubbles: true }));
+    return { ok: true, value: el.value, text: (opt.textContent || '').trim() };
+  })()`;
+  return assertFrameAccess(await evaluate(cdp, frameSel ? inFrame(frameSel, core('d', 'w')) : core('document', 'window')), frameSel);
+}
+
+/** fill 用：元素的类型信息；不存在返回 null。 */
+async function elementInfo(cdp, sel, frameSel) {
+  const core = (root, win) => `(() => {
+    const el = ${selectorExpr(sel, root, win)};
+    if (!el) return null;
+    return { tag: el.tagName, type: String(el.type || '').toLowerCase(), checked: !!el.checked, editable: !!el.isContentEditable };
+  })()`;
+  return assertFrameAccess(await evaluate(cdp, frameSel ? inFrame(frameSel, core('d', 'w')) : core('document', 'window'), { timeoutMs: 5000 }), frameSel);
+}
+
+/** fill 的单个字段：按元素类型分派到输入 / 下拉 / 勾选，操作后回读。 */
+async function fillOne(cdp, sel, value, timeout, frameSel) {
+  await waitForElement(cdp, sel, timeout, 150, frameSel);
+  const info = await elementInfo(cdp, sel, frameSel);
+  if (!info) throw new Error('元素不存在');
+  const isBool = typeof value === 'boolean';
+  if (info.tag === 'SELECT') {
+    if (isBool) throw new Error('select 需要字符串值（选项 value 或显示文本）');
+    const r = await selectOption(cdp, sel, String(value), frameSel);
+    if (!r.ok) throw new Error(r.reason);
+    return r.text;
+  }
+  if (info.type === 'checkbox' || info.type === 'radio') {
+    const want = isBool ? value : (String(value) === 'true' ? true : String(value) === 'false' ? false : null);
+    if (want === null) throw new Error('勾选框需要 true / false');
+    if (info.checked === want) return want;
+    if (info.type === 'radio' && !want) throw new Error('单选按钮不能取消选中；改为选中同组另一个值');
+    const box = assertFrameAccess(await evaluate(cdp, visibleRectExpr(sel, frameSel), { timeoutMs: 5000 }), frameSel);
+    if (!box) throw new Error('勾选框不可见');
+    await clickAt(cdp, box);
+    const after = await elementInfo(cdp, sel, frameSel);
+    if (!!after?.checked !== want) throw new Error('点击后状态未变为 ' + want);
+    return want;
+  }
+  if (isBool) throw new Error(`${info.tag} 不接受布尔值`);
+  const r = await setInputValue(cdp, sel, String(value), { clear: false, append: false }, frameSel);
+  if (!r.ok) throw new Error(r.reason);
+  return r.value;
+}
+
+/** 把会话 cookie 改写成持久 cookie：只动元数据，密文不碰。 */
+async function persistCookies(domainFilter) {
+  const db = cookiesDbPath();
+  const filter = String(domainFilter).replace(/[^A-Za-z0-9._-]/g, '');
+  if (!filter) throw new Error('--domain 只允许字母数字点横线下划线');
+  const FUTURE = 13537929600000000n; // 2030-01-01 (WebKit 1601 纪元微秒)
+  const where = `host_key LIKE '%${filter}%' AND has_expires = 0`;
+
+  let sqlite = null;
+  try { sqlite = await import('node:sqlite'); } catch { /* 回退到 sqlite3 CLI */ }
+
+  if (sqlite) {
+    const dbh = new sqlite.DatabaseSync(db);
+    const rows = dbh.prepare(`SELECT host_key, name FROM cookies WHERE ${where}`).all();
+    const n = dbh.prepare(`UPDATE cookies SET expires_utc = ?, has_expires = 1, is_persistent = 1 WHERE ${where}`)
+      .run(FUTURE).changes;
+    dbh.close();
+    return { db, converted: Number(n), rows };
+  }
+  const { execFileSync } = await import('node:child_process');
+  const rowsOut = execFileSync('sqlite3', ['-json', db, `SELECT host_key,name FROM cookies WHERE ${where}`], { encoding: 'utf8' });
+  execFileSync('sqlite3', [db, `UPDATE cookies SET expires_utc=${FUTURE}, has_expires=1, is_persistent=1 WHERE ${where}`]);
+  const rows = rowsOut.trim() ? JSON.parse(rowsOut) : [];
+  return { db, converted: rows.length, rows };
+}
+
+/**
+ * 抓包文件含 cookie/token，属本机私有数据：
+ * 硬校验「不得写进共享仓库」（不靠文档约定），并强制 0600。
+ * 仓库根 = 本文件所在处的上三级（<repo>/skills/cdp-page-control/scripts）。
+ */
+function resolveCapturePath(file) {
+  const abs = path.resolve(file);
+  const repoRoot = path.resolve(import.meta.dirname, '..', '..', '..');
+  const rel = path.relative(repoRoot, abs);
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+    throw new Error(
+      `--save 不能写进共享仓库（抓包含 cookie/token，属本机私有数据）:\n` +
+      `  ${abs}\n` +
+      `请写到本机私有目录或临时目录，例如 ~/.pi/agent/local/<技能>/ 或 $TMPDIR 下。`
+    );
+  }
+  return abs;
+}
+
+function writeCapture(file, data) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(file, 0o600); // 文件已存在时 mode 不生效，所以显式再来一次
+}
+
+const BODY_TYPES = new Set(['XHR', 'Fetch']);
+const MAX_BODY_BYTES = 256 * 1024;
+const SENSITIVE_HEADER = /^(cookie|set-cookie|authorization|proxy-authorization)$/i;
+
+/**
+ * 抓请求并（可选）落盘供逆向使用。
+ * 默认 stdout 仍然是脉敏报告（只看 cookie 名）；--save 写的是完整数据（含凭证值）。
+ */
+async function netLog({ match, target, seconds, grep, save, bodies, bodiesAll, sanitize }) {
+  const savePath = save ? resolveCapturePath(save) : null;
+  const { cdp, target: page } = await connectPage(match, target);
+  const byId = new Map();
+  const order = [];
+  const pendingBodies = [];
+  let bodyBytes = 0;
+
+  await cdp.send('Network.enable');
+  cdp.on(m => {
+    const p = m.params;
+    if (m.method === 'Network.requestWillBeSent') {
+      const rec = {
+        id: p.requestId, type: p.type, method: p.request.method, url: p.request.url,
+        requestHeaders: { ...(p.request.headers || {}) },
+      };
+      if (p.request.postData) rec.postData = p.request.postData;
+      byId.set(p.requestId, rec);
+      order.push(p.requestId);
+      return;
+    }
+    if (m.method === 'Network.requestWillBeSentExtraInfo') {
+      // 注意：requestWillBeSent 常常不带 Cookie，真实 Cookie 在这个事件里。
+      const rec = byId.get(p.requestId);
+      if (rec) rec.requestHeaders = { ...rec.requestHeaders, ...(p.headers || {}) };
+      return;
+    }
+    if (m.method === 'Network.responseReceived') {
+      const rec = byId.get(p.requestId);
+      if (rec) {
+        rec.status = p.response.status;
+        rec.mimeType = p.response.mimeType;
+        rec.responseHeaders = { ...(p.response.headers || {}) };
+        if (p.response.fromDiskCache) rec.fromDiskCache = true;
+      }
+      return;
+    }
+    if (m.method === 'Network.loadingFailed') {
+      const rec = byId.get(p.requestId);
+      if (rec) { rec.failed = true; rec.errorText = p.errorText; }
+      return;
+    }
+    if (m.method === 'Network.loadingFinished') {
+      const rec = byId.get(p.requestId);
+      if (!rec) return;
+      rec.finished = true;
+      const want = bodiesAll || (bodies && BODY_TYPES.has(rec.type));
+      if (!want || bodyBytes > 4 * 1024 * 1024) return;
+      pendingBodies.push((async () => {
+        try {
+          const r = await cdp.send('Network.getResponseBody', { requestId: rec.id });
+          const text = r.base64Encoded ? Buffer.from(r.body, 'base64').toString('utf8') : r.body;
+          bodyBytes += text.length;
+          rec.body = text.length > MAX_BODY_BYTES
+            ? { truncated: true, bytes: text.length, text: text.slice(0, MAX_BODY_BYTES) }
+            : { text };
+        } catch (e) {
+          rec.body = { error: String(e.message || e) };
+        }
+      })());
+    }
+  });
+
+  await sleep(seconds * 1000);
+  await Promise.race([Promise.all(pendingBodies), sleep(3000)]);
+  cdp.close();
+
+  const all = order.map(id => byId.get(id)).filter(Boolean);
+  const shown = all.filter(r => !grep || new RegExp(grep).test(r.url));
+
+  console.log(`目标: ${page.url}\n抓取 ${seconds}s，共 ${all.length} 个请求，显示 ${shown.length} 个\n`);
+  for (const r of shown) {
+    const h = r.requestHeaders || {};
+    const cookieNames = String(h.Cookie || h.cookie || '').split(';').map(s => s.trim().split('=')[0]).filter(Boolean);
+    console.log(`${String(r.status ?? (r.failed ? '失败' : '---')).padStart(3)} ${r.method.padEnd(5)} ${r.url.slice(0, 120)}`);
+    if (cookieNames.length) console.log(`        cookie: ${cookieNames.join(', ')}`);
+    if (h.Authorization) console.log(`        Authorization: ${String(h.Authorization).slice(0, 16)}…`);
+  }
+
+  if (savePath) {
+    const records = all.map(rec => {
+      const copy = { ...rec };
+      if (sanitize) {
+        copy.requestHeaders = redact(copy.requestHeaders);
+        copy.responseHeaders = redact(copy.responseHeaders);
+        delete copy.postData;
+      }
+      return copy;
+    });
+    writeCapture(savePath, {
+      capturedAt: new Date().toISOString(),
+      target: { id: page.id, url: page.url, title: page.title },
+      seconds,
+      sanitized: !!sanitize,
+      bodies: !!(bodies || bodiesAll),
+      requests: records,
+    });
+    const withBodies = records.filter(r => r.body).length;
+    console.log(
+      `\n已写入 ${savePath}（0600）：${records.length} 个请求，${withBodies} 个响应体` +
+      (sanitize ? '（已脉敏）' : '\n⚠ 文件含 cookie/token 原值，属本机私有数据：不要放进共享仓库，也不要原样发给别人')
+    );
+  }
+}
+
+/**
+ * 读控制台消息：Runtime.consoleAPICalled（含历史回放）/ Runtime.exceptionThrown / Log.entryAdded。
+ * 实测（Chrome 153）：Runtime.enable 会回放当前文档保留的 console API 消息与未捕获异常
+ * （Log 域不回放），所以不加 --reload 也能看到「页面早就报过的错」。
+ * --reload 时丢弃旧页面的回放，只保留重载后的消息。
+ */
+async function consoleLog({ match, target, seconds, grep, types, reload }) {
+  const { cdp, target: page } = await connectPage(match, target);
+  const entries = [];
+  const pending = [];
+  let collecting = !reload;
+  const re = grep ? new RegExp(grep) : null;
+  const want = types
+    ? new Set(String(types).split(',').map(s => s.trim().toLowerCase()).map(t => (t === 'warning' ? 'warn' : t)).filter(Boolean))
+    : null;
+  const norm = l => { l = String(l || 'log').toLowerCase(); return l === 'warning' ? 'warn' : l; };
+
+  const argText = async a => {
+    if (a.type === 'string') return a.value;
+    if (a.value !== undefined) return typeof a.value === 'string' ? a.value : JSON.stringify(a.value);
+    if (a.unserializableValue !== undefined) return a.unserializableValue;
+    if (a.objectId) {
+      const r = await cdp.send('Runtime.callFunctionOn', {
+        objectId: a.objectId, returnByValue: true,
+        functionDeclaration: 'function () { try { const s = JSON.stringify(this); return s === undefined ? String(this) : s; } catch (e) { return String(this); } }',
+      }).catch(() => null);
+      if (r && r.result && r.result.value !== undefined) return String(r.result.value).slice(0, 400);
+    }
+    return a.description || a.type;
+  };
+
+  cdp.on(m => {
+    if (!collecting) return;
+    const p = m.params;
+    if (m.method === 'Runtime.consoleAPICalled') {
+      const fr = p.stackTrace && p.stackTrace.callFrames && p.stackTrace.callFrames[0];
+      pending.push((async () => {
+        const parts = [];
+        for (const a of p.args.slice(0, 8)) parts.push(await argText(a));
+        entries.push({ ts: p.timestamp, level: norm(p.type), text: parts.join(' '), url: fr && fr.url, line: fr && fr.lineNumber });
+      })());
+      return;
+    }
+    if (m.method === 'Runtime.exceptionThrown') {
+      const d = p.exceptionDetails;
+      const fr = d.stackTrace && d.stackTrace.callFrames && d.stackTrace.callFrames[0];
+      entries.push({
+        ts: d.timestamp, level: 'error',
+        text: String((d.exception && d.exception.description) || d.text || '').trim(),
+        url: d.url || (fr && fr.url),
+        line: d.lineNumber !== undefined ? d.lineNumber : (fr && fr.lineNumber),
+      });
+      return;
+    }
+    if (m.method === 'Log.entryAdded') {
+      const e = p.entry;
+      entries.push({ ts: e.timestamp * 1000, level: norm(e.level), text: e.text, url: e.url, line: e.lineNumber });
+    }
+  });
+
+  await cdp.send('Runtime.enable', {}, { timeoutMs: 10000, timeoutHint: DIALOG_HINT });
+  await cdp.send('Log.enable', {}, { timeoutMs: 10000, timeoutHint: DIALOG_HINT });
+  if (reload) {
+    entries.length = 0;
+    const loaded = waitLoad(cdp);
+    collecting = true;
+    await cdp.send('Page.reload', {}, { timeoutMs: 30000, timeoutHint: DIALOG_HINT });
+    await loaded;
+  }
+  await sleep(Math.max(0, Math.min(120, seconds)) * 1000);
+  await Promise.race([Promise.all(pending), sleep(2000)]);
+  cdp.close();
+
+  entries.sort((a, b) => a.ts - b.ts);
+  const shown = entries.filter(e => (!want || want.has(e.level)) && (!re || re.test(e.text)));
+  console.log(`目标: ${page.url}`);
+  if (!shown.length) {
+    console.log(entries.length ? `没有匹配的消息（共 ${entries.length} 条被 --types/--grep 过滤）` : '没有控制台消息');
+    return;
+  }
+  for (const e of shown) {
+    const where = e.url ? `  (${e.url}${e.line !== undefined && e.line !== null ? ':' + (e.line + 1) : ''})` : '';
+    console.log(`[${String(e.level).padEnd(5)}] ${String(e.text).replace(/\s*\n\s*/g, ' ⏎ ').slice(0, 500)}${where}`);
+  }
+  console.log(`\n共 ${shown.length} 条${entries.length !== shown.length ? `（总 ${entries.length}，已过滤）` : ''}`);
+}
+
+function redact(headers) {
+  if (!headers) return headers;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k] = SENSITIVE_HEADER.test(k) ? '<redacted>' : v;
+  return out;
+}
+
+// ---------------------------------------------------------------- 用法
+
+const USAGE = `cdpctl — 用 Chrome DevTools Protocol 操作任意网页（原语层）
+
+用法: cdpctl <命令> [参数] [--match <URL或标题片段> | --target <targetId>]
+
+会话与生命周期:
+  launch [--url U] [--headless]
+                        启动/复用自动化浏览器（幂等），profile 持久保留登录态
+  stop                        优雅关闭自动化浏览器（不影响你自己的 Chrome）
+  status                      运行状态 / profile 路径 / 当前页面
+
+标签页:
+  targets                     列出全部目标（页面/Service Worker/扩展）
+  open <url>                  新开标签页
+  close <targetId>            关闭标签页
+
+导航与读取:
+  nav <url>                   导航并等待 load
+  nav --back|--forward|--reload
+                              历史后退 / 前进 / 刷新当前页
+  snapshot [--all] [--max N]  页面结构快照：可见交互/结构元素，带 @N 引用（--max 0=不限）
+  eval [--file F | <js> | -]  在页面执行 JS，结果按 JSON 输出（- 表示从 stdin 读）
+  console [--reload] [--seconds 秒] [--types 级别] [--grep 正则]
+                              读控制台消息（含历史回放与未捕获异常）；--reload 收加载期
+  text [选择器]               取可见文本（默认整个 body）
+  html [选择器]               取 outerHTML（默认整个 body）
+  shot <out.png> [选择器] [--full] [--clip x,y,w,h [--scale N]]
+                              截图；带选择器时只截该元素，--full 截整页，
+                              --clip 截指定矩形（页面坐标，比 --full 稳：--full 走
+                              captureBeyondViewport，宽画布的多栏页会卡死）
+  pdf <out.pdf> --size WxH [--media screen]
+                              整页导出 PDF（打印管线，一次调用出全部内容；页面坐标系：
+                              W/H 用 CSS px，内部换算成纸面英寸）。要图片就再用
+                              qlmanage -t -s <2*max(W,H)> 矢量重栅格成 PNG（比
+                              shot --full 稳：后者用 captureBeyondViewport，大画布会卡死）
+  find <选择器>               定位元素：几何 / 可见性 / 标签名（找不到返回 null）
+
+交互:
+  wait  <选择器> [--timeout 秒]     轮询等待元素可见可点击（稳定性原语；默认 15 秒）
+  hover <选择器> [--timeout 秒]     只把鼠标移到元素中心（悬停），不点击
+  select <选择器> <值> [--timeout 秒]  选择原生 <select> 的选项（按 value 或显示文本）
+  click <选择器> [--timeout 秒]     真实鼠标点击（isTrusted=true）
+  type  <选择器> <文本> [--clear]   受控组件安全输入（原生 setter + input/change 事件）
+  insert-text <文本> [--file F]    把文本插入当前焦点元素（CDP Input.insertText）
+                                   自绘编辑器（Monaco/ProseMirror/CodeMirror）唯一可靠输入方式
+                                   用法：先 click 聚焦目标编辑区，再 insert-text
+  press <按键...>                  真实按键: enter tab escape esc backspace arrowup/down/left/right
+                                   home end pageup pagedown 单字符，或 ctrl+a / cmd+enter
+  fill --file fields.json          按 { "选择器": 值 } 批量填表（输入框/下拉/勾选框）；--file - 读 stdin
+  drag <来源选择器> <目标选择器> [--steps N]
+                                   真实鼠标拖拽（分步移动，兼容 JS 与原生 HTML5 拖放）
+  upload <选择器> <文件路径>        设置 file input 的文件（@引用 也可用）
+
+会话凭证:
+  cookies                     列出 cookie 元数据（值只报长度，不打印）
+  persist-cookies --domain D  把 D 域下的会话 cookie 改写成持久 cookie（跨重启保登录）
+                              注意：会先关闭浏览器再改写，然后需自行 launch
+  import-cookies [--from 目录] [--profile 名] [--yes]
+                              把日常 Chrome 的登录态（Cookies 库）复制进自动化 profile
+                              默认只预览；--yes 才执行（会先关闭受控浏览器并备份原库）
+
+诊断:
+  net [--seconds 秒] [--grep 正则] [--save 文件] [--bodies] [--sanitize]
+                              抓请求并标出每个请求携带的 cookie 名（排查站点如何鉴权）
+                              --save 落盘完整抓包（含凭证 → 只允许写共享仓库外，权限 0600）
+
+目标定位（涉及页面元素的命令通用）:
+  --match <片段>   按 URL 或标题片段选页面；只有一个页面时自动选中。
+                   重定向后片段可能失配，命中多个时报错。
+  --target <id>    按 cdpctl status / targets 给出的 targetId 精确定位。
+                   编排或复用多个标签页时用它（不受重定向与同名页面影响）。
+
+选择器语法（所有 <选择器> 通用）:
+  css 写法        #id .class [data-x="y"]
+  text=文本       文本内容完全相等（取最内层；多个候选时优先可见的那个）
+  xpath=表达式    XPath
+  @N              snapshot 输出的引用编号（页面重渲染后会失效，重跑 snapshot）
+
+iframe（同源）内操作:
+  涉及元素定位的命令都支持 --frame <iframe 的 CSS 选择器>：
+  先把 iframe 滚进视口，再在它的 contentDocument 里解析选择器，
+  点击/输入的坐标自动换算回宿主页面。
+  例: cdpctl click "text=提交" --frame "#detail-frame"
+  跨域 iframe 进不去（同源策略），只能操作它的宿主元素。
+
+环境变量:
+  CDPCTL_PORT     调试端口，默认 9222
+  CDPCTL_PROFILE  自动化 profile 目录，默认 macOS ~/Library/Application Support/Chrome-CDP-Automation
+  CDPCTL_CHROME   Chrome 可执行文件路径（自动探测失败时用）
+  CDPCTL_HEADLESS 设为 1 则默认以 headless 启动
+  CDPCTL_LAUNCH_TIMEOUT_MS  启动后等 CDP 就绪的上限，默认 30000（超时会清理并重试一次）
+  CDPCTL_DIALOG      对话框策略: accept（默认）/ dismiss / ignore
+  CDPCTL_DIALOG_TEXT prompt 对话框自动应答的文本（默认用页面给的 defaultPrompt）
+
+help [命令]   不带参数=本总览；带参数=该命令详情`;
+
+const CMD_HELP = {
+  help: `help [命令]
+不带参数：打印总览与全部命令清单。带命令名：打印该命令的详细说明与注意事项。`,
+  launch: `launch [--url U] [--headless]
+确保自动化浏览器在运行（幂等）。已运行则直接复用；给了 --url 就新开一个页面。
+用独立 profile，绝不碰你日常用的 Chrome。profile 是持久的，登录态会留下来。
+浏览器必须带非默认 profile 才能开调试端口（Chrome 136+ 起的安全限制）。
+--headless 用新 headless 模式（不弹窗，适合脚本/CI）；登录类流程建议用可见模式，
+因为部分站点对 headless 有反自动化策略。`,
+  stop: `stop
+走 CDP Browser.close 优雅关闭（跨平台，不依赖记录 PID）。只影响自动化实例。`,
+  status: `status
+打印：CDP 版本 / 端口 / profile 路径 / 已打开页面列表。排查任何问题先跑它。`,
+  nav: `nav <url> | nav --back | nav --forward | nav --reload
+导航到 url 并等待 load 事件。每个页面目标串行导航，不新开标签。
+--back / --forward 走浏览历史；--reload 刷新当前页（比 eval location.reload() 可靠）。
+SPA 导航后内容可能还在渲染，接着用 wait。`,
+  snapshot: `snapshot [--all] [--max N]
+页面结构快照：把可见的交互元素（按钮/输入框/链接/下拉/勾选框/iframe...）与
+结构节点（标题/表单/导航/表格）一次列出来，每个带 @N 引用：
+  @1 button "登录"
+  @2 input[email] "邮箱" [value="a@b.c"]
+  @3 select [selected="Pro"]
+  @4 checkbox "同意条款" [checked]
+之后所有命令都可以直接引用：cdpctl click "@1"、cdpctl type "@2" "x"。
+比逐个 find/text 猜选择器省很多轮次。
+--all 额外纳入带可见文本的叶子节点（看正文用）；--max 限制输出条数（默认 250，0=不限）。
+注意：页面重渲染（SPA 路由、列表刷新）会清掉旧引用；此时重跑 snapshot 即可。
+引用也可能落在 open shadow DOM 里，解析时自动穿透。`,
+  eval: `eval [--file F | <js> | -]
+在页面上下文执行 JS 并返回结果，结果会被 cdpctl 自动 JSON 序列化（缩进 2 格）。
+  cdpctl eval "document.title"
+  cdpctl eval 'document.querySelectorAll("a").length'
+  cdpctl eval --file /tmp/probe.js
+  echo 'document.title' | cdpctl eval -
+注意：不要自己在页面里再 JSON.stringify 一次，会变成双重编码的字符串；
+直接返回 JavaScript 值即可。字符串结果在输出里带引号，取用时 JSON.parse 一下。
+复杂脚本建议写成文件，避免 shell 引号地狱。异常会打印页面内堆栈。`,
+  wait: `wait <选择器> [--timeout 秒]
+轮询直到元素出现且可见可点击（默认 15 秒）。超时报错并提示如何排查。
+--timeout 的单位是**秒**（--timeout 30 = 30 秒）；写 30000 这种毫秒值会被拒绝（上限 600 秒）。
+所有 click/type/hover 内部都会先 wait，所以通常不用显式调用。
+--frame <iframe的CSS选择器>：在同源 iframe 内解析元素。`,
+  hover: `hover <选择器> [--timeout 秒]
+只发一个真实鼠标移动事件到元素中心，不按下。用于展开 hover 触发的菜单/提示。
+先用 hover 展开，再 click 出现的子项。
+--frame <iframe的CSS选择器>：在同源 iframe 内解析元素。`,
+  select: `select <选择器> <值> [--timeout 秒]
+选择原生 <select> 的选项。先按 value 精确匹配，再按显示文本匹配。
+走原型上的原生 value setter + input/change 事件，受控组件（React/Vue）才能同步。
+只赋值不派发 change 事件，框架状态不会更新——和输入框是同一个坑。
+匹配不到时会列出全部可选 value/文本。
+非原生下拉（div 伪装的选择器）请用 hover + click。
+--frame <iframe的CSS选择器>：在同源 iframe 内解析元素。`,
+  click: `click <选择器> [--timeout 秒]
+先等元素可见，滚动到视口中心，然后发真实鼠标事件（mouseMoved/Pressed/Released）。
+真实事件 isTrusted=true，比 el.click() 更接近人操作。
+--frame <iframe的CSS选择器>：在同源 iframe 内解析元素（坐标自动换算回宿主页面）。`,
+  type: `type <选择器> <文本> [--clear]
+受控组件安全输入：走原型上的原生 value setter，再派发 input 与 change 事件。
+直接写 el.value 对 React/Vue 无效（框架状态不会更新），这是最常见的坑。
+contenteditable 元素走 execCommand insertText。
+--clear 先清空再输入；不加则直接写入（覆盖原值）。
+--frame <iframe的CSS选择器>：在同源 iframe 内输入（跨 realm 时自动用该 iframe 的原生 setter）。
+注意：自绘富文本编辑器（Monaco / ProseMirror / CodeMirror / 各类 chat 输入框）不是
+input/textarea，这条命令改不动它们的内部状态——那种情况用 insert-text。`,
+  fill: `fill --file fields.json | fill '<JSON对象>'
+按 JSON 对象批量填表，键是选择器（CSS / @引用），值决定动作：
+  {"#user": "alice", "#plan": "Pro", "#agree": true, "#note": "备注"}
+  - 字符串 -> 输入框/文本域/contenteditable 写入；<select> 按 value 或显示文本选中
+  - 布尔值 -> checkbox / radio 勾选或取消（radio 不能置 false，改选同组另一个值）
+每个字段先等可见再操作，操作后回读校验；逐条报告成功/失败，有失败则退出码 1。
+--file - 从 stdin 读。适合一个表单一次填完，比多次 type/select/click 少很多往返。
+--frame <iframe的CSS选择器>：字段在同源 iframe 内解析。`,
+  'insert-text': `insert-text <文本> [--file F]
+把文本插入**当前焦点元素**（CDP Input.insertText），走浏览器原生编辑管线：
+会发出真实的 beforeinput/input 事件，因此 Monaco、ProseMirror、CodeMirror 这类
+自绘编辑器（以及 React 的 contenteditable 聊天输入框）都能正确接收。
+用法：先聚焦——通常是一次 click 目标编辑区（click 路径见 click 命令）——再 insert-text。
+两个命令是两次独立连接、无状态，焦点是页面状态所以能接上；这是刻意设计，便于自由组合。
+--file F 从文件读文本（长文本、含引号/换行时用，避开 shell 引号地狱）；
+位置参数写 - 则从 stdin 读。
+执行后会回报插入前后焦点元素是谁、插入了多少字符、元素内文本长度是否真的涨了——
+别假设成功，看这个回执。`,
+  press: `press <按键...>
+真实键盘事件，可连发：press enter   press tab tab   press ctrl+a
+按键名: enter tab escape esc backspace delete space arrowup arrowdown arrowleft arrowright
+        home end pageup pagedown，或单个字符。修饰键: ctrl+ cmd+ shift+ alt+`,
+  drag: `drag <来源选择器> <目标选择器> [--steps N]
+真实鼠标拖拽：在来源中心按下，分 N 步（默认 10）移动到目标中心，再松开。
+分步移动是必须的：JS 拖拽库靠 mousemove 更新位置，浏览器原生 HTML5 拖放
+也要有过程事件才会触发 dragstart/dragover/drop。
+要求两端同时可见且在视口内（拖拽中途无法滚动），否则报错提示先调整页面。
+暂不支持 --frame（两端必须落在同一视口坐标系里）。`,
+  text: `text [选择器]
+取元素可见文本（innerText，保留换行）。默认取 body。找不到元素返回空串。
+--frame <iframe的CSS选择器>：读取同源 iframe 内的文本。`,
+  html: `html [选择器]
+取 outerHTML。默认取 documentElement。大页面建议先定位小容器再取，避免刷屏。
+--frame <iframe的CSS选择器>：取同源 iframe 内的 HTML。`,
+  pdf: `pdf <out.pdf> --size WxH [--media screen|print]
+把当前页面整页导出成 PDF（走打印管线：Chrome 自己分页/光栅化，一次调用拿到全部内容，
+不受视口限制，也不会碰到 captureBeyondViewport 的卡死）。
+--size WxH 是页面坐标（CSS px），内部换算成纸面英寸（/96），四边 margin 0，背景照印。
+--media screen（默认 print）：页面上有 @media print 样式、或想保持屏幕上那套版式时用 screen。
+返回文件字节数。要 PNG：qlmanage -t -s <希望的最大边长> -o <目录> <out.pdf>（矢量重栅格，2× 也锐利）。`,
+  shot: `shot <out.png> [选择器] [--full] [--clip x,y,w,h [--scale N]]
+截图到文件。给了选择器就只截该元素（支持 @引用 与 --frame）；--full 截整页。
+--clip 截页面坐标里的矩形（x,y,宽,高，CSS px）：只 rasters 视口内已绘制的区域，
+比 --full 快且稳 —— 超宽多栏页用 --full 会卡死（captureBeyondViewport 在多栏页上
+会进死循环）；要整页就自己按视口分块 --clip 再拼。--scale 缩放（默认 1）。
+返回文件字节数。`,
+  find: `find <选择器>
+返回元素几何与可见性: {x,y,w,h,tag}，不可见或不存在返回 null。定位问题时先跑它。
+--frame <iframe的CSS选择器>：几何坐标已换算回宿主页面。`,
+  upload: `upload <选择器> <文件路径>
+给 <input type=file> 设置文件（支持 CSS / @引用）。
+文件路径会转成绝对路径。这是页面 JS 做不到的操作（安全限制）。
+--frame <iframe的CSS选择器>：把文件设给同源 iframe 内的 <input type=file>。`,
+  cookies: `cookies
+列出当前浏览器所有 cookie 的域/名/过期/长度/HttpOnly/Secure。
+值只报长度不打印（避免凭证进日志）。HttpOnly cookie 只有 CDP 能看见，页面 JS 看不到。`,
+  'persist-cookies': `persist-cookies --domain D
+把 D 匹配的域名下、当前还是「会话 cookie」（has_expires=0）的 cookie 改写成持久 cookie
+（expires_utc 设到 2030-01-01, has_expires=1, is_persistent=1）。密文一字不改。
+为什么需要：浏览器正常退出时 Chrome 会删掉会话 cookie，重启后登录态就丢了。
+执行流程：先优雅关闭浏览器 -> 改写 SQLite -> 由你决定何时 launch。
+只改元数据，不解密、不改值、不外传。`,
+  'import-cookies': `import-cookies [--from <Chrome 用户数据目录>] [--profile <Default|Profile N>] [--yes]
+把日常 Chrome 某个 profile 的 Cookies 数据库整体复制进自动化 profile，用于「不想重新登录」。
+为什么可行：Chrome 136+ 不允许给默认 profile 开调试端口，但同机同 Chrome 的 cookie 密文
+由同一份 Keychain「Chrome Safe Storage」派生的密钥保护，文件级复制即可直接解密使用。
+默认只预览（打印源库/目标库/备份路径与 cookie 统计，不改文件）；--yes 才执行。
+执行流程：先关闭受控浏览器 -> 备份目标库 -> 覆盖 -> 回读计数 -> 由你决定何时 launch。
+边界：会复制**全部**站点的登录态（不是只挑某几个域）；目标 profile 里原有的 cookie 被替换，
+但不是删除——备份文件保留在 Cookies.bak-<时间戳>。不想长期保留就别把它提交/同步到别处。`,
+  net: `net [--seconds 秒] [--grep 正则] [--save 文件.json] [--bodies] [--bodies-all] [--sanitize]
+监听网络请求，打印 状态码/方法/URL，并标出该请求实际携带了哪些 cookie 名（不打印值）。
+用于回答「这个站点到底靠什么维持登录」。注意 Chrome 的 requestWillBeSent 事件
+常常不带 Cookie 头，真实 Cookie 在 requestWillBeSentExtraInfo 里，本命令已处理。
+
+--save <文件>   把完整抓包写成 JSON：请求头（含 Cookie 值）、响应头、postData、状态码、mimeType。
+                 **文件含凭证，属本机私有数据**：写共享仓库内会被硬拒绝，落盘权限 0600。
+                 人读报告仍是脉敏的；--grep 只影响报告，文件始终是全部请求。
+--bodies        额外抓 XHR/Fetch 的响应体（单个上限 256KB，总计 4MB）
+--bodies-all    连 Document/脚本/图片等所有类型的响应体都抓（文件会很大）
+--sanitize      落盘时把 Cookie/Authorization/Set-Cookie 的值换成 <redacted>，并丢弃 postData
+                （只在需要把文件拿给别人看结构时用；逆向复现需要原值，所以默认不脉敏）
+
+要抓「点某个按钮之后才发的请求」，得让 net 在后台跑、同时触发动作（net 本身是阻塞的）：
+  node scripts/cdpctl.mjs net --seconds 15 --save /tmp/net.json --target <id> &
+  sleep 1 && node scripts/cdpctl.mjs click "text=查询" --target <id>
+抓到的接口能不能脱离浏览器复现，必须实测（见 skills/web-api-reverse）。`,
+  console: `console [--reload] [--seconds 秒] [--types 级别] [--grep 正则]
+读控制台消息：console.* 输出、未捕获异常、浏览器日志（网络错误/安全告警）。
+默认会回放当前页面已经产生过的消息（Runtime.enable 的历史回放），所以「刚才
+点了没反应」不用重现也能看到报错。--seconds 是收集窗口（默认 3 秒）。
+--reload 先刷新页面再收集，适合抓加载期一次性报错；旧页面的回放会被丢弃。
+--types error,warn 只看指定级别（log/info/warn/error/debug/assert/verbose...）；
+--grep 正则过滤消息正文。
+提示：报错行里的 URL 与行号来自页面自身；sourcemap 不会自动还原。`,
+  targets: `targets
+列出所有调试目标：page / service_worker / browser_ui 等，含 id、标题、URL。
+--match 用的就是这些 page 目标的 URL 或标题；--target 用的是它们的 id。`,
+  open: `open <url>
+新开一个标签页并返回它的 targetId。已有页面要跳转请用 nav。
+拿到 id 后用 --target 精确定位这个页面，用完 close <targetId>。`,
+  close: `close <targetId>
+按 targetId 关闭标签页。targetId 从 cdpctl targets 拿。`,
+};
+
+// ---------------------------------------------------------------- 主流程
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv.shift();
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    const want = argv[0];
+    if (want) {
+      const body = CMD_HELP[want];
+      if (!body) {
+        console.error(`未知命令: ${want}\n可用: ${Object.keys(CMD_HELP).join(', ')}`);
+        process.exit(1);
+      }
+      console.log(body);
+    } else {
+      console.log(USAGE);
+      // 由 CMD_HELP 生成，不手写，避免与注册表漂移。
+      console.log('\n可用命令: ' + Object.keys(CMD_HELP).join(', '));
+    }
+    return;
+  }
+  if (!(cmd in CMD_HELP)) {
+    console.error(`未知命令: ${cmd}\n可用: ${Object.keys(CMD_HELP).join(', ')}\n\n运行 cdpctl help 看总览`);
+    process.exit(1);
+  }
+
+  const { flags, pos } = splitArgs(argv);
+  const match = flags.get('match');
+  const target = flags.get('target');
+  const frame = flags.get('frame');
+  const timeout = timeoutMs(flags);
+
+  switch (cmd) {
+    case 'launch': {
+      const headless = !!flags.get('headless') || process.env.CDPCTL_HEADLESS === '1';
+      const r = await launch({ url: flags.get('url'), headless });
+      console.log(r.started
+        ? `已启动 (pid ${r.pid}) ${r.version.Browser}${headless ? ' [headless]' : ''}\n  profile: ${profileDir()}\n  CDP: 127.0.0.1:${port()}`
+        : `已在运行，复用现有实例 ${r.version.Browser}`);
+      return;
+    }
+
+    case 'stop': {
+      const r = await stop();
+      console.log(r.stopped ? '已关闭自动化浏览器' : `未关闭：${r.reason}`);
+      return;
+    }
+
+    case 'status': {
+      const v = await version();
+      console.log(`CDP 端口 : ${port()} ${v ? '监听中 ✓' : '无响应 ✗'}`);
+      if (v) console.log(`浏览器   : ${v.Browser}`);
+      console.log(`profile  : ${profileDir()}`);
+      try { console.log(`Chrome   : ${chromePath()}`); } catch (e) { console.log(`Chrome   : ${e.message.split('\n')[0]}`); }
+      if (!v) { console.log('\n未运行。启动: cdpctl launch --url <URL>'); return; }
+      const pages = (await listTargets()).filter(t => t.type === 'page');
+      console.log(`\n页面 ${pages.length} 个:`);
+      for (const t of pages) console.log(`  ${t.title || '(无标题)'}\n    ${t.url}\n    id=${t.id}`);
+      return;
+    }
+
+    case 'targets': {
+      const ts = await listTargets();
+      for (const t of ts) console.log(`${String(t.type).padEnd(15)} ${t.id}\n                ${t.title}\n                ${t.url}`);
+      console.log(`\n共 ${ts.length} 个目标`);
+      return;
+    }
+
+    case 'open': {
+      const t = await httpJson(`/json/new?${encodeURIComponent(pos[0])}`, 'PUT');
+      console.log(t.id, t.url);
+      return;
+    }
+
+    case 'close': {
+      await httpJson(`/json/close/${pos[0]}`);
+      console.log('已关闭', pos[0]);
+      return;
+    }
+
+    case 'nav': {
+      const hist = ['back', 'forward', 'reload'].filter(f => flags.get(f));
+      if (hist.length > 1) throw new Error('nav 一次只能用 --back / --forward / --reload 之一');
+      if (hist.length && pos[0]) throw new Error('nav 给了 URL 就不能再带 --back / --forward / --reload');
+      if (!hist.length && !pos[0]) throw new Error('用法: cdpctl nav <url> | cdpctl nav --back | cdpctl nav --forward | cdpctl nav --reload');
+      const { cdp } = await connectPage(match, target);
+      if (hist[0] === 'reload') {
+        const p = waitLoad(cdp);
+        await cdp.send('Page.reload', {}, { timeoutMs: 15000, timeoutHint: DIALOG_HINT });
+        await p;
+      } else if (hist[0]) {
+        const h = await cdp.send('Page.getNavigationHistory', {}, { timeoutMs: 10000 });
+        const i = h.currentIndex + (hist[0] === 'back' ? -1 : 1);
+        if (i < 0 || i >= h.entries.length) {
+          throw new Error(`没有${hist[0] === 'back' ? '上一页' : '下一页'}（当前位于历史第 ${h.currentIndex + 1}/${h.entries.length} 条）`);
+        }
+        const p = waitLoad(cdp);
+        await cdp.send('Page.navigateToHistoryEntry', { entryId: h.entries[i].id }, { timeoutMs: 15000, timeoutHint: DIALOG_HINT });
+        await p;
+      } else {
+        const p = waitLoad(cdp);
+        await cdp.send('Page.navigate', { url: pos[0] }, { timeoutMs: 30000, timeoutHint: DIALOG_HINT });
+        await p;
+      }
+      console.log('url   =', await evaluate(cdp, 'location.href'));
+      console.log('title =', await evaluate(cdp, 'document.title'));
+      cdp.close();
+      return;
+    }
+
+    case 'eval': {
+      let src = flags.get('file') ? readFileSync(flags.get('file'), 'utf8') : pos[0];
+      if (!src || src === '-') {
+        if (process.stdin.isTTY) throw new Error('eval 需要表达式、--file，或用 - 从 stdin 读');
+        src = await new Response(process.stdin).text();
+      }
+      const { cdp } = await connectPage(match, target);
+      const v = await evaluate(cdp, src, {
+        awaitPromise: flags.get('await') !== false,
+        userGesture: flags.get('gesture') !== false,
+      });
+      console.log(JSON.stringify(v, null, 2));
+      cdp.close();
+      return;
+    }
+
+    case 'wait': {
+      const { cdp } = await connectPage(match, target);
+      const box = await waitForElement(cdp, pos[0], timeout, 150, frame);
+      console.log(JSON.stringify(box));
+      cdp.close();
+      return;
+    }
+
+    case 'find': {
+      const { cdp } = await connectPage(match, target);
+      const box = assertFrameAccess(await evaluate(cdp, boxExpr(pos[0], frame)), frame);
+      console.log(JSON.stringify(box
+        ? { x: Math.round(box.x), y: Math.round(box.y), w: Math.round(box.w), h: Math.round(box.h), tag: box.tag, visible: true }
+        : null, null, 2));
+      cdp.close();
+      return;
+    }
+
+    case 'snapshot': {
+      const maxRaw = flags.get('max');
+      const max = maxRaw === undefined ? 250 : Number(maxRaw);
+      if (!Number.isInteger(max) || max < 0) throw new Error(`--max 需要 0 或正整数（0 = 不限量），收到 "${maxRaw}"`);
+      const { cdp } = await connectPage(match, target);
+      const r = await evaluate(cdp, snapshotExpr({ all: !!flags.get('all'), max }), { timeoutMs: 10000 });
+      console.log(`目标: ${r.url}`);
+      console.log(`标题: ${r.title}`);
+      console.log(`元素: ${r.kept}${r.truncated ? `（超出 --max，截断 ${r.truncated} 个）` : ''}`);
+      if (r.lines.length) {
+        console.log('');
+        for (const l of r.lines) console.log(l);
+      } else {
+        console.log('（没有可见的交互/结构元素；试 --all，或用 text/html 看内容）');
+      }
+      console.log('\n引用用法: cdpctl click "@3"；页面重渲染后引用会失效，重跑 snapshot。');
+      cdp.close();
+      return;
+    }
+
+    case 'select': {
+      const [sel, ...rest] = pos;
+      if (!sel || rest.length === 0) throw new Error('用法: cdpctl select <选择器> <值或选项文本>');
+      const want = rest.join(' ');
+      const { cdp } = await connectPage(match, target);
+      await waitForElement(cdp, sel, timeout, 150, frame);
+      const r = await selectOption(cdp, sel, want, frame);
+      if (!r.ok) throw new Error('选择失败: ' + r.reason);
+      console.log(`已选择 ${sel} = ${r.value} (${r.text})`);
+      cdp.close();
+      return;
+    }
+
+    case 'hover': {
+      const { cdp } = await connectPage(match, target);
+      // waitForElement 的返回值就来自最后一次同步求值，紧接着派发是安全的。
+      const box = await waitForElement(cdp, pos[0], timeout, 150, frame);
+      await cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: box.x, y: box.y, buttons: 0 });
+      console.log(`已悬停 ${pos[0]} @ (${Math.round(box.x)},${Math.round(box.y)})`);
+      cdp.close();
+      return;
+    }
+
+    case 'click': {
+      const { cdp } = await connectPage(match, target);
+      const box = await waitForElement(cdp, pos[0], timeout, 150, frame);
+      await clickAt(cdp, box);
+      console.log(`已点击 ${pos[0]} @ (${Math.round(box.x)},${Math.round(box.y)})`);
+      cdp.close();
+      return;
+    }
+
+    case 'type': {
+      const [sel, ...rest] = pos;
+      if (!sel || rest.length === 0) throw new Error('用法: cdpctl type <选择器> <文本> [--clear]');
+      const text = rest.join(' ');
+      const { cdp } = await connectPage(match, target);
+      await waitForElement(cdp, sel, timeout, 150, frame);
+      const r = await setInputValue(cdp, sel, text, { clear: !!flags.get('clear'), append: !!flags.get('append') }, frame);
+      if (!r.ok) throw new Error(`输入失败: ${r.reason}`);
+      console.log(`已输入到 ${sel} (${r.kind})，当前值长度 ${String(r.value ?? '').length}`);
+      cdp.close();
+      return;
+    }
+
+    case 'fill': {
+      let raw;
+      const fileFlag = flags.get('file');
+      if (fileFlag && fileFlag !== '-') raw = readFileSync(fileFlag, 'utf8');
+      else if (fileFlag === '-') raw = await new Response(process.stdin).text();
+      else raw = pos.join(' ');
+      if (!raw || !raw.trim()) {
+        throw new Error('用法: cdpctl fill --file fields.json [--frame ...]（JSON 对象 { "选择器": 值 }；--file - 读 stdin）');
+      }
+      let spec;
+      try { spec = JSON.parse(raw); } catch (e) {
+        throw new Error(`fill 需要 JSON 对象 { "选择器": 值 }，解析失败: ${e.message}`);
+      }
+      if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+        throw new Error('fill 的 JSON 必须是对象: { "#user": "alice", "#agree": true }');
+      }
+      const entries = Object.entries(spec);
+      if (!entries.length) throw new Error('fill 的 JSON 是空的');
+      const { cdp } = await connectPage(match, target);
+      const oks = [], fails = [];
+      for (const [sel, value] of entries) {
+        try { oks.push(`ok   ${sel} = ` + JSON.stringify(await fillOne(cdp, sel, value, timeout, frame))); }
+        catch (e) { fails.push(`FAIL ${sel}: ${e.message}`); }
+      }
+      cdp.close();
+      console.log(`fill: ${oks.length}/${entries.length} 个字段成功`);
+      for (const l of oks) console.log('  ' + l);
+      for (const l of fails) console.log('  ' + l);
+      if (fails.length) throw new Error(`${fails.length} 个字段失败（逐条见上）`);
+      return;
+    }
+
+    case 'insert-text': {
+      let text = flags.get('file') ? readFileSync(flags.get('file'), 'utf8') : pos.join(' ');
+      if (!text || text === '-') {
+        if (process.stdin.isTTY) throw new Error('用法: cdpctl insert-text <文本> [--file F]（或用 - 从 stdin 读）');
+        text = await new Response(process.stdin).text();
+      }
+      if (!text) throw new Error('要插入的文本为空');
+      const { cdp } = await connectPage(match, target);
+      // insertText 只作用于「页面当前焦点元素」，没有焦点就静默丢字——所以先查再插，插完再验。
+      const focusExpr = `(() => { const a = document.activeElement;
+        if (!a || a === document.body) return null;
+        return { tag: a.tagName.toLowerCase(), cls: String(a.className || '').slice(0, 80), editable: !!a.isContentEditable, len: String(a.innerText ?? a.value ?? '').length }; })()`;
+      const before = await evaluate(cdp, focusExpr);
+      if (!before) throw new Error('页面里没有焦点元素。先用 cdpctl click <选择器> 点进目标输入区，再 insert-text。');
+      await insertText(cdp, text);
+      const after = await evaluate(cdp, focusExpr);
+      const grew = after && before ? after.len - before.len : null;
+      console.log(`已插入 ${text.length} 字符到焦点元素 ${before.tag}${before.cls ? '.' + before.cls.split(' ')[0] : ''}`);
+      console.log(`焦点元素文本长度: ${before.len} -> ${after?.len ?? '?'}${grew === 0 ? '  ⚠ 没变，可能没插进去' : ''}`);
+      cdp.close();
+      return;
+    }
+
+    case 'press': {
+      if (!pos.length) throw new Error('用法: cdpctl press <按键...>');
+      const { cdp } = await connectPage(match, target);
+      for (const spec of pos) await pressKey(cdp, spec);
+      console.log('已发送按键:', pos.join(' '));
+      cdp.close();
+      return;
+    }
+
+    case 'drag': {
+      const [fromSel, toSel] = pos;
+      if (!fromSel || !toSel) throw new Error('用法: cdpctl drag <来源选择器> <目标选择器> [--steps N]');
+      if (frame) throw new Error('drag 暂不支持 --frame：拖拽两端必须落在同一视口坐标系里。');
+      const stepsRaw = flags.get('steps');
+      const steps = stepsRaw === undefined ? 10 : Number(stepsRaw);
+      if (!Number.isInteger(steps) || steps < 1 || steps > 100) throw new Error(`--steps 需要 1-100 的整数，收到 "${stepsRaw}"`);
+      const { cdp } = await connectPage(match, target);
+      await waitForElement(cdp, fromSel, timeout, 150);
+      await waitForElement(cdp, toSel, timeout, 150);
+      const both = await evaluate(cdp, `(() => {
+        const a = ${selectorExpr(fromSel)}, b = ${selectorExpr(toSel)};
+        const rect = el => { const r = el.getBoundingClientRect(); return { x: r.x + r.width / 2, y: r.y + r.height / 2 }; };
+        const inView = el => { const r = el.getBoundingClientRect(); const x = r.x + r.width / 2, y = r.y + r.height / 2;
+          return x >= 0 && y >= 0 && x <= innerWidth && y <= innerHeight; };
+        if (!a || !b) return null;
+        return { from: rect(a), to: rect(b), fromIn: inView(a), toIn: inView(b) };
+      })()`, { timeoutMs: 5000 });
+      if (!both) throw new Error('拖拽两端必须都存在（且可见）: ' + fromSel + ' / ' + toSel);
+      if (!both.fromIn || !both.toIn) {
+        throw new Error(`拖拽要求两端同时可见且在视口内（来源${both.fromIn ? '在' : '不在'}视口，目标${both.toIn ? '在' : '不在'}视口）。先用 click / eval 把两者滚到同屏。`);
+      }
+      await dragBetween(cdp, both.from, both.to, steps);
+      console.log(`已拖拽 ${fromSel} → ${toSel}（${steps} 步）`);
+      cdp.close();
+      return;
+    }
+
+    case 'text': {
+      const { cdp } = await connectPage(match, target);
+      const root = frame ? 'd' : 'document';
+      const win = frame ? 'w' : 'window';
+      const core = pos[0]
+        ? `((${selectorExpr(pos[0], root, win)})?.innerText ?? '')`
+        : `${root}.body.innerText`;
+      console.log(assertFrameAccess(await evaluate(cdp, frame ? inFrame(frame, core) : core), frame));
+      cdp.close();
+      return;
+    }
+
+    case 'html': {
+      const { cdp } = await connectPage(match, target);
+      const root = frame ? 'd' : 'document';
+      const win = frame ? 'w' : 'window';
+      const core = pos[0]
+        ? `((${selectorExpr(pos[0], root, win)})?.outerHTML ?? '')`
+        : `${root}.documentElement.outerHTML`;
+      console.log(assertFrameAccess(await evaluate(cdp, frame ? inFrame(frame, core) : core), frame));
+      cdp.close();
+      return;
+    }
+
+    case 'pdf': {
+      const [outArg] = pos;
+      if (!outArg) throw new Error('用法: cdpctl pdf <out.pdf> --size WxH [--media screen|print]');
+      const sizeRaw = flags.get('size');
+      const m = /^(\d+)[x×](\d+)$/.exec(String(sizeRaw || ''));
+      if (!m) throw new Error(`--size 需要 宽x高（CSS px，如 --size 1440x788），收到 "${sizeRaw}"`);
+      const [pw, ph] = [Number(m[1]) / 96, Number(m[2]) / 96];      // CSS px → 英寸
+      const media = String(flags.get('media') || 'print');
+      if (!['print', 'screen'].includes(media)) throw new Error(`--media 只能是 print|screen，收到 "${media}"`);
+      const { cdp } = await connectPage(match, target);
+      if (media === 'screen') await cdp.send('Emulation.setEmulatedMedia', { media: 'screen' }, { timeoutMs: 5000 });
+      const r = await cdp.send('Page.printToPDF', {
+        printBackground: true, preferCSSPageSize: false,
+        paperWidth: pw, paperHeight: ph,
+        marginTop: 0, marginBottom: 0, marginLeft: 0, marginRight: 0,
+        transferMode: 'ReturnAsBase64',
+      }, { timeoutMs: 40000, timeoutHint: DIALOG_HINT });
+      const out = path.resolve(outArg);
+      mkdirSync(path.dirname(out), { recursive: true });
+      const buf = Buffer.from(r.data, 'base64');
+      writeFileSync(out, buf);
+      console.log(`${out} (${buf.length} 字节)`);
+      cdp.close();
+      return;
+    }
+
+    case 'shot': {
+      const [outArg, sel] = pos;
+      if (!outArg) throw new Error('用法: cdpctl shot <out.png> [选择器] [--full] [--clip x,y,w,h]');
+      const full = !!flags.get('full');
+      const clipRaw = flags.get('clip');
+      if (sel && full) throw new Error('元素截图与 --full 不兼容（元素截图本身就是按元素边界裁剪）');
+      if (sel && clipRaw !== undefined) throw new Error('元素截图与 --clip 不兼容（选择器已决定裁剪范围）');
+      if (full && clipRaw !== undefined) throw new Error('--full 与 --clip 不兼容：二选一');
+      const { cdp } = await connectPage(match, target);
+      const opts = { format: 'png', captureBeyondViewport: full };
+      if (clipRaw !== undefined) {
+        const n = String(clipRaw).split(',').map(Number);
+        if (n.length !== 4 || n.some(v => !Number.isFinite(v))) {
+          throw new Error(`--clip 需要 x,y,宽,高 四个数字，收到 "${clipRaw}"`);
+        }
+        const [x, y, width, height] = n;
+        if (width <= 0 || height <= 0) throw new Error(`--clip 的宽/高必须为正，收到 ${width}x${height}`);
+        const scale = num(flags.get('scale'), 1);
+        if (!(scale > 0)) throw new Error(`--scale 需要正数，收到 "${flags.get('scale')}"`);
+        opts.captureBeyondViewport = false;
+        opts.clip = { x, y, width, height, scale };
+      }
+      if (sel) {
+        const box = assertFrameAccess(await evaluate(cdp, boxExpr(sel, frame), { timeoutMs: 5000 }), frame);
+        if (!box) throw new Error(`找不到元素（或不可见）: ${sel}`);
+        const off = await evaluate(cdp, '({ x: scrollX, y: scrollY })', { timeoutMs: 5000 });
+        opts.captureBeyondViewport = true;
+        opts.clip = { x: box.x + off.x, y: box.y + off.y, width: box.w, height: box.h, scale: 1 };
+      }
+      const r = await cdp.send('Page.captureScreenshot', opts, { timeoutMs: 15000, timeoutHint: DIALOG_HINT });
+      const out = path.resolve(outArg);
+      mkdirSync(path.dirname(out), { recursive: true });
+      const buf = Buffer.from(r.data, 'base64');
+      writeFileSync(out, buf);
+      console.log(`${out} (${buf.length} 字节)`);
+      cdp.close();
+      return;
+    }
+
+    case 'upload': {
+      const [sel, file] = pos;
+      if (!sel || !file) throw new Error('用法: cdpctl upload <CSS选择器> <文件路径> [--frame <iframe选择器>]');
+      const abs = path.resolve(file);
+      if (!existsSync(abs)) throw new Error('文件不存在: ' + abs);
+      const { cdp } = await connectPage(match, target);
+      // 用 objectId 而不是 nodeId：同一套代码就能覆盖主文档与同源 iframe 内部。
+      // 表达式走 selectorExpr，所以 CSS / @引用 都可以。
+      const expr = frame
+        ? `(() => { const f = document.querySelector(${JSON.stringify(frame)}); if (!f || !f.contentDocument) return null; return (${selectorExpr(sel, 'f.contentDocument', 'f.contentWindow')}); })()`
+        : `(${selectorExpr(sel)})`;
+      await cdp.send('Runtime.enable');
+      const { result, exceptionDetails } = await cdp.send('Runtime.evaluate', { expression: expr, includeCommandLineAPI: true }, { timeoutMs: 5000 });
+      if (exceptionDetails) throw new Error('页面内异常: ' + (exceptionDetails.exception?.description || exceptionDetails.text));
+      if (!result?.objectId) throw new Error('找不到元素（或不可见）: ' + sel + (frame ? `（iframe: ${frame}）` : ''));
+      await cdp.send('DOM.enable');
+      await cdp.send('DOM.setFileInputFiles', { files: [abs], objectId: result.objectId });
+      console.log('已设置文件:', abs);
+      cdp.close();
+      return;
+    }
+
+    case 'cookies': {
+      const { cdp } = await connectPage(match, target);
+      const r = await cdp.send('Network.getCookies', {});
+      const rows = (r.cookies || []).map(c => ({
+        host: c.domain, name: c.name,
+        exp: c.expires > 0 ? new Date(c.expires * 1000).toISOString().slice(0, 10) : 'SESSION',
+        len: (c.value || '').length, ho: c.httpOnly ? 'HTTP' : '', sec: c.secure ? 'SEC' : '',
+      })).sort((a, b) => a.host.localeCompare(b.host) || a.name.localeCompare(b.name));
+      for (const x of rows) console.log(`${x.host.padEnd(26)} ${x.name.padEnd(44)} ${x.exp.padEnd(10)} len=${String(x.len).padStart(4)} ${x.ho} ${x.sec}`.trimEnd());
+      console.log(`\n共 ${rows.length} 个 cookie（SESSION = 会话 cookie，浏览器重启会丢）`);
+      cdp.close();
+      return;
+    }
+
+    case 'persist-cookies': {
+      const domain = flags.get('domain');
+      if (!domain) throw new Error('用法: cdpctl persist-cookies --domain <域名片段>');
+      const s = await stop();
+      console.log(s.stopped ? '已关闭浏览器（改写需要独占数据库）' : `浏览器状态: ${s.reason}`);
+      const r = await persistCookies(domain);
+      console.log(`数据库: ${r.db}`);
+      console.log(`已把 ${r.converted} 个会话 cookie 转成持久 cookie:`);
+      for (const x of r.rows) console.log(`  ${x.host_key} ${x.name}`);
+      if (!r.converted) console.log('  (没有需要转换的，可能已经是持久 cookie)');
+      console.log('\n下一步: cdpctl launch');
+      return;
+    }
+
+    case 'import-cookies': {
+      const apply = !!(flags.get('yes') || flags.get('apply'));
+      const fromDir = flags.get('from') || defaultChromeDataDir();
+      const profileName = flags.get('profile') || 'Default';
+      if (!existsSync(path.join(fromDir, profileName))) {
+        throw new Error(`源 profile 不存在：${path.join(fromDir, profileName)}\n提示：确认 Chrome 用户数据目录与 profile 名（macOS 常见 Default / "Profile 1"）`);
+      }
+      const s = apply ? await stop() : { stopped: false, reason: 'dry-run 不动浏览器' };
+      if (apply) console.log(s.stopped ? '已关闭受控浏览器（替换数据库需要独占）' : `浏览器状态: ${s.reason}`);
+      const r = await importCookies({ fromDir, profile: profileName, apply });
+      const top = r.src.top.map(x => `${x.host_key}(${x.n})`).join(' ');
+      console.log(`源数据库: ${r.srcDb}`);
+      console.log(`  cookie ${r.src.total} 个；域示例: ${top || '(空)'}`);
+      console.log(`目标数据库: ${r.dstDb}`);
+      if (!r.applied) {
+        console.log(`备份将写入: ${r.backup}`);
+        console.log('[dry-run] 未改动任何文件。确认后加 --yes 执行。');
+        console.log('注意: 复制的是源 profile 的全部站点登录态；目标库原有的 cookie 备份后被替换。');
+        return;
+      }
+      console.log(`已导入: cookie 总数 ${r.dst.total}；目标库备份: ${r.backup}`);
+      console.log('下一步: cdpctl launch');
+      return;
+    }
+
+    case 'net': {
+      await netLog({
+        match, target,
+        seconds: num(flags.get('seconds'), 8),
+        grep: flags.get('grep'),
+        save: flags.get('save'),
+        bodies: flags.get('bodies'),
+        bodiesAll: flags.get('bodies-all'),
+        sanitize: flags.get('sanitize'),
+      });
+      return;
+    }
+
+    case 'console': {
+      const seconds = num(flags.get('seconds'), 3);
+      if (!Number.isFinite(seconds) || seconds < 0) throw new Error(`--seconds 需要非负秒数，收到 "${flags.get('seconds')}"`);
+      await consoleLog({
+        match, target, seconds, grep: flags.get('grep'),
+        types: flags.get('types'), reload: !!flags.get('reload'),
+      });
+      return;
+    }
+  }
+}
+
+main().catch(e => { console.error('错误: ' + e.message); process.exit(1); });