feat(trace): 统一时间线——操作 + 网络请求录制，用于 site adapter 创建

[yan5xu]

背景

创建 site adapter 时，需要理解"用户操作 → 网络请求"的因果关系。现有的 trace 命令是空壳（traceEvents 永远为空），recordAction() 只存最后一个 seq 数字，人工在 Chrome 里的操作完全不可见。

改动

1. 统一时间线（feat(trace)）

将空壳 trace 命令改造为完整的录制系统，在同一条时间线里记录：

• 命令式操作（click/fill/press/scroll 等）—— 改造 recordAction() 传入操作详情
• 人工操作（用户直接在 Chrome 里点击/输入）—— 通过 Runtime.addBinding + 注入 JS 监听器捕获
• 网络请求/响应 —— CDP Network 事件推入 trace timeline
• 因果推断 —— 每个 request 自动关联最近的 action（triggerSeq）

新增子命令：

• trace events —— 查询时间线，支持 --tab/--type/--since/--filter/--limit
• trace body <requestId> —— 获取某个请求的 response body

设计要点：

• trace 是 session 级别，非 per-tab。新 tab 通过 Target.targetCreated 的 openerId 自动加入
• trace stop 只停止采集，数据保留，可反复查询
• 现有 network/console/errors 命令零改动，完全向后兼容

2. 修复页面导航后网络事件丢失（fix(cdp)）

这是一个长期存在的 bug，不限于 trace 功能。

根因：Target.detachedFromTarget 在同 tab 跨域导航时被触发，handler 误调 tabManager.removeTab()，导致 tab 的所有 event buffer（network/console/errors）被销毁。新 session attach 后事件无处写入，被静默丢弃。

修复：

• Target.detachedFromTarget：只清 session 映射，不删 tab state。tab 删除交给 Target.targetDestroyed
• Target.attachedToTarget：检测到已有 tab 时，重新 enable CDP domains（Network/Page/Runtime/DOM/Accessibility）

3. Help text 更新

CLI help 和选项说明同步更新。

改动文件

文件	改动
protocol.ts	TraceEvent → TraceEntry union 类型；Request 新增 traceType/requestId；ResponseData 新增 traceBody
index.ts (shared)	导出新类型
commands.ts	trace 扩展为 5 个子命令 + 过滤参数
tab-state.ts	TraceSession + ActionDetail 类型；recordAction() 接受 detail；TabStateManager 新增 trace 方法
command-dispatch.ts	trace handler 重写；~15 个 recordAction() 调用传入操作详情
cdp-connection.ts	Network/Response 推入 trace；人工操作捕获；新 tab 自动加入；导航 fix
trace.ts (cli)	格式化时间线输出
index.ts (cli)	help text + 新 flag 解析

验证

• 编译通过
• 现有测试通过（1 个 pre-existing failure 无关）
• action 录制（command + human）
• network 请求 + triggerSeq 因果关联
• trace events 查询 + 过滤（--type/--since/--tab）
• trace body 获取 response body
• 同域导航后 network events 正常
• 跨域导航后 network events 正常（HN → example.com）
• 向后兼容：network requests 等命令不受影响

Agent 使用示例

# 开始录制
bb-browser trace start --tab 58b0

# 操作
bb-browser snap --tab 58b0
bb-browser click 11 --tab 58b0
bb-browser fill 3 "搜索关键词" --tab 58b0
bb-browser press Enter --tab 58b0

# 查看时间线
bb-browser trace events
bb-browser trace events --type request    # 只看网络请求
bb-browser trace events --since 20        # 增量查询

# 获取请求 body
bb-browser trace body <requestId>

# 停止（数据保留）
bb-browser trace stop
bb-browser trace events                   # 停后仍可查询