对我来说，不学习，毋宁死。——罗蒙诺索夫

Context Mode：让 AI 编程助手把上下文留给真正重要的事

项目地址：https://github.com/mksglu/context-mode

当 AI 编程助手开始参与更长、更复杂的开发任务时，一个看似安静的问题往往会悄悄浮出水面：上下文窗口正在被大量原始工具输出一点点吞没。

一次网页快照、一串访问日志、一批 GitHub Issue、几十个文件的连续读取，都会把大量未经整理的数据送进对话上下文。它们像不断涌入房间的纸箱，刚开始似乎无伤大雅，时间一长，真正需要被记住的目标、决策、错误、修改和推理路径，反而容易被挤到角落。

Context Mode 正是为这类问题而来。它将自己定义为上下文问题的另一半，专注于为 AI 编程代理优化上下文窗口：把高噪声、重输出的工具工作放进沙箱，把重要的会话轨迹持续保存下来，并通过 MCP 与 Hooks 为多种平台建立工具调用的路由机制。

它不是要替模型决定答案应该写得简短还是详细，也不试图规定最终表达的风格。它更像一位守在上下文入口处的调度员：该留下的留下，该转移的转移，让模型的注意力能够回到真正需要思考的问题上。

上下文窗口为什么会越来越拥挤

AI 编程代理工作的过程，本质上是不断调用工具、读取结果、再决定下一步的过程。

读取文件、搜索代码、获取网页、查看日志、执行命令，这些动作本身都很有价值。但工具往往会返回原始输出，而原始输出并不总是适合完整进入模型上下文。

README 中列出了几个直观的场景：

  • 一份 Playwright 快照可能占用 56 KB
  • 二十个 GitHub Issue 可能占用 59 KB
  • 一份访问日志可能占用 45 KB
  • 长时间工作后，大量工具输出会逐渐占据上下文空间

这类消耗并不一定来自复杂的推理，而是来自信息搬运。模型为了完成一个统计、筛选、检索或比对任务，可能先把大量文件内容读进上下文，再从中提取一个很小的结论。

Context Mode 的核心思路很直接：不要把所有原始材料都搬进对话里。能在沙箱中完成的工作，就让沙箱完成；能被索引保存的内容，就让知识库保存；能通过代码计算的结果，就不要让模型逐行阅读后手工计算。

四个方向，重新整理上下文的流动方式

Context Mode 从四个方向处理上下文压力。

把原始工具输出留在沙箱里

第一件事，是减少原始数据直接进入上下文窗口的机会。

README 中给出的数据非常鲜明：315 KB 的数据可以被压缩为 5.4 KB 的上下文结果，对应约 98% 的减少。

这里的重点不是让信息消失，而是改变信息进入模型的方式。模型不必反复面对完整的原始输出，而是获得经过执行、筛选、汇总后的结果。大量字节不再挤占对话空间，真正有用的结论则能够更轻地进入后续推理。

这让上下文不再像一个无差别堆放的仓库，而更像一张经过整理的工作台。

让会话记忆能够跨越压缩继续存在

长会话并不只是工具调用的集合。文件编辑、Git 操作、任务进展、错误信息、用户决策，都会共同构成一条持续推进的工作轨迹。

Context Mode 会将这些信息记录到 SQLite 中。当会话发生压缩时，它不会把所有历史原始数据重新倾倒回上下文，而是依靠已记录的会话信息恢复连续性。

这意味着，代理不必每次都从一片模糊的历史中重新寻找线索。它可以延续此前的工作节奏，知道已经做过什么、遇到过什么、哪些方向已经被排除、哪些决定已经形成。

对于长时间运行的编程任务来说，这种连续性很重要。真正困难的往往不是开始做一件事，而是在多轮工具调用、文件修改和上下文压缩之后，仍然不偏离原先的问题。

让模型用代码思考，而不是用上下文硬算

Context Mode 提出了一条非常鲜明的原则：模型应该编写分析程序，而不是把计算工作全部塞进上下文。

