Cloud Agent 是什么

Copilot cloud agent 是 GitHub 上的异步软件开发代理。GitHub 官方说明，它能完成"研究仓库 → 制定实施计划（implementation plan）→ 在分支里改代码"这条链路，并在你准备好时创建 pull request。

它的曾用名是 Copilot coding agent。现在官方文档统一使用 Copilot cloud agent，但很多旧材料、博客和社区讨论仍会出现 coding agent 说法——遇到时按相同产品理解即可。

阅读目标：读完本章，你应该能判断一个任务是否适合交给 cloud agent，以及它和 VS Code Agent Mode 的差异。

1. 它能做什么

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

研究仓库。
创建实现计划。
修复 bug。
实现增量新功能。
提升测试覆盖率。
更新文档。
处理技术债。
解决 merge conflicts。

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 看得见也能改这些被排除的文件。

真正不想让 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。

深读：为什么云端临时环境不是安全免责

临时环境减少了本地副作用，但不代表任务没有风险。Agent 仍可能修改 workflow、依赖、权限、配置或业务逻辑。最后进入仓库的是 branch 和 PR，风险仍要通过代码审查、测试和 Actions 审批控制。

本章自检

完成本章后，用这 4 个问题检查：

任务是否能通过 branch、PR、测试和 review 验收？
是否需要 GitHub.com 上的 research / plan / iterate 能力？
仓库和 plan 是否支持 cloud agent？
结果失败时能否关闭 PR 或人工接管分支？

通过标准：你能说清楚为什么这个任务适合 cloud agent，而不是本地 Agent Mode。

官方来源

About GitHub Copilot cloud agent —— 官方概念页，覆盖能力、运行环境、适合任务和可用边界。
Responsible use of GitHub Copilot cloud agent —— 官方 responsible use 页面，覆盖用途、限制和安全措施。
Use Copilot agents —— 官方使用入口。