@epoint-playwright/cdp-recorder 0.0.0-stage → 2.0.0-rc.2

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
+# CDP 录制
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+评审当前未提交增量请看 [BMAD 方案与验收](../../_bmad-output/planning-artifacts/sprint-change-proposal-2026-10-26.md)；本轮历史检查记录见 [BMAD 证据附件](../../_bmad-output/planning-artifacts/prds/prd-epoint-playwright-2026-10-26/evidence/validation.json)。
+
+用 Chrome DevTools Protocol 驱动真实浏览器，把页面操作录成 JSON，再交给 `codegen-cli` 生成 Playwright 页面对象。
+
+## 为什么这么做
+
+原来的录制靠 Chrome 扩展（`packages/web-capture-ext`），要手动装扩展、点录制按钮。换成 CDP 后，脚本直接驱动浏览器，录制可以完全自动跑。
+
+关键是**没有重写采集逻辑**：注入的仍是那套 `recording-*.js`（现随本包发布，`web-capture-ext` 构建时复用同一份），只是把 `chrome.runtime.sendMessage` 桥接到 CDP 的 `Runtime.addBinding`。产出的 JSON 和扩展录制结构一致，codegen 不需要任何改动。
+
+## 在脚手架项目中使用
+
+`epoint-create` 生成的项目已把本包和 `codegen-cli` 装为 devDependencies，命令在**项目根**执行：
+
+```bash
+npx epoint-cdp-recorder probe --doctor
+npx epoint-cdp-recorder record --flow flows/xxx.mts --out recordings --verbose
+npx epoint-codegen recordings/action-*.json pages/XxxPage.ts "步骤名称" --stdout
+```
+
+- `--out` 缺省为 `recordings/`，`probe --facts` 缺省写到 `flows/`。
+- 页面内录制脚本随包发布（`recording-assets/`），不需要额外装扩展。
+- 本包依赖 Node 的全局 WebSocket / fetch，需要 **Node ≥ 22**。
+
+## 怎么跑
+
+Chrome 启动时加调试端口，**窗口放前台**（页面在后台时 `visibilityState === 'hidden'`，CDP 派发的鼠标事件不触发页面监听器，表现是"点了完全没反应也不报错"）：
+
+```bash
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-cdp-profile \
+  --no-first-run "about:blank"
+```
+
+```bash
+# 探索：先看清页面结构，再写流程脚本
+pnpm --filter @epoint-playwright/cdp-recorder probe
+pnpm --filter @epoint-playwright/cdp-recorder probe --frame purchasereqplan_workflow
+pnpm --filter @epoint-playwright/cdp-recorder probe --windows
+
+# 录制（凭据走环境变量）
+EPOINT_ENTRY=xxx EPOINT_PASS=xxx EPOINT_STRICT_MENU=1 pnpm --filter @epoint-playwright/cdp-recorder record \
+  --flow ../../examples/e2e/flows/purchase-initiation.mts --out /tmp/rec --verbose
+
+# EPOINT_STRICT_MENU=1：菜单真实点击失败时直接失败，不用 DOM click 兜底。
+# DOM click 是合成事件（isTrusted=false），录制脚本会忽略，录出来的 JSON 会缺菜单步骤。
+# 续跑被上次失败留下的弹窗挡住时加 --cleanup（录制启动前关掉遗留弹窗；续跑点在弹窗内时不要加）。
+
+# 生成页面对象
+node packages/codegen-cli/codegen-cli.mjs /tmp/rec/action-*.json \
+  examples/e2e/pages/PurchaseInitiationPage.ts "采购立项" --stdout
+```
+
+`probe` 的几种模式：
+
+| 命令 | 看什么 |
+|---|---|
+| `probe` | iframe 树 + 可见弹窗 + 控件类型统计（默认概览） |
+| `probe --frames` | 只列 iframe（含嵌套层级、可见性、跨域标记） |
+| `probe --windows` | 所有 `mini-window`（递归下钻，含标题和 iframe src） |
+| `probe --frame <src>` | 该 frame 的全部 MiniUI 控件（id / type / 必填 / 可见 / 值） |
+| `probe --popups --frame <src>` | 当前可见浮层里的树/列表节点 |
+| `probe --tree <控件id> --frame <src>` | 树控件的数据结构（含层级树形图） |
+| `probe --snapshot [--out <json>] [--shot <png>]` | 一次采集整页模型：frame 链、MiniUI 控件+选项、原生控件、必填空缺、弹窗、消息框 |
+| `probe --find <关键词>` | 跨 frame 找控件/原生元素/文本，包含隐藏/已关闭弹窗残留的 DOM |
+| `probe --required [--frame <src>]` | 列出页面真正会拦的必填项（含无 id 控件）和哪些为空，保存前先跑 |
+| `probe --act <意图> --target <目标>` | 统一动作接口。目标：`id:x` / `label:中文名` / `text:按钮文字` / `css:选择器` / `window:标题`；意图：`set` / `click` / `pick` / `click-menu` / `wait-control` / `wait-settled`。横切 flag：`--guard-required`、`--expect-message`、`--expect-window`、`--force`、`--no-confirm`、`--act-timeout <ms>`（默认 120s，卡死直接退出码 124） |
+| `probe --diff <before.json> <after.json>` | 对比两次快照，只看新增/消失/变化的 frame、控件、必填项、弹窗 |
+| `probe --facts <flow> [--from <json>]` | 把整页模型落成 `<flow>.probe.json` + `<flow>.facts.md`（已有 facts 默认不覆盖，`--force` 覆盖） |
+| `probe --check <probe.json> [--update]` | 对比当前页面与缓存模型，只报结构变化；`--update` 刷新缓存 |
+| `probe --doctor` | 开工前体检：CDP 可达、`visibilityState`、定时器是否被节流、有无其它录制进程、当前页面。正常退出码 0，有问题退出码 2 |
+
+`--frame` 支持嵌套链：`purchasereqplan_workflow>pplineitem_workflow`。只写一段时会递归搜索，不用先知道它嵌在哪一层。
+
+探索新页面时优先用「一次快照 + 差分」：`probe --snapshot --out /tmp/s1.json` 建立基线，做完一个动作再拍一张，`probe --diff /tmp/s1.json /tmp/s2.json` 只看新增的 frame、控件、必填项和弹窗。字段不在当前 frame 时用 `probe --find <关键词>`，它会连隐藏弹窗残留的 DOM 一起搜，并给出完整的 frame 链和所在弹窗标题。
+
+## 加新控件：四步闭环
+
+控件是**表驱动**的，加一个控件 = 加一行数据。
+
+**动手前先看 `packages/epoint-playwright-web/src/MiniDriver.ts` 有没有同控件的现成实现**——
+选择器和交互顺序照搬，别重新发明（控件与方法对应关系见 `cdp-control-dev` skill）。
+
+1. `probe --frame xxx` 看清楚控件的运行时 `type` 和内部结构
+2. 在 [`src/miniui/controls.ts`](src/miniui/controls.ts) 的 `CONTROL_SPECS` 加一行
+3. `pnpm --filter @epoint-playwright/cdp-recorder typecheck` —— 类型检查；`pnpm --filter @epoint-playwright/cdp-recorder test` —— 注册表结构 + 覆盖对齐
+4. 录一条真实流程验证，通过后把 `verified` 从 `false` 改成 `true`（只跑通部分分支就写 `'partial'` 并在 `notes` 里说明）
+
+八种交互策略（`op`）已实现，绝大多数控件直接复用：
+
+| op | 交互 | 典型控件 |
+|---|---|---|
+| `type` | 点内部输入框 → 全选 → 真实输入 → 失焦提交 | textbox / textarea / buttonedit |
+| `clickItem` | 在控件内按文本匹配子项并点击 | radiobuttonlist / checkboxlist |
+| `toggle` | 读状态 → 需要时点图标 | checkbox 开关 |
+| `pickList` | 点 trigger → 等浮层 → 按文本点列表项 | combobox |
+| `pickTree` | 点 trigger → 等浮层 → 逐级展开并点末节点 | treeselect |
+| `pickDate` | 点 trigger → 等 laydate 弹层 → 选「现在」或指定日期 | datepicker |
+| `checkTree` | 逐级展开树路径 → 勾选末端复选框 →（可选）点确认按钮 | tabstreeselect / 复选树 |
+| `typeRichText` | 点富文本编辑区 body → 全选 → 真实输入 → 失焦 | webeditor（UEditor/eWebEditor） |
+| `clickText` | 按文字点按钮 | button |
+
+## 当前支持情况
+
+`test/coverage.test.ts` 会直接读 codegen 的 `MAPPING_RULES_TS` 做集合比对，**跑测试就能看到"还有哪些控件没试"**，不需要记：
+
+```bash
+pnpm --filter @epoint-playwright/cdp-recorder test 2>&1 | grep 'coverage]'
+```
+
+当前状态（20 个控件，12 个完整 + 5 个部分）：
+
+| 已实现 | 说明 |
+|---|---|
+| `mini-textbox` / `mini-textarea` | 完整 |
+| `mini-combobox` | 完整 |
+| `mini-radiobuttonlist` | 完整 |
+| `mini-checkbox` | 完整 |
+| `mini-checkboxlist` | 完整：多选按「对齐集合」逐项勾选/取消（`DEBUG+WARN`） |
+| `mini-spinner` | **部分**：输入路径已真机验证；上下箭头未验证 |
+| `mini-button` / `mini-button-text` | 完整 |
+| `mini-contenteditable` | 原生可编辑区（工作流「签署意见」），完整 |
+| `mini-buttonedit-form` | 表单 searchbox，只填值不点 trigger |
+| `mini-datepicker` | 完整 |
+| `mini-treeselect` | 完整：单选和复选（多叶子 `checkPaths`）均已真机验证 |
+| `mini-tabstreeselect` | **部分**：复选叶子路径 `checkTreePath` + 可选「确认选择」；树网格行 `tr.mini-grid-row` 已适配；多 tab 切换未覆盖 |
+| `mini-filtertree` | **部分**：内嵌筛选树（树网格行），跳过 trigger 直接按控件作用域选节点；单层/两层已验证，更深分支未覆盖 |
+| `mini-webuploader` | **部分**：`DOM.setFileInputFiles` 设置文件并触发 change，录制生成 `miniUploadFile`；「开始上传」用合成点击 |
+| `mini-webeditor` | **部分**：UEditor 已真机录放（编辑区 iframe 的 blur 由父窗口代理采集，值随 blur 落盘，回放 `inputMiniWebEditor(value, label)`）；eWebEditor 变体未真机验证 |
+
+待实现：`mini-daterangepicker`、`mini-buttonedit-search`、`mini-datagrid-cell`。
+
+## 写流程脚本的规矩
+
+流程脚本放在 `examples/e2e/flows/*.mts`（`.mts` 永远是 ESM，绕开 examples 包的 `type: commonjs` 歧义）。
+
+```ts
+import { session, menu, ui, waitFor, type CdpClient, type CdpRecorder } from '@epoint-playwright/cdp-recorder';
+
+export const name = '采购立项-登录到保存';
+
+export async function run(cdp: CdpClient, recorder: CdpRecorder): Promise<void> {
+  await session.login(cdp);                                  // 凭据走环境变量
+  await menu.clickIdeaMenu(cdp, ['采购立项管理', '采购立项']);
+  await ui.clickButton(cdp, 'purchaseproject_list', '新增采购项目');
+  await ui.inputText(cdp, 'purchaseproject_workflow', 'projectname', value, 'buttonedit');
+  await ui.selectTree(cdp, 'purchaseproject_workflow', 'xiaqucode', '北京市', '110000');
+  await ui.expectMessageBox(cdp, '保存成功');
+}
+```
+
+三条硬规矩：
+
+1. **每个动作只做一次**。别写"滚动 + 命中检测 + 反复点"的试探循环，那会把一次操作录成四五个 click，污染录制。
+2. **不要按 Tab 失焦**。Tab 会把焦点跳到下一个控件，之后点别处时它空着 blur，录出一条假操作。用 `el.blur()`（原语内部已处理）。
+3. **等状态，不写固定 sleep**。`ui.waitIdle` / `ui.waitFrame` / `ui.waitPopup` 已经封装了 `div.page-loading`、`div.mini-mask-background`、浮层可见性判断；子窗口关闭后父窗口会重渲染工具栏，用 `ui.waitSettled` 等 DOM 真正安静再点。
+
+## 树操作 API（分层）
+
+树的 DOM 选择器、作用域回退和重试只有一份实现，按四层组织在 `src/miniui/tree/`：
+
+| 层 | 用什么 | 什么时候用 |
+|---|---|---|
+| 行模型（纯函数） | `planTreeAction` / `isCheckSettled` / `parseTreePath` / `childRows` | 写策略或做纯逻辑测试，不碰浏览器 |
+| 读行 | `readTreeRows(cdp, f, { scopeId })` / `readTreeRow(cdp, f, 节点名, scopeId?)` | 先看当前有哪些节点、各是什么状态 |
+| 单步动作 | `waitTreeRow` / `expandTreeRow` / `clickTreeRow` / `checkTreeRow` | 只展开/点/勾一个节点，选择逻辑自己写 |
+| 高层选择 | `selectTree` / `pickTreeNode` / `checkTreePath` / `selectFirstTreeLeaf` | 目标明确（按路径选）或没有目标（选第一个可选叶子） |
+
+行模型一次读出：`text / visible / parent / collapsed / hasExpander / checked / hasCheckbox / radio / leaf`。
+作用域：**给了控件 id 就只在「控件 → 可见浮层」里找**（treeselect 的节点在浮层、内嵌树在控件里），
+不退回整页 —— 退回整页会在浮层没打开时选中同页另一棵树的同名节点，把错误节点写进录制。不给 id 时才退到整页。
+旧名（`openTreePopup` / `checkTreeNode`）保留，迁移期脚本不用改。
+
+**新页面怎么写**：`ensureTreeOpen` 打开容器（内嵌树自动跳过）→ `readTreeRows` 看当前节点 → 组合
+`expandTreeRow` + `clickTreeRow` / `checkTreeRow`。不要往 `tree/` 里加页面专用函数；
+只有出现新的 DOM 变体（行结构、展开图标、勾选框选择器不同）才改 `tree/rows.ts`，只改那一处。
+
+## 目录
+
+```
+packages/cdp-recorder/
+  src/cdp/            CDP 客户端 + DOM 域定位
+  src/miniui/         控件原语（context / wait / pointer / read / controls / dialog）
+                      ops-input / ops-pick / date-picker / tree/ / apply（index.ts 统一出口）
+  src/miniui/tree/    树操作（model 行模型 / rows 读行 / ops 单步动作 / select 高层选择）
+  src/recorder/       录制器 + 后处理 + 约束校验
+  src/flows/session.ts  登录 / 配置 / stamp / waitControl（对外门面没有：按模块各自导出）
+  src/flows/menu.ts     菜单导航
+  src/flows/form.ts     表单填写 / 必填项 / 按钮+消息框
+  src/flows/grid.ts     表格行读取与等待
+  src/flows/steps.ts    断点续跑（runSteps）
+  src/cli/index.ts      只做分发；record.ts / doctor.ts / probe/*.ts 是各命令实现
+  test/               注册表 / 覆盖 / 后处理 / 约束
+  docs/               ARCHITECTURE / TROUBLESHOOTING / CONSTRAINTS / BACKLOG
+```
+
+更多细节：[ARCHITECTURE.md](docs/ARCHITECTURE.md)（录制器原理）、[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)（踩坑清单）、[CONSTRAINTS.md](docs/CONSTRAINTS.md)（录制硬约束）、[BACKLOG.md](docs/BACKLOG.md)（待办与已知缺口）。

