im_wower
·
2026-03-30
CONDUCTOR_UI_MODULE_REQUIREMENTS.md
1# Conductor UI 模块需求与流程调整
2
3日期：`2026-03-30`
4
5## 状态
6
7- `讨论后形成的正式规划文档`
8- 当前代码基线：`main@b1443f4`
9
10## 背景
11
12当前 `baa-conductor` 已经有比较完整的本地真相源和 HTTP 接口面，但缺少正式的人类操作 UI。
13
14现状存在两个结构性问题：
15
161. **业务操作没有正式入口**
17 - 人需要在 ChatGPT / Claude / Gemini 页面和 conductor 之间来回切换
18 - 很多闭环仍然依赖人工复制、粘贴、观察页面状态
19 - “频道”没有成为正式主体，人和 AI 不能在同一个业务线程里长期协作
20
212. **管理操作过度依赖插件页**
22 - 当前只有 Firefox 插件里的 `controller.html` 充当管理页
23 - 这会把“浏览器适配器职责”和“系统操作台职责”混在一起
24 - 导致很多本应走 `conductor` 正式接口的流程，退化成“开插件页、看日志、手动点动作”
25
26补充现状：
27
28- `conductor-daemon` 已有正式接口：`/describe`、`/v1/browser`、`/v1/browser/actions`、`/v1/browser/request`、`/v1/messages`、`/v1/executions`、`/v1/sessions`、`/v1/codex/*`
29- 当前只有一个很窄的 HTML 状态页：`GET /v1/status/ui`
30- 当前真正的管理 UI 仍是插件内的 [`plugins/baa-firefox/controller.html`](../plugins/baa-firefox/controller.html)
31
32## 问题定义
33
34如果继续沿用当前结构，后续会持续出现这些问题：
35
36- 新功能虽然有 API，但没有稳定的人类操作面
37- “业务流程”与“平台适配细节”混在一起，任务定义越来越难写清楚
38- 手动验收只能从插件和 AI 页面视角做，无法从正式产品流程视角验收
39- 文档、任务卡、handoff 会不断把插件页误写成主入口
40
41## 结论
42
43需要新增一个正式的 `UI 模块`，但**不需要新增一个独立常驻进程**。
44
45推荐方案：
46
47- 新建前端模块：`apps/conductor-ui/`
48- 构建结果由 `conductor-daemon` 同源托管
49- 正式访问路径建议：`/app`
50- 插件页 `controller.html` 降级为：
51 - 浏览器适配调试页
52 - 注入 / 诊断 / 本地 bridge 自检页
53 - 非正式主入口
54
55不推荐方案：
56
57- 再起一个独立的 UI daemon / server 作为长期进程
58
59原因：
60
61- `conductor-daemon` 已经是唯一真相源
62- UI 需要读取和写入的状态全部属于 `conductor`
63- 再拆一个常驻进程只会增加：
64 - 启动顺序
65 - 反向代理
66 - 鉴权
67 - 状态同步
68 - SSE / WS 转发
69 - 重启和部署复杂度
70
71所以，**代码目录独立，运行时附着在 conductor**，是当前阶段最稳妥的方案。
72
73## 目标
74
75新增 UI 模块后，要同时解决两类问题：
76
77### 1. 业务能力封装
78
79让“频道”成为正式主体。
80
81目标状态：
82
83- 人通过 UI 进入频道，而不是先进入 AI 网页
84- 频道里挂接 Claude / ChatGPT / Gemini / Codex 等成员
85- 人在频道里直接发消息
86- conductor 负责把消息投递到目标平台 / 会话
87- 回复、artifact、执行结果、诊断摘要回到同一频道线程
88
89### 2. 管理能力封装
90
91让系统操作通过 UI 完成，而不是依赖插件页。
92
93目标状态：
94
95- 查看浏览器 bridge / shell runtime / 登录态
96- 打开、聚焦、刷新、恢复 shell 页或业务页
97- 触发插件动作：reload、reconnect、request_credentials
98- 查看最近 action result、plugin log、ingest log、artifact 入口
99- 查看 codex / task / run 状态
100
101## 非目标
102
103这次 UI 模块规划不追求：
104
105- 替代浏览器侧 DOM 注入或 page-interceptor
106- 移除 Firefox 插件
107- 多用户权限系统
108- 独立公网部署的前端站点
109- 先做复杂的实时协同编辑
110
111需要明确：
112
113- UI 的职责是“正式人类操作面”
114- 插件的职责仍是“浏览器适配层”
115- ChatGPT / Claude / Gemini 的页面 DOM 注入能力仍然保留，因为平台投递和观察本来就依赖它
116
117## 架构分层
118
119新增 UI 后，系统职责应固定为三层：
120
121### 1. `conductor-daemon`
122
123职责：
124
125- 唯一真相源
126- 业务编排
127- 状态汇总
128- artifact / logs / channel / codex / browser API
129- UI 静态资源托管
130
131### 2. `conductor-ui`
132
133职责：
134
135- 正式人类入口
136- 业务工作台
137- 系统管理台
138- 读写正式 HTTP API
139
140### 3. `baa-firefox`
141
142职责：
143
144- 平台登录态元数据维护
145- shell 页与业务页收口
146- page-context request / final-message / proxy delivery
147- DOM fallback delivery
148- 诊断日志
149
150## UI 模块落位
151
152建议目录：
153
154```text
155apps/
156 conductor-ui/
157 src/
158 public/
159 package.json
160```
161
162建议运行模式：
163
164- 开发态：`conductor-ui` 可跑独立 dev server，并代理到 `http://100.71.210.78:4317`
165- 生产态：构建成静态资源，由 `conductor-daemon` 提供 `/app`
166
167建议正式入口：
168
169- `GET /app`
170- 保留 `GET /v1/status/ui` 作为只读健康页，不与新 UI 混用
171
172## UI 信息架构
173
174首版建议只做两个一级工作区：
175
176### 1. `Channels`
177
178这是正式业务入口。
179
180需要承载：
181
182- 频道列表
183- 频道详情
184- 频道消息流
185- 添加 / 移除成员
186- 直接发消息
187- 查看回复、artifact、执行结果
188- 最近关联页面或 route 摘要
189
190### 2. `Control`
191
192这是正式管理入口。
193
194需要承载：
195
196- 浏览器 bridge 状态
197- shell runtime
198- 平台登录态
199- 插件动作
200- 打开 / 刷新 / 恢复标签页
201- diagnostics / logs / recent action result
202
203首版不建议一开始就拆太多一级导航。`Artifacts`、`Codex`、`Diagnostics` 可以先作为二级页或抽屉，再决定是否升级为一级模块。
204
205## 领域模型调整
206
207做 UI 之后，必须把“频道”从概念提升为 `conductor` 正式领域模型。
208
209当前状态：
210
211- `baa-conductor` 里还没有旧版 `baa-server` 那种完整的 `/channels/*` 面
212- 现在更多是 browser / artifact / task / codex 的能力集合
213
214目标状态：
215
216- 频道是人类和 AI 的正式协作单元
217- platform conversation / browser route / artifact session 都是频道的从属或关联对象
218- 人类主路径是“进入频道并操作”，不是“进入平台页面并操作”
219
220## 做了 UI 之后必须调整的流程
221
222### 1. 人类操作流程
223
224当前：
225
226- 插件页是事实上的操作台
227- AI 页面承担部分业务入口
228
229调整后：
230
231- UI 是唯一正式人类入口
232- 插件页只用于浏览器侧调试
233- AI 页面是平台承载页，不再是系统操作台
234
235### 2. 业务流程
236
237当前：
238
239- 很多业务动作依赖人工在不同页面之间复制、粘贴、观察
240
241调整后：
242
243- 从频道发起消息
244- conductor 选择目标成员与投递路径
245- 平台回复回流到频道
246- artifact 结果附着在频道上下文中
247
248### 3. 管理流程
249
250当前：
251
252- reload / reconnect / restore / 打开新页面等动作大多从插件页执行
253
254调整后：
255
256- 这些动作通过 UI 调用 `POST /v1/browser/actions`
257- 插件只负责执行与回传结构化结果
258
259### 4. 手动验收流程
260
261当前：
262
263- 主要从插件和 AI 页面视角验收
264
265调整后需要拆成两层：
266
2671. 平台适配验收
268 - 仍检查 DOM 注入、page-interceptor、final-message、plugin log
2692. UI 业务流验收
270 - 从频道视角发消息
271 - 看消息是否进入频道
272 - 看回复 / artifact / 执行结果是否回到频道
273
274### 5. 文档流程
275
276做了 UI 之后，需要统一修正文档口径：
277
278- `README.md`
279 - 正式人类入口改为 `/app`
280- `HANDOFF.md`
281 - 插件页降级为 debug 页
282- 浏览器相关任务卡模板
283 - 增加“是否影响 UI 业务流”验收项
284- 手动验收清单
285 - 增加 UI 业务流验收步骤
286
287## 后端需要补的正式能力
288
289### 1. `UI bootstrap` 读面
290
291建议新增：
292
293- `GET /v1/ui/bootstrap`
294
295用途：
296
297- 一次返回首页需要的聚合数据
298- 避免 UI 首屏发太多散请求
299
300建议包含：
301
302- system status
303- browser summary
304- recent action results
305- recent tasks / runs
306- recent artifacts
307- feature flags / capability summary
308
309### 2. `UI event stream`
310
311建议新增：
312
313- `GET /v1/events/stream`
314
315用途：
316
317- 向 UI 统一推送：
318 - browser status 变化
319 - action result
320 - task / run 更新
321 - channel 新消息
322 - ingest 完成事件
323
324### 3. `channels` 正式接口
325
326建议新增正式面：
327
328- `GET /v1/channels`
329- `POST /v1/channels`
330- `GET /v1/channels/:channel_id`
331- `PATCH /v1/channels/:channel_id`
332- `DELETE /v1/channels/:channel_id`
333- `GET /v1/channels/:channel_id/messages`
334- `POST /v1/channels/:channel_id/messages`
335- `GET /v1/channels/:channel_id/messages/stream`
336- `GET /v1/channels/:channel_id/members`
337- `POST /v1/channels/:channel_id/members`
338- `DELETE /v1/channels/:channel_id/members/:member_id`
339
340### 4. 结构化日志读面
341
342建议新增：
343
344- `GET /v1/logs/plugin`
345- `GET /v1/logs/ingest`
346
347原因：
348
349- UI 不应直接读取 `logs/` 目录
350- `baa-plugin` / `baa-ingest` 需要正式 HTTP 读面才能接入 UI
351
352### 5. 现有接口复用
353
354以下接口应直接复用，不另起炉灶：
355
356- `GET /v1/browser`
357- `POST /v1/browser/actions`
358- `POST /v1/browser/request`
359- `GET /v1/messages`
360- `GET /v1/executions`
361- `GET /v1/sessions`
362- `GET /v1/codex/*`
363
364## 旧入口职责收缩
365
366### `plugins/baa-firefox/controller.html`
367
368收缩后定位：
369
370- 插件内调试页
371- bridge / 注入 / 日志 / 自检工具页
372
373不再作为：
374
375- 正式系统操作台
376- 正式业务入口
377
378### `GET /v1/status/ui`
379
380保留定位：
381
382- 极简健康页
383- 只读状态页
384
385不扩展为：
386
387- 完整业务与管理 UI
388
389## 分阶段落地建议
390
391### Phase 1：定边界
392
393- 新建 `CONDUCTOR_UI_MODULE_REQUIREMENTS.md`
394- 固定“代码独立、运行附着 conductor”的架构结论
395- 固定 `/app` 为正式入口
396- 固定“频道是主体，插件页降级为 debug 页”的口径
397
398### Phase 2：补后端读写面
399
400- `GET /v1/ui/bootstrap`
401- `GET /v1/events/stream`
402- `/v1/channels/*`
403- `/v1/logs/plugin`
404- `/v1/logs/ingest`
405
406### Phase 3：首版 UI 壳
407
408- `Overview`
409- `Channels`
410- `Control`
411
412### Phase 4：把人工操作迁移到 UI
413
414- 浏览器动作从 UI 触发
415- 状态读取从 UI 汇总
416- diagnostics 在 UI 内可读
417
418### Phase 5：收缩插件页职责
419
420- 更新文档
421- 更新任务模板
422- 更新手动验收模板
423
424## 验收标准
425
426当 UI 模块正式落地时，至少要满足以下标准：
427
428### 业务面
429
430- 人可以从 UI 创建频道
431- 人可以在 UI 中给频道发消息
432- 频道成员可包含 Claude / ChatGPT / Gemini / Codex
433- AI 回复与执行结果回到同一频道线程
434
435### 管理面
436
437- 人可以从 UI 查看浏览器 bridge 状态
438- 人可以从 UI 执行 tab open / reload / restore / reconnect 等动作
439- 人可以从 UI 看到最近 action result 和日志摘要
440
441### 流程面
442
443- 日常操作不再依赖插件 `controller.html`
444- 手动验收文档不再只写“插件页步骤”
445- `README` / `HANDOFF` / 任务卡模板的口径一致
446
447## 风险与注意事项
448
449### 1. 不要把 UI 做成另一个真相源
450
451UI 只能消费和调用 `conductor` 正式接口，不能在前端自己定义一套业务事实。
452
453### 2. 不要把插件页继续做大
454
455如果一边做 UI，一边继续给 `controller.html` 堆管理功能，最后只会有两个半成品入口。
456
457### 3. 不要误判 DOM 注入会消失
458
459UI 让人类操作解耦，但不意味着 ChatGPT / Claude / Gemini 的平台适配会消失。
460
461### 4. 频道模型不要直接照抄旧 `baa-server`
462
463旧版思路可参考，但当前 `baa-conductor` 的真相源、artifact、browser route、codex 能力面都不同，需要重新抽象。
464
465## 开放问题
466
467当前仍需后续明确的问题：
468
4691. 频道消息的存储是否直接复用现有 artifact / db 模块，还是新建独立表
4702. UI 是否需要登录与 token 机制，还是先仅提供本地可信环境访问
4713. channel member 的最小模型如何定义
4724. browser route、conversation、artifact session 与 channel 的关联模型如何落表
4735. `/v1/events/stream` 是统一 SSE 还是按模块拆分
474
475## 下一步
476
477这份文档确认后，下一步应做的不是直接写前端，而是先拆成两类落地任务：
478
4791. 后端模型与接口任务
4802. UI 模块实现任务
481
482建议在开始编码前，先补一轮更细的任务分解文档，把：
483
484- API 合同
485- channel 数据模型
486- UI 首版页面结构
487- 手动验收口径
488
489全部写清楚。