Epic: Pane 对称性 — 同页战役不必翻 headless(network / dialog / PDF) #12

已关闭
由 fourbroad 于 2026-10-26 21:13:41 +08:00创建 · 2 评论
所有者

北极星验收

用户看得见的那一页(desktop pane)上跑战役时,为了查请求清单、处理 confirm/prompt(含 accept)、或导出 PDF,不得被迫切到 isolated-headless。

PDF 若短期做不到双腿,必须工具面显式披露「仅 headless」并提供一键换面路径——不得静默成功在另一张看不见的页上。与 #5817 纪律一致:bound + pane 不可达时写路由结构化阻断,绝不静默落 headless。

可回看的 Epic Page:Pane 对称性 Epic:同页战役不必翻 headless

锚点:octopus main @ cadbbbb56


背景

内置浏览器是双后端:有桌面绑定时优先同页 pane(Electron webview + CDP),否则 headless-driver.ts(内嵌 Playwright Chromium)。对齐目标是 @playwright/mcp 工具面(browser-tools-parity-ledger.md),不是完整 Playwright Test API。

叶表 HEADLESS_ONLY_BROWSER_TOOL_IDS(packages/octopus/src/tool/browser-ids.ts)当前含:browser_pdf_save、browser_handle_dialog、browser_network_requests、browser_network_request、browser_highlight、browser_generate_locator。本 epic 只收前四项中与同页战役直接相关的 network / dialog / PDF;highlight / generate_locator 不绑。


目标

  • P0 三件套上 pane 腿(或 PDF 的披露+一键换面等价物),sticky-bound 同页战役不必为这三件事翻面
  • 更新 parity ledger / tool-surface / HEADLESS_ONLY 叶表与 registry lock,零漂移
  • capabilities 与失败文案可行动
  • 遵守 act 门与 fence:写类 dialog 走 confirm/grant;读类 network/PDF 不升级为静默写

非目标

  • E-7 窄面:mouse-xy、verify_*、check/uncheck、video、cookie/localStorage CRUD 细 API
  • E-4 browser_drop;E-6 browser_run_code_unsafe
  • 编程级任意 newContext、完整 device catalog
  • browser_highlight / browser_generate_locator pane 腿
  • browser_tabs action=new 恒 headless
  • 登录态细 API、#6036 人机换手、#6040 自愈定位(另票)

P0 范围

能力 现状 目标 验收
browser_network_requests / _request HEADLESS_ONLY;pane 仅 console network method 环 dual:1-based 清单 + index 详情 bound 同页 list/detail 成功
browser_handle_dialog HEADLESS_ONLY;pane 终身 auto-dismiss dual:可配置 + 对称 accept/dismiss(含 promptText) confirm/prompt 可在同页显式接受
browser_pdf_save HEADLESS_ONLY;page.pdf() 优先 A 双腿(CDP/Electron printToPDF);否则 B 披露+一键换面 同页导出成功,或明确仅 headless 且换面可点通

P0-a Network

