codex-app-server/docs/platform-browser.md

# 平台浏览器：与 Muse browser 的对照

本轨目标：把编程任务平台的浏览器能力复刻到与 Muse browser
可对照的程度——只服务编程任务（验证自己的 Web 应用、读官方
文档、查包与 CVE），不复刻个人 agent 的通用上网能力。

范围边界先说清：

- 搜索（browser.search / browser.open / browser.find 那一路）
  由另一轨负责，本轨只消费、不重建。
- 多标签页已由本轨另一路完成：`browser_new_page` / `browser_list_pages` / `browser_switch_page` / `browser_close_page`，导航白名单见下文补充。
- 本轨不部署：filter 改动只落在仓库文件里，主机 tinyproxy
  未 reload；真实站点未 live 验证（见文末“未验证”一节）。

## 逐项对照

| 能力 | Muse browser | 本轨状态 |
| --- | --- | --- |
| Live Chromium（真浏览器，非文本抓取） | 有 | 已有：`cloud/playwright_browser.py`，单页 headless Chromium，1280x800 视口 |
| 导航 | 有 | 已有：`browser_navigate`；代理显式传 launch，域名不在白名单时报代理 403，不编造页面 |
| 快照（无障碍式清单） | 有 | 已有：`browser_snapshot`，及 `browser_snapshot_refs`（ref -> 元素清单，`browser_click_ref` 按 ref 点击） |
| 点击 / 填写 | 有 | 已有：`browser_click`、`browser_click_at`（坐标，有视口边界检查）、`browser_fill`、`browser_type_text` |
| 键盘 / 鼠标 | 有 | 已有：`browser_key_press`、`browser_mouse_move` |
| 截图 / 实时画面 | 有 | 已有：`browser_screenshot`、`browser_live_shot`（固定 live 文件 + JSON sidecar，供 console 轮询）；截图只写任务工作区（`cwd`，文件名 basename 校验），不写共享目录 |
| JS 求值 | 有 | 已有：`browser_evaluate` |
| MCP 工具面 | 有 | 已有：`cloud/playwright_mcp.py`，stdio MCP，14 个工具（navigate / snapshot / snapshot_refs / click / click_at / click_ref / fill / type_text / key_press / mouse_move / evaluate / screenshot / live_shot / close） |
| 观看 + 接管 | 有（观看与接管） | 已有：`BrowserPanel.tsx` 是观看 + 接管面板，不是纯观看面板；`holder` 驱动——用户接管（holder=user）时 agent 工具报错、把控制权交还用户，交还后 agent 续跑前先快照确认用户改动 |
| Worker 播种 | — | 已有：worker `--playwright-mcp` 把 MCP 文件与配置播种进租户 codex-home |
| 租户工作区隔离 | — | 已有：浏览器跑在任务沙箱内，截图与下载落任务工作区 |
| 代理 403 如实报错 | — | 已有：域名不在 Tinyproxy 白名单时工具 plain 报错 403，不静默失败、不编造内容 |
| 持久 profile / 跨回合登录态 | 有 | 缺口（本轨未做）：每次任务的浏览器是 fresh 会话，登录态不跨回合保留 |
| 登录凭证保险库 | 有 | 缺口 + 本轨不做：不存任何已存凭证；见“本轨不做” |
| 服务端审批卡片（表单提交 / 下载 / 上传的 Allow / Ask / Deny） | 有 | 缺口（本轨未做）：本轨只有 holder 接管阻塞（用户接管时 agent 工具报错停下），没有提交/下载/上传的审批流 |
| 验证码 / 机器人检查 | 有处理流程 | 缺口（本轨未做绕过）：被挡就报 blocked 停下，不绕过、不伪装 |
| 下载落盘清单 | 有 | 缺口（本轨未做）：除截图落任务工作区外，无统一的下载物清单面 |
| 多标签页 | 有 | 已有（本轨补）：`browser_new_page` / `browser_list_pages` / `browser_switch_page` / `browser_close_page`；新页自带全新 Playwright context，cookie/存储隔离 |
| 真实站点 live 验证 | 有 | 未做：本轨只改 egress 白名单与文档，未在主机 tinyproxy 上 reload、未对真实站点跑 live 验证 |