package/dist/cdp/client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 极简 CDP 客户端。
+ *
+ * 只做三件事：连上已开的 Chrome、拿到页面 target、在页面/iframe 里执行 JS。
+ * 不封装业务，业务在 recorder/ 与 flows/ 里。
+ *
+ * 依赖全局 fetch / WebSocket（Node 22+ 稳定），刻意零 npm 依赖：
+ * 这个工具开发时直接 `node src/cli/index.ts` 跑，发布时编译到 dist/；运行时零 npm 依赖：
+ */
+export interface CdpMessage {
+    id?: number;
+    method?: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+    result?: Record<string, unknown>;
+    error?: unknown;
+}
+export interface CdpClient {
+    ws: WebSocket;
+    page: {
+        targetId: string;
+        url: string;
+    };
+    sessionId: string;
+    send: (method: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    on: (fn: (msg: CdpMessage) => void) => void;
+    close: () => void;
+}
+interface ConnectOptions {
+    /** 页面 URL 必须包含的片段；不传则取第一个 page target */
+    urlContains?: string;
+}
+export declare function connect(cdpUrl?: string, opts?: ConnectOptions): Promise<CdpClient>;
+/** 在指定执行上下文里求值，返回 JSON 值。 */
+export declare function evaluate(cdp: CdpClient, expression: string, contextId?: number): Promise<unknown>;
+/** 在顶层页面执行。 */
+export declare function evaluateTop(cdp: CdpClient, expression: string): Promise<unknown>;
+/** 发一次真实鼠标点击（CSS 像素，相对顶层视口）。 */
+export declare function clickAt(cdp: CdpClient, x: number, y: number): Promise<void>;
+/** 输入文本（走真实输入通道，触发 input/change）。 */
+export declare function typeText(cdp: CdpClient, text: string): Promise<void>;
+/** 按下并释放一个键，用于 Enter/Tab。 */
+export declare function pressKey(cdp: CdpClient, key: string): Promise<void>;
+/** 轮询等待条件成立。 */
+export declare function waitFor(cdp: CdpClient, expression: string, timeoutMs?: number, intervalMs?: number): Promise<true>;
+export {};

package/dist/cdp/client.js

@@ -0,0 +1,137 @@
+/**
+ * 极简 CDP 客户端。
+ *
+ * 只做三件事：连上已开的 Chrome、拿到页面 target、在页面/iframe 里执行 JS。
+ * 不封装业务，业务在 recorder/ 与 flows/ 里。
+ *
+ * 依赖全局 fetch / WebSocket（Node 22+ 稳定），刻意零 npm 依赖：
+ * 这个工具开发时直接 `node src/cli/index.ts` 跑，发布时编译到 dist/；运行时零 npm 依赖：
+ */
+export async function connect(cdpUrl = 'http://127.0.0.1:9222', opts = {}) {
+    const version = (await (await fetch(`${cdpUrl}/json/version`)).json());
+    const ws = new WebSocket(version.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+        ws.onopen = () => resolve();
+        ws.onerror = () => reject(new Error('CDP WebSocket 连接失败'));
+    });
+    let seq = 0;
+    const pending = new Map();
+    const listeners = [];
+    let closed = false;
+    /** 立即失败所有在途请求：socket 关掉后它们不会再收到响应，只能等 30s 超时。 */
+    const failPending = (reason) => {
+        for (const [id, p] of pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(reason));
+            pending.delete(id);
+        }
+    };
+    ws.onclose = () => {
+        closed = true;
+        failPending('CDP 连接已关闭');
+    };
+    ws.onmessage = (event) => {
+        const msg = JSON.parse(String(event.data));
+        if (msg.id && pending.has(msg.id)) {
+            const p = pending.get(msg.id);
+            pending.delete(msg.id);
+            // 必须清掉超时定时器：不清的话每次调用都挂一个 30s 的 timer，
+            // 最后一个命令跑完后 Node 还要空等 30 秒才退出。
+            clearTimeout(p.timer);
+            if (msg.error)
+                p.reject(new Error(JSON.stringify(msg.error)));
+            else
+                p.resolve(msg.result ?? {});
+            return;
+        }
+        if (msg.method)
+            listeners.forEach((fn) => fn(msg));
+    };
+    const send = (method, params = {}) => {
+        if (closed)
+            return Promise.reject(new Error(`CDP 已关闭: ${method}`));
+        const id = ++seq;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (pending.has(id)) {
+                    pending.delete(id);
+                    reject(new Error(`CDP timeout: ${method}`));
+                }
+            }, 30000);
+            pending.set(id, { resolve, reject, timer });
+            // 首次 Target.* 调用还没有 sessionId，带上空串会被 CDP 拒绝。
+            ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+        });
+    };
+    // sessionId 在下面拿到后回填；这里用闭包变量保证 send 里能读到最新值。
+    let sessionId = '';
+    const targets = (await send('Target.getTargets'));
+    const infos = targets.targetInfos;
+    // 指定了 urlContains 就按它挑；没指定时优先选有实际页面内容的 tab，
+    // 跳过 about:blank / devtools 之类的空白 target。
+    const pages = infos.filter((t) => t.type === 'page');
+    const page = opts.urlContains
+        ? (pages.find((t) => t.url.includes(opts.urlContains)) ?? pages[0])
+        : (pages.find((t) => /^https?:/i.test(t.url)) ?? pages[0]);
+    if (!page)
+        throw new Error('没有找到页面 target');
+    const attached = (await send('Target.attachToTarget', { targetId: page.targetId, flatten: true }));
+    sessionId = attached.sessionId;
+    return {
+        ws,
+        page,
+        sessionId,
+        send,
+        on: (fn) => listeners.push(fn),
+        close: () => {
+            closed = true;
+            ws.close();
+            failPending('CDP 连接已关闭');
+        },
+    };
+}
+/** 在指定执行上下文里求值，返回 JSON 值。 */
+export async function evaluate(cdp, expression, contextId) {
+    const result = (await cdp.send('Runtime.evaluate', {
+        expression,
+        ...(contextId ? { contextId } : {}),
+        awaitPromise: true,
+        returnByValue: true,
+        userGesture: true,
+    }));
+    if (result.exceptionDetails) {
+        throw new Error(result.exceptionDetails.exception?.description ?? JSON.stringify(result.exceptionDetails));
+    }
+    return result.result?.value;
+}
+/** 在顶层页面执行。 */
+export async function evaluateTop(cdp, expression) {
+    return evaluate(cdp, expression);
+}
+/** 发一次真实鼠标点击（CSS 像素，相对顶层视口）。 */
+export async function clickAt(cdp, x, y) {
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+}
+/** 输入文本（走真实输入通道，触发 input/change）。 */
+export async function typeText(cdp, text) {
+    await cdp.send('Input.insertText', { text });
+}
+/** 按下并释放一个键，用于 Enter/Tab。 */
+export async function pressKey(cdp, key) {
+    const code = key === 'Enter' ? 'Enter' : key === 'Tab' ? 'Tab' : key;
+    await cdp.send('Input.dispatchKeyEvent', { type: 'rawKeyDown', key, code });
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key, code });
+}
+/** 轮询等待条件成立。 */
+export async function waitFor(cdp, expression, timeoutMs = 15000, intervalMs = 250) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const ok = await evaluateTop(cdp, expression).catch(() => false);
+        if (ok)
+            return true;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`waitFor 超时: ${expression}`);
+}

