oh-my-openagent 背景任务并发治理：从 PR 设计看 max_background_agents 全局上限的落地思路

本文以一份真实的 PR 设计文档为切入点，解析 oh-my-openagent 后台 Agent 并发控制体系的演进方向：为何按模型/Provider 限流之外还需要一个全局上限 max_background_agents，该配置如何在配置校验、并发计数与任务生命周期三个层面接入，以及如何在多 Provider 场景下避免后台 Agent 无限扩张耗尽系统资源。读完本文，你将理解现有 ConcurrencyManager 的按键限流与队列机制，并能复现该 PR 中描述的 schema 校验、限流强制与槽位释放的完整测试链路。

PR 概览：一个旋钮收拢所有后台 Agent

该 PR（基线分支 dev）的核心提案来自 PR 描述文档：

• 标题：feat: add max_background_agents config to limit concurrent background agents
• 目标：向 BackgroundTaskConfigSchema 新增 maxBackgroundAgents 字段（默认 5，最小 1），为所有模型/Provider 的后台 Agent 总量设置一个全局封顶值。

PR 摘要中承诺了三层改动：

1. Schema 层：在 BackgroundTaskConfigSchema 中增加 maxBackgroundAgents 字段（default: 5, min: 1）；
2. 强制层：在 BackgroundManager.launch() 与 trackTask() 中执行全局限制，触发上限时返回带描述性的错误信息；
3. 释放层：在任务完成、取消、出错与中断（interrupt）四条路径上释放全局槽位，防止槽位泄漏。

PR 文档给出的配置用法示例如下：

// .opencode/oh-my-opencode.jsonc
{
  "background_task": {
    "maxBackgroundAgents": 10  // default: 5, min: 1
  }
}

需要说明的是：以当前仓库主干状态检索源码，maxBackgroundAgents 尚未出现在配置 schema 与并发管理实现中，因此本文以该 PR 设计文档为准陈述其方案细节，并以仓库现有并发体系作为落地基座来剖析这套设计的上下文与接入点。

动机：按 Provider 限流留下的全局盲区

PR 文档指出的核心问题，正是当前仓库并发体系的真实边界。

现有的按模型/Provider 限流由 ConcurrencyManager 承担，实现位于 concurrency.ts。从源码结构看：

• getConcurrencyLimit(model) 按 model → provider → default 的优先级解析上限：先查 modelConcurrency[model]，再取 model.split('/')[0] 得到 Provider 名查 providerConcurrency[provider]，最后回退 defaultConcurrency，硬编码兜底值为 5（见 concurrency.ts）；
• 取值 0 表示不限制（Infinity），与 docs/reference/configuration.md 中"background_task 并发值设为 0 即无上限"的说明一致；
• acquire(model, taskId) 在当前计数达到上限时并不拒绝，而是将调用方压入 queues 等待队列（QueueEntry 带 settled 标志防止双重决议），由 release() 做槽位交接（hand-off）或计数递减。

问题在于：计数键（getConcurrencyKey）是按模型或 Provider 分桶的。假设某用户同时对 anthropic/claude-opus-4-6、openai/gpt-5、google/gemini-3 各开了 5 并发，每一桶都合规，但系统里实际运行着 15 个后台 Agent——没有任何一桶违规，总量却无界。PR 文档的动机陈述正是这一点：多 Provider 用户可能派生无上限的后台 Agent，耗尽系统资源。max_background_agents 就是为此提供的"单一旋钮"：无论 Agent 使用哪个模型，总并发数都被压在一个全局上限内。

接入点：launch() 与 trackTask() 双入口强制

从 PR 的改动清单看，强制逻辑选了两个入口：

文件	职责
src/config/schema/background-task.ts	新增 maxBackgroundAgents schema 字段
src/config/schema/background-task.test.ts	校验测试（合法值、边界值、非法值）
src/features/background-agent/concurrency.ts	全局计数器 + canSpawnGlobally() / acquireGlobal() / releaseGlobal()
src/features/background-agent/concurrency.test.ts	全局限制单元测试
src/features/background-agent/manager.ts	在 launch()、trackTask() 中强制全局上限；在 complete/cancel/error 路径释放

（表中路径为 PR 文档中的模块相对位置，对应本仓库 packages/omo-opencode 下的同名文件，例如 manager.ts、schema 文件。）

这两个入口在现有 BackgroundManager 中都是真实存在的任务生命周期节点：launch()（manager.ts）负责启动新的后台任务，trackTask()（manager.ts）负责登记/跟踪任务。选择在两者都强制，意味着无论是新派生的 Agent 还是被追踪纳入管理的任务，都会经过全局配额检查，形成双重闸门。

PR 中为并发模块设计的三个全局方法命名（canSpawnGlobally / acquireGlobal / releaseGlobal）与现有 ConcurrencyManager 的 acquire / release 语义形成对应关系：acquire 返回 Promise 走排队等待，而 acquireGlobal 配合 canSpawnGlobally 的语义更偏向"准入判断 + 立即失败"——PR 明确要求"触发上限时返回带描述性的错误信息"，这与按模型队列的"排队等槽位"行为有意区分：全局超限直接拒绝并给出可诊断的错误，而非让任务悬挂在全局队列里。

Schema 校验：与现有 background_task 字段族的关系

