Agent Orchestrator (代理編排器) 教學 — 平行 AI Coding Agent 監督平台

1. 專案定位

Agent Orchestrator（以下簡稱 AO）是一套 Agentic IDE (代理式整合開發環境)，專門解決「同時跑多個 AI coding agent (AI 編碼代理)」會遇到的管理混亂問題。當你同時開好幾個 Claude Code / Codex / Cursor 終端機工作在同一個 repo，很快就會遇到：分支互相覆蓋、終端機視窗迷失、CI 失敗沒人跟進、review 留言沒人回、merge conflict (合併衝突) 不知道該丟給哪個 agent 處理。

AO 的定位不是「取代」這些 coding agent，而是提供一層監督 harness (監督層)：

每個 session 自動建立獨立的 git worktree (git 工作樹)，檔案互不干擾
桌面 App + CLI 雙介面，隨時查看每個 session 是 working / idle / waiting_input / 已結束
自動把 CI 失敗、PR 審查留言、merge conflict 導回正確的 session
用同一套介面操控 23 種不同的 agent CLI（claude-code、codex、aider、cursor、goose 等）

核心心法可以用一句話濃縮：「agent 還是負責寫程式，AO 負責維持工作區、狀態、終端機、回饋迴圈的秩序。」

專案採 Apache-2.0 授權，8,096 stars／1,155 forks，後端 Go + 前端 Electron/TypeScript，開發節奏非常快（幾乎每日多筆 commit + 每日 nightly build）。

2. 安裝指南

2.1 npm 全域安裝（推薦，最快路徑）

1npm install -g @aoagents/ao
2ao start

ao start 必須在你想讓 agent 操作的 repo 目錄下執行，daemon 只綁定 127.0.0.1（本機迴路，不對外開放）。

2.2 桌面版下載

平台	下載方式
Windows	Setup.exe（GitHub Releases）
macOS	Agent Orchestrator.dmg
Linux	Agent Orchestrator.AppImage

2.3 從原始碼建置（開發者路徑）

1git clone https://github.com/AgentWrapper/agent-orchestrator.git
2cd agent-orchestrator/backend
3go build -o ./bin/ao ./cmd/ao
4./bin/ao agent ls    # 若回報 "daemon is not running"，先跑 ./bin/ao start

前端（Electron App）需另外進入 frontend/ 目錄，用 npm／pnpm 安裝依賴後以 vite + electron-forge 建置，細節見 frontend/package.json 的 scripts。

2.4 環境需求

git（必要，AO 透過真實 git CLI 操作 worktree，非 go-git 函式庫）
macOS / Linux 需要 tmux（Windows 內建 conpty，不需額外安裝）
執行 ao doctor 可自動檢查 config、data 目錄、DB 檔案、daemon 狀態、git、tmux 是否就緒

3. 核心架構解析

AO 後端是一個長駐 Go daemon (常駐服務程式)，遵循「三段式管線」心智模型：OBSERVE (觀察外部事實) → UPDATE (更新持久事實) → DERIVE (推導顯示狀態 / 觸發動作)。

關鍵設計原則：顯示狀態從不落地儲存。資料庫只存最小的持久事實（activity_state、is_terminated、PR 相關 facts），像是「這個 session 現在算 working 還是 needs_input」這種顯示用狀態，一律在讀取當下由 service 層即時計算推導。


graph TB
    subgraph Frontend["前端"]
        FE["Electron + React UI"]
        CLI["ao CLI"]
    end

    subgraph HTTPLayer["HTTP Daemon (127.0.0.1)"]
        Controllers["REST Controllers"]
        SSE["SSE Events"]
        Terminal["Terminal WebSocket"]
    end

    subgraph Core["核心服務"]
        SessionSvc["Session Service"]
        SessionMgr["Session Manager"]
        LCM["Lifecycle Manager"]
    end

    subgraph Observe["觀察層"]
        SCMObserver["SCM Observer"]
        Reaper["Runtime Reaper"]
    end

    subgraph Storage["持久層"]
        SQLite[("SQLite DB")]
        CDC["CDC Poller"]
    end

    subgraph Adapters["Adapters (轉接器)"]
        AgentAdapter["Agent Adapters"]
        RuntimeAdapter["Runtime tmux/conpty"]
        WorkspaceAdapter["Workspace git worktree"]
    end

    FE -->|REST/SSE| Controllers
    CLI -->|REST| Controllers
    Controllers --> SessionSvc
    SessionSvc --> SessionMgr
    SessionMgr --> LCM
    SessionMgr --> AgentAdapter
    SessionMgr --> RuntimeAdapter
    SessionMgr --> WorkspaceAdapter
    LCM --> SQLite
    SCMObserver --> SQLite
    Reaper --> RuntimeAdapter
    CDC -->|poll| SQLite
    CDC --> SSE

架構上有兩個值得學習的模式：

