# FoxPaw 接入说明（给 Agent）

你被一位浏览器主人邀请，接入 FoxPaw — 借用主人已登录的 Chrome 操作其授权标签。
本文件是机器可读说明书：照此自助接入，不需要任何安装包。

## 1. 领取令牌（邀请链接 → 令牌，Agent 唯一的登录方式）
主人给你的邀请链接形如 https://foxpaw-43-161-229-43.sslip.io/app/claim?invite=<邀请码>，取出邀请码后：
POST https://foxpaw-43-161-229-43.sslip.io/auth/agent/claim  JSON: {"invite": "<邀请码>", "label": "<你在主人面板上显示的名字>"}
成功返回: {"kind":"agent","token":"<你的令牌>","mcp":"https://foxpaw-43-161-229-43.sslip.io/mcp"}
令牌只显示这一次（中继只存它的哈希），请妥善保存。旧地址 POST https://foxpaw-43-161-229-43.sslip.io/claim/api 在中继 3.0 仍可用一个版本（回包带 deprecated 提示）。

## 2. 接入：MCP（唯一推荐接口）
把 https://foxpaw-43-161-229-43.sslip.io/mcp 加为你的 MCP 服务器（Streamable HTTP，POST JSON-RPC），请求头
Authorization: Bearer <token>。工具（tools/list 有完整参数）：
- foxpaw_whoami：我是谁、权限、可用设备与授权标签、写锁占用。先调它。
- foxpaw_tabs：可用标签。assigned=FoxPaw 组内可操作的标签；只有主人给你开了「可见全部标签」时，
  才多一个 outside：组外标签 [{id, title, url, readonly:true}]（只读：只有标题和网址，不能快照、不能操作），
  all = assigned + outside；没开时没有 outside 字段。events 里是 tab_opened 通知
  （你持有写锁的页面开了新标签/弹窗：{tabId, openerTabId, url}；新标签已自动入组，你是唯一写锁持有者时它的写锁归你）。
- foxpaw_snapshot：页面快照，交互元素带 ref 和 role/name。插件 ≥1.16：ref 在同一文档内稳定
  （e12；iframe 里是 f5e12，含跨站 iframe 与开放 shadow DOM），页面跳转后失效（STALE_REF）；旧插件是 s3_12，到下次快照前有效。
- foxpaw_navigate：插件 ≥1.16 默认等页面 load 再返回（waitUntil:"none" 立即返回，timeout 毫秒）。
- foxpaw_click：真鼠标点击，动作前自动等元素可见/可用/稳定/不被遮挡（默认 5 秒，timeout 可改；被挡回 OBSCURED），
  点了真跳转才等加载，回包可带 navigated/load/epoch 与 opened（新开的标签）。定位任选其一：
  ref > role+name（如 button / "登录"）> label > text > selector；多个匹配回 AMBIGUOUS 并给候选 ref，用 nth（从 0 起）挑；
  exact:true 精确匹配名字。带上快照的 epoch，页面变了会回 STALE_DOCUMENT。role/name 等定位需要插件 ≥1.16。
- foxpaw_fill：真填（dryRun 默认 false）。fields 是数组，每项 {定位, value, kind?}，定位任选其一：
  ref（最快最准，来自最新快照）> role+name（如 textbox / "邮箱"）> label（可见标签文字）>
  text（占位符/附近文字）> selector（CSS，最后手段）。kind 可省（自动识别，含 React/Ant 下拉与日期）：
  text|select|combobox|checkbox|radio|date|contenteditable|file|slider。
  回包 {ok, fields:[{ok, actual, error?}]}，以 actual 为准核对。
- foxpaw_login（中继 ≥3.6 + 扩展 ≥1.26）：用主人存在 FoxPaw 里的登录凭证登录 {tabId, site?, user?, submit?}。
  你看不到密码：扩展在主人浏览器里找到账号 / 密码框填入（回读 •••）并点登录。site 是主域（含子域），只会填在该站；
  哪些站有凭证看 foxpaw_whoami 的 devices[].logins（站点 + 账号，没有密码），或不带 tabId 调本工具。
  主人信任你（该站 / 全部网站 / 这次都放行）时直接执行，否则主人点一次审批卡。付款页、支付密码框永远不填。
- foxpaw_login_save：你替主人注册了账号后，把站点 + 账号 + 密码存进主人的 FoxPaw（只加密存在主人浏览器，中继不留；
  回包密码是 •••，之后也读不回来，用 foxpaw_login 登录）。
- foxpaw_wait_for：等条件成立再继续：text（文字出现）/ textGone（文字消失）/ selector（CSS，state:
  attached|detached|visible|hidden）/ urlIncludes / role+name / label（state:"hidden" 等消失）；默认 10 秒，最长 30 秒，
  成功时带回最新快照（用它的 ref；snapshot:false 不带）。插件 ≥1.16 时 text/textGone/selector/urlIncludes 在浏览器里等
  （回包 via:"extension"），role+name/label 与旧插件由中继轮询快照（via:"relay-poll"；selector 需要 ≥1.16）。
