---
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="/docs/github-copilot/official/04-cloud-agent/kick-off-a-task" />
  <Card title="研究、计划和迭代" description="继续学习先 branch 迭代，再创建 PR 的流程。" href="/docs/github-copilot/official/04-cloud-agent/research-plan-iterate" />
</Cards>
