baa-conductor

BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md

  1# 浏览器桥接持久化新需求
  2
  3## 状态
  4
  5- `已落地（T-S017` 到 `T-S024` 已完成主线收口）`
  6- 优先级：`high`
  7- 记录时间：`2026-03-26`
  8
  9## 关联文档
 10
 11- [FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md](/Users/george/code/baa-conductor/plans/archive/FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md)
 12- [DISCUSS-FIREFOX-BRIDGE-CONTROL.md](/Users/george/code/baa-conductor/plans/discuss/DISCUSS-FIREFOX-BRIDGE-CONTROL.md)
 13
 14## 背景
 15
 16当前 Firefox 插件已经能发现登录态、账户和 API 端点，但 `conductor` 侧更偏内存态浏览器桥接摘要。
 17
 18新的目标不是保存原始凭证，而是把“哪些机器上的哪个浏览器已经具备可用登录态”持久化下来，供后续调度、状态判断和浏览器请求代发使用。
 19
 20## 核心结论
 21
 22- `conductor` 允许持久化 `account`
 23- `conductor` 只持久化“凭证指纹”和端点元数据
 24- `conductor` 不持久化原始 `cookie`、`token`、`header` 值
 25- 浏览器侧只保留一个空壳标签页，不承载真实对话 UI
 26- 业务请求走已拦截和已验证过的 API 端点，由浏览器侧代发
 27- 首版以 `client_id` 作为执行侧唯一标识；`host` / `browser` 先作为元数据保存，不在首版参与复杂调度
 28
 29## 需求目标
 30
 311. 让 `conductor` 长期知道：
 32   - 哪台机器
 33   - 哪个浏览器
 34   - 哪个平台
 35   - 哪个 `account`
 36   - 当前是否存在可用登录态
 372. 让这些信息在 `conductor` 重启后仍然存在。
 383. 让浏览器桥接从“页面对话驱动”收口到“登录态和 API 代理驱动”。
 39
 40## 必须持久化的内容
 41
 42- 平台：如 `claude` / `chatgpt` / `gemini`
 43- 机器标识：如 host、node、device identity
 44- 浏览器标识：如 `firefox`
 45- 浏览器 client 标识
 46- `account`
 47- 凭证指纹：
 48  - 仅用于判断“是否变更”
 49  - 不可逆
 50- 观测时间：
 51  - `captured_at`
 52  - `last_seen_at`
 53- 新鲜度和状态：
 54  - `fresh`
 55  - `stale`
 56  - `lost`
 57- 已发现且可用的 API 端点列表
 58- 端点最近验证时间
 59
 60## 明确不持久化的内容
 61
 62- 原始 `cookie`
 63- 原始 `token`
 64- 原始请求头值
 65- 原始请求体
 66- 页面内对话历史
 67- 页面 UI 状态
 68- 标签页业务语义
 69
 70## 浏览器侧需求
 71
 72- 每个平台最多维持一个空壳标签页或等价页面壳，用于保持登录环境和请求来源环境
 73- 不再依赖页面对话功能作为正式能力
 74- 插件继续负责：
 75  - 发现登录态
 76  - 发现 `account`
 77  - 发现 API 端点
 78  - 用原始凭证在浏览器本地代发请求
 79- 插件向 `conductor` 上报的是元数据、指纹和端点，不是原始凭证值
 80
 81## 空壳页定义
 82
 83- 空壳页必须是目标平台的一方页面，不能是 `about:blank` 或扩展自定义页
 84- 目标是同时满足：
 85  - 继承平台登录态
 86  - 能注入页面内 fetch/SSE 执行环境
 87  - 不承载真实对话 UI 作为主能力
 88- 首版每个平台最多维护一个空壳页
 89- 空壳页是否存活、是否需要恢复，由 Firefox 插件持续检测并向 `conductor` 上报
 90- 默认健康检查应至少覆盖：
 91  - tab 生命周期事件
 92  - `30s` 周期巡检
 93- 空壳页的控制和恢复语义，统一以控制方案文档为准
 94
 95## 凭证指纹规范
 96
 97- 指纹在 Firefox 插件侧生成，`conductor` 不接触原始凭证值
 98- 指纹输入是插件本地可见的认证材料规范化结果：
 99  - 参与认证的 cookie
100  - 参与认证的 auth/header 值
101  - 其他平台特有会话字段
102- 规范化后按稳定顺序拼接，再做 `SHA-256`
103- 上报给 `conductor` 的是十六进制摘要，不是原始值
104- 指纹变化表示登录态已更新：
105  - 更新 `captured_at`
106  - 更新 `last_seen_at`
107  - 状态保持 `fresh`
108
109## 首版执行标识
110
111- 首版浏览器代发和调度以 `client_id` 作为唯一执行者标识
112- `host`、`browser`、`account` 继续持久化，但短期只用于：
113  - 查询
114  - 展示
115  - 审计
116- 多浏览器、多 client 的复杂调度留作后续扩展，不作为首版必做范围
117
118## `conductor` 侧需求
119
120- 提供持久化的浏览器登录态记录
121- 允许按平台、机器、浏览器、`account` 查询当前可用桥接能力
122- 能判断某条登录态记录是否过期、失联或被替换
123- 能关联“哪个浏览器 client 可以为哪个平台/账户代发请求”
124
125## 运行边界
126
127- 真正的上游请求仍由浏览器侧发起
128- `conductor` 不应因为数据库泄露而直接泄露会话凭证
129- 如果浏览器 client 断开，`conductor` 仍保留最近一次持久化记录，但要把状态标成非新鲜或离线
130
131## 不在本轮范围内
132
133- 完整的页面自动化
134- 页面聊天 UI 编排
135- 多标签并行对话管理
136- 多 client 全局最优调度
137- 把原始凭证迁移到 `conductor` 端直接发请求
138
139## 当前优先级判断
140
141- 这是新的主方向，优先级高于：
142  - `4318` wrapper 删旧
143  - `status-api` 共享模块提取
144
145## 后续建议
146
1471. 先补一张专门任务卡，定义登录态记录模型和持久化位置。
1482. 再拆插件上报协议：
149   - 指纹
150   - `account`
151   - 端点
152   - freshness
1533. 最后再收口 `conductor` 查询面和浏览器代发面。