Context Mode 支持 14 个 AI 编程平台，分为三种 Hook 范式：JSON stdin/stdout（Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、Cursor、Codex CLI、Qwen Code）、TS Plugin（OpenCode）、MCP-only（Antigravity、Kiro、Zed、Pi Agent）。MCP Server 层 100% 跨平台复用，只有 Hook 层需要平台适配。完整支持的平台可拦截工具调用、修改参数、注入上下文；MCP-only 平台只能通过路由指令约束。

平台总览

Context Mode 架构

┌─────────────────────────────────┐
│         MCP Server              │  ← 100% 跨平台复用
│  (ctx_execute, ctx_search, ...) │
└──────────┬──────────────────────┘
           │
┌──────────┴──────────────────────┐
│         Hook Layer              │  ← 平台相关
│  ┌─────┐ ┌─────┐ ┌──────────┐ │
│  │JSON │ │ TS  │ │ MCP-only │ │
│  │stdio│ │Plugin│ │ (路由)   │ │
│  └─────┘ └─────┘ └──────────┘ │
└─────────────────────────────────┘

三种 Hook 范式

范式	平台	Hook 能力
JSON stdin/stdout	Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、Cursor、Codex CLI、Qwen Code	拦截+修改+注入+阻止
TS Plugin	OpenCode	拦截+修改+阻止（实验性压缩）
MCP-only	Antigravity、Kiro、Zed、Pi Agent	无 Hook，仅 MCP 工具

完整能力矩阵

能力	Claude Code	Gemini CLI	VS Code Copilot	JetBrains Copilot	Cursor	Codex CLI	Qwen Code	OpenCode	Antigravity	Kiro
PreToolUse	✓	✓	✓	✓	✓	✓*	✓	✓	—	—
PostToolUse	✓	✓	✓	✓	✓	✓	✓	✓	—	—
PreCompact	✓	✓**	✓	✓	—	—	✓	✓***	—	—
SessionStart	✓	✓	✓	✓	✓****	✓	✓	—	—	—
修改工具参数	✓	✓	✓	✓	✓	—	✓	✓	—	—
修改工具输出	✓	✓	✓	✓	—	—	✓	✓****	—	—
注入上下文	✓	✓	✓	✓	✓*****	✓	✓	—	—	—
阻止工具调用	✓	✓	✓	✓	✓	✓	✓	✓	—	—

* Codex CLI PreToolUse 仅支持 deny，不支持 additionalContext ** Gemini CLI PreCompress 是异步的，无法阻止压缩 *** OpenCode 的 PreCompact 标记为 experimental **** Cursor 的 sessionStart 存在已知 Bug ***** Cursor 的 additional_context 注入存在上游 Bug，模型实际读不到

各平台详解

Claude Code：主力平台

Claude Code 是 Context Mode 的开发基准，所有功能完整支持。

Hook 事件：PreToolUse、PostToolUse、PreCompact、SessionStart、UserPromptSubmit

安装：Plugin Marketplace 一条命令，Hook 全自动注册。

Hook 响应格式：

// 阻止工具
{ "permissionDecision": "deny", "reason": "Use ctx_execute instead" }

// 修改参数
{ "updatedInput": { "command": "ctx_execute ..." } }

// 注入上下文
{ "additionalContext": "Session state: editing auth.ts" }

Session ID 提取优先级：

1. transcript_path 中的 UUID
2. session_id 字段
3. CLAUDE_SESSION_ID 环境变量
4. 父进程 PID

Gemini CLI

Hook 事件：BeforeTool、AfterTool、PreCompress、SessionStart

与 Claude Code 的关键差异：

差异点	Claude Code	Gemini CLI
Hook 名称	PreToolUse	BeforeTool
阻止格式	permissionDecision: "deny"	decision: "deny"
参数修改	updatedInput	hookSpecificOutput.tool_input
压缩 Hook	PreCompact（同步）	PreCompress（异步，无法阻止）
子代理 Hook	不支持	不支持

WARNING

Gemini CLI 的 PreCompress 是异步触发的，无法阻止压缩发生。这意味着 Context Mode 只能在压缩前尽量备份数据，但不能阻止压缩本身。

Cursor

Hook 事件：preToolUse、postToolUse、stop、afterAgentResponse

注意：Cursor 使用小驼峰命名（preToolUse 非 PreToolUse）。

已知限制：

• sessionStart 被 Cursor validator 拒绝（不支持）
• postToolUse 的 additional_context 存在上游 Bug，注入的上下文模型读不到
• 路由强制主要靠 .mdc 规则文件和 MCP 工具描述

stop Hook 的特殊用法：Cursor 的 stop Hook 可以返回 followup_message 来自动触发下一轮对话——Context Mode 用它来弥补 sessionStart 的缺失。

VS Code Copilot / JetBrains Copilot

