baa-conductor

commit

12310df

parent

2ce8d18

author

codex@macbookpro

date

2026-03-26 11:41:31 +0800 CST

docs: prioritize browser bridge persistence

  1@@ -0,0 +1,109 @@
  2+# 浏览器桥接持久化新需求
  3+
  4+## 状态
  5+
  6+- `TODO`
  7+- 优先级：`high`
  8+- 记录时间：`2026-03-26`
  9+
 10+## 背景
 11+
 12+当前 Firefox 插件已经能发现登录态、账户和 API 端点，但 `conductor` 侧更偏内存态浏览器桥接摘要。
 13+
 14+新的目标不是保存原始凭证，而是把“哪些机器上的哪个浏览器已经具备可用登录态”持久化下来，供后续调度、状态判断和浏览器请求代发使用。
 15+
 16+## 核心结论
 17+
 18+- `conductor` 允许持久化 `account`
 19+- `conductor` 只持久化“凭证指纹”和端点元数据
 20+- `conductor` 不持久化原始 `cookie`、`token`、`header` 值
 21+- 浏览器侧只保留一个空壳标签页，不承载真实对话 UI
 22+- 业务请求走已拦截和已验证过的 API 端点，由浏览器侧代发
 23+
 24+## 需求目标
 25+
 26+1. 让 `conductor` 长期知道：
 27+   - 哪台机器
 28+   - 哪个浏览器
 29+   - 哪个平台
 30+   - 哪个 `account`
 31+   - 当前是否存在可用登录态
 32+2. 让这些信息在 `conductor` 重启后仍然存在。
 33+3. 让浏览器桥接从“页面对话驱动”收口到“登录态和 API 代理驱动”。
 34+
 35+## 必须持久化的内容
 36+
 37+- 平台：如 `claude` / `chatgpt` / `gemini`
 38+- 机器标识：如 host、node、device identity
 39+- 浏览器标识：如 `firefox`
 40+- 浏览器 client 标识
 41+- `account`
 42+- 凭证指纹：
 43+  - 仅用于判断“是否变更”
 44+  - 不可逆
 45+- 观测时间：
 46+  - `captured_at`
 47+  - `last_seen_at`
 48+- 新鲜度和状态：
 49+  - `fresh`
 50+  - `stale`
 51+  - `lost`
 52+- 已发现且可用的 API 端点列表
 53+- 端点最近验证时间
 54+
 55+## 明确不持久化的内容
 56+
 57+- 原始 `cookie`
 58+- 原始 `token`
 59+- 原始请求头值
 60+- 原始请求体
 61+- 页面内对话历史
 62+- 页面 UI 状态
 63+- 标签页业务语义
 64+
 65+## 浏览器侧需求
 66+
 67+- 每个平台最多维持一个空壳标签页或等价页面壳，用于保持登录环境和请求来源环境
 68+- 不再依赖页面对话功能作为正式能力
 69+- 插件继续负责：
 70+  - 发现登录态
 71+  - 发现 `account`
 72+  - 发现 API 端点
 73+  - 用原始凭证在浏览器本地代发请求
 74+- 插件向 `conductor` 上报的是元数据、指纹和端点，不是原始凭证值
 75+
 76+## `conductor` 侧需求
 77+
 78+- 提供持久化的浏览器登录态记录
 79+- 允许按平台、机器、浏览器、`account` 查询当前可用桥接能力
 80+- 能判断某条登录态记录是否过期、失联或被替换
 81+- 能关联“哪个浏览器 client 可以为哪个平台/账户代发请求”
 82+
 83+## 运行边界
 84+
 85+- 真正的上游请求仍由浏览器侧发起
 86+- `conductor` 不应因为数据库泄露而直接泄露会话凭证
 87+- 如果浏览器 client 断开，`conductor` 仍保留最近一次持久化记录，但要把状态标成非新鲜或离线
 88+
 89+## 不在本轮范围内
 90+
 91+- 完整的页面自动化
 92+- 页面聊天 UI 编排
 93+- 多标签并行对话管理
 94+- 把原始凭证迁移到 `conductor` 端直接发请求
 95+
 96+## 当前优先级判断
 97+
 98+- 这是新的主方向，优先级高于：
 99+  - `4318` wrapper 删旧
