为 AI 编程助手节省上下文的 MCP 插件 · 中文技术部署文档

项目仓库：https://github.com/mksglu/context-mode

当前版本 1.0.169 · 协议 Elastic License 2.0 · 运行环境 Node.js ≥ 22.5（或 Bun）

1 项目简介

Context Mode 是一个运行在 MCP（Model Context Protocol）协议层的插件 / 服务器，定位为“上下文问题的另一半解法”。它把工具产生的原始数据隔离在本地沙箱中，只把处理结果送入模型上下文；同时通过本地全文检索与会话记忆，解决对话被压缩后模型遗忘工作进度的问题。

与传统“在云端仪表盘里分析输出”的方案不同，Context Mode 完全在本机运行：代码、提示词与会话数据都不离开你的机器，无遥测、无云同步、无需账号。

1.1 核心信息一览

说明：GitHub Star、Fork 等实时统计以仓库页面徽章为准；本文不填写未经接口核实的精确 Star 数量。

1.2 适用场景

• 使用 Claude Code、Codex、Cursor、Gemini CLI 等 AI 编程助手，但上下文窗口很快被日志、网页快照、Issue 列表、接口返回等原始数据占满。
• 希望在对话被压缩（compaction）后，模型仍能记得正在修改的文件、进行中的任务、已做决策与未解决的报错。
• 希望把大段文档、网页、代码库索引到本地知识库，按需检索相关片段，而不是每次把全文重新送入上下文。
• 对隐私敏感：要求代码与会话数据留在本机，不经过第三方云端分析服务。

2 它要解决的问题

每一次 MCP 工具调用都会把原始数据直接倾倒进上下文窗口。根据官方 README 的实测口径：

• 一次 Playwright 网页快照约 56 KB；
• 20 个 GitHub Issue 合计约 59 KB；
• 一份访问日志约 45 KB。 持续工作约 30 分钟后，上下文已有约 40% 被这类原始数据占用。当助手为腾出空间而压缩对话时，模型会忘记正在修改哪些文件、哪些任务还在进行、你最后提出的要求是什么。此外，模型还会在最终回答上消耗输出 token 用于客套话、铺垫和冗长解释，从上下文两侧同时“烧”掉额度。

Context Mode 针对问题的四个方面同时给出解法：

3 核心工作原理

3.1 沙箱隔离：原始数据不进上下文（Context Saving）

每一次 ctx_execute 调用都会启动一个独立的子进程，拥有独立的进程边界：脚本之间无法互相访问内存或状态。子进程运行代码、捕获标准输出，只有标准输出进入对话上下文；日志文件、接口响应、网页快照等原始数据始终不离开沙箱。

当输出超过 5 KB 且提供了 intent（意图）参数时，Context Mode 切换为意图驱动过滤：把完整输出索引进知识库，只检索并返回与意图匹配的片段，同时给出可用于后续查询的检索词。

沙箱内可运行 12 种语言运行时：JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C#；检测到 Bun 时会自动使用 Bun，JS/TS 执行速度提升 3 至 5 倍。已认证的命令行工具（gh、aws、gcloud、kubectl、docker 等）通过凭证透传工作：继承环境变量与配置路径，但不会把凭证暴露给对话。

3.2 会话记忆：压缩后精准恢复（Session Continuity）

会话期间每一个有意义的事件都会被捕获，并持久化到按项目隔离的 SQLite 数据库。对话被压缩、或使用 --continue、--resume、/resume 恢复时，工作状态会自动重建，模型从你的最后一条提示词继续，无需重复交代背景。

被记录的事件类别包括：文件读写与修改、任务创建与完成、计划进入 / 退出 / 批准 / 驳回、规则文件路径与内容、用户提示词、用户纠正与偏好、Git 操作、工具报错、报错与修复配对、已发现的限制、阻塞项、被拒绝的方案、环境变化、子代理结论、重复调用循环、延迟、MCP 工具调用次数、技能调用、外部链接引用、角色设定、会话意图与大段粘贴数据等。