Port-Based Design (埠介面設計)：核心邏輯（backend/internal/domain、service）從不直接依賴具體實作，一律透過 backend/internal/ports/ 定義的介面存取外部系統（runtime、workspace、SCM）。真正的實作放在 backend/internal/adapters/，方便日後替換 runtime（例如從 tmux 換成別的多工方案）而不動核心邏輯。
CDC (Change Data Capture，變更資料擷取)：所有寫入都經過 SQLite 的 change_log 表，一個獨立的 CDC Poller 輪詢這張表，把變更透過 SSE 推送給前端，達成「單一寫入路徑 + 即時 UI 更新」，同時避免多個地方各自發事件造成不一致。

4. 主要功能詳細用法

4.1 CLI 常用指令

1ao start                 # 背景啟動 daemon，等待 /readyz
2ao status --json         # 查詳細 daemon 狀態
3ao doctor                # 檢查 git / tmux / DB / daemon 是否就緒
4ao project add           # 註冊要讓 agent 操作的專案
5ao agent ls --refresh    # 列出支援的 agent，重新探測本機安裝/授權狀態
6ao spawn                 # 在目前專案啟動一個新的 agent session
7ao session ls            # 列出所有 session 及狀態
8ao send                  # 對指定 session 送出後續指令
9ao session kill <id>     # 結束指定 session

ao spawn 解析專案脈絡的優先序：--project 參數 → AO_PROJECT_ID 環境變數 → AO_SESSION_ID（回頭查目前 session 綁定的專案）→ 目前工作目錄比對已註冊的專案路徑。若省略 --agent，會用該專案設定的 worker.agent 預設值，並在真正 spawn 前用本機探測結果做 preflight 檢查（可用 --skip-agent-check 跳過）。

4.2 桌面 App 三大面板

Projects（左側）：管理已註冊的專案
Sessions（中間）：目前所有 agent session 的看板視圖
Inspector（右側）：選定 session 的終端機、PR 狀態、review 執行紀錄、瀏覽器預覽，四合一面板

4.3 Review Feedback Loop（審查回饋迴圈）

AO 可以啟動 reviewer agent（目前支援 claude-code / codex / opencode）對 PR 進行審查，審查結果與「要求修改」的意見會自動路由回產生該 PR 的 worker session，不需要人工複製貼上 review 留言。

5. 應用場景

一人多開發：一個工程師同時派 3-5 個 agent 分頭處理不同 issue/feature，用看板一眼掌握誰卡住了
CI 修復自動化：CI 失敗訊息自動回饋給對應 session 的 agent，讓它自行修正後重推
PR review 迴圈：reviewer agent 產生的意見自動導回開發 agent，縮短「審查 → 修改 → 再審查」的手動搬運時間
多 agent CLI 比較評估：同一個任務用不同 agent（Claude Code vs Codex vs Aider）各跑一個 session，比較產出品質
教學/展示：透過終端機直連 + 瀏覽器預覽面板，適合錄製「AI agent 自動修 bug」的示範影片

6. 資安掃描報告

掃描範圍：backend/（Go 原始碼）、frontend/（Electron/TS）、CI workflow、gitleaks 設定。

項目	結果	說明
硬編碼密鑰 / token	🟢 綠燈	掃描 AWS key、`sk-`、`ghp_` 等常見密鑰樣式，原始碼中未發現任何命中
`exec.Command` 使用	🟡 黃燈	大量使用（47 處），但集中在測試檔案的 `git` 操作，以及 `backend/internal/process/command.go` 的通用進程包裝器；這是 AO 產品定位（管理 git worktree + 呼叫外部 agent CLI）的必要設計，非漏洞，但代表 AO 本質上會執行任意本機 agent CLI，使用前務必確認信任的 agent 二進位檔來源
Agent 啟動指令建構	🟡 黃燈	`backend/internal/agentlaunch/spec.go` 定義各 agent 的啟動 spec，實際執行透過 `backend/internal/process/command.go` 的 `exec.Command(name, args...)`；未見字串拼接進 shell（無 `sh -c` 注入風險），但參數來源涵蓋使用者可設定的 agent 設定，需留意設定檔權限
網路對外呼叫	🟢 綠燈	daemon 僅綁定 `127.0.0.1`，未見對外開放埠；`net/http` 使用集中在內部 REST/WS 層
Telemetry (遙測)	🟢 綠燈	Electron renderer 送匿名事件到 PostHog，官方文件明確說明可設 `VITE_AO_POSTHOG_KEY` 為空字串停用；本機路徑/URL 在傳送前會被 redact
CI 層級密鑰掃描	🟢 綠燈	repo 內建 `.github/workflows/gitleaks.yml`，每次 push/PR 都跑 gitleaks scan，並有完整的 `.github/.gitleaks.toml` 規則集（AWS/FB/Slack 等常見密鑰樣式）
危險函式（eval / pickle / os.system）	🟢 綠燈	Go/TypeScript 專案，未使用 Python，無 `eval()`／`pickle` 這類風險模式