package/dist/cdp/dom.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 用 CDP 的 DOM 域定位元素，代替页面里算坐标。
+ *
+ * 为什么不用 `getBoundingClientRect() + frameElement 偏移`：
+ *   - 多层 iframe 要手工累加偏移，差一层就点飞；
+ *   - 滚动位置要自己算，滚动容器可能是 iframe 内部的某个 div；
+ *   - 页面缩放/滚动条会让坐标偏。
+ *
+ * CDP 的做法：
+ *   - `DOM.describeNode` 拿 backendNodeId（页面 JS 只负责"找哪个元素"，不算位置）；
+ *   - `DOM.scrollIntoViewIfNeeded` 由浏览器自己滚；
+ *   - `DOM.getBoxModel` 返回主框架坐标系下的四边形，直接取中心。
+ */
+import type { CdpClient } from './client.ts';
+export interface Point {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    backendNodeId?: number;
+}
+/** 确保 DOM 域已启用。 */
+export declare function enableDom(cdp: CdpClient): Promise<void>;
+/**
+ * 把一个页面内表达式求值得到的元素转成 backendNodeId。
+ * expression 必须返回 Element 或 null。
+ */
+export declare function backendNodeIdOf(cdp: CdpClient, expression: string): Promise<number | null>;
+/**
+ * 让浏览器把节点滚进可视区并返回中心坐标（主框架坐标系，CSS 像素）。
+ * 节点不可见（尺寸为 0）时返回 null。
+ */
+export declare function centerOfNode(cdp: CdpClient, backendNodeId: number): Promise<Point | null>;
+/** 一次完成：表达式 → backendNodeId → 中心坐标。 */
+export declare function locate(cdp: CdpClient, expression: string): Promise<Point | null>;
+/** 带诊断的 locate：返回失败原因，便于定位是哪一层出问题。 */
+export declare function locateVerbose(cdp: CdpClient, expression: string): Promise<Point | {
+    x?: undefined;
+    reason: string;
+}>;

