Context Mode：解决 AI 编码 Agent 上下文窗口损耗问题

上下文问题的另一半。

每一次 MCP 工具调用都将原始数据倾倒到上下文窗口中。一次 Playwright 快照消耗 56 KB。二十条 GitHub Issue 消耗 59 KB。一条访问日志——45 KB。30 分钟后，40% 的上下文已经消失。而当 AI 智能体压缩对话以释放空间时，它会忘记正在编辑哪些文件、哪些任务正在进行中，以及你最后要求的是什么。此外，AI 智能体还在填充词、客套话和冗长的解释上浪费输出 token——从两侧同时燃烧上下文。

Context Mode 如何解决这一问题

Context Mode 是一个 MCP Server，解决了这个问题的全部四个方面：

上下文节省——沙盒工具将原始数据挡在上下文窗口之外。315 KB 变成 5.4 KB。减少 98%。

上下文节省——沙盒工具将原始数据挡在上下文窗口之外。315 KB 变成 5.4 KB。减少 98%。

Session Continuity — 每个文件编辑、git 操作、任务、错误和用户决策都被追踪存储在 SQLite 中。当对话压缩时，context-mode 不会将这些数据倾倒回上下文——而是通过 FTS5 将事件索引，并仅通过 BM25 搜索检索相关内容。模型从上次中断的地方无缝继续。如果不使用 --continue，之前的会话数据会立即删除——全新的会话意味着全新的开始。

Think in Code — LLM 应该编写分析代码，而不是自己计算。与其将 50 个文件读入上下文来统计函数数量，不如让智能体写一个脚本来完成计数，只用 console.log() 输出结果。一个脚本替代十次工具调用，节省 100 倍的上下文量。这是全部 17 个支持客户端以及 OpenClaw 网关集成的强制范式：不要再把 LLM 当作数据处理器，而是把它当作代码生成器。

// Before: 47 × Read() = 700 KB.  After: 1 × ctx_execute() = 3.6 KB.
ctx_execute("javascript", `
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\\n').length + ' lines'));
`);

No prose-style enforcement — context-mode 将原始数据排除在上下文之外，但从不规定模型如何撰写最终答案。简洁、完整、格式——由你的模型决定（或者通过你自己的 CLAUDE.md / AGENTS.md 由你决定）。过度强调简洁的提示已被证明会降低编码/推理基准测试的表现（Moonshot AI on kimi-k2.5）——路由模块专注于数据流向，而非模型如何表达。

平台按安装复杂度分组。支持 Hook 的平台获得自动路由强制执行。非 Hook 平台需要一次性复制路由文件。

前置条件：Claude Code v1.0.33+（运行 claude --version 检查版本）。如果 /plugin 命令无法识别，先更新：brew upgrade claude-code 或 npm update -g @anthropic-ai/claude-code。

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

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

/context-mode:ctx-doctor

所有检查项均应显示 [x]。doctor 会验证运行时环境、Hook、FTS5 和插件注册状态。

路由：自动执行。SessionStart Hook 在运行时注入路由指令——不会向你的项目写入任何文件。插件注册了所有 Hook（PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop）和 11 个 MCP 工具——六个沙箱工具（ctx_batch_execute、ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index）加上五个元工具（ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight）。

注意：斜杠命令是 Claude Code 的插件功能。在其他平台上，在聊天中输入 ctx stats、ctx doctor、ctx index、ctx search、ctx upgrade 或 ctx insight——模型会自动调用对应的 MCP 工具。详见 Utility Commands。

状态栏（可选）：Claude Code 的插件清单无法声明状态栏，因此需要一次性手动编辑 ~/.claude/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

保存后重启 Claude Code。状态栏显示本次会话节省 $ · 跨会话共节省 $ · 效率 %，让你实时看到节省量的积累。连接方式与路径无关——context-mode statusline 通过捆绑的 CLI 解析，无论插件缓存位于何处。

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

这让你获得全部 11 个 MCP 工具，但没有自动路由。模型仍然可以使用它们——只是不会被引导优先于原始 Bash/Read/WebFetch。适合在完全投入前先体验试用。

前置条件：Node.js >= 22.5（或 Bun），已安装 Gemini CLI。

全局安装 context-mode：

npm install -g context-mode

在 ~/.gemini/settings.json 中添加以下配置。这一单一文件注册了 MCP 服务器和全部四个 Hook：

{
  "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|mcp__context-mode|mcp__(?!.*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" }]
      }
    ]
  }
}

/mcp list

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

路由：通过 SessionStart Hook 自动执行。可选复制路由指令以获得完整的模型感知：

