Copilot.el

Copilot.el 是一个用于 GitHub Copilot 的 Emacs 插件。它提供了内联补全（幽灵文本）、交互式聊天界面以及下一次编辑建议——所有这些功能都由官方的 @github/copilot-language-server 提供支持。

该插件通过 JSON-RPC 与 Copilot 语言服务器通信，直接使用 jsonrpc.el 而不是通过像 eglot 这样的 LSP 客户端。这是一个有意的选择——Copilot 协议的大部分内容并非标准的 LSP，并且所有缓冲区和项目共享同一个全局服务器。完整的理由请参阅 doc/design.md。

[!NOTE]

您需要访问 GitHub Copilot 才能使用此插件。该服务在 2025 年初推出了免费层级。

需求

copilot.el 需要 Emacs 27 或更高版本，以及以下软件包（可从 MELPA 自动安装）：

• editorconfig
• jsonrpc
• compat
• track-changes

@github/copilot-language-server 则需要 Node.js 22 或更高版本。

快速入门

(use-package copilot
  :ensure t
  :hook (prog-mode . copilot-mode)
  :bind (:map copilot-completion-map
              ("<tab>" . copilot-accept-completion)
              ("TAB" . copilot-accept-completion)
              ("C-<tab>" . copilot-accept-completion-by-word)
              ("C-TAB" . copilot-accept-completion-by-word)
              ("C-n" . copilot-next-completion)
              ("C-p" . copilot-previous-completion)))

然后运行 M-x copilot-install-server 和 M-x copilot-login。就完成了！

安装

MELPA

安装 copilot.el 最简单的方式是从 MELPA 获取：

(use-package copilot
  :ensure t)

或者使用 M-x package-install RET copilot RET。

Emacs 30+ (use-package :vc)

(use-package copilot
  :vc (:url "https://github.com/copilot-emacs/copilot.el"
            :rev :newest
            :branch "main"))

Emacs 27-29 (straight / quelpa)

straight.el:

(use-package copilot
  :straight (:host github :repo "copilot-emacs/copilot.el" :files ("*.el"))
  :ensure t)

quelpa + quelpa-use-package:

(use-package copilot
  :quelpa (copilot :fetcher github
                   :repo "copilot-emacs/copilot.el"
                   :branch "main"
                   :files ("*.el")))

手动安装

克隆本仓库，确保已安装 需求 中列出的依赖项，然后：

