baa-conductor

commit

83f43b7

parent

dee2b20

author

im_wower

date

2026-03-29 03:12:19 +0800 CST

docs: add T-S053 plugin diagnostic logging enhancement

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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