Plugin Context-Mode 沙箱化工具输出给AI省下上下文

一、项目介绍

用 Agent 干活的人都吃过同一种亏：工具每返回一次原始数据，就往上下文窗口里塞进几十 KB。一次 Playwright 快照约 56 KB，二十条 GitHub issue 约 59 KB，一段访问日志 45 KB。半小时下来，40% 的上下文被工具输出吃掉；更糟的是，当 Agent 压缩对话腾空间时，它会连带忘掉自己正在改哪些文件、有哪些任务没做完、你上一句到底问了什么。

Context-Mode 解决的正是这"上下文的另一半"。它把工具输出放进沙箱执行并落盘，主上下文里只留一个可检索的句柄，配合本地 FTS5 全文索引，需要时再按需取回。项目方给出的数字是工具输出削减约 98%，且压缩时不再丢失工作状态。这个项目曾登上 Hacker News 首页第一，star 数约 3.29 万。

它以插件形态接入 Claude Code，同时提供 11 个 MCP 工具——六个沙箱类（批量执行、单条执行、执行文件、索引、检索、抓取并索引），五个元工具（统计、诊断、升级、清理、洞察）。对 Cursor 这类没有完整 hook 的客户端，则提供一次性路由文件方案。

要理解 Context-Mode 的设计，得先接受一个前提：上下文窗口不是无限的，而工具输出是海量的。一次网页快照、一次日志读取、一次批量 issue 拉取，动辄就是几十 KB 的原始文本。传统做法要么截断（信息丢了，Agent 没法基于被截断的内容做判断），要么原样塞进上下文（窗口被挤爆，真正的需求描述反而被挤出去）。

Context-Mode 的做法是把"执行"与"呈现"分开。工具在沙箱里跑，输出落到磁盘；主上下文里留下的只是一个句柄，配合本地 FTS5 索引，需要时用检索把相关片段取回。这样一来，Agent 的上下文里存的是"这件事的结论与位置"，而不是"这件事的原始字节"。

它对压缩场景的专门处理更值得注意。PreCompact 这个 hook 在上下文被压缩之前触发，把正在进行的任务状态固化下来；PreToolUse 与 PostToolUse 则负责在工具调用前后做路由与清理。这套 hook 链在 Claude Code 上是全自动的，SessionStart 时注入路由规则，不用往项目里写任何文件——这意味着加装这个插件不会污染你的代码库。

11 个 MCP 工具的划分也体现了它的思路：六个沙箱类负责执行与检索，五个元工具负责自检与运维。ctx-doctor 一次性告诉你运行时、hook、FTS5、插件注册四项是否正常，ctx-stats 告诉你省了多少——这类"可观测"设计在插件类工具里并不常见，却恰恰是判断它到底有没有生效的关键。

二、项目基本信息

三、核心优势

• 沙箱执行 + 落盘持久化，主上下文只留索引句柄，工具输出不再直接冲刷窗口
• 本地 FTS5 全文索引，支持按需检索已索引内容，而不是重新拉一遍
• /context-mode:ctx-doctor 一键诊断运行时会、hook、FTS5 与插件注册状态，安装问题一眼定位
• /context-mode:ctx-stats 按工具给出 token 消耗与节省比例，节省了多少看得见
• 覆盖 PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop 六类 hook，在压缩前先固化状态
• 同一套 MCP 工具可直接挂到 Cursor 等非 hook 客户端，用 .cursor/mcp.json 与 hooks.json 接入
• 抓取类工具（fetch_and_index）能把网络内容一并落盘索引，省去重复请求同一批网页的成本
• ctx-insight 提供对索引内容的洞察能力，便于判断哪些资料真正被用到
• 提供升级（upgrade）与清理（purge）命令，缓存与索引的生命周期可控
• 非 hook 客户端有专门的路由文件方案，不必为了用插件而更换主力 Agent

四、适用场景

适合把 Agent 用于真实项目、且工具输出频繁把上下文吃满的开发者与团队；特别适合跑浏览器自动化、日志分析、批量 issue 处理的场景。若你已经频繁遇到"Agent 忘记自己在改什么"，这个插件针对的就是那个具体故障。