## 本轨不做（明确排除）

- 个人购物下单。
- 个人邮箱 / 社交登录。
- 验证码绕过、机器人检查绕过。
- 已存凭证保险库（任何真实密码、cookie、token 绝不写进
  代码、测试、文档、回执）。

## 本轨改动：egress 白名单

文件：`deploy/egress/tinyproxy-filter`（Tinyproxy POSIX BASIC
正则写法，一行一条，`^\(.*\.\)*域名$` 形式；不要用 extended
锚定写法，2026-10-26 已实测 extended 写法会把允许域名也挡成
403；文件保持 644 可读）。

本轨新增 10 条（编程来源限定）：

- `^\(.*\.\)*python\.org$`（含 docs.python.org 子域名规则覆盖）
- `^\(.*\.\)*nodejs\.org$`
- `^\(.*\.\)*go\.dev$`
- `^\(.*\.\)*pkg\.go\.dev$`
- `^\(.*\.\)*rust-lang\.org$`（含 docs.rust-lang.org）
- `^\(.*\.\)*developer\.mozilla\.org$`（只放行该 host，不放行
  mozilla.org 通配）
- `^\(.*\.\)*crates\.io$`
- `^\(.*\.\)*stackoverflow\.com$`
- `^\(.*\.\)*cve\.mitre\.org$`
- `^\(.*\.\)*nvd\.nist\.gov$`

已在白名单、无需重复加：`github.com`、`pypi.org`、`npmjs.org`
（另有 `pythonhosted.org` 供 pip）。

刻意不动：`^searx\.diante\.me$` 精确行不动；未加任何
`diante.me` 通配（那会放行 control plane api.diante.me）；
未加购物、社交、邮箱、通用新闻、视频站。

对应测试：`cloud/tests/test_websearch_worker.py` 的
`EgressFilterTestCase` 新增 2 项（见“验证”一节）——断言新规则
存在、已存在规则不重复、searx 精确行仍在且无 diante.me 通配、
以及用 BASIC 转 extended 后的实际匹配语义（子域名放行、
形似域名与后缀 trick 不放行、control plane 与购物/视频/邮箱
域名不放行）。

## 本轨补充：多标签页、导航白名单、关闭清理

- 多标签页：`browser_new_page`（开新页并切为当前页）、`browser_list_pages`（未启动时不启动、返回空列表）、`browser_switch_page`（按 index 切页，不存在时报明确错误、当前页不变、旧页 refs 清空）、`browser_close_page`（缺省关当前页，关后自动切上一页；关最后一页报错“use browser_close”）。现有单页方法全部作用于当前页、行为不变。
- 导航白名单：`BROWSER_ALLOWED_HOSTS`（逗号列表，前导点后缀匹配，大小写与端口不影响匹配）。未设置时行为不变；设置后在启动 Chromium 之前检查，未命中直接报错且不启动；`file://` 一律放行；`localhost/127.0.0.1` 无特殊待遇、须显式列出（本地开发服务器要自己加 localhost）。接线：worker 在容器启动前把 worker 环境里的 `BROWSER_ALLOWED_HOSTS`（已设置且非空时）写进租户 config 的 `[mcp_servers.playwright.env]`，MCP 进程由此拿到它；未设置时不写该键、白名单不生效（见未验证一节）。
- 页内跳转白名单（本轮补齐，上一轮的缺口已收窄、未归零）：`browser_click` / `browser_click_ref` 在目标是带 href 的链接时先解析 href（相对链接按当前页展开）再做同款检查，未命中报错且点击不执行；`click` / `click_ref` / `click_at` 在点击后都会检查落点 URL，落到 blocked host 时报错。已拦住的：navigate、带 href 的 click / click_ref（事前）。确实拦不住的（经代码确认，不硬编检查）：`click_at` 的事前检查（坐标对应不了元素，elementFromPoint 探针受视口/滚动影响、且漏掉 JS 驱动的跳转，故只做事后检查）；无 href 目标的点击（按钮、JS 处理函数，事前无目的地）；页内 JS 自行跳转（`location.href`、表单提交、SPA 路由、回车提交）、`browser_evaluate` 内的任意 JS、meta refresh、弹窗新页（`page.click` 不跟随新页）。这些路径的兜底只能是 Tinyproxy 代理 403：当白名单与代理白名单取同一域名集合时，被挡域名在代理层就加载失败；但 evaluate 与 shell 同权，白名单不是它的沙箱边界。测试：`cloud/tests/test_playwright_allowlist_click.py`（13 项，fake browser，不联网）：命中/未命中/后缀 trick（`notpython.org`、`python.org.evil.com`）/端口/大小写/file/localhost 正反例、事前拒点击不执行、事后落点报错、未设置时行为不变。
- 关闭清理：`browser_close()` 关掉全部页并尽力删除 cwd 下的 `browser-live.png` 与 `browser-live.json`（删失败不报错）；自定义文件名的截图文件不在清理范围内。

