baa-conductor

T-S054.md

  1# Task T-S054：插件诊断日志通过 WS 转发到 conductor 落盘
  2
  3## 状态
  4
  5- 当前状态：`已完成`
  6- 规模预估：`S`
  7- 依赖任务：`T-S053`（已完成）
  8- 建议执行者：`Claude`（需要理解插件 WS 协议和 conductor 日志写入）
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S054.md` 任务文档，完成开发任务。
 13
 14## 当前基线
 15
 16- 仓库：`/Users/george/code/baa-conductor`
 17- 分支基线：`main`
 18- 提交：`762dc61`
 19
 20## 分支与 worktree（强制）
 21
 22- 分支名：`feat/plugin-log-forwarding`
 23- worktree 路径：`/Users/george/code/baa-conductor-plugin-log-forwarding`
 24
 25开工步骤：
 26
 271. `cd /Users/george/code/baa-conductor`
 282. `git worktree add ../baa-conductor-plugin-log-forwarding -b feat/plugin-log-forwarding main`
 293. `cd ../baa-conductor-plugin-log-forwarding`
 30
 31完成后提交与推送（由执行者完成，不要合并）：
 32
 331. 在 worktree 里提交所有变更（包括更新后的任务文档）
 342. `git push -u origin feat/plugin-log-forwarding`
 35
 36## 背景
 37
 38T-S053 在插件中加了 `[BAA]` 前缀的 console.log 诊断日志和 controller 内存缓冲区日志，但实际测试发现：
 39
 401. Browser Console 需要手动打开查看，不方便事后排查
 412. 插件重载后 content-script 可能没重新注入，console 日志完全看不到
 423. controller 内存日志在插件重载后丢失
 43
 44需要把插件的关键诊断日志通过 WS 发给 conductor，conductor 写到磁盘文件，这样即使不看 Browser Console 也能事后排查。
 45
 46## 目标
 47
 48插件通过 WS 把关键诊断事件发给 conductor，conductor 写到 `logs/baa-plugin/YYYY-MM-DD.jsonl`。
 49
 50## 必须完成
 51
 52### 1. 插件侧：发送诊断日志
 53
 54在 controller.js 中，`addLog` 函数对以下级别的日志通过 WS 发送 `plugin_diagnostic_log` 消息：
 55
 56- `error` — 全部转发
 57- `warn` — 全部转发
 58- `info` — 全部转发
 59- `debug` — 只转发关键事件（final_message 相关、tab 跟踪、SSE 流开始/结束）
 60
 61消息格式：
 62```json
 63{
 64  "type": "plugin_diagnostic_log",
 65  "ts": "2026-03-29T03:30:00.000Z",
 66  "level": "info",
 67  "text": "[NET] chatgpt POST /backend-api/conversation → relevant=true",
 68  "client_id": "firefox-73q0ro"
 69}
 70```
 71
 72不转发的日志：
 73- 高频的每个 SSE chunk 事件
 74- credentials 和 endpoint 上报（已有专门的消息类型）
 75
 76### 2. conductor 侧：接收并写文件
 77
 78在 `firefox-ws.ts` 中处理 `plugin_diagnostic_log` 消息：
 79
 80- 写到 `logs/baa-plugin/YYYY-MM-DD.jsonl`
 81- 每行一个 JSON，追加写入
 82- 日志目录在 conductor 启动时创建
 83- 写入失败只 stderr，不影响主流程
 84
 85### 3. content-script 和 page-interceptor 的日志转发
 86
 87content-script.js 中的 `[BAA-CS]` 日志和 page-interceptor.js 中的 `[BAA]` 日志当前只输出到 console。
 88
 89把这些关键事件通过 `browser.runtime.sendMessage` 发给 controller，controller 再通过 WS 转发：
 90
 91- content-script.js：新增消息类型 `baa_diagnostic_log`，发送给 controller
 92- page-interceptor.js：通过 CustomEvent `__baa_diagnostic__` 发给 content-script，content-script 再转发
 93- controller.js：收到 `baa_diagnostic_log` 后走 `addLog("debug", ...)` + WS 转发
 94
 95只转发关键事件：
 96- `interceptor_active`（page-interceptor 成功注入）
 97- `sse_stream_start` / `sse_stream_done`（SSE 流生命周期）
 98- `fetch_intercepted`（匹配平台的 fetch 请求）
 99- `page_bridge_ready`（content-script 就绪）
100
101## 允许修改的目录
102
103- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
104- `/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
105- `/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
106- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-ws.ts`
107- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`（日志目录创建）
108
109## 尽量不要修改
110
111- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/`
112- `/Users/george/code/baa-conductor/packages/`
113
114## 需要特别注意
115
116- 日志转发不能影响正常功能——所有发送/写入包在 try-catch 中
117- 避免日志风暴——debug 级别只转发关键事件，不转发每个 SSE chunk
118- WS 未连接时日志丢弃，不缓存（避免内存增长）
119- page-interceptor 运行在 MAIN world，不能直接调 `browser.runtime.sendMessage`，必须通过 CustomEvent → content-script → controller 的桥接链路
120- 所有开发必须在 worktree 中进行
121
122## 验收标准
123
124- 插件重载 + 刷新 ChatGPT 页面后，`logs/baa-plugin/YYYY-MM-DD.jsonl` 出现日志
125- 日志包含 `interceptor_active`（证明 page-interceptor 注入了）
126- 日志包含 `sse_stream_start` / `sse_stream_done`（证明 SSE 拦截工作了）
127- ChatGPT 发消息后，日志包含 final-message 相关事件
128- 日志文件每行是合法 JSON
129- 正常功能不受影响
130
131## 推荐验证命令
132
133- `cd /Users/george/code/baa-conductor-plugin-log-forwarding && pnpm build`
134- `cd /Users/george/code/baa-conductor-plugin-log-forwarding && pnpm test`
135- 重启 conductor，重载插件，刷新 ChatGPT 页面
136- `cat logs/baa-plugin/*.jsonl`
137
138## 执行记录
139
140> 以下内容由执行任务的 AI 填写，创建任务时留空。
141
142### 开始执行
143
144- 执行者：Codex
145- 开始时间：2026-03-29
146- 状态变更：`待开始` → `进行中`
147
148### 完成摘要
149
150- 完成时间：2026-03-29
151- 状态变更：`进行中` → `已完成`
152- 修改了哪些文件：
153  - `plugins/baa-firefox/controller.js` — `addLog` 增加 `plugin_diagnostic_log` 转发，筛选 debug 级别关键事件，新增 `baa_diagnostic_log` 处理与页面诊断文本格式化
154  - `plugins/baa-firefox/content-script.js` — 新增 `baa_diagnostic_log` runtime 消息发送，桥接 `__baa_diagnostic__`，并在 content-script 就绪时上报 `page_bridge_ready`
155  - `plugins/baa-firefox/page-interceptor.js` — 新增 `__baa_diagnostic__` CustomEvent，转发 `interceptor_active`、`fetch_intercepted`、`sse_stream_start`、`sse_stream_done`
156  - `apps/conductor-daemon/src/firefox-ws.ts` — 接收 `plugin_diagnostic_log`，按消息时间写入 `logs/baa-plugin/YYYY-MM-DD.jsonl`
157  - `apps/conductor-daemon/src/index.ts` — conductor 启动时创建 `logs/baa-plugin` 目录并注入 Firefox WS server
158  - `apps/conductor-daemon/src/index.test.js` — 增加 WS 诊断日志落盘测试
159- 核心实现思路：
160  - 插件端采用 `page-interceptor -> content-script -> controller -> WS` 的桥接链路，把 MAIN world 里的关键诊断事件带回后台页
161  - controller 保持现有内存日志，同时在 `addLog` 内按级别筛选并发送 `plugin_diagnostic_log`，debug 只放行 final-message、SSE 生命周期和页面桥接关键事件
162  - conductor 端把 `plugin_diagnostic_log` 规范化后按天追加写入 JSONL；写失败只打 stderr，不影响主流程
163- 跑了哪些测试：
164  - `pnpm install`
165  - `pnpm build`
166  - `pnpm -C apps/conductor-daemon test`
167  - `node --check plugins/baa-firefox/controller.js`
168  - `node --check plugins/baa-firefox/content-script.js`
169  - `node --check plugins/baa-firefox/page-interceptor.js`
170
171### 执行过程中遇到的问题
172
173> 记录执行过程中遇到的阻塞、环境问题、临时绕过方案等。合并时由合并者判断是否需要修复或建新任务。
174
175- worktree 初始未安装依赖，`pnpm build` 时 `pnpm exec tsc` 报 `tsc not found`；执行 `pnpm install` 后恢复正常。
176
177### 剩余风险
178
179- 自动化验证覆盖了 WS 落盘与 daemon 行为，但插件重载后在真实 Firefox + ChatGPT 页面上的手动验证仍需按任务文档走一遍，确认 `interceptor_active` / `sse_stream_*` / final-message 相关事件都能稳定落盘。