如何让 IntelliJ IDEA 的 copilot 插件读取项目目录外的自定义 agents？

2026-11-04排障赵师傅

可以跨项目复用，前提是插件版本支持全局 custom agents。GitHub 在 2026 年 5 月 13 日的 JetBrains 插件更新中加入了这项功能，使用的目录是：

~/.copilot/agents/

将配置保存为 ~/.copilot/agents/code-reviewer.agent.md，多个工作区就能共用，无须在每个项目中重新定义。GitHub 官方更新说明

你已经试过这个路径，建议先检查插件是否包含这项更新，再排查符号链接和文件格式。目前还无法确定问题出在目录限制还是链接读取上。

为什么 CLI 能识别，IDEA 插件却不能

Copilot CLI 和 JetBrains 插件支持的功能、配置入口可能不同。CLI 能读取某个位置，不代表你安装的插件版本也会扫描那里。

设置界面只能创建工作区 agent，也不能据此判断插件只读取工作区文件。上述更新发布时，插件已经支持从全局目录加载 agent，只是还没有全局 agent 的界面管理功能。官方更新说明中的全局 agent 支持

符号链接不会扩大插件的扫描范围。如果链接放在插件不读取的位置，即使目标正确，也无法加载。

在 IntelliJ IDEA 的插件管理界面检查 GitHub Copilot 更新，安装支持全局 .agent.md 的版本，并按提示重启 IDE。

官方公告没有列出这项功能要求的最低插件版本号，无法据此指定版本。如果受 IDEA 兼容性要求影响，无法安装相关更新，需要先解决版本兼容问题。

先把现有配置复制到全局目录，排除符号链接的影响。以下命令适用于 macOS/Linux，源路径沿用问题中的 ~/config/copilot/agents/：

mkdir -p "$HOME/.copilot/agents"

cp -i "$HOME/config/copilot/agents/code-reviewer.agent.md" \
  "$HOME/.copilot/agents/code-reviewer.agent.md"

目标文件已存在时，cp -i 会询问是否覆盖。如果目标位置已有之前创建的符号链接，先检查并移走链接，再用普通文件验证。

agent 文件应以 .agent.md 结尾，并包含 YAML frontmatter。最小示例：

---
name: code-reviewer
description: 审查代码变更，查找缺陷和缺失的测试。
---

审查当前项目中的代码变更。

优先报告可能导致错误结果、异常或回归的问题。
每个问题注明文件位置、触发条件和修改建议。
不要修改文件；没有发现具体问题时，直接说明。

description 是必填字段。如果需要限制工具权限，应通过插件的 Configure Tools... 选择可用工具；提示词中的“不要修改文件”只是行为指令。官方 agent 配置说明

打开 GitHub Copilot Chat，在 agent 下拉列表中查找 code-reviewer。必要时重新打开聊天窗口或重启 IDE，再检查一次。

先确认列表中是否出现这个 custom agent。主 agent 能否将它作为 subagent 自动调用，取决于另一项能力，因此不能用是否发生自动调用来判断文件有没有加载。

可以尝试把链接放在插件支持的全局目录中：

mkdir -p "$HOME/.copilot/agents"

ln -s "$HOME/config/copilot/agents/code-reviewer.agent.md" \
  "$HOME/.copilot/agents/code-reviewer.agent.md"

执行前，确保目标位置没有同名文件或链接。可用以下命令查看链接，并检查目标是否可读：

ls -l "$HOME/.copilot/agents/code-reviewer.agent.md"
test -r "$HOME/.copilot/agents/code-reviewer.agent.md" && echo "readable"

GitHub 的全局目录公告没有明确保证插件如何处理符号链接，建议先确认普通文件能被识别，再换成链接：

如果链接无法使用，可以将唯一维护的配置直接放在 ~/.copilot/agents/，再按 CLI 支持的配置方式复用；也可以通过同步脚本更新这个目录。

官方已明确支持 ~/.copilot/agents/*.agent.md，可以满足个人在多个项目中复用 agent 的需求。不过，使用这个全局目录和自行指定扫描目录是两回事。上述官方说明没有提供指定任意外部目录的配置，也不能直接套用其他编辑器的设置项。

如果旧版本尚不支持全局 agents，项目级入口是：

<project>/.github/agents/code-reviewer.agent.md

这个路径相对于项目根目录，与用户主目录下的 ~/.github/agents/ 不同。JetBrains 工作区 agent 创建说明

global-copilot-instructions.md 用于自定义指令，不能代替 .agent.md 配置文件来注册可选 agent。将 agent 链接到这个文件名下，也无法完成注册。