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

[shnpd]

Summary

把录制结果从单个 trace.json 升级为 Trace v3 目录包（trace/trace.json + trace/states/sN.txt）。旧扩展仍可回退为 v2 单文件。

base 分支 feat/record-settled-states 已经能在页面 settle 后捕获状态。本 PR 补齐交付链路：扩展产出带动作前后状态的 v3 trace，CLI 原子写出目录包。

Motivation

给 Agent 回放/理解录制结果时，需要同时拿到：

• 用户做了什么（steps）
• 动作前后页面长什么样（states）

state 正文体积较大，不适合全部塞进一个 JSON。导出过程还要能扛住中途失败，避免留下半包。

Changes

Extension

核心文件：apps/extension/src/tools/record.ts、lib/recording/recording-runtime.ts、content/record-capture.ts、content/record-step-delivery.ts

版本协商

• record start 读取 trace_version
• 新 CLI 显式请求 3
• 未传时按 v2 录制，保证旧客户端可用
• 非法版本直接拒绝，不进入录制

v3 录制语义

• 启动后先抓一份初始 settled observation，作为后续步骤的基准 state
• 每个 action 绑定两个状态：
  • state：动作发生前的页面
  • result.state：动作 settle 后的页面
• 页面正文使用与 bsk observe 相同的 VOM 格式
• max_page_tokens、redact_values 从 start 参数传到 observation runtime，控制截断和脱敏

按 tab 的 observation runtime

• 新增 RecordingObservationRuntime，每个 tab 独立维护 session / settle / 初始 capture
• stop 前 drain 尚未完成的 capture，避免最后一页状态丢失
• 多 tab 切换时状态按 tab 隔离，不串到别的页面

导航与动作时序

• OAuth / 重定向链合并成一个 navigate，后续 click 绑到落地页，而不是中间 hop
• 用 actionQueue 串行化「先入 step、再处理 webNavigation」，避免 click 和跳转几乎同时到达时绑错页
• 先 flush 待合并导航，再追加后续动作，保证顺序稳定

stop / Finish 稳定性

• stop 时 flush content script 里还没送出的最后一步（record-step-delivery 支持重试）
• drain 未 settle 的 draft，以及还在 coalesce 的 redirect landing
• 浏览器点「结束」和 CLI record stop 并发时，共用同一次结束结果（成功或失败都一致回传）
• content script 在 chrome://、about:blank 等受限页无法注入时，会等 tab ready 并重试 RECORD_START ack

v2 路径仍导出 pages[] + steps，且不记录 hover。

CLI

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

产物布局

• --output 默认改为目录 trace

• v3 写出：

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

• trace.json 只保留 state 索引和 steps；正文落到 states/sN.txt

• 接到旧扩展的 v2 trace 时，只写 trace.json，不创建 states/

导出安全

• 独立模块 export.rs：文件锁 .bsk-record-export.lock + staging 目录 + 失败回滚
• 覆盖已有 bundle 时，只清理本工具生成的 sN.txt，不删用户自有文件
• start 失败会拆掉刚开的 session；await 结束后无论成败都 session stop 并清本地 recording state

参数与 stop 重试

• 新增 --max-page-tokens、--redact-values
• 新 CLI 始终带 trace_version: 3 发起 start
• record stop 若为可重试失败，保留 recording session，允许再次 stop 后再写 bundle

Protocol / 文档 / i18n

• RecordStartParams 增加 trace_version / max_page_tokens / redact_values
• 磁盘语义从 pages/ 改为 states/sN.txt
• record.rs 保持 base 的 record_v2 / record_v3 拆分，补齐 v3 round-trip、start options、extension 反序列化测试
• SKILL 和 popup 文案改为引导读取 ./trace 目录包，并说明 v2 fallback

User impact

之前：当前目录下一个 trace.json

现在（推荐）：

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

字段含义：

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

连的是旧扩展时，仍导出 v2 单文件，没有完整 states/。

Test plan

• apps/extension/src/tools/__tests__/record-steps.test.ts：click/fill 顺序、地址栏/浏览器导航、OAuth coalesce、settle 中 stop、capture 失败重试、慢页面 settle、后续动作打断 settle、Finish 与 CLI stop 竞态、v2 fallback / 非法 trace_version
• crates/bsk-cli/tests/record_stop_retry.rs：首次 stop 可重试失败时保留 session；重试成功后写出 trace.json + states/s1.txt
• protocol：record.rs 中 v3 序列化、v2/v3 分类与 schema、start 可选字段
• CI 在本分支跑绿

Review focus

1. v3 / v2 协商和 fallback 是否正确，非法版本是否被拒绝
2. redirect coalesce 之后，后续 click 是否绑到落地页
3. stop 是否不丢最后一步、也不卡在未 settle 的 capture 上
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.

[iuyo5678]

兼容问题可能导致已完成的录制结果丢失
实际场景：用户之前使用 --output trace.json，且该文件已经存在。升级后 --output 被当作 bundle 目录，用户完成录制时才会收到“不是目录”的错误。
此时扩展已经返回完整 Trace，但 CLI 仍会关闭 session 并清除录制状态，导致用户无法重新导出，只能重新录制。
建议：
录制开始前检查 --output，发现旧的 JSON 文件路径时提前报错并提示新用法；
收到 Trace 后先保存 recovery 文件，再执行 bundle 导出；
只有导出成功后才删除 recovery 数据；
增加“已有 trace.json 文件”和“导出失败后可恢复”的测试。
这是录制数据完整性问题，建议修复后再合入。