copilot-cli

name	copilot-cli
description	GitHub Copilot CLI — 安装、认证、三种模式、工具权限、上下文管理、GitHub 集成、Custom Agents、MCP、Hooks
version	1.1.0
tags	["copilot","github","cli","agent","mcp"]

GitHub Copilot CLI v1.0.40+

安装

推荐（Linux/macOS）：

curl -fsSL https://gh.io/copilot-install | bash

Homebrew：

brew install copilot-cli

pip（任意平台）：

pip install github-copilot-cli

验证：

copilot --version

⚠️ 注意：gh copilot 扩展已于 2025 年 9 月废弃，所有功能已迁移到独立的 copilot CLI。

---

认证

关键：需要 Fine-Grained PAT（ghp_ 开头的不行）

Fine-Grained PAT 创建：https://github.com/settings/tokens 需要勾选 Copilot scope。

三种认证方式：

# 方式1：Web 登录（需浏览器）
copilot login

# 方式2：环境变量（推荐自动化）
export COPILOT_GITHUB_TOKEN=$(gh auth token)

# 方式3：直接指定 PAT
export COPILOT_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
copilot

---

三种运行模式

用 Shift+Tab 循环切换模式。

交互模式（默认）

copilot

• 每条指令需要确认后才执行
• 按需提问澄清
• 文件修改和命令执行前会弹出权限确认

Plan 模式（推荐复杂任务）

# 在交互模式内按 Shift+Tab 切换，或启动时：
copilot --mode plan

• 不直接写代码，先生成结构化实施计划
• 可在执行前修改、调整单个步骤
• 适合多步骤重构、复杂功能设计

自动驾驶模式（Autopilot）

copilot --mode autopilot -p "实现 xxx 功能"

• 自动执行，不需要手动确认
• 适合已充分理解的任务

---

工具权限控制

权限标志说明

标志	说明
--allow-tool 'shell(COMMAND)'	允许特定 shell 命令（可重复使用）
--allow-tool 'write'	允许所有文件修改
--allow-tool 'shell'	允许所有 shell 命令
--allow-all-tools / --yolo	全部允许（谨慎使用）
--deny-tool 'shell(rm)'	拒绝特定命令（优先级最高）
--allow-tool 'postgres'	允许 MCP server 的工具

权限示例

# 允许运行 pytest 和写文件（无需每次确认）
copilot -p "运行测试并报告结果" --allow-tool 'shell(pytest)' --allow-tool 'write'

# 允许所有但拒绝危险操作
copilot --allow-all-tools --deny-tool 'shell(rm)' --deny-tool 'shell(git push)'

# 允许 MCP server（需先配置 MCP）
copilot --allow-tool 'postgres' --allow-tool 'postgres(query)'

交互模式内权限

1. Yes                          — 允许本次
2. Yes, and approve for session  — 本次会话内不再询问
3. No + 说明                     — 拒绝并告诉 Copilot 怎么处理

---

模型选择

/model 命令

交互模式内输入：

/model

可选 Auto（自动选最优模型）或指定模型。

常见模型（2026年2月）：

模型	倍率	备注
Claude Sonnet 4.6	1×	默认，代码能力强
Claude Opus 4.6	varies	复杂规划任务
GPT-5.3-Codex	varies	Agentic 任务更快
Auto	—	自动选择最优模型

启动时指定

copilot --model claude-sonnet-4.6

Auto 模式比手动选择便宜 10%（Pro+ 及以上）。Auto 不会选有 premium multiplier > 1× 的模型。

---

上下文管理

/context — 查看 token 使用

/context

显示：系统提示词 / 对话历史 / 剩余可用 token。

/compact — 压缩上下文

/compact

压缩对话历史，保留关键信息。需要时按 Escape 取消。

自动压缩在会话达到 95% token 限制时自动触发，可实现几乎无限的会话长度。

---

GitHub.com 集成（内置 MCP）

Copilot CLI 内置 GitHub MCP server，无需额外配置即可使用：

copilot

常用指令

List my open PRs
List all open issues assigned to me in owner/repo
Check the changes made in PR https://github.com/owner/repo/pull/123
Use the GitHub MCP server to find good first issues for owner/repo

在 Issue 上工作

I've been assigned this issue: https://github.com/<owner>/<repo>/issues/<number>. Start working on this in a suitably named branch.

Copilot 会：读取 Issue → 创建分支 → 实现 → 运行测试 → 汇报。

创建 PR

In the root of this repo, add health_check.py. Create a pull request against main.

---

远程 Agent Task（gh agent-task）

在云端 Codespace 运行，不占用本地资源，适合长任务。

# 关联 Issue 创建远程任务
gh agent-task create --repo <owner>/<repo> --issue <number> \
  --body "Add docstrings to the new code"

# 列出所有任务
gh agent-task list --repo <owner>/<repo>