總結：整體評級 🟡 中度留意，非 🔴 高風險。AO 本質上是一個「代理外部 CLI 執行權」的工具，exec.Command 大量出現是產品功能所需而非誤用；主要風險點在於你信任哪些 agent CLI 被 AO 呼叫，而非 AO 自身程式碼注入問題。建議企業內部使用時，鎖定 ao agent ls 白名單、審視 worker.agent 設定來源。

7. FAQ

Q: AO 會不會自己幫我寫程式？ 不會。AO 是監督層，實際寫程式碼的仍是你選擇的 agent（Claude Code、Codex 等）。AO 只負責工作區隔離、狀態追蹤、回饋路由。

Q: 多個 session 會不會互相覆蓋檔案？ 不會，每個 session 都在獨立的 git worktree 中工作，天生隔離。

Q: 一定要用 tmux 嗎？ macOS/Linux 需要，Windows 則用內建的 conpty，不需額外安裝。

Q: daemon 資料存哪？ 預設 ~/.ao/data（SQLite），可用環境變數 AO_DATA_DIR 覆寫；~/.ao/running.json 存 PID/port 交握資訊。

Q: 支援 agent 清單怎麼查？ ao agent ls --refresh 會列出全部 23 種支援的 agent harness，並顯示本機安裝/授權狀態。

8. 進階技巧

用 ao doctor --json 整合進自己的健康檢查腳本，CI/CD 前先確認 git/tmux/daemon 就緒
AO_SESSION_ID 環境變數在 session 內可用，讓 ao spawn / ao preview 自動綁定當前 session 脈絡，不需每次手動帶 --project
ao preview 無參數時會自動偵測 session workspace 內的 index.html；帶 URL 參數則直接開啟該 URL（支援 file://／http／https）
想停用 telemetry，建置前把 VITE_AO_POSTHOG_KEY 設為空字串
Go 測試套件內建 e2e 分層：go test -tags e2e ./internal/cli/... 跑跨平台 CLI 行為測試；test/cli/Dockerfile 提供「全新機器安裝」的驗證環境

9. 整合進其他工作流

搭配 gh-tutorial-qd（本模板 Layer 12）：本篇教學即是該工作流的產出範例，後續可用 qd 編譯成 PDF/HTML 分享
搭配公司內部 CI：AO 的 CI 失敗回饋機制可與既有 GitHub Actions pipeline 串接，讓 agent 自動處理紅燈
搭配多 agent 評測：若團隊已有「multi-backend / multi-frontend」類型的多 agent 協作 skill，AO 可作為底層 session 管理平台，取代手動開多個終端機視窗

10. 重點摘要 Checklist

已確認 git 與（macOS/Linux）tmux 已安裝，ao doctor 全綠
已用 npm install -g @aoagents/ao 或桌面版安裝 AO
已理解「durable facts vs derived status」的架構心法，知道狀態是即時算出來的
已確認要呼叫的 agent CLI 來源可信（exec.Command 是產品核心，非漏洞，但要管好白名單）
已視需求停用 PostHog telemetry（VITE_AO_POSTHOG_KEY 設空字串）
已排除機密專案不進入多 agent session 流程

11. 進一步閱讀

官方文件：https://ao-agents.com/docs
架構文件：docs/architecture.md（本教學第 3 節即取材自此）
後端程式碼結構：docs/backend-code-structure.md
CLI 完整指令參考：docs/cli/README.md
技術棧決策記錄：docs/stack.md
Telemetry 說明：docs/telemetry.md
Discord 社群：https://discord.com/invite/UZv7JjxbwG

Agent Orchestrator (代理編排器) 教學 — 平行 AI Coding Agent 監督平台

Contents

Agent Orchestrator (代理編排器) 教學 — 平行 AI Coding Agent 監督平台

1. 專案定位

2. 安裝指南

2.1 npm 全域安裝（推薦，最快路徑）

2.2 桌面版下載

2.3 從原始碼建置（開發者路徑）

2.4 環境需求

3. 核心架構解析

4. 主要功能詳細用法

4.1 CLI 常用指令

4.2 桌面 App 三大面板

4.3 Review Feedback Loop（審查回饋迴圈）

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Comments

Agent Orchestrator (代理編排器) 教學 — 平行 AI Coding Agent 監督平台

Contents

Agent Orchestrator (代理編排器) 教學 — 平行 AI Coding Agent 監督平台

1. 專案定位

2. 安裝指南

2.1 npm 全域安裝（推薦，最快路徑）

2.2 桌面版下載

2.3 從原始碼建置（開發者路徑）

2.4 環境需求

3. 核心架構解析

4. 主要功能詳細用法

4.1 CLI 常用指令

4.2 桌面 App 三大面板

4.3 Review Feedback Loop（審查回饋迴圈）

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments