Cursor：MCP+Hooks 手动安装与沙箱工具跟做

你将得到什么

• 在 Cursor 项目（或全局）配好 mcp.json + hooks.json + 路由规则 context-mode.mdc
• 用聊天里的 ctx stats / ctx doctor 确认 MCP 已连接
• 抄官方 Think in Code 的 ctx_execute JavaScript 示例，理解沙箱如何把大输出挡在上下文外

开始前准备

node -v   # 官方要求 Node.js >= 22.5（或使用 Bun）
npm install -g context-mode
context-mode --help

对照结果：context-mode 命令可用。若全局安装失败，检查 Node 版本与 npm 权限。

Marketplace 一键安装（Option A）尚未上架时，不要空等；用下面 Option B。macOS/Linux 也可用 README 的 local-folder 软链方式，本课以手动配置为主，便于理解每一层在干什么。

步骤 1：注册 MCP 服务器

在项目根创建 .cursor/mcp.json（或全局 ~/.cursor/mcp.json）：

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

对照结果：文件保存后，打开 Cursor Settings → MCP，context-mode 应显示为已连接（绿点/Connected）。若失败，确认 which context-mode 在 Cursor 进程可见的 PATH 上。

步骤 2：配置 hooks

创建 .cursor/hooks.json（或 ~/.cursor/hooks.json），内容与官方 README 一致：

{
  "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"
      }
    ],
    "postToolUse": [
      {
        "command": "context-mode hook cursor posttooluse"
      }
    ],
    "stop": [
      {
        "command": "context-mode hook cursor stop"
      }
    ]
  }
}

说明（官方口径）：

• preToolUse 的 matcher 可选；去掉则对所有工具触发
• Cursor 目前 拒绝 sessionStart hook（论坛已有报告），因此会话恢复能力是 Partial；路由指令要靠下一步的 .mdc 文件
• 项目级 .cursor/hooks.json 会覆盖用户级配置
• 若以前跑过 Option B 又装了 local plugin，context-mode doctor 可能警告 hooks 重复——只保留一套

步骤 3：复制路由规则文件

Cursor 缺 SessionStart，需要规则文件让模型知道优先走沙箱：

mkdir -p .cursor/rules
cp "$(npm root -g)/context-mode/configs/cursor/context-mode.mdc" .cursor/rules/context-mode.mdc

对照结果：.cursor/rules/context-mode.mdc 存在。然后 重启 Cursor 或新开一个 Agent 会话。

步骤 4：验证 — `ctx stats` 与 `ctx doctor`

在 Cursor Agent 聊天中输入：

ctx stats

再输入：

ctx doctor

对照结果：

• Settings → MCP 中 context-mode 为 connected
• 模型应调用 ctx_stats / ctx_doctor 并返回报告（与 Claude Code 的 slash 命令同源工具）
• 终端也可：context-mode doctor

步骤 5：沙箱工具 — 用 `ctx_execute` Think in Code

官方核心范式：让模型写分析脚本，而不是把 50 个文件读进上下文。README 中的对照示例：

// Before: 47 × Read() = 700 KB.  After: 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'));
`);

跟做建议（在任意含 src/ 的 TypeScript 小项目 Agent 会话里）：

1. 先让 Agent「统计 src 下每个 .ts 文件行数」，并明确要求：必须用 ctx_execute，不要连续 Read
2. 跑完后执行 ctx stats，看本次调用是否记入沙箱统计

对照结果：对话里应主要看到脚本的 stdout 摘要，而不是整文件内容；ctx_stats 中 ctx_execute 计数增加。

沙箱六件套在做什么（官方表）

元工具：ctx_stats、ctx_doctor、ctx_upgrade、ctx_purge、ctx_insight。

隔离模型（官方）：每次 ctx_execute 起独立子进程；脚本互不共享内存；只有 stdout 进入对话。支持 JS/TS/Python/Shell/Ruby/Go/Rust/PHP/Perl/R/Elixir/C#；Bun 可用时 JS/TS 更快。gh / aws 等经凭证透传，不把密钥写进对话。

步骤 6（可选）：官方试玩提示

README「Try It」里任意一条均可在装好后试用，例如文档检索：

Fetch the React useEffect docs, index them, and find the cleanup pattern
with code examples. Then run ctx stats.

对照结果：应走 ctx_fetch_and_index → ctx_search（或等价组合），最后 ctx stats 显示节省。

Cursor 路径的已知限制（诚实口径）

• Marketplace 插件仍在审核；上架前用本课手动路径
• sessionStart 被 Cursor 校验拒绝 → 压缩后会话恢复不如 Claude Code 完整
• Cursor 接受 hook 的 additional_context 但未必展示给模型 → 路由依赖 .mdc
• 官方称 hooks 打开时约 ~98% 节省；仅靠说明文件约 ~60%

本课验收清单

1. MCP 面板中 context-mode 已连接
2. ctx stats 与 ctx doctor 有实质回复
3. 至少成功一次 ctx_execute（或 ctx_fetch_and_index + ctx_search），再用 ctx stats 看到计数变化
4. 仓库中有 .cursor/mcp.json、.cursor/hooks.json、.cursor/rules/context-mode.mdc（若用项目级配置）

两条路径怎么选

来源与站内入口

• 仓库与安装全文：https://github.com/mksglu/context-mode
• 产品与 Platform 说明：https://context-mode.com
• npm：https://www.npmjs.com/package/context-mode
• 昆仑工具页：https://www.kun.net/tools/context-mode/