baa-conductor

commit

c772d0c

parent

d04922a

author

codex@macbookpro

date

2026-03-27 13:59:02 +0800 CST

docs: add bug fix task docs

  1@@ -0,0 +1,102 @@
  2+# Task T-BUG-011：修复 writeHttpResponse drain 等待挂起
  3+
  4+## 直接给对话的提示词
  5+
  6+读 `/Users/george/code/baa-conductor/tasks/T-BUG-011.md` 任务文档，完成开发任务。
  7+
  8+如需补背景，再读：
  9+
 10+- `/Users/george/code/baa-conductor/bugs/README.md`
 11+- `/Users/george/code/baa-conductor/bugs/BUG-011-writeHttpResponse-drain-handler-hangs.md`
 12+- `/Users/george/code/baa-conductor/bugs/FIX-BUG-011.md`
 13+
 14+## 建议分支名
 15+
 16+- `fix/bug-011-write-http-response`
 17+
 18+## 目标
 19+
 20+修复 `writeHttpResponse()` 在背压后客户端提前断开时可能永久挂起的问题，并补上可复现的自动化测试。
 21+
 22+## 背景
 23+
 24+当前 `apps/conductor-daemon/src/index.ts` 里的 `writeHttpResponse()` 在 `response.write(...)` 返回 `false` 后只等待 `drain`，没有同时处理 `close` / `error`。一旦客户端在 `drain` 触发前断开，协程可能永远不返回。
 25+
 26+## 涉及仓库
 27+
 28+- `/Users/george/code/baa-conductor`
 29+
 30+## 范围
 31+
 32+- 修复 `writeHttpResponse()` 的 drain 等待逻辑
 33+- 覆盖普通 body 写入和 `streamBody` 循环写入两条路径
 34+- 增加最小但有效的自动化测试
 35+
 36+## 路径约束
 37+
 38+优先在现有实现附近修复，不要为了这个任务引入新的抽象层或大范围重构。
 39+
 40+## 推荐实现边界
 41+
 42+建议新增：
 43+
 44+- 一个局部复用的等待 helper，例如 `awaitWritableDrainOrClose(...)`
 45+
 46+建议放到：
 47+
 48+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 49+
 50+## 允许修改的目录
 51+
 52+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 53+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 54+
 55+## 尽量不要修改
 56+
 57+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 58+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/browser-request-policy.ts`
 59+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
 60+
 61+## 必须完成
 62+
 63+### 1. 修复挂起点
 64+
 65+- 处理 `payload.body` 写入时的背压等待
 66+- 处理 `streamBody` 循环写入时的背压等待
 67+- `drain`、`close`、`error` 任一触发后都能正确清理 listener
 68+
 69+### 2. 保持旧行为
 70+
 71+- 正常慢客户端下仍能继续写完响应
 72+- 连接已关闭时不要继续写入或抛出新的未处理异常
 73+
 74+### 3. 补测试
 75+
 76+- 增加能覆盖 `write()` 返回 `false` 后提前断开的测试
 77+- 至少验证 handler 不会永久 pending
 78+
 79+## 需要特别注意
 80+
 81+- 不要只修一处，`writeHttpResponse()` 里两处 drain 等待都要覆盖
 82+- 不要引入 listener 泄漏
 83+- 不要把这次任务扩成 HTTP 层全面重构
 84+
 85+## 验收标准
 86+
 87+- 背压后客户端提前断开时，请求处理不会永久挂起
 88+- `payload.body` 和 `streamBody` 两条路径都被覆盖
 89+- 相关自动化测试通过
 90+
 91+## 推荐验证命令
 92+
 93+- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
 94+- `node --test /Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 95+
 96+## 交付要求
 97+
 98+完成后请说明：
 99+
