context-mode 接入 JetBrains Copilot 完整指南：MCP 工具路由、Hook 沙箱与会话持久化

context-mode 接入 JetBrains Copilot 完整指南：MCP 工具路由、Hook 沙箱与会话持久化

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

本文是一份面向 JetBrains IDE（IntelliJ IDEA、WebStorm、PyCharm、GoLand、Rider、CLion 等）用户的技术指南，讲解如何在 JetBrains 的 GitHub Copilot 插件中接入 context-mode：通过 Settings UI 注册 MCP 服务器、用 setup 命令写入.github/hooks/context-mode.json钩子配置，实现工具调用路由强制、工具输出沙箱（约 98% 上下文压缩）以及跨会话记忆持久化。读完本文，你将掌握从零配置、诊断验证到故障排查的完整实战流程，并理解 JetBrains Copilot 与 VS Code Copilot 共享的 hook 线协议及其底层实现原理。

前置条件

在开始之前，请确认以下环境就绪：

• Node.js 18+—— 验证方式：node --version。context-mode 的 MCP 服务器与 hook 分发器都以 Node 运行时为基础。
• 任意 JetBrains IDE—— IntelliJ IDEA、WebStorm、PyCharm、GoLand、Rider、CLion 等均可。
• GitHub Copilot 插件 v1.5.57+—— 通过Settings > Plugins > Marketplace搜索 "GitHub Copilot" 安装。JetBrains 侧的 MCP 与 hook 支持依赖该插件版本，低于此版本将无法正常注册服务器。

另外推荐先做全局安装，这样context-mode二进制会进入 PATH，后续 MCP 命令、hook 命令与doctor/upgrade等工具命令都能直接解析：

npm install -g context-mode

从 docs/platform-support.md 可以看到，JetBrains Copilot 属于JSON stdin/stdouthook 范式平台，MCP 服务器层 100% 可移植、无需适配器，只有 hook 层需要平台专属适配器。

MCP 配置：通过 Settings UI 注册服务器

JetBrains 与多数 CLI 工具不同——它通过 IDE 的 Settings UI 配置 MCP 服务器，而不是编辑配置文件。这也是 JetBrains 适配器在 doctor 诊断中无法通过 CLI 检查 MCP 注册状态的根本原因（见下文源码分析）。

操作步骤：

1. 打开你的 JetBrains IDE。
2. 进入Settings > Tools > AI Assistant > Model Context Protocol (MCP)。
3. 点击Add Server，按以下内容填写：
   • Name:context-mode
   • Command:npx
   • Args:-y context-mode
4. 点击OK保存。

如果已执行过全局安装，也可以把 Command 直接设为context-mode，Args 留空，这样会启动更快且不依赖网络拉取。

仓库内附带的 MCP 参考配置见 configs/jetbrains-copilot/mcp.json，其内容如下，可作为你在其他支持文件式配置的场景下的对照：

{ "servers": { "context-mode": { "command": "context-mode" } } }

注意：JetBrains 的 MCP 服务器命名约定与 VS Code Copilot 一致，暴露出来的工具名带f1e_前缀（而非 Claude Code 的mcp__server__tool格式），适配层已对此做了归一化处理。

Hook 安装：一条命令写入项目钩子

注册完 MCP 服务器后，还需要安装 hook，让 context-mode 能在工具调用前后、上下文压缩与会话启动等时机介入。使用自动化安装命令：

npx context-mode@latest setup --adapter jetbrains-copilot

该命令会在项目根目录创建.github/hooks/context-mode.json，内容如下：

{ "hooks": { "PreToolUse": [ { "type": "command", "command": "context-mode hook jetbrains-copilot pretooluse" } ], "PostToolUse": [ { "type": "command", "command": "context-mode hook jetbrains-copilot posttooluse" } ], "PreCompact": [ { "type": "command", "command": "context-mode hook jetbrains-copilot precompact" } ], "SessionStart": [ { "type": "command", "command": "context-mode hook jetbrains-copilot sessionstart" } ] } }

仓库中对应的完整 hook 配置参考见 configs/jetbrains-copilot/hooks.json，与上面结构一致。四个 hook 的职责：

hook 命令为什么是context-mode hook <platform> <event>？

从 src/adapters/jetbrains-copilot/hooks.ts 的源码可以看到，buildHookCommand始终输出 CLI 分发器形式：

return `context-mode hook jetbrains-copilot ${hookType.toLowerCase()}`;

采用 CLI 分发器而不是直接指向node ./node_modules/...的脚本路径，有四个实际好处（依据 docs/platform-support.md 的 "CLI Hook Dispatcher" 一节）：

