oh-my-openagent: 背景代理并发上限 PR 的三重门禁验证策略与并发控制实现解析

本文围绕 oh-my-openagent（下称 omo）仓库中一份针对"背景代理全局并发上限（maxBackgroundAgents）"PR 的验证策略文档展开：它定义了从推送前本地校验，到 Gate A（CI）、Gate B（/review-work 五路并行审查代理）、Gate C（Cubic 机器人）三道门禁的完整验证闭环。读完本文，你将掌握该 PR 需要守护的核心技术点——背景代理（background agent）的并发控制实现与配置模型——以及一套可复用的"推送—CI—代理审查—机器人审查"验证循环方法论，并能对照仓库源码逐条核实每个门禁的检查依据。

验证对象：背景代理并发控制的现状与 PR 目标

这份验证策略（verification-strategy.md）服务于一个具体的功能改动：为 omo 的背景代理任务引入全局并发上限 maxBackgroundAgents（默认 5、最小 1），约束"整个插件同时运行的背景代理总数"，而不只是"每个模型各自的并发数"。理解这一点需要先看仓库中现有的并发控制实现：

• Zod 配置模式：背景任务的配置模型定义在 background-task.ts，BackgroundTaskConfigSchema 声明了 defaultConcurrency、providerConcurrency、modelConcurrency（按 provider/model 维度的并发数）、maxDepth、staleTimeoutMs、circuitBreaker 等字段；类型 BackgroundTaskConfig 通过 z.infer<typeof BackgroundTaskConfigSchema> 从 schema 自动推导，这正是验证策略中"Typecheck 失败时只需确认类型是自动推导的，无需手工改类型"这一条修复依据的出处。该模式经 schema.ts 的 export * from "./schema/background-task" 桶状导出对外暴露。
• 现有并发管理器：concurrency.ts 中的 ConcurrencyManager 按"模型"为 key 维护 counts（当前运行数）与 queues（等待队列）。getConcurrencyLimit() 的解析优先级为：modelConcurrency[model] → providerConcurrency[provider] → defaultConcurrency → 硬编码默认值 5（见 concurrency.ts 第 39 行）。acquire() 在未达上限时同步递增计数直接放行，超限则把 waiter 压入队列等待；release() 优先把手持槽位移交给队首等待者（计数不变），无人等待时才递减（见 concurrency.ts）。

PR 目标是在这一层之上叠加全局计数（文档中称为 globalRunningCount，配套 acquireGlobal() / releaseGlobal() / canSpawnGlobally() / getMaxBackgroundAgents() 方法）。需要说明的事实边界：以当前仓库快照检索，上述四个方法名与 maxBackgroundAgents 字段在源码中均无直接命中——从源码结构看，该 PR 对应的实现可能在合入后经历了重构或命名演进，但文档所描述的机制骨架（Zod 校验配置、同步计数 + 队列、默认值 5）与现存 ConcurrencyManager 的实现完全一致，本文以文档为主体、以现存源码为佐证来讲解。

推送前本地校验（Gate 0）

策略要求在每次 push 之前按顺序跑完三条检查：

bun run typecheck && bun test && bun run build

这三条命令均真实存在于仓库根 package.json：typecheck 为 tsgo --noEmit && bun run typecheck:script && bun run typecheck:packages，test 为 bun test，build 为 bun run script/build.ts。

针对本次改动，文档特别点出两个必须盯住的测试文件（仓库根相对路径）：

bun test src/config/schema/background-task.test.ts
bun test src/features/background-agent/concurrency.test.ts

对应仓库中的实际文件为 background-task.test.ts（覆盖 BackgroundTaskConfigSchema 的解析与默认值）和 concurrency.test.ts 配套的 concurrency.test.ts（覆盖 ConcurrencyManager 的 acquire/release/取消语义）。同目录下还有 concurrency-cancel-waiter.test.ts、concurrency-normalized-key.test.ts 等针对性用例，共同锁住并发槽位的边界行为——本地先跑通这些，是后面所有门禁不返工的前提。

Gate A：CI（ci.yml）

CI 实际执行什么

根据文档记载，ci.yml（工作流名为 CI）执行四类检查：

1. 测试（拆分执行）：重度使用 mock 的测试在独立的 bun test 进程中隔离运行，其余测试成批执行。当前 ci.yml 中可以看到对应的实现方式：每个操作系统把根测试套件拆成两个并行 job（见 ci.yml 中的注释 Every OS splits the root suite into two parallel jobs），其中主 job 运行 bun test packages/omo-opencode packages/memory-core。
2. 类型检查：bun run typecheck（tsc 系的 --noEmit 检查）。ci.yml 的 typecheck job 正是执行 bun run typecheck，且 job summary 明确写着 "Runs root bun run typecheck, including script and package checks"。
3. 构建：bun run build（产出 ESM + 声明文件 + schema）。
4. Schema 自动提交：若生成出的 JSON schema 发生变化，CI 会直接提交它。

