- commit
- 81fa64c
- parent
- 12310df
- author
- codex@macbookpro
- date
- 2026-03-26 11:47:22 +0800 CST
docs: add browser bridge persistence tasks
5 files changed,
+534,
-6
+133,
-0
1@@ -0,0 +1,133 @@
2+# Task T-S017：定义浏览器登录态持久化模型与仓储
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S017.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
11+- `/Users/george/code/baa-conductor/packages/db/src/index.ts`
12+- `/Users/george/code/baa-conductor/ops/sql/schema.sql`
13+- `/Users/george/code/baa-conductor/ops/sql/migrations/0001_init.sql`
14+- `/Users/george/code/baa-conductor/packages/schemas/src/index.ts`
15+
16+## 当前基线
17+
18+- 仓库：`/Users/george/code/baa-conductor`
19+- 分支：`main`
20+- 提交：`12310df`
21+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
22+
23+## 建议分支名
24+
25+- `feat/browser-auth-record-model`
26+
27+## 目标
28+
29+为浏览器桥接新增可持久化的登录态元数据模型，只保存 `account`、凭证指纹和端点元数据，不保存原始凭证值。
30+
31+## 背景
32+
33+新的主需求已经从“页面对话驱动”转向“登录态元数据持久化 + 浏览器本地代发请求”。
34+
35+当前缺的第一块是稳定的数据模型和仓储接口。没有这层，后续 `conductor` 和插件都只能继续停留在内存态或临时协议上。
36+
37+## 涉及仓库
38+
39+- `/Users/george/code/baa-conductor`
40+
41+## 范围
42+
43+- 定义浏览器登录态持久化记录
44+- 补 SQL schema / migration
45+- 补 `packages/db` 仓储方法与测试
46+- 如有必要，补 `packages/schemas` 的共享类型
47+
48+## 路径约束
49+
50+- 本任务只负责持久化模型与仓储，不处理 `conductor-daemon` HTTP/WS 接入。
51+- 不修改 Firefox 插件实现。
52+- 不处理文档总收口，那是后续任务。
53+
54+## 推荐实现边界
55+
56+建议优先做：
57+
58+- 定义一条稳定的浏览器登录态记录，至少覆盖：
59+ - `platform`
60+ - `host` / `machine`
61+ - `browser`
62+ - `client_id`
63+ - `account`
64+ - `credential_fingerprint`
65+ - `captured_at`
66+ - `last_seen_at`
67+ - `status`
68+- 定义端点元数据记录，至少覆盖：
69+ - `platform`
70+ - `client_id`
71+ - `account`
72+ - `endpoints`
73+ - `updated_at`
74+- 给仓储补读取、upsert、失联/过期状态更新接口
75+
76+## 允许修改的目录
77+
78+- `/Users/george/code/baa-conductor/packages/db/`
79+- `/Users/george/code/baa-conductor/packages/schemas/`
80+- `/Users/george/code/baa-conductor/ops/sql/`
81+
82+## 尽量不要修改
83+
84+- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
85+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
86+- `/Users/george/code/baa-conductor/docs/`
87+
88+## 必须完成
89+
90+### 1. 定义持久化记录模型
91+
92+- 明确哪些字段会被长期保存
93+- 明确哪些字段绝对不能入库
94+- 让“凭证指纹”和“端点元数据”成为一等概念
95+
96+### 2. 补仓储与 migration
97+
98+- `packages/db` 提供稳定的读写接口
99+- SQL schema 和 migration 与仓储接口一致
100+- 不破坏现有 task/controller/run 等表
101+
102+### 3. 补测试
103+
104+- 至少覆盖新增记录的写入、读取、更新
105+- 至少覆盖状态从 `fresh` 到 `stale` 或等价状态的路径
106+
107+## 需要特别注意
108+
109+- 不要把原始 `cookie`、`token`、`header` 值写进任何持久化模型
110+- `account` 允许持久化，但要和凭证指纹、端点元数据分开建模
111+- 本任务可以和 `T-S018` 并行，但不要修改插件文件
112+
113+## 验收标准
114+
115+- 仓库里有明确的浏览器登录态持久化模型
116+- SQL schema / migration / repository 三者一致
117+- 测试能覆盖新增读写路径
118+- `git diff --check` 通过
119+
120+## 推荐验证命令
121+
122+- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/db test`
123+- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/db typecheck`
124+- `git -C /Users/george/code/baa-conductor diff --check`
125+
126+## 交付要求
127+
128+完成后请说明：
129+
130+- 修改了哪些文件
131+- 最终持久化模型包含哪些字段
132+- 明确排除了哪些敏感字段
133+- 跑了哪些测试
134+- 还有哪些集成依赖留给后续任务
+131,
-0
1@@ -0,0 +1,131 @@
2+# Task T-S018：把 Firefox 插件收口到空壳标签页并上报账号/指纹/端点
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S018.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
11+- `/Users/george/code/baa-conductor/plugins/baa-firefox/README.md`
12+- `/Users/george/code/baa-conductor/plugins/baa-firefox/manifest.json`
13+- `/Users/george/code/baa-conductor/plugins/baa-firefox/background.js`
14+- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
15+- `/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
16+- `/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
17+
18+## 当前基线
19+
20+- 仓库：`/Users/george/code/baa-conductor`
21+- 分支：`main`
22+- 提交：`12310df`
23+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
24+
25+## 建议分支名
26+
27+- `feat/firefox-shell-tab-metadata-reporting`
28+
29+## 目标
30+
31+把 Firefox 插件的正式能力收口到“空壳标签页 + 登录态元数据上报 + 浏览器本地代发请求”，不再把页面对话功能当成主能力。
32+
33+## 背景
34+
35+新的主需求明确要求：
36+
37+- 浏览器侧只保留空壳标签页
38+- 允许持久化 `account`
39+- 只上报凭证指纹和端点元数据
40+- 正式请求统一走已发现的 API 端点，由浏览器本地代发
41+
42+当前插件还保留了较多面向 Claude 页面会话和对话状态的逻辑，需要重新收口。
43+
44+## 涉及仓库
45+
46+- `/Users/george/code/baa-conductor`
47+
48+## 范围
49+
50+- 调整插件标签页策略到空壳模式
51+- 上报 `account`、凭证指纹和 API 端点元数据
52+- 收口页面对话状态相关逻辑
53+- 保留浏览器本地请求代发能力所需的最小原始凭证持有
54+
55+## 路径约束
56+
57+- 本任务只修改 Firefox 插件目录及其本地 README。
58+- 不修改 `conductor-daemon` 和 `packages/db`。
59+- 不在本任务里设计最终数据库 schema。
60+
61+## 推荐实现边界
62+
63+建议优先做：
64+
65+- 把每个平台的正式标签页模型收口成单个空壳页
66+- 明确插件向 `conductor` 上报的元数据：
67+ - `platform`
68+ - `account`
69+ - `credential_fingerprint`
70+ - `endpoints`
71+ - freshness / timestamps
72+- 把对话态、消息回读、页面 UI 状态降为非正式能力或直接移除
73+
74+## 允许修改的目录
75+
76+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
77+
78+## 尽量不要修改
79+
80+- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
81+- `/Users/george/code/baa-conductor/packages/db/`
82+- `/Users/george/code/baa-conductor/docs/api/`
83+
84+## 必须完成
85+
86+### 1. 收口空壳标签页模式
87+
88+- 正式能力不再依赖页面对话上下文
89+- 每个平台只需要一个空壳页或等价页面壳
90+- 标签页不再作为业务持久化单位
91+
92+### 2. 上报账号/指纹/端点元数据
93+
94+- 允许上报 `account`
95+- 只上报凭证指纹，不上报原始凭证值
96+- 上报已发现且可用于代发的 API 端点列表
97+
98+### 3. 保留浏览器本地代发边界
99+
100+- 浏览器本地仍可持有原始凭证用于代发
101+- 但这些原始值不能通过桥接协议回传给 `conductor`
102+
103+## 需要特别注意
104+
105+- 不要把原始 `cookie`、`token`、`header` 值发到 `conductor`
106+- 不要在没有说明的情况下保留“页面对话功能仍是正式能力”的旧口径
107+- 本任务可以与 `T-S017` 并行，但不要修改数据库模型
108+
109+## 验收标准
110+
111+- 插件正式模型已经收口到空壳标签页
112+- 插件能输出 `account`、凭证指纹和端点元数据
113+- 插件不再把页面对话状态当主能力
114+- `git diff --check` 通过
115+
116+## 推荐验证命令
117+
118+- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/background.js`
119+- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
120+- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
121+- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
122+- `git -C /Users/george/code/baa-conductor diff --check`
123+
124+## 交付要求
125+
126+完成后请说明：
127+
128+- 修改了哪些文件
129+- 空壳标签页模式最终怎么定义
130+- 上报了哪些元数据
131+- 明确禁止上报了哪些敏感值
132+- 还有哪些 `conductor` 侧对接依赖留给后续任务
+128,
-0
1@@ -0,0 +1,128 @@
2+# Task T-S019：让 conductor 持久化浏览器登录态并提供查询面
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S019.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
11+- `/Users/george/code/baa-conductor/tasks/T-S017.md`
12+- `/Users/george/code/baa-conductor/tasks/T-S018.md`
13+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/browser-types.ts`
14+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-ws.ts`
15+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
16+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
17+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
18+
19+## 当前基线
20+
21+- 仓库：`/Users/george/code/baa-conductor`
22+- 分支：`main`
23+- 提交：`12310df`
24+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
25+
26+## 建议分支名
27+
28+- `feat/conductor-browser-auth-persistence`
29+
30+## 目标
31+
32+让 `conductor` 接收并持久化浏览器登录态元数据，并提供稳定的查询视图，而不是只保留内存态浏览器桥接摘要。
33+
34+## 背景
35+
36+新需求要求 `conductor` 长期知道：
37+
38+- 哪台机器
39+- 哪个浏览器
40+- 哪个平台
41+- 哪个 `account`
42+- 哪些 API 端点当前可由浏览器代发
43+
44+当前 `conductor` 的浏览器桥接状态主要还是基于活跃 WS 连接的内存态快照，重启或 client 断开后不会长期保留。
45+
46+## 涉及仓库
47+
48+- `/Users/george/code/baa-conductor`
49+
50+## 范围
51+
52+- 调整 Firefox WS / browser bridge 的元数据接入
53+- 把接收到的登录态元数据写入持久层
54+- 提供 `conductor` 上的只读查询面
55+- 更新 `conductor-daemon` 测试
56+
57+## 路径约束
58+
59+- 本任务默认依赖 `T-S017` 提供的仓储能力。
60+- 本任务默认对接 `T-S018` 提供的插件元数据上报格式。
61+- 不在本任务里改 Firefox 插件实现。
62+- 不处理全量文档收口，那是后续任务。
63+
64+## 推荐实现边界
65+
66+建议优先做：
67+
68+- 让 WS bridge 能接收 `account`、凭证指纹和端点元数据
69+- 把持久化记录和当前活跃连接状态合并成可读视图
70+- 优先复用现有 `/v1/browser` 路由；只有在必要时再加新的只读路由
71+
72+## 允许修改的目录
73+
74+- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
75+
76+## 尽量不要修改
77+
78+- `/Users/george/code/baa-conductor/packages/db/`
79+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
80+- `/Users/george/code/baa-conductor/docs/`
81+
82+## 必须完成
83+
84+### 1. 接入并持久化浏览器登录态元数据
85+
86+- `conductor` 能接收 `account`
87+- `conductor` 能接收并保存凭证指纹
88+- `conductor` 能接收并保存端点元数据
89+
90+### 2. 提供可读查询面
91+
92+- 能按平台、浏览器、机器、`account` 观察当前桥接能力
93+- 能区分“当前活跃连接”和“仅持久化记录”
94+- 能正确表达 `fresh` / `stale` / `lost` 或等价状态
95+
96+### 3. 补测试
97+
98+- 至少覆盖活跃连接上报后持久化成功
99+- 至少覆盖断开后仍可读到持久化记录
100+- 至少覆盖敏感值不出现在对外读接口
101+
102+## 需要特别注意
103+
104+- 不要把原始凭证值暴露到 `/v1/browser` 或任何新读接口
105+- 不要把“标签页”继续当正式持久化主键
106+- 本任务应在 `T-S017`、`T-S018` 结果上做集成，不要反向改它们的写范围
107+
108+## 验收标准
109+
110+- `conductor` 重启后仍能保留浏览器登录态元数据
111+- 对外读接口只暴露 `account`、指纹和端点元数据，不暴露原始凭证值
112+- 测试覆盖新增持久化和查询路径
113+- `git diff --check` 通过
114+
115+## 推荐验证命令
116+
117+- `npx --yes pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon test`
118+- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
119+- `git -C /Users/george/code/baa-conductor diff --check`
120+
121+## 交付要求
122+
123+完成后请说明：
124+
125+- 修改了哪些文件
126+- `conductor` 现在持久化了哪些浏览器元数据
127+- 哪些读接口返回了这些数据
128+- 如何保证原始凭证值不会泄露
129+- 跑了哪些测试
+131,
-0
1@@ -0,0 +1,131 @@
2+# Task T-S020：回写浏览器桥接文档并补持久化 smoke
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S020.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
11+- `/Users/george/code/baa-conductor/tasks/T-S017.md`
12+- `/Users/george/code/baa-conductor/tasks/T-S018.md`
13+- `/Users/george/code/baa-conductor/tasks/T-S019.md`
14+- `/Users/george/code/baa-conductor/README.md`
15+- `/Users/george/code/baa-conductor/docs/api/README.md`
16+- `/Users/george/code/baa-conductor/docs/firefox/README.md`
17+- `/Users/george/code/baa-conductor/plugins/baa-firefox/README.md`
18+- `/Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
19+
20+## 当前基线
21+
22+- 仓库：`/Users/george/code/baa-conductor`
23+- 分支：`main`
24+- 提交：`12310df`
25+- 开工要求：不要从其他任务分支切出；如需新分支，从当前 `main` 新切
26+
27+## 建议分支名
28+
29+- `docs/browser-bridge-persistence-cutover`
30+
31+## 目标
32+
33+把浏览器桥接的正式口径改写成“登录态元数据持久化 + 空壳标签页 + 浏览器本地代发请求”，并补与之匹配的 smoke / 文档验收。
34+
35+## 背景
36+
37+在 `T-S017`、`T-S018`、`T-S019` 落地后，原来的文档口径会过时：
38+
39+- 以前更像页面对话和页面桥接
40+- 现在要收口成登录态记录、账户、指纹、端点元数据与浏览器代发
41+
42+如果文档和 smoke 不跟上，后续调用方仍会按旧模型理解插件和 `conductor`。
43+
44+## 涉及仓库
45+
46+- `/Users/george/code/baa-conductor`
47+
48+## 范围
49+
50+- 更新 README 和相关 docs
51+- 更新插件 README
52+- 更新 browser smoke 或等价回归检查
53+- 在任务总览里同步新的任务状态
54+
55+## 路径约束
56+
57+- 本任务默认在 `T-S017`、`T-S018`、`T-S019` 基础上收尾。
58+- 不再改数据库模型和插件核心协议。
59+- 如果 smoke 缺少必要钩子，只做最小补充，不回头大改实现。
60+
61+## 推荐实现边界
62+
63+建议优先做：
64+
65+- 改写正式需求口径
66+- 让 smoke 覆盖登录态元数据与持久化读取
67+- 清掉“页面对话是正式能力”的旧文案
68+
69+## 允许修改的目录
70+
71+- `/Users/george/code/baa-conductor/README.md`
72+- `/Users/george/code/baa-conductor/docs/`
73+- `/Users/george/code/baa-conductor/plugins/baa-firefox/README.md`
74+- `/Users/george/code/baa-conductor/tests/browser/`
75+- `/Users/george/code/baa-conductor/tasks/TASK_OVERVIEW.md`
76+- `/Users/george/code/baa-conductor/plans/STATUS_SUMMARY.md`
77+
78+## 尽量不要修改
79+
80+- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
81+- `/Users/george/code/baa-conductor/packages/db/`
82+- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
83+
84+## 必须完成
85+
86+### 1. 回写正式口径
87+
88+- 明确浏览器桥接正式能力是登录态元数据持久化和浏览器代发
89+- 明确只保存 `account`、凭证指纹和端点元数据
90+- 明确不保存原始凭证值
91+
92+### 2. 更新 smoke / 验收说明
93+
94+- browser smoke 要覆盖新的正式模型
95+- 至少能验证：
96+ - 元数据上报
97+ - 持久化存在
98+ - 读接口不泄露原始凭证值
99+
100+### 3. 同步任务状态
101+
102+- `tasks/` 和 `plans/` 里的当前 TODO 状态与新任务进度一致
103+- 不再让旧的 `4318/status-api` backlog 看起来像当前主线
104+
105+## 需要特别注意
106+
107+- 不要继续把页面对话、聊天 UI 或多标签会话写成插件主能力
108+- 不要在文档里模糊“浏览器本地代发”和“conductor 直接持凭证调用”的边界
109+- 这是收尾任务，优先讲清边界和验收口径
110+
111+## 验收标准
112+
113+- 文档与新需求一致
114+- browser smoke 与新正式模型一致
115+- `tasks/`、`plans/` 状态视图同步
116+- `git diff --check` 通过
117+
118+## 推荐验证命令
119+
120+- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
121+- `npx --yes pnpm -C /Users/george/code/baa-conductor smoke`
122+- `git -C /Users/george/code/baa-conductor diff --check`
123+
124+## 交付要求
125+
126+完成后请说明：
127+
128+- 修改了哪些文档和 smoke
129+- 正式口径现在如何表述
130+- 哪些旧文案被删除或降级
131+- 跑了哪些验证
132+- 还有哪些残余风险
+11,
-6
1@@ -57,13 +57,18 @@
2
3 ## 当前 TODO
4
5-当前最高优先级 TODO 只有一件事：
6+当前最高优先级 TODO 已拆成 4 张任务卡：
7
8-1. 按 [`../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`](../plans/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md) 收口新的浏览器桥接持久化需求：
9- - `conductor` 持久化 `account`
10- - 只持久化凭证指纹和端点元数据
11- - 浏览器侧只保留空壳标签页
12- - 正式请求通过已发现 API 端点由浏览器代发
13+1. [`T-S017.md`](./T-S017.md)：定义浏览器登录态持久化模型与仓储
14+2. [`T-S018.md`](./T-S018.md)：把 Firefox 插件收口到空壳标签页并上报账号/指纹/端点
15+3. [`T-S019.md`](./T-S019.md)：让 conductor 持久化浏览器登录态并提供查询面
16+4. [`T-S020.md`](./T-S020.md)：回写浏览器桥接文档并补持久化 smoke
17+
18+建议并行关系：
19+
20+- `T-S017` 与 `T-S018` 可并行
21+- `T-S019` 作为集成任务，默认接在 `T-S017`、`T-S018` 之后
22+- `T-S020` 作为文档和 smoke 收尾任务，默认接在 `T-S019` 之后
23
24 ## 低优先级 TODO
25