baa-conductor

BUG-027-startup-plugin-diagnostic-events-lost-before-ws-open.md

  1# BUG-027: 插件启动期诊断事件会在 WS 建立前丢失，阻塞 `logs/baa-plugin` 排障链路
  2
  3> 提交者：代码核对
  4> 日期：2026-03-29
  5
  6## 现象
  7
  8当前 `logs/baa-plugin/YYYY-MM-DD.jsonl` 被设计成 Firefox 插件诊断的统一落点，但插件冷启动、插件重载或页面首次注入时，最早一批关键事件可能完全不会进入 conductor：
  9
 10- `page_bridge_ready`
 11- `interceptor_active`
 12- 其他依赖页面刚加载时立即发送的诊断事件
 13
 14结果是：
 15
 16- 插件后续若成功连上 WS，后面的诊断日志能看到
 17- 但最关键的“页面桥接是否成功注入”“page-interceptor 是否已激活”这批启动期证据会静默缺失
 18- 当当前排障路径依赖 `logs/baa-plugin/` 判断注入链路时，会出现“没有日志，不知道是没注入还是只是太早发了”的盲区
 19
 20## 触发路径
 21
 22```text
 23刷新 ChatGPT / Claude / Gemini 页面
 24-> content-script / page-interceptor 刚加载即发送 page_bridge_ready / interceptor_active
 25-> controller 这时尚未 connectWs() 或 WS 仍未 open
 26-> wsSend() 直接返回 false
 27-> 事件无重试、无排队、无本地缓冲
 28-> conductor 侧 logs/baa-plugin/ 看不到这批启动期日志
 29```
 30
 31## 根因
 32
 33根因基本确认：
 34
 35- content-script 会在加载后立即发送 `page_bridge_ready`
 36- page-interceptor 会在激活后立即发送 `interceptor_active`
 37- controller 直到初始化尾部才调用 `connectWs()`
 38- `wsSend()` 在 socket 未连接时直接返回 `false`
 39- `plugin_diagnostic_log` 没有补发、排队或本地缓存机制
 40
 41因此，所有发生在 WS 建立之前的诊断事件都会被静默丢弃。
 42
 43## 复现步骤
 44
 45这是一个很短的时序问题，最小复现依赖真实 Firefox 插件环境：
 46
 471. 启动 conductor，确保会写 `logs/baa-plugin/`
 482. 重载 Firefox 插件或冷启动浏览器
 493. 刷新一个 AI 页面，例如 ChatGPT
 504. 观察页面控制台可看到 `content_script_loaded` / `interceptor_active`
 515. 再查看 conductor 的 `logs/baa-plugin/YYYY-MM-DD.jsonl`
 52
 53预期：
 54
 55- 应能看到 `page_bridge_ready`
 56- 应能看到 `interceptor_active`
 57
 58当前高概率实际情况：
 59
 60- 若事件发生在 WS `open` 之前，这两条日志不会出现在 `logs/baa-plugin/`
 61- 后续较晚产生的日志可能正常出现，造成“部分有日志、最早证据缺失”的假象
 62
 63## 当前影响
 64
 65- 直接影响当前依赖 `logs/baa-plugin/` 排查插件注入、桥接就绪、SSE 拦截起点的问题
 66- 当问题恰好发生在页面刚加载或插件刚重载阶段时，conductor 侧日志失去最关键证据
 67- 这不是普通信息缺失，而是会阻塞“确认 page-interceptor / content-script 是否启动成功”这条诊断路径
 68- 对正常业务请求不一定构成功能性故障，但对当前诊断主流程是阻塞性的
 69
 70## 修复建议
 71
 72### 方案 A（推荐）
 73
 74在 controller 侧为 `plugin_diagnostic_log` 增加一个很小的启动缓冲队列：
 75
 76- WS 未 open 时先暂存在内存
 77- `onopen` 后立即 flush
 78- 队列限制条数，避免无上限积累
 79
 80### 方案 B
 81
 82在 content-script/page-interceptor 侧延迟发送首批诊断事件，等 controller 与 WS 建立后再发。
 83
 84这个方案实现简单，但会把可靠性依赖到更多时序假设上。
 85
 86### 方案 C
 87
 88保留现有链路，但在 controller 与页面握手成功后主动补发一轮启动状态摘要。
 89
 90这样能补证据，但语义上不如真实事件直观。
 91
 92## 严重程度
 93
 94**High**
 95
 96这会直接阻塞当前 `logs/baa-plugin/` 诊断链路最重要的一段：页面启动与注入时序。功能本身不一定坏，但排障会失真。
 97
 98## 发现时间
 99
100`2026-03-29 by Codex`
101
102## 备注
103
104相关代码位置：
105
106- 启动期事件发送：[content-script.js](/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js#L888)
107- 启动期事件发送：[page-interceptor.js](/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js#L228)
108- WS 未连通时直接丢弃：[controller.js](/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js#L4003)
109- controller 在初始化尾部才开始连 WS：[controller.js](/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js#L7322)