feat(record): 导出带 settled 页面状态的 Trace v3 bundle

[shnpd]

一句话总结

把录制结果从「单个 trace.json」升级为完整的 Trace v3 bundle：

• 扩展侧产出带 settled 页面状态的 v3 trace
• CLI 写出 trace/trace.json + trace/states/sN.txt
• 继续兼容旧扩展的 v2 回退

背景

feat/record-settled-states 已经具备「页面 settle 后再捕获状态」的能力。
本 PR 在此基础上把录制链路补齐为可交付产物，让 Agent 能直接消费录制结果：

1. 记录用户做了什么（steps）
2. 记录动作前后页面长什么样（states）
3. 把结果稳定导出为目录包

主要改动

1. 扩展侧：真正产出 Trace v3

核心文件：apps/extension/src/tools/record.ts

• record start 支持协商 trace_version
  • 新 CLI 请求 v3
  • 未传时回退 v2
  • 非法版本直接拒绝
• v3 录制时：
  • 启动后捕获初始 settled observation
  • 每个 action 绑定：
    • state：动作前页面状态
    • result.state：动作 settle 后页面状态
  • 页面正文使用与 bsk observe 相同的 VOM 格式
• 保留 v2 兼容：
  • 旧协议仍可导出 pages[] + steps
  • v2 下不记录 hover

2. 导航与动作时序更稳

这里不是新功能，而是修「谁先谁后、绑到哪一页」的竞态问题。

以前容易录乱的典型场景：

• OAuth / 重定向跳转链：login → callback → dashboard
• 点击后立刻跳转：click 与 webNavigation 几乎同时到达
• 用户点「结束」时，最后一步还没送出或还没 settle

本 PR 的处理方式：

• 重定向链合并为一个 navigate，后续 click 绑定落地页，而不是中间 hop
• 先 flush 待合并导航，再追加后续动作，保证顺序正确
• stop 前：
  • flush content script 里未送出的最后一步
  • drain 未 settle 的 draft
  • drain 还在 coalesce 的 redirect landing
• 浏览器 Finish 与 CLI record stop 并发时，共享同一次结束结果（成功/失败都一致回传）

3. CLI：导出目录包，而不是单文件

核心文件：crates/bsk-cli/src/cli/record.rs

推荐产物变为：

./trace/
  trace.json
  states/
    s1.txt
    s2.txt
    ...

关键行为：

• --output 默认改为目录 trace
• v3：trace.json 只保留 state 索引；正文落到 states/sN.txt
• v2 fallback：仍写单个 trace.json，不生成 states/
• 新增 --max-page-tokens、--redact-values
• 导出使用文件锁 + staging + rollback，避免半写入
• 只清理生成的 sN.txt，不误删用户自有文件
• record stop 若为可重试失败，会保留 recording session，允许再次 stop

4. 协议 / 文档 / i18n 对齐

• protocol：disk 文件语义从 pages/ 调整为 states/，文件名约定为 sN.txt
• skill 文档：改为介绍 v3 bundle，并说明 v2 fallback
• popup 文案：引导 Agent 读取 ./trace 目录包（trace.json + states/）

对用户可见的变化

之前：

trace.json

现在（推荐）：

trace/
  trace.json
  states/s1.txt
  states/s2.txt

语义：

• steps[].state：动作发生前的页面观察
• steps[].result.state：动作 settle 后的页面观察
• states/sN.txt：对应 settled page observation 的正文

若连接的是旧扩展，CLI 仍可导出 v2 单文件，但不会有完整 states/。

测试覆盖

扩展侧新增 record-steps.test.ts，覆盖：

• click / fill 顺序
• 浏览器导航与地址栏导航
• OAuth redirect coalesce
• settle 中 stop、capture 失败重试
• 慢页面 settle、后续动作打断 settle
• Finish 与 CLI stop 竞态
• v2 fallback / 非法 trace_version

CLI 新增 record_stop_retry.rs，覆盖：

• 首次 stop 可重试失败时保留 session
• 重试成功后写出 trace.json + states/s1.txt

建议 Review 重点

1. v3 / v2 协商与 fallback 是否正确
2. redirect coalesce 后，后续 click 是否绑定落地页
3. stop 时是否不丢最后一步、也不卡死
4. CLI 原子导出是否安全（锁、staging、回滚、残留清理）
5. 文档与 i18n 是否与新的目录包语义一致

[Copilot]

Pull request overview

This PR upgrades the recording pipeline from exporting a single trace.json to exporting a Trace v3 bundle directory (trace/trace.json + trace/states/sN.txt), with the extension producing v3 traces that include settled page observations and the CLI writing them atomically. It also preserves compatibility by falling back to legacy v2 output when talking to older extensions.

Changes:

• Extension: negotiate trace_version, record v3 traces with settled pre/post-action states, and stabilize navigation/action ordering (redirect coalescing + stop draining).
• CLI: export v3 as a bundle directory with locking + staging + rollback; keep v2 fallback as a single JSON output.
• Docs/UI: update SKILL docs and extension i18n/popup guidance to reference the bundle layout.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skill/SKILL.md	Updates recording docs to describe v3 bundle output + v2 fallback semantics.
crates/bsk-cli/skill/SKILL.md	Mirrors SKILL documentation updates within the CLI crate.
packages/i18n/src/locales/zh-CN/extension.json	Updates CN popup copy to reference the ./trace bundle output.
packages/i18n/src/locales/en-US/extension.json	Updates EN popup copy to reference the ./trace bundle output.
crates/bsk-protocol/src/tools/record.rs	Adjusts on-disk naming/semantics from pages/ to states/ and updates tests.
crates/bsk-cli/src/cli/record.rs	Implements bundle export (v3) + atomic directory writing and v2 fallback export behavior.
crates/bsk-cli/tests/record_stop_retry.rs	Adds CLI integration test for retryable record stop and bundle export verification.
apps/extension/src/tools/record.ts	Adds v3 negotiation, settled observation capture, redirect coalescing, and stop/drain stability logic.
apps/extension/src/tools/tests/record-steps.test.ts	Adds comprehensive tests covering ordering, redirects, stop race/drain, v2 fallback, etc.
apps/extension/src/lib/trace-reducer-v2.ts	Drops hover in v2 output to avoid breaking legacy v2 readers.
apps/extension/src/lib/recording-step-buffer.ts	Enhances step buffering (navigation cause mapping, redirect coalesce signaling, safer indexing).
apps/extension/src/lib/record-observation.ts	Improves target matching fallback and redirect landing handling during coalescing.
apps/extension/src/lib/record-bridge.ts	Expands step payload schema (geometry, commit, scroll, transition metadata).
apps/extension/src/lib/match-target.ts	Adds semantic target matching fallback when geometry is unavailable.
apps/extension/src/lib/tests/trace-reducer-v2.test.ts	Updates expectations for hover dropping behavior in v2.
apps/extension/src/lib/tests/recording-step-buffer.test.ts	Adds tests for capture fallback retention and redirect coalesce behavior.
apps/extension/src/lib/tests/match-target.test.ts	Adds tests for semantic fallback matching behavior.
apps/extension/src/entrypoints/popup/App.test.tsx	Updates popup test assertions to expect bundle-based instructions.
apps/extension/src/entrypoints/background.ts	Wires the CDP runner into recording listeners.
apps/extension/src/content/record-capture.ts	Adds geometry + commit metadata and improves stop flushing/retry behavior for step delivery.
apps/extension/src/content/tests/record-capture.test.ts	Adds tests covering stop retry behavior and geometry capture.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.