Context Mode 新手教程

1这是什么

Context Mode（作者 mksglu / Mert Koseoğlu，TypeScript 编写）解决的是 AI 编程代理的「上下文问题另一半」。

每次 Agent 调工具，工具都会把原始数据整包塞进上下文窗口：一次 Playwright 页面快照 56 KB、20 个 GitHub issues 59 KB、一份 500 行的 nginx 访问日志 45 KB。半小时下来，40% 的窗口没了；再触发一次自动压缩（compact），Agent 就忘了自己正在改哪个文件、任务进行到哪、你最后一句要求是什么。

Context Mode 的做法是三件套：沙箱让原始数据根本不进窗口，本地索引（SQLite FTS5 + BM25）把大内容存起来按需查，hooks 路由在工具调用前后程序化拦截。官方基准：一整段会话 315 KB 原始输出压到 5.4 KB 进窗口，节省 98%（条件：带 hooks 的平台，数据来自 README 实测场景）。

它不做什么（反向界定）

• 不管文风。第四支柱就叫「No prose-style enforcement」——它只管数据去哪，模型回答简短还是啰嗦，由你自己的 AGENTS.md / CLAUDE.md 决定。
• 不上传数据。无遥测、无云服务，全部存在本机 SQLite。
• 不是普通压缩器。它不摘要全文完事，而是「路由 + 沙箱 + 索引」：需要精确代码示例时走 ctx_index + ctx_search，代码块原样返回（基准测试中 100% 保留）。
• 不能在无 hooks 的平台强制拦截。MCP-only 平台（Zed、Antigravity IDE 等）只能靠指令文件自觉，官方实测约 60% 遵从率。

2为什么需要

在它之前，你已经用过至少三种「省上下文」的办法，但每个都各有失败姿势。

核心洞察：上下文问题的另一半，不是「窗口不够大」，而是原始数据根本不该进窗口。分析一个 200 行文件统计函数行数，1 个脚本胜过 10 次工具调用——把「读数据」变成「编程算数据」，这就是项目说的 Think in Code：

