context-mode 深拆：AI 编程代理的上下文窗口优化

一、上下文窗口：被忽视的"另一半问题"

过去一年里，编码 agent 成了开发者身边最忙的"数字劳动力"。它们开终端、跑命令、改文件、提 PR，一个人同时挂着 Claude Code、Codex、Cursor 已经不稀奇。但很少有人注意到，模型变聪明之后，真正的瓶颈悄悄从"模型够不够强"挪到了"上下文窗口装不下"。

context-mode 的官方定位是"上下文问题的另一半"。它想补的正是这一半：不是让模型更会写代码，而是让 agent 在长会话里别被自己的上下文撑爆、别在压缩时失忆、别把 token 浪费在搬运原始数据上。

痛点很具体。README 的数字来自真实场景：一次 Playwright 页面快照 56 KB，二十个 GitHub issue 合计 59 KB，一条访问日志 45 KB。三十分钟下来，你的上下文窗口里有 40% 是这种"搬运来的原始数据"。更糟的是，当 agent 为了腾地方做会话压缩（compact）时，它会把正在编辑的文件、进行中的任务、你上一句的要求一起忘掉。再加上 agent 自己会把输出 token 花在寒暄、废话和冗长解释上，上下文从两端一起被烧。

这正是 herdr 这类运行时项目 没碰到的那一层：herdr 管的是 agent 的终端与多机调度，context-mode 管的是 agent 脑内那块上下文内存。两者不是替代，是同一波浪潮在不同入口的落点，而上下文优化与会话编排两件事都得解决，这也正是本文要拆的核心。

二、context-mode 是什么：卡在 MCP 协议层的沙箱

context-mode 本质是一个 MCP server，用 TypeScript 写成，以 npm 包形式分发（包名 context-mode）。它的关键设计判断是：上下文优化应该发生在数据源头，而不是在一个按席位收费的云端看板后面。所以整个工具跑在你本机，没有遥测、没有云同步、不需要账号，你的代码、提示词、会话数据全在本地。

它在 MCP 协议层拦截工具调用：读大文件、跑海量输出命令、抓网页时，不把原始数据灌进上下文窗口，而是丢进隔离子进程沙箱处理，只把"结果"放回对话。README 的原话是：原始数据留在沙箱里，永远不进你的上下文窗口。

这个分层很值得一说。它不是简单的"CLI 输出过滤器"，也不是把日志发到云上做分析的仪表盘。它是在模型真正看到数据之前，先做一次就地蒸馏。这一点也决定了它的许可证选择——后面第六节会专门谈 ELv2 意味着什么。

三、四大能力逐条拆

README 把 context-mode 解决的四个面拆得很清楚，我们逐条转述并加判断。

第一，上下文节省（Context Saving）。沙箱工具把原始数据拦在上下文窗口之外。README 给出的总账是：一次完整会话里 315 KB 原始输出被压成 5.4 KB，降幅 98%。它不靠模型自己"精简"，而是从架构上就不让原始数据进来。

第二，会话连续性（Session Continuity）。每一次文件编辑、git 操作、任务、错误、用户决策都被记进 SQLite。当对话压缩时，context-mode 不把这些数据原样倒回上下文，而是用 FTS5 建立全文索引，再用 BM25 检索只把相关的那部分取回来。模型能精确接着你上次停的地方往下走。这里有个如实说明的边界：如果你不 --continue，上一会话的数据会被立即删除，干净起步。

第三，用代码思考（Think in Code）。LLM 应该"写程序去做分析"，而不是"自己读数据去算"。与其把 50 个文件读进上下文去数函数，不如让 agent 写脚本去数，只 console.log 结果。一个脚本顶十个工具调用，省下 100 倍上下文。README 强调这是横跨全部 17 个客户端的强制范式：别把 LLM 当数据处理器，把它当代码生成器。

第四，不强加文风。context-mode 把原始数据挡在外面，但绝不规定模型最终答案怎么写；简练还是完整、什么格式，交给模型或你自己的 CLAUDE.md / AGENTS.md。README 还引用证据：过度简练的提示反而拉低编码与推理基准，所以路由块只管"数据去哪"，不管"模型怎么说话"。

四、沙箱与知识库：怎么做到 315 KB 变 5.4 KB

光看卖点不够，落到实现才有说服力。context-mode 的两台引擎是"沙箱执行"和"SQLite 知识库"，我们分头看。

沙箱侧，每一次 ctx_execute 调用都会拉起一个带独立进程边界的子进程，脚本之间互相碰不到对方的内存和状态。子进程跑你的代码、捕获 stdout，只有 stdout 进对话上下文，原始数据（日志、API 响应、快照）永远不离开沙箱。它支持 12 种语言运行时：JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir、C#；如果检测到 Bun，JS/TS 执行还能快 3 到 5 倍。已认证的 CLI（gh、aws、gcloud、kubectl、docker）通过凭据透传工作，继承环境变量和配置路径，但绝不明文暴露给对话。当输出超过 5 KB 且带了 intent 时，它切换到"意图驱动过滤"：把完整输出建索引，只搜出和你意图相关的片段。

