baa-conductor

DISCUSS-FIREFOX-BRIDGE-CONTROL.md

  1# DISCUSS: FIREFOX_BRIDGE_CONTROL_REQUIREMENTS 核对与改进
  2
  3日期：2026-03-26
  4来源：Claude 交叉审查 FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md + BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md + 现有代码 + handoff
  5
  6---
  7
  8## 1. 现有接口与需求文档的迁移缺口
  9
 10### 现状
 11
 12当前 `/describe/business` 里浏览器接口是 claude-specific 的：
 13
 14```
 15/v1/browser                    # bridge 状态
 16/v1/browser/claude/open        # 打开 Claude 标签页
 17/v1/browser/claude/send        # 发消息（页面对话模式）
 18/v1/browser/claude/current     # 当前对话
 19/v1/browser/claude/reload      # 重载
 20```
 21
 22### 问题
 23
 24需求文档定义了通用能力模型（`api_request`、`stream_open` 等，按平台和账号选择代发目标），但没有说明：
 25
 26- 现有 `/v1/browser/claude/*` 系列接口的**迁移路径**：是废弃重建还是渐进改造？
 27- 过渡期是否需要两套接口并存？兼容性承诺是什么？
 28- 新的通用接口 URL 结构是什么？例如 `POST /v1/browser/request` + body 里选平台/账号？还是 `POST /v1/browser/:platform/request`？
 29
 30### 建议
 31
 32在需求文档中增加「迁移策略」章节，明确：
 331. 新接口路径命名规范
 342. 旧接口废弃时间表（或标记为 legacy）
 353. 灰度切换方式
 36
 37---
 38
 39## 2. SSE 链路的断连补偿机制
 40
 41### 问题
 42
 43需求文档把 SSE 列为首批正式能力，但 SSE 回传链路很长：
 44
 45```
 46conductor → WS → Firefox 插件 → 页面 fetch(SSE) → 拦截 → WS 回传 → conductor
 47```
 48
 49每一跳都可能断，但文档只定义了事件类型（`stream_open/event/end/error`），没有定义：
 50
 51- **断连重传**：WS 断了再连上后，丢失的 SSE event 怎么办？需要 sequence number 吗？
 52- **背压控制**：上游 SSE 速率 > WS 回传速率时怎么处理？缓冲？丢弃？
 53- **超时判定**：stream_open 后多久没收到 event 算超时？和 stream_error 的区别？
 54- **部分成功**：收到一半 SSE 后断了，已收到的数据如何交付给调用方？
 55
 56### 建议
 57
 58增加「SSE 可靠性设计」子章节，至少定义：
 59- 每个 stream_event 带递增 seq
 60- 断连后 conductor 向调用方发 stream_error + 已收到的 partial_events
 61- 超时阈值可配置（建议默认 30s 无 event = timeout）
 62
 63---
 64
 65## 3. 空壳页（Shell Page）定义不清
 66
 67### 问题
 68
 69两份需求文档都提到「空壳标签页」，这是关键概念但缺乏定义：
 70
 71- 空壳页的 URL 是什么？需要在目标平台同域才能携带 cookie 发起 fetch
 72- 如果用 `about:blank` 或自定义页面，cookie 不会自动附加
 73- 如果用目标平台的某个轻量页面，上游 CSP/CORS 变更可能导致 fetch 失败
 74- 空壳页 crash 或被用户手动关闭后的检测和恢复机制
 75
 76### 建议
 77
 78明确定义空壳页的实现方案，例如：
 79- 打开目标平台的最小页面（如 claude.ai 的某个静态端点）
 80- 插件通过 content_script 注入 fetch 执行环境
 81- 定义 tab 健康检查周期（如每 30s 检测一次 tab 是否存活）
 82
 83---
 84
 85## 4. 调度策略参数缺失
 86
 87### 问题
 88
 89需求文档列出了调度与风控的能力清单（限流、抖动、退避、熔断），但没有定义任何参数：
 90
 91- 人类化抖动的高斯分布 μ 和 σ 范围？
 92- 平台级限流的窗口和阈值？（例如 claude.ai 每分钟最多 N 次？）
 93- 失败退避的公式？（指数退避？基数和上限？）
 94- 熔断的触发条件？（连续 N 次失败？错误率超 X%？）
 95- 熔断恢复的半开探测策略？
 96
 97### 建议
 98
 99不需要在需求文档里定死数字，但应该定义：