• 任意目录下都能工作，无需每个项目单独npm install；
• 一次全局安装服务所有项目；
• context-mode upgrade可以原地升级 hook 实现；
• 配置文件中命令字符串短小、跨机器可移植。

另外，.github/hooks/context-mode.json是随仓库提交、团队共享的配置文件，若在命令里嵌入process.execPath或绝对 pluginRoot 路径会泄露本机信息并破坏跨机器移植性，因此必须使用可移植的context-mode hook ...形式（见 copilot-base.ts 中的设计说明）。

JetBrains Copilot 与 VS Code Copilot 共享同一套 hook 线协议（详见 src/adapters/copilot-base.ts 的类注释），因此 JetBrains 侧也支持以下额外的 PascalCase 事件：Stop（智能体回合结束）、SubagentStart、SubagentStop。但注意一个关键限制：matcher 会被解析但被忽略——所有 hook 会对所有工具触发，无法按工具名精确匹配（源码注释明确标注了这一点）。

hook 响应格式：hookSpecificOutput 包装

与 Claude Code 的扁平响应不同，JetBrains Copilot（同 VS Code Copilot）要求 hook 响应包在hookSpecificOutput包装器内并携带hookEventName。以参数改写为例：

{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "updatedInput": { "...": "..." } } }

该格式由 copilot-base.ts 中的formatPreToolUseResponse生成：拒绝工具时返回顶层permissionDecision: "deny"+reason；改写参数时返回上述包装结构；注入上下文时在hookSpecificOutput内放additionalContext。会话 ID 字段则是 camelCase 的sessionId（不是 Claude Code 的session_id）。

升级：保持版本最新

两种升级方式：

context-mode upgrade

或在 Copilot 聊天会话中直接输入ctx upgrade。升级会从 GitHub 拉取最新版本、重新构建，并重新配置所有已注册平台的 hook（MCP 服务器与 hook 分发器共用同一个全局二进制，升级后立即生效）。

验证：doctor 与 stats

运行诊断命令确认一切正常：

context-mode doctor

或在 Copilot 聊天会话中输入ctx doctor。所有检查项都应显示[x]。doctor 会校验：运行时、hook 注册、FTS5 全文检索、MCP 注册状态。

还可以在聊天会话中输入ctx stats查看上下文节省量、调用次数与会话统计——这正是"工具输出沙箱"效果的量化体现：未路由的原始命令单次可能向上下文倾倒约 56 KB 输出（见下文路由规则），而通过ctx_*沙箱工具处理后只保留 stdout 摘要。

doctor 对 JetBrains 的两个特殊警告

从 src/adapters/jetbrains-copilot/index.ts 源码可见，JetBrains 适配器的诊断有两个平台特性：