100+  - `status-api` 共享模块提取
101+
102+## 后续建议
103+
104+1. 先补一张专门任务卡，定义登录态记录模型和持久化位置。
105+2. 再拆插件上报协议：
106+   - 指纹
107+   - `account`
108+   - 端点
109+   - freshness
110+3. 最后再收口 `conductor` 查询面和浏览器代发面。

 1@@ -11,6 +11,16 @@
 2 - 当前活动任务见 `tasks/TASK_OVERVIEW.md`
 3 - `T-S001` 到 `T-S016` 已经合入主线
 4 
 5+## 当前状态分类
 6+
 7+- `已完成`：`T-S001` 到 `T-S016`
 8+- `当前 TODO`：浏览器桥接登录态与 API 端点元数据持久化
 9+- `低优先级 TODO`：`4318/status-api` 兼容层删旧与解耦
10+
11+当前新的主需求文档：
12+
13+- [`./BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`](./BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md)
14+
15 ## 当前状态
16 
17 - 部署目标：`mini` 单节点
18@@ -23,6 +33,7 @@
19 - `tests/control-api/` 当前只剩一份 legacy absence smoke 测试文件
20 - `status-api` 当前默认读 `BAA_CONDUCTOR_LOCAL_API` / `4317`，`BAA_CONTROL_API_BASE` 只保留为兼容覆盖入口
21 - `status-api` 当前结论是继续保留为显式 opt-in 的本地兼容包装层，不立即删除
22+- 浏览器桥接当前正在转向“登录态元数据持久化 + 浏览器本地代发请求”模型
23 
24 ## 当前在线面
25 
26@@ -43,6 +54,24 @@
27 - 单节点的 Nginx / DNS 计划脚本
28 - 迁移期兼容件：`apps/status-api`、`ops/cloudflare/**`、`tests/control-api/**`、`BAA_CONTROL_API_BASE`
29 
30+## 当前 TODO
31+
32+当前主 TODO：
33+
34+1. 按 [`./BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`](./BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md) 定义并实现浏览器桥接持久化模型：
35+   - `conductor` 持久化 `account`
36+   - 只保存凭证指纹，不保存原始值
37+   - 持久化已发现 API 端点
38+   - 浏览器侧只保留空壳标签页，不把页面对话作为正式能力
39+
40+## 低优先级 TODO
41+
42+下面这些继续保留，但不再是当前最高优先级：
43+
44+- 清理仍依赖 `4318` / `status-api` wrapper 的旧脚本、书签和运维说明
45+- 把 `conductor-daemon` 对 `status-api` 构建产物的复用提成共享模块
46+- 只有在完成上面两项后，才重新评估是否删除 `apps/status-api`
47+
48 ## 最近完成
49 
50 - `T-S001`：`codexd` transport 现在会在关闭前冲刷尾部缓冲区，`BUG-010` 已修复，`BUG-008` 不再作为独立未解问题保留
51@@ -76,6 +105,7 @@
52 
53 - `status-api` 继续保留为显式 opt-in 兼容层
54 - 现在不删除 `apps/status-api`
55+- 这组工作已降为低优先级 backlog
56 - 只有在清完 `4318` 调用方，并把 `conductor-daemon` 对 `status-api` 构建产物的复用提成共享模块之后，才适合讨论删除
57 
58 ## 当前仍需关注

 1@@ -11,6 +11,16 @@
 2 - 当前任务卡都放在本目录
 3 - 当前任务基线：`main@4796db4`
 4 
 5+## 状态分类
 6+
 7+- `已完成`：`T-S001` 到 `T-S016`
 8+- `当前 TODO`：浏览器桥接登录态与端点元数据持久化
 9+- `低优先级 TODO`：`4318/status-api` 兼容层删旧与解耦
10+
11+当前新的主需求文档：
12+
13+- [`../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`](../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md)
14+
15 ## 最近完成任务
16 
17 当前已完成的主线任务：
18@@ -45,7 +55,19 @@
19 
20 当前没有进行中的任务卡。
21 
22-下一步建议优先处理两件事：
23+## 当前 TODO
24+
25+当前最高优先级 TODO 只有一件事：
26+
27+1. 按 [`../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`](../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md) 收口新的浏览器桥接持久化需求：
28+   - `conductor` 持久化 `account`
29+   - 只持久化凭证指纹和端点元数据
30+   - 浏览器侧只保留空壳标签页
31+   - 正式请求通过已发现 API 端点由浏览器代发
32+
33+## 低优先级 TODO
34+
35+下面两件事先降级为低优先级 backlog，不作为当前主线：
36 
37 1. 盘点并清理仍依赖 `4318` wrapper 的旧脚本、书签和运维说明
38 2. 把 `conductor-daemon` 目前对 `status-api` 构建产物的复用提成共享模块，再评估是否删除 `apps/status-api`