baa-conductor

T-S022.md

  1# Task T-S022：实现 Firefox 空壳页 runtime 与插件管理动作
  2
  3## 直接给对话的提示词
  4
  5读 `/Users/george/code/baa-conductor/tasks/archive/T-S022.md` 任务文档，完成开发任务。
  6
  7如需补背景，再读：
  8
  9- `/Users/george/code/baa-conductor/plans/archive/FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md`
 10- `/Users/george/code/baa-conductor/plans/archive/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
 11- `/Users/george/code/baa-conductor/plans/discuss/DISCUSS-FIREFOX-BRIDGE-CONTROL.md`
 12- `/Users/george/code/baa-conductor/plugins/baa-firefox/README.md`
 13- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
 14- `/Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
 15- `/Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
 16
 17## 当前基线
 18
 19- 仓库：`/Users/george/code/baa-conductor`
 20- 分支：`main`
 21- 提交：`0f218b9`
 22- 开工要求：如需新分支，从当前 `main` 新切
 23
 24## 当前状态
 25
 26- `已完成`
 27
 28## 建议分支名
 29
 30- `feat/firefox-shell-runtime`
 31
 32## 目标
 33
 34让 Firefox 插件正式实现空壳页 runtime、desired/actual tab 状态模型和插件管理动作，为后续通用 browser API 链路提供稳定执行环境。
 35
 36## 背景
 37
 38浏览器桥接下一阶段不再把页面对话 UI 当主能力，而是以：
 39
 40- 空壳页
 41- 本地登录态
 42- 本地请求代发
 43- SSE 拦截
 44
 45作为主模型。
 46
 47这要求 Firefox 插件自己先把 runtime 管理能力做稳，包括：
 48
 49- 空壳页存在性
 50- WS 重连
 51- 页面重载
 52- tab 恢复
 53- 实际状态上报
 54
 55## 涉及仓库
 56
 57- `/Users/george/code/baa-conductor`
 58
 59## 范围
 60
 61- Firefox 插件管理页和 runtime 管理
 62- 平台空壳页的 desired/actual 状态模型
 63- 插件管理类动作
 64- 插件侧健康检查和状态上报
 65
 66## 路径约束
 67
 68- 首版每个平台最多一个空壳页
 69- 空壳页必须是目标平台一方页面，不能是 `about:blank`
 70- 默认健康检查至少覆盖：
 71  - tab 生命周期事件
 72  - `30s` 周期巡检
 73
 74## 推荐实现边界
 75
 76建议优先做：
 77
 78- `controller.js` 的 runtime 状态模型
 79- tab desired/actual 对比与恢复
 80- 管理页重载 / WS 重连 / tab 打开聚焦重载恢复
 81- 状态回报 payload
 82
 83## 允许修改的目录
 84
 85- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
 86
 87## 尽量不要修改
 88
 89- `/Users/george/code/baa-conductor/apps/conductor-daemon/`
 90- `/Users/george/code/baa-conductor/docs/api/`
 91- `/Users/george/code/baa-conductor/packages/db/`
 92- `/Users/george/code/baa-conductor/tests/`
 93
 94## 必须完成
 95
 96### 1. 实现空壳页 runtime
 97
 98- 每个平台最多维护一个空壳页
 99- 区分 `desired` 和 `actual`
100- 能检测页被关闭、失效或不可用
101
102### 2. 实现插件管理动作
103
104- 支持：
105  - `plugin_status`
106  - `ws_reconnect`
107  - `controller_reload`
108  - `tab_open`
109  - `tab_focus`
110  - `tab_reload`
111  - `tab_restore`
112
113### 3. 上报真实状态
114
115- 插件上报的状态要反映实际页面状态
116- `tab_restore` 语义要明确：
117  - 重建 `desired` 中存在但 `actual` 中缺失的空壳页
118
119## 需要特别注意
120
121- 本任务不负责 `conductor` 的 describe 和 HTTP 合同
122- 本任务不负责最终通用 SSE 协议集成
123- 不要把真实对话 UI 重新拉回主能力模型
124- 如果必须动到页面代发逻辑，只做最小支撑，不扩散范围
125
126## 验收标准
127
128- 插件具备空壳页 runtime 与 tab 恢复能力
129- 插件具备管理类动作处理能力
130- 插件状态上报能区分 `desired/actual`
131- `git diff --check` 通过
132
133## 推荐验证命令
134
135- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
136- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/content-script.js`
137- `node --check /Users/george/code/baa-conductor/plugins/baa-firefox/page-interceptor.js`
138- `git -C /Users/george/code/baa-conductor diff --check`
139
140## 交付要求
141
142完成后请说明：
143
144- 空壳页 runtime 如何建模
145- 管理类动作如何落到插件侧
146- `desired/actual` 如何同步
147- 跑了哪些验证
148- 还有哪些剩余风险
149
150## 最新接力说明
151
152- 本任务已完成，Firefox 插件侧已经把空壳页 runtime、`desired/actual` 和管理类 payload 准备好。
153- 当前剩余集成工作已经转入：
154  - `/Users/george/code/baa-conductor/tasks/archive/T-S023.md`
155  - `/Users/george/code/baa-conductor/tasks/archive/T-S024.md`
156
157## 当前残余风险
158
159- 这轮没有跑真实 Firefox 手工 smoke。
160- 还没实测“手动关 tab -> `tab_restore` -> WS 重连后状态回报”的浏览器端闭环。