例如，若要统计一个目录中多个 TypeScript 文件的行数，传统方式可能是逐个读取大量文件，再由模型在上下文中理解和汇总。Context Mode 更希望代理编写一段脚本，在沙箱中完成读取与统计，只将结果输出回来。

1
2
3
4
5
6
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'
  ));
`);

README 中给出的对比是，47 次读取操作可能带来 700 KB 上下文消耗，而一次 ctx_execute 调用的输出可能只有 3.6 KB。

这背后是一种很朴素的工作方式：把重复、机械、适合程序完成的任务交给程序；把判断、规划、解释和决策留给模型。

当代理不必在上下文中抱着几十份文件做统计时，上下文窗口也就不再被低价值的中间材料占满。

不干预最终答案的表达方式

Context Mode 的目标是减少原始数据造成的上下文压力，而不是约束模型最后应该如何说话。

它不会强制模型必须简洁，也不会要求回答必须采用特定格式。完整程度、篇幅、结构与表达风格，仍然由模型决定。

这使得它的职责边界非常清楚：它管理的是数据进入上下文的路径，而不是替模型接管最终回答。

一个 MCP Server，也是一套工具调用机制

Context Mode 以 MCP Server 的形式工作，并结合 Hooks 形成更完整的上下文保护流程。

它提供了多个 ctx_* 工具，覆盖代码执行、批量执行、内容索引、知识库搜索、网页获取与索引、统计、诊断、升级、清理和仪表盘等工作。

其中最具代表性的能力包括：

工具 作用
ctx_execute 在多种语言中执行代码，只返回标准输出
ctx_execute_file 从工作区文件路径读取输入后执行代码
ctx_batch_execute 在一次调用中执行多个命令，并自动索引输出
ctx_index 将文本以标签形式存入 FTS5 知识库
ctx_search 在知识库中使用 BM25 排名进行搜索
ctx_fetch_and_index 获取网页内容、去除 HTML 后写入索引
ctx_stats 查看知识库大小、命中情况和主要来源
ctx_doctor 检查运行环境与 Hook 健康状态
ctx_upgrade 应用待处理修复
ctx_purge 清空知识库
ctx_insight 启动仪表盘服务

这些工具共同构成了一套面向长期代理任务的工作台。

执行类工具负责把重计算、重读取、重输出的任务放入沙箱。

索引与搜索类工具负责让已经获取过的信息能够被保存和再次检索，而不是每次都重新抓取、重新读取、重新塞入上下文。

诊断与统计类工具则让上下文节省情况、运行时状态、Hook 配置和知识库使用情况变得可见。

沙箱执行：让输出变轻，让分析更接近程序

Context Mode 支持在 11 种语言中运行代码，包括：

  • Node
  • Python
  • Bun
  • Deno
  • Ruby
  • Go
  • Rust
  • Java
  • C
  • C++
  • Shell

它的关键约束是，进入上下文的是标准输出，而不是全部执行过程中的原始材料。

这种机制尤其适合处理以下类型的任务：

  • 对多个文件进行统计
  • 从大量文本中提取符合条件的记录
  • 对目录结构进行汇总
  • 批量分析代码内容
  • 对命令输出进行二次过滤
  • 将分散信息转换为短小、明确的结果

如果模型需要知道的是某个目录里有哪些 TypeScript 文件、每个文件有多少行、是否存在某个模式，那么最合适的路径并不是把所有文件全文读进对话，而是让代码完成读取和分析，再把结论交给模型。

这就是 Think in Code 的含义：不是用上下文模拟程序，而是让程序承担程序本该承担的工作。

FTS5 知识库：让已经得到的信息不必反复重来

Context Mode 使用 SQLite FTS5 保存内容，并通过 BM25 排名进行检索。

它可以把研究资料、命令输出和网页内容存进本地知识库。当代理后续需要回忆某份内容时，可以通过搜索来找回，而不是重新读取全部原始信息。

这种方式为长会话提供了另一层稳定性。

会话中经常会出现这样的情况：前面已经查过一段文档、跑过一条命令、读过一批输出，但任务推进到后面时，又需要回到当初的某个细节。如果所有信息都只能依靠对话上下文保存，那么随着窗口被压缩，先前的内容很容易变得难以访问。

知识库则像一座有索引的资料室。内容被放进去之后，代理可以用搜索重新定位，而不是靠记忆猜测它曾经出现在哪里。

ctx_index 用于写入文本，ctx_search 用于检索，ctx_fetch_and_index 则将网页获取、HTML 清理和索引保存串联起来。它们让信息从一次性工具输出，变成可以持续使用的可检索材料。

Hooks：在工具调用前后建立上下文秩序

单纯提供工具，并不一定能保证模型每次都优先使用这些工具。

因此，Context Mode 还借助 Hooks 在工具调用生命周期中参与路由、记录和恢复。

不同平台的 Hook 能力各不相同，但整体目标是一致的：

  • 在高输出工具调用前进行路由引导或拦截
  • 在工具调用后记录输入和输出
  • 在会话开始时注入路由规则
  • 在上下文压缩前保存恢复所需的信息
  • 在会话结束时记录生命周期状态

以 Cursor 插件为例，README 描述了五类事件：

事件 行为
preToolUse 匹配 Shell、Read、Grep、WebFetch、Task 与 ctx_* 工具，并给出路由引导，让重 I/O 工作保持在沙箱中
postToolUse 将工具输入与输出保存到会话数据库，以便恢复
sessionStart 注入路由规则，并在恢复或压缩后的会话中继续此前状态
afterAgentResponse 记录生成的助手文本到会话遥测信息中
stop 记录轮次生命周期信息，包括状态与循环次数

Hooks 的存在，让 Context Mode 不只是一个等待调用的工具集合，也能够成为工具使用流程中的一层协调机制。

它关注的不只是某一次执行是否完成，也关注这次执行会给会话带来多少上下文负担，以及如何让这段工作在之后仍然可追溯、可恢复。

多平台支持，围绕 MCP 与路由机制展开

Context Mode 的 description 明确指出，它通过 MCP 与 Hooks 在 17 个平台上执行路由机制。

README 列出了多个安装与配置入口，覆盖 Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、GitHub Copilot CLI、Cursor、OpenCode、KiloCode、OpenClaw、Codex CLI、Kimi Code、Qwen Code、Antigravity IDE、Antigravity CLI、Kiro、Zed、Pi Coding Agent 等环境。

不同平台的集成深度并不完全相同。

具备 Hook 能力的平台可以通过会话开始、工具调用前后、压缩前后等事件实现更自动化的路由与记录。

没有 Hook 支持的平台，则可以通过 MCP 配置和路由说明文件建立手动的工作约束。

这种差异并不改变 Context Mode 的核心目标：尽可能让大规模原始工具输出停留在沙箱中，让模型获得更轻、更适合继续推理的信息。

GitHub Copilot CLI 中的一键安装方式

对于 GitHub Copilot CLI，Context Mode 提供了插件安装路径。

先安装全局二进制：

1
npm install -g context-mode

再安装 Copilot CLI 插件：

1
copilot plugin install mksglu/context-mode:configs/copilot-cli

该插件会注册 MCP Server、路由技能与捕获 Hooks。

其中 MCP Server 提供 ctx_execute、ctx_batch_execute、ctx_search、ctx_fetch_and_index 等 ctx_* 工具。

路由技能承载 Think in Code 规则，用于减少原始字节直接进入上下文窗口。

捕获 Hooks 覆盖 preToolUse、postToolUse、sessionStart、userPromptSubmitted、agentStop 和 preCompact 等事件，用于在 Copilot CLI 的工作流中处理工具调用路由、会话记录与压缩前准备。

也可以使用不安装插件的方式注册 MCP Server：

1
copilot mcp add context-mode --env CONTEXT_MODE_PLATFORM=copilot-cli -- context-mode

如果还需要安装捕获 Hooks，可以在 Copilot 环境中调用升级工具：

1
copilot -p "Use the context-mode ctx_upgrade tool to install context-mode's hooks." --allow-all

Claude Code 中的自动化接入

Claude Code 的安装方式采用插件市场路径：

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

安装完成后，可以重启 Claude Code，或者执行：

1
/reload-plugins

随后通过下面的命令进行诊断：

1
/context-mode:ctx-doctor

README 中说明，诊断会检查运行时、Hooks、FTS5 和插件注册状态。

Claude Code 还提供了多个斜杠命令：

命令 作用
/context-mode:ctx-stats 查看工具级别的上下文节省、消耗与节省比例
/context-mode:ctx-doctor 查看运行时、Hooks、FTS5、插件注册与版本诊断
/context-mode:ctx-index 将本地文件或目录写入持久化 FTS5 知识库
/context-mode:ctx-search 搜索此前索引过的内容
/context-mode:ctx-upgrade 拉取更新、重建、迁移缓存并修复 Hooks
/context-mode:ctx-purge 永久删除知识库中的全部已索引内容
/context-mode:ctx-insight 打开 Insight 仪表盘

Claude Code 的 SessionStart Hook 会在运行时注入路由说明，因此不需要把路由文件写入项目目录。

VS Code Copilot 中的配置方式

在 VS Code Copilot 环境中，首先需要全局安装：

1
npm install -g context-mode

然后在项目根目录创建 .vscode/mcp.json：

1
2
3
4
5
6
7
{
  "servers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

再创建 .github/hooks/context-mode.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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 中输入：

1
ctx stats

如果工具正常出现并响应，说明 Context Mode 已经进入会话。

README 还提供了用于增强模型路由感知的说明文件复制方式：

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

Cursor 中的本地插件路径

Context Mode 为 Cursor 提供了插件与手动配置两种思路。

在插件市场正式可用前，可以通过本地目录安装。

Windows PowerShell 环境可以使用：

1
2
3
4
5
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 环境可以使用：

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

在 Cursor 中，插件会涉及 MCP、Skills 与 Hooks。README 描述其可注册 MCP Server、多个技能以及多个 Hook 事件。

对于 Cursor 的会话上下文保护而言，preToolUse 可以面向 Shell、Read、Grep、WebFetch 等高输出工具执行路由处理，postToolUse 负责记录工具信息，sessionStart 用于注入规则与恢复状态，stop 则能够记录轮次生命周期。

这套机制让 Cursor 中持续运行的代理任务不必任由工具输出无限涌入对话。

统计与诊断，让节省变得可见

上下文优化如果只是一个不可见的内部过程，很难让使用者判断它是否真正发挥作用。

Context Mode 提供 ctx_stats 来展示上下文节省情况，也提供 ctx_doctor 来诊断运行环境、Hook 与 MCP 注册状态。

在 Claude Code 中，状态栏还可以配置为调用：

1
2
3
4
5
6
{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

README 描述，该状态栏会显示本次会话节省量、跨会话节省量与效率比例，让节省过程能够在工作中持续累积、持续可见。

当上下文不再只是一个抽象上限，而能够被统计、被诊断、被观察时，代理工具的工作方式也会更加清晰。

Context Mode 想解决的，不只是容量问题

从表面看，Context Mode 在处理上下文窗口的容量压力。

但它更深层的价值，在于重新划分 AI 编程代理与工具之间的职责。

模型不应把每份原始数据都背在身上。

工具不应只是返回冗长输出的管道。

脚本不应只用于最后一步自动化，而应该参与分析过程。

会话记忆不应随着上下文压缩而被迫遗失。

知识不应只存在于短暂的一轮对话中，而应该能够被索引、检索与复用。

Context Mode 把这些想法放进了同一个工作流里：用沙箱承接重输出，用代码完成可编程分析，用 SQLite 保存会话轨迹，用 FTS5 组织可检索信息，再用 MCP 与 Hooks 建立工具调用的路由秩序。

它让 AI 编程代理面对长任务时，不必把上下文窗口变成一间堆满原始输出的仓库。

更理想的状态是，代理仍然拥有足够的空间去理解问题、维持方向、回顾决策、组织行动，并在漫长的开发路径中持续向前。