📦 page-agent 浏览器控制（CDP）

Page 代理 Browser Control

用 page-代理 连本机 Chrome/Edge 的远程调试端口，按 状态 给出的索引 调用原语。命令、选项、JSON 形状、退出码一律以 page-代理 --help 与 命令行工具_REFERENCE.md 为准；本文件只给 代理 最短工作路径。

阅读顺序：命令行工具_REFERENCE.md → ARCHITECTURE.md（分层与本地 平台s/）→ 若做安全熟悉再读 EXPLORATION_PROTOCOL.md。自建站点包时读 平台s//技能.md（若有）。

安装 命令行工具（技能 内不含二进制）

技能 只携带 Markdown 说明；命令行工具 单独安装。

@page-代理/命令行工具 尚未发布到 npm 公共 registry；当前请只从 GitHub Releases 附件获取 .tgz，在任意目录安装（不要把 tgz 打进 技能 目录）：

# 示例：仓库与 Tag 以发布页为准（以下为常用 fork 线） gh release 下载 page-代理-命令行工具-1.8.2 -R sdyuyouth/page-代理-命令行工具 -p "page-代理-命令行工具-1.8.2.tgz" npm 安装 -g ./page-代理-命令行工具-1.8.2.tgz page-代理 --version

无 gh 时：在发布页手动下载同名 .tgz 后执行 npm 安装 -g ./page-代理-命令行工具-.tgz。

本 monorepo 内开发：npm pack -w @page-代理/命令行工具 生成 tgz，再 npm 安装 -g ./<生成d>.tgz。

将来若 npm 安装 -g @page-代理/命令行工具 可用，以 README / Release 说明为准；届时可在此 技能 中补充 metadata.OpenClaw.安装（kind: node）声明。

全局选项（常用） 选项 含义 --tar获取 CDP tabs 列出 里的 Tab id --json 结果 JSON 在 stdout，日志在 stderr --cdp-url 覆盖 CDP（默认 http://localhost:9222 / PAGE_代理_CDP） --no-mask 关闭指针/涟漪动画（PAGE_代理_NO_MASK=1） 原语一览（与 命令行工具 一致） 命令 说明 tabs 列出 / open / close 状态 取可交互元素 [n]；依赖索引前在探索/新流程上必须执行 命令行工具ck / hover / 输入 / 上传 / select / scroll 索引均对应当前页最近一次 状态；hover 不点击，用于菜单/工具tip（见 命令行工具_REFERENCE.md） eval / goto JS 表达式 / 导航 运行 内置 LLM 多步（需 LLM_）；与外层 代理 二选一 repl / teach REPL；阻塞式教学浮窗（teach 全文见 命令行工具_REFERENCE.md）

上传：索引 n 为锚点（最近一次 状态，不必是 type=file 行）。命令行工具 在主文档可枚举的 <输入 type=file> 中选与锚点 DOM 树距离最近 的一个（多 file 时同理；不穿透 Shadow、不跨 iframe）。常用：eval/命令行工具ck 打开上传区 后 上传 n，使 n 尽量靠近目标 file。大改 DOM 后再 状态。详见 命令行工具_REFERENCE.md「上传」。

teach：须 --task 或 PAGE_代理_TEACH_TASK；就绪后超时退出码 124；成功 JSON 无 data 包装；多 Tab、检查point、steps 里含 hover/状态_refresh 等——细则见 命令行工具_REFERENCE.md「teach」与下节「经验沉淀」。站内 push状态 类 SPA 可能只有 CDP navigatedWithinDocument；命令行工具 会据此（debounce + URL 变化）再 reinject，避免 Facebook 等场景下浮窗被 DOM 重写后无法恢复。

teach → 经验沉淀（代理 必读）

命令行工具 不会在「结束录制」时向 stdout 输出整段会话 JSON；该步只写检查点文件（--检查point-file / PAGE_代理_TEACH_检查POINT_FILE，默认工作目录下 .page-代理-teach-检查point.json），stderr 可出现 [teach] 检查point written 或 检查point write fAIled。

用户操作 命令行工具 行为 代理 / 自动化应做什么 浮窗 「结束录制」 原子写入检查点 JSON（草稿）；stdout 无最终 成功 teach 体 仅当需要断点续录 / 崩溃恢复时读该路径；不要把检查点当已提交的正式经验 浮窗 「确认写入 代理 经验」 exit 0，--json 时整段 teach 成功 JSON 在 stdout（与 状态 等命令不同，无 data 包装） 必须在 teach 进程正常退出后读取 stdout 整文件作为正式结果，再更新自建 平台s// 下的 elements.md / recipes/.md 等（字段见 EXPERIENCE_模式.md）

