Context Mode 深度解析：用沙盒、SQLite 与钩子路由，把 AI 编码 Agent 的上下文消耗削减 98%

核心信息速览

项目	详情
项目名称	Context Mode
GitHub 仓库	https://github.com/mksglu/context-mode
开发者	mksglu
开源协议	MIT License
主要语言	TypeScript
GitHub Star	约 23k（撰写时快照）
开源时间	2026 年 2 月 23 日
最新版本	v1.0.164（2026 年 6 月 22 日）
项目定位	AI 编码 Agent 的上下文窗口优化工具（MCP Server + 钩子路由）
核心指标	沙盒化工具输出，声称减少 98% 上下文占用
关键技术	SQLite FTS5、BM25 排序、多语言沙盒子进程、MCP 协议、钩子路由
支持平台	17 个 AI 编码客户端（Claude Code、Gemini CLI、VS Code Copilot、OpenCode、Codex CLI 等）
支持语言运行时	11 种（JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir）
安装方式	Claude Code 插件市场 / npm 全局安装 / MCP-only 配置

一、问题：上下文窗口正在被"工具输出"淹没

每个使用 AI 编码 Agent 的开发者都经历过这个循环：一开始模型很聪明，几分钟后开始犯糊涂、遗忘文件、重复提问。罪魁祸首往往不是模型本身，而是工具输出正在无声地吞噬上下文窗口。

一个 Playwright 快照消耗 56 KB ，20 个 GitHub Issue 消耗 59 KB ，一份访问日志消耗 45 KB 。30 分钟后，40% 的上下文空间就消失了。当 Agent 为了腾出空间而压缩对话时，它会忘记正在编辑哪个文件、当前任务进行到哪一步、你最后要求了什么。

Context Mode 的定位非常清晰：它是"上下文问题的另一半" 。如果说 Cloudflare Code Mode 解决的是工具定义占用过多 token 的问题（将工具描述从百万 token 压缩到约 1000 token），那么 Context Mode 解决的是工具输出占用过多 token 的问题。两者互补，共同构成完整的上下文治理方案。

二、四大核心机制：从"数据处理器"到"代码生成器"

Context Mode 通过四个相互配合的机制解决上述问题：

2.1 沙盒隔离：原始数据永不进入上下文

这是 Context Mode 最核心的设计。每次工具调用在独立的子进程中运行 ，子进程执行代码、捕获 stdout，只有 stdout 会进入对话上下文。原始数据------日志文件、API 响应、快照------永远留在沙盒内。

支持 11 种语言运行时 ：JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir。Bun 会被自动检测，用于将 JS/TS 执行速度提升 3--5 倍。

实测压缩效果：

场景	原始大小	沙盒后	压缩比
Playwright 快照	56 KB	299 B	~99.5%
20 个 GitHub Issue	59 KB	1.1 KB	~98%
500 条访问日志	45 KB	155 B	~99.7%
500 行 CSV 分析	85 KB	222 B	~99.7%
153 次 git 提交日志	11.6 KB	107 B	~99.1%
完整会话	315 KB	5.4 KB	~98%

数据来源：项目作者在 11 个真实场景中的测试。

这一机制将会话的可用时间从约 30 分钟延长到约 3 小时。

2.2 持久化会话内存：压缩后不丢失工作状态

当上下文窗口填满、Agent 压缩对话时，传统方案会让模型丢失工作状态。Context Mode 的做法不同：每一次文件编辑、git 操作、任务、错误和用户决策都被记录在项目级的 SQLite 数据库中 。当对话压缩时，Context Mode 不会把数据倒回上下文 ，而是将事件索引到 FTS5 中，通过 BM25 搜索只检索相关部分。模型从你上次停下的地方精确继续。

如果你不使用 --continue 恢复会话，上一次的会话数据会被立即删除------新会话意味着干净的状态。

2.3 代码化思考（Think in Code）：让 LLM 写脚本，而不是读数据

这是 Context Mode 最具范式转变意义的强制规则。LLM 应该编写分析代码，而不是亲自计算分析 。与其读取 50 个文件到上下文中来统计函数数量，不如让 Agent 写一个脚本来完成计数，只 console.log() 出结果。

