oh-my-opencode 背景代理全局并发上限 maxBackgroundAgents：从每模型限流到全局封顶的设计解析

本篇基于仓库中的 PR 设计文档 pr-description.md 展开，讲解 oh-my-opencode（oh-my-openagent 仓库的 OpenCode 插件包）如何为后台任务系统新增 maxBackgroundAgents 全局并发上限：从 BackgroundTaskConfigSchema 的 Zod 字段设计，到 ConcurrencyManager 中全局计数、跨模型排队与释放唤醒的改造思路，再到配套的 14 个测试用例与向后兼容策略。读完本文，你能掌握该功能的完整实现路径、配置方式与验证手段，并理解它与既有每模型/每 Provider 限流机制的交互关系。

一、背景：后台任务的并发限流现状

oh-my-opencode 的后台代理编排核心位于 packages/omo-opencode/src/features/background-agent/，其任务生命周期为：

LaunchInput → pending → [ConcurrencyManager queue] → running → polling → completed/error/cancelled/interrupt

限流的核心是 ConcurrencyManager（concurrency.ts）。它按“并发键（concurrency key）”维护每个模型的运行计数 counts 与 FIFO 等待队列 queues，键的推导规则见 getConcurrencyKey()（L42-L53）：

• 若配置了 modelConcurrency[model]，键为该模型全名；
• 否则若配置了 providerConcurrency[provider]（provider 取 model.split('/')[0]，如 anthropic/claude-sonnet-4 中的 anthropic），键为该 provider；
• 否则键就是模型本身。

单键并发上限的解析链在 getConcurrencyLimit()（L25-L40）中实现，优先级从高到低为：

1. modelConcurrency[model]
2. providerConcurrency[provider]
3. defaultConcurrency
4. 硬编码默认值 5

其中任一层的值设为 0 表示该层不限制（返回 Infinity）。acquire()（L55-L85）在满员时把请求挂入该键的 FIFO 队列；release()（L87-L109）优先把空出的槽位直接“移交（hand off）”给队首等待者（计数保持不变），没有等待者时才递减计数；cancelWaiter()/cancelWaiters() 用 settled 标志位防止“已 resolve 的条目被重复 reject”；clear() 在管理器清理时取消所有等待者并清空状态。这套机制的文档化说明见 packages/omo-opencode/src/features/background-agent/AGENTS.md 的“CONCURRENCY MODEL”一节（默认每键 5 并发、FIFO 排队、任务完成/出错/取消时释放槽位）。

二、问题定义：为什么需要全局上限

PR 文档在 Motivation 部分指出了这一模型的缺口：并发只按“模型/provider 键”限流（默认每键 5 个），但没有任何全局封顶。在资源受限的机器上，或者同时使用许多不同模型时，后台代理总数会随模型数量线性膨胀——5 per model x N models，理论上无上界。

maxBackgroundAgents 配置项的目标就是让用户能够设置一个跨所有模型/provider 的硬性总上限（global ceiling），与既有的每模型限制并行生效：一个任务必须同时拿到“每模型槽位”和“全局槽位”才能运行。

三、Schema 设计：BackgroundTaskConfigSchema 新增字段

改动位置是 background-task.ts。该文件当前定义了 background_task 配置对象的 Zod Schema（L9-L29），其中已有一批“限制类”字段：maxDepth、maxLiveDescendantsPerRoot、各类超时（staleTimeoutMs、taskTtlMs 等）与熔断器 circuitBreaker。

PR 设计按以下模式追加字段：

// 分组放在既有 limit 字段（maxDepth 等）附近
/** Maximum number of background agents that can run simultaneously
 *  across all models/providers (default: no global limit) */
maxBackgroundAgents: z.number().int().min(1).optional(),

设计要点（结合 执行计划 中的 Design Decisions）：

决策	理由
类型 z.number().int().min(1).optional()	与 maxDepth 等既有整数限制字段模式一致；min(1) 排除 0 和负数
不加 .default()	缺省语义是“无全局限制”（Infinity），该回退逻辑放在 ConcurrencyManager 的 getGlobalLimit() 中，而非 Schema 默认值
命名采用 camelCase	与 defaultConcurrency、maxDepth 等 background_task 段内字段的用户面 JSONC 键命名约定一致
可选字段	现有所有消费方保持兼容，无需配置迁移

