後台並行任務：像團隊一樣工作

學完你能做什麼

✅ 啟動多個並行後台任務，讓不同 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 行）

後台並行任務：像團隊一樣工作 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

🎒 開始前的準備 ​

核心思路 ​

1. 並行執行 ​

2. 並行控制 ​

3. 輪詢機制 ​

跟我做 ​

第 1 步：啟動後台任務 ​

第 2 步：檢查任務狀態 ​

第 3 步：配置並行控制 ​

第 4 步：取消任務 ​

檢查點 ✅ ​

踩坑提醒 ​

坑 1：忘記配置並行限制 ​

坑 2：輪詢檢查結果太頻繁 ​

坑 3：任務逾時 ​

坑 4：Pending 任務一直不啟動 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

後台並行任務：像團隊一樣工作

學完你能做什麼

你現在的困境

什麼時候用這一招

🎒 開始前的準備

核心思路

1. 並行執行

2. 並行控制

3. 輪詢機制

跟我做

第 1 步：啟動後台任務

第 2 步：檢查任務狀態

第 3 步：配置並行控制

第 4 步：取消任務

檢查點 ✅

踩坑提醒

坑 1：忘記配置並行限制

坑 2：輪詢檢查結果太頻繁

坑 3：任務逾時

坑 4：Pending 任務一直不啟動

本課小結

下一課預告

附錄：原始碼參考