知识库侧，用的是 SQLite FTS5 全文检索表，底层自动选择：bun:sqlite、node:sqlite（Node 22.5+）或 better-sqlite3。检索用 BM25 排序，索引时做 Porter 词干还原（"running""runs""ran"归一词干），标题权重是正文 5 倍。更进一步，它用 Reciprocal Rank Fusion 把"词干匹配"和"三元组子串匹配"两条策略的排名融合，再用邻近重排把多词查询里挨得近的结果顶上去，还用 Levenshtein 距离做拼写纠错（"kuberntes"自动变为"kubernetes"）。检索结果用智能片段而非截断，只回你查询词附近的窗口。

README 的基准表给了直观感受（以下数字均来自 README 的 Benchmarks 章节，未经我方复核）：

单次会话维度，315 KB 原始输出压到 5.4 KB，会话时长从约 30 分钟拉长到约 3 小时。注意这些数字来自 README 自报基准，属于项目方口径，读者应自行验证后再作为采购依据。

五、会话连续性：压缩之后还能接得上

这是 context-mode 最容易被低估的一块。上下文窗口满了，agent 会做 compact 丢掉旧消息来腾地方；没有会话追踪，模型就忘了自己在改哪个文件、哪些任务在进行、哪些错误已解决、你最后要什么。

context-mode 的做法是：把会话里每一个有意义的事件都捕获下来，存进按项目隔离的 SQLite。压缩发生（或你用 --continue / --resume 续上）时，工作态自动重建，模型从你最后一句提示继续，不用你重复任何事。它靠 5 类 hook 协同工作：PreToolUse（执行前强制走沙箱）、PostToolUse（捕获每次工具调用后的事件）、UserPromptSubmit（捕获你的决策和纠正）、Stop（捕获助手轮次结尾态）、PreCompact（压缩前建快照）、SessionStart（压缩或续接后恢复状态）。

捕获的事件分了优先级，从文件、任务、计划、规则、用户提示、决策、git、错误、约束、阻塞、环境、子代理发现到迭代循环、延迟、MCP 工具、技能、外部引用，细到"同一个工具被相似输入调了 3 次以上"都算重试检测。压缩时按优先级分层建一个不超过 2 KB 的 XML 快照，预算紧就先丢低优先级，但活动文件、任务、规则、决策这些关键态永远保留。压缩后模型拿到的"会话指引"有 15 个类别：最后请求、任务清单、计划、关键决策、改动过的文件、未解决错误、约束、阻塞、git、项目规则、用过的 MCP 工具、子代理任务、技能、被拒方案、外部引用。

平台覆盖上，README 列出多达 17 个受支持客户端（Claude Code、Qwen Code、Gemini CLI、VS Code / JetBrains Copilot、GitHub Copilot CLI、Cursor、OpenCode、KiloCode、OpenClaw、Codex CLI、Kimi Code、Antigravity、Kiro、Zed、Pi、OMP 等）。但完整会话连续性（捕获加快照加恢复）只在 Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、OpenCode、KiloCode 这一档；Cursor 因为 sessionStart 被自家校验器拒掉，目前只能做到部分覆盖。如果你正在挑 agent，顺手看这篇 Claude Code 与 Cursor、Codex 的横评 会更有体感。

六、上手与用法：安装、路由强制、命令

安装分两类平台：支持 hook 的平台自动强制路由，不支持的就复制一次路由文件。以 Claude Code 为例，官方走插件市场，全自动：

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

重启 Claude Code（或 /reload-plugins）后，跑 /context-mode:ctx-doctor，各项都应显示勾。它一次性注册了全部 6 个 hook 和 11 个 MCP 工具。Gemini CLI、VS Code Copilot、JetBrains Copilot、GitHub Copilot CLI、Cursor 走各自的配置文件加 hook，OpenCode / KiloCode 走 TypeScript 插件，Codex CLI 需要在配置里开 [features].hooks = true。

路由这件事值得单独强调：hook 在程序层面拦截并改写工具调用，把危险、会灌数据的命令在执行前重定向进沙箱；纯指令文件只能"劝"模型，拦不住任何东西。README 对照很直接——开 hook 约省 98%，只靠指令文件约省 60%。一句话：平台支持 hook 就务必开。

日常命令很简单，在任意 AI 会话里直接打字，LLM 自动调对应 MCP 工具：

ctx stats     # 上下文节省、调用次数、会话报告
ctx doctor    # 诊断运行时、hook、FTS5、版本
ctx index     # 把本地文件或目录建索引
ctx search    # 检索已索引内容
ctx upgrade    # 从 GitHub 拉最新、重建、迁移、修 hook
ctx purge     # 永久清空知识库已索引内容

一个最小可跑的例子，把"读 50 个文件数函数"换成"写脚本数"：

