Context Mode 支持 14 个 AI 编程平台，按安装复杂度分为三档：Claude Code 最简单（Plugin Marketplace 一条命令），Gemini CLI / VS Code Copilot / Cursor 需要手动配置 Hook，Antigravity / Kiro / Zed 只支持 MCP-only 模式（无 Hook，靠路由指令约束）。本文重点讲解三个主流平台的完整安装流程，其他平台给出配置要点。

前置条件

平台	最低版本	Node.js
Claude Code	v1.0.33+	内置
Gemini CLI	—	18+
VS Code Copilot	Chat v0.32+	18+
Cursor	—	18+
Codex CLI	—	18+

更新 Claude Code：

brew upgrade claude-code
# 或
npm update -g @anthropic-ai/claude-code

Claude Code 安装（推荐）

Claude Code 是 Context Mode 的主力平台，支持 Plugin Marketplace 安装，Hook 全自动注册。

方式一：Plugin Marketplace（推荐）

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

重启 Claude Code（或执行 /reload-plugins）。

方式二：MCP-only（纯 MCP，无 Hook）

claude mcp add context-mode -- npx -y context-mode

只有 6 个沙盒工具，没有自动路由强制。适合先试用再决定是否装完整版。

验证安装

/context-mode:ctx-doctor

所有检查项应显示 [x]。Doctor 会验证：运行时检测（Node/Bun/Python 等）、Hook 注册状态、FTS5 数据库、插件版本。

安装后会发生什么

Plugin 安装完成后自动注册：

Hook	作用
PreToolUse	拦截大输出工具，路由到沙盒执行
PostToolUse	记录每次工具调用的事件
PreCompact	压缩前构建会话快照
SessionStart	恢复会话状态，注入路由指令
UserPromptSubmit	捕获用户决策和修正

注册的 MCP 工具：

工具	作用
ctx_execute	在沙盒中运行代码（11 种语言）
ctx_batch_execute	批量执行命令 + 搜索
ctx_execute_file	在沙盒中处理文件
ctx_index	将 Markdown 分块索引到 FTS5
ctx_search	全文搜索已索引内容
ctx_fetch_and_index	抓取 URL 并索引（24h 缓存）

Slash 命令：

命令	功能
/context-mode:ctx-stats	查看上下文节省统计
/context-mode:ctx-doctor	安装健康诊断
/context-mode:ctx-upgrade	升级到最新版本
/context-mode:ctx-purge	删除所有已索引内容
/context-mode:ctx-insight	个人分析仪表盘（Web UI）

Gemini CLI 安装

全局安装

npm install -g context-mode

配置 ~/.gemini/settings.json

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
      }
    ],
    "AfterTool": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]
      }
    ],
    "PreCompress": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]
      }
    ]
  }
}

TIP

BeforeTool 的 matcher 只拦截大输出工具（run_shell_command、read_file 等），避免对轻量工具造成不必要的 Hook 开销。

验证

重启 Gemini CLI，执行：

/mcp list

应看到 context-mode: ... - Connected。

VS Code Copilot 安装

全局安装

npm install -g context-mode

配置 MCP

在项目根目录创建 .vscode/mcp.json：

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

配置 Hook

在 .github/hooks/ 目录下创建 Hook 配置文件。详细格式参考 platform-support.md。

WARNING

VS Code Copilot 的 Hook 仍在 Preview 状态，API 可能变更。

Cursor 安装

全局安装

npm install -g context-mode

配置 MCP

创建 .cursor/mcp.json 或 ~/.cursor/mcp.json：

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

配置 Hook

创建 .cursor/hooks.json：

{
  "preToolUse": [
    {
      "matcher": "",
      "command": "context-mode hook cursor pretooluse"
    }
  ],
  "postToolUse": [
    {
      "matcher": "",
      "command": "context-mode hook cursor posttooluse"
    }
  ],
  "stop": [
    {
      "matcher": "",
      "command": "context-mode hook cursor stop"
    }
  ]
}

WARNING

Cursor 的 sessionStart Hook 存在已知 Bug（validator 会拒绝），Context Mode 目前通过 stop + postToolUse 组合弥补。postToolUse 的 additional_context 注入也存在上游 Bug（不被模型读取），路由强制主要靠 .mdc 规则文件。

其他平台

Codex CLI

npm install -g context-mode

Hook 配置：~/.codex/hooks.json（JSON 格式，与 Claude Code 结构相同） MCP 配置：~/.codex/config.toml（TOML 格式，[mcp_servers] 段）

OpenCode

OpenCode 使用 TypeScript 插件范式（非 JSON stdin/stdout），在 opencode.json 的 plugin 数组中注册 npm 包名。

Antigravity / Kiro / Zed

MCP-only 模式，无 Hook 支持。Context Mode 会自动写入路由指令文件（GEMINI.md / KIRO.md）到项目根目录，依赖模型自觉遵循。路由指令覆盖率约 60%。

升级与卸载

升级

Claude Code 用户：

/context-mode:ctx-upgrade

其他平台：

context-mode upgrade

卸载

Claude Code：

/plugin uninstall context-mode@context-mode

全局 npm 安装的：

npm uninstall -g context-mode

FAQ

Q: 全局安装和 npx 的区别？

全局安装后 context-mode 命令在 PATH 里，Hook 命令可以直接写 context-mode hook claude-code pretooluse。用 npx 的话每次执行都会临时下载，速度慢且 Hook 配置路径会变长。推荐全局安装。

Q: 多个项目会冲突吗？

不会。Session 数据按项目路径哈希隔离，存储在各自的 Session 目录中。不同平台的 Session 目录也不同（如 ~/.claude/context-mode/sessions/ vs ~/.cursor/context-mode/sessions/）。

Q: Claude Code Plugin 安装和 MCP-only 安装能共存吗？

不推荐。Plugin 已包含 MCP Server 注册，再手动添加会导致双实例。如果想从 MCP-only 升级到 Plugin，先执行 claude mcp remove context-mode，再装 Plugin。