(add-to-list 'load-path "/path/to/copilot.el")
(require 'copilot)

Doom Emacs

(package! copilot
  :recipe (:host github :repo "copilot-emacs/copilot.el" :files ("*.el")))

;; 接受 Copilot 的补全并回退到 company
(use-package! copilot
  :hook (prog-mode . copilot-mode)
  :bind (:map copilot-completion-map
              ("<tab>" . 'copilot-accept-completion)
              ("TAB" . 'copilot-accept-completion)
              ("C-TAB" . 'copilot-accept-completion-by-word)
              ("C-<tab>" . 'copilot-accept-completion-by-word)))

(after! (evil copilot)
  ;; 定义一个自定义函数，要么接受补全，要么执行默认行为
  (defun my/copilot-tab-or-default ()
    (interactive)
    (if (and (bound-and-true-p copilot-mode)
             ;; 如有必要，可以添加其他条件来检查 Copilot 是否有活跃的建议
             )
        (copilot-accept-completion)
      (evil-insert 1))) ; 默认操作是插入一个制表符。可根据需要调整。

  ;; 将自定义函数绑定到 Evil 的插入模式下的 <tab>
  (evil-define-key 'insert 'global (kbd "<tab>") 'my/copilot-tab-or-default))

(use-package! copilot
  :hook (prog-mode . copilot-mode)
  :bind (:map copilot-completion-map
              ("<tab>" . 'copilot-accept-completion)
              ("TAB" . 'copilot-accept-completion)
              ("C-TAB" . 'copilot-accept-completion-by-word)
              ("C-<tab>" . 'copilot-accept-completion-by-word)
              ("C-n" . 'copilot-next-completion)
              ("C-p" . 'copilot-previous-completion))

  :config
  (add-to-list 'copilot-indentation-alist '(prog-mode 2))
  (add-to-list 'copilot-indentation-alist '(org-mode 2))
  (add-to-list 'copilot-indentation-alist '(text-mode 2))
  (add-to-list 'copilot-indentation-alist '(clojure-mode 2))
  (add-to-list 'copilot-indentation-alist '(emacs-lisp-mode 2)))

Spacemacs

;; ===================
;; dotspacemacs/layers
;; ===================

;; 添加或取消注释自动补全层
;; 添加 GitHub Copilot 层
dotspacemacs-configuration-layers
'(
  ...
  auto-completion
  github-copilot
  ...
 )

安装完包后，运行 M-x copilot-install-server 来安装语言服务器，然后运行 M-x copilot-login 进行认证。您可以通过 M-x copilot-diagnose 来验证一切是否正常工作（如果显示“NotAuthorized”，则表示您没有有效的订阅）。

配置

补全触发

使用 copilot-mode 可以在缓冲区中自动提供补全：

(add-hook 'prog-mode-hook 'copilot-mode)

或者使用 global-copilot-mode 在全局范围内启用：

(global-copilot-mode)

若要自定义补全何时触发，请查看 copilot-enable-predicates 和 copilot-disable-predicates。若要自定义补全何时显示，请查看 copilot-enable-display-predicates 和 copilot-disable-display-predicates。

此外，您也可以手动调用 copilot-complete，并在 post-command-hook 中使用 copilot-clear-overlay 来清除补全提示。

聊天

copilot-chat 使用 conversation/* LSP 方法打开与 GitHub Copilot 的交互式聊天。聊天缓冲区会实时流式显示响应，并自动提供当前缓冲区作为上下文。

;; 开始聊天（或在已有聊天窗口时发送后续消息）
M-x copilot-chat

;; 发送选中的代码并附带可选提示
M-x copilot-chat-send-region

*copilot-chat* 缓冲区中的快捷键：

• C-c RET 或 C-c C-c — 发送后续消息
• C-c C-k — 取消流式输出，或在空闲时重置
• q — 退出聊天窗口

自定义选项：

• copilot-chat-model — 用于聊天的模型（默认为 nil，即使用服务器默认值）

[!TIP]

安装 markdown-mode 可以在聊天缓冲区中实现丰富的 Markdown 渲染效果（标题、代码块、强调等）。如果没有安装该模式，则仅使用基本的语法高亮。

若需更丰富的聊天体验，请查看 copilot-chat.el。

[!WARNING]

copilot-chat.el（chep 包）和 copilot.el 都提供了名为 copilot-chat 的 Emacs 功能，因此它们 不能同时安装。同时安装会导致自动加载错误，例如“无法定义函数 copilot-chat-display”。如果希望使用 copilot.el 内置的聊天功能，请确保卸载 chep/copilot-chat.el，反之亦然。

下一步编辑建议 (NES)

NES 根据您最近的编辑模式，预测您在文件中任何位置接下来想要进行的编辑。与内联补全（光标处的幽灵文本）不同，NES 建议可以替换或删除文件中任意位置的现有文本。

[!NOTE]

NES 需要 copilot-language-server 版本 1.434.0 或更高。如有需要，请运行 M-x copilot-reinstall-server 进行升级。

在缓冲区中启用 copilot-nes-mode 即可开始接收建议。它可与 copilot-mode 共存：

(add-hook 'prog-mode-hook #'copilot-nes-mode)

当有建议待处理时：

• TAB — 接受建议（如果距离较远会先跳转到建议位置，第二次按下则应用）
• C-g — 撤销建议

自定义变量：

• copilot-nes-idle-delay — 在请求建议之前需要等待的空闲时间（秒）（默认为 0.5）
• copilot-nes-auto-dismiss-move-count — 光标移动多少次后自动撤销建议（默认为 3）
• copilot-nes-auto-dismiss-distance — 光标与建议之间的最大行数，超过此值则自动撤销建议（默认为 40）

快捷键绑定

copilot-mode 默认不设置任何快捷键。您可以使用 copilot-completion-map（在补全覆盖层可见时生效）来绑定按键：

(keymap-set copilot-completion-map "<tab>" #'copilot-accept-completion)
(keymap-set copilot-completion-map "TAB" #'copilot-accept-completion)
(keymap-set copilot-completion-map "C-<tab>" #'copilot-accept-completion-by-word)
(keymap-set copilot-completion-map "C-TAB" #'copilot-accept-completion-by-word)
(keymap-set copilot-completion-map "M-n" #'copilot-next-completion)
(keymap-set copilot-completion-map "M-p" #'copilot-previous-completion)

Fish 风格的快捷键绑定

如果您使用 company-mode 或 corfu，TAB 键可能已被占用。一种受 Fish shell 启发的替代方案可以完全避免冲突——右箭头接受完整建议，而 forward-word/end-of-line 则部分接受建议：

(keymap-set copilot-completion-map "<right>" #'copilot-accept-completion)
(keymap-set copilot-completion-map "C-f" #'copilot-accept-completion)
(keymap-set copilot-completion-map "M-<right>" #'copilot-accept-completion-by-word)
(keymap-set copilot-completion-map "M-f" #'copilot-accept-completion-by-word)
(keymap-set copilot-completion-map "C-e" #'copilot-accept-completion-by-line)
(keymap-set copilot-completion-map "<end>" #'copilot-accept-completion-by-line)
(keymap-set copilot-completion-map "M-n" #'copilot-next-completion)
(keymap-set copilot-completion-map "M-p" #'copilot-previous-completion)

Zap 风格的部分接受方式

为了在覆盖层可见时自动重新映射内置的 zap 命令：

(keymap-set copilot-completion-map "<remap> <zap-to-char>" #'copilot-accept-completion-to-char)
(keymap-set copilot-completion-map "<remap> <zap-up-to-char>" #'copilot-accept-completion-up-to-char)

LSP 设置

您可以通过 copilot-lsp-settings 配置底层的 LSP 设置。可用选项的完整列表请参见 此处。

以下示例将 GitHub Enterprise 服务器设置为 https://example2.ghe.com，请将其替换为您自己的服务器地址。

(setopt copilot-lsp-settings '(:github-enterprise (:uri "https://example2.ghe.com"))) ;; 允许在不重启 LSP 的情况下更改值
(setq copilot-lsp-settings '(:github-enterprise (:uri "https://example2.ghe.com"))) ;; 或者

使用 setq 更改值时，必须重启 LSP（M-x copilot-diagnose）。登录时，身份验证流程的 URL 应与 copilot-lsp-settings 中设置的 URL 一致。

语言检测

Copilot.el 根据缓冲区的主要模式名称检测编程语言，去掉 -mode 部分。生成的 languageId 应与 此处 的表格匹配。您可以将不常见的主要模式映射添加到 copilot-major-mode-alist 中。如果没有正确设置语言，建议的质量可能会较差。

(add-to-list 'copilot-major-mode-alist '("enh-ruby" . "ruby"))

网络代理

格式：'(:host "127.0.0.1" :port 7890 :username "user" :password "password")，其中 :username 和 :password 是可选的。

例如：

(setq copilot-network-proxy '(:host "127.0.0.1" :port 7890))

处理服务器消息

copilot-on-request 注册一个处理器，用于接收来自语言服务器的 JSON-RPC 请求。返回值应为可序列化的 JSON 数据，或调用 jsonrpc-error 报告错误。更多信息。

;; 如果 Emacs 编译时支持 D-Bus，则显示桌面通知
(copilot-on-request
 'window/showMessageRequest
 (lambda (msg) (notifications-notify :title "Emacs Copilot" :body (plist-get msg :message))))

copilot-on-notification 注册一个监听器，用于接收传入的 LSP 通知。

(copilot-on-notification
  'window/logMessage
  (lambda (msg) (message (plist-get msg :message))))

命令

[!TIP]

你不必记住这些命令——只需输入 M-x copilot- 后按 TAB 键，或使用菜单栏中的 Copilot 菜单即可。

自定义

[!TIP]

使用 M-x customize-group RET copilot 来浏览所有可用的配置选项及其文档。

以下是一些常用的可调整变量：

• copilot-idle-delay — 触发补全前的等待时间（默认为 0 秒）。将其设置为 nil 可完全禁用自动补全。
• copilot-lsp-server-version — 锁定特定的 @github/copilot-language-server 版本（nil 表示最新版本）。
• copilot-enable-predicates / copilot-disable-predicates — 控制 copilot-mode 何时请求补全。
• copilot-enable-display-predicates / copilot-disable-display-predicates — 控制何时显示补全结果。
• copilot-clear-overlay-ignore-commands — 不会关闭覆盖层的命令。
• copilot-indentation-alist — 根据主要模式覆盖缩进宽度。
• copilot-enable-parentheses-balancer — 对 Lisp 模式下的补全结果进行后处理以平衡括号（默认为 t）。将其设置为 nil 可使用原始服务器补全结果。

协议支持

copilot.el 使用 LSP 协议以及 Copilot 特有的扩展，通过 JSON-RPC 与 @github/copilot-language-server 进行通信。下表显示了当前的支持情况。

客户端到服务器请求

客户端到服务器通知

服务器到客户端请求

服务器到客户端通知

可通过 copilot-on-request 和 copilot-on-notification 对上述未处理的消息进行扩展。

已知问题

其他补全弹出窗口位置错误

这是一个与 company-mode 默认前端一起使用的示例。由于 company-mode 和 copilot.el 都使用覆盖层来显示补全结果，冲突是不可避免的。推荐的解决方案是使用 company-box（仅限 GUI），它基于子框架而非覆盖层。

使用 company-box 后，效果如下：

在其他编辑器（如 VS Code、PyCharm）中，Copilot 和其他来源的补全结果不能同时显示。而在 copilot.el 中，它们可以共存，因此你可以随时选择更好的补全结果。

光标在输入时跳到行尾

如果您正在使用 whitespace-mode，请确保从 whitespace-style 中移除 newline-mark。

常见问题解答

我需要付费的 GitHub Copilot 订阅吗？

不一定。GitHub 在 2025 年初推出了 Copilot 的免费层级，包含每月有限数量的补全建议。付费订阅（个人或企业）则取消了这些限制。

TAB 键无法接受补全建议

这通常是由其他包以更高优先级绑定了 TAB 键导致的。常见的“罪魁祸首”包括 company-mode、corfu、yasnippet 和 Evil 模式。您可以尝试以下几点：

1. 同时绑定 <tab> 和 TAB。 在 GUI Emacs 中，它们是不同的事件——<tab> 是功能键，而 TAB 是 C-i 字符。有些模式只拦截其中一种。快速入门 示例中同时绑定了两者。
2. 使用 Fish 风格的快捷键。 如果 TAB 键被其他包彻底占用，可以将接受补全的按键改为 <right> 或 C-f。详情请参阅Fish 风格的快捷键。
3. Doom Emacs 用户——请参阅Doom Emacs 安装部分，了解如何通过自定义 Evil 插入模式绑定来解决此问题。

是否可以在不启用 copilot-mode 的情况下使用 copilot-complete？

可以。您可以在任何缓冲区中手动调用 M-x copilot-complete，它会自动启动服务器并打开文档。使用 copilot-clear-overlay（或直接输入内容）即可关闭提示。如果您更倾向于按需触发补全而非自动补全，这种方式非常实用。

补全速度慢或未出现

您可以尝试以下几种方法：

1. 运行 M-x copilot-diagnose——它会重启服务器并输出诊断信息。请注意是否有 NotAuthorized（订阅问题）或连接错误。
2. 检查网络连接——语言服务器需要访问 GitHub 的 API。如果您处于代理之后，请配置 copilot-network-proxy。
3. 大文件——超过 copilot-max-char 字符数（默认 100,000）的缓冲区会被跳过。您可以提高此限制，但非常大的文件始终会较慢。
4. 调整 copilot-idle-delay——默认值为 0（立即触发）。设置一个小的延迟（例如 0.2 秒）可以在快速输入时降低服务器负载。

如何在某些模式或缓冲区中禁用 Copilot？

使用 copilot-disable-predicates 添加函数，当返回 t 时 Copilot 将保持静默：

;; 在 org-mode 中禁用
(add-to-list 'copilot-disable-predicates
             (lambda () (derived-mode-p 'org-mode)))

或者直接不要将 copilot-mode 加入您希望排除的模式钩子中。如果您使用 global-copilot-mode，那么使用谓词方式是最合适的。

Lisp 补全中的括号不平衡

Copilot.el 包含一个括号平衡器，在 Lisp 模式（emacs-lisp-mode、clojure-mode、scheme-mode 等）中对补全结果进行后处理，以修复不平衡的分隔符。该功能默认启用。如果仍然遇到问题，请确保 copilot-enable-parentheses-balancer 设置为 t，否则请附上补全文本和缓冲区上下文提交 bug 报告。

如果括号平衡器影响了您的工作流程，可以将其禁用：

(setopt copilot-enable-parentheses-balancer nil)

如何选择不同的补全模型？

运行 M-x copilot-select-completion-model 可以交互式地从您订阅可用的模型中选择。选择结果会保存在 copilot-completion-model 中。将其设置为 nil 可恢复到服务器默认值。

注意： 只有具有“补全”范围的模型才可用于内联补全。像 Claude、Gemini 等您可能在 VS Code 的聊天界面中看到的模型，仅适用于聊天/编辑模式，无法用于内联补全。这是服务器端的限制，而非 copilot.el 的限制。目前 GitHub 仅提供单一的补全模型（gpt-41-copilot）。

要选择聊天模型，请运行 M-x copilot-chat-select-model。聊天模式下可用的模型更多（Claude、Gemini、GPT-4o 等）。选择结果会保存在 copilot-chat-model 中。

报告 Bug

• 更新插件后，请务必重启 Emacs，并在必要时重新构建插件。
• 异步请求错误（例如补全被取消）会自动记录到 *Messages* 缓冲区中。请先查看那里以获取线索。
• 若要进行更深入的调查，可以通过自定义 copilot-log-max（例如设置为 1000）启用事件日志，并通过 (setq copilot-server-args '("--stdio" "--debug")) 启用调试日志，然后粘贴来自 *copilot events*、*copilot stderr* 和 *copilot-language-server-log* 缓冲区的相关日志。
• 如果抛出异常，请同时粘贴堆栈跟踪信息（使用 M-x toggle-debug-on-error 启用堆栈跟踪）。

开发

有关架构和关键设计决策的概述，请参阅 doc/design.md。

运行测试

单元测试（需要 eask）：

eask test buttercup

代码检查

eask lint checkdoc
eask lint indent

集成测试

dev/integration-smoke.el 中包含一个手动集成测试，它会连接到真实的 Copilot 语言服务器，并验证 textDocument/inlineCompletion 的往返通信。此测试需要安装并认证服务器。

emacs --batch -L . -l dev/integration-smoke.el

历史

copilot.el 项目始于 2022 年 3 月。当时还没有公开的 Copilot 服务器包——唯一的方法是从 copilot.vim 内部提取 Node.js 客户端。早期版本的 copilot.el 通过对 copilot.vim 中 JSON-RPC 协议的逆向工程，复制了一份客户端代码并存储在仓库中，每次 copilot.vim 发布新版本时都会更新该副本。

2025 年初，GitHub 在 npm 上发布了官方的 @github/copilot-language-server。copilot.el 迁移到这个开源服务器，完全移除了对 copilot.vim 的依赖。此次切换还带来了新的协议特性，如 textDocument/inlineCompletion（取代了旧版的 getCompletions）、Copilot 聊天以及下一阶段的编辑建议等功能。

致谢

以下项目帮助实现了 copilot.el：

• copilot.vim — 最初的参考实现，其捆绑的客户端驱动了 copilot.el 前三年的发展。
• https://github.com/TommyX12/company-tabnine/ — 基于覆盖层的补全用户体验的灵感来源。
• https://github.com/cryptobadger/flight-attendant.el
• @github/copilot-language-server

团队

现任维护者：@bbatsov。

已卸任的维护者：@zerolfx、@emil-vdw、@jcs090218、@rakotomandimby。

支持项目发展

copilot.el 由志愿者在业余时间开发和维护。如果您觉得它很有用，请考虑支持其持续发展。

以下是您可以支持该项目的方式：

• GitHub Sponsors（定期或一次性捐赠）
• Patreon（定期捐赠）
• PayPal（一次性捐赠）

许可证

copilot.el 采用 MIT 许可证进行分发。

版权所有 © 2022–2026 copilot-emacs 维护者及贡献者。

Copilot.el 快速上手指南

Copilot.el 是一个 Emacs 插件，用于在编辑器中集成 GitHub Copilot 功能。它提供行内代码补全（幽灵文本）、交互式聊天界面以及下一步编辑建议（NES）。

环境准备

在开始之前，请确保您的系统满足以下要求：

• Emacs: 版本 27 或更高。
• Node.js: 版本 22 或更高（用于运行 Copilot 语言服务器）。
• GitHub Copilot 订阅: 您需要拥有有效的 GitHub Copilot 访问权限（该服务已于 2025 年初推出免费层级）。
• 依赖包: 以下 Emacs 包会在安装时自动从 MELPA 获取：
  • editorconfig
  • jsonrpc
  • compat
  • track-changes

安装步骤

1. 配置包管理器

推荐使用 use-package 进行配置。如果您使用 MELPA（最简便的方式），请在配置文件（如 init.el）中添加以下内容：

(use-package copilot
  :ensure t
  :hook (prog-mode . copilot-mode)
  :bind (:map copilot-completion-map
              ("<tab>" . copilot-accept-completion)
              ("TAB" . copilot-accept-completion)
              ("C-<tab>" . copilot-accept-completion-by-word)
              ("C-TAB" . copilot-accept-completion-by-word)
              ("C-n" . copilot-next-completion)
              ("C-p" . copilot-previous-completion)))

注意：如果您使用的是 Doom Emacs 或 Spacemacs，请参考原文中的特定配置章节进行适配。

2. 安装语言服务器

重启 Emacs 或重新加载配置文件后，执行以下命令安装后端语言服务器：

M-x copilot-install-server

3. 登录认证

服务器安装完成后，执行以下命令登录您的 GitHub 账户：

M-x copilot-login

按照提示在浏览器中完成授权即可。

4. 验证安装

您可以运行诊断命令来确认一切正常：

M-x copilot-diagnose

如果显示 NotAuthorized，请检查您的订阅状态或重新登录。

基本使用

安装并登录后，Copilot.el 将在编程模式（prog-mode）下自动激活。

行内补全 (Inline Completions)

当您在编写代码时，灰色的“幽灵文本”会自动出现作为建议。

• 接受建议: 按下 <Tab> 键。
• 按词接受: 按下 C-<Tab>。
• 切换建议: 使用 C-n (下一个) 或 C-p (上一个)。

交互式聊天 (Chat)

您可以直接与 Copilot 对话以获取代码解释或生成代码片段。

• 打开聊天窗口: M-x copilot-chat
• 发送选中代码: 选中代码区域后，执行 M-x copilot-chat-send-region。
• 常用快捷键 (在聊天缓冲区):
  • C-c RET: 发送跟进消息。
  • C-c C-k: 取消流式输出。
  • q: 关闭聊天窗口。

提示: 建议安装 markdown-mode 包，以便在聊天窗口中获得更好的 Markdown 渲染效果（如代码高亮、标题格式等）。

下一步编辑建议 (NES)

NES 功能会根据您最近的编辑模式，预测您在文件任何位置的下一步操作（包括替换或删除现有文本）。

• 启用: 在配置中添加 (add-hook 'prog-mode-hook #'copilot-nes-mode)。
• 接受建议: 当建议出现时，按下 <Tab> 键（如果光标距离较远，第一次按下会跳转，第二次按下应用）。
• 拒绝建议: 按下 C-g。