mksglu/context-mode — AI 编程智能体的上下文窗口优化器

精简 AI 编程工具输出，保留会话记忆。
本周新增 Star 4,224 ｜ 仓库 Star 总数 31,937 ｜ Forks 2,200

▲ 图 0：Context Mode 官方 Logo（官方图）

Context Mode 官方仓库未提供产品界面截图（仓库内仅有一张 logo）。可观看官方演示视频：https://www.youtube.com/watch?v=QUHrntlfPo4

一、它解决什么问题

AI 编程智能体的上下文窗口是稀缺资源。一次 curl、一次 Playwright 快照、一次 cat 一个大文件，就可能把几十万字符灌进上下文。Context Mode 的做法：

1. 沙箱化执行：所有工具输出先进入隔离沙箱，只有 stdout 进入上下文
2. 知识库索引：大输出被切块存入 SQLite FTS5 全文索引，需要时再检索
3. 钩子强制路由：PreToolUse 钩子 拦截 工具调用，把本该走沙箱的调用重定向过去 —— 甚至可以 直接阻断 危险命令
4. 会话连续性：压缩（compaction）前的快照与恢复，跨会话不丢记忆

实测节省数据（官方工具表）：

有钩子 vs 无钩子： 有钩子约 98% 节省，无钩子约 60% 节省。官方强调：只要支持钩子的平台就一定要开 —— 没有钩子时，一次没走路由的 curl 或 Playwright 快照就能倒进 56 KB，抹掉一整轮会话的节省量。

二、环境要求

SQLite 后端自动选择（无需配置）：

• Bun → bun:sqlite
• Node.js ≥ 22.5 → node:sqlite（Linux 上自动使用，避免 better-sqlite3 偶发 SIGSEGV 崩溃）
• 其他 → better-sqlite3

Linux + Node < 22.5 不支持 —— npm install 会失败并给出修复说明。

旧 glibc 系统（CentOS 7/8、RHEL 8、Debian 10）：

# CentOS 8 / RHEL 8（glibc 2.28）
dnf install -y gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ make python3 python3-setuptools
scl enable gcc-toolset-10 'npm install -g context-mode'

# CentOS 7 / RHEL 7（glibc 2.17）
yum install -y centos-release-scl
yum install -y devtoolset-10-gcc devtoolset-10-gcc-c++ make python3
pip3 install setuptools
scl enable devtoolset-10 'npm install -g context-mode'

# Alpine（musl 预编译版需 better-sqlite3 ≥ 12.8.0；若锁定旧版本）
apk add build-base python3 py3-setuptools
npm install -g context-mode

Windows 自愈机制：若安装后 better_sqlite3.node 缺失（如 prebuild-install 不在 cmd.exe PATH、无 MSVC 工具链），postinstall 脚本与运行时钩子会自动重新拉取预编译包并修复绑定，无需手动 npm rebuild。

三、部署方式

方式 A：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 会验证运行时、钩子、FTS5 与插件注册。

路由： 自动。SessionStart 钩子在运行时注入路由指令 —— 不会往你的项目里写文件。插件注册了全部钩子（PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop）与 11 个 MCP 工具。

可选：状态栏

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

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

保存后重启 Claude Code。状态栏显示 $ saved this session · $ saved across sessions · % efficient。接线是 path-free 的 —— context-mode statusline 会通过内置 CLI 解析，无论插件缓存在哪。

方式 B：Claude Code —— 仅 MCP（无钩子、无斜杠命令）

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

11 个 MCP 工具全都有，只是 没有自动路由 —— 模型仍能用，只是不再被提示优先用它们而非裸 Bash/Read/WebFetch。适合先试用。

方式 C：Gemini CLI —— 一个配置文件

前置： Node.js ≥ 22.5（或 Bun）、已装 Gemini CLI。

# 1. 全局安装
npm install -g context-mode

2. 在 ~/.gemini/settings.json 中加入以下内容（这一个文件同时注册 MCP 服务器与全部四个钩子）：

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

3. 重启 Gemini CLI

验证： /mcp list → 应看到 context-mode: ... - Connected

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

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）。这避免了对轻量工具的无谓钩子开销，同时拦截每一个可能淹没上下文的工具。

方式 D：VS Code Copilot

前置： Node.js ≥ 22.5（或 Bun）、VS Code + Copilot Chat v0.32+。

npm install -g context-mode

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

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

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

3. 重启 VS Code

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

方式 E：JetBrains Copilot