由于类型通过 z.infer<typeof BackgroundTaskConfigSchema> 推导（background-task.ts L31），新增字段后 BackgroundTaskConfig 类型会自动包含 maxBackgroundAgents，下游无需改类型。而根配置 oh-my-opencode-config.ts 已通过 background_task: BackgroundTaskConfigSchema.optional() 组合该 Schema，因此配置加载链路（配置文件 → Schema 解析 → BackgroundManager 构造参数 → ConcurrencyManager 构造参数）全程无需额外改动。

四、ConcurrencyManager 的核心改造

改动集中在 concurrency.ts。PR 文档列出的改动点如下，逐条对应到类结构中：

4.1 全局计数与上限读取

private globalCount = 0 // 跨所有并发键的活跃代理总数

getGlobalLimit(): number {
  const limit = this.config?.maxBackgroundAgents
  if (limit === undefined) {
    return Infinity // 未配置 = 不启用全局限制
  }
  return limit
}

getGlobalLimit() 缺省返回 Infinity 是关键：未配置 maxBackgroundAgents 时，acquire()/release() 走快路径（limit === Infinity 直接放行/跳过计数），行为与改造前完全一致，这就是向后兼容的落点。

4.2 acquire()：双限制检查

改造后的 acquire() 需同时检查每模型容量与全局容量：

async acquire(model: string): Promise<void> {
  const perModelLimit = this.getConcurrencyLimit(model)
  const globalLimit = this.getGlobalLimit()

  // 快路径：两个限制都不受约束
  if (perModelLimit === Infinity && globalLimit === Infinity) return

  const currentPerModel = this.counts.get(model) ?? 0
  if (currentPerModel < perModelLimit && this.globalCount < globalLimit) {
    this.counts.set(model, currentPerModel + 1)
    if (globalLimit !== Infinity) this.globalCount++
    return
  }

  // 任一限制已满 → 进入该模型的 FIFO 队列等待
  // （复用既有 QueueEntry settled-flag 模式，L9-L14）
  return new Promise<void>((resolve, reject) => { /* ... */ })
}

注意 globalCount 只在 globalLimit !== Infinity 时才自增——未配置全局上限时连计数开销都省掉。等待入口复用现有的 QueueEntry settled 标志模式，保证 cancelWaiters() 不会 reject 已被 release() 唤醒的条目。

4.3 release()：跨模型唤醒

这是设计中最微妙的一步。release(model) 的顺序为：

1. 每模型移交优先：先尝试把槽位交给同一模型队列中的等待者（与现有 L92-L102 的逻辑一致，计数不变）；
2. 无同模型移交时，递减该模型的 counts，并（在配置了全局上限时）递减 globalCount；
3. 跨模型排空（drain）：全局容量空出后，遍历其他模型的队列，唤醒那些“每模型容量充足、仅被全局上限挡住”的等待者——即 验证策略 中“Release from one model unblocks different model”这一行为。

配套改动：clear() 重置 globalCount 并取消全局等待中的条目；新增 getGlobalCount() / getGlobalQueueLength() 两个调试/测试辅助方法，与既有 getCount()/getQueueLength()（L165-L174）保持同一风格。

实现上有一处值得注意的权衡：等待者被“全局上限”挡住时，是放进独立的 globalQueue，还是仍留在各自模型的队列里由 release() 统一排空？代码变更说明 给出了两种方案并自我修正——独立全局队列在移交时需要知道等待者对应的模型（需额外记录 model key），而保留单一每模型队列 + release 时跨模型 drain 的方案更简单也更不易出错。这说明该 PR 文档记录的是一个经过推敲的实现取舍过程。

五、配置使用示例

PR 文档给出的用户面配置（.opencode/oh-my-opencode.jsonc 的 background_task 段）：

{
  "background_task": {
    "maxBackgroundAgents": 5,
    "defaultConcurrency": 3
  }
}

更完整的组合示例（全局封顶 + 分层每模型限制）：

{
  "background_task": {
    // 全局上限：所有模型合计最多 5 个后台代理同时运行
    "maxBackgroundAgents": 5,
    // 每模型默认 3 个（独立于全局限制继续生效）
    "defaultConcurrency": 3,
    "providerConcurrency": {
      "anthropic": 2
    }
  }
}

该配置下的运行时语义：

• 任意时刻跨所有模型运行的后台代理总数 ≤ 5；
• 单个（非 Anthropic）模型 ≤ 3，Anthropic 下任意模型 ≤ 2；
• 当已有 2 个 Anthropic + 3 个 OpenAI 代理在跑（合计 5）时，即便各模型自身的每模型容量未满，新任务也只能排队。

仓库中 background_task 配置段的完整字段说明与“0 表示不限”的约定，可参考 docs/reference/configuration.md 的 concurrency 章节及示例配置 docs/examples/default.jsonc、docs/examples/coding-focused.jsonc。

六、测试策略：14 个用例覆盖两层验证

PR 文档将测试拆为两组，共 14 个用例，均沿用仓库既有的 given/when/then 命名风格。

6.1 Schema 验证（packages/omo-opencode/src/config/schema/background-task.test.ts，6 例）

测试用例	输入	预期
合法值	{ maxBackgroundAgents: 10 }	解析为 10
最小边界	{ maxBackgroundAgents: 1 }	解析为 1
低于最小值	{ maxBackgroundAgents: 0 }	抛 ZodError
负数	{ maxBackgroundAgents: -1 }	抛 ZodError
非整数	{ maxBackgroundAgents: 2.5 }	抛 ZodError
未提供	{}	字段为 undefined

这与现有测试文件 background-task.test.ts 中对 defaultConcurrency、maxDepth、syncPollTimeoutMs 的既有用例模式一致。

6.2 全局限制执行（packages/omo-opencode/src/features/background-agent/concurrency.test.ts，8 例）

测试用例	构造	预期
未配置 = 无全局限制	无 maxBackgroundAgents	getGlobalLimit() 返回 Infinity
读取配置值	maxBackgroundAgents: 3	getGlobalLimit() 返回 3
跨模型阻塞	全局 2，占用 model-a + model-b，再取 model-c	model-c 被阻塞，尽管其每模型容量充足
未达上限放行	全局 3，依次取 3 个不同模型	全部成功
每模型 + 全局交互	每模型 1、全局 3，对 model-a 二次 acquire	被每模型限制而非全局限制阻塞
释放解除阻塞	全局 1，占 model-a，排队 model-b，释放 model-a	model-b 获得槽位
未配置不执行	无全局配置，跨 6 个模型 acquire	全部成功
clear 重置	占 2 个后 clear()	getGlobalCount() 归 0

其中“跨模型阻塞”与“释放解除阻塞”两个用例是本次功能的核心行为契约：前者证明全局上限独立于每模型限制生效，后者证明一个模型的 release() 能唤醒另一个模型的等待者——这正是 4.3 节 drain 逻辑的目标。

6.3 验证命令

按 执行计划 的流程，验证顺序为：

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

七、向后兼容与边界行为

PR 文档的 Backward Compatibility 一节给出三条承诺，结合源码可逐一印证：

1. 未配置时行为与之前完全一致：getGlobalLimit() 返回 Infinity，acquire() 走快路径，不引入全局计数与队列语义；
2. 既有字段不受影响：defaultConcurrency、providerConcurrency、modelConcurrency 的解析链（getConcurrencyLimit()，concurrency.ts L25-L40）保持原样，全局限制只是在其之上叠加的第二道闸；
3. 无需配置迁移：新字段为可选，旧配置文件原样可用。

验证策略 还列出了关键边界行为的预期：

边界场景	预期行为
全局上限 > 所有每模型上限之和	全局限制永不触发（每模型限制更紧）
每模型限制更紧	每模型限制先阻塞
全局限制更紧	全局限制先阻塞
管理器关闭时存在全局等待者	clear() reject 所有等待者并重置全局计数
并发 acquire/release	无竞态（依赖 JS 单线程事件循环）

八、当前仓库状态与延伸阅读

需要说明的是：maxBackgroundAgents 是以 PR 设计文档形式存在于技能评测工作区（.agents/skills/work-with-pr-workspace/iteration-1/eval-1/）的方案描述。从当前仓库源码结构看，background-task.ts 与 concurrency.ts 中尚无 maxBackgroundAgents 字段与 globalCount 逻辑——即线上实现仍是“仅每模型/provider 限流（默认 5/键）”的基线版本。因此本文中的实现细节应视为待合入的设计方案，其价值在于完整展示了在既有 ConcurrencyManager 架构上叠加全局闸的改造方法：Schema 层一个可选 Zod 字段、管理器层计数/排队/唤醒三处改动、以及 14 个测试用例钉住行为契约。

继续深入可参考：

• packages/omo-opencode/src/features/background-agent/AGENTS.md：后台代理编排引擎的文件职责表与并发模型说明；
• docs/reference/configuration.md：background_task 各配置字段（含“0 = 不限”约定）的官方说明；
• packages/omo-opencode/src/features/background-agent/concurrency-normalized-key.test.ts 等测试文件：并发键归一化与取消/释放路径的既有测试基线。