baa-conductor

commit

88dab15

parent

8936aa7

author

jiaozhiwang

date

2026-03-27 08:20:50 +0800 CST

docs: refine BUG-014/FIX-BUG-014 and update bugs README

 1@@ -2,43 +2,39 @@
 2 
 3 ## 现象
 4 
 5-当 conductor 通过 `POST /v1/browser/actions` 发送 `ws_reconnect` 动作时，插件立刻回传 `action_result` 报告 `completed: true, failed: false`，但实际的 WS 断开和重连在 80ms 后才发生。
 6+`POST /v1/browser/actions` 派发 `ws_reconnect` 后，conductor 收到 `action_result` 标记 `completed: true, failed: false`，但此时 WS 实际还没断开更没重连。真正的断开和重连在 80ms 后的 setTimeout 回调中才执行。
 7 
 8-- 哪个模块：`plugins/baa-firefox/controller.js`，`runPluginManagementAction()` 中 `ws_reconnect` 分支
 9+- 哪个模块：`plugins/baa-firefox/controller.js`，`runPluginManagementAction` 函数，ws_reconnect 分支
10 - 返回了什么：`completed: true`
11-- 预期：`completed` 应反映实际执行状态；WS 重连是异步的，不应在执行前就报完成
12-- 复现条件：任何 `ws_reconnect` 调用
13+- 预期：要么等重连完成后再报 completed，要么报 `completed: false` 表示异步执行中
14+- 复现条件：任何 ws_reconnect 调用
15 
16 ## 触发路径
17 
18 ```text
19-conductor POST /v1/browser/actions {action: "ws_reconnect"}
20-→ firefox-bridge dispatchWithActionResult
21-→ WS → controller.js
22+POST /v1/browser/actions {action: "ws_reconnect"}
23+→ conductor dispatchWithActionResult
24+→ WS → Firefox controller.js
25 → runPluginManagementAction("ws_reconnect")
26 → setTimeout(() => { closeWsConnection(); connectWs(); }, 80)  ← 非阻塞
27-→ 函数立刻返回 → .then() 发 action_result completed=true
28+→ 函数立即返回 → .then() 发 action_result(completed: true)
29 → 80ms 后才真正断开和重连
30 ```
31 
32 ## 根因
33 
34-`ws_reconnect` 的实际执行被放在 `setTimeout(..., 80)` 里延迟执行，但 `runPluginManagementAction` 在 setTimeout 注册后立刻返回，调用方的 `.then()` 立刻发出 `action_result(completed=true)`。
35+`ws_reconnect` 的 `setTimeout(..., 80)` 是非阻塞的，`runPluginManagementAction` 在 setTimeout 注册后立刻返回，调用链的 `.then()` 把结果当作「已完成」发给 conductor。
36 
37 ## 影响
38 
39-- 语义不准确：conductor 侧认为重连已完成，但此时 WS 可能还没断开
40-- 如果 conductor 在收到 completed=true 后立刻发送新命令，该命令可能在旧连接上被发出（80ms 窗口内）
41-- 后续自动化调度依赖 completed 语义做决策时可能产生误判
42+- conductor 侧收到 `completed: true` 后可能立即发后续请求，但 WS 此时正在断连过程中
43+- 自动化编排如果依赖 ws_reconnect 的 completed 语义来做顺序控制，会出问题
44+- 当前手动使用不易触发，但 task scheduler 上线后风险增大
45 
46 ## 严重度
47 
48 Low-Medium
49 
50-## 建议修复方向
51+## 关联
52 
53-方案 A：让 `ws_reconnect` 返回 `completed: false`，表示动作已接受但异步完成。conductor 侧通过后续 hello 消息确认重连成功。
54-
55-方案 B：把 setTimeout 改为同步执行 closeWsConnection，然后异步 connectWs，在 connectWs 的 onopen 回调里才发 action_result。
56-
57-方案 A 更简单，方案 B 语义更准确。
58+无前置依赖

 1@@ -1,4 +1,4 @@
 2-# FIX-BUG-014: ws_reconnect 提前报 completed=true
 3+# FIX-BUG-014: ws_reconnect completed 语义修复
 4 
 5 ## 关联 Bug
 6 
 7@@ -6,44 +6,44 @@ BUG-014-ws-reconnect-premature-completed.md
 8 
 9 ## 目标
10 
11-让 `ws_reconnect` 的 `action_result` 准确反映执行状态。
12+让 ws_reconnect 的 action_result 正确反映重连是否完成。
13 
14 ## 修改文件
15 
16-`plugins/baa-firefox/controller.js`
17+`plugins/baa-firefox/controller.js` — `runPluginManagementAction` 的 ws_reconnect 分支和调用链 `.then()` 处理
18 
19-## 修改方案（推荐方案 A）
20+## 修改方案
21 
22-在 `runPluginManagementAction` 的 ws_reconnect 分支中，让返回的 results 携带一个标记，使 `sendPluginActionResult` 生成 `completed: false`：
23+### 方案 A（推荐）：先发 action_result 再执行重连
24 
25-```javascript
26-case "ws_reconnect":
27-  addLog("info", "正在重连本地 WS", false);
28-  setTimeout(() => {
29-    closeWsConnection();
30-    connectWs({ silentWhenDisabled: true });
31-  }, 80);
32-  break;
33-```
34+在 WS 消息处理的 `.then()` 和 `.catch()` 中，对 ws_reconnect 特殊处理：
35 
36-在 `connectWs` 的 WS message handler 中，ws_reconnect 的 `.then()` 改为：
37+1. 在 `runPluginManagementAction` 返回后、`.then()` 调 `sendPluginActionResult` 时，把 ws_reconnect 的 `completed` 设为 `false`，表示「已接受，异步执行中」
38+2. 80ms 后 setTimeout 触发时，closeWsConnection + connectWs 正常执行
39+3. 重连成功后 conductor 通过 hello 消息感知新连接建立
40+
41+具体改动（connectWs 中的 `.then()` 回调，约第 3856 行附近）：
42 
43 ```javascript
44-}).then((result) => {
45+.then((result) => {
46   sendPluginActionResult(result, {
47     action: pluginAction.action,
48     commandType: pluginAction.commandType,
49-    completed: pluginAction.action === "ws_reconnect" ? false : true,
50     platform: pluginAction.platform,
51-    requestId: pluginAction.requestId
52+    requestId: pluginAction.requestId,
53+    // ws_reconnect 是异步执行的，completed 应为 false
54+    completed: pluginAction.action !== "ws_reconnect"
55   });
56 })
57 ```
58 
59-这样 conductor 收到 `completed: false, accepted: true`，知道动作已被接受但需要等后续 hello 确认。
60+### 方案 B：把 ws_reconnect 改为同步等待
61+
62+把 setTimeout 改为 await promise，等 closeWsConnection + connectWs 都完成后再返回。需要把 connectWs 改成返回 Promise（当前是 void）。改动较大，不推荐首版。
63 
64 ## 验收标准
65 
66-1. `ws_reconnect` 返回的 action_result 中 `completed` 为 `false`
67-2. 重连后 conductor 通过 hello 消息确认连接恢复
68-3. 其他 action 不受影响，仍返回 `completed: true`
69+1. `pnpm typecheck` 通过
70+2. `pnpm test` 通过
71+3. 手动测试：派发 ws_reconnect 后，action_result 返回 `completed: false`
72+4. WS 重连成功后 conductor 收到新的 hello 消息

 1@@ -20,19 +20,19 @@
 2 | BUG-011 | `BUG-011-*.md` | writeHttpResponse drain handler 永久挂起 | Medium-High | FIX-BUG-011.md |
 3 | BUG-012 | `BUG-012-*.md` | browser-request-policy waiter 死锁 | Medium | FIX-BUG-012.md |
 4 | BUG-013 | `BUG-013-*.md` | stream session timer 未清除 | Low | FIX-BUG-013.md |
 5-| BUG-014 | `BUG-014-*.md` | ws_reconnect 提前报 completed=true | Low-Medium | FIX-BUG-014.md |
 6+| BUG-014 | `BUG-014-*.md` | ws_reconnect 报 completed=true 但还没重连 | Low-Medium | FIX-BUG-014.md |
 7 
 8 修复优先级：BUG-011 > BUG-012 > BUG-014 > BUG-013
 9 
10 ## 优化建议
11 
12-| # | 文件 | 内容 |
13-|---|---|---|
14-| OPT-001 | `OPT-001-*.md` | action_result 命名风格、test 重复定义、async 错误路径注释 |
15+| # | 文件 | 内容 | 优先级 |
16+|---|---|---|---|
17+| OPT-001 | `OPT-001-*.md` | action_result 命名一致性、test 去重、async catch 注释 | Low |
18 
19 ## 编号规则
20 
21 - BUG-XXX：bug 报告
22 - FIX-BUG-XXX：对应修复任务卡（给 Codex 执行）
23-- OPT-XXX：优化建议（非紧急）
24+- OPT-XXX：优化建议（非紧急，按需执行）
25 - 编号按发现顺序递增，不复用