GitHub Copilot CLI 的最佳实践

简介

GitHub Copilot CLI 是一款面向终端的 AI 编码助手，直接在命令行中提供代理功能。Copilot CLI 可以像聊天机器人一样回答你的问题，但其真正的力量在于能够作为你的编码伙伴自主工作，让你可以委派任务并监督其工作。

本文提供了充分利用 Copilot CLI 的技巧，包括有效使用各种 CLI 命令以及管理 CLI 对文件的访问权限。请将这些技巧视为起点，随后进行实验，找出最适合你工作流的做法。

1. 定制你的环境

使用自定义指令文件

Copilot CLI 会自动从多个位置读取指令，帮助你定义组织范围的标准和仓库特定的约定。

支持的路径（发现顺序）

位置	范围
~/.copilot/copilot-instructions.md	所有会话（全局）
.github/copilot-instructions.md	仓库
.github/instructions/**/*.instructions.md	仓库（模块化）
AGENTS.md (in Git root or cwd)	仓库
Copilot.md, GEMINI.md, CODEX.md	仓库

最佳实践

仓库指令 始终优先于 全局指令。可利用此方式强制执行团队约定。例如，这是一份简单的 .github/copilot-instructions.md 文件。

## Build Commands
- `npm run build` - Build the project
- `npm run test` - Run all tests
- `npm run lint:fix` - Fix linting issues

## Code Style
- Use TypeScript strict mode
- Prefer functional components over class components
- Always add JSDoc comments for public APIs

## Workflow
- Run `npm run lint:fix && npm test` after making changes
- Commit messages follow conventional commits format
- Create feature branches from `main`

了解更多，请参阅 关于自定义 GitHub Copilot 响应。

配置允许的工具

管理 Copilot 能在无需授权的情况下运行的工具。当 Copilot 请求某项操作的授权时，你通常可以选择仅本次允许，或在整个 CLI 会话期间始终允许该工具。

要重置之前批准的工具，请使用

/reset-allowed-tools

也可以通过 CLI 标志预先配置允许的工具

copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

常见授权模式

• shell(git:*) — 允许所有 Git 命令
• shell(npm run:*) — 允许所有 npm 脚本
• shell(npm run test:*) — 允许 npm test 命令
• write — 允许文件写入

选择首选模型

使用 /model 根据任务复杂度从可用模型中选择

模型	最佳适用场景	权衡
Claude Opus 4.5 (default)	复杂架构、困难的调试、细致的重构	能力最强，但会消耗更多 高级请求
Claude Sonnet 4.5	日常编码、常规任务	快速、性价比高，能够胜任大多数工作
GPT-5.2 Codex	代码生成、代码审查、直接的实现	非常适合审查其他模型生成的代码

推荐

• Opus 4.5 适用于需要深度推理、复杂系统设计、细微 Bug 调查或大量上下文理解的任务。
• 切换到 Sonnet 4.5 在对速度和成本敏感的常规任务中，请切换到 Sonnet 4.5 ——它能够高效处理大多数日常编码。
• 使用 Codex 在大批量代码生成以及作为其他模型代码审查的第二意见时，请使用 Codex。

任务复杂度变化时，可使用 /model 在会话中途切换模型。

如果你的组织或企业使用自有 LLM 提供商的 API 密钥配置了自定义模型，这些模型也会出现在 /model 列表底部。

使用自有模型提供商

你可以将 Copilot CLI 配置为使用自己的模型提供商，而非 GitHub 托管的模型。运行 copilot help providers 获取完整的设置说明。

关键考量

• 你的模型必须支持 工具调用（函数调用）和 流式传输。若缺少任一功能，Copilot CLI 会报错。
• 为获得最佳效果，请使用上下文窗口至少为 128k token 的模型。
• 内置子代理（/review、/task、explore、/fleet）会自动继承你的提供商配置。
• 使用自有提供商时，费用估算会被隐藏。仍会显示 Token 使用情况（输入、输出及缓存计数）。
• `/delegate` 仅在已登录 GitHub 时可用。它会把会话转移到 GitHub 的服务器端 Copilot，而非你的提供商。

参见 使用自有模型提供商。

2. 编码前先规划

计划模式

当模型有明确的计划可遵循时，成功率更高。 在计划模式下，Copilot 会在编写任何代码前创建结构化的实现计划。

按 Shift+Tab 可在普通模式与计划模式之间切换。进入计划模式后，你输入的所有提示都会触发计划工作流。