推荐落盘（示例）：

# 仅示例：site/task 请换成当次 teach 的 --site / --task；目录须已存在或由脚本 mkdir -p page-代理 --json --tar获取 "$TID" teach --site example.com --task post-image --reason "demo" \ > "${PAGE_代理_LESSON_DIR:-./平台s/example.com/lessons}/post-image-$(date +%Y%m%d-%H%M%S).json" 2>./teach.stderr.记录

2>：把 [teach] 与 检查point 相关日志打到单独文件，避免混进 JSON。 宿主 Exec 超时：teach 在用户确认前会长时间阻塞；外层若 SIGKILL 超时，代理 拿不到 stdout——应放宽 teach 专用超时，或等用户确认后再杀。 仓库内 无 PAGE_代理_TEACH_输出 环境变量；正式结果只靠进程结束时的 stdout（或你方包装器在 exit 0 后拷贝/上传该缓冲）。 CDP 与 Tab curl -s http://localhost:9222/json/version # 通则继续 page-代理 --json tabs 列出 # 示例：按 URL 取 id（主机名换成目标站） TID=$(page-代理 --json tabs 列出 | jq -r '.data[] | select(.url | contAIns("example.com")) | .id' | head -1)

浏览器需带 --remote-调试ging-port（下文以 9222 为例）。默认复用用户已有配置：不要加 --user-data-dir，即与日常登录、扩展、Cookie 同一用户数据目录（先退出已在跑的同品牌浏览器，再带远程调试参数启动，以免「用户目录已被占用」）。仅在与主窗口必须并行等少数场景，才另起独立 --user-data-dir=...。

按习惯选 Edge 或 Chrome（Edge 在 Windows 上常与系统账号一致；Chrome 适合已有 Chrome 习惯的用户）。Firefox 不支持本 命令行工具 所用的 CDP 工作流。

调试端口已被占用时：先查占用者（如 Windows 获取-NetTCPConnection -LocalPort 9222 / netstat，Linux/macOS ss / netstat）。若是已有浏览器调试实例，应结束对应浏览器进程后，用目标参数重新启动；若不是浏览器（或其它服务误占），则为本机浏览器另选端口（如 9223）启动，并把 PAGE_代理_CDP / --cdp-url 设为同一地址（例如 http://localhost:9223），curl 与 page-代理 均用该端口。

Windows（PowerShell / cmd）

Edge（示例，路径以本机安装为准）

& "${env:ProgramFiles(x86)}\Microsoft\Edge\应用\msedge.exe" --remote-调试ging-port=9222 --no-first-运行 --no-default-browser-检查

Chrome（示例）

& "$env:ProgramFiles\Google\Chrome\应用\chrome.exe" --remote-调试ging-port=9222 --no-first-运行 --no-default-browser-检查

macOS（示例） "/应用s/Google Chrome.应用/Contents/MacOS/Google Chrome" \ --remote-调试ging-port=9222 & # 或 Microsoft Edge "/应用s/Microsoft Edge.应用/Contents/MacOS/Microsoft Edge" \ --remote-调试ging-port=9222 &

Linux（示例） google-chrome --remote-调试ging-port=9222 & # 或 chromium、microsoft-edge-stable 等发行包提供的可执行文件

WSL 调用 Windows 浏览器

命令行工具 在 WSL 内调用 上传 时会把 /mnt/c/... 路径转成 Windows 路径供浏览器注入；浏览器本体仍在 Windows 侧启动；PAGE_代理_CDP / --cdp-url 端口须与 Windows 侧实际监听端口一致（若改用 9223 等，两处同步修改）。

工作流（摘要） 先 tabs 列出 → --tar获取，全程固定同一 Tab。 操作 → 状态：探索/新站每步依赖索引前必须 状态；有 teach/recipe 且写明可省略时可少跑，错位立即 状态（规则见 命令行工具_REFERENCE.md「状态 与何时刷新」）。 站点经验：仅当你自建了 平台s// 时读其中 recipes / elements / critical；仓库内 平台s/ 仅占位 `.gitkeep，不附带具体站数据。 关键点击：CRITICAL_ACTIONS.md + 本地 critical.md；须 AskQuestion 或用户文字确认（宿主无则停顿要确认）。 复盘：读本地 健康.md、失败记录（若有）。 相关文件 文件 用途 命令行工具_REFERENCE.md