page-agent 浏览器控制（CDP）

SKILL.md

---
name: page-agent-browser
description: 通过 page-agent CLI（CDP）驱动浏览器；CLI 当前仅从 GitHub Release 的 .tgz 安装（npm 官方包尚未发布）。
version: 1.0.0
allowed-tools: "Bash(page-agent:*), Bash(curl:*), Exec(tools:process:kill)"
metadata:
  openclaw:
    homepage: https://github.com/sdyuyouth/page-agent-cli/releases
    requires:
      anyBins:
        - page-agent
        - page-agent-cli
---

# Page Agent Browser Control

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

**阅读顺序**：`CLI_REFERENCE.md` → `ARCHITECTURE.md`（分层与本地 `platforms/`）→ 若做安全熟悉再读 `EXPLORATION_PROTOCOL.md`。自建站点包时读 `platforms/<site>/SKILL.md`（若有）。

---

## 安装 CLI（skill 内不含二进制）

Skill 只携带 Markdown 说明；**CLI 单独安装**。

**`@page-agent/cli` 尚未发布到 npm 公共 registry**；当前请**只从 GitHub Releases 附件**获取 `.tgz`，在**任意目录**安装（不要把 tgz 打进 skill 目录）：

```bash
# 示例：仓库与 Tag 以发布页为准（以下为常用 fork 线）
gh release download page-agent-cli-1.8.2 -R sdyuyouth/page-agent-cli -p "page-agent-cli-1.8.2.tgz"
npm install -g ./page-agent-cli-1.8.2.tgz
page-agent --version
```

无 `gh` 时：在发布页手动下载同名 `.tgz` 后执行 `npm install -g ./page-agent-cli-<version>.tgz`。

本 monorepo 内开发：`npm pack -w @page-agent/cli` 生成 tgz，再 `npm install -g ./<generated>.tgz`。

将来若 **`npm install -g @page-agent/cli`** 可用，以 README / Release 说明为准；届时可在此 skill 中补充 `metadata.openclaw.install`（`kind: node`）声明。

---

## 全局选项（常用）

| 选项 | 含义 |
|------|------|
| `--target <id>` | CDP `tabs list` 里的 Tab id |
| `--json` | 结果 JSON 在 stdout，日志在 stderr |
| `--cdp-url` | 覆盖 CDP（默认 `http://localhost:9222` / `PAGE_AGENT_CDP`） |
| `--no-mask` | 关闭指针/涟漪动画（`PAGE_AGENT_NO_MASK=1`） |

---

## 原语一览（与 CLI 一致）

| 命令 | 说明 |
|------|------|
| `tabs` | `list` / `open` / `close` |
| `state` | 取可交互元素 `[n]`；**依赖索引前**在探索/新流程上必须执行 |
| `click` / **`hover`** / `input` / `upload` / `select` / `scroll` | 索引均对应当前页**最近一次** `state`；`hover` 不点击，用于菜单/tooltip（见 `CLI_REFERENCE.md`） |
| `eval` / `goto` | JS 表达式 / 导航 |
| `run` | 内置 LLM 多步（需 `LLM_*`）；与外层 Agent 二选一 |
| `repl` / `teach` | REPL；阻塞式教学浮窗（**`teach` 全文见 `CLI_REFERENCE.md`**） |

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

**`teach`**：须 `--task` 或 `PAGE_AGENT_TEACH_TASK`；就绪后超时退出码 **124**；成功 JSON **无** `data` 包装；多 Tab、checkpoint、`steps` 里含 `hover`/`state_refresh` 等——细则见 **`CLI_REFERENCE.md`「teach」**与下节「**经验沉淀**」。站内 **pushState** 类 SPA 可能只有 CDP **`navigatedWithinDocument`**；CLI 会据此（debounce + URL 变化）再 reinject，避免 Facebook 等场景下浮窗被 DOM 重写后无法恢复。

---

## `teach` → 经验沉淀（Agent 必读）