扩展既有 guest-network-cdp.ts(#5902 / #5826)采集 → browser_network_* 去 headlessOnly。CDP attach 失败结构化拒绝,不静默空列表。

P0-b Dialog

guest-dialog.ts 策略 + pending/handle;禁止 guard 与 handle 双答。默认仍 auto-dismiss;accept 必经 act 门。

P0-c PDF

推荐先 spike A;不可行再退 B。禁止 bound+pane-live 时静默在 headless 生成「看起来成功」的 PDF。


建议拆 PR

  1. PR0 · Epic 契约冻结(ledger / tool-surface 里程碑行;PDF 标推荐 A、保留 B)
  2. PR1 · Network pane 腿(可与 PR2 并行)
  3. PR2 · Dialog pane 腿(可与 PR1 并行)
  4. PR3 · PDF spike → A 或 B
  5. PR4 · 收口(capabilities、SKILL、ledger 勾双腿、#5817 相关 e2e)

验收清单

  • bound 同页战役 network 清单不必翻 headless
  • bound 同页 confirm/prompt 可显式 accept
  • PDF 双腿或披露+一键换面(无静默错页)
  • HEADLESS_ONLY 叶表与 defineActTool / registry lock 一致
  • parity ledger + tool-surface 主表行已更新
  • CDP attach 失败 / 无对话框 / 路径逃逸均为结构化错误
  • #5817:不因 PDF/network/dialog 引入静默 headless 写路由
  • 非目标未膨胀进本 epic

证据锚点

  • packages/octopus/contracts/browser-tools-parity-ledger.md
  • packages/octopus/contracts/browser-tool-surface-v1.md
  • packages/octopus/contracts/browser-act-surface-v1.md
  • packages/octopus/src/tool/browser-ids.ts
  • packages/desktop/src/main/guest-dialog.ts
  • packages/desktop/src/main/guest-network-cdp.ts
  • packages/octopus/src/browser/headless-driver.ts
## 北极星验收 用户看得见的那一页(desktop pane)上跑战役时,为了查请求清单、处理 confirm/prompt(含 accept)、或导出 PDF,**不得被迫切到 isolated-headless**。 PDF 若短期做不到双腿,必须工具面显式披露「仅 headless」并提供一键换面路径——不得静默成功在另一张看不见的页上。与 **#5817** 纪律一致:bound + pane 不可达时写路由结构化阻断,绝不静默落 headless。 可回看的 Epic Page:[Pane 对称性 Epic:同页战役不必翻 headless](https://cursor.com/canvas/store-4f9f1907-ae97-49af-8174-93162628478f/e067b9fd-9167-4c33-96b3-ffdaaf798fcf) 锚点:`octopus` main `@ cadbbbb56` --- ## 背景 内置浏览器是双后端:有桌面绑定时优先同页 pane(Electron webview + CDP),否则 `headless-driver.ts`(内嵌 Playwright Chromium)。对齐目标是 `@playwright/mcp` 工具面(`browser-tools-parity-ledger.md`),不是完整 Playwright Test API。 叶表 `HEADLESS_ONLY_BROWSER_TOOL_IDS`(`packages/octopus/src/tool/browser-ids.ts`)当前含:`browser_pdf_save`、`browser_handle_dialog`、`browser_network_requests`、`browser_network_request`、`browser_highlight`、`browser_generate_locator`。本 epic 只收前四项中与同页战役直接相关的 **network / dialog / PDF**;highlight / generate_locator 不绑。 --- ## 目标 - P0 三件套上 pane 腿(或 PDF 的披露+一键换面等价物),sticky-bound 同页战役不必为这三件事翻面 - 更新 parity ledger / tool-surface / `HEADLESS_ONLY` 叶表与 registry lock,零漂移 - capabilities 与失败文案可行动 - 遵守 act 门与 fence:写类 dialog 走 confirm/grant;读类 network/PDF 不升级为静默写 ## 非目标 - E-7 窄面:mouse-xy、verify_*、check/uncheck、video、cookie/localStorage CRUD 细 API - E-4 `browser_drop`;E-6 `browser_run_code_unsafe` - 编程级任意 `newContext`、完整 device catalog - `browser_highlight` / `browser_generate_locator` pane 腿 - `browser_tabs` action=new 恒 headless - 登录态细 API、#6036 人机换手、#6040 自愈定位(另票) --- ## P0 范围 | 能力 | 现状 | 目标 | 验收 | | --- | --- | --- | --- | | `browser_network_requests` / `_request` | HEADLESS_ONLY;pane 仅 console network method 环 | dual:1-based 清单 + index 详情 | bound 同页 list/detail 成功 | | `browser_handle_dialog` | HEADLESS_ONLY;pane 终身 auto-dismiss | dual:可配置 + 对称 accept/dismiss(含 promptText) | confirm/prompt 可在同页显式接受 | | `browser_pdf_save` | HEADLESS_ONLY;`page.pdf()` | **优先 A 双腿**(CDP/Electron printToPDF);否则 **B 披露+一键换面** | 同页导出成功,或明确仅 headless 且换面可点通 | ### P0-a Network 扩展既有 `guest-network-cdp.ts`(#5902 / #5826)采集 → `browser_network_*` 去 headlessOnly。CDP attach 失败结构化拒绝,不静默空列表。 ### P0-b Dialog `guest-dialog.ts` 策略 + pending/handle;禁止 guard 与 handle 双答。默认仍 auto-dismiss;accept 必经 act 门。 ### P0-c PDF 推荐先 **spike A**;不可行再退 **B**。禁止 bound+pane-live 时静默在 headless 生成「看起来成功」的 PDF。 --- ## 建议拆 PR 1. **PR0** · Epic 契约冻结(ledger / tool-surface 里程碑行;PDF 标推荐 A、保留 B) 2. **PR1** · Network pane 腿(可与 PR2 并行) 3. **PR2** · Dialog pane 腿(可与 PR1 并行) 4. **PR3** · PDF spike → A 或 B 5. **PR4** · 收口(capabilities、SKILL、ledger 勾双腿、#5817 相关 e2e) --- ## 验收清单 - [ ] bound 同页战役 network 清单不必翻 headless - [ ] bound 同页 confirm/prompt 可显式 accept - [ ] PDF 双腿或披露+一键换面(无静默错页) - [ ] `HEADLESS_ONLY` 叶表与 `defineActTool` / registry lock 一致 - [ ] parity ledger + tool-surface 主表行已更新 - [ ] CDP attach 失败 / 无对话框 / 路径逃逸均为结构化错误 - [ ] #5817:不因 PDF/network/dialog 引入静默 headless 写路由 - [ ] 非目标未膨胀进本 epic ## 证据锚点 - `packages/octopus/contracts/browser-tools-parity-ledger.md` - `packages/octopus/contracts/browser-tool-surface-v1.md` - `packages/octopus/contracts/browser-act-surface-v1.md` - `packages/octopus/src/tool/browser-ids.ts` - `packages/desktop/src/main/guest-dialog.ts` - `packages/desktop/src/main/guest-network-cdp.ts` - `packages/octopus/src/browser/headless-driver.ts`
作者
所有者

【票面刷新注记 — 2026-11-11 代码取证,octopus main】

本 Epic 的 P0 三件套经本轮新鲜代码证据核实均已双腿落地,票面锚定已 stale(锚点 cadbbbb56 时期的 HEADLESS_ONLY 清单已过时):

  • browser_network_requests / _request:dual-backend 已落地(pane 腿读 CDP Network ring)— packages/octopus/src/tool/browser-network-requests.txt:1-5
  • browser_handle_dialog:dual-backend 已落地(pane 腿 CDP 处理当前对话框,mode handle 走 act consent)— browser-handle-dialog.txt:1-5
  • browser_pdf_save:dual-leg 已落地(pane 腿 CDP MHTML + 离线渲染 + printToPDF,产物落 downloads 面板)— browser-pdf-save.txt:1-5(#6515 N-03)

当前 HEADLESS_ONLY_BROWSER_TOOL_IDS 仅剩 browser_permissions / browser_devices(browser-ids.ts:123-152)。

后续 parity 工作已转至主仓 octopus #7086(browser parity 三期:跨腿黄金一致性套件 + browser_drop / hide_highlight 缺口收口;其中 browser_drop 即本票 E-4 排除项的实证立项)。建议本票按剩余未完成项重核范围或关闭。

【票面刷新注记 — 2026-11-11 代码取证,octopus main】 本 Epic 的 P0 三件套经本轮新鲜代码证据核实**均已双腿落地**,票面锚定已 stale(锚点 cadbbbb56 时期的 HEADLESS_ONLY 清单已过时): - `browser_network_requests` / `_request`:dual-backend 已落地(pane 腿读 CDP Network ring)— `packages/octopus/src/tool/browser-network-requests.txt:1-5` - `browser_handle_dialog`:dual-backend 已落地(pane 腿 CDP 处理当前对话框,mode handle 走 act consent)— `browser-handle-dialog.txt:1-5` - `browser_pdf_save`:dual-leg 已落地(pane 腿 CDP MHTML + 离线渲染 + printToPDF,产物落 downloads 面板)— `browser-pdf-save.txt:1-5`(#6515 N-03) 当前 `HEADLESS_ONLY_BROWSER_TOOL_IDS` 仅剩 `browser_permissions` / `browser_devices`(`browser-ids.ts:123-152`)。 后续 parity 工作已转至主仓 octopus #7086(browser parity 三期:跨腿黄金一致性套件 + browser_drop / hide_highlight 缺口收口;其中 browser_drop 即本票 E-4 排除项的实证立项)。建议本票按剩余未完成项重核范围或关闭。
作者
所有者

收口: P0 三件套(network_requests/request、handle_dialog、pdf_save)经 2026-11-11 代码取证均已双腿落地(见票面刷新注记);后续 parity 缺口已在主仓 #7086 立项并于 2026-11-12 关闭交付。本票按剩余项重核=无未决 P0,关闭。via 2026-11-13 清理战役。

收口: P0 三件套(network_requests/request、handle_dialog、pdf_save)经 2026-11-11 代码取证均已双腿落地(见票面刷新注记);后续 parity 缺口已在主仓 #7086 立项并于 2026-11-12 关闭交付。本票按剩余项重核=无未决 P0,关闭。via 2026-11-13 清理战役。
登录 并参与到对话中。
未选择标签
1 名参与者
通知
截止日期
未设置截止日期。
依赖工单

未设置依赖工单。

引用:Octopus/release#12