package/dist/cdp/dom.js

@@ -0,0 +1,112 @@
+/**
+ * 用 CDP 的 DOM 域定位元素，代替页面里算坐标。
+ *
+ * 为什么不用 `getBoundingClientRect() + frameElement 偏移`：
+ *   - 多层 iframe 要手工累加偏移，差一层就点飞；
+ *   - 滚动位置要自己算，滚动容器可能是 iframe 内部的某个 div；
+ *   - 页面缩放/滚动条会让坐标偏。
+ *
+ * CDP 的做法：
+ *   - `DOM.describeNode` 拿 backendNodeId（页面 JS 只负责"找哪个元素"，不算位置）；
+ *   - `DOM.scrollIntoViewIfNeeded` 由浏览器自己滚；
+ *   - `DOM.getBoxModel` 返回主框架坐标系下的四边形，直接取中心。
+ */
+/** 确保 DOM 域已启用。 */
+export async function enableDom(cdp) {
+    await cdp.send('DOM.enable').catch(() => { });
+}
+/**
+ * 把一个页面内表达式求值得到的元素转成 backendNodeId。
+ * expression 必须返回 Element 或 null。
+ */
+export async function backendNodeIdOf(cdp, expression) {
+    const res = (await cdp
+        .send('Runtime.evaluate', { expression, returnByValue: false, userGesture: true })
+        .catch(() => null));
+    if (res?.exceptionDetails)
+        return null;
+    const objectId = res?.result?.objectId;
+    if (!objectId)
+        return null;
+    const described = (await cdp.send('DOM.describeNode', { objectId }).catch(() => null));
+    return described?.node?.backendNodeId ?? null;
+}
+/**
+ * 让浏览器把节点滚进可视区并返回中心坐标（主框架坐标系，CSS 像素）。
+ * 节点不可见（尺寸为 0）时返回 null。
+ */
+export async function centerOfNode(cdp, backendNodeId) {
+    await cdp.send('DOM.scrollIntoViewIfNeeded', { backendNodeId }).catch(() => { });
+    const { model } = (await cdp.send('DOM.getBoxModel', { backendNodeId }).catch(() => ({ model: null })));
+    if (!model)
+        return null;
+    // content quad = [x1,y1, x2,y2, x3,y3, x4,y4]，四个角
+    const q = model.content;
+    const width = Math.hypot(q[2] - q[0], q[3] - q[1]);
+    const height = Math.hypot(q[4] - q[2], q[5] - q[3]);
+    if (width === 0 || height === 0)
+        return null;
+    return {
+        x: (q[0] + q[2] + q[4] + q[6]) / 4,
+        y: (q[1] + q[3] + q[5] + q[7]) / 4,
+        w: width,
+        h: height,
+    };
+}
+/** 一次完成：表达式 → backendNodeId → 中心坐标。 */
+export async function locate(cdp, expression) {
+    const id = await backendNodeIdOf(cdp, expression);
+    if (id == null)
+        return null;
+    const center = await centerOfNode(cdp, id);
+    if (!center)
+        return null;
+    return { ...center, backendNodeId: id };
+}
+/** 带诊断的 locate：返回失败原因，便于定位是哪一层出问题。 */
+export async function locateVerbose(cdp, expression) {
+    const res = (await cdp
+        .send('Runtime.evaluate', { expression, returnByValue: false, userGesture: true })
+        .catch((e) => ({ err: e.message })));
+    if (!res || res.err)
+        return { reason: 'evaluate-failed: ' + (res?.err ?? '') };
+    if (res.exceptionDetails) {
+        return {
+            reason: 'evaluate-exception: ' +
+                String(res.exceptionDetails.exception?.description ?? res.exceptionDetails.text ?? '').slice(0, 160),
+        };
+    }
+    if (!res.result)
+        return { reason: 'no-result' };
+    if (!res.result.objectId) {
+        return {
+            reason: 'element-not-found (结果是 ' +
+                res.result.type +
+                ': ' +
+                String(res.result.value ?? res.result.description ?? '').slice(0, 60) +
+                ')',
+        };
+    }
+    const described = (await cdp.send('DOM.describeNode', { objectId: res.result.objectId }).catch((e) => ({
+        err: e.message,
+    })));
+    const backendNodeId = described?.node?.backendNodeId;
+    if (!backendNodeId)
+        return { reason: 'describe-failed: ' + (described?.err ?? 'no backendNodeId') };
+    await cdp.send('DOM.scrollIntoViewIfNeeded', { backendNodeId }).catch(() => { });
+    const boxed = (await cdp.send('DOM.getBoxModel', { backendNodeId }).catch((e) => ({ err: e.message })));
+    if (!boxed?.model)
+        return { reason: 'boxmodel-failed: ' + (boxed?.err ?? 'no model') };
+    const q = boxed.model.content;
+    const width = Math.hypot(q[2] - q[0], q[3] - q[1]);
+    const height = Math.hypot(q[4] - q[2], q[5] - q[3]);
+    if (width === 0 || height === 0)
+        return { reason: 'zero-size' };
+    return {
+        x: (q[0] + q[2] + q[4] + q[6]) / 4,
+        y: (q[1] + q[3] + q[5] + q[7]) / 4,
+        w: width,
+        h: height,
+        backendNodeId,
+    };
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,5 @@
+/** 命令行参数解析：手工解析，零依赖（内部工具，不需要 commander）。 */
+export declare function arg(name: string, fallback?: string): string | undefined;
+export declare const hasFlag: (name: string) => boolean;
+export declare const subcommand: string;
+export declare function stamp(): string;

package/dist/cli/args.js

@@ -0,0 +1,12 @@
+/** 命令行参数解析：手工解析，零依赖（内部工具，不需要 commander）。 */
+export function arg(name, fallback) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > -1 ? process.argv[i + 1] : fallback;
+}
+export const hasFlag = (name) => process.argv.includes(`--${name}`);
+export const subcommand = process.argv[2] ?? '';
+export function stamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+/** probe --doctor：开工前环境体检（CDP / 可见性 / 定时器节流 / 其它录制进程）。 */
+export declare function runDoctor(): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,67 @@
+/** probe --doctor：开工前环境体检（CDP / 可见性 / 定时器节流 / 其它录制进程）。 */
+import { execSync } from 'node:child_process';
+import { connect, evaluateTop } from "../cdp/client.js";
+import { arg } from "./args.js";
+export async function runDoctor() {
+    const cdpUrl = arg('cdp', 'http://127.0.0.1:9222');
+    const urlContains = arg('url-contains', process.env.EPOINT_URL_CONTAINS ?? '');
+    const lines = [];
+    let ok = true;
+    let others = '';
+    try {
+        others = execSync('pgrep -fl "cdp-recorder.*record" || true', { encoding: 'utf8' }).trim();
+    }
+    catch {
+        others = '';
+    }
+    if (others) {
+        ok = false;
+        lines.push(`✗ 有其他录制进程（会互相点对方的弹窗）：\n${others}`);
+    }
+    else {
+        lines.push('✓ 没有其它录制进程');
+    }
+    try {
+        const res = await fetch(`${cdpUrl}/json/version`);
+        const data = (await res.json());
+        lines.push(`✓ CDP 可达 ${cdpUrl}（${data.Browser ?? '未知版本'}）`);
+    }
+    catch (e) {
+        lines.push(`✗ CDP 不可达 ${cdpUrl}：${e.message}`);
+        console.log(lines.join('\n'));
+        process.exit(1);
+    }
+    const cdp = await connect(cdpUrl, { urlContains });
+    try {
+        const raw = await evaluateTop(cdp, `(() => JSON.stringify({ vis: document.visibilityState, focus: document.hasFocus(), url: location.href, frames: document.querySelectorAll('iframe').length }))()`);
+        const info = JSON.parse(String(raw));
+        if (info.vis === 'visible') {
+            lines.push('✓ visibilityState=visible');
+        }
+        else {
+            ok = false;
+            lines.push('✗ visibilityState=hidden（窗口被遮挡/锁屏）。CDP 点击仍然有效，但后台定时器会被节流：' +
+                '懒加载变 5~6s、保存后父窗口重渲染 2~3s，容易点空。' +
+                'Chrome 启动时加 --disable-background-timer-throttling --disable-renderer-backgrounding ' +
+                '--disable-backgrounding-occluded-windows --disable-features=CalculateNativeWinOcclusion 可解决。');
+        }
+        // 50ms × 500ms 正常应触发约 10 次；被节流时只有 1~2 次。
+        const ticks = Number(await evaluateTop(cdp, `new Promise((done) => { let n = 0; const id = setInterval(() => n++, 50); setTimeout(() => { clearInterval(id); done(n); }, 500); })`));
+        if (ticks >= 7) {
+            lines.push(`✓ 定时器未节流（50ms×500ms 触发 ${ticks} 次）`);
+        }
+        else {
+            ok = false;
+            lines.push(`✗ 定时器被节流（50ms×500ms 只触发 ${ticks} 次）`);
+        }
+        lines.push(`• 当前页面：${info.url}`);
+        lines.push(`• iframe 数：${info.frames}（--url-contains=${urlContains || '(空)'}）`);
+        lines.push(`• 页面焦点：${info.focus ? '有' : '无'}`);
+    }
+    finally {
+        cdp.close();
+    }
+    console.log(lines.join('\n'));
+    if (!ok)
+        process.exit(2);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CDP 录制工具入口。
+ *
+ *   epoint-cdp-recorder record --flow <path.mts> [--out <dir>] [--verbose]
+ *   epoint-cdp-recorder probe [--frames|--windows|--popups|--snapshot|--find|--required|--act|--doctor]
+ *
+ * 这里只做分发；各命令实现在 record.ts / probe/*.ts。
+ * 前置：Chrome 已用 --remote-debugging-port=9222 启动，窗口在前台，且已登录目标系统。
+ */
+export type { Recording } from '../recorder/recorder.ts';