如何监控

gh pr checks <PR_NUMBER> --watch

常见失败场景与修复（文档原表）

失败	可能原因	修复
Typecheck error	新字段与现有类型导入不匹配	确认 BackgroundTaskConfig 类型由 schema 自动推导，无需手工更新类型
Test failure	测试断言错误或缺少 import	修复测试，重新 push
Build failure	循环导入或缺少导出	检查 src/config/schema.ts 的桶导出（已通过 export * 再导出）
Schema auto-commit	生成的 JSON schema 发生了变化	拉取自动提交，必要时 rebase

其中 Build 失败一行的"桶导出"说法可对照源码验证：schema.ts 第 4 行确实是 export * from "./schema/background-task"，新增字段只要写进 BackgroundTaskConfigSchema 即自动进入对外类型面，不会引入新导出。

恢复路径

# 读取 CI 日志
gh run view <RUN_ID> --log-failed

# 修复、提交、推送
git add -A && git commit -m "fix: address CI failure" && git push

Gate B：review-work（5 个并行审查代理）

它检查什么

运行 /review-work 会启动 5 个后台子代理，各自职责如下（文档原表）：

代理	角色	对本 PR 的检查点
Oracle (goal)	目标/约束核验	maxBackgroundAgents 是否真正限制代理数量？默认是否为 5？最小是否为 1？
Oracle (quality)	代码质量	是否遵循既有模式？有无 catch-all 大文件？是否低于 200 LOC？测试是否为 given/when/then 风格？
Oracle (security)	安全审查	无注入向量、无不安全默认值、是否通过 Zod 做输入校验
Hephaestus (QA)	实操 QA	实际运行测试、跑 typecheck、验证 build
Hephaestus (context)	上下文挖掘	检查 git 历史与相关 issue，确保没有重复/冲突的 PR

通过标准

5 个代理全部通过才算通过，任何一个失败都会阻塞。

常见失败场景与修复（文档原表）

代理	可能问题	修复
Oracle (goal)	全局上限未在所有退出路径生效（完成、取消、错误、中断）	审计 manager.ts 中每个应当调用 releaseGlobal() 的状态迁移
Oracle (quality)	测试风格不符合 given/when/then	用 #given/#when/#then describe 嵌套重构测试
Oracle (quality)	文件超过 200 LOC	concurrency.ts 为 137 LOC + 约 25 行新增 ≈ 162 LOC，安全；manager.ts 虽大但只在既有方法上加约 20 行，不新增职责
Oracle (security)	整数溢出或负值	Zod 的 .int().min(1) 在配置解析期即拦截
Hephaestus (QA)	实际运行时测试失败	先本地跑通测试再 push

结合当前仓库可以补充两点佐证：其一，200 LOC 这条质量红线是刻意设计的——现存 concurrency.ts 当前为 175 行，仍守在该阈值内，文档写作期估算的 ~162 行与之一脉相承；其二，Zod 校验层是安全门禁的直接执行者，background-task.ts 中现有字段已大量使用 z.number().int().min(...) 约束（如 maxToolCalls 的 min(10)、staleTimeoutMs 的 min(60000)），为 maxBackgroundAgents 的 .int().min(1) 写法提供了现成范式。

恢复路径

# 读取审查代理的输出
background_output(task_id="<review-work-task-id>")

# 修复发现的问题
# ... 编辑文件 ...
git add -A && git commit -m "fix: address review-work feedback" && git push

Gate C：Cubic（cubic-dev-ai[bot]）

它检查什么

Cubic 是一个分析 PR diff 的自动化代码审查机器人，门禁通过的条件是它回复 "No issues found"。

常见失败场景与修复（文档原表）

问题	可能原因	修复
"Missing error handling"	某条错误路径漏调 releaseGlobal()	在漏掉的路径补上 releaseGlobal()
"Inconsistent naming"	字段名不符合约定	使用 maxBackgroundAgents（schema 中 camelCase，JSONC 配置中为 max_background_agents）
"Missing documentation"	新增公开方法无 JSDoc	为 canSpawnGlobally()、acquireGlobal()、releaseGlobal()、getMaxBackgroundAgents() 补 JSDoc
"Test coverage gap"	缺少边界用例	补上 Cubic 指出的具体测试

命名约定一行值得展开：omo 的配置面存在"TS schema 用 camelCase、用户侧 JSONC 用 snake_case"的双层命名，Cubic 正是按这一约定校验，出现命名类意见时按此对照即可快速定位。

恢复路径

# 读取 Cubic 的审查意见
gh api repos/code-yeongyu/oh-my-openagent/pulls/<PR_NUMBER>/reviews

# 逐条处理评论
# ... 编辑文件 ...
git add -A && git commit -m "fix: address Cubic review feedback" && git push

验证循环：按成本排序的门禁编排

