context-mode：2.3 万星的上下文优化器，沙箱化工具输出省 98% 上下文窗口

用 AI 编程 Agent 的人迟早撞上一堵墙：上下文窗口不够用。一个 Playwright 页面快照 56 KB，20 个 GitHub issue 59 KB，一份访问日志 45 KB——Agent 跑半小时，40% 的上下文就被工具输出吃掉了，然后开始"失忆"：忘记改到哪了、忘记用户要求、被迫压缩后彻底跑题。

context-mode 就是冲着这个问题来的。它 2026 年 2 月创建，7 个月冲到 2.3 万星，一度登顶 Hacker News（570+ 分）。它的口号很直白："The other half of the context problem"（上下文问题的另一半）——前一半是"模型上下文窗口多大"，后一半是"怎么把有用的东西留在窗口里"。

这篇文章拆解它的实现原理：为什么能省 98% 上下文、怎么做到的、以及它对"上下文工程"这个领域的意义。

本文 outline

1. 问题：工具输出正在吃掉 Agent 的上下文
2. context-mode 是什么：MCP 层的上下文优化器
3. 核心机制一：沙箱化工具输出
4. 核心机制二：FTS5 知识库按需检索
5. 核心机制三：会话快照恢复（防失忆）
6. "Think in Code"：把 Agent 从数据处理器变回代码生成器
7. 实现细节：hooks 路由 + 17 平台适配
8. 价值与局限

1. 问题：工具输出正在吃掉 Agent 的上下文

先算一笔账。Agent 每调用一次工具，工具返回的原始数据就全部塞进上下文。真实场景里的典型数据量：

这些数据里，Agent 真正需要的往往只是其中的一小段——但传统机制是全量进上下文。结果就是：上下文被无关数据灌满，模型注意力被稀释，长任务跑不动，压缩后关键信息丢失。

context-mode 的创始人算过一笔账：一次完整会话 315 KB 的原始输出，真正需要的只有 5.4 KB，98% 是浪费。它要做的就是把那 98% 挡在上下文窗口之外，同时保证 Agent 需要时还能拿到那 2%。

2. context-mode 是什么：MCP 层的上下文优化器

context-mode 是一个 MCP server（npm 包 context-mode），不是代理、不是包装 CLI。它工作在 MCP 协议层，通过每个平台的 hooks 介入 Agent 的工具调用循环。

它解决四个问题：

1. 上下文节省——沙箱化工具输出，原始数据不进窗口
2. 会话连续性——把会话状态持久化到 SQLite，压缩/恢复不丢工作状态
3. "Think in Code"——引导 Agent 写脚本只返回结果，而不是把大数据读进上下文
4. 不强求精简文风——它明确不做"让模型少说废话"这件事，引用了 Moonshot 的 kimi-k2.5 研究：激进的精简提示反而降低编码/推理基准分

许可证是 Elastic License 2.0（源码可用，但禁止重打包成竞争性闭源 SaaS）。TypeScript 实现，核心用 SQLite（bun:sqlite / node:sqlite / better-sqlite3 自适应）。

3. 核心机制一：沙箱化工具输出

这是省 98% 的核心手段，原理一句话：工具在隔离的子进程里执行，只有 stdout 进入上下文，原始数据永远出不了沙箱。

ctx_execute 工具每次调用启动一个隔离子进程，支持 12 种语言运行时（JS/TS/Python/Shell/Ruby/Go/Rust/PHP/Perl/R/Elixir/C#），Bun 自动检测可让 JS/TS 快 3-5 倍。

关键在意图驱动的过滤：当输出超过 5 KB 且提供了 intent（意图）时，它把完整输出索引进知识库，搜索与意图匹配的片段，只返回相关部分。看真实数字：

• ctx_execute：56 KB → 299 B（99% 省）
• ctx_execute_file：45 KB → 155 B（100% 省）
• ctx_batch_execute：986 KB → 62 KB（94% 省）

这就是"315 KB 变成 5.4 KB"的真相——不是压缩，是选择性保留：全量数据存到沙箱外可检索的地方，上下文里只放 Agent 当下需要的片段。

4. 核心机制二：FTS5 知识库按需检索

被沙箱"挡下来"的数据去哪了？进了 SQLite 的 FTS5 全文索引，变成可检索的知识库。Agent 需要时可以按需查回来。

ctx_index 把 Markdown 按标题分块（代码块保持完整）索引进 FTS5，检索用 BM25 排序 + Porter stemming（标题加权 5 倍）+ Reciprocal Rank Fusion（porter + trigram 子串融合）+ 邻近度重排 + Levenshtein 模糊纠正 + 智能摘要。

ctx_fetch_and_index 抓 URL → HTML 转 Markdown → 分块 → 索引，原始网页永不进上下文，带 24 小时 TTL 缓存（缓存命中返回 ~0.3 KB 提示 vs 重新抓取的 48 KB+）。

这套机制的本质是**"检索增强的上下文"（retrieval-augmented context）：把数据移出上下文、按需取回，而不是对话式地全量塞进去。这和我此前写过的 OpenViking、LLM Wiki 是同一个思路在不同层面的应用——不过 context-mode 是给编码 Agent 的会话**用的，粒度更细、更实时。

5. 核心机制三：会话快照恢复（防失忆）

