baa-conductor

conductor-control.md

  1# Firefox Conductor Control
  2
  3`baa-firefox` 现在默认同时接两条固定链路：
  4
  5- 本地 WS bridge：`ws://100.71.210.78:4317/ws/firefox`
  6- 本地 HTTP 入口：`http://100.71.210.78:4317`
  7
  8管理页已经收口，只保留：
  9
 10- 本地 WS 状态
 11- 本地 HTTP 状态
 12- `Pause` / `Resume` / `Drain` 按钮
 13
 14不再允许用户手工编辑 WS 地址或 HTTP 地址。
 15
 16## 范围
 17
 18- `controller.html` / `controller.js`
 19  - Firefox 启动后自动连接本地 `/ws/firefox`
 20  - 启动后立即请求 `GET /v1/system/state`
 21  - HTTP 失败时自动退避重试，成功后恢复常规轮询
 22  - 消费服务端下发的 `open_tab`、`api_request`、`reload`
 23  - Claude send/current 走页面内 HTTP 代理，不做 DOM 自动化点击
 24  - 调用 `POST /v1/system/pause`
 25  - 调用 `POST /v1/system/resume`
 26  - 调用 `POST /v1/system/drain`
 27- `background.js`
 28  - Firefox 启动时确保 `controller.html` 标签页存在
 29  - 根据最新 HTTP control snapshot 更新扩展 badge
 30
 31## 固定地址
 32
 33- Local WS: `ws://100.71.210.78:4317/ws/firefox`
 34- Local HTTP: `http://100.71.210.78:4317`
 35
 36当前实现不再从 UI 或 storage 读取用户自定义地址；旧配置会被固定地址覆盖。
 37
 38## 默认连接行为
 39
 40- Firefox 启动时，`background.js` 会确保 `controller.html` 标签页存在。
 41- `controller.html` 启动后立即尝试连接本地 WS。
 42- WS 断开后按固定间隔自动重连；本地服务重启后，连接会自动恢复。
 43- `controller.html` 启动后也会立刻请求一次 `GET /v1/system/state`。
 44- HTTP 成功后按 `15` 秒周期继续拉取状态。
 45- HTTP 失败后按 `1` 秒、`3` 秒、`5` 秒快速重试，再切到每 `30` 秒一次的慢速重试。
 46- 服务恢复后自动回到正常已连接状态，不需要手工刷新页面。
 47
 48## WS 侧职责
 49
 50插件会向本地 WS 发送：
 51
 52- `hello`
 53- `credentials`
 54- `api_endpoints`
 55- `client_log`
 56
 57插件会消费服务端返回的：
 58
 59- `hello_ack`
 60- `state_snapshot`
 61- `action_result`
 62- `open_tab`
 63- `api_request`
 64- `request_credentials`
 65- `reload`
 66- `error`
 67
 68管理页中的 WS 卡片和 WS 详情面板直接展示这条本地 bridge 的连接状态、最近快照和服务端元数据。
 69
 70## Claude 浏览器链路
 71
 72正式 Claude 浏览器动作统一走 `conductor` HTTP：
 73
 74- `GET /v1/browser`
 75- `POST /v1/browser/claude/open`
 76- `POST /v1/browser/claude/send`
 77- `GET /v1/browser/claude/current`
 78
 79约束：
 80
 81- 当前正式只支持 `Claude`
 82- 依赖本地 `/ws/firefox` 已连接
 83- `send` / `current` 走页面内 HTTP 代理，不通过 DOM 冒充用户点击
 84
 85## HTTP 侧职责
 86
 87本地 HTTP 是管理页里控制状态的同步来源，也是控制按钮的写入通道。
 88
 89读取：
 90
 91- `GET /v1/system/state`
 92
 93写入：
 94
 95- `POST /v1/system/pause`
 96- `POST /v1/system/resume`
 97- `POST /v1/system/drain`
 98
 99写接口会带固定请求体字段：
100
101```json
102{
103  "requested_by": "browser_admin",
104  "source": "firefox_extension",
105  "reason": "human_clicked_pause",
106  "request_id": "uuid"
107}
108```
109
110## 管理页可见信息
111
112- WS 卡片：连接状态、最近快照、最近错误
113- HTTP 卡片：连接状态、当前 mode、最近成功/失败、下次重试
114- WS 详情：本地 bridge 的原始状态摘要
115- HTTP 详情：本地 `conductor-daemon` 的原始状态摘要
116
117不再展示：
118
119- 地址输入框
120- 手工重连按钮
121- 手工刷新按钮
122- 标签页/凭证/端点/日志面板
123
124## 验证建议
125
1261. 安装插件并启动 Firefox，确认 `controller.html` 自动打开。
1272. 打开管理页，确认：
128   - `本地 WS` 最终变成 `已连接`
129   - `本地 HTTP` 能显示 `已连接` 或自动重试中的明确状态
1303. 停掉本地 `conductor-daemon`，确认 WS 状态进入重连中；恢复服务后确认自动回到 `已连接`。
1314. 点击 `暂停` / `恢复` / `排空`，确认 HTTP 状态会更新 mode，且服务端状态与按钮动作一致。
1325. 运行 `./scripts/runtime/browser-control-e2e-smoke.sh`，确认 `status -> open -> send -> current` 链路能跑通。