后台并行任务：像团队一样工作

学完你能做什么

✅ 启动多个并行后台任务，让不同 AI 代理同时工作
✅ 配置并发限制，避免 API 限流和成本失控
✅ 获取后台任务结果，无需等待完成
✅ 取消任务，释放资源

你现在的困境

只有一个人在做事？

想象一下这个场景：

你需要让 Explore 代理查找代码库中的认证实现
同时让 Librarian 代理研究最佳实践
再让 Oracle 代理审查架构设计

如果按顺序执行，总耗时 = 10 分钟 + 15 分钟 + 8 分钟 = 33 分钟

但如果能并行呢？3 个代理同时工作，总耗时 = max(10, 15, 8) = 15 分钟，节省了 54% 的时间。

问题：默认情况下，OpenCode 一次只能处理一个会话。要实现并行，你需要手动管理多个窗口或等待任务完成。

解决：oh-my-opencode 的后台任务系统可以同时运行多个 AI 代理，并在后台追踪它们的进度，让你可以继续其他工作。

什么时候用这一招

使用后台任务系统可以提升效率的场景：

场景	示例	价值
并行研究	Explore 查找实现 + Librarian 查文档	3 倍速度完成研究
多专家审查	Oracle 审查架构 + Momus 验证计划	快速获得多角度反馈
异步任务	提交 Git commit 时同时进行代码审查	不阻塞主流程
资源受限	限制并发数避免 API 限流	控制成本和稳定性

Ultrawork 模式

在提示词中加入 ultrawork 或 ulw，会自动激活最大性能模式，包括所有专业代理和并行后台任务。无需手动配置。

🎒 开始前的准备

前置条件

开始本教程前，请确保：

已安装 oh-my-opencode（见安装教程）
已完成基础配置，至少有一个 AI Provider 可用
了解 Sisyphus 编排器的基础用法（见 Sisyphus 教程）

核心思路

后台任务系统的工作原理可以概括为三个核心概念：

1. 并行执行

后台任务系统允许你同时启动多个 AI 代理任务，每个任务在独立的会话中运行。这意味着：

Explore 查找代码
Librarian 查阅文档
Oracle 审查设计

三个任务并行运行，总耗时等于最慢的那个任务。

2. 并发控制

为避免同时启动太多任务导致 API 限流或成本失控，系统提供了三级并发限制：

优先级：Model > Provider > Default

示例配置：
modelConcurrency:     claude-opus-4-5 → 2
providerConcurrency:  anthropic → 3
defaultConcurrency:   所有 → 5

规则：

如果指定了 model 级限制，使用该限制
否则，如果指定了 provider 级限制，使用该限制
否则，使用默认限制（默认值 5）

3. 轮询机制

系统每 2 秒检查一次任务状态，判断任务是否完成。完成条件：

会话 idle（session.idle 事件）
稳定性检测：连续 3 次轮询，消息数不变
TODO 列表为空：所有任务都已完成

跟我做

第 1 步：启动后台任务

使用 delegate_task 工具启动后台任务：

markdown

启动并行后台任务：

1. Explore 查找认证实现
2. Librarian 研究最佳实践
3. Oracle 审查架构设计

并行执行：

为什么 这是演示后台任务最经典的使用场景。3 个任务可以同时进行，大幅节省时间。

你应该看到 系统会返回 3 个任务 ID：

Background task launched successfully.

Task ID: bg_abc123
Session ID: sess_xyz789
Description: Explore: 查找认证实现
Agent: explore
Status: pending
...

Background task launched successfully.

Task ID: bg_def456
Session ID: sess_uvwx012
Description: Librarian: 研究最佳实践
Agent: librarian
Status: pending
...

任务状态说明

pending：排队等待并发槽
running：正在执行
completed：已完成
error：出错
cancelled：已取消

第 2 步：检查任务状态

使用 background_output 工具查看任务状态：

markdown

查看 bg_abc123 的状态：

为什么 了解任务是否完成或仍在运行。默认不等待，立即返回状态。

你应该看到 如果任务仍在运行：

## Task Status

