context-mode

Context Mode

上下文问题的另一半。

被以下团队内部使用

问题

每次 MCP 工具调用都会将原始数据倾倒在您的上下文窗口中。一个 Playwright 快照需要 56 KB。二十个 GitHub issue 需要 59 KB。一条访问日志——45 KB。30 分钟后，40% 的上下文就丢失了。当 agent 压缩对话以腾出空间时，它会忘记正在编辑哪些文件、进行中的任务以及您最后的要求。此外，agent 还浪费输出 token 在填充、礼貌用语和冗长的解释上——从两端消耗上下文。

Context Mode 如何解决

Context Mode 是一个 MCP server，解决了这个问题的所有四个方面：

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

2. 会话连续性 —— 每一次文件编辑、git 操作、任务、错误和用户决策都记录在 SQLite 中。当对话压缩时，context-mode 不会将这些数据重新放回上下文——而是将事件索引到 FTS5 中，仅通过 BM25 搜索检索相关内容。模型从您离开的地方精确继续。如果您不使用 --continue，之前的会话数据会立即删除——新会话意味着新开始。

3. 用代码思考 —— LLM 应该编程分析，而不是计算分析。agent 不再将 50 个文件读入上下文来计算函数数量，而是编写一个脚本进行计数，并只 console.log() 结果。一个脚本替代十次工具调用，节省 100 倍上下文。这是所有 14 个平台必须遵循的范式：停止将 LLM 视为数据处理者，将其视为代码生成器。

   // 之前: 47 × Read() = 700 KB。 之后: 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'));
   `);
   

4. 输出压缩 —— 像穴居人一样简洁。只保留技术实质。只有废话消失。去掉冠词、填充词（just/really/basically）、客气话、模糊措辞。片段可用。短同义词。代码不变。模式：[事物] [动作] [原因]。[下一步]。安全警告、不可逆操作和用户困惑时自动扩展。输出 token 减少约 65-75%，同时保持完整技术准确性。

安装

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

Claude Code — 插件市场，全自动

前置条件： 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 会验证运行时、hooks、FTS5 和插件注册。

路由： 自动。SessionStart hook 在运行时注入路由指令——不会向您的项目写入任何文件。插件注册了所有 hooks（PreToolUse, PostToolUse, PreCompact, SessionStart）和 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）。

斜杠命令	功能
/context-mode:ctx-stats	上下文节省——按工具细分、消耗的 token、节省比例。
/context-mode:ctx-doctor	诊断——运行时、hooks、FTS5、插件注册、版本。
/context-mode:ctx-upgrade	拉取最新版本、重新构建、迁移缓存、修复 hooks。
/context-mode:ctx-purge	永久删除知识库中所有索引内容。
/context-mode:ctx-insight	个人分析仪表板——90 个指标、37 个洞察模式、4 个综合分数（生产力、质量、委派、上下文健康度），覆盖 23 个事件类别。打开一个本地 Web UI。

注意： 斜杠命令是 Claude Code 插件特性。在其他平台上，在聊天中输入 ctx stats、ctx doctor、ctx upgrade 或 ctx insight——模型会自动调用 MCP 工具。请参见实用命令。

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

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

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

替代方案——仅 MCP 安装（无 hooks 或斜杠命令）

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

这将提供所有 11 个 MCP 工具，但没有自动路由。模型仍然可以使用它们——只是不会被提示优先使用它们而非原始的 Bash/Read/WebFetch。适合在提交到完整插件前先试用。

Gemini CLI — 一个配置文件，包含 hooks

前置条件： Node.js 18+，已安装 Gemini CLI。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 将以下内容添加到 ~/.gemini/settings.json。这一文件注册了 MCP server 和所有四个 hooks：

   {
     "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" }]
         }
       ]
     }
   }
   

3. 重启 Gemini CLI。

验证：

/mcp list

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

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

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

为什么使用 BeforeTool matcher？ 它只针对产生大量输出的工具（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

VS Code Copilot — 包含 SessionStart 的 hooks

前置条件： Node.js 18+，VS Code 附带 Copilot Chat v0.32+。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

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

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

3. 创建 .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" }
       ]
     }
   }
   

4. 重启 VS Code。

验证： 打开 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

JetBrains Copilot — 包含 SessionStart 的 hooks

前置条件： Node.js 18+，JetBrains IDE 附带 GitHub Copilot 插件 v1.5.57+。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 通过设置 UI 添加 MCP server：Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add Server：

   • Name： context-mode
   • Command： context-mode

3. 创建 .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" }
       ]
     }
   }
   

4. 重启 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

Cursor — 包含 stop 支持的 hooks

前置条件： Node.js 18+，启用了 agent 模式的 Cursor。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 在项目根目录创建 .cursor/mcp.json（或 ~/.cursor/mcp.json 用于全局）：

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

3. 创建 .cursor/hooks.json（或 ~/.cursor/hooks.json 用于全局）：

   {
     "version": 1,
     "hooks": {
       "preToolUse": [
         {
           "command": "context-mode hook cursor pretooluse",
           "matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"
         }
       ],
       "postToolUse": [
         {
           "command": "context-mode hook cursor posttooluse"
         }
       ],
       "stop": [
         {
           "command": "context-mode hook cursor stop"
         }
       ]
     }
   }
   

   preToolUse matcher 是可选的——没有它，hook 会在所有工具上触发。stop hook 在 agent 轮次结束时触发，可以发送后续消息以继续循环。afterAgentResponse 也可用（fire-and-forget，接收完整响应文本）。

4. 复制路由规则文件。Cursor 缺少 SessionStart hook，因此模型需要规则文件来实现路由感知：

   mkdir -p .cursor/rules
   cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc
   

5. 重启 Cursor 或打开一个新的 agent 会话。

验证： 打开 Cursor Settings > MCP 并确认 "context-mode" 显示为已连接。在 agent 聊天中输入 ctx stats。

路由： Hooks 通过 preToolUse/postToolUse/stop 以编程方式强制路由。.cursor/rules/context-mode.mdc 文件在会话启动时提供路由指令，因为 Cursor 的 sessionStart hook 目前被其验证器拒绝（论坛报告）。项目 .cursor/hooks.json 会覆盖 ~/.cursor/hooks.json。

已知限制： Cursor 接受 hook 响应中的 additional_context，但不会将其暴露给模型（论坛 #155689）。路由依赖 .mdc 规则文件而非 hook 上下文注入。

完整配置：configs/cursor/hooks.json | configs/cursor/mcp.json | configs/cursor/context-mode.mdc

OpenCode — 带 hooks 的 TypeScript 插件

前置条件： Node.js 18+，已安装 OpenCode。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到项目根目录的 opencode.json（或 ~/.config/opencode/opencode.json 用于全局）：

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "context-mode": {
         "type": "local",
         "command": ["context-mode"]
       }
     },
     "plugin": ["context-mode"]
   }
   

   mcp 条目注册所有 11 个 MCP 工具。plugin 条目启用 hooks——OpenCode 在每次工具执行前后直接调用插件的 TypeScript 函数，阻止危险命令并强制沙盒路由。

3. *（可选）*复制路由规则文件。模型需要 AGENTS.md 文件来实现路由感知：

   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
   

   这告诉模型应该使用哪些工具以及哪些命令被阻止。如果没有它，hooks 仍然会强制路由——但模型不会知道命令被拒绝的原因。

4. 重启 OpenCode。

验证： 在 OpenCode 会话中，输入 ctx stats。context-mode 工具应出现并响应。

路由： Hooks 通过 tool.execute.before 和 tool.execute.after 以编程方式强制路由。可选的 AGENTS.md 文件为模型感知提供路由指令。experimental.session.compacting hook 在对话压缩时构建恢复快照。experimental.chat.system.transform hook 在会话启动时注入路由块和先前会话快照，实现跨重启的会话连续性。chat.message hook 捕获用户提示和决策（相当于 UserPromptSubmit）。

注意： OpenCode 缺少真正的 SessionStart hook（#14808, #5409）。插件使用 experimental.chat.system.transform 作为替代——它将路由块和恢复快照注入系统提示。用户提示捕获使用 chat.message 代替缺失的 UserPromptSubmit hook。AGENTS.md/CLAUDE.md/CONTEXT.md 规则在每次项目的第一个 hook 触发时自动捕获。

完整配置：configs/opencode/opencode.json | configs/opencode/AGENTS.md

KiloCode — 带 hooks 的 TypeScript 插件

前置条件： Node.js 18+，已安装 KiloCode。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到项目根目录的 kilo.json（或 ~/.config/kilo/kilo.json 用于全局）：

   {
     "$schema": "https://app.kilo.ai/config.json",
     "mcp": {
       "context-mode": {
         "type": "local",
         "command": ["context-mode"]
       }
     },
     "plugin": ["context-mode"]
   }
   

   mcp 条目注册所有 11 个 MCP 工具。plugin 条目启用 hooks——KiloCode 在每次工具执行前后直接调用插件的 TypeScript 函数，阻止危险命令并强制沙盒路由。

3. *（可选）*复制路由规则文件。KiloCode 与 OpenCode 共享插件架构，因此模型需要 AGENTS.md 文件来实现路由感知：

   cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
   

4. 重启 KiloCode。

验证： 在 KiloCode 会话中，输入 ctx stats。context-mode 工具应出现并响应。

路由： Hooks 通过 tool.execute.before 和 tool.execute.after 以编程方式强制路由。可选的 AGENTS.md 文件为模型感知提供路由指令。experimental.session.compacting hook 在对话压缩时构建恢复快照。experimental.chat.system.transform hook 在会话启动时注入路由块和先前会话快照，实现跨重启的会话连续性。chat.message hook 捕获用户提示和决策（相当于 UserPromptSubmit）。

注意： KiloCode 与 OpenCode 共享相同的插件架构，使用 OpenCodeAdapter 并指定平台特定的配置路径（kilo.json 代替 opencode.json，~/.config/kilo/ 代替 ~/.config/opencode/）。与 OpenCode 一样，它缺少真正的 SessionStart hook——插件使用 experimental.chat.system.transform 作为替代。用户提示捕获使用 chat.message 代替缺失的 UserPromptSubmit hook。AGENTS.md/CLAUDE.md/CONTEXT.md 规则在每次项目的第一个 hook 触发时自动捕获。

OpenClaw / Pi Agent — 原生网关插件

前置条件： OpenClaw gateway 正在运行（>2026.1.29），Node.js 22+。

context-mode 作为原生 OpenClaw 网关插件运行，针对 Pi Agent 会话（Read/Write/Edit/Bash 工具）。与其他平台不同，没有单独的 MCP server——插件通过 OpenClaw 的 plugin API 直接注册到网关运行时。

安装：

1. 克隆并安装：

   git clone https://github.com/mksglu/context-mode.git
   cd context-mode
   npm run install:openclaw
   

   安装程序使用您环境中的 $OPENCLAW_STATE_DIR（默认：/openclaw）。要指定自定义路径：

   npm run install:openclaw -- /path/to/openclaw-state
   

   常见位置：Docker —— /openclaw（默认）。本地 —— ~/.openclaw 或您设置 OPENCLAW_STATE_DIR 的任何位置。

   安装程序处理所有事情：npm install、npm run build、better-sqlite3 原生重建、在 runtime.json 中注册扩展，以及通过 SIGUSR1 重启网关。

2. 打开一个 Pi Agent 会话。

验证： 插件通过 api.on()（生命周期）和 api.registerHook()（命令）注册 8 个 hooks。输入 ctx stats 确认工具已加载。

路由： 自动。所有工具拦截、会话跟踪和压缩恢复 hooks 自动激活——无需手动 hook 配置或路由文件。

最低版本： OpenClaw >2026.1.29——这包含了来自 PR #9761 的 api.on() 生命周期修复。在旧版本上，生命周期 hooks 静默失败。适配器回退到数据库快照重建（不太精确但保留了关键状态）。

完整文档：docs/adapters/openclaw.md

Codex CLI — MCP + hooks

前置条件： Node.js 18+，已安装 Codex CLI。

安装：

1. 全局安装 context-mode：

   npm install -g context-mode
   

2. 添加到 ~/.codex/config.toml：

   [mcp_servers.context-mode]
   command = "context-mode"
   

3. 添加 hooks 以实现路由强制和会话跟踪。创建 ~/.codex/hooks.json：

   {
     "hooks": {
       "PreToolUse": [{ "matcher": "local_shell|shell|shell_command|exec_command|container.exec|Bash|Shell|grep_files|mcp__plugin_context-mode_context-mode__ctx_execute|mcp__plugin_context-mode_context-mode__ctx_execute_file|mcp__plugin_context-mode_context-mode__ctx_batch_execute", "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
       "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
       "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }],
       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex userpromptsubmit" }] }],
       "Stop": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex stop" }] }]
     }
   }
   

   PreToolUse 目前强制执行 deny/block 路由，并准备在 Codex 支持输入重写时使用。PostToolUse 捕获会话事件。SessionStart 在压缩后恢复状态。UserPromptSubmit 捕获用户决策和修正。Stop 记录轮次结束状态。

   注意： Codex PreToolUse 路由目前仅支持 deny 规则（阻止危险命令）。在 context-mode 可以重写工具输入之前，仍需要上游的 updatedInput 支持；请跟踪 openai/codex#18491。Codex PreToolUse 不支持上下文注入（additionalContext）——它通过 PostToolUse 和 SessionStart 代替。这已自动处理。

4. 复制路由指令（即使有 hooks，也建议这样做以获得完整的路由感知）：

   cp node_modules/context-mode/configs/codex/AGENTS.md ./AGENTS.md
   

   全局使用：cp node_modules/context-mode/configs/codex/AGENTS.md ~/.codex/AGENTS.md。全局适用于所有项目。如果两者都存在，Codex CLI 会合并它们。

5. 重启 Codex CLI。

验证： 启动一个会话并输入 ctx stats。context-mode 工具应出现并响应。

路由： MCP 工具可工作。配置了 ~/.codex/hooks.json 后，基于 hook 的路由处于活动状态。AGENTS.md 文件为模型感知提供路由指令。

Qwen Code — MCP + hooks（与 Claude Code 使用相同的连接协议）

前置条件： Node.js 18+，已安装 Qwen Code（npm install -g @qwen-code/qwen-code）。

1. 安装 context-mode：

   npm install -g context-mode
   

2. 将 context-mode 添加为 MCP server。添加到 ~/.qwen/settings.json：

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode",
         "args": []
       }
     }
   }
   

3. 添加 hooks 以实现路由强制和会话跟踪。添加到 ~/.qwen/settings.json：

   {
     "hooks": {
       "PreToolUse": [{ "matcher": "run_shell_command|read_file|
   

[原 README 过长已截断]