文档给出了完整的验证循环伪代码，核心思想是把最便宜的门禁放在最前面，贵的（多代理审查、外部机器人）逐级后置，任何一级失败就修完回到循环顶部：

iteration = 0
while true:
  iteration++
  log("Verification iteration ${iteration}")

  # Gate A: CI (cheapest, check first)
  push_and_wait_for_ci()
  if ci_failed:
    read_ci_logs()
    fix_and_commit()
    continue

  # Gate B: review-work (5 agents, more expensive)
  run_review_work()
  if any_agent_failed:
    read_agent_feedback()
    fix_and_commit()
    continue

  # Gate C: Cubic (external bot, wait for it)
  wait_for_cubic_review()
  if cubic_has_issues:
    read_cubic_comments()
    fix_and_commit()
    continue

  # All gates passed
  break

# Merge
gh pr merge <PR_NUMBER> --squash --delete-branch

文档明确：不设迭代次数上限，循环持续运行，直到某一次迭代中三道门禁同时全绿，随后以 squash 方式合并并删除分支。这个编排与 CI 侧的实际行为一致——ci.yml 的失败分支都会写 job summary 并提示"打开第一个失败的测试或 package-build 步骤"，即每轮失败都指向一个明确的、可定位的修复入口，使"读日志 → 修复 → 重推"的循环单轮成本保持最低。

风险评估：并发槽位泄漏是最主要的真实风险

文档最后的风险表（原表保留）：

风险	概率	缓解措施
槽位泄漏（全局计数永不递减）	中	审计每条退出路径：tryCompleteTask、cancelTask、handleEvent(session.error)、startTask 的 prompt 错误、resume 的 prompt 错误
全局计数上的竞态	低	globalRunningCount 是同步的（单线程 JS），launch() 中检查与递增之间没有异步间隙
破坏既有行为	低	默认值为 5，与既有 per-model 默认相同；总代理数少于 5 的用户感知不到变化
manager.ts 超过 200 LOC	已超限	该文件已是约 1500 LOC 的编排核心类（多方法，豁免 200 LOC 红线）；本次改动只在既有方法上加约 20 行，不新增职责

对照当前源码可以对这三类风险做进一步印证：

1. 槽位泄漏的机制背景：ConcurrencyManager 的 QueueEntry 采用 settled-flag 模式防止双重决议——cancelWaiters() 不会 reject 一个已被 release() 决议的条目（见 concurrency.ts 的注释与 concurrency.ts 的 cancelWaiter() 实现）。全局计数同理：完成、取消、错误、中断四条路径必须各自恰好调用一次释放，任何一条路径漏掉（或重试路径重复释放）都会让计数永久偏高，最终表现为"代理池被静默占满"。文档把这条标为"中"概率，正是因为它是纯逻辑风险，无法靠类型系统兜底。
2. 竞态风险为何低：acquire() 中 counts.get(key) → counts.set(key, current + 1) 是同步代码，JavaScript 单线程模型下两个任务不可能插入到"检查—递增"之间（见 concurrency.ts）。全局计数只要沿用同样的同步写法，就不存在 check-then-act 的异步间隙——这是文档"概率：低"的直接依据。
3. 兼容性为何保守：getConcurrencyLimit() 的兜底返回值就是 5（concurrency.ts），所以"全局上限默认 5"对存量用户是零变化；只有显式配置更小值或总代理数超过 5 的场景才会观察到行为差异。
4. manager.ts 的规模豁免：文档写作期该文件约 1500 LOC；以当前仓库快照实测，manager.ts 已达 3249 行，进一步坐实了"它属于因承担大量编排方法而被豁免 200 LOC 红线的核心类"这一说法，也解释了为什么审查标准对它的要求是"只改既有方法、不新增职责"而非"控制总行数"。

小结：这套验证策略的可复用要点

• 门禁按成本排序：CI（秒~分钟级、机器判定）→ 多代理深度审查（分钟级、多维度）→ 外部机器人（等待异步评论），失败一律回到循环顶部，不设迭代上限；
• 配置改动靠 schema 推导类型：新增字段写进 Zod schema（background-task.ts）即自动进入类型面与桶导出（schema.ts），把"类型不匹配"类 CI 失败消灭在机制层面；
• 并发类改动的审查焦点固定为三类：所有状态退出路径是否恰好释放一次、检查—递增之间是否同步无间隙、默认值是否与存量行为兼容（默认 5 即来自 concurrency.ts 的既有兜底）；
• 质量红线前置：200 LOC/文件、given-when-then 测试结构、camelCase（schema）与 snake_case（JSONC）双层命名，都是可以在本地 push 前就自查完毕的硬约束。

按此策略执行的验证对象、测试文件与配置入口均可在仓库中直接定位：background-task.test.ts、concurrency.test.ts、concurrency.ts、manager.ts 与 ci.yml，可作为复现本文全部结论的核查路径。