| Field | Value |
|--- | ---|
| Task ID | `bg_abc123` |
| Description | Explore: 查找认证实现 |
| Agent | explore |
| Status | **running** |
| Duration | 2m 15s |
| Session ID | `sess_xyz789` |

> **Note**: No need to wait explicitly - system will notify you when this task completes.

## Original Prompt

查找 src/auth 目录下的认证实现，包括登录、注册、Token 管理等

如果任务已完成：

Task Result

Task ID: bg_abc123
Description: Explore: 查找认证实现
Duration: 5m 32s
Session ID: sess_xyz789

---

找到了 3 个认证实现：
1. `src/auth/login.ts` - JWT 认证
2. `src/auth/register.ts` - 用户注册
3. `src/auth/token.ts` - Token 刷新
...

第 3 步：配置并发控制

编辑 ~/.config/opencode/oh-my-opencode.json：

jsonc

{
  "$schema": "https://code-yeongyu.github.io/oh-my-opencode/schema.json",

  "background_task": {
    // Provider 级并发限制（推荐设置）
    "providerConcurrency": {
      "anthropic": 3,     // Anthropic 模型最多同时 3 个
      "openai": 2,         // OpenAI 模型最多同时 2 个
      "google": 2          // Google 模型最多同时 2 个
    },

    // Model 级并发限制（优先级最高）
    "modelConcurrency": {
      "claude-opus-4-5": 2,    // Opus 4.5 最多同时 2 个
      "gpt-5.2": 2              // GPT 5.2 最多同时 2 个
    },

    // 默认并发限制（当上面都没配置时使用）
    "defaultConcurrency": 3
  }
}

为什么 并发控制是避免成本失控的关键。如果你没有设置限制，同时启动 10 个 Opus 4.5 任务，可能会瞬间消耗大量 API 配额。

推荐设置

对于大多数场景，推荐设置：

providerConcurrency.anthropic: 3
providerConcurrency.openai: 2
defaultConcurrency: 5

你应该看到 配置生效后，启动后台任务时：

如果已达到并发限制，任务会进入 pending 状态排队
一旦有任务完成，排队的任务会自动启动

第 4 步：取消任务

使用 background_cancel 工具取消任务：

markdown

取消所有后台任务：

为什么 有时任务卡住或不再需要，可以主动取消释放资源。

你应该看到

Cancelled 3 background task(s):

| Task ID | Description | Status | Session ID |
|--- | --- | --- | ---|
| `bg_abc123` | Explore: 查找认证实现 | running | `sess_xyz789` |
| `bg_def456` | Librarian: 研究最佳实践 | running | `sess_uvwx012` |
| `bg_ghi789` | Oracle: 审查架构设计 | pending | (not started) |

## Continue Instructions

To continue a cancelled task, use:

    delegate_task(session_id="<session_id>", prompt="Continue: <your follow-up>")

Continuable sessions:
- `sess_xyz789` (Explore: 查找认证实现)
- `sess_uvwx012` (Librarian: 研究最佳实践)

检查点 ✅

确认你理解了以下要点：

[ ] 能启动多个并行后台任务
[ ] 理解任务状态（pending、running、completed）
[ ] 配置了合理的并发限制
[ ] 能查看和获取任务结果
[ ] 能取消不需要的任务

踩坑提醒

坑 1：忘记配置并发限制

症状：启动太多任务，API 配额瞬间耗尽，或触 Rate Limit。

解决：在 oh-my-opencode.json 中配置 providerConcurrency 或 defaultConcurrency。

坑 2：轮询检查结果太频繁

症状：每隔几秒就调用 background_output 检查任务状态，增加不必要的开销。

解决：系统会自动通知你任务完成。只有在确实需要中间结果时才手动检查。

坑 3：任务超时

症状：任务运行超过 30 分钟后被自动取消。

原因：后台任务有 30 分钟的 TTL（超时时间）。

解决：如果需要长时间任务，考虑拆分为多个子任务，或使用 delegate_task(background=false) 前台运行。

坑 4：Pending 任务一直不启动

症状：任务状态一直是 pending，不进入 running。