100+- 修改了哪些文件
101+- 核心实现思路是什么
102+- 跑了哪些测试
103+- 还有哪些剩余风险

  1@@ -0,0 +1,109 @@
  2+# Task T-BUG-012：修复 browser-request-policy waiter 死锁
  3+
  4+## 直接给对话的提示词
  5+
  6+读 `/Users/george/code/baa-conductor/tasks/T-BUG-012.md` 任务文档，完成开发任务。
  7+
  8+如需补背景，再读：
  9+
 10+- `/Users/george/code/baa-conductor/bugs/README.md`
 11+- `/Users/george/code/baa-conductor/bugs/BUG-012-browser-request-policy-waiter-deadlock.md`
 12+- `/Users/george/code/baa-conductor/bugs/FIX-BUG-012.md`
 13+
 14+## 建议分支名
 15+
 16+- `fix/bug-012-browser-request-policy`
 17+
 18+## 目标
 19+
 20+避免 `browser-request-policy` 在 lease 未正常 `complete()` 时让后续请求永久挂起，并补上对应测试。
 21+
 22+## 背景
 23+
 24+当前 `BrowserRequestPolicyController` 的 waiter 没有超时保护；如果某次 lease 泄漏，对同一目标的后续请求可能一直卡在等待队列里。文档还要求核对调用方是否已用 `try/finally` 保证 `lease.complete()`。
 25+
 26+## 涉及仓库
 27+
 28+- `/Users/george/code/baa-conductor`
 29+
 30+## 范围
 31+
 32+- 修复 `browser-request-policy.ts` 的 waiter 永久等待问题
 33+- 核对并必要时补强 `local-api.ts` 中 lease 生命周期收口
 34+- 增加自动化测试覆盖超时或泄漏后的恢复行为
 35+
 36+## 路径约束
 37+
 38+优先做最小闭环修复：先解决死锁，再考虑防御性增强；不要顺手改浏览器桥接协议。
 39+
 40+## 推荐实现边界
 41+
 42+建议新增：
 43+
 44+- waiter 超时与清理逻辑
 45+- 针对 lease 生命周期的防御性测试
 46+
 47+建议放到：
 48+
 49+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/browser-request-policy.ts`
 50+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 51+
 52+如确实需要收口 lease 完成路径，可修改：
 53+
 54+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 55+
 56+## 允许修改的目录
 57+
 58+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/browser-request-policy.ts`
 59+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 60+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
 61+
 62+## 尽量不要修改
 63+
 64+- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
 65+- `/Users/george/code/baa-conductor/tests/browser/`
 66+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-bridge.ts`
 67+
 68+## 必须完成
 69+
 70+### 1. 消除永久等待
 71+
 72+- `acquireTargetSlot` 不能无限期等待
 73+- `acquirePlatformAdmission` 不能无限期等待
 74+- 超时后要把 waiter 从队列里清理掉
 75+
 76+### 2. 核对 lease 生命周期
 77+
 78+- 检查 browser request 执行路径是否总能走到 `lease.complete()`
 79+- 如果存在遗漏，使用最小改动补上 `try/finally`
 80+
 81+### 3. 补测试
 82+
 83+- 覆盖 waiter 超时或 slot 泄漏后的行为
 84+- 验证系统返回明确错误，而不是永久挂起
 85+
 86+## 需要特别注意
 87+
 88+- 不要只加 timeout 而不清理 waiters 数组
 89+- 不要破坏现有 policy snapshot 和 admission 数据结构
 90+- 如果引入新的错误码或错误文案，要和现有 `BrowserRequestPolicyError` 风格保持一致
 91+
 92+## 验收标准
 93+
 94+- 同一 target 的后续请求不会因为前一次 lease 泄漏而永久挂起
 95+- 超时路径能稳定返回错误
 96+- 相关自动化测试通过
 97+
 98+## 推荐验证命令
 99+
100+- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
101+- `node --test /Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
102+
103+## 交付要求
104+
105+完成后请说明：
106+
107+- 修改了哪些文件
108+- 核心实现思路是什么
109+- 跑了哪些测试
110+- 还有哪些剩余风险

  1@@ -0,0 +1,104 @@
  2+# Task T-BUG-014：修正 ws_reconnect 的 completed 语义
  3+
  4+## 直接给对话的提示词
  5+
  6+读 `/Users/george/code/baa-conductor/tasks/T-BUG-014.md` 任务文档，完成开发任务。
  7+
  8+如需补背景，再读：
  9+
 10+- `/Users/george/code/baa-conductor/bugs/README.md`
 11+- `/Users/george/code/baa-conductor/bugs/BUG-014-ws-reconnect-premature-completed.md`
 12+- `/Users/george/code/baa-conductor/bugs/FIX-BUG-014.md`
 13+
 14+## 建议分支名
 15+
 16+- `fix/bug-014-ws-reconnect-completed`
 17+
 18+## 目标
 19+
 20+让 `ws_reconnect` 的 `action_result.completed` 语义与真实执行时序一致，不再在真正重连前就回 `completed: true`。
 21+
 22+## 背景
 23+
 24+当前 Firefox 插件里的 `ws_reconnect` 是通过 `setTimeout(...)` 异步触发断开与重连，但上层 action_result 在函数返回后立即发送，导致 conductor 过早认为动作已经完成。
 25+
 26+## 涉及仓库
 27+
 28+- `/Users/george/code/baa-conductor`
 29+
 30+## 范围
 31+
 32+- 修正 Firefox 插件侧 `ws_reconnect` 的返回语义
 33+- 保证其他 plugin action 的完成语义不被回归
 34+- 增加最小但有效的验证
 35+
 36+## 路径约束
 37+
 38+优先在插件侧修复，尽量不要改 conductor 的 action 协议；除非现有协议无法表达延迟完成，才允许做最小配套改动。
 39+
 40+## 推荐实现边界
 41+
 42+建议新增：
 43+
 44+- 一个显式的 deferred / pending 完成标记，或等价的最小机制
 45+
 46+建议放到：
 47+
 48+- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
 49+
 50+如需补自动化验证，可修改：
 51+
 52+- `/Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
 53+
 54+## 允许修改的目录
 55+
 56+- `/Users/george/code/baa-conductor/plugins/baa-firefox/controller.js`
 57+- `/Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
 58+
 59+## 尽量不要修改
 60+
 61+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 62+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/firefox-bridge.ts`
 63+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts`
 64+
 65+## 必须完成
 66+
 67+### 1. 修正 ws_reconnect 返回语义
 68+
 69+- `ws_reconnect` 在真正完成前不能回 `completed: true`
 70+- conductor 侧仍能收到可用于追踪动作的结果
 71+
 72+### 2. 保证其他动作不回归
 73+
 74+- `plugin_status`、`tab_open`、`tab_focus`、`tab_reload` 等现有 action 保持原有语义
 75+
 76+### 3. 补验证
 77+
 78+- 至少覆盖 `ws_reconnect` 的结果语义
 79+- 如果已有 smoke 测试可复用，优先补到现有测试里
 80+
 81+## 需要特别注意
 82+
 83+- 不要把这个任务扩成完整的 reconnect 生命周期重构
 84+- 不要破坏现有 `hello` / 状态同步链路
 85+- 如果采用 deferred 标记，确保发送 `action_result` 的公共路径能正确识别
 86+
 87+## 验收标准
 88+
 89+- `ws_reconnect` 不会在实际重连前回 `completed: true`
 90+- 其他 plugin action 行为不回归
 91+- 相关自动化测试通过
 92+
 93+## 推荐验证命令
 94+
 95+- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
 96+- `node --test /Users/george/code/baa-conductor/tests/browser/browser-control-e2e-smoke.test.mjs`
 97+
 98+## 交付要求
 99+
100+完成后请说明：
101+
102+- 修改了哪些文件
103+- 核心实现思路是什么
104+- 跑了哪些测试
105+- 还有哪些剩余风险