im_wower
·
2026-03-28
T-S025.md
1# Task T-S025：收口插件管理闭环与真实 Firefox 验收
2
3## 直接给对话的提示词
4
5读 `/Users/george/code/baa-conductor/tasks/archive/T-S025.md` 任务文档，完成开发任务。
6
7如需补背景，再读：
8
9- `/Users/george/code/baa-conductor/plans/archive/FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md`
10- `/Users/george/code/baa-conductor/tasks/archive/T-S022.md`
11- `/Users/george/code/baa-conductor/tasks/archive/T-S023.md`
12- `/Users/george/code/baa-conductor/tasks/archive/T-S024.md`
13- `/Users/george/code/baa-conductor/docs/api/control-interfaces.md`
14- `/Users/george/code/baa-conductor/docs/api/firefox-local-ws.md`
15- `/Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
16
17## 当前基线
18
19- 仓库：`/Users/george/code/baa-conductor`
20- 分支：`main`
21- 提交：`07895cd`
22- 开工要求：如需新分支，从当前 `main` 新切
23
24## 当前状态
25
26- `已完成（2026-03-26）`
27- `2026-03-26`：代码闭环已接通；`shell_runtime`、结构化 `action_result`、`/v1/browser` 与 `/describe/control` 已同步落地。
28- `2026-03-26`：自动化验证已通过，包括 `apps/conductor-daemon/src/index.test.js` 和 `tests/browser/browser-control-e2e-smoke.test.mjs`。
29- `2026-03-26`：当日的真实 Firefox 手工 smoke 在当前机器上受阻；未发现 `Firefox.app`（已检查 `/Applications` 与 `~/Applications`），因此当日无法在本环境完成“真实 Firefox 手工验收”。
30- `2026-03-27`：后续代码跟进已补上“插件管理页启动 / 浏览器重开 / 扩展重载后自动恢复 desired shell tabs”，并支持把平台根页收进受管理 shell 集合。
31- `2026-03-27`：后续缺陷修复已补上 `ws_reconnect` 的 deferred 结果语义；当前 `action_result.completed` 不再在真正重连前提前为 `true`。
32- `2026-03-27`：后续拆卡 `T-S026` 已在真实 `Firefox.app` 上完成手工 smoke；`plugin_status`、`tab_open`、`tab_restore`、`ws_reconnect` 和“扩展重载后自动恢复”均已通过。
33
34## 建议分支名
35
36- `feat/browser-control-runtime-closure`
37
38## 目标
39
40把 Firefox 插件管理闭环真正接进 `conductor`：消费 `shell_runtime`、收口 richer 插件动作结果合同，并完成一轮真实 Firefox 手工 smoke。
41
42## 背景
43
44`T-S021` 到 `T-S024` 已经把通用 browser request / cancel / SSE 和插件管理动作接入主线，但还剩两条实际残余风险：
45
46- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同
47- 真实 Firefox 手工 smoke 还没跑，因此“手动关 tab -> tab_restore -> WS 重连后状态回报”的浏览器端闭环仍未实测
48
49这两项都属于浏览器管理面的最后一公里。如果不收口，当前管理动作虽然已进入主线合同，但仍偏“代码就绪”，还不是“运行闭环已验收”。
50
51## 涉及仓库
52
53- `/Users/george/code/baa-conductor`
54
55## 范围
56
57- `conductor` 侧消费 `shell_runtime`
58- 插件管理动作的 richer 结果合同
59- `/v1/browser` 与 `/describe/control` 的控制读面同步
60- browser-control 回归测试
61- 真实 Firefox 手工 smoke 记录
62
63## 路径约束
64
65- 继续保留两层 describe：
66 - `/describe/business`
67 - `/describe/control`
68- 不新增 `browser describe` 或 `plugin describe`
69- 不改变当前通用 browser request / cancel / SSE 主合同
70- 不把风控状态持久化并入本任务
71- 不把多平台 relay 扩展并入本任务
72
73## 推荐实现边界
74
75建议优先做：
76
77- `conductor` 接入并持有 `shell_runtime` 的当前视图
78- 浏览器管理动作返回结构化结果：
79 - 动作是否接受
80 - 动作是否完成
81 - 失败原因
82 - 关联平台 / client / tab 摘要
83 - 新的 runtime 快照或最小状态摘要
84- `/v1/browser` 和控制读面暴露新的 runtime / 动作结果信息
85- 补自动化测试，并留出真实 Firefox 手工 smoke 记录位
86
87## 允许修改的目录
88
89- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/`
90- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
91- `/Users/george/code/baa-conductor/tests/browser/`
92- `/Users/george/code/baa-conductor/docs/api/`
93- `/Users/george/code/baa-conductor/docs/firefox/`
94- `/Users/george/code/baa-conductor/tasks/`
95- `/Users/george/code/baa-conductor/plans/`
96
97## 尽量不要修改
98
99- `/Users/george/code/baa-conductor/packages/db/`
100- `/Users/george/code/baa-conductor/apps/status-api/`
101- `/Users/george/code/baa-conductor/packages/host-ops/`
102
103## 必须完成
104
105### 1. 接入 `shell_runtime`
106
107- `conductor` 能消费插件上报的 `shell_runtime`
108- `/v1/browser` 能返回当前 shell runtime 视图或等价摘要
109- `/describe/control` 能描述这部分新的控制读面
110
111### 2. 收口插件动作结果合同
112
113- 浏览器管理动作不再只返回粗略 ack
114- 至少要有结构化结果：
115 - `accepted`
116 - `completed`
117 - `failed`
118 - `reason`
119 - 关联目标摘要
120 - 结果状态摘要
121- `conductor` 与插件侧合同保持一致
122
123### 3. 完成真实 Firefox 验收
124
125- 补一轮真实 Firefox 手工 smoke
126- 至少覆盖：
127 - 手动关闭平台 tab
128 - `tab_restore`
129 - WS 重连
130 - 状态回报恢复
131- 把结果写回任务卡或状态文档
132
133## 需要特别注意
134
135- 不要新增第三层 describe
136- 不要在这个任务里顺手做风控状态持久化
137- 不要把其它平台 request / SSE 接入并进来
138- 如果插件侧已有 payload，优先让 `conductor` 兼容消费，不要重做一套协议
139
140## 验收标准
141
142- `shell_runtime` 已进入 `conductor` 控制读面
143- 浏览器管理动作有结构化结果合同
144- browser-control 自动化测试通过
145- 真实 Firefox 手工 smoke 已完成并有结论记录
146- `git diff --check` 通过
147
148## 推荐验证命令
149
150- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
151- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
152- `pnpm -C /Users/george/code/baa-conductor smoke`
153- `git -C /Users/george/code/baa-conductor diff --check`
154
155## 实施结果
156
157- `conductor-daemon` 现在会从 Firefox 插件 `credentials`、`api_endpoints` 和 `action_result` payload 中消费 `shell_runtime`，并把它挂进当前 client 视图、Claude 读面和 merged browser records。
158- `POST /v1/browser/actions` 不再只返回 dispatch ack；现在会等待插件回传结构化 `action_result`，并统一暴露：
159 - `accepted`
160 - `completed`
161 - `failed`
162 - `reason`
163 - `target`
164 - `result`
165 - `results`
166 - `shell_runtime`
167- Firefox 插件侧现在会为正式 browser/plugin 管理动作回传结构化 `action_result`；legacy `reload` 也会按是否带 `platform` 区分 `controller_reload` 与 `tab_reload`。
168- `/v1/browser` 现已带出：
169 - `current_client.shell_runtime`
170 - `current_client.last_action_result`
171 - `claude.shell_runtime`
172 - `records[].live.shell_runtime`
173- Firefox 插件现在会在管理页启动、浏览器重开或扩展重载后自动执行一次后台 `tab_restore`，恢复之前明确启用过、但当前缺失的 shell tab；如果用户手工打开 Claude `new`、ChatGPT 根页或 Gemini `app`，插件也会把它们纳入受管理 shell 集合。
174
175## 后续代码跟进
176
177- `2026-03-27`：提交 `25be868` 已补上启动时的受管 shell tab 自动恢复逻辑，收口了“插件重启后 desired 仍在、actual 丢失但没有自动调和”的空窗。
178- `2026-03-27`：同一轮跟进里，`verify-mini.sh` 的 wrapper 调用也改成数组参数拼装，降低空参数场景下的脚本调用风险。
179- `2026-03-27`：后续缺陷任务已修复 `BUG-014`，并补上 `ws_reconnect.completed === false` 的 smoke 断言；同日真机手工验收也已完成，剩余主线风险已转到 `T-S035` / `T-S036`。
180- `2026-03-27`：真实 Firefox 手工 smoke 的执行流程和记录模板已拆到 `/Users/george/code/baa-conductor/tasks/archive/T-S026.md`；同日已在真机完成验收并回写结果。
181- `2026-03-27`：其余两项工程化后续任务也已拆卡：
182 - `/Users/george/code/baa-conductor/tasks/archive/T-S027.md`：补 `browser-request-policy` stale `inFlight` 自愈清扫
183 - `/Users/george/code/baa-conductor/tasks/archive/T-S028.md`：把 ChatGPT browser relay 收口到正式合同
184
185## 自动化验证
186
187- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
188- `node --test /Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
189- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
190
191## 真实 Firefox 手工 Smoke 记录
192
193- 日期：`2026-03-26`、`2026-03-27`
194- 目标步骤：
195 - 手动关闭平台 tab
196 - `tab_restore`
197 - WS 重连
198 - 状态回报恢复
199- `2026-03-26` 结果：阻塞，未执行
200- `2026-03-26` 阻塞原因：当日机器未发现可启动的 `Firefox.app`（已检查 `/Applications`、`~/Applications` 和 Spotlight `org.mozilla.firefox` bundle id）。
201- `2026-03-27` 结果：通过
202- `2026-03-27` 记录来源：后续拆卡 `/Users/george/code/baa-conductor/tasks/archive/T-S026.md`
203- `2026-03-27` 结论：真实 Firefox 手工 smoke 已覆盖 `plugin_status`、`tab_open`、`tab_restore`、`ws_reconnect`、扩展重载自动恢复；其中 `ws_reconnect` 还额外完成了 `disconnect_ms=3000`、`repeat_count=3`、`repeat_interval_ms=500` 的 3 轮稳定性验证。
204
205## 交付要求
206
207完成后请说明：
208
209- `shell_runtime` 最终如何进入 `conductor`
210- 插件动作结果合同最终长什么样
211- 跑了哪些自动化验证
212- 真实 Firefox 手工 smoke 覆盖了哪些步骤
213- 还有哪些剩余风险