baa-conductor

NEXT_WAVE_REQUIREMENTS.md

  1# 下一波需求清单
  2
  3日期：`2026-03-30`
  4
  5## 状态
  6
  7- `历史需求视图`
  8- 基线：`main@625f808`
  9- 当前正式进度以 `tasks/TASK_OVERVIEW.md` 和 `plans/STATUS_SUMMARY.md` 为准
 10
 11## 关联文档
 12
 13- [`./ARTIFACT_STATIC_SERVICE.md`](./ARTIFACT_STATIC_SERVICE.md)
 14- [`./STATUS_SUMMARY.md`](./STATUS_SUMMARY.md)
 15- [`./BAA_INSTRUCTION_SYSTEM.md`](./BAA_INSTRUCTION_SYSTEM.md)
 16
 17## 背景
 18
 19Artifact 静态服务主线（T-S039~T-S045）已完成。当前文档继续保留“下一波需求”视图，同时把已完成的 `T-BUG-029`、`T-S047`、`T-S050` 标出来，避免后续接手时重复判断。
 20
 21## 1. ChatGPT final-message 提取 bug（P0）
 22
 23### 问题
 24
 25ChatGPT 使用思考模式（o3/o4）时，SSE 流先发 "Thought for a few seconds" 思考标记，再发真正的 assistant 回复。当前 `final-message.js` 的 `extractChatgptCandidateFromText` 只提取到思考标记，漏掉了包含 baa 指令的正文。
 26
 27### 影响
 28
 29ChatGPT 闭环完全断裂——conductor 收到的 raw_text 是 "Thought for a couple of seconds"，无法提取 baa 指令。
 30
 31### 修复方向
 32
 33- 修改 `extractChatgptCandidateFromText` 和 `extractChatgptCandidateFromChunk`
 34- 跳过 thinking/reasoning 类型的消息，只提取 role=assistant 且 content 非空的最终回复
 35- 参考 ChatGPT SSE 响应中的 `message.metadata.is_complete` 或 `message.status` 字段区分
 36
 37### 需要日志支持
 38
 39修复前需要先能看到 ChatGPT 的原始 SSE 流数据，否则只能盲改。建议先完成需求 2（日志落盘），再修此 bug。
 40
 41## 2. 请求/响应日志落盘（P1）
 42
 43### 问题
 44
 45当前无论插件还是 conductor，都没有把原始请求/响应数据写到文件。排查任何问题都要猜。
 46
 47- 插件：日志在内存循环缓冲区，重载即丢
 48- conductor：stdout 只有启动/停止状态行，`browser.final_message` 的完整 payload 不记录
 49
 50### 需求
 51
 52**conductor 侧：**
 53
 54- 每次收到 `browser.final_message` 时，把完整 payload 写到日志文件
 55- 日志目录：`logs/baa-ingest/`
 56- 按天轮转：`YYYY-MM-DD.jsonl`（每行一个 JSON）
 57- 包含：timestamp、platform、conversation_id、assistant_message_id、raw_text 全文、ingest 结果摘要
 58
 59**插件侧（可选，优先级较低）：**
 60
 61- 把拦截到的 SSE chunk 原始数据通过 WS 发给 conductor 落盘
 62- 或者插件本地写到 `browser.storage.local`（有大小限制）
 63
 64### 实现方式
 65
 66conductor 侧只需在 `firefox-ws.ts` 的 `handleBrowserFinalMessage` 和 `ingest.ts` 的 `ingestAssistantFinalMessage` 中加 `appendFileSync` 写 JSONL 即可。
 67
 68## 3. `/v1/files/read` kind 标记 bug（P1）
 69
 70### 问题
 71
 72`local-api.ts` 中 `/v1/files/read` 路由的 kind 被标记为 `"write"`，导致 `/v1/capabilities` 将它归入 write 端点。
 73
 74### 修复
 75
 76一行改动：`kind: "write"` → `kind: "read"`。
 77
 78## 4. 跨会话接续入口（P2）
 79
 80### 问题
 81
 82Artifact 静态服务已经把消息和执行结果持久化并生成了 URL，但新 AI 对话没有入口发现这些 URL。
 83
 84### 需求
 85
 86`@conductor::describe` 的回复中应包含：
 87
 88- 最近活跃会话的 URL：`https://conductor.makefile.so/artifact/session/latest.txt`
 89- 或最近 N 条消息/执行的 URL 列表
 90
 91这样新对话的 AI 可以 fetch 这个 URL 获取历史上下文。
 92
 93### 实现方式
 94
 95修改 `/describe` 或 `/describe/business` 的响应，加入 `recent_sessions_url` 字段。
 96
 97## 5. Gemini 投递适配器（P2）
 98
 99### 问题