或者，你也可以在普通模式下使用 /plan 命令来实现相同效果。

示例提示（来自普通模式）

/plan Add OAuth2 authentication with Google and GitHub providers

会发生什么

• Copilot 会分析你的请求和代码库。
• 提出澄清性问题 以明确需求和实现方式。
• 创建带复选框的结构化实现计划。
• 将计划保存至会话文件夹中的 plan.md。
• 等待你的批准 后再执行实现。

按 Ctrl+y 可在默认的 Markdown 编辑器中查看并编辑计划。

示例计划输出

# Implementation Plan: OAuth2 Authentication

## Overview
Add social authentication using OAuth2 with Google and GitHub providers.

## Tasks
- [ ] Install dependencies (passport, passport-google-oauth20, passport-github2)
- [ ] Create authentication routes in `/api/auth`
- [ ] Implement passport strategies for each provider
- [ ] Add session management middleware
- [ ] Create login/logout UI components
- [ ] Add environment variables for OAuth credentials
- [ ] Write integration tests

## Detailed Steps
1. **Dependencies**: Add to package.json...
2. **Routes**: Create `/api/auth/google` and `/api/auth/github`...

何时使用计划模式

情形	使用计划模式吗？
复杂的多文件修改
涉及众多触点的重构
新功能实现
快速 bug 修复
单文件修改

explore → plan → code → commit 工作流

在复杂任务中取得最佳结果

• 探索:

  读取认证文件但暂不编写代码

• 计划:

  /plan Implement password reset flow

• 审查:

  检查计划，提出修改建议

• 实现:

  按照计划执行

• 验证:

  运行测试并修复所有失败

• 提交:

  使用描述性信息提交这些更改

3. 利用无限会话

自动上下文窗口管理

Copilot CLI 拥有 无限会话功能。无需担心上下文耗尽。系统通过智能压缩自动管理上下文，概括对话历史并保留关键信息。

会话存储位置

~/.copilot/session-state/{session-id}/
├── events.jsonl      # Full session history
├── workspace.yaml    # Metadata
├── plan.md           # Implementation plan (if created)
├── checkpoints/      # Compaction history
└── files/            # Persistent artifacts

会话管理命令

要查看当前 CLI 会话信息，输入

/session

要查看会话检查点列表，输入

/session checkpoints

要查看特定检查点的详细信息，输入

/session checkpoints NUMBER

其中 NUMBER 为你想显示的检查点编号。

要查看当前会话期间创建的任何临时文件，例如不应保存到仓库的 Copilot 生成的产物，输入

/session files

要查看当前计划（若 Copilot 已生成），输入

/session plan

最佳实践：保持会话聚焦

虽然无限会话支持长时间工作，但聚焦会话能产出更好结果

• 在不相关任务之间使用 /clear 或 /new。
• 这会重置上下文并提升响应质量。
• 可以把它想象成与同事重新开始一次对话。

/context 命令

使用 /context 可可视化当前上下文使用情况。它会展示以下细分：

• 系统/工具 token
• 消息历史 token
• 剩余空间
• 缓冲区分配

4. 有效委派工作

/delegate 命令

将工作卸载到云端，由 Copilot 云代理运行。 这在以下场景尤为强大：

• 可异步执行的任务。
• 对其他仓库的更改。
• 不想等待的长时间运行操作。

示例提示

/delegate Add dark mode support to the settings page

会发生什么

• 你的请求会发送至 Copilot 云代理。
• 代理会基于更改创建一个 Pull Request。
• 在云代理处理期间，你可以继续本地工作。

何时使用 /delegate

使用 /delegate	本地工作
次要任务	核心功能工作
文档更新	调试
重构独立模块	交互式探索

5. 常见工作流

代码库入职

在加入新项目时，将 Copilot CLI 作为结对编程伙伴。例如，你可以询问 Copilot

• 此项目的日志配置是怎样的？
• 新增 API 接口的模式是什么？
• 解释认证流程
• 数据库迁移文件在哪里？

测试驱动开发

与 Copilot CLI 配对编写测试。

• 为用户注册流程编写失败的测试
• 审查并批准这些测试。
• 现在实现代码，使所有测试通过
• 审查实现。
• 提交并使用信息 "feat: add user registration"

代码审查辅助

• /review 使用 Opus 4.5 和 Codex 5.2 审查我当前分支相对于 `main` 的更改。重点关注潜在的错误和安全问题。

