---
title: "Cloud Agent 是什麼"
description: "解釋 Copilot cloud agent 的能力、臨時開發環境、可用範圍、適合任務和審查邊界。"
verifiedAt: "2026-05-06"
---

Copilot cloud agent 是 GitHub 上的非同步軟體開發代理。GitHub 官方說明，它能完成"研究儲存庫 → 制定實施計劃（implementation plan）→ 在分支裡改程式碼"這條鏈路，並在你準備好時建立 pull request。

它的曾用名是 Copilot coding agent。現在官方文件統一使用 Copilot cloud agent，但很多舊材料、部落格和社群討論仍會出現 coding agent 說法——遇到時按相同產品理解即可。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能判斷一個任務是否適合交給 cloud agent，以及它和 VS Code Agent Mode 的差異。

## 1. 它能做什麼

官方概念頁列出的能力包括：

- 研究儲存庫。
- 建立實現計劃。
- 修復 bug。
- 實現增量新功能。
- 提升測試覆蓋率。
- 更新文件。
- 處理技術債。
- 解決 merge conflicts。

```mermaid
flowchart TD
    Prompt["任務 prompt"] --> Env["GitHub Actions 臨時開發環境"]
    Env --> Research["研究儲存庫"]
    Research --> Plan["建立計劃"]
    Plan --> Branch["在 branch 上修改"]
    Branch --> Tests["執行 tests / linters"]
    Tests --> PR["建立或更新 PR"]
    PR --> Review["人工 review"]

    style Env fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Tests fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Review fill:#dcfce7,stroke:#16a34a,stroke-width:2px
```

## 2. 在哪裡執行

官方文件說明，cloud agent 在由 GitHub Actions 驅動的臨時開發環境中工作。它可以探索程式碼、修改檔案、執行自動化測試和 linters。

這和本地 VS Code Agent Mode 的區別：

- VS Code Agent Mode 更適合你即時觀察和批准本地操作。
- Cloud agent 更適合非同步、分支、PR 和團隊 review。
- Cloud agent 的結果應該回到 PR 和 session logs 審查。

## 3. 可用範圍

2026-05-06 核驗時，官方文件說明 cloud agent 可用於 GitHub Copilot Pro、Pro+、Business 和 Enterprise plans。它適用於 GitHub 上的儲存庫，但 managed user accounts 擁有的儲存庫、以及顯式停用 cloud agent 的儲存庫除外。

還有一個重要邊界：deep research、planning 和在建立 PR 前迭代，只在 GitHub.com 的 cloud agent 上可用。某些外部整合只支援直接建立 PR。

## 4. 適合任務

適合：

- backlog 中低到中風險的改進。
- 文件、測試、技術債、日誌、錯誤提示。
- 可以透過 PR review 驗收的 bug 或小功能。
- 需要先研究儲存庫再給方案的任務。

不適合：

- 必須使用本地私有環境才能驗證的任務。
- 沒有測試和 review 路徑的生產修改。
- 需要線下上下文、敏感憑據或人工判斷的任務。
- 高風險部署、許可權、資料遷移。

## 5. 與 VS Code Agent Mode 對比

用一句話判斷：

- **本地 Agent Mode**：你要在編輯器裡邊看邊批。
- **Cloud agent**：你要讓它非同步工作，最後在 PR 裡審。

如果任務很小，本地更快；如果任務可以排隊、需要 review、需要 branch 和 PR，cloud agent 更合適。

## 6. 新手必踩的 4 個坑

官方 about 頁給出幾條邊界，新手容易忽略。把它們當**硬約束**而不是"建議"：

### 坑 1：cloud agent 不讀 content exclusion

官方明確說 "Copilot cloud agent doesn't account for content exclusions"。也就是你在儲存庫設定裡配的"內容排除"對 IDE Chat 和 inline suggestions 有效，但 cloud agent **看得見也能改**這些被排除的檔案。

> [!WARNING]
> 真正不想讓 cloud agent 看到的檔案（金鑰、客戶資料、專有演算法），不要靠內容排除擋——靠**儲存庫許可權**或**把它們移出該儲存庫**。

### 坑 2：單次任務只能改 1 個儲存庫 / 1 個分支 / 1 個 PR

