baa-conductor

OPT-001-action-result-code-quality.md

 1# OPT-001: action_result 闭环代码质量优化
 2
 3日期：2026-03-27
 4来源：Claude 代码审查 commit 782e4c7
 5
 6---
 7
 8## OPT-A: request_id 字段命名风格不一致
 9
10### 问题
11
12`BrowserBridgeActionResultSnapshot` 接口定义 `request_id`（snake_case），但 Firefox 插件 WS 发送的是 `requestId`（camelCase）。firefox-ws.ts 的 `handlePluginActionResult` 做了归一化（`readFirstString(message, ["requestId", "request_id", "id"])`），功能不受影响。
13
14但接口层 snake_case 和插件层 camelCase 混用，增加维护困惑。
15
16### 建议
17
18统一为 snake_case（与 BrowserBridgeClientSnapshot 等其他快照接口一致）。插件侧发送时也改为 `request_id`，减少 conductor 侧的归一化分支。
19
20### 优先级
21
22Low
23
24---
25
26## OPT-B: test 文件中 buildShellRuntime 定义了两次
27
28### 问题
29
30`apps/conductor-daemon/src/index.test.js` 中：
31
321. 模块级 `buildShellRuntime(platform, overrides)` — tab_id=321
332. `createBrowserBridgeStub()` 内部 `buildShellRuntime(platform, overrides)` — tab_id=88
34
35两个函数功能几乎相同，只有默认值不同。内部那个遮蔽了外部那个。
36
37### 建议
38
39删除内部重复定义，统一使用模块级版本，通过 overrides 参数传入 stub 特有的默认值。
40
41### 优先级
42
43Low
44
45---
46
47## OPT-C: dispatchBrowserAction async 错误路径可加注释
48
49### 问题
50
51`dispatchBrowserAction` 内有两层错误处理：
52
531. 内层 `catch` — 捕获 bridge 同步抛出的错误（如 no_active_client、send_failed）
542. 外层 `handleBrowserActions` 的 `try/catch` — 捕获 `await dispatch.result` 的 rejection（如 action_timeout、client_disconnected）
55
56逻辑正确，两层分工合理，但没有注释说明。如果后续有人改动错误处理，可能不理解为什么有两层。
57
58### 建议
59
60在 `dispatchBrowserAction` 的 catch 块加一行注释：
61
62```typescript
63// 这里只捕获 dispatch 阶段的同步错误（bridge 不可用、发送失败）。
64// action_result 超时或连接断开的异步错误由 await dispatch.result 传播到调用方。
65```
66
67### 优先级
68
69Low