GitHub Copilot CLI 功能图谱:基于 Using-GitHub-Copilot-CLI 工作坊 21 个关键能力点的完整使用指南
GitHub Copilot CLI 功能图谱:基于 Using-GitHub-Copilot-CLI 工作坊 21 个关键能力点的完整使用指南
在终端里把 GitHub Copilot 当作一个可以自主阅读代码、规划方案、执行命令并直接对接 GitHub.com 的编码 Agent,是 Using-GitHub-Copilot-CLI 这个四模块工作坊的核心目标。其 images 目录下的 README.md 以 21 张待采集截图的形式,完整索引了这套 CLI 的全部关键能力:从安装、三种交互模式、模型选择,到工具审批、上下文压缩、GitHub.com 集成、远程 Agent 任务,再到自定义 Agent、记忆与 MCP 扩展。本文以这份截图清单为骨架,逐条对照四篇模块文档展开成文,让你读完后既能看懂每张截图对应的技术含义,也能照着命令亲手复现整套终端工作流。
一、这份截图索引文档的定位与结构
Using-GitHub-Copilot-CLI/images/README.md 是工作坊配套的资源说明文件,它规定了截图目录需要收录哪些演示画面、每张画面应该呈现什么内容。虽然它本身不含代码,但它的 21 个条目恰好构成了一张完整的"能力验收清单",与工作坊的四个模块一一对应:
| 模块文档(仓库相对路径) | 覆盖的截图编号 | 主题 |
|---|---|---|
| 1-Install-and-Modes.md | 001–005 | 安装验证、默认模式、计划模式、Auto 模型选择 |
| 2-Tool-Approval-and-Context.md | 006–009 | 工具审批、程序化模式、上下文管理 |
| 3-GitHub-Integration-and-Workflows.md | 010–014、018–021 | GitHub.com 集成、模型选择、端到端工作流、远程 Agent |
| 4-Customization-and-Extensions.md | 015–017 | 自定义 Agent、Memory、MCP 服务器 |
下文按模块顺序逐条解读,把每张截图"该拍什么"升级为"该掌握什么、命令怎么写"。
二、安装与交互模式:截图 001–005
001-install.jpg:安装完成的终端画面
这条截图要求呈现 "Copilot CLI installation completing in a terminal"。对应实操在 1-Install-and-Modes.md 的 Section 1,需要先明确:这里的 copilot 是独立的终端应用,区别于 2025 年 9 月弃用、归档于 v1.2.0 的 gh copilot 扩展(gh extension install github/gh-copilot)。工作坊同时使用两套 CLI:copilot 用于交互式编码会话,gh(GitHub CLI)用于 Section 4、6 中的 gh agent-task 命令。
按平台选择安装方式:
- Windows(WinGet):
winget install GitHub.Copilot - macOS / Linux(Homebrew):
brew install copilot-cli - 任意平台(pip):
pip install github-copilot-cli - macOS / Linux(安装脚本):
curl -fsSL https://gh.io/copilot-install | bash
安装后用 copilot --version 验证,在示例项目根目录执行 copilot 启动;未登录时按提示使用 /login 走浏览器授权,也可以使用带 Copilot Requests 权限的细粒度 PAT 通过环境变量无头登录:export GH_TOKEN=<your-pat> 后再启动。升级命令与安装方式对应:brew upgrade copilot-cli、winget upgrade GitHub.Copilot、pip install --upgrade github-copilot-cli。
002-welcome.jpg:交互式欢迎界面
对应首次启动时出现的动画欢迎横幅。此时 CLI 已完成登录态检测并进入会话,后续所有斜杠命令(/login、/model、/compact 等)都从这个界面进入。
003-default-mode.jpg:默认模式响应项目概览提示
默认模式即 Ask/Execute 模式,Copilot 会对每个提示做出响应、必要时追问澄清问题,并在修改文件或执行命令前征求你的批准。截图建议的演示提示是让 Copilot 给出项目整体结构:
Explain the overall structure of this Python project and what each file contains.
更进一步,可以让它做一个小改动来演示"修改需批准"的机制:
Add a GET /ping endpoint to the FastAPI app that returns {"status": "ok"} with HTTP 200.
当 Copilot 请求修改 main.py 的权限时,选择 Yes(仅本次允许)或 Yes, and approve for the rest of this session(本会话内免再询问)。
004-plan-mode.jpg:计划模式输出编号步骤
计划模式适合更大或边界不清晰的任务:Copilot 先分析需求、提出澄清问题,再产出一份带编号步骤的结构化实施计划,在你批准前不会写任何代码。通过 Shift+Tab 在三种模式间循环切换(提示符处的模式指示器会变化)。截图要求呈现"numbered steps",典型演示提示为:
Refactor the token generation endpoint to use a service class with dependency injection, add CRUD operations for a User entity with Pydantic models, and write pytest tests for both.
批准前可以要求修订某一步,例如"Change step 3 to use pytest-mock instead of unittest.mock for mocking",确认后再让 Copilot 逐步执行。
005-auto-model.jpg:/model 选择器中的 Auto 选项
打开 /model 选择 Auto 后,Copilot 会自动从 1× multiplier 模型池中挑选,避免手动选模型的负担并降低限流风险。文档列出当前池中的模型包括 GPT-4.1、GPT-5 mini、GPT-5.2-Codex、GPT-5.3-Codex、Claude Haiku 4.5、Claude Sonnet 4.5(池会随新模型发布而变动)。要点:
- Auto 永远不会选择被管理员策略排除的模型、倍率大于 1× 的溢价模型,以及当前套餐不可用的模型;
- 付费套餐(Pro、Pro+、Business、Enterprise)使用 Auto 时,符合条件的模型可享受 10% 倍率折扣;
gh agent-task(Copilot coding agent)的 Auto 模型选择目前仅对 Pro 和 Pro+ 套餐 正式可用;- 每次回复会报告实际使用的模型;可随时用
/model手动覆盖,或在启动时指定:copilot --model claude-sonnet-4.6。
三、工具审批与上下文管理:截图 006–009
这部分对应 2-Tool-Approval-and-Context.md 的 Section 3,核心是"让 Agent 干活,但由你掌控边界"。
006-tool-approval.jpg:三选项审批提示
当 Copilot 请求运行 pytest 时会弹出三个选项:
1. Yes
2. Yes, and approve pytest for the rest of this session
3. No, and tell Copilot what to do differently (Esc)
选项 2 表示本会话内 pytest 命令免再确认。启动时也可用 --allow-tool 预批准,适合 CI 脚本等可信任务:
copilot --allow-tool 'shell(pytest)' --allow-tool 'write'
其中 shell(COMMAND) 批准特定 shell 命令(省略命令名则放行所有 shell 命令),write 放行所有文件修改。
007-deny-tool.jpg:allow-all-tools 与 deny-tool 覆盖
截图要求呈现"以 allow-all-tools 启动并带特定 deny-tool 覆盖"的场景。--deny-tool 的优先级始终高于 --allow-tool 和 --allow-all-tools。例如放行一切但封禁 rm 与 git push:
copilot --allow-all-tools --deny-tool 'shell(rm)' --deny-tool 'shell(git push)'
008-programmatic.jpg:程序化模式完成任务后退出
无头场景(脚本、CI)使用 -p 直接传提示,任务完成后进程退出:
copilot -p "Show me this week's commits and summarize them" --allow-tool 'shell(git)'
也可以从管道喂入提示:
echo "Run pytest and report any failures" | copilot --allow-tool 'shell(pytest)'
009-compact.jpg:/compact 把上下文从 80% 压到 12%
长会话中对话历史会逼近模型 token 上限。/context 显示按系统提示、对话历史、剩余可用 token 拆分的用量明细;/compact 压缩历史但保留已完成任务的关键事实,可用 Escape 取消。文档给出的示例数字(80%→12%)表明一次压缩能显著释放空间。自动压缩在会话接近 token 上限的 95% 时在后台触发,不打断工作流,从而实现"一个会话从功能开始写到结束"的超长会话。
四、GitHub.com 集成与远程 Agent 任务:截图 010–014、020–021
对应 3-GitHub-Integration-and-Workflows.md 的 Section 4:独立 CLI 内置 GitHub MCP 服务器,复用你已有的 GitHub 凭据,让 GitHub.com 操作成为会话的自然组成部分。
010-list-prs.jpg:列出打开的 Pull Request
在项目目录启动 copilot 后直接提问:
List my open PRs
仓库级范围可以写成:
List all open issues assigned to me in <owner>/<repo>
011 / 020-create-pr.jpg:创建 Pull Request
两张截图分别覆盖"从 CLI 创建 PR"的两个阶段。典型提示是让 Copilot 写一个脚本并开 PR:
In the root of this repo, add a Python script called health_check.py that pings the /health endpoint and prints the result. Create a pull request to add this file to the repo on GitHub.
注意:即使代码是 Copilot 写的,PR 作者仍标记为你。也可以先让 Copilot 认领一个 issue 再自动开 PR:
I've been assigned this issue: https://github.com/<owner>/<repo>/issues/<number>. Start working on this for me in a suitably named branch.
012-model-select.jpg:/model 模型列表与倍率
/model 弹出可选项列表,文档(截至 2026 年 2 月)列出:
| 模型 | 请求倍率 | 说明 |
|---|---|---|
| Claude Sonnet 4.6(默认) | 1×(暂定) | 2026-02-17 GA,擅长 agentic coding 与搜索 |
| Claude Sonnet 4.5 | 1× | |
| Claude Sonnet 4 | 1× | |
| Claude Opus 4.6 | varies | 2026-02-05 GA,适合复杂规划与工具调用 |
| Claude Opus 4.6 Fast | 30× | Preview,仅 Pro+/Enterprise,输出最高快 2.5× |
| GPT-5.3-Codex | varies | 2026-02-09 GA,agentic 任务比 GPT-5.2-Codex 快 25% |
每次提示都会按倍率消耗月度 premium 请求配额。模型可用性取决于套餐(Pro、Pro+、Business、Enterprise),企业管理员需在组织 Copilot 设置中逐个启用模型。启动时指定模型:copilot --model claude-sonnet-4。
013 / 014 / 021-agent-task:gh agent-task 远程 Agent 任务
gh agent-task 让 Copilot coding agent 在 GitHub 云端(远程 Codespace)独立执行任务,不使用你的本地文件。三个命令覆盖完整生命周期:
# 创建任务(关联 issue,排队后 agent 会自动实现并开 PR)
gh agent-task create --repo <owner>/<repo> --issue <number>
# 列出仓库内所有 agent 任务
gh agent-task list --repo <owner>/<repo>
# 查看指定任务状态(完成后会给出 PR URL)
gh agent-task view <task-id> --repo <owner>/<repo>
任务完成后用 gh pr view <pr-number> --web 在浏览器审查 PR。截图 013 呈现创建后返回的 task ID 与状态,014 呈现 completed 状态与 PR URL,021 呈现最终"文档 PR 已就绪可合并"的收尾画面。注意:完成 Section 4 与 6 需要将 Copilot Free 套餐升级以启用 Agent Mode。
五、端到端工作流与自纠错:截图 018–019
这两张截图来自 Section 5 的实战场景——为 /token 端点添加分页支持,把前面所有能力串成一条可复用的流水线。
018-plan-pagination.jpg:分页功能的编号实施计划
场景要求 /token 端点接受 page、page_size 查询参数,用 Pydantic 校验,返回带 total、page、page_size、total_pages 元数据的 PaginatedResponse,更新 OpenAPI 规范,并补 pytest 用例。在计划模式下给出完整需求描述,Copilot 会产出编号步骤;批准后切回默认模式(或留在计划模式)逐步执行并在每步后汇报。完整工作流可归纳为七阶段:
| 阶段 | 工具 | 动作 |
|---|---|---|
| 探索 | 默认模式 | 自然语言定位受影响文件 |
| 设计 | 计划模式 | 构建并评审结构化计划 |
| 构建与测试 | 默认/计划模式 | 实现、跑 pytest、自纠错 |
| 上下文 | /context + /compact |
监控与管理 token 用量 |
| 交付 | GitHub.com 集成 | 终端内提交并开 PR |
| 打磨 | gh agent-task |
远程 Agent 异步补文档 |
| 审查 | gh pr view |
检查并合并 |
其中值得注意的 Agent 行为:coding agent 任务总是基于仓库默认分支的最新状态在云端创建独立分支,不会复用你的本地分支或改动既有 PR。
019-self-correct.jpg:跑测试、发现失败、自我修正
截图要求呈现 "running tests, observing a failure, and self-correcting"。Copilot 创建 models/pagination.py、更新 main.py 路由、在 tests/ 搭测试后请求运行 pytest,此时选择"1. Yes, and approve pytest for the rest of this session";它会观察失败并持续修正直至全部通过。会话较长时可先用 /context 检查用量,高于 70% 时执行 /compact 再进入收尾步骤。最后用一条提示收尾提交与开 PR:
Commit these changes with a conventional commit message and create a pull request against main with a description that summarises the pagination feature.
六、自定义与扩展:截图 015–017
对应 4-Customization-and-Extensions.md 的 Section 6。
015-custom-agent.jpg:编辑中的自定义 Agent Markdown
自定义 Agent 是针对特定任务/角色的 Copilot 特化版本。在项目 .github/agents/fastapi-expert.md 中定义:
---
name: fastapi-expert
description: A FastAPI specialist that follows best practices for async Python web development.
---
## Role
You are a Python backend engineer specialising in FastAPI and async Python.
## Conventions
- Use async/await for all I/O operations
- Define Pydantic models for all request/response bodies
- Use dependency injection for shared resources (database, config)
- Follow RESTful naming conventions for endpoints
- Include OpenAPI documentation via docstrings
- Use proper HTTP status codes (201 for creation, 204 for delete, etc.)
- Implement proper error handling with HTTPException
会话中用 @fastapi-expert 前缀调用,例如:@fastapi-expert Add rate limiting middleware to the API and implement proper error handling for all endpoints. 该约定文件会成为额外的系统上下文。配套的还有 .github/copilot-instructions.md(项目级指南,可声明 PEP 8、Google-style docstrings、pytest-mock 等约定)和带 applyTo front matter 的目录级指令文件(如 .github/instructions/api.instructions.md,applyTo: "webapp/**/*.py")。社区资源可通过插件市场引入:copilot plugin marketplace add github/awesome-copilot、copilot plugin install awesome-copilot@awesome-copilot,再在会话中用 /awesome-copilot:suggest-awesome-github-copilot-skills 等斜杠命令按仓库上下文推荐技能、指令与 Agent。
016-memory.jpg:/memory 查看持久化约定
Copilot Memory 让 CLI 跨会话积累对仓库的持久理解。在一个重要任务完成后执行 /memory 查看已存储的编码约定、模式与偏好(可增删改以纠正误解);新会话中它会自动记得"你偏好 pytest 而非 unittest""你使用 Pydantic v2 语法"这类上下文,无需重复解释。
017-mcp-server.jpg:/mcp 列出已配置服务器及工具
CLI 出厂即内置并认证好 GitHub MCP 服务器,还可通过配置文件追加数据库、监控、云厂商等服务器:用户级 ~/.copilot/mcp-config.json(对所有项目生效)或仓库级 .github/mcp.json。一个 PostgreSQL 示例:
{
"servers": {
"postgres": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "DATABASE_URL",
"mcp/postgres"
],
"env": {
"DATABASE_URL": "postgresql://localhost:5432/mydb"
}
}
}
}
会话内 /mcp 列出服务器并查看其暴露的工具,随后用自然语言调用,如 "Use the postgres MCP server to show me the schema of the users table."。启动预批准时以服务器名作为 --allow-tool 参数,并可细分到工具级:copilot --allow-tool 'postgres(query)' --deny-tool 'postgres(execute)'。本仓库还提供独立的 Integrate-MCP-with-Copilot 模块,可进一步学习 MCP 与 Copilot Agent Mode 的集成实践。
延伸:钩子(Hooks)
截图清单未单列钩子,但 4-Customization-and-Extensions.md 补充了它:Hooks 允许在 Agent 执行的关键节点运行自定义 shell 命令。例如 .github/hooks/post-write.sh 在每次写出 .py 文件后自动执行 ruff check --fix 与 ruff format,并通过 .github/hooks/config.json 注册 { "event": "post-write", "command": ".github/hooks/post-write.sh" },实现"写完即 lint"的自动化闭环。
七、截图采集规范(Image Guidelines)
images/README.md 末尾对截图本身提出了四项要求,这也是复现工作坊演示时的录制标准:
- 格式:截图优先使用 JPEG;
- 可读性:终端文本必须清晰可读;
- 上下文:画面应包含相关上下文与 UI 元素(如模式指示器、审批选项、模型列表);
- 安全:确保敏感信息已打码(token、私有仓库名等)。
这些约束保证了 21 张截图作为"能力验收证据"的可信度——每张图都能独立说明一个功能点,与上文的命令操作一一对照,方便讲师验收、读者自查,也让这份索引文档成为可检索、可引用的功能目录。
八、进一步阅读
- 工作坊总览与模块导航:Using-GitHub-Copilot-CLI/README.md
- 安装与模式:1-Install-and-Modes.md
- 工具审批与上下文:2-Tool-Approval-and-Context.md
- GitHub 集成与端到端工作流:3-GitHub-Integration-and-Workflows.md
- 自定义、Memory、MCP 与 Hooks:4-Customization-and-Extensions.md
- 远程 coding agent 的完整生命周期:Using-GitHub-Copilot-Coding-Agent
- MCP 与 Copilot 的集成实践:Integrate-MCP-with-Copilot