feat: `page --all` 一次性抓取完整页面内容

[4fuu]

动机

当前 page 命令按视口高度分页，每次只返回一页内容。对于使用了懒加载（loading="lazy"、Intersection Observer、content-visibility: auto、虚拟滚动等）的现代网页，视口外的内容可能尚未渲染，导致快照中缺失这些节点。

AI agent 在需要全量理解页面内容时，只能手动循环 page --next 逐页翻取，缺少一步到位的方式。

方案

为 page 命令新增 --all flag：

browser-cli page <session-id> --all [--fresh] [--json] [--verbose]

CLI 侧编排（不新增 extension action）

复用已有的 SCROLL + GET_PAGE_FRESH，由 CLI 驱动循环：

1. 取初始快照，根据 scroll_height / viewport_height 算出总页数
2. 逐页循环：
   • SCROLL 到对应偏移量
   • 等待页面稳定（触发懒加载内容渲染）
   • GET_PAGE_FRESH 取新快照，收集节点
3. 按绝对坐标去重合并所有快照的节点
4. 跳过 ViewFilter，直接输出全部内容

这符合项目「浏览器薄、CLI 厚」的架构原则——extension 侧无需改动。

约束与细节

项目	说明
互斥	--all 与 --next/--prev/-p 互斥，同时传入应报错
节点去重	相邻页快照中同一元素会重复出现，需按绝对坐标 + tag + 内容去重
进度提示	长页面需多次滚动，可在 stderr 输出进度（如 Scrolling 3/12...），不影响 stdout 结构化输出
输出体积	长页面节点量大，--all 配合 --json 时可考虑默认 compact 模式
分页元数据	合并后视为单页输出，total_pages: 1, current_page: 1，保持与普通 page 输出结构一致，下游无需额外适配
滚动恢复	完成后将视口滚回原始位置，避免副作用

不采用的替代方案

• 新增独立命令（fullpage / capture）— 与 page 功能高度重叠，增加概念负担
• extension 侧实现自动滚动 — 违反「浏览器薄」原则，节奏难以控制
• 一次性 scrollTo(bottom) 后单次抓取 — 中间未经过视口的懒加载内容仍会缺失

依赖

• Sync browser viewport with page pagination #10 （SCROLL action 支持）

[4fuu]

等待策略补充

调查了 extension 侧 SCROLL 的实现，发现当前滚动后只等了一帧（requestAnimationFrame，约 16ms）就返回：

// content-script.ts
window.scrollTo({ top: ..., behavior: 'auto' });
await nextFrame();  // ← 仅此而已
return { ok: true, ... };

所以 --all 如果 SCROLL 后立刻 GET_PAGE_FRESH，懒加载根本来不及触发。

推荐方案：CLI 侧固定延迟 + --settle flag

不改 extension，在 CLI 侧 SCROLL 之后 sleep 一段时间再抓快照：

browser-cli page <session-id> --all [--settle <ms>]

• 默认 --settle 500，覆盖大多数懒加载场景
• 用户可调高（慢网络/复杂动画）或调低（已知静态页面）
• 对于需要精确等待的场景，建议先手动 wait --for <text>，再 --all

排除的替代方案

方案	排除原因
给 SCROLL 加 settle_ms 参数	需要改 extension，违反"浏览器薄"原则
复用现有 WAIT action	WAIT 等的是页面导航/DOMContentLoaded，不是懒加载渲染完成，语义不符
轮询 scroll_height 稳定	懒加载插入内容确实会改变 scrollHeight，但轮询需要多次往返，实现复杂，收益有限

[4fuu]

补一个我更倾向的 v1 方案，尽量先做出稳定可用版本，不一开始追求“完美合并 DOM 树”。

建议的实现方向

直接支持：

browser-cli page <session-id> --all [--settle <ms>] [--fresh] [--json] [--verbose]

约束：

• --all 与 -p / --next / --prev 互斥
• --settle 只在 --all 下可用，默认例如 500ms
• --all 明确定义为“全量阅读视图”，优先服务 AI / 阅读，不强承诺它和普通单页 page 一样适合作为后续交互定位依据

为什么建议这样做

我现在更不建议走“多份 RawSnapshot 底层节点去重合并”的路线。那个方向理论上更完整，但实现复杂度比较高：

• 去重规则容易变脆
• 父子关系合并容易出错
• sticky header / 动态插入 / 虚拟列表会把规则搞复杂

更务实的方式是：复用现有单页结构化能力，按页抓、按页解析、最后在 CLI 层聚合结果。

建议的编排流程

1. 先拿初始快照，记录原始 scroll_top
2. 从第 1 页开始循环
3. 每轮：
   • SCROLL 到目标页顶
   • sleep settle_ms
   • GET_PAGE_FRESH
   • 用现有 parse_page_from_snapshot(snapshot, Some(page_num)) 解析这一页
   • 将该页 nodes 追加到聚合结果
4. 每轮都基于最新快照重新计算 total_pages
   • 这样页面因为懒加载变长时，后续页数能自动补出来
5. 完成后滚回原始位置
6. 输出一个聚合后的 PageData
   • current_page = 1
   • total_pages = 1
   • truncated = false

v1 可以故意简化的点

• 不做底层 RawNode 树合并
• 不做复杂全局去重
• 最多做一个很轻的相邻重复顶层节点去重，用来压掉常见 sticky header
• --all 结果更偏“读模式”；真正需要点元素时，仍建议回到普通 page -p N

我觉得这个版本的优点是：

• 改动主要留在 CLI / Rust 侧，符合“浏览器薄、CLI 厚”
• 代码风险低，复用现有分页与结构化逻辑
• 用户价值高，AI 可以一次拿到更完整的页面内容
• 后续如果发现某些站点重复严重，再继续增强去重策略即可

额外提醒

如果这个功能最终落地，除了代码和测试，建议同步更新文档：

• README.md 里的命令用法、page 示例、--all / --settle 行为说明
• 仓库根目录 SKILL.md 里的命令说明和 agent 使用建议

否则工具能力已经变了，但外部文档和 skill 描述还停留在旧语义，后续 agent/用户会很容易用错。