cp node_modules/context-mode/configs/gemini-cli/GEMINI.md ./GEMINI.md

为什么使用 BeforeTool 匹配器？它只针对会产生大量输出的工具（run_shell_command、read_file、read_many_files、grep_search、search_file_content、web_fetch、activate_skill）以及 context-mode 自身的工具（mcp__plugin_context-mode）。这避免了对轻量级工具的不必要 Hook 开销，同时拦截了每个可能撑爆上下文窗口的工具。

完整配置参考：configs/gemini-cli/settings.json

前置条件：Node.js >= 22.5（或 Bun），VS Code 配合 Copilot Chat v0.32+。

全局安装 context-mode：

npm install -g context-mode

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

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

创建 .github/hooks/context-mode.json：

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

验证：打开 Copilot Chat 并输入 ctx stats。context-mode 工具应该出现并响应。

路由：通过 SessionStart hook 自动路由。也可以复制路由指令以实现完整的模型感知：

cp node_modules/context-mode/configs/vscode-copilot/copilot-instructions.md .github/copilot-instructions.md

包含 PreCompact 的完整 hook 配置：configs/vscode-copilot/hooks.json

前置条件：Node.js >= 22.5（或 Bun），JetBrains IDE 已安装 GitHub Copilot 插件 v1.5.57+。

全局安装 context-mode：

npm install -g context-mode

通过设置界面添加 MCP 服务器：Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add Server：

Name: context-mode

Command: context-mode

创建 .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" }
    ],
    "SessionStart": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot sessionstart" }
    ]
  }
}

重启 JetBrains IDE。

验证：打开 Copilot Chat 并输入 ctx stats。context-mode 工具应该出现并响应。

路由：通过 SessionStart hook 自动路由。也可以复制路由指令以实现完整的模型感知：

cp node_modules/context-mode/configs/jetbrains-copilot/copilot-instructions.md .github/copilot-instructions.md

包含 PreCompact 的完整 hook 配置：configs/jetbrains-copilot/hooks.json

完整设置指南：docs/jetbrains-copilot.md

前置条件：Node.js >= 22.5（或 Bun），已安装 GitHub Copilot CLI（copilot）。如果使用独立的 Copilot home，先设置 COPILOT_HOME。

安装——方式 A（插件，一条命令——推荐）：

npm install -g context-mode                                     # 插件的 MCP server 运行全局二进制文件
copilot plugin install mksglu/context-mode:configs/copilot-cli  # 注册 MCP + hooks + 路由 skill

打包包的 .mcp.json 固定了 CONTEXT_MODE_PLATFORM=copilot-cli，因此 context-mode 自我识别为 Copilot——ctx_upgrade 和平台检测会解析 copilot-cli，即使同时安装了 Claude Code（其 ~/.claude/ 会优先生效）。无需 context-mode 升级/agent 调用。要在合入默认分支之前从本地克隆试用，让 Copilot 指向打包目录：copilot --plugin-dir /path/to/context-mode/configs/copilot-cli。

安装——方式 B（手动，无插件）：

全局安装 context-mode：

npm install -g context-mode

通过 Copilot CLI 内置命令注册 MCP 服务器（自动写入 ~/.copilot/mcp-config.json）：

copilot mcp add context-mode -- context-mode

在 ~/.copilot/hooks/context-mode.json（或 $COPILOT_HOME/hooks/context-mode.json）中配置 hooks。配置使用扁平的 { "type": "command", "command": "..." } 条目；context-mode 也会写入顶级 "version": 1，但该字段是可选的——Copilot CLI 接受省略它的 hook 配置（它只在自文档中固定）。Copilot CLI 触发 context-mode 使用的六个事件：

{
  "version": 1,
  "hooks": {
    "preToolUse":          [{ "type": "command", "command": "context-mode hook copilot-cli pretooluse" }],
    "postToolUse":         [{ "type": "command", "command": "context-mode hook copilot-cli posttooluse" }],
    "preCompact":          [{ "type": "command", "command": "context-mode hook copilot-cli precompact" }],
    "sessionStart":        [{ "type": "command", "command": "context-mode hook copilot-cli sessionstart" }],
    "userPromptSubmitted": [{ "type": "command", "command": "context-mode hook copilot-cli userpromptsubmit" }],
    "agentStop":           [{ "type": "command", "command": "context-mode hook copilot-cli stop" }]
  }
}

或者让 context-mode 为你写入 hooks 文件：context-mode upgrade（在 Copilot CLI 上下文中运行，或设置 CONTEXT_MODE_PLATFORM=copilot-cli）。upgrade 只写入 hooks 文件——在步骤 2 中用 copilot mcp add 注册 MCP 服务器。