baa-conductor

T-S053.md

  1# Task T-S053：插件详细日志与诊断增强
  2
  3## 状态
  4
  5- 当前状态：`已完成`
  6- 规模预估：`M`
  7- 依赖任务：无
  8- 建议执行者：`Claude`（需要理解插件 controller.js / content-script.js / page-interceptor.js 的事件流）
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S053.md` 任务文档，完成开发任务。
 13
 14如需补背景，再读：
 15
 16- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
 17- `/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
 18- `/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
 19- `/Users/george/code/baa-conductor/plugins/baa-firefox/final-message.js`
 20
 21## 当前基线
 22
 23- 仓库：`/Users/george/code/baa-conductor`
 24- 分支基线：`main`
 25- 提交：`dee2b20`
 26
 27## 分支与 worktree（强制）
 28
 29- 分支名：`feat/plugin-diagnostic-logging`
 30- worktree 路径：`/Users/george/code/baa-conductor-plugin-diagnostic-logging`
 31
 32开工步骤：
 33
 341. `cd /Users/george/code/baa-conductor`
 352. `git worktree add ../baa-conductor-plugin-diagnostic-logging -b feat/plugin-diagnostic-logging main`
 363. `cd ../baa-conductor-plugin-diagnostic-logging`
 37
 38完成后提交与推送（由执行者完成，不要合并）：
 39
 401. 在 worktree 里提交所有变更（包括更新后的任务文档）
 412. `git push -u origin feat/plugin-diagnostic-logging`
 42
 43## 目标
 44
 45增强 Firefox 插件的日志和诊断能力，让排查 final-message 捕获失败等问题不再需要猜。
 46
 47## 背景
 48
 49手动验证 ChatGPT 闭环时，ChatGPT 明确回复了 baa 代码块，但插件没有捕获到 final_message。当前插件日志在内存循环缓冲区，无法事后查看，也不记录关键事件（哪个 tab 的哪个请求被拦截/跳过、final-message 观察器为什么没触发等）。
 50
 51## 必须完成
 52
 53### 1. Tab 跟踪日志
 54
 55在 controller.js 中，每个被跟踪的 tab 记录：
 56- tab ID
 57- 平台（chatgpt / claude / gemini）
 58- 页面标题
 59- 页面 URL
 60- content-script 是否注入成功
 61- page-interceptor 是否注入成功
 62- 最近一次网络事件时间
 63
 64每当 tab 状态变化时（创建、导航、关闭、content-script 就绪）写一条日志。
 65
 66### 2. 网络事件日志
 67
 68在 handlePageNetwork 和 handlePageSse 中，对每个被处理的事件记录：
 69- 来源 tab ID 和平台
 70- URL（截取路径部分）
 71- 方法（GET/POST）
 72- 是否匹配 `isRelevantStreamUrl`
 73- 是否触发了 final-message 观察器
 74- 如果触发了，观察器返回了什么（relay 成功 / 被去重 / 为 null）
 75
 76### 3. final-message 观察日志
 77
 78在 observeFinalMessageFromPageSse 和 observeFinalMessageFromPageNetwork 中记录：
 79- 是否有 observer（`state.finalMessageRelayObservers[platform]` 是否存在）
 80- observeSse / observeNetwork 的返回值（null = 未产生 relay，有值 = 产生了 relay）
 81- relay 是否被去重跳过
 82- relay 是否成功发送到 conductor
 83
 84### 4. console.log 转发
 85
 86在 page-interceptor.js 和 content-script.js 中：
 87- 关键事件（fetch 拦截、SSE 流开始/结束、代理请求）用 `console.log("[BAA]", ...)` 输出
 88- content-script.js 收到页面事件时 `console.log("[BAA-CS]", event.type, ...)` 输出
 89- 这些日志可以通过 Firefox 的 Browser Console（Ctrl+Shift+J）查看
 90
 91### 5. 日志通过 WS 转发到 conductor（可选）
 92
 93如果实现简单，把关键日志事件通过 WS 发给 conductor，conductor 写到 `logs/baa-plugin/YYYY-MM-DD.jsonl`。消息类型用 `plugin_diagnostic_log`。
 94
 95如果实现复杂，跳过此项，只做本地 console 日志。
 96
 97## 允许修改的目录
 98
 99- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
100- `/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
101- `/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
102- `/Users/george/code/baa-conductor/plugins/baa-firefox/final-message.js`
103- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-ws.ts`（如果做 WS 转发）
104
105## 尽量不要修改
106
107- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/`
108- `/Users/george/code/baa-conductor/packages/`
109
110## 需要特别注意
111
112- 日志不能影响正常功能——所有日志写入包在 try-catch 中
113- 日志量要控制——网络事件日志只记录匹配平台 URL 的请求，不记录所有请求
114- console.log 前缀统一用 `[BAA]`，方便在 Browser Console 中过滤
115- controller.js 的内存日志缓冲区上限可以适当加大（从当前值加到 500 条）
116- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
117
118## 验收标准
119
120- 插件重载后，Browser Console 中能看到 `[BAA]` 前缀的日志
121- 打开 ChatGPT 页面后，能看到 tab 跟踪日志（tab ID、平台、URL）
122- ChatGPT 发消息后，能看到网络事件日志（SSE 流开始/结束）
123- final-message 观察器的触发/跳过原因可见
124- 日志不影响正常功能
125
126## 推荐验证命令
127
128- 在 Firefox 中按 Ctrl+Shift+J 打开 Browser Console
129- 过滤 `[BAA]`
130- 重载插件，观察 tab 跟踪日志
131- 在 ChatGPT 中发消息，观察网络事件和 final-message 日志
132
133## 执行记录
134
135> 以下内容由执行任务的 AI 填写，创建任务时留空。
136
137### 开始执行
138
139- 执行者：Claude
140- 开始时间：2026-03-29
141- 状态变更：`待开始` → `进行中`
142
143### 完成摘要
144
145- 完成时间：2026-03-29
146- 状态变更：`进行中` → `已完成`
147- 修改了哪些文件：
148  - `plugins/baa-firefox/controller.js` — LOG_LIMIT 160→500，handlePageNetwork/handlePageSse 增加 [NET]/[SSE] 诊断日志，observeFinalMessageFromPageNetwork/PageSse 增加 [FM-NET]/[FM-SSE] 诊断日志，handlePageBridgeReady 增加 URL 和标题输出
149  - `plugins/baa-firefox/content-script.js` — 所有事件处理函数（page_ready, network, sse, proxy_response, proxy_request_dispatch）增加 `[BAA-CS]` console.log
150  - `plugins/baa-firefox/page-interceptor.js` — fetch 拦截、SSE 流开始/结束、XHR 拦截、代理请求增加 `[BAA]` console.log
151  - `plugins/baa-firefox/final-message.js` — 导出 `isRelevantStreamUrl` 供 controller.js 诊断日志使用
152- 核心实现思路：
153  - controller.js 使用 `addLog("debug", ..., false)` 写入内存日志缓冲区（不通过 WS 发送），所有诊断日志包在 try-catch 中
154  - content-script.js 和 page-interceptor.js 使用 `console.log("[BAA]"/[BAA-CS]", ...)` 输出到 Browser Console，全部包在 try-catch 中
155  - SSE 事件日志仅在 done/error 时记录（避免每个 chunk 都记录）
156  - 网络事件日志记录所有已匹配平台的请求（shouldTrack 已在上游过滤）
157- 跑了哪些测试：
158  - 无自动化测试（纯日志增强，需手动在 Firefox Browser Console 验证）
159
160### 执行过程中遇到的问题
161
162无。
163
164### 剩余风险
165
166- WS 转发诊断日志（必须完成项第 5 项）标记为可选，本次未实现。如需事后查看日志，仍需通过 Browser Console 实时观察。
167- `addLog("debug", ...)` 的日志会占用内存缓冲区（已扩容到 500 条），高频 API 调用场景下可能挤掉较早的 info/warn/error 日志。
168