1001. 每个策略的**配置接口**（至少可以通过 conductor config 调整）
1012. **默认值**（可以先用保守值：抖动 μ=2s σ=0.5s，限流 10req/min/platform，退避 base=1s max=60s）
1023. 策略参数是否纳入 `/describe/control` 的可读可写范围
103
104---
105
106## 5. 多浏览器/多 client 是否过度设计
107
108### 现状
109
110当前只有一个 Firefox 实例（一个 client_id）。DB schema 设计了 `(platform, host, browser, client_id, account)` 五级键。
111
112### 问题
113
114- 五级键的调度逻辑复杂度高，但短期内不会有多浏览器场景
115- 如果过度设计调度层，首版实现的复杂度会大幅上升，拖慢交付
116
117### 建议
118
119- 首版调度以 `client_id` 为唯一执行者标识，`host`/`browser` 作为元数据记录但不参与调度决策
120- 在需求文档中标注哪些是「首版必须」vs「多 client 扩展预留」
121- 多 client 调度作为独立需求文档，不混在首版里
122
123---
124
125## 6. tab 管理能力的状态同步问题
126
127### 问题
128
129需求文档定义了 `tab_open/focus/reload/restore` 四个管理能力，但缺少：
130
131- conductor 侧用什么标识一个 tab？`platform + shell_id`？
132- 如果 Firefox 侧用户手动关了 tab，conductor 怎么得知？（插件需要监听 `tabs.onRemoved` 并主动上报）
133- tab 状态在 conductor 侧是纯内存态还是也要持久化？
134- `tab_restore` 和初始 `tab_open` 的区别是什么？（restore 是否暗示有「期望 tab 列表」的概念？）
135
136### 建议
137
138增加「Tab 状态模型」子章节：
139- 定义 conductor 侧维护的 tab 期望状态（desired）和 Firefox 上报的实际状态（actual）
140- 定义 actual ≠ desired 时的自动调和策略
141- 明确 `tab_restore` = "重建所有 desired 中存在但 actual 中缺失的 tab"
142
143---
144
145## 7. codexd 链路与 browser 链路的关系
146
147### 问题
148
149handoff 文档里 codexd 和 browser 是并列的两条执行链路。本需求只定义 browser 链路，但没说明：
150
151- codexd（走 OpenAI 直连 API）和 browser（走 claude.ai 代发）在 task scheduler 里如何选择？
152- 是否需要统一的「执行后端」抽象层？task step 定义 `executor: codexd | browser`？
153- 如果两条链路都能完成同一件事，调度优先级是什么？
154
155### 建议
156
157在需求文档或 handoff 里增加一段「执行链路选择原则」，例如：
158- codexd = 用于代码任务（有文件系统访问）
159- browser/claude = 用于对话任务（无文件系统访问）
160- 两者不互相替代，由 task 定义决定
161
162---
163
164## 8. 凭证指纹的生成规范
165
166### 问题
167
168持久化需求说存「凭证指纹」用于判断变更，DB 里有 `credential_fingerprint TEXT`，但没定义：
169
170- 指纹的输入是什么？（哪些 header 字段？cookie name？token 前缀？）
171- 哈希算法是什么？（SHA-256？）
172- 指纹在哪一侧生成？如果在插件侧生成，conductor 无法验证一致性
173- 指纹变更是否触发 `status` 从 `fresh` 降级到 `stale`？
174
175### 建议
176
177在持久化需求文档中增加指纹规范：
178- 输入 = 排序后的 `cookie names + auth header type + token prefix(8 chars)`
179- 算法 = SHA-256
180- 生成侧 = 插件（conductor 不接触原始值）
181- 变更 = 触发 `captured_at` 更新，status 保持 `fresh`（指纹变了说明重新登录了，是好事）
182
183---
184
185## 9. 两份需求文档缺乏交叉引用
186
187### 问题
188
189`BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md` 和 `FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md` 有大量概念重叠（空壳页、凭证不持久化、账号发现等），但各自独立，没有引用关系。
190
191### 建议
192
193- 在两份文档开头加「关联文档」章节，互相引用
194- 共享概念（如空壳页、凭证指纹、状态三态 fresh/stale/lost）抽到一份共享定义文档或 glossary
195- 避免后续 codex 实现时两边对同一概念的理解不一致
196
197---
198
199## 总结：建议改进优先级
200
201| # | 问题 | 严重度 | 改动量 |
202|---|---|---|---|
203| 1 | 现有接口迁移路径缺失 | High | 在需求文档加一章 |
204| 2 | SSE 断连补偿未定义 | High | 加子章节 |
205| 3 | 空壳页定义不清 | High | 加定义 + 补到两份文档 |
206| 4 | 调度参数缺失 | Medium | 加默认值和配置接口定义 |
207| 5 | 多 client 过度设计风险 | Medium | 标注首版 vs 扩展 |
208| 6 | tab 状态同步缺失 | Medium | 加状态模型章节 |
209| 7 | codexd 与 browser 选择原则 | Medium | 加一段说明 |
210| 8 | 凭证指纹规范缺失 | Low | 加到持久化文档 |
211| 9 | 文档缺交叉引用 | Low | 加关联章节 |