一个脚本可以替代十次工具调用，节省 100 倍上下文。这一范式在全部 17 个支持的客户端中强制执行，并在 OpenClaw 网关集成中同样生效。

前后对比：

之前：47 × Read() = 700 KB
之后：1 × ctx_execute() = 3.6 KB

2.4 不强制文风：只管数据去哪，不管模型怎么说

一个值得注意的设计克制：Context Mode 将原始数据挡在上下文之外，但从不规定模型如何撰写最终回答 。简洁度、完整度、格式------完全由模型自己（或你的 CLAUDE.md/AGENTS.md）决定。项目引用 Moonshot AI 在 Kimi K2.5 上的测试指出，激进的简洁性提示会降低编码和推理基准的表现，因此路由块只关注"数据去哪里"，不关注"模型怎么说话"。

三、技术架构：MCP Server + 钩子路由 + FTS5 知识库

3.1 组件构成

Context Mode 以 MCP Server 的形式运行，同时通过钩子在工具调用前后进行程序化拦截。在 Claude Code 上，插件安装会注册 6 个钩子 （PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop）和 11 个 MCP 工具（6 个沙盒工具 + 5 个元工具）。

核心沙盒工具：

工具	功能	上下文节省
`ctx_batch_execute`	在一次调用中运行多个命令 + 多个搜索查询	986 KB → 62 KB
`ctx_execute`	在 11 种语言中运行代码，只有 stdout 进入上下文	56 KB → 299 B
`ctx_execute_file`	在沙盒中处理文件，原始内容永不离开	45 KB → 155 B
`ctx_index`	将 Markdown 分块索引入 FTS5，BM25 排序	60 KB → 40 B
`ctx_search`	在一次调用中执行多个查询	按需检索
`ctx_fetch_and_index`	抓取 URL，检测内容类型，分块并索引	60 KB → 40 B

元工具 ：ctx_stats（节省统计）、ctx_doctor（诊断）、ctx_upgrade（升级）、ctx_purge（清除索引）、ctx_insight（团队分析仪表盘）。

3.2 知识库：SQLite FTS5 + BM25 + 模糊搜索

ctx_index 工具按标题对 Markdown 内容分块，保持代码块完整 ，然后存入 SQLite FTS5 虚拟表。搜索使用 BM25 排序 ------一种基于词频、逆文档频率和文档长度归一化的概率相关性算法。索引时应用 Porter 词干化，使"running""runs""ran"匹配同一个词干。

搜索采用三层回退处理拼写错误和部分匹配：

Porter 词干化：标准 FTS5 MATCH
Trigram 子串匹配 ："useEff" 可找到 "useEffect"
Levenshtein 模糊纠正 ："kuberntes" → "kubernetes"

搜索结果使用智能片段提取，返回匹配词周围的窗口，而非简单截断。

3.3 钩子路由：从"建议"到"强制"

Context Mode 在不同平台上的强制力取决于该平台是否支持钩子：

平台	钩子支持	路由强制力
Claude Code	全部 6 个钩子	完全自动，程序化拦截
Gemini CLI	BeforeTool、AfterTool、PreCompress、SessionStart	自动，BeforeTool 拦截
VS Code Copilot	PreToolUse、PostToolUse、SessionStart	自动
OpenCode	插件钩子（`tool.execute.before`、`experimental.session.compacting`）	自动（SessionStart 暂缺）
Codex CLI	不支持钩子	仅靠 `AGENTS.md` 指令（~60% 遵从率）

关键差异：没有钩子时，Context Mode 依赖路由指令文件，遵从率约 60% ；有钩子时，遵从率接近 98%------一个未经路由的 Playwright 快照（56 KB）就可能抹掉整个会话的节省。

四、支持的 17 个平台

Context Mode 覆盖 17 个 AI 编码客户端，按安装复杂度分组：

平台	安装方式	钩子路由
Claude Code	插件市场，全自动	✅ 完全自动
Gemini CLI	全局 npm + 单一配置文件	✅ BeforeTool 等
VS Code Copilot	全局 npm + `.vscode/mcp.json` + 钩子文件	✅ PreToolUse 等
JetBrains Copilot	全局 npm + 设置 UI + 钩子文件	✅
GitHub Copilot CLI	插件（一键）或手动	✅ 6 个事件
OpenCode	全局 npm + 插件	✅（部分）
Codex CLI	全局 npm + `config.toml`	❌ 仅指令（~60%）
Kiro、Zed 等	逐步适配	视平台而定