CLI **不会**在「结束录制」时向 **stdout** 输出整段会话 JSON；该步只写**检查点文件**（`--checkpoint-file` / `PAGE_AGENT_TEACH_CHECKPOINT_FILE`，默认工作目录下 `.page-agent-teach-checkpoint.json`），stderr 可出现 **`[teach] checkpoint written`** 或 **`checkpoint write failed`**。

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

**推荐落盘（示例）**：

```bash
# 仅示例：site/task 请换成当次 teach 的 --site / --task；目录须已存在或由脚本 mkdir -p
page-agent --json --target "$TID" teach --site example.com --task post-image --reason "demo" \
  > "${PAGE_AGENT_LESSON_DIR:-./platforms/example.com/lessons}/post-image-$(date +%Y%m%d-%H%M%S).json" 2>./teach.stderr.log
```

- **`2>`**：把 **`[teach]`** 与 checkpoint 相关日志打到单独文件，**避免**混进 JSON。  
- **宿主 Exec 超时**：`teach` 在用户确认前会长时间阻塞；外层若 **SIGKILL** 超时，Agent **拿不到 stdout**——应放宽 teach 专用超时，或等用户确认后再杀。  
- 仓库内 **无** `PAGE_AGENT_TEACH_OUTPUT` 环境变量；正式结果**只靠进程结束时的 stdout**（或你方包装器在 exit 0 后拷贝/上传该缓冲）。

---

## CDP 与 Tab

```bash
curl -s http://localhost:9222/json/version   # 通则继续
page-agent --json tabs list
# 示例：按 URL 取 id（主机名换成目标站）
TID=$(page-agent --json tabs list | jq -r '.data[] | select(.url | contains("example.com")) | .id' | head -1)
```

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

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

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

### Windows（PowerShell / cmd）

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

```powershell
& "${env:ProgramFiles(x86)}\Microsoft\Edge\Application\msedge.exe" `
  --remote-debugging-port=9222 --no-first-run --no-default-browser-check
```

**Chrome（示例）**

```powershell
& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 --no-first-run --no-default-browser-check
```

### macOS（示例）

```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 &
# 或 Microsoft Edge
"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" \
  --remote-debugging-port=9222 &
```

### Linux（示例）

```bash
google-chrome --remote-debugging-port=9222 &
# 或 chromium、microsoft-edge-stable 等发行包提供的可执行文件
```

### WSL 调用 Windows 浏览器

CLI 在 WSL 内调用 **`upload`** 时会把 **`/mnt/c/...`** 路径转成 Windows 路径供浏览器注入；浏览器本体仍在 **Windows** 侧启动；**`PAGE_AGENT_CDP` / `--cdp-url` 端口须与 Windows 侧实际监听端口一致**（若改用 9223 等，两处同步修改）。

---

## 工作流（摘要）

1. **先 `tabs list` → `--target`**，全程固定同一 Tab。  
2. **操作 → `state`**：探索/新站**每步依赖索引前**必须 `state`；有 teach/recipe 且写明可省略时可少跑，错位立即 `state`（规则见 `CLI_REFERENCE.md`「state 与何时刷新」）。  
3. **站点经验**：仅当你自建了 `platforms/<site>/` 时读其中 `recipes` / `elements` / `critical`；**仓库内 `platforms/` 仅占位 `.gitkeep**，不附带具体站数据。  
4. **关键点击**：`CRITICAL_ACTIONS.md` + 本地 `critical.md`；须 **`AskQuestion` 或用户文字确认**（宿主无则停顿要确认）。  
5. **复盘**：读本地 `health.md`、失败记录（若有）。

---

## 相关文件

| 文件 | 用途 |
|------|------|
| `CLI_REFERENCE.md` | **权威**：子命令、`teach`/`upload`/`hover`、环境变量、退出码 |
| `ARCHITECTURE.md` | 分层、复用、探索与权限 |
| `EXPERIENCE_SCHEMA.md` | 经验 Markdown 字段约定 |
| `CRITICAL_ACTIONS.md` | 全局 critical 关键词与策略 |
| `EXPLORATION_PROTOCOL.md` | active-safe 探索边界 |