baa-conductor

T-S019.md

  1# Task T-S019：让 conductor 持久化浏览器登录态并提供查询面
  2
  3## 直接给对话的提示词
  4
  5读 `/Users/george/code/baa-conductor/tasks/archive/T-S019.md` 任务文档，完成开发任务。
  6
  7如需补背景，再读：
  8
  9- `/Users/george/code/baa-conductor/plans/archive/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
 10- `/Users/george/code/baa-conductor/tasks/archive/T-S017.md`
 11- `/Users/george/code/baa-conductor/tasks/archive/T-S018.md`
 12- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/browser-types.ts`
 13- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-ws.ts`
 14- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 15- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 16- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 17
 18## 当前基线
 19
 20- 仓库：`/Users/george/code/baa-conductor`
 21- 分支：`main`
 22- 文档基线提交：`81fa64c`
 23- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
 24
 25## 当前状态
 26
 27- `已完成`
 28- 当前作用：保留为实现与验收参考，不再作为当前待开发任务卡
 29
 30## 最新接力说明
 31
 32`T-S017`、`T-S018` 的并行改动已经在本地工作树里完成，当前这张任务卡只负责把它们接进 `conductor-daemon`。
 33
 34已经存在的前置产物：
 35
 36- `packages/db/` 已提供浏览器登录态与端点元数据仓储接口
 37- `ops/sql/` 已补浏览器登录态与端点元数据表
 38- Firefox 插件已经开始上报：
 39  - `account`
 40  - `credential_fingerprint`
 41  - `endpoints`
 42  - `endpoint_metadata`
 43  - `freshness` / `captured_at` / `last_seen_at`
 44
 45本任务已完成的核心收口项：
 46
 471. 把 `credentials` / `api_endpoints` WS 消息接到新的仓储写接口
 482. 在 `conductor` 读接口里合并“活跃 WS 连接视图”和“持久化记录视图”
 493. 在 WS 断连或心跳老化时更新 `fresh` / `stale` / `lost`
 504. 把 `conductor-daemon` 测试和 browser smoke 更新到新的上报格式与读接口断言
 51
 52工作树注意事项：
 53
 54- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js` 当前存在与本任务无关的本地改动
 55- 本任务不要顺手清理、覆盖或回退该文件
 56- 后续收尾任务如果需要读这里的实现，仍然要避免覆盖该文件
 57
 58## 建议分支名
 59
 60- `feat/conductor-browser-auth-persistence`
 61
 62## 目标
 63
 64让 `conductor` 接收并持久化浏览器登录态元数据，并提供稳定的查询视图，而不是只保留内存态浏览器桥接摘要。
 65
 66## 背景
 67
 68新需求要求 `conductor` 长期知道：
 69
 70- 哪台机器
 71- 哪个浏览器
 72- 哪个平台
 73- 哪个 `account`
 74- 哪些 API 端点当前可由浏览器代发
 75
 76当前 `conductor` 的浏览器桥接状态主要还是基于活跃 WS 连接的内存态快照，重启或 client 断开后不会长期保留。
 77
 78## 涉及仓库
 79
 80- `/Users/george/code/baa-conductor`
 81
 82## 范围
 83
 84- 调整 Firefox WS / browser bridge 的元数据接入
 85- 把接收到的登录态元数据写入持久层
 86- 提供 `conductor` 上的只读查询面
 87- 更新 `conductor-daemon` 测试
 88
 89## 路径约束
 90
 91- 本任务默认依赖 `T-S017` 提供的仓储能力。
 92- 本任务默认对接 `T-S018` 提供的插件元数据上报格式。
 93- 不在本任务里改 Firefox 插件实现。
 94- 不处理全量文档收口，那是后续任务。
 95
 96## 推荐实现边界
 97
 98建议优先做：
 99
100- 让 WS bridge 能接收 `account`、凭证指纹和端点元数据
101- 把持久化记录和当前活跃连接状态合并成可读视图
102- 在 WS 断连和老化场景下落库 `stale` / `lost`
103- 优先复用现有 `/v1/browser` 路由；只有在必要时再加新的只读路由
104
105## 允许修改的目录
106
107- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
108- `/Users/george/code/baa-conductor/tests/browser/`
109
110## 尽量不要修改
111
112- `/Users/george/code/baa-conductor/packages/db/`
113- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
114- `/Users/george/code/baa-conductor/docs/`
115
116## 必须完成
117
118### 1. 接入并持久化浏览器登录态元数据
119
120- `conductor` 能接收 `account`
121- `conductor` 能接收并保存凭证指纹
122- `conductor` 能接收并保存端点元数据
123- `conductor` 能接收插件侧新的 `freshness` / 时间戳字段
124- 对旧格式消息最多保留兼容读法，但不能阻断新格式接入
125
126### 2. 提供可读查询面
127
128- 能按平台、浏览器、机器、`account` 观察当前桥接能力
129- 能区分“当前活跃连接”和“仅持久化记录”
130- 能正确表达 `fresh` / `stale` / `lost` 或等价状态
131- 读接口里不能出现原始 `cookie` / `token` / `header` 值
132
133### 3. 补测试
134
135- 至少覆盖活跃连接上报后持久化成功
136- 至少覆盖断开后仍可读到持久化记录
137- 至少覆盖 WS 心跳老化后状态从 `fresh` 变成 `stale` 或 `lost`
138- 至少覆盖敏感值不出现在对外读接口
139
140## 需要特别注意
141
142- 不要把原始凭证值暴露到 `/v1/browser` 或任何新读接口
143- 不要把“标签页”继续当正式持久化主键
144- 本任务应在 `T-S017`、`T-S018` 结果上做集成，不要反向改它们的写范围
145- 如果必须读 Firefox 插件代码，只作为协议对接参考，不要在本任务里回写插件实现
146- 如果发现 `plugins/baa-firefox/controller.js` 的本地改动与集成点冲突，先保留它，再最小化调整 `conductor-daemon` 适配
147
148## 验收标准
149
150- `conductor` 重启后仍能保留浏览器登录态元数据
151- 对外读接口只暴露 `account`、指纹和端点元数据，不暴露原始凭证值
152- WS 断开后记录会变成 `stale` 或等价离线状态
153- 心跳老化后记录会进一步进入 `lost` 或等价状态
154- 测试覆盖新增持久化和查询路径
155- `@baa-conductor/conductor-daemon` 能在当前 workspace 做一次真实 build
156- `git diff --check` 通过
157
158## 推荐验证命令
159
160- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon test`
161- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
162- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
163- `git -C /Users/george/code/baa-conductor status --short`
164- `git -C /Users/george/code/baa-conductor diff --check`
165
166## 交付要求
167
168完成后请说明：
169
170- 修改了哪些文件
171- `conductor` 现在持久化了哪些浏览器元数据
172- 哪些读接口返回了这些数据
173- WS 断连和老化分别如何更新状态
174- 如何保证原始凭证值不会泄露
175- 跑了哪些测试