前置： Node.js ≥ 22.5（或 Bun）、JetBrains IDE + GitHub Copilot 插件 v1.5.57+。

npm install -g context-mode

2. 通过设置界面添加 MCP：Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add Server
- Name: context-mode
- Command: context-mode

3. 创建 .github/hooks/context-mode.json，内容与方式 D 相同，但命令改为 context-mode hook jetbrains-copilot。

4. 重启 JetBrains IDE

方式 F：GitHub Copilot CLI —— 插件（一行命令，推荐）

前置： Node.js ≥ 22.5（或 Bun）、已装 copilot。若使用隔离的 Copilot home，先设 COPILOT_HOME。

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

该 bundle 的 .mcp.json 固定了 CONTEXT_MODE_PLATFORM=copilot-cli，因此即使同时装了 Claude Code（其 ~/.claude/ 通常会胜出），context-mode 仍能正确自我识别为 Copilot。无需 context-mode upgrade 或智能体调用。

方式 F-2：手动安装（不用插件）

npm install -g context-mode
copilot mcp add context-mode -- context-mode

然后在 ~/.copilot/hooks/context-mode.json（或 $COPILOT_HOME/hooks/context-mode.json）配置六个钩子事件：

{
  "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 帮你写这个文件：context-mode upgrade（在 Copilot CLI 上下文中运行，或带 CONTEXT_MODE_PLATFORM=copilot-cli）。注意 upgrade 只写 hooks 文件 —— MCP 服务器仍需 copilot mcp add 手动注册。

版本提示： 钩子命令运行的是 全局 的 context-mode。旧版本的全局安装上钩子是 惰性的（不路由、不捕获），但 不会阻塞你的工具（context-mode 失败时放行）。用 npm install -g context-mode@latest 升级。

方式 G：Codex CLI —— 插件 + 特性开关

前置： Node.js ≥ 22.5（或 Bun）、已装 Codex CLI。

codex plugin marketplace add mksglu/context-mode

2. 启用插件钩子（Codex 特性仍受门控）：

[features]
plugin_hooks = true
hooks = true

特性开关说明： 当前 Codex 构建把钩子暴露在 [features].hooks（或 codex --enable hooks）。优先用 [features].hooks；[features].codex_hooks 在当前构建中仍作为遗留别名被接受。打包的插件钩子在 Codex 默认启用插件钩子之前，额外需要 plugin_hooks。

3. 重启 Codex CLI，用 ctx stats 验证 MCP

ctx stats 只能证明插件 MCP 服务器已安装且可达，不能证明钩子已被信任并在运行。

4. 若 Codex 提示钩子审批，请 审查并信任 context-mode 的钩子

自定义存储位置： 若 Codex 无法写入适配器默认存储目录，在启动 Codex 的环境中设 CONTEXT_MODE_DIR 为绝对可写根目录：

CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex

会话与统计在 /sessions；已索引内容在 /content。

手动回退方案（不支持 plugin_hooks 的 Codex 构建）：

npm install -g context-mode

在 ~/.codex/config.toml 中加入：

[features]
hooks = true

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

[mcp_servers.context-mode.env]
CONTEXT_MODE_PLATFORM = "codex"

再创建 $CODEX_HOME/hooks.json：

{
  "hooks": {
   "PreToolUse": [{ "matcher": "local_shell|shell|shell_command|exec_command|Bash|Shell|apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__", "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" }] }],
     "PreCompact": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex precompact" }] }],
     "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex userpromptsubmit" }] }],
     "Stop": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex stop" }] }]
  }
}

并复制路由指令：

CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ./AGENTS.md
# 全局：
CM_ROOT="$(npm root -g)/context-mode"; cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.codex/AGENTS.md

Codex 限制： PreToolUse 目前 仅支持 deny 规则（阻止危险命令）；输入改写需上游 updatedInput 支持（openai/codex#18491）。additionalContext 上下文注入在 Codex PreToolUse 不支持，改由 PostToolUse 与 SessionStart 实现 —— 官方已自动处理。

方式 H：Cursor —— 本地文件夹路径

🚧 Marketplace 插件仍在等待 Cursor 团队审核（追踪 #485 / #489）。在 Cursor 上架前，用本地文件夹方式。

Windows（PowerShell） —— Cursor 不跟随 Windows 符号链接/目录联接，用 robocopy：

git clone https://github.com/mksglu/context-mode.git
cd context-mode
robocopy . "$env:USERPROFILE\.cursor\plugins\local\context-mode" /MIR `
  /XD node_modules .git build web tests scripts .vscode `
  /XF *.log .gitignore *.bundle.mjs.map