## 本轮补齐：老租户脚本安全升级

上一轮的播种器是“版本变化就刷新一切不同脚本”；本轮改为
安全升级（`cloud/playwright_browser.py` 的
`ensure_codex_home_playwright`，worker 播种时调用）：

- 自动合并（只对已证明未改动者）：播种 manifest
  （租户 codex-home 里的 `playwright_scripts_manifest.json`，
  播种器自己的元数据，不是租户数据）命中、或命中 2a569ac
  已发布三脚本的 SHA-256（`KNOWN_SHIPPED_SCRIPT_HASHES`，
  已对 origin/main blob 验过哈希）、或文件缺失（全新播种）、
  或已是最新（不写）。
- 绝不覆盖：内容已改动、且两项证明都不命中的脚本，原样
  不动、列入返回值的 `script_skipped_modified`（兼容旧字段
  `script_differs`）、在租户 codex-home 的
  `playwright_scripts_audit.jsonl` 里记一条
  `skipped_modified` 审计（脚本名、租户哈希、新版哈希），
  worker 同时打 warning 日志；留待人工处理。
- 幂等与防误判：重跑不重复写（已是最新不写、审计按
  脚本+租户哈希去重）；跳过时 manifest 绝不记录租户哈希
  ——否则下次升级会把改动过的脚本误判为“未改动”而覆盖
  （本轮修掉的正是这一处隐患，见测试
  `test_modified_rerun_does_not_rewrite_or_duplicate_audit`）。
- 升级不删除任何租户文件、不改租户已有配置语义：
  `[mcp_servers.playwright]` 只在缺失时追加，现有配置段
  原样保留；manifest 与审计文件只是播种器自己的附加元数据。
- 测试：`cloud/tests/test_playwright_upgrade.py`（8 项）：
  全新播种、未变脚本自动合并、已变脚本原样不动且有审计、
  幂等重跑不重复写、无 manifest 老租户（已知哈希合并 /
  未知哈希跳过）、租户数据与配置不受影响。

## 本轮补齐：BROWSER_ALLOWED_HOSTS 激活方案（本轮不执行主机激活）

候选值（域名集合 = 已部署的 Tinyproxy 编程域名集合，不编
新清单；编码用前导点形式，因为 filter 行本身就是子域名
包含式，见下文编码说明）：

```
BROWSER_ALLOWED_HOSTS=.python.org,.nodejs.org,.go.dev,.pkg.go.dev,.rust-lang.org,.developer.mozilla.org,.crates.io,.stackoverflow.com,.cve.mitre.org,.nvd.nist.gov,.github.com,.pypi.org,.npmjs.org
```