// Before: 47 次 Read() ≈ 700 KB 进上下文
// After:  1 次 ctx_execute() ≈ 3.6 KB，只有 stdout 进窗口
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'));
`);

3核心流程

三步：Agent 想读数据 → hook 拦截重定向 → 窗口里只进摘要。

整个体系由三块组成，对应三个支柱：

• Context Saving（沙箱）：ctx_execute / ctx_execute_file / ctx_batch_execute 在隔离子进程里跑代码，脚本之间内存不互通，只有 stdout 进上下文。支持 12 种语言（JS/TS/Python/Shell/Ruby/Go/Rust/PHP/Perl/R/Elixir/C#），有 Bun 时自动提速 3–5 倍。输出超过 5 KB 且带意图说明时，自动转「意图驱动过滤」——索引全文、按相关段返回。
• Session Continuity（会话记忆）：hooks 抓取文件编辑、git 操作、任务、错误、用户决策存进 SQLite；压缩前生成 ≤2 KB 快照，新会话启动时注入 <session_knowledge>。不 --continue 时上次会话数据立即删除。
• Routing（路由强制）：hooks 是程序，能阻断或重定向工具调用；指令文件只能引导。这正是有 hooks 平台 ~98% 节省、无 hooks 平台只有 ~60% 的原因。

4安装：全局装 + 按宿主接线

无论哪个宿主，第一步都一样：npm install -g context-mode。第二步「接线」因宿主而异。

npm install -g context-mode   # Node >= 22.5.0，装完得到 context-mode 命令

容易混淆的两条路：MCP-only（只注册 MCP server，模型「自愿」用，无 hooks 平台走这条）和 MCP + Hooks（工具调用被程序化拦截，效果拉满）。能用 hooks 就一定配 hooks。

MCP 层 100% 可移植——17 个平台全部支持；差异全在 hooks。完整矩阵见官方 platform-support.md。

5环境自检

装之前花一分钟确认这四件事，能避开绝大多数安装失败。

node -v                      # 必须 >= 22.5.0
npm -v
context-mode --version       # 全局安装成功则输出版本号
npx context-mode doctor      # 装好后跑一次，全绿即接线成功

6第一次实战：Cursor / Cursor CLI 集成

这是本文的重点。Cursor 是 context-mode 官方「一等适配器」（native hooks v1），配置分插件版和手动版两条路。

6.1 先弄清配置体系

Cursor 的 hooks 与 MCP 配置位于 ~/.cursor/（用户级，全局生效）和项目 .cursor/（项目级）。Cursor 桌面端 Agent 与 Cursor CLI（cursor-agent）共用这套配置目录——官方文档按「Cursor 平台」适配，不区分 IDE / CLI；context-mode 用 CURSOR_TRACE_ID、CURSOR_CLI 等环境变量识别当前运行在哪种上下文里。CLI 会话里 hooks 是否触发，装完用 doctor + 实测确认（见 6.5）。

6.2 推荐：手动配置（CLI 用户首选）

Cursor 插件市场版还在审核中。手动配置最稳、全局安装后无 npx 冷启动（插件版冷启动约 4–5 秒）：

# 1. 全局安装
npm install -g context-mode

// 2. 用户级 MCP 注册：~/.cursor/mcp.json（项目级则放 .cursor/mcp.json）
{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

// 3. 用户级 hooks：~/.cursor/hooks.json（项目级则放 .cursor/hooks.json）
// 官方手动版注册 3 个事件；sessionStart 被 Cursor 校验器拒绝，故不写
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "context-mode hook cursor pretooluse",
        "matcher": "Shell|Read|Grep|WebFetch|mcp_web_fetch|mcp_fetch_tool|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute|MCP:(?!ctx_)"
      }
    ],
    "postToolUse": [
      {
        "command": "context-mode hook cursor posttooluse"
      }
    ],
    "stop": [
      {
        "command": "context-mode hook cursor stop"
      }
    ]
  }
}

# 4. 项目级路由规则（关键！Cursor 的 additional_context 注入有 bug，
#    .mdc 规则是当前最可靠的路由引导通道）
MDC="$(npm root -g)/context-mode/configs/cursor/context-mode.mdc"
mkdir -p .cursor/rules
cp "$MDC" .cursor/rules/context-mode.mdc

# 5. 诊断验证
npx context-mode doctor

.mdc 规则带 alwaysApply: true，内容是给模型的硬规矩：分析/统计/过滤数据一律写代码走 ctx_execute；禁止用 Read 做分析（Read 只留给 Edit 前定位）；禁止终端 curl/wget，抓网页走 ctx_fetch_and_index；文件创建修改必须用原生编辑工具，沙箱只做分析不做写入。

6.3 备选：本地插件（一键注册）

不想手写 JSON，可以从仓库直接装本地插件（自动注册 MCP + hooks + 规则 + skills）：

# macOS / Linux：symlink 到 Cursor 本地插件目录
git clone https://github.com/mksglu/context-mode.git
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

# Windows 不跟 symlink，用 robocopy 镜像（官方 README 提供完整命令）
# 重启 Cursor → Settings → Plugins 出现 "Context Mode (Local)"
# 注册内容：1 个 MCP server + 7 个 skills + 5 个 hooks

注意：插件版 hook 命令是 npx -y context-mode hook cursor <event>（免全局安装但冷启动 4–5 秒）；插件注册 5 个事件（多 sessionStart、afterAgentResponse），但 sessionStart 实际会被 Cursor 校验器拒绝。插件版与手动版二选一——两份同时存在时每个事件会触发两次，doctor 会警告 duplicate hook registrations。

6.4 验证

npx context-mode doctor
# 期望输出包含：
#   MCP server registered: pass
#   Hooks configured: 3/3（手动版）或 5/5（插件版）

然后在 Cursor CLI 会话里实测：让它「统计 src 目录下每个文件的行数」。接线正确的话，它应该调 ctx_execute 跑一段脚本而不是连发十几次 Read，结束时用 ctx stats 能看到真实的节省字节数。

6.5 Cursor 平台的三个已知坑（装前必读）

7装完之后：数据都在哪

全部数据落本机，按平台隔离，随时可删。

设计上，存储是「可抛弃的」：删掉目录只会丢索引和会话记忆，重装不丢任何项目代码。ctx purge 一键清空重来。

8怎么用：工具表与命令

装好后你几乎不用「手动」用它——hooks 会引导模型自己调用沙箱工具。但工具表值得过一遍。

会话里可以对模型说 ctx stats、ctx doctor；终端里则直接跑 CLI：

context-mode doctor                                     # 诊断运行时 + hooks 健康度
context-mode index . --source project:my-app            # 把当前项目建入索引
context-mode search "authentication middleware" --source project:my-app
context-mode stats                                      # 看节省了多少
context-mode upgrade                                    # 应用待应用的修复

选型心法（对应官方 Tool Decision Matrix）：要精确代码（文档、API 参考、skills 提示词）→ ctx_index + ctx_search；要统计结论（日志、测试输出、CSV、构建输出）→ ctx_execute_file；输出超过 100 KB 自动外置成 FTS5 指针，不丢数据。

会发生 vs 不会发生：

• ✅ 会发生：Agent 把「读大文件做分析」改写成 ctx_execute 脚本；抓网页自动走 ctx_fetch_and_index；compact 后能恢复任务上下文（有 SessionStart 的平台）；ctx stats 显示真实节省。
• ❌ 不会发生：不改模型文风；不自动改写工具参数（updatedInput 上游未支持，Codex 平台 PreToolUse 只能 deny）；不上传任何数据；在无 hooks 平台不强制拦截。

9进阶：安全与调参

默认配置已经够安全，这三件套是给要上生产环境的人准备的。

权限白名单/黑名单

{
  "permissions": {
    "deny": ["Bash(sudo *)", "Bash(rm -rf /*)", "Read(.env)", "Read(**/.env*)"],
    "allow": ["Bash(git:*)", "Bash(npm:*)"]
  }
}

沙箱有项目边界（containment）：ctx_execute_file 只许碰项目根内文件，越界拒绝；确有需要（如读系统日志）用 Read(/var/log/**) 类 allow 规则显式放行。抓网页默认只走 http/https、禁元数据 IP；设 CTX_FETCH_STRICT=1 再禁掉私有网段。工具入参里的凭证字段持久化前会被红字遮罩。

并发调参

多 URL 抓取、多 API 调用属于 I/O 密集，concurrency 给 4–8；跑测试、构建、lint 或共享状态（端口、锁文件）保持 1。GitHub API 类 gh 调用封顶 4（rate limit）。

环境变量速查

10不止是「省 token」

名字叫 Context Mode，但下面这些场景才是它真正的用武之地。

• 深度仓库研究：一次 subagent 级研究 986 KB → 62 KB（94%），多仓库对比不再是窗口杀手。
• 网页抓取 / 浏览器自动化：Playwright 快照 99% 节省，配合 ctx_fetch_and_index 抓文档站不爆窗。
• 大 JSON API 消费：20 个 GitHub issues 59 KB → 1.1 KB，格式化输出只留关键字段。
• 文档与代码块精确检索：ctx_search 返回完整代码块而非摘要——「useEffect 清理函数」连代码带依赖数组原样回来。
• 会话连续性：compact / 新会话后先 ctx_search(sort: "timeline") 再干活，不用重新交代背景（Cursor 等 sessionStart 受限平台暂不可用）。
• 跨平台统一工作流：17 个平台同一套工具名、同一个 CLI 调度器（context-mode hook <platform> <event>），换宿主不改习惯。

11性能与成本

官方 BENCHMARK.md 的 21 个场景，fixture 全部来自真实工具调用（Playwright、GitHub、nginx、vitest 等），不是合成数据。

两个口径要分清：ctx_execute_file 摘要型 95–100% 节省（数据变成 1–2 行结论）；ctx_index + ctx_search 精确型 50–93%（返回完整原文块，代码示例 100% 原样保留，是为「能写代码」服务）。

一次完整调试会话的全景：7 类工具调用合计 177.1 KB → 10.2 KB，约 45,300 tokens → 2,600 tokens，窗口占用 22.7% → 1.3%（200K 窗口模型）。成本上相当于同样的任务预算下多出约 94% 的窗口给真正的问题。会话时长从「30 分钟后 40% 上下文没了」延长到官方宣称的约 3 小时。125 个自动化测试（执行器 55 / FTS5 34 / MCP 集成 22 / 生态基准 14）全过，可 npm run test:all 复现。

12FAQ / 踩坑

每条都给可执行的解法，来源为官方文档与 issue 讨论。

13许可与合规

Elastic License 2.0（ELv2）——对个人和公司内部使用完全开放，但有一条红线。

• ✅ 可以：自由使用、修改、分发，集成进自己的开发工作流，公司内部部署。
• ❌ 不可以：把它作为托管服务提供给他人（managed service），或移除 / 规避许可声明。
• 对个人开发者与团队内部工具链无任何影响；若你做的是面向第三方的 SaaS 化产品并打算内嵌它，需要先过一遍 ELv2 条款或联系作者。

14参考链接