100
101`plugins/baa-firefox/delivery-adapters.js` 只有 Claude 和 ChatGPT 的适配器，缺 Gemini。执行结果无法回送到 Gemini 对话。
102
103### 需求
104
105补充 Gemini 平台的 DOM 选择器：
106
107- readinessSelectors：Gemini 页面就绪标识
108- composerSelectors：输入框选择器
109- sendButtonSelectors：发送按钮选择器
110- sendingSelectors：发送中状态选择器
111
112### 前置条件
113
114需要在 Gemini 页面上实际观察 DOM 结构，确认选择器。
115
116## 6. 开放 `@browser.chatgpt` / `@browser.gemini` target（P2）
117
118### 问题
119
120当前 policy 白名单只有 `conductor`、`system`、`browser.claude`。AI 不能向 ChatGPT/Gemini 对话发消息。
121
122### 需求
123
124- `policy.ts`：SUPPORTED_TARGET_TOOLS 加入 `browser.chatgpt` 和 `browser.gemini`，tools 同 `browser.claude`（`current`、`send`）
125- `router.ts`：加对应的路由映射
126- `local-api.ts`：加对应的端点（如 `/v1/browser/chatgpt/send`）
127
128### 前置条件
129
130- ChatGPT 需要先修复 final-message bug（需求 1）
131- Gemini 需要先补投递适配器（需求 5）
132
133## 7. stagit 生成 git 静态页面（P3）
134
135### 需求
136
137用 stagit 把 git 仓库生成纯静态 HTML，conductor serve，AI 通过 URL 浏览 git 历史、diff、文件。
138
139### 实现方式
140
141- `brew install stagit`
142- 写一个 shell 脚本 `scripts/git-snapshot.sh`，生成到 `state/artifacts/repo/{repo-name}/`
143- conductor 的 `/artifact/repo/` 路由 serve
144- post-commit hook 或 cron 触发重新生成
145
146### 优先级
147
148低。AI 可以通过 `@conductor::exec:::"git log"` 等指令获取 git 信息，结果已经通过 artifact 持久化为 URL。stagit 是锦上添花。
149
150## 8. 代码文件直读映射（P3）
151
152### 需求
153
154conductor 的 `/code/{repo}/...` 路由直接 serve 磁盘上的代码文件，AI 通过 URL 读取任意源文件。
155
156### 实现方式
157
158- conductor 加 `/code/` 路由，alias 到 `/Users/george/code/`
159- `autoindex` 功能（列出目录内容）
160- 安全：排除 `.env`、`.credentials`、`.git/objects`
161- Content-Type：统一 `text/plain; charset=utf-8`
162
163### 优先级
164
165低。AI 可以通过 `@conductor::files/read` 读文件，结果已经 artifact 化。直读映射是便利性优化。
166
167## 9. 签名 URL 鉴权（P3，暂不做）
168
169### 需求
170
171后续给 `/artifact/` 路由加签名 URL 鉴权：`?sig=xxx&exp=xxx`。
172
173### 设计要点（已与 ChatGPT / Gemini 确认）
174
175- AI 无法带自定义 Header，只能用 URL 参数
176- 签名 URL 比纯 token 更安全（可过期、可绑定路径）
177- 当前暂不实现，保持公开访问
178
179## 10. 历史消息回补（P2）
180
181### 问题
182
183当前 conductor 只存储插件实时观察到的消息。如果插件重载、conductor 重启、或页面在插件未注入时收到回复，这些消息永久丢失，无法回补。
184
185旧版 baa-server 通过 sync-worker 定时拉取平台对话历史解决此问题。
186
187### 需求
188
189在 conductor 内部实现定时消息回补：
190
191- 通过浏览器代理（`/v1/browser/request`）调平台 API 拉取对话历史
192- 与 artifact-db 中已有消息对比，补入缺失的消息
193- 写入 messages 表 + 生成静态文件
194
195### 设计要点
196
197- **在 conductor 内部实现**，不做独立进程（已有浏览器代理、凭证、artifact-db 依赖）
198- 参考旧版 `baa-old-files/baa/baa-server/lib/sync-worker.js`：
199  - 两类定时任务：历史同步（60 分钟）+ 增量同步（6-10 分钟随机）
200  - 活跃检测：proxy busy 时跳过，Extension 离线时跳过
201  - 对话间延迟 1-3 秒，避免限流
202  - 重试 2 次，间隔 5 秒
203  - INSERT OR IGNORE 幂等写入
204- 需要各平台的对话历史 API 端点：
205  - Claude：`GET /api/organizations/{orgId}/chat_conversations/{convId}`
206  - ChatGPT：`GET /backend-api/conversation/{convId}`
207  - Gemini：待确认
208
209### 前置条件
210
211- 插件诊断日志（T-S053）完成后，能观察到各平台的 API 端点格式
212- 各平台的浏览器代理请求路径已可用
213
214## 11. 拦截 AI 平台消息完成推送（P2）
215
216### 问题
217
218当前 final-message 捕获依赖解析 SSE 流，存在多个不稳定因素：
219
220- ChatGPT 思考模式下 SSE 流结构变化导致提取遗漏
221- SSE 流解析需要处理分块、超时、中断等边界情况
222- 不同平台的 SSE 格式各异，维护成本高
223
224如果能拦截 AI 平台在消息完成后发出的推送事件或回调请求，会比解析 SSE 流更可靠。
225
226### 需求
227
228调研并实现更可靠的消息完成检测机制：
229
230- **ChatGPT**：观察消息完成后是否有 REST 回调（如 `GET /backend-api/conversation/{id}` 获取完整对话状态）或 WebSocket 推送
231- **Claude**：SSE 流的 `message_stop` 事件已经比较可靠，但观察是否有额外的完成信号
232- **Gemini**：观察消息完成后的网络活动
233
234### 实现方向
235
2361. 先通过 T-S053 的诊断日志观察各平台在消息完成后的网络请求模式
2372. 如果存在可靠的"消息完成"回调请求，在 page-interceptor 中拦截该请求，提取完整的 assistant 回复文本
2383. 作为 final-message 的补充或替代信号源
2394. 如果平台使用 WebSocket 推送，需要在 page-interceptor 中增加 WebSocket 拦截能力（当前只拦截 fetch/XHR）
240
241### 前置条件
242
243- T-S053（插件诊断日志）完成后才能有效观察
244- 需要在各平台实际触发对话，观察 DevTools Network 面板确认推送机制
245
246### 优先级
247
248中。依赖 T-S053 的日志能力，且需要实际观察才能确定技术方案。先观察再设计。
249
250## 优先级总览
251
252| 优先级 | 需求 | 工作量 | 状态 |
253|---|---|---|---|
254| P0 | #1 ChatGPT final-message 提取 bug | M | ✅ T-BUG-029 已完成 |
255| P1 | #2 请求/响应日志落盘 | S | ✅ T-S046 已完成 |
256| P1 | #3 files/read kind bug | S | ✅ T-S046 已完成 |
257| P2 | #4 跨会话接续入口 | S | ✅ T-S047 已完成 |
258| P2 | #5 Gemini 投递适配器 | M | T-S048 待开始 |
259| P2 | #6 开放 chatgpt/gemini target | S | T-S049 待开始 |
260| P2 | #10 历史消息回补 | M | 未建任务 |
261| P2 | #11 拦截消息完成推送 | M | 未建任务（依赖 T-S053） |
262| P3 | #7 stagit | M | ✅ T-S050 已完成 |
263| P3 | #8 代码文件直读 | S | T-S051 待开始 |
264| P3 | #9 签名 URL | — | 暂不做 |
265
266## 建议执行顺序
267
268```
269T-S053 (插件诊断日志)
270    ↓
271T-S048 (Gemini 适配器)    #10 (历史回补)    #11 (拦截推送)  ← 可并行
272    ↓
273T-S049 (开放 target)
274
275T-S051 (代码文件直读)  ← 独立
276```