Git 操作

Copilot 在 Git 工作流中表现出色

• 哪些更改进入了版本 `2.3.0`？
• 为此分支创建一个带详细描述的 PR
• 将此分支变基到 `main`
• 解决 `package.json` 中的合并冲突

Bug 调查

• `/api/users` 接口间歇性返回 500 错误。搜索代码库和日志以确定根本原因。

重构

• /plan 将所有类组件迁移为使用 Hook 的函数组件

  随后回答 Copilot 的提问。审查它生成的计划，如有必要让 Copilot 进行修改。当对计划满意后，可提示：Implement this plan

6. 高级模式

跨多个仓库工作

Copilot CLI 提供灵活的多仓库工作流——是微服务、单体仓库或相关项目团队的关键差异化特性。

选项 1：从父目录运行

# Navigate to a parent directory containing multiple repos
cd ~/projects
copilot

Copilot 现在可以同时访问并跨所有子仓库工作，这非常适用于

• 微服务架构
• 在相关仓库之间进行协调性更改
• 跨项目重构共享模式

选项 2：使用 /add-dir 扩展访问范围

# Start in one repo, then add others (requires full paths)
copilot
/add-dir /Users/me/projects/backend-service
/add-dir /Users/me/projects/shared-libs
/add-dir /Users/me/projects/documentation

查看并管理允许的目录

/list-dirs

示例工作流：协调 API 更改

I need to update the user authentication API. The changes span:

- @/Users/me/projects/api-gateway (routing changes)
- @/Users/me/projects/auth-service (core logic)
- @/Users/me/projects/frontend (client updates)

Start by showing me the current auth flow across all three repos.

此多仓库功能实现了

• 全局重构（在所有位置更新共享模式）
• API 合约变更以及客户端更新
• 引用多个代码库的文档
• 单体仓库中的依赖升级

使用图像进行 UI 工作

Copilot 能处理视觉参考，只需 拖放 图像到 CLI 输入，或引用图像文件即可

Implement this design: @mockup.png
Match the layout and spacing exactly

复杂迁移的检查清单

针对大规模更改

Run the linter and write all errors to `migration-checklist.md` as a checklist.
Then fix each issue one by one, checking them off as you go.

自主任务完成

切换到 autopilot 模式，使 Copilot 能自主完成任务直至结束。这非常适合不需要持续监督的长时间任务。更多信息请参见 允许 GitHub Copilot CLI 自主工作。

可选地，你可以在提示开头使用 /fleet 命令，让 Copilot 将任务拆分为并行子任务，从而加速大任务的完成。更多信息请参见 使用 /fleet 命令并行运行任务。

7. 团队指南

推荐的仓库设置

• 创建 .github/copilot-instructions.md，内容包括

  • 构建和测试命令
  • 代码风格指南
  • 提交前的必需检查
  • 架构决策

• 建立约定，包括

  • 何时使用 /plan（复杂功能、重构）
  • 何时使用 /delegate（次要工作）
  • 使用 AI 辅助的代码审查流程

安全考虑因素

• Copilot CLI 对可能具破坏性的操作需要明确授权。
• 接受前请审查所有提议的更改。
• 谨慎使用权限白名单。
• 绝不要提交机密信息。Copilot 设计上会避免此类情况，但仍需自行核实。

衡量生产力

跟踪以下指标

• 从 issue 到 Pull Request 的时间
• 合并前的迭代次数
• 代码审查反馈循环
• 测试覆盖率提升

获取帮助

在命令行中，可使用 copilot -h 查看帮助。

要获取各主题帮助，输入

copilot help TOPIC

其中 TOPIC 可以是：config、commands、environment、logging 或 permissions。

在 CLI 中

在 CLI 中获取帮助，输入

/help

查看使用统计，输入

/usage

要向 GitHub 提交关于 Copilot CLI 的私密反馈、报告 bug 或提交功能请求，请输入

/feedback

实战练习

尝试 使用 Copilot CLI 创建应用程序 练习，获得实际构建应用的经验。

你将学习以下内容

• 安装 Copilot CLI
• 使用 issue 模板创建 issue
• 生成一个 Node.js CLI 计算器应用
• 扩展计算器功能
• 为计算器函数编写单元测试
• 创建、审查并合并你的 Pull Request

延伸阅读

• 关于 GitHub Copilot CLI
• 使用 GitHub Copilot CLI
• GitHub Copilot CLI 命令参考
• Copilot 计划与定价