！ 本篇文章將會介紹 Subagents：一人軍團平行作戰，期望大家都能學會派出 subagent，讓多個 agent 同時上工 :D

昨天把重複流程封裝成技能包之後，武裝看似齊全了，直到我犯了每個新手都會犯的錯：在對話裡隨口請 agent「順便盤整一下這個 repo 的現況」。它很認真，把 scripts/ 底下的腳本、articles/ 的五篇舊文、還有 logs/ 裡的發文紀錄全讀了一輪——結論是給我了，但主對話的 context 也被中間過程塞得亂七八糟，後續追問開始變得遲鈍。問題不在 agent 不夠聰明，而在「所有工作都擠在同一間辦公室」。opencode 的答案是把 agent 分成兩種：你直接對話的 primary agent，以及被派出去幹活、幹完只交報告的 subagent。今天來認識這支特種部隊。

本篇目標

讀完這篇你會學到：

• primary 與 subagent 的分工：Tab 切換的是你的主對話，Task 自動派與 @ 手動派的是特種部隊
• 三個內建 subagent（general / explore / scout）的選兵邏輯，以及 context 隔離帶來的真正紅利
• 實戰：為本系列打造唯讀的 fact-checker，再用 permission.task 控制「誰能派誰」

環境準備

• 裝好的 opencode（opencode --version 跑得動即可）
• 一個有點內容的 repo 當練習場——本篇直接拿本系列的 repo 示範

# 進到練習場並啟動 opencode
cd /Users/benben/ai/automations/ironman
opencode

主要內容

步驟一：兩種 agent——跟你對話的，和被派出去的

opencode 的 agent 分兩類。primary agent 是你直接互動的對象，內建 Build（全工具開放）和 Plan（唯讀分析）兩個，在 TUI 裡用 Tab 鍵循環切換。subagent 則是「被派出去的」，主 agent 可以透過 Task 工具依任務描述自動派遣，你也可以在訊息裡用 @ 直接點名：

@explore 盤點 articles/ 底下每篇文章用的 tags，列表回報

真正的紅利在 context 隔離。subagent 有自己獨立的對話空間：它翻十個檔案、跑二十次 grep，過程全部留在它自己的 session 裡，回報給主 agent 的只有最終結論。上面那個盤點任務，主對話只會收到一張清單，而不是十幾個檔案的全文——這就是昨天講的「按需付費」在組織層級的重演。

步驟二：內建三本柱——general / explore / scout

opencode 內建三個 subagent，各有明確的軍種：

• explore：快速唯讀偵察兵。不能改檔案，專門找檔案、搜關鍵字、回答代碼庫問題。
• general：全能工兵。除 todo 外工具全開，可以執行多步驟任務、必要時動手改檔，也是最適合平行派遣的軍種。
• scout：外部情報員。唯讀，會把依賴的 repo clone 進 opencode 管理的快取裡研究上游實作，不弄髒你的工作區。

選兵原則只有一條：先問「這任務需不需要寫入」。純偵察派 explore（快、安全），要動手派 general，要查外部文件與依賴派 scout。

小小小測驗：你知道 subagent 回報給主 agent 的，從來不是它的工作全紀錄，而是一份「結案報告」嗎？它讀過的內容永遠不會灌回你的主對話。

步驟三：平行作戰——一個 prompt，三路並進

「一人軍團」的精髓在這一步：把幾個互不依賴的任務寫進同一個 prompt，主 agent 就會在同一回合發出多個 Task 呼叫，同時開工：

請同時派出三個 subagent，全部完成後再彙整：
1. explore：統計 articles/ 每篇文章的字數與 tags
2. scout：查 opencode 官方文件的 agents 頁，列出 subagent 的可用設定
3. general：在 /tmp 底下寫一個練習用的 agent markdown 檔，回報內容

三路偵察同時進行，總耗時取決於最慢的那一路，而不是三段加總。做完想檢閱過程？subagent 會建立子 session：用 session_child_first（預設 <Leader>+Down）進入子 session，左右鍵在子 session 間循環，Up 回到母 session——軍團的作戰紀錄全程可回放。

步驟四：自訂 subagent——為本系列打造 fact-checker

內建三本柱之外，自訂 subagent 樸素依舊：一份 markdown 檔。放 .opencode/agents/（專案層）或 ~/.config/opencode/agents/（全域），檔名就是 agent 名。也可以跑互動式的 opencode agent create 代勞。我為本系列建了一個查核員：

# 專案層自訂 subagent（檔名 ＝ agent 名）
$EDITOR .opencode/agents/fact-checker.md

description: 查核鐵人賽文章草稿：逐條比對 prompts/generate.md 寫作規則與 outline.md 大綱，回報違規與不一致之處
mode: subagent
permission:
  edit: deny
  bash: deny
你是事實查核員。逐一比對草稿與規則檔，只回報問題與修改建議，絕不動手改檔。

兩個欄位是靈魂：description 是主 agent 挑人的唯一線索（跟昨天 skill 的 description 同一個道理）；permission 是煞車——查核員只需要讀，edit 與 bash 直接 deny，想亂來也沒轍。沒指定 model 的 subagent 會沿用派出它的 primary agent 的模型，想省 token 也可以幫它單獨指派小模型。

最後一招：控制「誰能派誰」。在 opencode.json 用 permission.task 限縮派遣權：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "task": {
          "*": "deny",
          "explore": "allow",
          "fact-checker": "allow"
        }
      }
    }
  }
}

規則依序評估、最後符合者生效；被 deny 的 subagent 會直接從 Task 工具的清單消失，模型連試都不會試。這招在第 27 天講安全煞車時還會再用到。

常見問題 / 踩坑記錄

• Q：派出去的 subagent 自己改了我的檔案，我只是叫它「看一下」？
  A：你派到 general 了——它除 todo 外工具全開，動手是它的天性。純偵察請派 explore；或照步驟四自訂 agent 加上 permission: { edit: deny }。部隊選對，紀律就來了。

• Q：自訂的 subagent 沒被自動派用，@ 自動完成選單裡也找不到？
  A：兩個檢查點。第一，frontmatter 的 mode 要設 subagent（不設的預設是 all）；第二，hidden: true 的 agent 不會出現在 @ 選單（這是設計行為，方便藏內部用工具，但權限允許時模型仍可透過 Task 派用）。至於自動派用，看 description 寫得夠不夠具體。

• Q：本系列每晚的 generate 管線，為什麼不搞平行發電？
  A：因為有依賴：規則 → 大綱 → 文章是單向流水線，下游吃上游的產出，拆開平行毫無意義；而且無人值守場景，可預測性永遠優先於炫技。平行的甜蜜點是「彼此獨立的子任務」——像步驟三那種三路互不相干的偵察。至於多 agent 平行寫作、互評、主編彙整，第 28 天再來玩真的。

小結

• agent 分兩種：primary 跟你對話（Tab 切換），subagent 被派出去（Task 自動派遣、@ 手動點名）
• 內建三本柱：explore 偵察、general 工兵、scout 情報；最大紅利是 context 隔離與平行加速
• 自訂 subagent ＝ 一份 markdown：description 決定會不會被挑中，permission 決定能做多大事，permission.task 決定誰能派誰

明日預告

下一篇我們要介紹「第一週回顧：踩坑與成果」。第一週的工具鏈——opencode 安裝、headless 模式、AGENTS.md、Skills、Subagents——要來個總整理，附上本系列系統的實測數據與讀者問答，敬請期待！

參考資料：

• opencode 官方文件：Agents
• opencode 官方文件：Permissions
• opencode 官方文件

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/Z5442T 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D