GitHub Copilot CLI 功能图谱:基于 Using-GitHub-Copilot-CLI 工作坊 21 个关键能力点的完整使用指南

原创2026-10-10 20:19:511,739 阅读
文章标签:教程示例工程AI 应用Vibe Coding

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 张截图作为"能力验收证据"的可信度——每张图都能独立说明一个功能点,与上文的命令操作一一对照,方便讲师验收、读者自查,也让这份索引文档成为可检索、可引用的功能目录。

八、进一步阅读

登录后查看全文
Mastering-GitHub-Copilot-for-Paired-Programming