原因：并发限制已满，没有可用槽。

解决：

等待现有任务完成
增加并发限制配置
取消不必要的任务释放槽

本课小结

后台任务系统让你可以像真实团队一样工作，多个 AI 代理并行执行任务：

启动并行任务：使用 delegate_task 工具
控制并发：配置 providerConcurrency、modelConcurrency、defaultConcurrency
获取结果：使用 background_output 工具（系统会自动通知）
取消任务：使用 background_cancel 工具

核心规则：

每 2 秒轮询一次任务状态
连续 3 次稳定或 idle 则任务完成
任务 30 分钟后自动超时
优先级：modelConcurrency > providerConcurrency > defaultConcurrency

下一课预告

下一课我们学习 LSP 与 AST-Grep：代码重构利器。
你会学到：
如何使用 LSP 工具进行代码导航和重构
如何使用 AST-Grep 进行精确的模式搜索和替换
LSP 和 AST-Grep 的结合使用最佳实践

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-26

功能	文件路径	行号
后台任务管理器	`src/features/background-agent/manager.ts`	1-1378
并发控制	`src/features/background-agent/concurrency.ts`	1-138
delegate_task 工具	`src/tools/background-task/tools.ts`	51-119
background_output 工具	`src/tools/background-task/tools.ts`	320-384
background_cancel 工具	`src/tools/background-task/tools.ts`	386-514

关键常量：

TASK_TTL_MS = 30 * 60 * 1000：任务超时时间（30 分钟）
MIN_STABILITY_TIME_MS = 10 * 1000：稳定性检测启动时间（10 秒）
DEFAULT_STALE_TIMEOUT_MS = 180_000：默认超时时间（3 分钟）
MIN_IDLE_TIME_MS = 5000：忽略早期 idle 的最小时间（5 秒）

关键类：

BackgroundManager：后台任务管理器，负责启动、追踪、轮询、完成任务
ConcurrencyManager：并发控制管理器，实现三级优先级（model > provider > default）

关键函数：

BackgroundManager.launch()：启动后台任务
BackgroundManager.pollRunningTasks()：每 2 秒轮询任务状态（第 1182 行）
BackgroundManager.tryCompleteTask()：安全完成任务，防止竞态条件（第 909 行）
ConcurrencyManager.getConcurrencyLimit()：获取并发限制（第 24 行）
ConcurrencyManager.acquire() / ConcurrencyManager.release()：获取/释放并发槽（第 41、71 行）

5 分钟跑起来

连接你的 AI 账号

像团队一样工作

遇到问题怎么办

配置迁移全搞定

新功能速览

后台并行任务：像团队一样工作

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

1. 并行执行

2. 并发控制

3. 轮询机制

跟我做

第 1 步：启动后台任务

第 2 步：检查任务状态

第 3 步：配置并发控制

第 4 步：取消任务

检查点 ✅

踩坑提醒

坑 1：忘记配置并发限制

坑 2：轮询检查结果太频繁

坑 3：任务超时

坑 4：Pending 任务一直不启动

本课小结

下一课预告

附录：源码参考

后台并行任务：像团队一样工作 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

1. 并行执行 ​

2. 并发控制 ​

3. 轮询机制 ​

跟我做 ​

第 1 步：启动后台任务 ​

第 2 步：检查任务状态 ​

第 3 步：配置并发控制 ​

第 4 步：取消任务 ​

检查点 ✅ ​

踩坑提醒 ​

坑 1：忘记配置并发限制 ​

坑 2：轮询检查结果太频繁 ​

坑 3：任务超时 ​

坑 4：Pending 任务一直不启动 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

后台并行任务：像团队一样工作

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

1. 并行执行

2. 并发控制

3. 轮询机制

跟我做

第 1 步：启动后台任务

第 2 步：检查任务状态

第 3 步：配置并发控制

第 4 步：取消任务

检查点 ✅

踩坑提醒

坑 1：忘记配置并发限制

坑 2：轮询检查结果太频繁

坑 3：任务超时

坑 4：Pending 任务一直不启动

本课小结

下一课预告

附录：源码参考