- foxpaw_need_human：卡在登录/验证码/二次确认等只有主人能做的事时举手等回执。
- foxpaw_open_tab / foxpaw_close_tab / foxpaw_activate_tab：开/关/切 FoxPaw 组内标签（新开的标签自动入组）。
- foxpaw_find_tabs：请主人把一个已打开的标签拉进组（主人确认卡）。
- foxpaw_request_elevation：临时提权申请。
- foxpaw_list_tasks / foxpaw_task_accept / foxpaw_task_progress / foxpaw_task_result：云端任务（先接单、可报进度、再交结果）。
- foxpaw_cdp / foxpaw_cdp_endpoint：原始模式（见下）。
- foxpaw_recording_start(tabId, goal) / foxpaw_recording_stop(name?)：「教 FoxPaw」——你照常操作，每一步都被录下
  （一台浏览器同时只有一个录制；遇登录会暂停、请主人登录，登录不进步骤）；结束生成草稿（来源 Agent 录制）。
- foxpaw_flow_draft_submit(flow, name?, note?)：把一次代跑整理成草稿流程（来源 Agent 代跑）；草稿不能带凭据明文。
- foxpaw_flow_list：已生效的流程 + 你自己提交的草稿状态（草稿 / 已生效 / 已驳回）。草稿只有主人能收下；
  你不能改已生效的流程，只能再提交新草稿。
- foxpaw_flow_run(recordingId | flow, tabId, vars?, onFail?)：回放流程。中继 3.4 + 扩展 1.21 起每次回放都有运行记录（回包带 run_id，
  主人能在控制台实时看逐步进度和截图）；某步失败默认**暂停**而不是报错（onFail:'fail' = 直接失败）：回包 paused:true +
  pause{at, label, kind, code, reason} + actions + next。付款 / 授权 / 秘密字段同样停在那一步等主人。
- foxpaw_run(run_id?, action?, screenshot?)：查运行状态（当前步、每步状态、暂停原因、截图）；对暂停的运行
  continue（这步已有人手动做完）/ retry（重做这步）/ skip（跳过这步）/ abort（终止）。主人可能已在控制台或侧栏处理过，以回包状态为准。
- 所有工具都可带 task（你当前任务的简短标识）：主人批准时可以给「本任务 5 分钟内同类操作不再问」，按任务生效。

原始 CDP（foxpaw_cdp，或 foxpaw_cdp_endpoint 给 Playwright connectOverCDP）是单独授权的「原始模式」：
主人在控制台给你打开后才可用，否则回 RAW_CDP_NOT_GRANTED（HTTP 403）。同样受下面的规矩约束。

命令行（可选）：仓库里的 agent/foxpaw.js 是 MCP 薄客户端，FOXPAW_URL=<中继地址> FOXPAW_AGENT_TOKEN=<令牌>
node foxpaw.js tabs | snapshot <tabId> | click <tabId> <ref> | ...（每条命令就是一次 MCP tools/call）。

## 3. 旧 WebSocket Agent 协议（弃用，原定中继 3.1 删除，推迟到 3.5）
ws 地址 wss://foxpaw-43-161-229-43.sslip.io/agent 的自定义协议在中继 3.0 仍兼容一个版本（auth.ok 帧里带 deprecated 提示），不再增加任何能力。
请改用上面的 MCP；迁移对照见 https://foxpaw-43-161-229-43.sslip.io/docs/migration-3.0。

## 4. 规矩
- 只能操作主人拖进 FoxPaw 组的标签；付款/授权与密码、验证码、卡号等秘密字段永远由主人亲自完成（回 USER_STEP，
  请用 foxpaw_need_human 举手）；删除/提交等会弹卡等主人批准，被拒就停。原始 CDP（含 Playwright）同样受这些规则约束。
- 等主人批准的命令最多等约 1 分钟；超时回 EXT_TIMEOUT / CONFIRM_TIMEOUT 时该命令已作废、绝不会事后补执行，可重新发起。
- 「只看」权限下读不到 Cookie / 本地存储等会话数据。
- 一个标签同一时刻只有一个写作者（租约锁）：写命令若回 TAB_LEASED，先只读观察或换个标签。
- 先调 foxpaw_whoami 看设备与占用，再动手。

## 5. 多台设备（device 参数）
主人可能有好几台浏览器（如「公司电脑」「家里 Mac」）。每个工具都可带 device（设备 id 如 d2，或设备名）：
- 你能用的设备只有一台时，不带 device 就用它。
- 能用的设备有多台时，第一次请带 device 指定；之后不带 device 的调用都落在你**上次指定**的那台。
- 上次指定的那台离线了，回 DEVICE_OFFLINE（附在线设备列表），**不会**自动改用另一台；请明确带 device。
- 没指定过、又有多台可用时回 DEVICE_REQUIRED（附在线设备列表）；两台以上同时在线时回 DEVICE_AMBIGUOUS。
- foxpaw_whoami 列出你能用的设备和在线状态。