1. MCP 注册不可 CLI 检查：checkPluginRegistration()返回warn状态，因为 MCP 配置存在 IDE Settings UI 中（Settings > Tools > GitHub Copilot > MCP），不是项目内可读取的文件。修复建议是到 UI 中人工确认存在 context-mode 服务器条目。
2. hook 校验只检查必需项：validateHooks()强制校验PreToolUse与SessionStart（源码中REQUIRED_HOOKS定义），缺失时提示运行context-mode upgrade修复；同时提示 hook 包装脚本应解析到pluginRoot/hooks/jetbrains-copilot/*.mjs。

深入原理：JetBrains 适配器源码解析

JetBrains 平台适配器定义在 src/adapters/jetbrains-copilot/index.ts，继承自CopilotBaseAdapter，两者共享同一套解析（parse）与格式化（format）逻辑，仅在平台差异处覆写：

• 会话 ID 提取优先级（extractSessionId）：

  1. hook 输入中的sessionId字段（camelCase）；
  2. 环境变量JETBRAINS_CLIENT_ID（生成jetbrains-<id>）；
  3. 环境变量IDEA_HOME（生成idea-<pid>）；
  4. 兜底pid-<ppid>。

• 项目目录解析（getProjectDir）：优先IDEA_INITIAL_DIRECTORY，其次CLAUDE_PROJECT_DIR，最后process.cwd()。这也解释了 hook 脚本 hooks/jetbrains-copilot/pretooluse.mjs 中为什么把process.env.IDEA_INITIAL_DIRECTORY || process.env.CLAUDE_PROJECT_DIR作为项目目录传入路由核心。

• 配置目录：getConfigDir()返回<projectDir>/.github，指令文件为copilot-instructions.md（与 VS Code Copilot 同位置，即.github/copilot-instructions.md）。

• 会话存储：适配器构造时传入[".config", "JetBrains"]作为会话目录段，按 src/adapters/base.ts 的getSessionDir()逻辑，会话数据库默认落在~/.config/JetBrains/context-mode/sessions/（除非设置了上下文目录覆盖）。

hook 执行链

以 PreToolUse 为例，hooks/jetbrains-copilot/pretooluse.mjs 的执行链是：读取 stdin JSON →parseStdin归一化 → 调用routePreToolUse做路由决策（工具名、参数、项目目录、平台标识、会话 ID 全部参与）→formatDecision按 JetBrains 线协议格式化响应 → 输出到 stdout。PostToolUse、PreCompact、SessionStart三个 hook 脚本（hooks/jetbrains-copilot/ 目录下）走同样的瘦包装模式，复用共享的路由核心，不掺入 Claude Code 专属逻辑。对应的适配器测试见 tests/adapters/jetbrains-copilot.test.ts，其中验证了IDEA_INITIAL_DIRECTORY项目目录解析、hook 命令格式为context-mode hook jetbrains-copilot <event>等行为。

路由规则：让模型"先思考代码，再调用工具"

JetBrains Copilot 与 VS Code Copilot 一样，读取项目根的.github/copilot-instructions.md（见 configs/jetbrains-copilot/copilot-instructions.md）。这份路由规则是"软约束 + hook 硬执行"的配套：规则文件让模型偏好使用沙箱工具，而 PreToolUse hook 在模型违反规则时强制拦截。

规则的核心思想（也是 98% 上下文缩减的来源）：

• Think in Code：分析/统计/过滤/搜索/解析/转换数据时，用ctx_execute(language, code)写代码、只console.log答案，而不是把原始数据读进上下文。一段脚本代替十次工具调用。
• BLOCKED 清单：curl/wget、内联 HTTP（fetch('http、requests.get(等）、WebFetch/fetch 全部拦截，改用ctx_fetch_and_index(url, source)+ctx_search(queries)。
• REDIRECTED 清单：终端命令超过 20 行输出时改用ctx_batch_execute(commands, queries)；读文件做分析时改用ctx_execute_file(path, language, code)（读文件准备编辑时才用原生read_file）。
• 工具选择顺序：ctx_search查记忆 →ctx_batch_execute批量收集 →ctx_search追问 →ctx_execute/ctx_execute_file处理 →ctx_fetch_and_index抓取网页 →ctx_index入库。
• 会话连续性：技能、角色、决策在整个会话中保持，压缩/清空后知识库与统计保留，用ctx_search(sort: "timeline")在恢复会话时先检索再提问。
• ctx 命令映射：ctx stats→ctx_stats工具；ctx doctor→ctx_doctor工具并执行其返回的 shell 命令；ctx upgrade→ctx_upgrade；ctx purge→ctx_purge（清除知识库，需 confirm）。

故障排查

MCP 服务器无法连接

• 确认 Node.js 18+ 在 PATH 中（node --version）。
• 添加 MCP 服务器后重启 JetBrains IDE。
• 到 Settings > Tools > AI Assistant > MCP 确认 "context-mode" 显示绿色状态指示。

Hook 不触发

• 确认项目根存在.github/hooks/context-mode.json。
• JetBrains Copilot 从.github/hooks/读取 hook——与 VS Code Copilot 位置完全相同。
• 重新运行npx context-mode@latest setup --adapter jetbrains-copilot重新生成 hook 配置。

"context-mode: command not found"

• 全局安装：npm install -g context-mode。
• 验证which context-mode能返回路径。
• 若使用npx，确保 npx 在 IDE 的 PATH 中（JetBrains 从 IDE 启动的子进程可能不继承 shell 的 PATH 配置，需在 IDE 中补充）。

工具可见但路由未被强制

• Hook 以编程方式强制执行路由；没有 hook 时，模型仍能调用 context-mode 工具，但不会被重定向去优先使用它们。
• 确保 hook 配置文件位于.github/hooks/context-mode.json（不是.github/hooks.json——这是两类平台配置位置最容易混淆的点）。

会话连续性不工作

• 确认四个 hook（PreToolUse、PostToolUse、PreCompact、SessionStart）都已配置。
• 运行ctx doctor检查 hook 注册状态。

小结

JetBrains Copilot 接入 context-mode 的完整链路可以概括为三步：Settings UI 注册 MCP 服务器（提供ctx_*沙箱与记忆工具）→setup 命令写入.github/hooks/context-mode.json（四个 hook 实现路由强制、输出捕获、压缩快照与会话恢复）→doctor/stats 验证（确认运行时、hook、FTS5 与 MCP 全部就绪）。由于 JetBrains Copilot 与 VS Code Copilot 共享 hook 线协议与配置目录，熟悉任意一方都能快速迁移；而其"配置在 UI、hook 在项目文件"的双轨模式，则是排障时最需要牢记的平台特性。

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode