JetBrains Context 配置 IntelliJ IDEA 教程

本文介绍如何将 JetBrains Context 接入 IntelliJ IDEA 中的 ACP Agent，让 Codex、Claude 等外部 AI Agent 在 IDEA 内使用代码索引和语义搜索能力。

本文配置的是 JetBrains Context 代码检索能力，不是 AI 模型 API Key 或 BYOK。模型供应商配置请参考项目中的《JetBrains IDE 配置指南》。

一、工作原理

JetBrains Context 会为代码仓库建立语义索引，并向 IntelliJ IDEA 中运行的 ACP Agent 提供：

• context-search Skill：按代码含义定位文件和实现。
• jbcontext MCP Server：让 Agent 通过 MCP 调用 Context。
• AGENTS.md 指令：告诉 Agent 何时使用语义搜索。IntelliJ IDEA 的自动配置目标名称是 intellij，配置目录为：

用户级：~/.ai项目级：项目根目录/.ai

IntelliJ ACP Agent 当前不安装 Context Hooks 和子代理；索引可以通过 CLI 手动执行。

二、环境要求

• IntelliJ IDEA 已安装并能正常打开项目。
• 已安装 JetBrains AI Assistant，并能在 AI Chat 中使用 Agents/ACP Agent。
• 已安装需要在 IDEA 中调用的外部 Agent，例如 Codex 或 Claude Code。
• 能访问 JetBrains 下载、登录和 Context 服务。在 IDEA 内置终端或系统终端中检查：

codex --versionclaude --version

只使用其中一个 Agent 时，另一个命令不存在不影响配置。

三、安装 JetBrains Context CLI

macOS 或 Linux 执行：

curl -fsSL https://download.jetbrains.com/jetbrains-context/release/download-jbcontext.sh | bash

默认安装目录通常是：

~/.jbcontext/bin

Zsh 用户重新加载 PATH：

source ~/.zshrcrehash

Bash 用户执行：

source ~/.bashrc

验证安装：

command -v jbcontextjbcontext --versionjbcontext --help

如果提示 command not found: jbcontext，可以先使用完整路径：

~/.jbcontext/bin/jbcontext --help

也可以手动将安装目录加入 Zsh PATH：

echo 'export PATH="$PATH:$HOME/.jbcontext/bin"' >> ~/.zshrcsource ~/.zshrcrehash

四、登录 JetBrains Context

执行：

jbcontext login

根据终端和浏览器提示：

1. 登录 JetBrains 账号。
2. 授权 JetBrains Context CLI。
3. 阅读并确认 JetBrains Context CLI 用户协议。登录成功后再继续配置 IDEA。

五、选择配置范围

JetBrains Context 支持用户级和项目级两种配置方式。

用户级配置

推荐个人开发环境使用。配置一次后，当前用户在多个项目中使用 IntelliJ ACP Agent 时都能识别 Context。

配置位置：

~/.ai/AGENTS.md~/.ai/skills/context-search/SKILL.md~/.ai/mcp/mcp.json

项目级配置

适合团队统一项目配置。相关文件位于项目仓库中，可以选择提交到 Git，供团队成员共享 Agent 指令和 MCP 配置。

配置位置：

项目根目录/AGENTS.md项目根目录/.ai/skills/context-search/SKILL.md项目根目录/.ai/mcp/mcp.json

项目级配置中，MCP 命令可能包含安装者本机的绝对路径。提交前应检查 .ai/mcp/mcp.json，避免把个人路径直接作为团队通用配置。

六、配置 IntelliJ IDEA ACP Agent

方式一：用户级配置（推荐）

执行：

jbcontext setup-agent --agent intellij --auto --scope user

非交互执行：

jbcontext setup-agent --agent intellij --auto --scope user --non-interactive

该命令通常会：

• 安装 context-search Skill 到 ~/.ai/skills。
• 将 Context 使用指令写入 ~/.ai/AGENTS.md。
• 将 jbcontext MCP Server 写入 ~/.ai/mcp/mcp.json。

方式二：项目级配置

先进入项目根目录：

cd /path/to/project

执行：

jbcontext setup-agent --agent intellij --auto --scope project

非交互执行：

jbcontext setup-agent --agent intellij --auto --scope project --non-interactive

该命令通常会：

• 安装 Skill 到项目的 .ai/skills。
• 将 Context 指令合并到项目根目录的 AGENTS.md。
• 将 MCP Server 写入项目的 .ai/mcp/mcp.json。

七、配置前预览

如果不希望直接修改配置，可以先查看安装器将执行的操作。

预览用户级配置：

jbcontext setup-agent --agent intellij --scope user --dump-auto --print-instructions

预览项目级配置：

jbcontext setup-agent --agent intellij --scope project --dump-auto --print-instructions

预览命令不会安装配置。

八、在 IntelliJ IDEA 中启用

完成 CLI 配置后：

1. 完全退出 IntelliJ IDEA。
2. 重新打开 IDEA 和目标项目。
3. 打开 AI Assistant 的 AI Chat 工具窗口。
4. 切换到 Agents 或 ACP Agent 模式。
5. 选择已经配置好的 Codex、Claude Code 或其他兼容 Agent。
6. 新建会话，确保 Agent 重新加载 AGENTS.md、Skills 和 MCP 配置。不同 IDEA 和 AI Assistant 版本的菜单名称可能略有区别。如果看不到 Agents/ACP Agent：

• 更新 IntelliJ IDEA。
• 更新 JetBrains AI Assistant 插件。
• 在 Settings/Preferences → Plugins 中确认 AI Assistant 已启用。
• 打开 AI Chat 后检查 Agent 选择器。

九、建立项目索引

在 IDEA 内置终端中进入项目根目录：

cd /path/to/project

建立或更新索引：

jbcontext index

查看索引状态：

jbcontext status

项目代码发生较大变化后，可以重新执行：

jbcontext index

十、在 IDEA Agent 中使用

可以直接在 AI Chat 的 Agent 会话中输入：

使用 context-search 查找项目中的用户登录、Token 生成和权限校验流程。

先通过 jbcontext 语义搜索定位订单退款实现，再分析完整调用链。

使用 context-search 查找所有负责消息失败重试和死信处理的代码。

如果已知大致目录，可以要求 Agent 缩小范围：

使用 jbcontext 在 src/auth 目录中查找 JWT Token 刷新逻辑。

推荐让 Agent 在不知道代码位置时先使用 Context；已经知道明确文件、类名或方法名时，直接打开文件或精确搜索通常更快。

十一、在 IDEA 终端手动搜索

语义搜索：

jbcontext search "用户身份认证和访问令牌校验流程"

限制搜索目录：

jbcontext search -p src/auth "JWT Token 的签发、刷新和失效处理"

建议使用完整自然语言描述目标功能，不要只输入单个模糊关键词。

十二、检查配置是否生成

检查用户级配置：

ls -la ~/.aicat ~/.ai/mcp/mcp.jsoncat ~/.ai/AGENTS.md

检查项目级配置：

ls -la .aicat .ai/mcp/mcp.jsoncat AGENTS.md

检查 Skill：

find ~/.ai/skills/context-search -maxdepth 2 -type f -print

项目级配置则执行：

find .ai/skills/context-search -maxdepth 2 -type f -print

十三、更新配置

更新 JetBrains Context CLI：

jbcontext upgrade

更新后重新执行安装命令，可刷新安装器管理的配置块：

jbcontext setup-agent --agent intellij --auto --scope user --non-interactive

项目级配置执行：

jbcontext setup-agent --agent intellij --auto --scope project --non-interactive

十四、移除配置

移除用户级 IDEA 集成：

jbcontext remove-agent --agent intellij --scope user

移除当前项目的 IDEA 集成：

jbcontext remove-agent --agent intellij --scope project

无人值守执行时追加：

--non-interactive

只移除特定组件时，可以使用 --skills、--instructions 或 --mcp。执行前查看当前版本帮助：

jbcontext remove-agent --help

十五、常见问题

1. IDEA 中看不到 ACP Agent

• 确认 JetBrains AI Assistant 插件已安装并启用。
• 更新 IDEA 和 AI Assistant 插件。
• 打开 AI Chat，检查 Agent 模式或 Agent 选择器。
• 确认 Codex、Claude Code 等外部 Agent 已单独安装并能在终端运行。

2. Agent 没有使用 Context

1. 完全退出并重启 IDEA。
2. 新建 Agent 会话，不要继续使用配置前创建的旧会话。
3. 执行 jbcontext status 检查索引。
4. 明确要求 Agent 使用 context-search 或 jbcontext。
5. 检查 ~/.ai/mcp/mcp.json 或 .ai/mcp/mcp.json 是否存在。
6. 重新执行对应的 setup-agent 命令。

3. IDEA 启动的 Agent 找不到 jbcontext

GUI 启动的 IDEA 有时不会读取终端的 .zshrc。自动配置生成的 MCP 通常使用 jbcontext 的绝对路径，因此先检查：

cat ~/.ai/mcp/mcp.json

确认其中的命令指向真实文件，例如：

/Users/你的用户名/.jbcontext/bin/jbcontext

同时检查该文件：

ls -la ~/.jbcontext/bin/jbcontext

4. 项目级配置在同事电脑上无法使用

检查 .ai/mcp/mcp.json 是否写入了安装者本机的绝对路径。每位成员可以在自己的项目目录中重新执行：

jbcontext setup-agent --agent intellij --auto --scope project

这会按当前用户的实际安装路径刷新 MCP 配置。

5. 搜索结果过旧或不准确

jbcontext indexjbcontext status

搜索时使用完整功能描述；已知模块目录时使用 -p 缩小范围。

十六、团队快速配置

个人电脑推荐执行用户级配置：

curl -fsSL https://download.jetbrains.com/jetbrains-context/release/download-jbcontext.sh | bashsource ~/.zshrcjbcontext loginjbcontext setup-agent --agent intellij --auto --scope user

项目团队希望共享配置时，在项目根目录执行：

jbcontext setup-agent --agent intellij --auto --scope project

完成后重启 IntelliJ IDEA，打开 AI Chat 的 ACP Agent 新会话，并在项目根目录执行一次 jbcontext index。