长任务失忆的根源是：上下文压缩（compaction）时，模型"想不起来"之前的工作状态。context-mode 的解法是把状态持久化到磁盘，而不是指望模型记住。

通过 hooks 捕获每个事件（文件编辑、git 操作、任务、错误、用户决策）写入每项目的 SQLite。关键动作：

• PreCompact（压缩前）：构建一个分级优先级的 XML 快照（≤2 KB），包含当前任务、计划、关键决策、未解决错误、约束、阻塞项等
• SessionStart（会话恢复）：从快照重建一个 19 类别的 Session Guide（最后请求、任务、计划、关键决策、修改的文件、未解决错误、约束、阻塞项、Git 状态、项目规则、用过的 MCP 工具、子 Agent 任务、用过的 Skills、被否定的方案、外部引用、环境、数据引用、会话意图、用户角色）

结果：压缩不再丢状态，会话从 ~30 分钟延长到 ~3 小时。这是"抗压缩的 Agent 记忆"的一个具体实现——和我在 langflow/LLM Wiki 文章里讲过的会话持久化理念一脉相承，但落地在编码 Agent 的日常循环里。

还有渐进式节流：工具调用 1-3 次正常（每次返回 2 个结果）、4-8 次降为 1 个结果 + 警告、9 次以上直接拦截并重定向到 ctx_batch_execute。防止 Agent 疯狂调工具刷爆上下文。

6. "Think in Code"：把 Agent 从数据处理器变回代码生成器

这是 context-mode 最有思想性的一点，也是一种范式转变。

传统模式：Agent 面对 47 个文件，逐个 Read()，700 KB 读进上下文，然后"理解"它们。context-mode 的替代：让 Agent 写一段脚本去计算，只把结果 console.log() 出来。

之前：47 × Read() = 700 KB 进上下文
之后：1 × ctx_execute() = 3.6 KB 进上下文

这背后是一个深刻的判断：LLM 是代码生成器，不是数据处理引擎。让模型"读"海量数据是扬短避长——应该让它"写代码去处理数据"，它只消费处理结果。README 原话："Think in Code"——在代码里思考，而不是在上下文里堆数据。

这个理念对 Agent 开发的启示：工具设计应该引导模型计算而不是搬运。一个设计良好的 Agent 工具集，天然就会把数据留在外面、只传结果进来。

7. 实现细节：hooks 路由 + 17 平台适配

context-mode 支持 17 个平台：Claude Code（插件，全自动）、Gemini CLI、VS Code Copilot、Cursor、Codex CLI、OpenCode、KiloCode、OpenClaw/Pi、Kimi Code、Qwen Code、Zed 等。

实现分两层：

• MCP 工具层：11 个工具——6 个沙箱工具（ctx_batch_execute、ctx_execute、ctx_execute_file、ctx_index、ctx_search、ctx_fetch_and_index）+ 5 个元工具（ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight）
• Hooks 层：各平台的 PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop。hooks 程序化强制路由（拦截/拒绝 + 重定向到沙箱）

一个很有说服力的数据点：hooks 强制路由的合规率 ~98%，而只靠指令文件（AGENTS.md）只有 ~60%。没有 hooks 的平台（Zed、Antigravity）只能靠手动复制路由文件，合规率就是 60% 档。这直接说明：上下文工程里，机制强制 >> 提示词劝导。

安装很简单，Claude Code 走插件市场：

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

通用 MCP 安装：npm install -g context-mode 然后注册 MCP server。

8. 价值与局限

价值：

• 省的是真金白银：上下文字节/token 直接转成成本。context-mode v1.0.167 起加入了真实的逐轮 token/成本捕获（"FinOps"），内置 63 个模型的定价目录，状态栏能显示"本会话省了 $X · 累计省了 $Y · 效率 Z%"——省上下文 = 省成本，可量化
• 隐私友好："Nothing leaves your machine"——无遥测、无云同步、无账号，全本地 SQLite
• 会话时长质变：30 分钟 → 3 小时，长任务 Agent 从"不可能"变"可行"

局限（要诚实说）：

• 98% / 315KB→5.4KB / 30分钟→3小时 都是项目自报数字，没有独立第三方复测
• 许可证是 ELv2（源码可用但限制重打包 SaaS），不是 OSI 认证的开源协议，商用前要评估
• 数据留沙箱意味着检索质量依赖索引：FTS5 的 BM25 检索质量不如向量检索精细，某些"需要完整理解上下文"的任务可能不适合
• 项目太活跃：版本迭代快、配置经常变（各平台安装步骤差异大），有 244 个 open issues
• 大厂采用是营销声明（Microsoft/Google/...），未经验证

一句话定位：context-mode 是"上下文工程"这个新兴领域里，把理论落到编码 Agent 日常的最完整实现之一。它证明了三件事——工具输出应该沙箱化、知识应该按需检索、会话状态应该持久化。对做长任务 Agent 的团队，它既是可用的工具，也是一份值得抄的架构设计。

参考

• mksglu/context-mode GitHub — 2.3 万星，ELv2，TypeScript
• context-mode 官网 — 安装与文档
• 前篇：Langflow LLM Tracing 拆解 — Agent 可观测性与会话状态
• 前篇：OpenAI 和 Claude 的 API 缓存原理 — 长上下文 Agent 的成本问题

作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

关注公众号，获取更多 AI 技术干货！