baa-conductor

commit

b0d8f7b

parent

762dc61

author

im_wower

date

2026-03-29 03:31:15 +0800 CST

docs: add T-S054 forward plugin diagnostic logs to conductor via WS

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

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