压缩前，PreCompact 钩子读取全部会话事件，构建一个优先级分层、不超过 2 KB 的 XML 快照并写入 session_resume 表；压缩后 SessionStart 钩子取回快照，生成包含 15 类条目的 Session Guide（最后请求、任务、计划、关键决策、已修改文件、未解决报错、限制、阻塞项、Git、项目规则、已用 MCP 工具、子代理任务、已用技能、被拒绝方案、外部引用、环境、数据引用、会话意图、用户角色等），注入 <session_knowledge> 指令后让模型接着工作。详细事件数据同时索引进 FTS5，可通过 ctx_search 按需检索。

若会话未带 --continue，上一次会话数据会被立即删除——新会话从干净状态开始。

3.3 用代码计算：让模型写脚本而不是读文件（Think in Code）

官方主张：LLM 应当负责编写分析程序，而不是亲自完成计算。与其把 50 个文件读进上下文再逐个统计函数数量，不如由助手写一段脚本完成统计，只把 console.log 的结果回传。一个脚本替代十次工具调用，约节省 100 倍上下文。这一范式在全部受支持客户端与 OpenClaw 网关中统一执行：不要把 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'));
`);

3.4 不强制文风（No prose-style enforcement）

Context Mode 只保证原始数据不进入上下文，从不规定模型最终回答该如何写。简洁、完整、格式如何，由模型自身决定，也可以通过你自己的 CLAUDE.md / AGENTS.md 等规则文件约束。官方说明：过于激进的“简洁提示词”已被证明会降低编码与推理基准表现，因此路由规则只聚焦“数据去哪里”，不干预“模型怎么说话”。

3.5 本地知识库与检索机制

ctx_index 按标题对 Markdown 分块并保留代码块完整，存入 SQLite FTS5 全文检索虚拟表；检索使用 BM25 概率相关性算法，按词频、逆文档频率与文档长度归一化打分。索引时应用 Porter 词干提取，使 running、runs、ran 匹配同一词干；标题与标题文字在 BM25 打分中权重为正文的 5 倍，便于精确的导航式查询。

检索采用两条并行策略再用倒数排名融合（RRF）合并：一是 Porter 词干的 FTS5 MATCH，二是 Trigram 子串匹配（useEff 可命中 useEffect，authenticat 可命中 authentication）。多词查询额外做邻近重排，查询词彼此靠近的段落获得更高权重；再用 Levenshtein 距离在重新检索前纠正拼写错误（kuberntes → kubernetes）。结果采用智能片段抽取，围绕匹配词返回窗口，而不是简单截断前 N 个字符。

索引内容持久化在按项目隔离的 SQLite 数据库中，默认路径 ~/.context-mode/content/。URL 抓取结果默认缓存 24 小时，可在单次调用中用 ttl（毫秒）覆盖；ttl: 0 或 force: true 可绕过缓存；启动时自动清理超过 14 天的内容数据库与来源。

4 内置工具一览

插件共注册 11 个 MCP 工具：6 个沙箱工具与 5 个元工具。下表“上下文节省”一列数据来自官方 README 工具表。

渐进限流：第 1–3 次检索返回常规结果（每查询 2 条）；第 4–8 次减少结果（每查询 1 条）并给出提示；第 9 次起拦截，引导改用 ctx_batch_execute。

5 兼容平台与路由方式

官方共支持 17 个 AI 编程客户端，另提供 OpenClaw 网关集成。支持钩子（Hook）的平台可在程序层面自动拦截与路由；不支持钩子的平台需要一次性复制路由指令文件。钩子可在工具执行前拦截危险命令并将其重定向到沙箱；指令文件只能通过提示词引导模型，无法真正拦截命令。因此官方建议：在支持钩子的平台上务必启用钩子。

Qwen Code、Kimi Code 同样配置 PreToolUse / PostToolUse / SessionStart / PreCompact / UserPromptSubmit 等钩子；完整能力对照见官方文档 platform-support.md。

完整平台能力对照：docs/platform-support.md

6 环境准备

6.1 运行时要求

• Node.js ≥ 22.5.0，或安装 Bun；Linux 上 Node < 22.5 不受支持，npm install 会失败并给出修复提示。
• 在 glibc ≥ 2.31 的系统（Ubuntu 20.04+、Debian 11+、Fedora 34+、macOS、Windows）上，npm install 无需任何构建工具。 SQLite 后端在运行时自动选择：Bun 环境使用内置 bun:sqlite；Linux + Node.js ≥ 22.5 使用内置 node:sqlite；其余环境使用 better-sqlite3。Bun 用户无需原生编译，会自动跳过 better-sqlite3 及其全部构建依赖。

6.2 老旧系统构建依赖（CentOS、RHEL、Alpine）

在 glibc 较老的系统（CentOS 7/8、RHEL 8、Debian 10）上，预编译二进制无法加载，better-sqlite3 会自动回退到源码编译（prebuild-install || node-gyp rebuild --release），需要 C++20 编译器（GCC 10+）、Make 与带 setuptools 的 Python。

6.2.1 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'

6.2.2 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'

6.2.3 Alpine Linux

better-sqlite3 v12.8.0+ 已提供 musl 预编译二进制；依赖范围 ^12.6.2 会解析到最新 12.x，通常无需构建工具。若固定了旧版本：

apk add build-base python3 py3-setuptools
npm install -g context-mode

Windows 或绑定缺失时，postinstall 脚本与运行时钩子会自动重新拉取预编译产物并修复绑定，无需手动 npm rebuild。

7 分平台安装部署

平台按安装复杂度分组。支持钩子的平台可获得自动路由强制；不支持钩子的平台需要一次性复制路由指令文件。下列命令与配置均逐字取自官方 README，版本与路径以官方仓库为准。

7.1 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。状态栏显示“本次会话节省 · 累计节省 · 效率百分比”，可实时看到节省累积。

备选：仅安装 MCP（不装钩子与斜杠命令）：

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

该方式提供全部 11 个 MCP 工具，但没有自动路由，模型不会被引导优先使用沙箱工具，适合在完整接入前先试用。

7.2 Gemini CLI（一个配置文件，含钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Gemini CLI。

第一步，全局安装 context-mode：

npm install -g context-mode

第二步，将以下内容加入 ~/.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" }] }
    ]
  }
}

第三步，重启 Gemini CLI。

验证：执行 /mcp list，应看到 context-mode: ... - Connected。

**路由方式：**由 SessionStart 钩子自动注入。可选复制路由指令文件，让模型完整感知路由规则：

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

7.3 VS Code Copilot（含 SessionStart 钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），VS Code 已安装 Copilot Chat v0.32+。

第一步，全局安装：

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

第四步，重启 VS Code。

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

**路由方式：**由 SessionStart 钩子自动注入。可选复制路由指令文件：

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

7.4 JetBrains Copilot（含 SessionStart 钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），JetBrains IDE 已安装 GitHub Copilot 插件 v1.5.57+。

第一步，全局安装：

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，工具应出现并响应。

**路由方式：**由 SessionStart 钩子自动注入。可选复制路由指令文件：

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

7.5 GitHub Copilot CLI（MCP + 钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 GitHub Copilot CLI（copilot）。若使用隔离的 Copilot 主目录，先设置 COPILOT_HOME。

方案 A（推荐，插件一条命令）：

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

插件包的 .mcp.json 固定 CONTEXT_MODE_PLATFORM=copilot-cli，使 context-mode 自识别为 Copilot；即使与 Claude Code 共存，ctx_upgrade 与平台检测也能正确解析为 copilot-cli，无需再执行 context-mode upgrade 或让代理调用。

方案 B（手动，不使用插件）：

第一步，全局安装：

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）配置钩子。Copilot CLI 触发六个事件：

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

也可在 Copilot CLI 上下文中执行 context-mode upgrade（或带 CONTEXT_MODE_PLATFORM=copilot-cli），由其写入该钩子文件；MCP 服务器仍需用第二步的 copilot mcp add 注册。

第四步，重启 Copilot CLI。

验证：在会话中输入 ctx stats；再执行 context-mode doctor 确认钩子与 MCP 注册。

版本说明：钩子命令运行全局 context-mode，因此需要具备 Copilot CLI 支持的版本；旧版本上钩子不生效（不拦截、不捕获），但不会阻断工具使用，升级命令为 npm install -g context-mode@latest。

7.6 Cursor（含 stop 支持的钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），Cursor 已开启 agent 模式。

市场插件仍在等待 Cursor 团队审核；上架前请使用下方本地文件夹方式安装。

方案 A：本地文件夹方式（市场上架前使用）。Windows 上 Cursor 不跟随符号链接，需使用 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)；更新时重新执行同一行复制命令即可。

方案 B：手动安装。第一步，全局安装：

npm install -g context-mode

第二步，在项目根目录创建 .cursor/mcp.json（全局则用 ~/.cursor/mcp.json）：

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

第三步，创建 .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" }]
  }
}

第四步，复制路由规则文件。Cursor 没有 SessionStart 钩子，模型需要规则文件来感知路由：

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

第五步，重启 Cursor 或新建 agent 会话。

验证：打开 Cursor Settings > MCP，确认 context-mode 显示为 connected；在 agent 对话中输入 ctx stats。

已知限制：Cursor 会接受钩子响应中的 additional_context，但不会把它呈现给模型；路由依赖 .mdc 规则文件，而非钩子上下文注入。

7.7 OpenCode（TypeScript 插件，含钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 OpenCode。

第一步，在项目根目录 opencode.json（全局则用 ~/.config/opencode/opencode.json）中加入：

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

plugin 条目原生注册全部 11 个 ctx_* 工具并启用钩子；OpenCode 在进程内调用 context-mode 的 TypeScript 插件，不会为每个会话额外派生 stdio MCP 子进程。

第二步（可选），复制路由规则文件，让模型感知路由：

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

第三步，重启 OpenCode。验证：在会话中输入 ctx stats，工具应出现并响应。

升级注意：若现有配置同时存在 plugin: ["context-mode"] 与 mcp.context-mode，OpenCode 将注册不到任何 ctx_ 工具。执行 context-mode upgrade 移除遗留的 mcp.context-mode 条目，其他 MCP 服务器保留。*

7.8 KiloCode（TypeScript 插件，含钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 KiloCode。

第一步，在项目根目录 kilo.json（全局则用 ~/.config/kilo/kilo.json）中加入：

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

第二步（可选），复制路由规则文件。KiloCode 与 OpenCode 共享插件架构，同样需要 AGENTS.md：

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

第三步，重启 KiloCode。验证：在会话中输入 ctx stats。

升级注意与 OpenCode 相同：不要同时配置 plugin 与 mcp.context-mode；必要时执行 context-mode upgrade 清理遗留 MCP 条目。

7.9 OpenClaw / Pi Agent（原生网关插件）

**前置要求：**OpenClaw 网关运行中（版本 > 2026.1.29），Node.js 22+。

与其他平台不同，这里没有独立的 MCP 服务器——插件通过 OpenClaw 插件 API 直接注册进网关运行时，面向 Pi Agent 会话（Read/Write/Edit/Bash 工具）。

第一步，克隆并安装：

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 重启网关。

第二步，打开 Pi Agent 会话。验证：插件通过 api.on() 与 api.registerHook() 注册 8 个钩子；输入 ctx stats 确认工具已加载。

**路由方式：**全自动，无需手动配置钩子或路由文件。

最低版本：OpenClaw > 2026.1.29，该版本包含 api.on() 生命周期修复；旧版本生命周期钩子会静默失效，适配器回退到数据库快照重建（精度较低但保留关键状态）。

7.10 Codex CLI（MCP + 钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Codex CLI。

第一步，添加 context-mode 市场并从 Codex 插件界面安装插件：

codex plugin marketplace add mksglu/context-mode

第二步，在插件钩子仍处于功能开关阶段时启用插件钩子：

[features]
plugin_hooks = true
hooks = true

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

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

第三步，重启 Codex CLI，用 ctx stats 验证 MCP。ctx stats 只能证明插件 MCP 服务器已安装可达，不能证明钩子已被信任并运行。

第四步，若 Codex 提示审批插件钩子，需审阅并信任 context-mode 插件钩子；只有两个功能开关都启用且 Codex 接受钩子命令后，插件钩子才生效。

手动回退（用于未提供 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（CODEX_HOME 未设置时用 ~/.codex/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

全局使用时复制到 ~/.codex/AGENTS.md；两者同时存在时 Codex CLI 会合并。第五步，重启 Codex CLI。

Codex 的 PreToolUse 目前仅支持 deny 规则（拦截危险命令），输入改写仍需上游 updatedInput 支持；PreToolUse 不支持上下文注入，上下文注入通过 PostToolUse 与 SessionStart 完成。

7.11 Kimi Code（MCP + 钩子，TOML 配置）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Kimi Code CLI。

第一步，全局安装：

npm install -g context-mode

第二步，在 ~/.kimi-code/mcp.json 中添加 MCP 服务器：

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

第三步，在 ~/.kimi-code/config.toml 中添加钩子：

[[hooks]]
event = "PreToolUse"
matcher = "Bash|Shell|Read|Edit|Write|WebFetch|Agent|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__"
command = "context-mode hook kimi pretooluse"
timeout = 30

[[hooks]]
event = "PostToolUse"
command = "context-mode hook kimi posttooluse"
timeout = 30

[[hooks]]
event = "SessionStart"
command = "context-mode hook kimi sessionstart"
timeout = 30

[[hooks]]
event = "PreCompact"
command = "context-mode hook kimi precompact"
timeout = 30

[[hooks]]
event = "UserPromptSubmit"
command = "context-mode hook kimi userpromptsubmit"
timeout = 30

[[hooks]]
event = "Stop"
command = "context-mode hook kimi stop"
timeout = 30

第四步，重启 Kimi Code CLI，用 ctx stats 验证 MCP。

第五步（可选），复制项目路由指令文件：

cp "$(npm root -g)/context-mode/configs/codex/AGENTS.md" ./AGENTS.md

7.12 Qwen Code（MCP + 钩子，协议同 Claude Code）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Qwen Code（npm install -g @qwen-code/qwen-code）。

第一步，全局安装：

npm install -g context-mode

第二步，在 ~/.qwen/settings.json 中添加 MCP 服务器：

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

第三步，在同一文件中添加钩子用于路由强制与会话跟踪：

{
  "hooks": {
    "PreToolUse": [{ "matcher": "run_shell_command|read_file|read_many_files|grep_search|web_fetch|agent|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|mcp__(?!.*context-mode)", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code pretooluse" }] }],
    "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code posttooluse" }] }],
    "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code sessionstart" }] }],
    "PreCompact": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code precompact" }] }],
    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code userpromptsubmit" }] }]
  }
}

第四步，复制路由指令文件：

cp node_modules/context-mode/configs/qwen-code/QWEN.md ./QWEN.md

全局使用时复制到 ~/.qwen/QWEN.md。第五步，重启 Qwen Code，输入 ctx stats 验证。

7.13 Antigravity IDE（仅 MCP，无钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Antigravity 桌面 IDE。

第一步，全局安装：

npm install -g context-mode

第二步，在 ~/.gemini/antigravity/mcp_config.json 中添加：

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

第三步，复制路由指令文件（Antigravity 不支持钩子）：

cp node_modules/context-mode/configs/antigravity/GEMINI.md ./GEMINI.md

第四步，重启 Antigravity，输入 ctx stats 验证。

**路由方式：**手动。GEMINI.md 是唯一强制手段，依从度约 60%，没有程序层面的拦截；平台经 MCP 协议握手自动识别。

7.14 Antigravity CLI（agy，插件：MCP + 技能 + 钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），Antigravity CLI（agy）≥ 1.0.7（用 agy update 升级；已在 agy 1.0.10 验证）。

安装：

npm install -g context-mode                                                                  # 插件的 MCP 服务器与钩子运行全局二进制
agy plugin install https://github.com/mksglu/context-mode/tree/main/configs/antigravity-cli  # 注册 MCP + 规则 + 技能 + 钩子

重启 agy。验证：在 agy 会话中输入 ctx stats，或运行 Try It 中的任意提示词查看节省；context-mode doctor 可确认 MCP 与钩子注册。卸载使用 agy plugin uninstall context-mode。

仅安装 MCP（不用插件、不要钩子）：跳过插件，把 context-mode 加入 agy 全局 MCP 配置 ~/.gemini/config/mcp_config.json（注意与 Antigravity IDE 的 ~/.gemini/antigravity/ 路径区分），然后重启 agy：

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

7.15 Kiro（钩子 + 引导文件）

**前置要求：**Node.js ≥ 22.5（或 Bun），Kiro 已启用 MCP（Settings 中搜索 MCP）。

第一步，全局安装：

npm install -g context-mode

第二步，在项目 .kiro/settings/mcp.json（全局则用 ~/.kiro/settings/mcp.json）中添加：

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

第三步，创建 .kiro/hooks/context-mode.json：

{
  "name": "context-mode",
  "description": "Context-mode hooks for context window protection",
  "hooks": {
    "preToolUse": [
      { "matcher": "execute_bash|fs_read|@context-mode/ctx_execute|@context-mode/ctx_execute_file|@context-mode/ctx_batch_execute|@(?!context-mode/)", "command": "context-mode hook kiro pretooluse" }
    ],
    "postToolUse": [
      { "matcher": "*", "command": "context-mode hook kiro posttooluse" }
    ]
  }
}

第四步，复制路由指令文件。Kiro 的 agentSpawn（SessionStart 等价物）尚未实现，模型需要会话开始时的路由文件：

cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md

第五步，重启 Kiro。验证：打开 Kiro 面板 MCP Servers 标签，确认 context-mode 为绿色状态；对话中输入 ctx stats。

7.16 Zed（仅 MCP，无钩子）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Zed。

第一步，全局安装：

npm install -g context-mode

第二步，在 ~/.config/zed/settings.json（Windows 为 %APPDATA%\Zed\settings.json）中添加：

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

Zed 使用 context_servers 而不是 mcpServers；args 与 env 对 context-mode 可选，此处仅用于匹配 Zed 自定义 MCP 服务器结构。

第三步，复制路由指令文件（Zed 不支持钩子）：

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

第四步，重启 Zed（保存 settings.json 后 Zed 会自动重启上下文服务器）。

验证：打开 Agent Panel（Cmd+Shift+A）进入设置，查看 context-mode 旁的状态点，绿色即生效；在 agent 对话中输入 ctx stats。

7.17 Pi Coding Agent（扩展，完整钩子支持）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Pi Coding Agent。

第一步，全局安装：

npm install -g context-mode

第二步，将包安装进 Pi：

pi install npm:context-mode

备选：手动加入 ~/.pi/agent/settings.json（项目级用 .pi/settings.json）：

{ "packages": ["npm:context-mode"] }

第三步，在 ~/.pi/agent/mcp.json（项目级用 .pi/mcp.json）中添加：

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

第四步，重启 Pi，输入 ctx stats 验证。扩展注册 tool_call、tool_result、session_start、session_before_compact 等关键生命周期事件，提供完整会话连续性与路由强制。

7.18 OMP（Oh My Pi，插件，完整钩子支持）

**前置要求：**Node.js ≥ 22.5（或 Bun），已安装 Oh My Pi。

方案 A（推荐，插件路径）。第一步，执行插件安装：

omp plugin install context-mode

第二步，重启 OMP。第三步，验证：

omp plugin list
omp plugin doctor

两者都应显示 context-mode 为 enabled。插件首次加载时会在 ~/.omp/agent/mcp.json 自注册 MCP 服务器（以 node <插件目录>/server.bundle.mjs 启动，因为插件安装包目录不在 PATH 上），重启后 11 个 ctx_* 工具即可访问；已存在的 context-mode 条目不会被覆盖，如需插件重新注册内置路径可先删除旧条目。

方案 B（手动插件路径，当 omp plugin install 不可用）：

cd ~/.omp/plugins
bun add context-mode    # 或：npm install context-mode

随后重启 OMP，无需编辑锁文件或固定版本。

方案 C（仅 MCP，不使用插件）。第一步，全局安装：

npm install -g context-mode

第二步，加入 ~/.omp/agent/mcp.json（用户级）或 /.omp/mcp.json（项目级）：

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

第三步，复制路由指令文件：

cp node_modules/context-mode/configs/omp/SYSTEM.md ~/.omp/agent/SYSTEM.md

项目级可复制到 .omp/SYSTEM.md；OMP 也会自动发现项目树中的 AGENTS.md。第四步，重启 OMP，输入 ctx stats 验证。

**路由方式：**插件路径通过四个 pi.on(...) 处理器实现程序强制，依从度约 98%，与 Claude Code 钩子持平；仅 MCP 路径依靠 SYSTEM.md 规则，依从度约 60%。存储根目录位于 ~/.omp/context-mode/，OMP 与 Pi 安装不会共享会话数据库、内容索引或统计文件。

8 验证与常用命令

8.1 会话内命令

在任意 AI 会话中直接输入命令，LLM 会自动调用对应 MCP 工具：

ctx stats       # 上下文节省、调用次数、会话报告
ctx doctor      # 诊断运行时、钩子、FTS5、版本
ctx index       # 索引本地文件或目录，供后续检索
ctx search      # 检索此前已索引的内容
ctx upgrade     # 从 GitHub 更新、重建、重新配置钩子
ctx purge       # 永久删除知识库中全部已索引内容
ctx insight     # 在浏览器打开托管的 Insight 仪表盘

上述命令在全部平台可用。Claude Code 另提供斜杠命令：/context-mode:ctx-stats、/context-mode:ctx-doctor、/context-mode:ctx-index、/context-mode:ctx-search、/context-mode:ctx-upgrade、/context-mode:ctx-purge、/context-mode:ctx-insight。

8.2 终端命令（无需进入 AI 会话）

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    # 提交问题时使用的完整诊断报告

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

9 效果基准

下表为官方 README 给出的 8 个典型场景实测结果：

完整会话口径：315 KB 原始输出压缩为 5.4 KB，可用会话时长从约 30 分钟延长到约 3 小时。

完整基准数据（21 个场景、总原始 376 KB → 16.5 KB、整体节省 96%、代码示例 100% 原样保留）见官方 BENCHMARK.md：BENCHMARK.md

10 隐私与安全

10.1 隐私与运行架构

Context Mode 不是 CLI 输出过滤器，也不是云端分析仪表盘，而是运行在 MCP 协议层：原始数据留在隔离的子进程中，绝不进入上下文窗口。网页、接口响应、文件分析、Playwright 快照、日志文件，全部在完全隔离的环境中处理。

• 代码、提示词、会话数据全部留在本机；无遥测、无云同步、无使用追踪、无需账号。
• SQLite 数据库位于用户主目录，会话结束后随清理规则释放。
• 已索引内容默认存储在 ~/.context-mode/content/；内容数据库与来源超过 14 天会在启动时自动清理。 自定义存储根目录：可设置环境变量 CONTEXT_MODE_DIR 为绝对可写路径；会话与统计使用 /sessions，已索引内容使用 /content。空值或纯空白视为未设置；非空值必须为绝对路径，不展开 ~。

10.2 权限规则透传

Context Mode 沿用你已有的权限规则，并将其扩展到 MCP 沙箱：若你在主机上拦截了 sudo，那么在 ctx_execute、ctx_execute_file、ctx_batch_execute 中同样被拦截。未配置任何权限规则时不发生变化，只有添加规则后才生效。规则格式为 Tool(匹配项)，* 表示任意内容：

{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /*)",
      "Read(.env)",
      "Read(**/.env*)"
    ],
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)"
    ]
  }
}

规则可写入项目 .claude/settings.json 或全局 ~/.claude/settings.json；全部平台都读取 Claude Code 设置格式，包括 Gemini CLI、VS Code Copilot 与 OpenCode。Codex CLI 的安全强制需要在 $CODEX_HOME/hooks.json 或 ~/.codex/hooks.json 中配置 Codex 钩子。

• deny 始终优先于 allow；更具体的项目级规则覆盖全局规则。
• 用 &&、;、| 连接的命令会被拆分，逐段检查；echo hello && sudo rm -rf /tmp 会因 sudo 段命中 deny 规则而被拦截。

10.3 项目边界隔离

ctx_execute_file 被限制在项目根目录内。若解析出的路径位于工作区之外（绝对路径 /home/user/secrets、../../ 回溯、或指向项目外的本地符号链接），会以 File access blocked 错误拒绝，堵住代理在主机沙箱被拒后又试图通过 MCP 沙箱越权读取的逃逸路径。

该防护默认开启，无需配置。若确实需要处理项目外文件（例如 /var/log 下的共享日志），使用与主机 Read 工具相同的 permissions.allow 规则放行，不提供 context-mode 专属环境变量开关：

{
  "permissions": {
    "allow": ["Read(/var/log/**)"]
  }
}

防护边界说明：ctx_execute 与 ctx_batch_execute 会运行任意代码并继承进程的文件系统访问，因此边界守卫只是文件读取工具的纵深防御层，不是完整操作系统沙箱；审批任意执行工具时应视同审批任意代码，并保持主机层面的沙箱开启。

10.4 网络抓取加固

ctx_fetch_and_index 默认拦截危险 URL 目标：

• 协议：仅允许 http: 与 https:，禁止 file://、gopher://、javascript:、data:。
• 云元数据与链路本地地址：169.254.0.0/16（含 AWS/GCP/Azure 元数据端点 169.254.169.254）即使主机名解析到该段也会硬拦截（DNS 重绑定防御）。
• 组播与保留地址：224.0.0.0/4、0.0.0.0/8、IPv6 ff00::/8、fe80::/10 被拦截。
• 回环地址与 RFC1918 内网段（localhost、127.x、10.x、172.16-31.x、192.168.x、IPv6 ::1、fc00::/7）默认放行，保证本地开发服务器与内网抓取可用。 在托管或 CI 环境中如需同时拦截私有目标，设置环境变量 CTX_FETCH_STRICT=1，将在常驻拦截网段之外再拦截回环、RFC1918 与 ULA 段，适合把 context-mode 作为共享服务运行的场景。

任何 mcp__* 工具调用的 tool_input 在持久化前都会被脱敏：authorization、auth_token、access_token、refresh_token、bearer、token、secret、password、passwd、pwd、api_key/apikey/x_api_key、cookie/set-cookie、signature、private_key、client_secret 等字段（大小写、连字符与下划线不敏感）会被替换为 [REDACTED]，避免凭证进入会话数据库。

10.5 相关环境变量

11 团队版 Insight 平台

Insight 是 Context Mode 平台上的第一个解决方案，面向 AI 辅助研发团队提供工程信号分析：按工程师统计生产率、按团队统计重试浪费、识别并命名模式、给出可执行动作，并为 CTO、工程经理、个人贡献者、CISO、FinOps、DevOps 等角色提供收窄后的视图。

仪表盘入口：https://context-mode.com/insight

官方图面标注：222 种模式、13 个 MCP 工具、14 个 AI 适配器、7 种角色视图，定价 20 美元 / 席位 / 月。会话内执行 ctx insight 即可在浏览器打开该仪表盘。

12 官方链接汇总

说明：受当前网络环境限制，本环境未能拉取 shields.io 统计徽章与 YouTube 演示封面图；上述链接可在浏览器直接打开，查看实时 Star、版本与演示画面。

13 附录

13.1 开源协议（Elastic License 2.0）

项目以 Elastic License 2.0（ELv2）许可发布，属于源码可见协议：你可以使用、Fork、修改与分发。两项限制为：不得将其作为托管 / 托管服务提供，不得删除许可声明。官方说明：选择 ELv2 而非 MIT，是因为 MIT 允许把代码重新打包成竞争性闭源 SaaS；ELv2 在保持源码对所有人可见的同时禁止此类转售。

13.2 常见故障排查

• 先在会话中执行 ctx doctor，或在终端执行 context-mode doctor，逐一确认运行时、钩子、FTS5 与插件注册状态。
• 工具未出现：检查 MCP 服务器命令是否可执行；OpenCode/KiloCode 若同时配置 plugin 与 mcp.context-mode，会注册不到工具，执行 context-mode upgrade 清理遗留 MCP 条目。
• 钩子不生效：确认平台已启用对应功能开关（如 Codex 的 [features].hooks 与 plugin_hooks），并在平台提示时信任插件钩子。
• 需要提交问题时，运行 bash scripts/ctx-debug.sh 生成完整诊断报告。
• 升级到最新版本：执行 context-mode upgrade，或 npm install -g context-mode@latest；升级会重建、迁移缓存并修复钩子。
• 清空知识库：执行 ctx purge 永久删除全部已索引内容。

13.3 本地开发与贡献

git clone https://github.com/mksglu/context-mode.git
cd context-mode && npm install && npm test

开发流程与 TDD 规范见仓库内 CONTRIBUTING.md。