// 之前：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'));
`);

如果你关心各家 agent 的免费额度、以及哪家长会话更烧上下文，这篇 AI 编码工具免费额度横评 和这篇 Qoder 加 Qwen3-8 的热点解读 可以和本文互补着看。

七、许可证冷思考：ELv2 到底意味着什么

最后这段必须讲清楚，因为它是 context-mode 和"正宗开源"的分水岭，不能含糊带过。

context-mode 用的是 Elastic License 2.0（ELv2），README 自己写的是 "source-available"（源码可得）而不是 "open source"。截至 2026 年 9 月 18 日 GitHub API 核实，仓库 mksglu/context-mode 累计 23,324 颗星，TypeScript 实现，许可证为 ELv2，仓库创建于 2026-02-23，最近一次 push 在 2026-09-16，属于快速上升期的年轻项目。

ELv2 不是 OSI 认证的开源许可证。它允许你使用、fork、修改、分发；但有两条红线不能碰：第一，不能把它当作托管的、受管理的服务对外提供；第二，不能移除许可证声明。项目方在 README 里直说了选 ELv2 而非 MIT 的理由：MIT 允许别人把代码重新打包成一个竞争的闭源 SaaS，而 ELv2 在保留源码对所有人可得的同时，堵住了这条路。

对使用者这意味着什么，要分人来谈。对个人开发者，平时在自己机器上跑 agent、装 npm 包、接 Claude Code 这类客户端，ELv2 和 MIT 的体感几乎没差——你能用、能改、能学源码，没有费用，也不触发那两条红线。对在公司里用的人，绝大多数内部研发场景也安全，因为红线是"对外提供托管服务"，内部使用、内部工具链集成都不算。真正要小心的有两类：其一，若你公司做"给客户的 AI 编码平台 / agent 托管服务"，把 context-mode 当后端能力对外卖，就踩第一条红线；其二，二次分发须保留许可证声明，不能抹原作者署名与 ELv2 条款。

我的判断：把它当个人和小团队的生产力工具完全没问题，许可证不会挡你；但如果你打算基于它做商业化的托管产品，必须提前和法务确认 ELv2 的边界，或者走商业授权。源码可得但不自由，这是 ELv2 的诚实定位，也是选型评估表上要如实写的一行。

常见问题

问题一：context-mode 和直接让模型"精简输出"有什么区别？

A1：区别在于它在架构层拦数据，而不是靠提示词劝模型。模型自己精简是不可靠的，且 README 引用证据表明过度简练的提示反而拉低编码与推理基准。context-mode 用沙箱让原始数据根本不进上下文窗口，用 FTS5 加 BM25 做按需检索，用"写代码去分析"替代"读数据去算"，从机制上把上下文占用压下来，不依赖模型自律。

问题二：会话压缩后我的工作状态真的能接上吗，会丢什么？

A2：在完整支持的平台（Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、OpenCode、KiloCode）上，它能捕获文件、任务、计划、规则、决策、git、错误、阻塞等关键事件，压缩前建不超过 2 KB 的优先级快照，压缩后重建 15 类"会话指引"，模型从你最后一句提示继续，不用重复交代。但如果你不 --continue，上一会话数据会被立即删除，干净起步；而且 Cursor 等部分平台因 hook 限制，目前做不到压缩后恢复。

问题三：装上之后，我的密钥和安全规则还管用吗？

A3：管用，而且被延伸到了沙箱。你在 Claude Code 的 settings.json 里配的 deny / allow 规则，context-mode 会原样读到并应用到 ctx_execute 等执行工具上，挡 sudo、rm -rf 这类命令。沙箱还有项目边界 containment（越界路径直接拒绝）、网络抓取加固（挡云元数据、内网保留地址）、以及对 mcp__* 工具入参里的 token、密钥做脱敏再落库。权限规则里 deny 永远优先于 allow，项目级规则覆盖全局。

问题四：支持哪些编码 agent，我是 Codex / Cursor / Zed 用户能用吗？

A4：README 列出 17 个受支持客户端，覆盖 Claude Code、Qwen Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、GitHub Copilot CLI、Cursor、OpenCode、KiloCode、OpenClaw、Codex CLI、Kimi Code、Antigravity、Kiro、Zed、Pi、OMP。能用，但体验分档：有 hook 的平台约省 98%，只靠指令文件的约省 60%；Zed 和 Antigravity 当前没有 hook 支持，需要手动复制路由文件，且压缩后恢复不可用。选平台时优先挑带 hook 的那一档。

问题五：ELv2 不是开源，我公司和我在个人项目里用有风险吗？

A5：对绝大多数人没风险。ELv2 允许你使用、fork、修改、分发，红线只有两条：不能把它当托管服务对外提供，不能移除许可证声明。个人机器上跑、公司内部研发集成都不踩线。真正要谨慎的是做商业化 AI 编码托管产品、把 context-mode 当后端能力对外卖的场景，那会触发第一条红线，需要和法务确认边界或拿商业授权。源码可得但不自由，这是选型时要如实写进评估表的一点。