# 查看任务状态
gh agent-task view <task-id> --repo <owner>/<repo>

# 查看完成后的 PR
gh pr view <pr-number> --web

Agent Task 需要 Copilot Pro 或更高版本。

---

Custom Agents（自定义代理）

创建 Agent

在项目 .github/agents/ 目录下创建：

---
name: fastapi-expert
description: FastAPI 专家代理
---

## Role
你是 Python 后端工程师，专精 FastAPI 和异步 Python。

## Conventions
- 使用 async/await 处理所有 I/O 操作
- 使用 Pydantic 定义所有请求/响应模型
- 使用依赖注入管理共享资源
- 遵循 RESTful 命名规范
- 使用正确的 HTTP 状态码

使用 Agent

@fastapi-expert Add rate limiting middleware

Agent 名称前加 @ 调用。

---

Custom Instructions（自定义指令）

在 .github/ 目录创建 copilot-instructions.md：

# Project Guidelines

## Technology Stack
- Framework: FastAPI
- Testing: pytest with pytest-mock
- Validation: Pydantic v2

### Coding Style
- 遵循 PEP 8
- 使用类型提示
- 使用 f-strings
- 公共函数添加 Google-style docstrings

### Testing Guidance
- 使用 pytest
- 使用 pytest-mock mock 外部依赖
- 测试命名：`test_<function>_<scenario>`

### Architecture
- 路由、模型、工具函数分离
- 使用 Pydantic 定义 schema

作用域指令

在 .github/instructions/ 下按目录应用：

---
applyTo: "webapp/**/*.py"
---

## API Conventions
- PascalCase 类名
- 使用 type hints
- 为 endpoint 函数添加详细 docstrings

---

MCP Servers（扩展工具）

配置文件

用户级（所有项目）：~/.copilot/mcp-config.json 项目级：.github/mcp.json

示例：PostgreSQL MCP

{
  "servers": {
    "postgres": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DATABASE_URL", "mcp/postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

使用 MCP 工具

交互模式内查看已配置的 MCP servers：

/mcp

然后用自然语言调用：

Use the postgres MCP server to show me the schema of the users table.

预批准 MCP 工具

# 允许整个 server
copilot --allow-tool 'postgres'

# 只允许特定工具
copilot --allow-tool 'postgres(query)' --deny-tool 'postgres(execute)'

---

Copilot Memory（跨会话记忆）

# 查看当前记忆
/memory

Copilot 会记住项目规范、偏好设置，下次启动无需重复说明。

---

Hooks（写文件后自动执行）

创建 Hook

.github/hooks/post-write.sh：

#!/bin/bash
if [[ "$COPILOT_HOOK_FILE" == *.py ]]; then
  ruff check --fix "$COPILOT_HOOK_FILE"
  ruff format "$COPILOT_HOOK_FILE"
fi

注册 Hook

.github/hooks/config.json：

{
  "hooks": [
    { "event": "post-write", "command": ".github/hooks/post-write.sh" }
  ]
}

---

Community Extensions（Awesome Copilot）

# 添加插件市场
copilot plugin marketplace add github/awesome-copilot

# 安装 awesome-copilot 插件
copilot plugin install awesome-copilot@awesome-copilot

然后在交互模式内：

/awesome-copilot:suggest-awesome-github-copilot-skills
/awesome-copilot:suggest-awesome-github-copilot-instructions
/awesome-copilot:suggest-awesome-github-copilot-agents

---

实际工作流模板

完整 Python 功能开发流程

Stage 1 → 探索（默认模式）
  copilot
  "Show me all files involved in the /token endpoint"

Stage 2 → 设计（Plan 模式）
  [Shift+Tab] → Plan 模式
  "Add pagination to /token endpoint..."

Stage 3 → 构建测试
  Copilot 实现代码 → 运行 pytest → 自我修正
  /context  → 检查 token 使用
  /compact   → 压缩上下文

Stage 4 → 提交 PR
  "Commit with conventional commit and create PR"

Stage 5 → 异步完善（远程 Agent）
  gh agent-task create --repo owner/repo --issue <num> \
    --body "Add docstrings"

表格式总结

阶段	模式	工具	动作
探索	默认	Copilot CLI	自然语言映射文件
设计	Plan	Copilot CLI	构建实施计划
构建	默认/Plan	Copilot CLI	实现 + pytest + 自我修正
上下文	—	/context + /compact	管理 token 使用
交付	—	GitHub MCP	提交 + PR
完善	—	gh agent-task	异步文档生成

---

参考资源

• 官方文档：https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli
• 安装指南：https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli
• Copilot CLI 参考：https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli
• 官方课程（微软）：https://github.com/microsoft/Mastering-GitHub-Copilot-for-Paired-Programming
• Awesome Copilot：https://github.com/github/awesome-copilot