两者共享相同的 Hook 协议（和 Cursor 不同），格式基本一致：

差异：

• VS Code 使用 f1e_ 前缀命名 MCP 工具（非 mcp__server__tool）
• Session ID 字段是 sessionId（驼峰，非 session_id）
• 独有 SubagentStart / SubagentStop Hook
• 响应必须包装在 hookSpecificOutput 中

状态：Preview，API 可能变更。

Codex CLI

Hook 事件：PreToolUse、PostToolUse、SessionStart、UserPromptSubmit、Stop

独特之处：

• tool_name 始终是 "Bash"（Codex 只有一种工具类型）
• updatedInput 和 updatedMCPToolOutput 在 schema 中定义但未实现
• PreToolUse 只支持 deny（阻止），不支持 additionalContext（注入）
• 默认 Hook 超时：600 秒

Qwen Code

与 Claude Code 使用完全相同的 Hook 协议（源码验证自 hookRunner.ts 和 claude-converter.ts）。配置在 ~/.qwen/settings.json，Session 目录在 ~/.qwen/context-mode/sessions/。

OpenCode

TypeScript 插件范式，不使用 JSON stdin/stdout：

// Hook 注册
{
  "plugin": ["context-mode"]
}

// Hook 处理
export function toolExecuteBefore(input) {
  // throw Error 阻止
  // output.args 修改参数
}

限制：SessionStart 不工作（上游 Bug），输出修改有 TUI 渲染 Bug。

Antigravity / Kiro / Zed

MCP-only 模式，无 Hook 支持。Context Mode 启动时自动写入路由指令文件到项目根目录，依赖模型自觉遵循。

平台	路由文件	预期遵守率
Antigravity	GEMINI.md	~60%
Kiro	KIRO.md	~60%
Zed	—	~40%

Hook 响应格式速查

阻止工具调用

// Claude Code / VS Code Copilot / JetBrains Copilot / Qwen Code
{ "permissionDecision": "deny", "reason": "用 ctx_execute 替代" }

// Gemini CLI
{ "decision": "deny", "reason": "..." }

// Cursor
{ "permission": "deny", "user_message": "..." }

// Codex CLI
{ "hookSpecificOutput": { "permissionDecision": "deny" } }
// 或 exit code 2

// OpenCode
throw new Error("用 ctx_execute 替代")

修改工具参数

// Claude Code / Qwen Code
{ "updatedInput": { "command": "modified" } }

// Gemini CLI
{ "hookSpecificOutput": { "tool_input": { "command": "modified" } } }

// VS Code Copilot / JetBrains Copilot
{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "updatedInput": { "command": "modified" } } }

// Cursor / Codex CLI
不支持原生参数修改

注入上下文（PostToolUse）

// Claude Code / Qwen Code
{ "additionalContext": "..." }

// Gemini CLI
{ "hookSpecificOutput": { "additionalContext": "..." } }

// VS Code Copilot / JetBrains Copilot
{ "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "..." } }

// Cursor
{ "additional_context": "..." }  // 已知 Bug：模型读不到

// Codex CLI
{ "hookSpecificOutput": { "additionalContext": "..." } }

平台自动检测

Context Mode 通过 MCP 协议握手自动识别连接的平台：

// detect.ts 逻辑（简化）
const clientName = mcpRequest.clientInfo.name;
switch (true) {
  case clientName.includes("claude"):    return "claude-code";
  case clientName.includes("gemini"):    return "gemini-cli";
  case clientName.includes("copilot"):   return "vscode-copilot";
  case clientName.includes("cursor"):    return "cursor";
  case clientName.includes("codex"):     return "codex";
  case clientName.includes("qwen"):      return "qwen-code";
  case clientName.includes("antigravity"): return "antigravity";
  case clientName.includes("Kiro"):      return "kiro";
  // ...
}

也支持通过环境变量 CONTEXT_MODE_PLATFORM 手动覆盖。

FAQ

Q: 我用多个 AI 编程工具，可以同时安装 Context Mode 吗？

可以。每个平台的 Session 目录独立（路径不同），不会冲突。你甚至可以在同一个项目里用 Claude Code 和 Cursor 同时跑——它们各有独立的 Hook 和 Session。

Q: MCP-only 模式够用吗？

MCP-only 模式有 6 个沙盒工具（ctx_execute、ctx_search 等），可以节省上下文。但没有 Hook 层的自动拦截和路由强制，AI 可能仍然习惯性地使用原始 Read/Bash。建议 Hook 支持完整的平台上使用完整版。

Q: 我的平台不在支持列表里怎么办？

只要你的 AI 编程工具支持 MCP Server，就可以用 MCP-only 模式。在 MCP 配置中添加 context-mode 服务器即可。如果你想获得 Hook 支持，可以在 GitHub 上提 Issue 请求适配。