它解决的问题

普通 MCP 工具会把原始数据直接放进上下文：一份 Playwright 快照约 56 KB，20 个 GitHub issue 约 59 KB，一份访问日志约 45 KB。会话进行一段时间后，大量窗口被工具输出占用；压缩又可能让模型忘记正在编辑的文件、当前任务、已处理错误和用户最后的要求。

Context Mode 同时处理输入侧的原始数据膨胀、压缩后的会话连续性，以及模型把数据分析过程写成冗长文字所造成的输出浪费。

Context Mode 如何解决

• 上下文节省：让原始数据停留在沙箱中，只返回程序计算或意图检索后的必要结果；项目给出的完整会话示例从 315 KB 降到 5.4 KB。
• 会话连续性：把文件编辑、Git 操作、任务、错误与用户决定记录进 SQLite；压缩后通过 FTS5 与 BM25 只恢复相关状态。
• 用代码思考：让模型编写脚本分析大量文件或数据，只输出结论，而不是把几十份文件逐一读进对话。
• 不强制回答风格：扩展只规定数据如何路由，不要求模型必须简短或采用特定排版。最终表达仍由模型或项目指令决定。

// 之前：47 次 Read，总计约 700 KB
// 之后：1 次 ctx_execute，只返回约 3.6 KB
ctx_execute("javascript", `
  const files = fs.readdirSync("src").filter((f) => f.endsWith(".ts"));
  for (const file of files) {
    const lines = fs.readFileSync("src/" + file, "utf8").split("\n").length;
    console.log(file + ": " + lines + " lines");
  }
`);

在 Pi 中安装

前置要求是 Node.js 22.5+ 或 Bun，并已安装 Pi Coding Agent。Pi 需要同时加载扩展包和 context-mode MCP server。

npm install -g context-mode
pi install npm:context-mode

然后在 ~/.pi/agent/mcp.json（项目级可用 .pi/mcp.json）注册 MCP server：

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

重启 Pi 后输入 ctx stats 验证。扩展会注册 tool_call、tool_result、session_start 和 session_before_compact 生命周期事件，以提供自动路由与较完整的会话恢复。

也可以不使用 pi install，直接在用户级或项目级 Pi settings.json 的 packages 中加入 npm:context-mode。其他客户端的安装方式不同，完整配置以英文原页为准。

工具

沙箱如何工作

每次 ctx_execute 都会启动独立子进程。脚本之间不能访问彼此的内存或状态；日志、API 响应和快照留在沙箱，只有 stdout 进入对话。

支持 JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、R、Elixir 和 C#。认证 CLI 可以透传已有环境和配置路径，而无需把凭据暴露给对话。

输出超过 5 KB 且提供 intent 时，会自动把完整输出索引进知识库，只返回与意图匹配的片段。

知识库如何工作

ctx_index 按 Markdown 标题分块并保持代码块完整，再存入 SQLite FTS5。运行时会自动选择 SQLite 后端：Bun 使用 bun:sqlite，Node.js 22.5+ 使用 node:sqlite，其他环境使用 better-sqlite3。BM25 根据词频、逆文档频率和文档长度评分，标题权重是正文的 5 倍。

Porter 词干处理让 running、runs、ran 等变体可以互相命中；contentType 还能把结果限制为 code 或 prose。URL 抓取会先转换成 Markdown，原始网页不会进入对话。

Reciprocal Rank Fusion 排名

搜索并行运行 Porter 词干匹配和 trigram 子串匹配，再用 RRF 合并两份排名。这样 useEff 可以找到 useEffect，而同时被两种策略命中的文档会排得更高。

邻近度重排

多词查询会再次检查词语距离。例如查询 session continuity 时，两个词相邻的段落会高于分散在不同段落的页面。

模糊纠错

当查询包含拼写错误时，Levenshtein 距离会尝试纠正后重新搜索，例如把 kuberntes 纠正为 kubernetes。

智能片段

结果不会简单截取文档开头，而是定位查询词，返回围绕命中位置的真实内容窗口。

TTL 缓存

• 每个项目的索引存放在 ~/.context-mode/content/；URL 默认 TTL 为 24 小时，也可逐次传入毫秒值。
• TTL 内命中时不再抓取，只返回约 0.3 KB 的缓存提示并继续搜索现有索引；过期后会静默重新抓取。
• ttl: 0 或 force: true 会跳过缓存；超过 14 天的内容数据库和来源会在启动时清理。
• ctx_stats 会分别报告缓存命中、避免传入的数据量、节省的网络请求和总上下文节省。

渐进式节流

会话连续性

Context Mode 把有意义的会话事件保存在每个项目的 SQLite 数据库中。发生压缩，或用 --continue、--resume、/resume 恢复时，它会重建当前工作状态，而不是把全部历史重新塞回上下文。

关键 hook 分别负责执行前路由、执行后捕获、用户输入、turn 结束、压缩前快照和会话恢复。新开会话而不继续旧会话时，旧 session 数据会清理，让新会话保持干净。

平台兼容性

项目列出了 18 个客户端。所有列出的客户端都能接入 MCP server 或原生工具，但 hook、自动路由、参数改写、工具阻止和会话恢复的覆盖程度不同。

Pi 通过扩展事件支持 tool_call、tool_result、session_start 和 session_before_compact，属于高覆盖；默认 Ctrl+O 可折叠或展开工具输出。各平台的具体版本和配置差异请以英文原页的兼容矩阵为准。

路由强制

支持 hook 的平台可以在工具执行前拦截高体积或危险调用，并把它们重定向到沙箱。说明文件只能提示模型，不能真正阻止工具，因此有 hook 时应优先启用。

项目已经停止在首次启动时自动向仓库写入路由说明，以免污染 Git 工作树。支持 hook 的平台改为在运行时注入或执行路由；不支持 hook 的平台仍需手动复制对应的 AGENTS.md、GEMINI.md 等文件。

实用命令

ctx stats       → 查看节省量、调用次数与会话报告
ctx doctor      → 检查运行时、hook、FTS5 与版本
ctx index       → 索引本地文件或目录
ctx search      → 搜索已有索引
ctx upgrade     → 更新、重建并重新配置 hook
ctx purge       → 永久删除全部索引内容
ctx insight     → 在浏览器打开托管的 Insight 仪表盘

这些指令可直接在 AI 会话中输入，由模型调用对应 MCP 工具。也可以在终端运行 context-mode doctor、context-mode index、context-mode search、context-mode upgrade 和 context-mode insight。

基准结果

项目的完整会话测试把 315 KB 原始输出压缩为约 5.4 KB，并声称把约 30 分钟的可用会话延长到约 3 小时。数据来自项目自身基准，实际效果取决于任务、路由与检索命中情况。

快速体验

可以用下面几类任务验证效果，并在完成后运行 ctx stats 查看节省量：

• 深度研究一个大型 GitHub 仓库的架构、技术栈、贡献者、issue 与近期活动。
• 抓取网页或文档并建立索引，再用多组查询检索细节。
• 分析大体积日志、CSV、Git 历史或测试输出，只返回统计与异常。
• 执行多步骤 REST API 开发，在 20 次以上工具调用及会话压缩后检查任务、文件和决定是否能恢复。

隐私与架构

Context Mode 工作在 MCP 协议层，不是简单的 CLI 输出过滤器，也不是云端分析后台。网页、API 响应、文件、浏览器快照和日志都在本地隔离进程中处理。

项目声明没有遥测、云同步、使用追踪或账户要求；代码、提示词和会话数据都留在本机，SQLite 数据库也位于用户目录。

安全

沙箱继承已有权限规则。例如禁止 sudo、读取 .env 或危险删除后，ctx_execute、ctx_execute_file 和 ctx_batch_execute 中的对应操作也会被阻止。命令链会按 &&、; 和 | 拆分检查，deny 永远优先于 allow。

项目边界限制

ctx_execute_file 默认限制在项目根目录。绝对路径、../../ 穿越，或指向项目外部的符号链接都会被拒绝。确有需要时，可在宿主的 Read allow 规则中显式允许目标路径。

网络抓取加固

• 抓取会限制协议与重定向，避免把本地文件或不安全目标当作普通网页处理。
• 外部 MCP 的大载荷可由路由提示引导进入 ctx_execute，避免直接污染上下文。
• 未配置权限规则时扩展不会额外改变现有行为；安全策略使用 Claude Code 的 settings 格式，Codex CLI 还需要对应 hook 配置。

存储与路由环境变量

缓存、会话状态和索引默认放在用户目录下，并按平台与项目隔离。需要自定义部署时，可以使用项目提供的存储根目录、会话数据库、内容索引和统计文件相关环境变量。

路由相关环境变量可调整大输出阈值、外部 MCP 提示频率等行为。例如外部 MCP 路由提示默认每 10 次匹配调用重新注入一次，可在 1–100 之间调整；设为 1 会最积极，但每次调用都会增加少量提示 token。变量名称与默认值可能随版本变化，配置前应查看英文原页。

参与贡献

git clone https://github.com/mksglu/context-mode.git
cd context-mode
npm install
npm test

项目的 CONTRIBUTING.md 说明了开发流程与测试驱动开发要求。

许可

项目采用 Elastic License 2.0，是 source-available 许可：允许使用、fork、修改和分发，但不能把它作为托管或代管服务提供，也不能删除许可声明。