macOS / Linux：

git clone https://github.com/mksglu/context-mode.git
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

重启 Cursor。插件出现在 Settings → Plugins，名为 "Context Mode (Local)"。更新时重跑同一条 robocopy / ln -s 即可。

方式 I：其他平台速查

四、使用方法

4.1 全部 11 个 MCP 工具

4.2 沙箱机制

每次 ctx_execute 调用都会派生一个 独立子进程，有自己的进程边界。脚本之间无法访问彼此的内存或状态。子进程运行你的代码、捕获 stdout，只有 stdout 进入对话上下文。原始数据（日志文件、API 响应、快照）永远不离开沙箱。

12 种语言运行时： JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C#。Bun 会自动探测，JS/TS 执行快 3-5 倍。

凭据透传： gh、aws、gcloud、kubectl、docker 等已认证 CLI 通过凭据透传工作 —— 它们继承环境变量与配置路径，但不会把凭据暴露到对话里。

意图驱动过滤： 当输出超过 5 KB 且提供了 intent 参数时，Context Mode 切换到意图驱动过滤 —— 把完整输出索引进知识库，搜索与意图匹配的片段，只返回相关匹配并附带可搜索词汇表供后续查询。

4.3 知识库机制

ctx_index 按标题切块 markdown（保持代码块完整），存入 SQLite FTS5 虚拟表。

• BM25 排序 —— 基于词频、逆文档频率与文档长度归一化的概率相关性算法
• Porter 词干化 —— 索引时应用，"running"、"runs"、"ran" 匹配同一词干
• 标题与标题权重 ×5 —— 让导航型查询更精准

ctx_search 返回围绕匹配词提取的 真实索引内容 —— 不是完整文档，不是近似值。

Reciprocal Rank Fusion（RRF）双路排序：

1. Porter 词干化 —— FTS5 MATCH 配合 porter 分词器，"caching" 匹配 "cached"/"caches"/"cach"
2. Trigram 子串 —— FTS5 trigram 分词器匹配部分字符串，"useEff" 找到 "useEffect"，"authenticat" 找到 "authentication"

RRF 把两份排序列表 合并成一个结果集 —— 在两种策略中都排名靠前的文档会排得更高。这取代了旧的级联回退方案（trigram 结果只在 porter 无结果时才用）。

4.4 会话连续性

• PreCompact 钩子在压缩 之前 构建恢复快照
• SessionStart 钩子在压缩 之后 恢复状态
• 会话数据与统计持久化在本地 SQLite

4.5 实用命令

在任何 AI 会话内 —— 直接输入，LLM 会自动调用 MCP 工具：

ctx stats       # 上下文节省、调用次数、会话报告
ctx doctor      # 诊断运行时、钩子、FTS5、版本
ctx index       # 索引本地文件或目录，供后续搜索
ctx search      # 搜索已索引内容
ctx upgrade     # 从 GitHub 更新、重建、重配钩子
ctx purge       # 永久删除知识库中所有已索引内容
ctx insight     # 打开托管的 Insight 面板

在终端直接运行：

context-mode doctor
context-mode index . --source project:my-app
context-mode search "authentication middleware" --source project:my-app
context-mode upgrade
context-mode insight          # 在浏览器打开托管的 Insight 面板
bash scripts/ctx-debug.sh    # 生成完整诊断报告，便于提 issue

调试脚本会收集 OS 信息、运行时版本、better-sqlite3 状态、适配器检测、配置文件（脱敏）、钩子校验、FTS5/SQLite 测试、执行器测试、进程检查、会话数据库与环境变量，汇总成一份可粘贴的 markdown 报告。

4.6 存储与网络环境变量

五、安全与隐私

项目边界隔离

Context Mode 把每个项目的知识库 隔离，项目 A 的内容不会泄漏到项目 B。

网络抓取加固

ctx_fetch_and_index 的抓取有加固：限制重定向、校验内容类型、防止 SSRF 式的内网访问。

隐私与架构

分析在本地完成；只有你需要用 ctx_insight 打开托管面板时才会有对外交互。

参考链接

• 仓库：https://github.com/mksglu/context-mode
• 官网：https://context-mode.com
• 平台支持文档：https://github.com/mksglu/context-mode/blob/main/docs/platform-support.md
• Gemini CLI 适配器：https://github.com/mksglu/context-mode/blob/main/docs/adapters/gemini-cli.md
• npm：https://www.npmjs.com/package/context-mode