mksglu/context-mode
GitHub: mksglu/context-mode
一个工作在 MCP 协议层的上下文窗口优化工具，通过沙盒隔离原始输出和 FTS5 全文检索实现会话状态持久化，解决 AI 编程助手上下文窗口被快速填满以及对话压缩后状态丢失的问题。
Stars: 9066 | Forks: 645
# 上下文模式
**上下文问题的另一半。**
[](https://www.npmjs.com/package/context-mode) [](https://www.npmjs.com/package/context-mode) [](https://github.com/mksglu/context-mode) [](https://github.com/mksglu/context-mode/stargazers) [](https://github.com/mksglu/context-mode/network/members) [](https://github.com/mksglu/context-mode/commits) [](LICENSE)
[](https://discord.gg/DCN9jUgN5v)
[](https://news.ycombinator.com/item?id=47193064)
directive into context
→ Model continues from last user prompt with full working state
```
快照按优先级层级构建 —— 如果 2 KB 的预算紧张，会首先丢弃较低优先级的事件（意图、MCP 工具计数），而关键状态（活动文件、任务、规则、决策）则总是会被保留。
压缩后，模型会收到一份 **Session Guide** —— 一份包含可操作部分的结构化叙述：
- **最后请求** —— 用户最后的提示，这样模型就可以继续工作而不用问 "我们刚才在做什么？"
- **任务** —— 带有完成状态的复选框格式（`[x]` 已完成，`[ ]` 待处理）
- **关键决策** —— 用户纠正和偏好设置（"改用 X"，"不要做 Y"）
- **修改的文件** —— 会话期间接触过的所有文件
- **未解决的错误** —— 尚未修复的错误
- **Git** —— 执行过的操作（checkout、commit、push、status）
- **项目规则** —— CLAUDE.md / GEMINI.md / AGENTS.md 路径
- **使用过的 MCP 工具** —— 工具名称及调用次数
- **子 任务** —— 委派工作的摘要
- **使用过的技能** —— 调用过的 slash 命令
- **环境** —— 工作目录，环境变量
- **数据引用** —— 会话期间粘贴的大型数据
- **会话意图** —— 模式分类（实现、调查、审查、讨论）
- **用户角色** —— 会话期间设置的行为指令
详细的事件数据也被索引到 FTS5 中，以便通过 `search()` 按需检索。
## 平台兼容性
| 功能 | Claude Code | Gemini CLI | VS Code Copilot | Cursor | OpenCode | KiloCode | OpenClaw | Codex CLI | Antigravity | Kiro | Zed | Pi |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| MCP Server | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| PreToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | Yes (扩展) |
| PostToolUse Hook | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | Yes (扩展) |
| SessionStart Hook | Yes | Yes | Yes | -- | -- | -- | Plugin | Yes | -- | -- | -- | Yes (扩展) |
| PreCompact Hook | Yes | Yes | Yes | -- | Plugin | Plugin | Plugin | -- | -- | -- | -- | Yes (扩展) |
| 可修改参数 | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | -- | -- | Yes (扩展) |
| 可阻止工具 | Yes | Yes | Yes | Yes | Plugin | Plugin | Plugin | Yes | -- | Yes | -- | Yes (扩展) |
| 实用命令 | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes (/ctx-stats, /ctx-doctor) |
| Slash 命令 | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| 插件市场 | Yes | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
### 路由强制执行
Hooks 以编程方式拦截工具调用 —— 它们可以阻止危险命令，并在执行前将其重定向到沙盒。指令文件通过提示指令引导模型，但无法阻止任何操作。**在支持的地方务必启用 hooks。**
| 平台 | Hooks | 指令文件 | 有 Hooks | 无 Hooks |
|---|:---:|---|:---:|:---:|
| Claude Code | Yes (自动) | [`CLAUDE.md`](configs/claude-code/CLAUDE.md) | **节省约 98%** | 节省约 60% |
| Gemini CLI | Yes | [`GEMINI.md`](configs/gemini-cli/GEMINI.md) | **节省约 98%** | 节省约 60% |
| VS Code Copilot | Yes | [`copilot-instructions.md`](configs/vscode-copilot/copilot-instructions.md) | **节省约 98%** | 节省约 60% |
| Cursor | Yes | [`context-mode.mdc`](configs/cursor/context-mode.mdc) | **节省约 98%** | 节省约 60% |
| OpenCode | Plugin | [`AGENTS.md`](configs/opencode/AGENTS.md) | **节省约 98%** | 节省约 60% |
| OpenClaw | Plugin | [`AGENTS.md`](configs/openclaw/AGENTS.md) | **节省约 98%** | 节省约 60% |
| Codex CLI | Yes | [`AGENTS.md`](configs/codex/AGENTS.md) | **节省约 98%** | 节省约 60% |
| Antigravity | -- | [`GEMINI.md`](configs/antigravity/GEMINI.md) | -- | 节省约 60% |
| Kiro | Yes | [`KIRO.md`](configs/kiro/KIRO.md) | **节省约 98%** | 节省约 60% |
| Zed | -- | [`AGENTS.md`](configs/zed/AGENTS.md) | -- | 节省约 60% |
| Pi | ✓ | [`AGENTS.md`](configs/pi/AGENTS.md) | **节省约 98%** | 节省约 60% |
如果没有 hooks，一次未路由的 `curl` 或 Playwright 快照就可能会将 56 KB 转储到上下文中 —— 使整个会话节省的上下文化为乌有。
有关完整的功能比较，请参见 [`docs/platform-support.md`](docs/platform-support.md)。
## 实用命令
**在任何 AI 会话中** —— 只需输入命令。LLM 会自动调用 MCP 工具：
```
ctx stats → context savings, call counts, session report
ctx doctor → diagnose runtimes, hooks, FTS5, versions
ctx upgrade → update from GitHub, rebuild, reconfigure hooks
ctx purge → permanently delete all indexed content from the knowledge base
ctx insight → personal analytics dashboard (opens local web UI)
```
**从您的终端** —— 无需 AI 会话即可直接运行：
```
context-mode doctor
context-mode upgrade
context-mode insight # opens analytics dashboard in browser
bash scripts/ctx-debug.sh # full diagnostic report for bug reports
```
调试脚本将操作系统信息、运行时版本、better-sqlite3 状态、适配器检测、配置文件（已脱敏）、hook 验证、FTS5/SQLite 测试、执行器测试、进程检查、会话数据库和环境变量收集到一个可粘贴的 markdown 报告中。
适用于**所有平台**。在 Claude Code 上，也可以使用 slash 命令（`/ctx-stats`、`/ctx-doctor`、`/ctx-upgrade`、`/ctx-purge`、`/ctx-insight`）。
## 基准测试
| 场景 | 原始大小 | 上下文大小 | 节省比例 |
|---|---|---|---|
| Playwright 快照 | 56.2 KB | 299 B | 99% |
| GitHub Issues (20) | 58.9 KB | 1.1 KB | 98% |
| 访问日志 (500 请求) | 45.1 KB | 155 B | 100% |
| Context7 React 文档 | 5.9 KB | 261 B | 96% |
| 分析 CSV (500 行) | 85.5 KB | 222 B | 100% |
| Git 日志 (153 次提交) | 11.6 KB | 107 B | 99% |
| 测试输出 (30 个套件) | 6.0 KB | 337 B | 95% |
| 仓库研究 (子 agent) | 986 KB | 62 KB | 94% |
在一个完整的会话中：315 KB 的原始输出变成 5.4 KB。会话时间从约 30 分钟延长到约 3 小时。
[包含 21 个场景的完整基准测试数据 →](BENCHMARK.md)
## 试试看
这些提示开箱即用。在每次执行后运行 `/context-mode:ctx-stats` 以查看节省情况。
**深度仓库研究** —— 5 次调用，62 KB 上下文（原始：986 KB，节省 94%）
```
Research https://github.com/modelcontextprotocol/servers — architecture, tech stack,
top contributors, open issues, and recent activity. Then run /context-mode:ctx-stats.
```
**Git 历史分析** —— 1 次调用，5.6 KB 上下文
```
Clone https://github.com/facebook/react and analyze the last 500 commits:
top contributors, commit frequency by month, and most changed files.
Then run /context-mode:ctx-stats.
```
**网页抓取** —— 1 次调用，3.2 KB 上下文
```
Fetch the Hacker News front page, extract all posts with titles, scores,
and domains. Group by domain. Then run /context-mode:ctx-stats.
```
**大型 JSON API** —— 7.5 MB 原始大小 → 0.9 KB 上下文（节省 99%）
```
Create a local server that returns a 7.5 MB JSON with 20,000 records and a secret
hidden at index 13000. Fetch the endpoint, find the hidden record, and show me
exactly what's in it. Then run /context-mode:ctx-stats.
```
**文档搜索** —— 2 次调用，1.8 KB 上下文
```
Fetch the React useEffect docs, index them, and find the cleanup pattern
with code examples. Then run /context-mode:ctx-stats.
```
**会话连续性** —— 具有完整状态的压缩恢复
```
Start a multi-step task: "Create a REST API with Express — add routes, tests,
and error handling." After 20+ tool calls, type: ctx stats to see the session
event count. When context compacts, the model continues from your last prompt
with tasks, files, and decisions intact — no re-prompting needed.
```
## 隐私与架构
Context Mode 不是 CLI 输出过滤器，也不是云分析仪表板。它在 MCP 协议层运行 —— 原始数据保留在沙盒子进程中，永远不会进入您的上下文窗口。网页、API 响应、文件分析、Playwright 快照、日志文件 —— 所有内容都在完全隔离的环境中处理。
**没有任何数据会离开您的机器。** 没有遥测，没有云同步，没有使用跟踪，无需注册帐户。您的代码、您的提示、您的会话数据 —— 都是本地的。SQLite 数据库位于您的主目录中，并在您完成操作后销毁。
这是一个深思熟虑的架构选择，而不是缺失的功能。上下文优化应该在源头进行，而不是在按席位订阅的仪表板中进行。隐私至上是我们的理念 —— 每一项设计决策都源于此。[许可证 →](#license)
## 安全性
Context Mode 强制执行您已经在使用的相同权限规则 —— 但将它们扩展到了 MCP 沙盒。如果您阻止了 `sudo`，它在 `ctx_execute`、`ctx_execute_file` 和 `ctx_batch_execute` 中也会被阻止。
**无需任何设置。** 如果您没有配置任何权限，什么都不会改变。只有当您添加规则时，此功能才会激活。
```
{
"permissions": {
"deny": [
"Bash(sudo *)",
"Bash(rm -rf /*)",
"Read(.env)",
"Read(**/.env*)"
],
"allow": [
"Bash(git:*)",
"Bash(npm:*)"
]
}
}
```
将此添加到您项目的 `.claude/settings.json`（或 `~/.claude/settings.json` 用于全局规则）。所有平台都从 Claude Code 的设置格式中读取安全策略 —— 即使在 Gemini CLI、VS Code Copilot 和 OpenCode 上也是如此。Codex CLI 的安全强制执行需要启用 `codex_hooks` 功能标志。
模式是 `Tool(匹配内容)`，其中 `*` 表示 "任何内容"。
用 `&&`、`;` 或 `|` 链接的命令会被拆分 —— 每一部分都会被单独。`echo hello && sudo rm -rf /tmp` 将被阻止，因为 `sudo` 部分匹配了拒绝规则。
**deny** 总是优先于 **allow**。更具体的（项目级）规则会覆盖全局规则。
## 贡献
有关开发工作流程和 TDD 指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
```
git clone https://github.com/mksglu/context-mode.git
cd context-mode && npm install && npm test
```
## 许可证
根据 [Elastic License 2.0](LICENSE)（源码可用）授权。您可以自由使用、分叉、修改和分发它。有两件事您不能做：将其作为托管/托管服务提供，或删除许可声明。我们选择 ELv2 而不是 MIT，是因为 MIT 允许将代码重新打包为具有竞争力的闭源 SaaS —— ELv2 阻止了这一点，同时保持源代码对所有人开放。
Used across teams at
Claude Code — 插件市场，全自动
**前提条件：** Claude Code v1.0.33+ (`claude --version`)。如果不识别 `/plugin` 命令，请先更新：`brew upgrade claude-code` 或 `npm update -g @anthropic-ai/claude-code`。 **安装：** ``` /plugin marketplace add mksglu/context-mode /plugin install context-mode@context-mode ``` 重启 Claude Code（或运行 `/reload-plugins`）。 **验证：** ``` /context-mode:ctx-doctor ``` 所有检查项都应显示 `[x]`。Doctor 会验证 runtimes、hooks、FTS5 和插件注册情况。 **路由：** 自动。SessionStart hook 在运行时注入路由指令 —— 不会向您的项目写入任何文件。该插件注册了所有 hooks（PreToolUse、PostToolUse、PreCompact、SessionStart）和 6 个沙盒工具（`ctx_batch_execute`、`ctx_execute`、`ctx_execute_file`、`ctx_index`、`ctx_search`、`ctx_fetch_and_index`）以及元工具（`ctx_stats`、`ctx_doctor`、`ctx_upgrade`、`ctx_purge`、`ctx_insight`）。 | Slash 命令 | 作用 | |---|---| | `/context-mode:ctx-stats` | 上下文节省情况 —— 按工具细分、消耗的 token 数、节省比例。 | | `/context-mode:ctx-doctor` | 诊断 —— runtimes、hooks、FTS5、插件注册、版本。 | | `/context-mode:ctx-upgrade` | 拉取最新版本、重新构建、迁移缓存、修复 hooks。 | | `/context-mode:ctx-purge` | 从知识库中永久删除所有已索引的内容。 | | `/context-mode:ctx-insight` | 个人分析仪表板 —— 包含 15 项以上关于工具使用、会话活跃度、错误率、并行工作模式和学习曲线的指标。打开本地 Web UI。 |备选方案 —— 仅 MCP 安装（无 hooks 或 slash 命令）
``` claude mcp add context-mode -- npx -y context-mode ``` 这将为您提供 6 个沙盒工具，但没有自动路由。模型仍然可以使用它们 —— 只是不会被引导优先使用它们而不是原生的 Bash/Read/WebFetch。适合在完全安装插件之前进行试用。Gemini CLI — 一个配置文件，包含 hooks
**前提条件：** Node.js 18+，已安装 Gemini CLI。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到 `~/.gemini/settings.json` 中。这一个文件即可注册 MCP server 和全部四个 hooks： { "mcpServers": { "context-mode": { "command": "context-mode" } }, "hooks": { "BeforeTool": [ { "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }] } ], "AfterTool": [ { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }] } ], "PreCompress": [ { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }] } ], "SessionStart": [ { "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }] } ] } } 3. 重启 Gemini CLI。 **验证：** ``` /mcp list ``` 您应该会看到 `context-mode: ... - Connected`。 **路由：** 自动。SessionStart hook 在运行时注入路由指令 —— 不会向您的项目写入任何 `GEMINI.md` 文件。所有四个 hooks（BeforeTool、AfterTool、PreCompress、SessionStart）以编程方式处理强制路由。 完整配置参考：[`configs/gemini-cli/settings.json`](configs/gemini-cli/settings.json)VS Code Copilot — 包含 SessionStart 的 hooks
**前提条件：** Node.js 18+，安装了带有 Copilot Chat v0.32+ 的 VS Code。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 在项目根目录下创建 `.vscode/mcp.json`： { "servers": { "context-mode": { "command": "context-mode" } } } 3. 创建 `.github/hooks/context-mode.json`： { "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" } ] } } 4. 重启 VS Code。 **验证：** 打开 Copilot Chat 并输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** 自动。SessionStart hook 在运行时注入路由指令 —— 不会向您的项目写入任何 `copilot-instructions.md` 文件。 包含 PreCompact 的完整 hook 配置：[`configs/vscode-copilot/hooks.json`](configs/vscode-copilot/hooks.json)Cursor — 支持 stop 的 hooks
**前提条件：** Node.js 18+，带有 Agent 模式的 Cursor。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 在您的项目根目录下创建 `.cursor/mcp.json`（或全局配置 `~/.cursor/mcp.json`）： { "mcpServers": { "context-mode": { "command": "context-mode" } } } 3. 创建 `.cursor/hooks.json`（或全局配置 `~/.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" } ], "postToolUse": [ { "command": "context-mode hook cursor posttooluse" } ], "stop": [ { "command": "context-mode hook cursor stop" } ] } } `preToolUse` matcher 是可选的 —— 如果没有它，hook 将在所有工具上触发。`stop` hook 在 agent 回合结束时触发，并且可以发送跟进消息以继续循环。也支持 `afterAgentResponse`（触发即忘记模式，接收完整的响应文本）。 4. 复制路由规则文件。Cursor 缺少 SessionStart hook，因此模型需要一个规则文件来感知路由： mkdir -p .cursor/rules cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc 5. 重启 Cursor 或开启新的 agent 会话。 **验证：** 打开 Cursor 设置 > MCP，确认 "context-mode" 显示为已连接。在 agent 聊天中，输入 `ctx stats`。 **路由：** Hooks 通过 `preToolUse`/`postToolUse`/`stop` 以编程方式强制执行路由。`.cursor/rules/context-mode.mdc` 文件在会话开始时提供路由指令，因为 Cursor 的 `sessionStart` hook 当前被其验证器拒绝（[论坛报告](https://forum.cursor.com/t/unknown-hook-type-sessionstart/149566))。项目中的 `.cursor/hooks.json` 会覆盖 `~/.cursor/hooks.json`。 **已知限制：** Cursor 接受 hook 响应中的 `additional_context`，但不会将其展示给模型（[论坛 #155689](https://forum.cursor.com/t/native-posttooluse-hooks-accept-and-log-additional-context-successfully-but-the-injected-context-is-not-surfaced-to-the-model/155689))。路由依赖于 `.mdc` 规则文件而不是 hook 上下文注入。 完整配置：[`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`configs/cursor/mcp.json`](configs/cursor/mcp.json) | [`configs/cursor/context-mode.mdc`](configs/cursor/context-mode.mdc)OpenCode — 带有 hooks 的 TypeScript 插件
**前提条件：** Node.js 18+，已安装 OpenCode。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到项目根目录的 `opencode.json`（或全局配置 `~/.config/opencode/opencode.json`）中： { "$schema": "https://opencode.ai/config.json", "mcp": { "context-mode": { "type": "local", "command": ["context-mode"] } }, "plugin": ["context-mode"] } `mcp` 条目注册了 6 个沙盒工具。`plugin` 条目启用了 hooks —— OpenCode 在每次工具执行前后直接调用插件的 TypeScript 函数，阻止危险命令并强制执行沙盒路由。 3. *(可选)* 复制路由规则文件。OpenCode 缺少 SessionStart hook，因此模型需要一个 `AGENTS.md` 文件来感知路由： cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md 这会告诉模型应该使用哪些工具以及哪些命令被阻止。没有它，hooks 仍然会强制执行路由 —— 但模型不会知道命令*为什么*被拒绝。 4. 重启 OpenCode。 **验证：** 在 OpenCode 会话中，输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** Hooks 通过 `tool.execute.before` 和 `tool.execute.after` 以编程方式强制执行路由。可选的 [`AGENTS.md`](configs/opencode/AGENTS.md) 文件提供了供模型感知的路由指令。`experimental.session.compacting` hook 会在对话压缩时构建恢复快照。 完整配置：[`configs/opencode/opencode.json`](KiloCode — 带有 hooks 的 TypeScript 插件
**前提条件：** Node.js 18+，已安装 KiloCode。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到项目根目录的 `kilo.json`（或全局配置 `~/.config/kilo/kilo.json`）中： { "$schema": "https://app.kilo.ai/config.json", "mcp": { "context-mode": { "type": "local", "command": ["context-mode"] } }, "plugin": ["context-mode"] } `mcp` 条目注册了 6 个沙盒工具。`plugin` 条目启用了 hooks —— KiloCode 在每次工具执行前后直接调用插件的 TypeScript 函数，阻止危险命令并强制执行沙盒路由。 3. *(可选)* 复制路由规则文件。KiloCode 共享 OpenCode 的插件架构且缺少 SessionStart，因此模型需要一个 `AGENTS.md` 文件来感知路由： cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md 4. 重启 KiloCode。 **验证：** 在 KiloCode 会话中，输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** Hooks 通过 `tool.execute.before` 和 `tool.execute.after` 以编程方式强制执行路由。可选的 [`AGENTS.md`](configs/opencode/AGENTS.md) 文件提供了供模型感知的路由指令。`experimental.session.compacting` hook 会在对话压缩时构建恢复快照。OpenClaw / Pi Agent — 原生网关插件
**前提条件：** OpenClaw 网关正在运行 ([>2026.1.29](https://github.com/openclaw/openclaw/pull/9761))，Node.js 22+。 context-mode 作为一个原生的 [OpenClaw](https://github.com/openclaw) 网关插件运行，目标是 **Pi Agent** 会话（Read/Write/Edit/Bash 工具）。与其他平台不同，这里没有单独的 MCP server —— 插件通过 OpenClaw 的 [plugin API](https://docs.openclaw.ai/tools/plugin) 直接注册到网关运行时中。 **安装：** 1. 克隆并安装： git clone https://github.com/mksglu/context-mode.git cd context-mode npm run install:openclaw 安装程序使用您环境中的 `$OPENCLAW_STATE_DIR`（默认值：`/openclaw`）。要指定自定义路径： npm run install:openclaw -- /path/to/openclaw-state 常见位置：**Docker** —— `/openclaw`（默认值）。**本地** —— `~/.openclaw` 或您设置的任何 `OPENCLAW_STATE_DIR`。 安装程序会处理所有事情：`npm install`、`npm run build`、`better-sqlite3` 原生重构建、`runtime.json` 中的扩展注册，以及通过 SIGUSR1 重启网关。 2. 开启一个 Pi Agent 会话。 **验证：** 插件通过 [`api.on()`](https://docs.openclaw.ai/tools/plugin)（生命周期）和 [`api.registerHook()`](https://docs.openclaw.ai/tools/plugin)（命令）注册了 8 个 hooks。输入 `ctx stats` 以确认工具已加载。 **路由：** 自动。所有工具拦截、会话跟踪和压缩恢复 hooks 都会自动激活 —— 无需手动配置 hook 或路由文件。 完整文档：[`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)Codex CLI — MCP + hooks（等待上游调度）
**前提条件：** Node.js 18+，已安装 Codex CLI。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到 `~/.codex/config.toml` 中： [mcp_servers.context-mode] command = "context-mode" 3. *(等待上游)* 启用 hooks 功能标志。添加到 `~/.codex/config.toml`： [features] codex_hooks = true 4. *(为启用调度做准备)* 为强制执行路由和跟踪会话添加 hooks。创建 `~/.codex/hooks.json`： { "hooks": { "PreToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }], "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }], "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }] } } `PreToolUse` 强制执行沙盒路由（阻止危险命令，重定向到 MCP 工具）。`PostToolUse` 捕获会话事件。`SessionStart` 在压缩后恢复状态。 5. 复制路由指令（即使有 hooks 也建议复制，以实现全面的路由感知）： cp node_modules/context-mode/configs/codex/AGENTS.md ./AGENTS.md 全局使用方式：`cp node_modules/context-mode/configs/codex/AGENTS.md ~/.codex/AGENTS.md`。全局配置适用于所有项目。如果两者都存在，Codex CLI 会将它们合并。 6. 重启 Codex CLI。 **验证：** 启动一个会话并输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** MCP 工具正常工作。基于 Hook 的路由已准备就绪，但正在等待 Codex 启用 hook 调度。在此期间，`AGENTS.md` 文件提供了供模型感知的路由指令。Antigravity — 仅 MCP，无 hooks
**前提条件：** Node.js 18+，已安装 Antigravity。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到 `~/.gemini/antigravity/mcp_config.json`： { "mcpServers": { "context-mode": { "command": "context-mode" } } } 3. 复制路由指令（Antigravity 不支持 hook）： cp node_modules/context-mode/configs/antigravity/GEMINI.md ./GEMINI.md 4. 重启 Antigravity。 **验证：** 在 Antigravity 会话中，输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** 手动。`GEMINI.md` 文件是唯一的执行方法（约 60% 依从率）。没有程序化拦截。通过 MCP 协议握手（`clientInfo.name`）自动检测 —— 无需手动配置平台。 完整配置：[`configs/antigravity/mcp_config.json`](configs/antigravity/mcp_config.json) | [`configs/antigravity/GEMINI.md`](configs/antigravity/GEMINI.md)Kiro — 包含引导文件的 hooks
**前提条件：** Node.js 18+，开启了 MCP 的 Kiro（设置 > 搜索 "MCP"）。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到项目中的 `.kiro/settings/mcp.json`（或全局的 `~/.kiro/settings/mcp.json`）： { "mcpServers": { "context-mode": { "command": "context-mode" } } } 3. 创建 `.kiro/hooks/context-mode.json`： { "name": "context-mode", "description": "Context-mode hooks for context window protection", "hooks": { "preToolUse": [ { "matcher": "*", "command": "context-mode hook kiro pretooluse" } ], "postToolUse": [ { "matcher": "*", "command": "context-mode hook kiro posttooluse" } ] } } 4. 复制路由指令。Kiro 的 `agentSpawn`（SessionStart）尚未实现，因此模型在会话开始时需要一个路由文件： cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md 5. 重启 Kiro。 **验证：** 打开 Kiro 面板 > MCP Servers 标签页，确认 "context-mode" 显示绿色状态指示灯。在聊天中，输入 `ctx stats`。 **路由：** Hooks 通过 `preToolUse`/`postToolUse` 以编程方式强制执行路由。由于 `agentSpawn`（相当于 SessionStart）尚未接入，因此 `KIRO.md` 文件提供了路由指令。工具名称显示为 `@context-mode/ctx_batch_execute`、`@context-mode/ctx_search` 等。通过 MCP 协议握手自动检测。 完整配置：[`configs/kiro/mcp.json`](configs/kiro/mcp.json) | [`configs/kiro/agent.json`](configs/kiro/agent.json) | [`configs/kiro/KIRO.md`](configs/kiro/KIRO.md)Zed — 仅 MCP，无 hooks
**前提条件：** Node.js 18+，已安装 Zed。 **安装：** 1. 全局安装 context-mode： npm install -g context-mode 2. 将以下内容添加到 `~/.config/zed/settings.json`（Windows: `%APPDATA%\Zed\settings.json`）： { "context_servers": { "context-mode": { "command": { "path": "context-mode" } } } } 注意：Zed 使用 `"context_servers"` 和 `"command": { "path": "..." }` 语法，而不是像其他平台那样使用 `"mcpServers"` 或 `"command": "..."`。 3. 复制路由指令（Zed 不支持 hook）： cp node_modules/context-mode/configs/zed/AGENTS.md ./AGENTS.md 4. 重启 Zed（或保存 `settings.json` —— Zed 会在配置更改时自动重启上下文服务器）。 **验证：** 打开 Agent 面板（`Cmd+Shift+A`），进入设置，检查 "context-mode" 旁边的指示点 —— 绿色表示激活。在 agent 聊天中输入 `ctx stats`。 **路由：** 手动。`AGENTS.md` 文件是唯一的执行方法（约 60% 依从率）。没有程序化拦截。工具名称显示为 `mcp:context-mode:ctx_batch_execute`、`mcp:context-mode:ctx_search` 等。通过 MCP 协议握手自动检测。Pi Coding Agent — 支持完整 hook 的扩展
**前提条件：** Node.js 18+，已安装 Pi Coding Agent。 **安装：** 1. 克隆该扩展： git clone https://github.com/mksglu/context-mode.git ~/.pi/extensions/context-mode cd ~/.pi/extensions/context-mode npm install npm run build 2. 将以下内容添加到 `~/.pi/agent/mcp.json`（项目级则使用 `.pi/mcp.json`）： { "mcpServers": { "context-mode": { "command": "node", "args": ["/home/youruser/.pi/extensions/context-mode/node_modules/context-mode/start.mjs"] } } } 3. 重启 Pi。 **验证：** 在 Pi 会话中，输入 `ctx stats`。Context-mode 工具应该会出现并做出响应。 **路由：** 自动。该扩展注册了所有关键生命周期事件（`tool_call`、`tool_result`、`session_start`、`session_before_compact`），提供完整的会话连续性和路由强制执行。构建前提条件 (CentOS, RHEL, Alpine)
Context Mode 在 Node.js 上使用 [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)，后者为大多数平台提供了预构建的原生二进制文件。在 glibc >= 2.31 的系统上（Ubuntu 20.04+、Debian 11+、Fedora 34+、macOS、Windows），无需任何构建工具即可运行 `npm install`。 **Linux + Node.js >= 22.13：** Context Mode 自动使用内置的 `node:sqlite` 模块代替 `better-sqlite3`。这彻底消除了原生插件，避免了由于 Linux 上 V8 的 `madvise(MADV_DONTNEED)` 损坏插件的 `.got.plt` 部分而导致的[偶发性 SIGSEGV 崩溃](https://github.com/nodejs/node/issues/62515)。无需配置 —— 自动检测。在较旧的 Node.js 版本上会回退到 `better-sqlite3`。 **Bun 用户：** 无需原生编译。Context Mode 自动检测 Bun 并通过兼容性适配器使用内置的 `bun:sqlite` 模块。`better-sqlite3` 及其所有构建依赖项将被完全跳过。 在较旧的 glibc 系统上CentOS 7/8、RHEL 8、Debian 10），预构建的二进制文件无法加载，better-sqlite3 会**自动回退到从源码编译**，经由 `prebuild-install || node-gyp rebuild --release`。这需要 C++20 编译器（GCC 10+）、Make 和带有 setuptools 的 Python。 **CentOS 8 / RHEL 8** (glibc 2.28): ``` dnf install -y gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ make python3 python3-setuptools scl enable gcc-toolset-10 'npm install -g context-mode' ``` **CentOS 7 / RHEL 7** (glibc 2.17): ``` yum install -y centos-release-scl yum install -y devtoolset-10-gcc devtoolset-10-gcc-c++ make python3 pip3 install setuptools scl enable devtoolset-10 'npm install -g context-mode' ``` **Alpine Linux:** better-sqlite3 v12.8.0+ 提供了 Alpine 预构建二进制文件 (musl)。在 `^12.6.2` 依赖范围内，`npm install` 将解析到最新的 12.x 版本，并在 Alpine 上无需构建工具即可工作。如果您固定使用较旧的版本： ``` apk add build-base python3 py3-setuptools npm install -g context-mode ```捕获的内容
每个工具调用都会通过提取结构化事件的 hooks： | 类别 | 事件 | 优先级 | 捕获者 | |---|---|---|---| | **文件** | read, edit, write, glob, grep | 关键 (P1) | PostToolUse | | **任务** | create, update, complete | 关键 (P1) | PostToolUse | | **规则** | CLAUDE.md / GEMINI.md / AGENTS.md 路径 + 内容 | 关键 (P1) | SessionStart | | **决策** | 用户纠正，偏好设置（"改用 X"，"不要做 Y"） | 高 (P2) | UserPromptSubmit | | **Git** | checkout, commit, merge, rebase, stash, push, pull, diff, status | 高 (P2) | PostToolUse | | **错误** | 工具故障，非零退出码 | 高 (P2) | PostToolUse | | **环境** | cwd 更改，venv，nvm，conda，包安装 | 高 (P2) | PostToolUse | | **MCP 工具** | 所有带有使用次数的 `mcp__*` 工具调用 | 普通 (P3) | PostToolUse | | **子 Agent** | Agent 工具调用 | 普通 (P3) | PostToolUse | | **技能** | Slash 命令调用 | 普通 (P3) | PostToolUse | | **角色** | 人设 / 行为指令（"扮演高级工程师"） | 普通 (P3) | UserPromptSubmit | | **意图** | 会话模式分类（调查、实现、调试） | 低 (P4) | UserPromptSubmit | | **数据** | 大型用户粘贴数据引用 (>1 KB) | 低 (P4) | UserPromptSubmit | | **用户提示** | 每条用户消息（用于恢复最后的提示） | 关键 (P1) | UserPromptSubmit |会话如何在压缩后存活
``` PreCompact fires → Read all session events from SQLite → Build priority-tiered XML snapshot (≤2 KB) → Store snapshot in session_resume table SessionStart fires (source: "compact") → Retrieve stored snapshot → Write structured events file → auto-indexed into FTS5 → Build Session Guide with 15 categories → Inject各平台细节
**Claude Code** —— 完整的会话支持。所有 5 种 hook 类型都会触发，捕获工具事件、用户决策、构建压缩快照，以及在压缩或 `--continue` 后恢复状态。 **Gemini CLI** —— 高覆盖率。PostToolUse (AfterTool)、PreCompact (PreCompress) 和 SessionStart 都会触发。缺少 UserPromptSubmit，因此不捕获用户决策和纠正 —— 但文件编辑、git 操作、错误和任务都被完全跟踪。 **VS Code Copilot** —— 高覆盖率。与 Gemini CLI 相同 —— PostToolUse、PreCompact 和 SessionStart 都会触发。不捕获用户决策，但所有工具级别的事件都会被捕获。 **Cursor** —— 部分覆盖率。原生的 `preToolUse` 和 `postToolUse` hooks 捕获工具事件。`sessionStart` 已被 Cursor 记录在案，但目前被其验证器拒绝，因此无法进行会话恢复。路由指令改为通过 MCP server 启动时传递。 **OpenCode** —— 部分。TypeScript 插件通过 `tool.execute.after` 捕获 PostToolUse 事件，但 SessionStart 尚不可用 ([#14808](https://github.com/sst/opencode/issues/14808))。事件已被存储，但在压缩后不会自动恢复。 **KiloCode** —— 部分。通过 OpenCodeAdapter 共享与 OpenCode 相同的插件架构。TypeScript 插件通过 `tool.execute.after` 捕获 PostToolUse 事件，但 SessionStart 的可用性取决于 KiloCode 的实现。事件已被存储，但在压缩后可能不会自动恢复。 **OpenClaw / Pi Agent** —— 高覆盖率。所有的工具生命周期 hooks（`after_tool_call`、`before_compaction`、`session_start`）都通过原生网关插件触发。不捕获用户决策，但文件编辑、git 操作、错误和任务都被完全跟踪。在较旧的网关版本上，如果压缩 hooks 失败，会回退到数据库快照重建。参见 [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)。 **Codex CLI** —— MCP 激活，hooks 就绪。Hook 脚本（PreToolUse、PostToolUse、SessionStart）已实现并经过测试，但 Codex CLI 尚未调度它们 (Stage::UnderDevelopment)。MCP 工具正常工作。跟踪：[openai/codex#16685](https://github.com/openai/codex/issues/16685)。 **Antigravity** —— 无会话支持。没有 hooks，没有事件捕获。需要手动复制 `GEMINI.md` 到您的项目根目录。通过 MCP 协议握手（`clientInfo.name`）自动检测。 **Zed** —— 无会话支持。没有 hooks，没有事件捕获。需要手动复制 `AGENTS.md` 到您的项目根目录。通过 MCP 协议握手（`clientInfo.name`）自动检测。 **Kiro** —— 部分覆盖率。原生的 `preToolUse` 和 `postToolUse` hooks 捕获工具事件并强制执行沙盒路由。`agentSpawn`（Kiro 的 SessionStart 等价物）尚未实现，因此压缩后无法进行会话恢复。需要手动复制 `KIRO.md` 到您的项目根目录。通过 MCP 协议握手（`clientInfo.name`）自动检测。 **Pi Coding Agent** —— 高覆盖率。该扩展注册了所有关键的生命周期事件：`tool_call` (PreToolUse)、`tool_result` (PostToolUse)、`session_start` (SessionStart) 和 `session_before_compact` (PreCompact)。文件编辑、git 操作、错误和任务都被完全跟踪。压缩后的会话恢复通过扩展的事件 hooks 进行。标签：AI智能体, AI编程, AI编程助手, Cilium, DLL 劫持, LLM上下文管理, MITM代理, NPM, Token优化, 上下文压缩, 上下文模式, 上下文窗口优化, 上下文裁剪, 人工智能开发工具, 代码辅助, 企业级AI工具, 信息密度, 多平台兼容, 大语言模型, 威胁情报, 工具输出优化, 开发效率, 开发者工具, 性能优化, 提示词工程, 检测绕过, 沙箱, 策略决策点, 网络可观测性, 自动化攻击, 输出过滤