此外，项目还提供了 OpenClaw 网关集成，使得 OpenClaw 用户也能受益于沙盒路由。

五、安装与使用（以 Claude Code 为例）

5.1 插件安装（推荐，全自动）

前提：Claude Code v1.0.33+（claude --version 确认）。

bash 复制代码

# 在 Claude Code 中执行
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

重启 Claude Code。插件会自动安装 MCP Server（11 个工具）、全部钩子、以及路由指令文件。

验证：

bash 复制代码

/context-mode:ctx-doctor

所有检查项应显示 [x]，验证运行时、钩子、FTS5 和插件注册。

5.2 MCP-Only 安装（仅工具，无钩子路由）

bash 复制代码

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

这会提供 11 个 MCP 工具，但没有自动路由------模型不会被告知优先使用它们，适合先试用再决定是否全量安装。

5.3 状态栏（可选）

手动编辑 ~/.claude/settings.json：

json 复制代码

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

状态栏会显示 $ saved this session · $ saved across sessions · % efficient，让节省过程实时可见。

六、小结

Context Mode 的价值不在于它发明了某个全新的存储或检索技术，而在于它精准地识别并系统性地解决了 AI 编码 Agent 工作流中的一个结构性浪费：工具输出正在无声地消耗本应留给推理的上下文预算。

它的核心设计决策------沙盒隔离让原始数据永不进入上下文、SQLite FTS5 + BM25 让压缩后的会话状态可精准恢复、代码化思考强制范式将 LLM 从数据处理器转变为代码生成器、钩子路由将"建议"升级为"强制"------共同构成了一套可安装、可验证、跨平台复用的上下文治理层。

对于长期使用 AI Agent 进行复杂任务的开发者，它的实际意义可以用一个数字概括：完整会话的上下文占用从 315 KB 降到 5.4 KB（减少 98%），可用时间从约 30 分钟延长到约 3 小时。对于需要多轮工具调用的编码任务，这直接转化为更少的会话重置、更少的上下文遗忘、以及更低的 token 成本。

需要客观指出的是，98% 是项目说明中的能力表达，不能被理解为对任何仓库都成立的性能承诺------实际节省取决于工作负载中工具输出的比例和大小。Codex CLI 等不支持钩子的平台只能达到约 60% 的遵从率，效果会打折扣。此外，项目仍在快速迭代中（从 v0.9.x 到 v1.0.164 仅数月），API 和平台适配可能持续变化，生产使用前建议以仓库最新 Release 说明为准。

附录：资源列表

类型	资源	说明
📦 下载地址	点击下载	zip压缩包和安装使用说明
✅ GitHub 仓库	https://github.com/mksglu/context-mode	MIT License
📦 npm 包	`context-mode`	全局安装：`npm install -g context-mode`
📦 MCP 包（社区镜像）	`@iflow-mcp/mksglu-context-mode`	社区维护的 MCP 封装
📄 Claude Code 安装文档	仓库 README 的 Install 章节	插件市场安装步骤
📄 Gemini CLI 配置	`configs/gemini-cli/settings.json`	单一配置文件示例
📄 VS Code Copilot 配置	`configs/vscode-copilot/`	MCP + 钩子配置
📄 GitHub Copilot CLI 配置	`configs/copilot-cli/`	插件 Bundle
📄 OpenClaw 集成	仓库 README 相关章节	网关级路由集成

作者简介：橘子，计算机视觉方向工程师，深耕 AIGC 与多媒体处理领域，专注技术实用化落地。

本文为原创内容，转载请注明来源与作者。

📢 温馨提示：Context Mode 为 MIT 协议开源项目，使用前请阅读仓库 LICENSE 文件。98% 的上下文缩减为项目说明中的能力表达，实际效果因工作负载而异。Codex CLI 等不支持钩子的平台遵从率约为 60%。项目处于快速迭代阶段，功能与 API 可能变化，建议以 GitHub 仓库最新 README 和 Release Notes 为准。