cloud agent **不能跨儲存庫改程式碼**，也只在它啟動時指定的那個儲存庫裡工作；並且**只在一個分支上工作**，每個任務**只開一個 PR**。

> 現實含義：跨儲存庫重構（例如同時改 `frontend-app` 和 `shared-lib`）必須拆成兩個獨立任務，分別啟動。不要在一個 prompt 裡寫"順便也把 shared-lib 改一下"——它做不到。

### 坑 3：可能被 branch protection rule 阻斷

如果儲存庫配了 ruleset 或 branch protection，且規則不相容（例如"只允許特定 commit author"），cloud agent **會被直接擋在外面，連 PR 都開不了**。

> 修復方式：在 ruleset 裡把 Copilot 加成 bypass actor。第一次啟用 cloud agent 前，先確認你目標儲存庫的保護規則不會卡它。

### 坑 4：預設只能看到當前儲存庫的上下文

cloud agent 預設只能訪問啟動時指定的那個儲存庫的 issues 和歷史 PR。如果你的任務需要它**參考另一個儲存庫**（例如內部元件庫的實現規範），必須額外配 MCP server 給它開啟訪問。

> 不配的話它只會"按當前儲存庫猜怎麼實現"，結果通常和團隊規範脫節。

## 7. Custom agent：不是新增產品，是給 cloud agent 起角色

官方 customization 章節列了 custom agents——這容易讓人以為是新功能。實際上 custom agent 就是**給 cloud agent 配一份身份卡**：固定的 system prompt + 限定的工具集 + 專屬 MCP server。

新手友好理解：把它當"團隊裡的專科同事"。常見三類：

| Custom agent 例子 | 身份卡 | 適合的任務 |
| --- | --- | --- |
| Frontend agent | "我是前端工程師，遵守團隊 React + Tailwind 規範" + 只允許改 `src/components/` 和 `src/styles/` | 改 UI 元件、補樣式、調可訪問性 |
| Documentation agent | "我擅長寫技術文件" + 只允許改 `docs/` 和 README + 接 link checker MCP | 同步 API 示例、補 frontmatter、檢查連結 |
| Tests agent | "我專寫最小回歸測試" + 只允許改 `tests/` + 跑指定測試命令 | bug fix 後補回歸測試 |

不需要從第一天就做 custom agent。先用預設 cloud agent 跑通幾個任務，識別出"我每週都讓它做同一類事"，再把它沉澱成 custom agent。

<details>
<summary>深讀：為什麼雲端臨時環境不是安全免責</summary>

臨時環境減少了本地副作用，但不代表任務沒有風險。Agent 仍可能修改 workflow、依賴、許可權、配置或業務邏輯。最後進入儲存庫的是 branch 和 PR，風險仍要透過程式碼審查、測試和 Actions 審批控制。
</details>

## 本章自檢

完成本章後，用這 4 個問題檢查：

1. 任務是否能透過 branch、PR、測試和 review 驗收？
2. 是否需要 GitHub.com 上的 research / plan / iterate 能力？
3. 儲存庫和 plan 是否支援 cloud agent？
4. 結果失敗時能否關閉 PR 或人工接管分支？

透過標準：你能說清楚為什麼這個任務適合 cloud agent，而不是本地 Agent Mode。

## 官方來源

- [About GitHub Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent) —— 官方概念頁，覆蓋能力、執行環境、適合任務和可用邊界。
- [Responsible use of GitHub Copilot cloud agent](https://docs.github.com/en/copilot/responsible-use/copilot-cloud-agent) —— 官方 responsible use 頁面，覆蓋用途、限制和安全措施。
- [Use Copilot agents](https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents) —— 官方使用入口。

## 接下來去哪

<Cards>
  <Card title="啟動任務" description="繼續學習 issue assignment、Agents prompt 和 repository seed 的區別。" href="/zh-Hant/docs/github-copilot/official/04-cloud-agent/kick-off-a-task" />
  <Card title="研究、計劃和迭代" description="繼續學習先 branch 迭代，再建立 PR 的流程。" href="/zh-Hant/docs/github-copilot/official/04-cloud-agent/research-plan-iterate" />
</Cards>