该字段将被并入现有的 BackgroundTaskConfigSchema（background-task.ts）。当前该 schema 已包含一组完整的后台任务治理字段，maxBackgroundAgents 是其中"并发维度"的补全：

• 并发类：defaultConcurrency、providerConcurrency、modelConcurrency（均 min(0)，0 = 不限制）、maxDepth、maxLiveDescendantsPerRoot；
• 超时/TTL 类：staleTimeoutMs（默认 180000，min 60000）、messageStalenessTimeoutMs（默认 1800000，min 60000）、taskTtlMs（默认 1800000，min 300000）、sessionGoneTimeoutMs（默认 60000，min 10000）、taskCleanupDelayMs（默认 600000，min 60000）；
• 熔断类：maxToolCalls（默认 200，min 10）与 circuitBreaker 子对象。

值得注意的是 PR 给 maxBackgroundAgents 设定的约束是 min: 1（而非既有并发字段的 min: 0）。可以推断其设计意图是：全局上限永远生效、不允许"0 = 无限"——因为该字段本身就是用来兜住无限扩张的，若允许 0 则失去兜底意义；默认 5 也与 ConcurrencyManager.getConcurrencyLimit() 的硬编码兜底值 5 保持一致，行为平滑。

PR 的测试章节要求对此做三类 schema 校验测试：合法值、边界值（如 1）、非法值（如 0、负数、非整数）。对应测试文件为 background-task.test.ts，其中已有同风格的 schema 校验用例可以参照。

槽位释放：四条终态路径防泄漏

并发限制类功能最容易翻车的不是"限制本身"，而是"释放"。PR 明确列出四条必须释放全局槽位的路径：

1. 完成（completion）；
2. 取消（cancellation）；
3. 出错（error）；
4. 中断（interrupt）。

现有代码库已为这些路径铺设了相当完善的清理基础设施，这也是该设计可落地的基础：

• ConcurrencyManager.cancelWaiter(model, taskId) 可按任务 ID 精确移除等待队列中的条目（concurrency.ts），cancelWaiters(model) / clear() 则用于模型级与全量清理，覆盖 shutdown 场景；
• 仓库中已存在针对各清理路径的专项测试，如 cancel-task-cleanup.test.ts、task-completion-cleanup.test.ts、manager-shutdown-global-cleanup.test.ts，说明"每条终态路径都要回收资源"是该模块一贯的工程纪律。

对全局计数器而言，这意味着 releaseGlobal() 必须在这四条路径上都被调用且不可重入双释放——与现有 QueueEntry.settled 标志防止双重决议是同一类问题：一旦某条路径漏释放，全局槽位计数只增不减，最终所有 launch() 都会撞上"描述性错误"，系统表现为"后台任务整体罢工"，排查成本高。PR 将释放逻辑与强制逻辑一并列入改动表，正是把泄漏防护做进了同一个变更单元。

验证与回归：PR 给出的测试矩阵

PR 文档给出了明确的验证命令（以 bun 为运行时）：

# schema 校验
bun test src/config/schema/background-task.test.ts

# 全局上限强制逻辑
bun test src/features/background-agent/concurrency.test.ts

# 类型检查与构建
bun run typecheck
bun run build

（执行前需进入对应包目录，如 packages/omo-opencode；其中测试文件在本仓库对应 concurrency.test.ts 与 background-task.test.ts。）

这套测试矩阵覆盖了三层风险：schema 层的取值合法性、并发层的准入/释放正确性、以及整仓的类型与构建完整性。

使用建议与适用前提

结合 docs/reference/configuration.md 与 docs/examples/default.jsonc 中 background_task 的既有配置惯例，给出几点实操建议（以 PR 落地后为准）：

• 优先级关系：现有并发解析优先级为 modelConcurrency > providerConcurrency > defaultConcurrency；maxBackgroundAgents 作为全局封顶，独立于该优先级之外——即使每个桶都调大，总量仍受全局值约束。理解这一点才能正确解释"为什么我把 Provider 并发调高了任务却被拒绝"；
• 与 0 语义的区分：既有并发字段 0 表示"无限"，而 maxBackgroundAgents 最小为 1，二者语义不可混用；
• 默认值 5 的含义：不配置时系统行为变化为"全局最多 5 个后台 Agent"。对于多 Provider 重度用户，这相当于一次显式的资源预算收紧，建议结合 taskTtlMs、staleTimeoutMs 等既有超时字段一并评估；
• 跨端注意：background_task（camelCase）是 OpenCode 插件侧的配置键，与共享/Senpi/Codex 侧的 task（snake_case：default_concurrency 等）是两个独立对象而非别名，这一点在 configuration.md 中有明确警告——全局上限若要在其他端生效，需按对应端的配置键另行评估。

小结

这份 PR 的价值不在于多写一个数字字段，而在于把 oh-my-openagent 后台 Agent 的并发模型从"分桶限流"补全为"分桶限流 + 全局预算"：schema 层以 min: 1 保证兜底语义，launch() / trackTask() 双入口保证无旁路，complete/cancel/error/interrupt 四路径释放保证槽位不泄漏。以当前仓库为准，全局上限字段尚未合入主干，但其依赖的 ConcurrencyManager 按键计数、队列交接与清理测试体系已经齐备，这套设计可以直接对照 concurrency.ts 与 manager.ts 的现有实现进行代码走读与落地验证。