值不值得装，取决于你的 Agent 是不是真的被工具输出拖累。可以先观察两个信号：一是长任务跑到一半 Agent 开始"忘事"，反复问你之前说过什么；二是上下文快满时它开始频繁压缩，导致刚改的文件路径都记不住。出现其中任一情况，装它通常有明显收益。

反过来说，如果你的任务都很短、工具调用很少、输出也小，那它带来的收益有限，反而是多装一个插件带来的排查成本。

还有一个现实提醒：不同客户端的收益差异很大。Claude Code 上有完整 hook 链，压缩前的状态保护、自动路由都能生效；Cursor 等没有完整 hook 的平台需要手动复制一次路由文件，压缩保护会弱一些。如果你主力用 Claude Code，这个插件基本是开箱即用；如果主力用别的客户端，建议先按 README 里的手动方案试一轮再决定。

如果你正被同类问题反复绊住——要么是人肉重复劳动没完，要么是工具装不上跑不通、要么是产出的结果根本没法用——那这个项目值得先花十分钟装一遍试试。

五、安装教程

当前最新版本 v1.0.169。下面是可直接执行的安装方式：

# 方式一：Claude Code 插件市场（推荐，全自动，依赖 Claude Code v1.0.33+）
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

# 重启 Claude Code，或执行 /reload-plugins

# 方式二：全局安装 + 手动配置（适用于 Cursor 等非 hook 客户端）
npm install -g context-mode

常见报错与处理：依赖缺失时先确认运行时版本（Node、Python、Rust、PHP 等）是否满足项目要求；网络超时多半是镜像或代理问题，可换源重试；权限类报错请检查当前账号是否已登录对应平台，以及脚本是否需要管理员权限执行。

六、使用示例

下面这段是可以直接参照的真实用法：

# 校验安装：所有检查项应显示为通过
/context-mode:ctx-doctor

# 查看上下文节省情况（按工具分解 token 消耗与节省比例）
/context-mode:ctx-stats

# 把本地文件或目录索引进持久化 FTS5 知识库
/context-mode:ctx-index

# 检索此前索引的内容
/context-mode:ctx-search

# Cursor 等客户端的 MCP 配置：项目根目录 .cursor/mcp.json
{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

# 对应的 hook 配置：项目根目录 .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"
      }
    ]
  }
}

七、常见问题

问：/plugin 命令不被识别怎么办？答：说明 Claude Code 版本过低，需要 1.0.33 以上，可执行 brew upgrade claude-code 或 npm update -g @anthropic-ai/claude-code 后重试。

问：非 hook 平台为什么效果会打折？答：没有完整 hook 链时无法在压缩前固化状态，需要手动复制一次路由文件，压缩时的状态保护会弱一些。

问：索引的数据存在哪里？答：存在本地，用的是内置 FTS5 全文索引，不依赖外部服务；用 /context-mode:ctx-purge 可以清理。

问：和简单的"截断输出"有什么区别？答：截断只是丢数据，而 Context-Mode 是把输出落到沙箱并建立可检索索引，需要时还能按需取回完整内容，同时保住 Agent 的任务状态。

问：会占用多少磁盘？答：工具输出与索引都存在本地，具体占用取决于你索引的内容量，可用 purge 命令清理。

问：会影响原有工具的行为吗？答：路由机制会把符合条件的调用转到沙箱执行路径，行为上做了兼容，但建议刚装上时留意一次实际任务的输出是否完整。

以上是实际使用中最常被问到的几个问题。若遇到文档未覆盖的情况，可以先翻项目的 Issues 与 Discussions 区，那里有更多真实踩坑记录。

八、总结

Context-Mode 在把重复流程沉淀成可复用的能力这件事上做到了足够扎实的程度：它不追求大而全，而是把一个具体环节做透，让原本要靠人盯的流程变成可以交给工具执行的流程。

从上面的安装步骤和使用示例可以看出，它的接入成本并不高：一条命令装好，按提示完成配置，然后就能把它放进你原有的工作流里。如果你正在被同类问题困扰，不妨先在自己的一小块任务上试一轮，确认顺手了再推广到日常流程中。