在 AI 编码代理的工作场景中，上下文窗口正面临前所未有的压力。每一次工具调用都可能向上下文注入大量原始数据：Playwright 页面快照占用 56 KB，二十个 GitHub Issue 占用 59 KB，一份访问日志占用 45 KB。经过三十分钟的交互，40% 的上下文空间已被消耗，而当代理执行上下文压缩以释放空间时，它会丢失正在编辑的文件、进行中的任务以及用户上一次的具体需求。这种「上下文书签」的丢失严重影响了代理的持续工作能力。
GitHub trending 项目 context-mode 提出了一个系统性的解决方案，它通过沙箱化工具输出、会话状态持久化以及「用代码思考」范式三大核心机制，实现了 315 KB 原始数据压缩至 5.4 KB（98% 上下文节约）的效果，并支持 12 个主流 AI 编码平台。
沙箱化工具输出：隔离与过滤
context-mode 的核心创新在于将所有可能产生大量输出的工具调用重定向到沙箱环境执行。传统的工具调用模式是：代理调用 Bash 执行命令、调用 Read 读取文件、调用 WebFetch 获取网页，所有这些操作的原始输出直接进入上下文窗口。context-mode 引入了一个 MCP 服务器层，在工具执行前拦截调用，将它们路由到专门的沙箱工具。
以 ctx_execute 为例，该工具支持 11 种语言运行时（JavaScript、TypeScript、Python、Shell、Ruby、Go、Rust、PHP、Perl、Elixir），每个调用都在独立的子进程中执行。原始数据 —— 日志文件、API 响应、快照内容 —— 被完全隔离在沙箱内部，只有 stdout 输出进入对话上下文。官方 benchmark 显示，一个 56 KB 的 Playwright 快照在沙箱处理后仅占用 299 B，节省 99%；一个 45 KB 的访问日志（500 条请求）压缩至 155 B，节省 100%。
对于超过 5 KB 的输出，context-mode 采用了意图驱动过滤（intent-driven filtering）策略。当调用 ctx_execute 时提供 intent 参数，系统会将完整输出索引到知识库，然后仅返回与意图匹配的内容片段，而非完整的原始数据。
ctx_batch_execute 进一步提升了效率，它允许在单次调用中执行多条命令或搜索多个查询，将 986 KB 的仓库研究场景压缩至 62 KB（94% 节省）。
知识库与检索：FTS5 与 BM25
context-mode 并非简单丢弃数据，而是建立了一个结构化的知识库来持久化有价值的信息。ctx_index 工具将 markdown 内容按标题分块（code blocks 保持完整），存入 SQLite FTS5（Full-Text Search 5）虚拟表。搜索时使用 BM25 排名算法，这是一种基于词频、逆文档频率和文档长度归一化的概率相关性算法。
系统采用多项技术提升检索质量：索引时应用 Porter 词干提取，使 "running"、"runs"、"ran" 匹配同一词根；查询时同时运行 porter 匹配和三元组子字符串匹配两种策略，通过 Reciprocal Rank Fusion（RRF）合并两个结果列表；多词查询还会进行邻近度重排序，查询词相邻出现的结果排名更高；Levenshtein 距离用于模糊纠正，「kuberntes」会自动修正为「kubernetes」后重新搜索。
搜索结果采用智能片段提取（smart snippets），即定位查询词在内容中的位置并返回该位置周围的窗口，而非简单的字符截断。ctx_fetch_and_index 进一步扩展到 URL 抓取：获取网页、转换为 markdown、分块、索引，原始页面内容从不进入上下文。
知识库采用 TTL 缓存机制：24 小时内重复访问同一 URL 跳过网络请求，仅返回缓存提示（0.3 KB vs 48 KB+）；14 天以上的索引内容在启动时自动清理。
会话连续性：让压缩不再丢失状态
当上下文窗口满载时，AI 代理会执行会话压缩（compaction）—— 丢弃旧消息以腾出空间。没有会话追踪的情况下，这会导致代理遗忘所有工作状态。context-mode 通过四个协同工作的钩子（hooks）解决了这一问题。
PostToolUse 钩子在每次工具调用后触发，捕获结构化事件：文件操作（read、edit、write、glob、grep）、任务状态（create、update、complete）、Git 操作（checkout、commit、merge、rebase、stash、push、pull、diff、status）、工具错误与退出码、环境变化（cwd、venv、nvm、conda）。UserPromptSubmit 钩子记录用户决策与修正（"use X instead"、"don't do Y"）、角色指令（"act as senior engineer"）和会话意图分类。PreCompact 钩子在压缩前触发，从 SQLite 读取所有会话事件，构建优先级分层的 XML 快照（≤2 KB），存储到 session_resume 表。SessionStart 钩子在会话恢复时触发，检索快照、索引事件到 FTS5、生成包含 15 个类别的会话指南（Session Guide），最后向上下文注入 <session_knowledge> 指令。
会话指南的结构设计体现了对代理工作流的深刻理解：包含「最后请求」（用户的最后一条指令，代理据此继续而非询问「我们要做什么」）、任务列表（checkbox 格式，含完成状态）、关键决策、修改的文件列表、未解决的错误、Git 操作记录、项目规则路径、MCP 工具调用统计、子任务摘要、环境信息等。快照构建采用优先级分层：P1 关键状态（active files、tasks、rules、decisions）始终保留，P2 高优先级事件（git、errors、environment）次之，P3-P4 低优先级事件在 2 KB 预算紧张时优先丢弃。
十二平台适配：Hook 机制的差异化实现
context-mode 的另一显著特性是对 12 个 AI 编码平台的适配支持。这些平台的 Hook 机制差异巨大，context-mode 针对性地实现了兼容性方案。
| 平台 | Hook 支持 | 会话完整性 |
|---|---|---|
| Claude Code | PreToolUse、PostToolUse、PreCompact、SessionStart、UserPromptSubmit | 完整 |
| Gemini CLI | AfterTool、PreCompress、SessionStart | 高 |
| VS Code Copilot | PostToolUse、PreCompact、SessionStart | 高 |
| Cursor | preToolUse、postToolUse | 部分（SessionStart 被拒绝） |
| OpenCode | TypeScript Plugin（tool.execute.before/after、experimental.session.compacting） | 部分（SessionStart 未实现） |
| KiloCode | 同 OpenCode 架构 | 部分 |
| OpenClaw/Pi Agent | Native Gateway Plugin（api.on()、api.registerHook()） | 高 |
| Codex CLI | Hook 已实现，等待上游 dispatch | 部分 |
| Antigravity | 无 | 无 |
| Kiro | preToolUse、postToolUse | 部分（agentSpawn 未实现） |
| Zed | 无 | 无 |
| Pi Coding Agent | Extension（tool_call、tool_result、session_start、session_before_compact） | 高 |
对于缺乏 Hook 支持的平台（Antigravity、Zed），context-mode 依赖手动复制的路由指令文件（如 AGENTS.md、GEMINI.md），但合规率仅约 60%，因为文件仅提供提示而无法拦截危险命令。有 Hook 的平台通过 PreToolUse 可以在执行前阻止未经沙箱路由的调用，实现约 98% 的上下文节省。
权限与安全模型
context-mode 继承并扩展了各平台的权限规则。如果用户在平台设置中阻止了 sudo 命令，该规则同样适用于沙箱内的 ctx_execute、ctx_execute_file、ctx_batch_execute。权限配置采用 Tool(匹配模式) 格式，支持通配符：Bash(sudo *)、Read(.env)、Read(/**/.env*)。deny 规则优先于 allow 规则，项目级规则优先于全局规则。
安全策略在所有平台间统一：即使在 Gemini CLI、VS Code Copilot 或 OpenCode 上运行，也统一读取 Claude Code 格式的安全策略文件。
工程实践参数
在生产环境中部署 context-mode 时，以下参数值得关注：
沙箱输出阈值建议保持默认的 5 KB，超过此大小的输出自动触发意图驱动过滤。意图描述应具体明确，例如「找出所有包含 useEffect 清理模式的代码示例」优于「分析 useEffect」。FTS5 索引的标题与 heading 权重设为 5 倍于正文，这在代码仓库导航查询中极为有效。24 小时 TTL 缓存适合文档类场景，若需实时数据可在调用时传入 force: true 绕过缓存。会话快照预算 2 KB 在大多数场景下足够，若任务极为复杂可考虑调整优先级分层策略。
ctx_stats 工具提供按工具分类的上下文节省明细、token 消耗与节省比例；ctx_doctor 诊断运行时环境、Hook 状态、FTS5 可用性与版本信息；ctx_insight 打开本地 Web UI 展示 15+ 项指标，包括工具使用频率、会话活动、错误率、并行工作模式与掌握曲线。
隐私架构
context-mode 明确选择了本地优先的隐私架构。所有数据处理发生在用户的机器上，不存在遥测、云同步或使用追踪。SQLite 数据库存在于用户主目录，会话结束后即删除。知识库索引同样存储在 ~/.context-mode/content/，14 天后自动清理。这一设计选择源于创始团队的核心信念：上下文优化应在源头发生，而非在某个订阅制仪表板后方。
License 采用 Elastic License 2.0（ELv2），允许使用、fork、修改和分发，但禁止将其作为托管服务提供。这与 MIT License 的关键区别在于防止代码被闭源 SaaS 产品商业化。
小结
context-mode 代表了 AI 编码代理上下文管理的一个新范式。它不试图扩展上下文窗口的物理大小，而是通过沙箱化、索引化和优先级化三个手段，在有限的上下文中存储更高密度的语义信息。98% 的上下文压缩率不是理论值，而是通过沙箱输出隔离、FTS5 检索与会话状态持久化在真实工作流中实现的。对于长时间运行的复杂任务 —— 如大型代码库研究、多文件重构、端到端测试编写 ——context-mode 提供的会话连续性尤为重要，它让代理能够真正「记住」工作进度，而非每次压缩后都需要用户重新说明上下文。
资料来源：GitHub mksglu/context-mode（https://github.com/mksglu/context-mode）