baa-conductor

commit

7526ab5

parent

b1443f4

author

im_wower

date

2026-03-30 00:42:18 +0800 CST

docs: add conductor ui module requirements

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