- commit
- 7ba57c9
- parent
- 07895cd
- author
- codex@macbookpro
- date
- 2026-03-26 20:00:09 +0800 CST
docs: add browser control closure task
3 files changed,
+173,
-11
+8,
-4
1@@ -6,7 +6,7 @@
2
3 ## 当前代码基线
4
5-- 主线基线：`main@5d4febb`
6+- 主线基线：`main@07895cd`
7 - 任务文档已统一收口到 `tasks/`
8 - 当前活动任务见 `tasks/TASK_OVERVIEW.md`
9 - `T-S001` 到 `T-S024` 已经完成
10@@ -14,7 +14,7 @@
11 ## 当前状态分类
12
13 - `已完成`：`T-S001` 到 `T-S024`
14-- `当前 TODO`：无高优先级主线任务
15+- `当前 TODO`：`T-S025`
16 - `低优先级 TODO`：`4318/status-api` 兼容层删旧与解耦
17
18 当前新的主需求文档：
19@@ -65,7 +65,7 @@
20
21 当前策略：
22
23-- 当前没有高优先级主线 blocker
24+- 当前主线任务是 `T-S025`：收口插件管理闭环与真实 Firefox 验收
25 - 当前不把大文件拆分当作主线 blocker
26 - 以下重构工作顺延到下一轮专门重构任务：
27 - `apps/conductor-daemon/src/local-api.ts`
28@@ -140,5 +140,9 @@
29 - 风控状态当前仍是进程内内存态；`conductor` 重启后，限流、退避和熔断计数会重置
30 - 正式 browser HTTP relay 当前仍只支持 Claude；其它平台目前只有空壳页和元数据链路，没有接入通用 request / SSE 合同
31 - 这轮还没跑真实 Firefox 手工 smoke，因此“手动关 tab -> tab_restore -> WS 重连后状态回报”的浏览器端闭环仍未实测
32-- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同；这两项已降为后续增量，不再算当前主线 blocker
33+- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同；这两项是 `T-S025` 的主收口内容
34 - 当前多个源码文件已超过常规体量，但拆分重构已明确延后到浏览器桥接主线收口之后再做
35+
36+## 下一步任务
37+
38+- `T-S025`：收口插件管理闭环与真实 Firefox 验收
+157,
-0
1@@ -0,0 +1,157 @@
2+# Task T-S025：收口插件管理闭环与真实 Firefox 验收
3+
4+## 直接给对话的提示词
5+
6+读 `/Users/george/code/baa-conductor/tasks/T-S025.md` 任务文档，完成开发任务。
7+
8+如需补背景，再读：
9+
10+- `/Users/george/code/baa-conductor/plans/FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md`
11+- `/Users/george/code/baa-conductor/tasks/T-S022.md`
12+- `/Users/george/code/baa-conductor/tasks/T-S023.md`
13+- `/Users/george/code/baa-conductor/tasks/T-S024.md`
14+- `/Users/george/code/baa-conductor/docs/api/control-interfaces.md`
15+- `/Users/george/code/baa-conductor/docs/api/firefox-local-ws.md`
16+- `/Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
17+
18+## 当前基线
19+
20+- 仓库：`/Users/george/code/baa-conductor`
21+- 分支：`main`
22+- 提交：`07895cd`
23+- 开工要求：如需新分支，从当前 `main` 新切
24+
25+## 当前状态
26+
27+- `TODO`
28+
29+## 建议分支名
30+
31+- `feat/browser-control-runtime-closure`
32+
33+## 目标
34+
35+把 Firefox 插件管理闭环真正接进 `conductor`：消费 `shell_runtime`、收口 richer 插件动作结果合同，并完成一轮真实 Firefox 手工 smoke。
36+
37+## 背景
38+
39+`T-S021` 到 `T-S024` 已经把通用 browser request / cancel / SSE 和插件管理动作接入主线，但还剩两条实际残余风险：
40+
41+- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同
42+- 真实 Firefox 手工 smoke 还没跑，因此“手动关 tab -> tab_restore -> WS 重连后状态回报”的浏览器端闭环仍未实测
43+
44+这两项都属于浏览器管理面的最后一公里。如果不收口，当前管理动作虽然已进入主线合同，但仍偏“代码就绪”，还不是“运行闭环已验收”。
45+
46+## 涉及仓库
47+
48+- `/Users/george/code/baa-conductor`
49+
50+## 范围
51+
52+- `conductor` 侧消费 `shell_runtime`
53+- 插件管理动作的 richer 结果合同
54+- `/v1/browser` 与 `/describe/control` 的控制读面同步
55+- browser-control 回归测试
56+- 真实 Firefox 手工 smoke 记录
57+
58+## 路径约束
59+
60+- 继续保留两层 describe：
61+ - `/describe/business`
62+ - `/describe/control`
63+- 不新增 `browser describe` 或 `plugin describe`
64+- 不改变当前通用 browser request / cancel / SSE 主合同
65+- 不把风控状态持久化并入本任务
66+- 不把多平台 relay 扩展并入本任务
67+
68+## 推荐实现边界
69+
70+建议优先做：
71+
72+- `conductor` 接入并持有 `shell_runtime` 的当前视图
73+- 浏览器管理动作返回结构化结果：
74+ - 动作是否接受
75+ - 动作是否完成
76+ - 失败原因
77+ - 关联平台 / client / tab 摘要
78+ - 新的 runtime 快照或最小状态摘要
79+- `/v1/browser` 和控制读面暴露新的 runtime / 动作结果信息
80+- 补自动化测试，并留出真实 Firefox 手工 smoke 记录位
81+
82+## 允许修改的目录
83+
84+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/`
85+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
86+- `/Users/george/code/baa-conductor/tests/browser/`
87+- `/Users/george/code/baa-conductor/docs/api/`
88+- `/Users/george/code/baa-conductor/docs/firefox/`
89+- `/Users/george/code/baa-conductor/tasks/`
90+- `/Users/george/code/baa-conductor/plans/`
91+
92+## 尽量不要修改
93+
94+- `/Users/george/code/baa-conductor/packages/db/`
95+- `/Users/george/code/baa-conductor/apps/status-api/`
96+- `/Users/george/code/baa-conductor/packages/host-ops/`
97+
98+## 必须完成
99+
100+### 1. 接入 `shell_runtime`
101+
102+- `conductor` 能消费插件上报的 `shell_runtime`
103+- `/v1/browser` 能返回当前 shell runtime 视图或等价摘要
104+- `/describe/control` 能描述这部分新的控制读面
105+
106+### 2. 收口插件动作结果合同
107+
108+- 浏览器管理动作不再只返回粗略 ack
109+- 至少要有结构化结果：
110+ - `accepted`
111+ - `completed`
112+ - `failed`
113+ - `reason`
114+ - 关联目标摘要
115+ - 结果状态摘要
116+- `conductor` 与插件侧合同保持一致
117+
118+### 3. 完成真实 Firefox 验收
119+
120+- 补一轮真实 Firefox 手工 smoke
121+- 至少覆盖：
122+ - 手动关闭平台 tab
123+ - `tab_restore`
124+ - WS 重连
125+ - 状态回报恢复
126+- 把结果写回任务卡或状态文档
127+
128+## 需要特别注意
129+
130+- 不要新增第三层 describe
131+- 不要在这个任务里顺手做风控状态持久化
132+- 不要把其它平台 request / SSE 接入并进来
133+- 如果插件侧已有 payload，优先让 `conductor` 兼容消费，不要重做一套协议
134+
135+## 验收标准
136+
137+- `shell_runtime` 已进入 `conductor` 控制读面
138+- 浏览器管理动作有结构化结果合同
139+- browser-control 自动化测试通过
140+- 真实 Firefox 手工 smoke 已完成并有结论记录
141+- `git diff --check` 通过
142+
143+## 推荐验证命令
144+
145+- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
146+- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
147+- `pnpm -C /Users/george/code/baa-conductor smoke`
148+- `git -C /Users/george/code/baa-conductor diff --check`
149+
150+## 交付要求
151+
152+完成后请说明：
153+
154+- `shell_runtime` 最终如何进入 `conductor`
155+- 插件动作结果合同最终长什么样
156+- 跑了哪些自动化验证
157+- 真实 Firefox 手工 smoke 覆盖了哪些步骤
158+- 还有哪些剩余风险
+8,
-7
1@@ -9,12 +9,12 @@
2 - `control-api.makefile.so`、Cloudflare Worker、D1 只剩迁移期 legacy 兼容残留和依赖盘点用途
3 - `baa-hand` / `baa-shell` 只保留为接口语义参考，不再作为主系统维护
4 - 当前任务卡都放在本目录
5-- 当前任务基线：`main@5d4febb`
6+- 当前任务基线：`main@07895cd`
7
8 ## 状态分类
9
10 - `已完成`：`T-S001` 到 `T-S024`
11-- `当前 TODO`：无高优先级主线任务
12+- `当前 TODO`：`T-S025`
13 - `低优先级 TODO`：`4318/status-api` 兼容层删旧与解耦
14
15 当前新的主需求文档：
16@@ -62,8 +62,7 @@
17
18 ## 当前活动任务
19
20-- 浏览器桥接第二阶段已完成主线收口
21-- 当前没有高优先级活动任务卡；如需继续推进，直接新开后续任务
22+- [`T-S025.md`](./T-S025.md)：收口插件管理闭环与真实 Firefox 验收
23
24 ## 当前主线收口情况
25
26@@ -89,13 +88,15 @@
27
28 当前已知主线遗留：
29
30-- 当前高优先级浏览器桥接任务已收口；后续若继续扩展，需单独新开任务卡
31 - 风控状态当前仍是进程内内存态；`conductor` 重启后，限流、退避和熔断计数会重置
32 - 正式 browser HTTP relay 当前仍只支持 Claude；其它平台目前只有空壳页和元数据链路，没有接入通用 request / SSE 合同
33 - runtime smoke 仍依赖仓库根已有 `state/`、`runs/`、`worktrees/`、`logs/launchd/`、`logs/codexd/`、`tmp/` 等本地运行目录；这是现有脚本前提，不是本轮功能回归
34-- 本地工作树里仍存在与本轮并行任务无关的 `plugins/baa-firefox/controller.js` 改动；后续开发继续避免覆盖它
35 - 这轮还没跑真实 Firefox 手工 smoke，因此“手动关 tab -> `tab_restore` -> WS 重连后状态回报”的浏览器端闭环仍未实测
36-- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同；这两项已降为后续增量，不再算当前主线 blocker
37+- `conductor` 还不会消费新增的 `shell_runtime` 字段，也没有 richer 的插件管理动作结果合同；这两项是 `T-S025` 的主收口内容
38+
39+下一步主线任务：
40+
41+1. [`T-S025.md`](./T-S025.md)：收口插件管理闭环与真实 Firefox 验收
42
43 ## 低优先级 TODO
44