编码说明（关键，不可照抄纯域名版）：filter 行
`^\(.*\.\)*python\.org$` 放行 `python.org` 及其全部子域名，
而白名单的不带点条目 `python.org` 只精确匹配自身、不放行
`docs.python.org`；所以候选值必须用前导点条目，否则激活后
`docs.python.org` / `docs.rust-lang.org` 会被白名单挡掉、
相对代理白名单是回归（测试
`test_plain_entries_would_break_subdomains` 已证明这一点）。
出入说明：任务文本写的是 `npmjs.com`，但已部署 filter
（`deploy/egress/tinyproxy-filter:23`）、`deploy/new-host-checklist.md`
与本文档旧文均为 `npmjs.org`，候选值按已部署集合取
`npmjs.org`，`npmjs.com` 不在候选值内；如需放行 npm 官网
本身，那是另起的 filter 变更，不由本轮擅自决定。

测试租户/测试任务层面验证（本轮已做，全部 mock/fake，
未碰生产租户）：`cloud/tests/test_playwright_activation.py`
（7 项）：候选值域名集合与已部署 filter 一致；裸域名与子
域名放行、后缀 trick 与圈外域名拦截；file 放行、localhost
在候选值下被挡（见行为变更）；fake 任务级 navigate 放行与
拦截（拦截时不启动 Chromium）；未设置时行为不变。

对已有浏览器任务的行为变更：

- 未设置 `BROWSER_ALLOWED_HOSTS`：行为完全不变（只靠代理
  403），已有任务不受影响。
- 设置候选值后：navigate 与带 href 的 click / click_ref 在
  命中时不变、未命中时事前报错（navigate 不启动浏览器、
  click 不执行）；无 href 点击与 click_at 只在事后落点检查；
  file:// 一律放行；localhost / 127.0.0.1 被挡——本地开发
  服务器任务须在值里另加 `localhost`，否则会新报错，这是
  已知行为变更，不是 bug。
- JS 自行跳转等拦不住的路径：行为上只剩代理 403 兜底，
  与激活前一致（激活前也是代理 403）。

主机激活步骤（只交付步骤，本轮不执行）：

1. 在主机 worker/service 的环境里设置上述
   `BROWSER_ALLOWED_HOSTS`（与 worker 透传链路一致：worker
   环境变量 → 租户 config 的 `[mcp_servers.playwright.env]`，
   未设置时不写该键）。
2. 重启 worker 相关 unit（只重启、不改 unit 文件与 filter）。
3. 用一个测试任务验证：navigate 到 `docs.python.org` 成功、
   navigate 到圈外域名事前报错且不启动浏览器、click 圈外
   链接事前拒点、localhost 任务按预期被挡（或按需加
   `localhost` 后放行）。

回滚：清空该变量（从 worker 环境里删除
`BROWSER_ALLOWED_HOSTS` 并重启相关 unit），即回到未设置
行为——已有租户 config 里的旧 env 块由下次任务准备时的
`ensure_playwright_mcp_env` 覆盖（未设置时不写该键；注意：
已写入旧值的租户 config 需一次任务准备刷新后才彻底回到
未设置行为，见 worker 透传说明）。回滚不改 filter、不删
租户数据。

是否执行主机激活：本轮不执行。执行条件是本轮测试通过
（本轮测试已通过，见验证一节）且由 parent/用户拍板——
测试不通过时只交付方案与回滚、不强行激活；本轮测试通过
不等于主机已激活，主机激活仍待明确指令。

## 安全硬线

- 任何真实密码、cookie、token 绝不写进代码、测试、文档、回执。
- 浏览器只在任务沙箱与 egress 白名单内跑；白名单外域名一律
  代理 403，如实报错。
- 截图与下载落任务工作区，不写共享目录。

## 未验证（诚实边界）

- filter 未在主机 tinyproxy 上 reload（本轨不部署、不碰主机）。
- 真实站点未 live 验证：上述 10 条域名在主机生效后的实际
  可达性、以及浏览器在真实站点上的端到端回合，仍待部署后
  在有 egress 的环境里实测；本轨的测试只验证 filter 文件本身
  的语法与匹配语义，不冒充生产可用。