Octopus/octopus-release
3
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 34 Wiki Activity

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

New Issue
Open
opened 2026-10-26 21:13:41 +08:00 by fourbroad · 0 comments
fourbroad commented 2026-10-26 21:13:41 +08:00
Owner
Copy Link
Copy Source

北极星验收

用户看得见的那一页（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`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
fourbroad octopus-bot (Octopus Agent Bot) ZJZ
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Octopus/octopus-release#12