mksglu/context-mode：20.8k stars 的 AI 编码上下文优化器，Hacker News

发表于 分类于
mksglu/context-mode（GitHub 20.8k stars、当日 +96 stars、Elastic License v2）是一款给 AI 编码 Agent 用的上下文窗口优化 MCP 服务器，三件套：1) Sandbox 工具输出 98% 减量（315 KB → 5.4 KB），2) SQLite FTS5 + BM25 做 session 持续性让模型跨 compaction 不丢上下文，3) "Think in Code" 强制让 LLM 写脚本跑分析而不是用 read 工具把数据吃进 context。PreToolUse/PostToolUse/SessionStart/PreCompact/UserPromptSubmit/Stop 六类 hook 拦截，支持 Claude Code、Codex、Cursor、Copilot CLI/IDE/JetBrains、Gemini CLI、Qwen Code、Kimi Code、Antigravity IDE/CLI、OpenClaw 等 17 个客户端，是 ponytail 之后 AI Agent 工具链里第二个跨平台编排的硬基础设施。

上周我在改一个老项目的支付回调逻辑。改完跑测试，一堆失败。我让 Claude Code 看 logs 找根因。

它跑了 cat /var/log/app/error.log，一文件 4.5 MB，全塞进了 context。

然后它跑了 git log --oneline -50，又 1.2 MB。

然后它跑了 npm test 2>&1，200 KB。

然后我让它 “再看看另外那个文件”，它跑了 cat /var/log/app/access.log | tail -1000，20 KB。

我盯着屏幕看 token 计数从 12k 飙升到 380k。等它给出分析的时候，输出已经变成了 “I need to acknowledge that my context window is filling up…” 后面跟着一段自动 compact 的提示。

Compact 完，它忘了我让它看的是支付回调，忘了刚才那 50 个 git commit 是给什么 feature 用的，忘了我让它对比的两个 error。

那一刻我才意识到，AI Agent 的” 上下文窗口” 这件事是个结构性问题，不是”prompt 写好一点” 就能解决的。

那天我在 Hacker News 看到 context-mode 拿了首页 #1，570+ 分。

20.8k stars，Elastic License v2。它干的事情只有一件：让 agent 看到的所有数据不挤占 context window。

一、问题的真相：context 浪费在工具输出上

README 开篇那几行我反复看了三遍，因为它把这个问题量化了。

一个 Playwright snapshot 56 KB。 20 个 GitHub issue 59 KB。 一个 access log 45 KB。 跑 30 分钟之后，40% 的 context window 没了。

你辛辛苦苦把 prompt 写得简洁、CLAUDE.md 写得克制，结果 agent 调一个 cat 命令就把你一天的工作量打回零。

更糟的是 compact。 context 满了之后 agent 会自动压缩历史，但你之前让它改的文件、跑的 task、做的决策，compact 完它不知道了。 它给你一个” 干净的总结”，但你跟它聊到第 30 轮的那个默契断了。

这件事的根因是：模型当成数据处理器。 模型读 50 个文件去数函数、读 200 个 commit 去归类 feature、读 1 MB log 去定位 error。 这些事 LLM 不擅长，script 写一行 wc -l 就行。但 agent 不知道该写 script，它只会 cat。

context-mode 想做的事是把这三个问题一起解决：

  1. 工具输出别进 context。
  2. session 状态别因为 compact 丢。
  3. 让模型写 script 而不是用 read 工具读数据。

二、核心机制：sandbox + FTS5 + Think in Code 三件套

1. Sandbox：315 KB → 5.4 KB

第一个动作是拦截。 context-mode 装上之后，agent 调任何工具（Read、Bash、Grep、Glob、fetch）之前，PreToolUse hook 介入，重写工具入参：把大输出塞进本地文件，给工具调用返回一个” 可索引的引用”，而不是原始输出。

具体效果：Playwright snapshot 56 KB → 5.4 KB 索引描述。 GitHub issue 列表 59 KB → 2 KB 引用。 access log 45 KB → 1.5 KB 索引。

README 给了 315 KB → 5.4 KB 的总体减量。 98% 的工具输出被踢出 context，进了本地 SQLite。

agent 拿到这个引用之后，如果它真的需要查具体内容，调 ctx_search 或 ctx_fetch_and_index 走精确查询拿回相关片段。不是把整个 315 KB 再读一遍。

这件事的本质是：把工具输出从 context 这个” 易失的内存” 搬到 SQLite 这个” 持久的硬盘”。 硬盘上存多少没关系，内存里只能放当前需要的那一小块。

2. Session Continuity：FTS5 + BM25 跨 compact 不丢

第二个动作是记忆。 context-mode 把每一次文件编辑、git 操作、task 状态、error、用户决策都记录在 SQLite 里，索引到 FTS5 虚拟表。

当 agent 触发 compact（context 满了要压缩），PreCompact hook 触发，context-mode 把完整的 session state 存盘。 压缩完成后，SessionStart hook 重新加载，agent 从断点续上。

ctx_search 走 BM25 排序（一种概率相关性算法，考虑词频、文档频率、文档长度归一化）。 标题和标题头权重 5x。 Porter stemming 自动应用（”running”、”runs”、”ran” 匹配同一 stem）。 Trigram 匹配支持子串查询（”useEff” 找到 “useEffect”）。

model 想要查” 上次我改 PaymentService 的时候是不是在重构抽象层”，调 ctx_search("PaymentService 重构")，拿到精确的 session 事件列表，而不是再读一遍 50 个 git commit。

这个机制跟 OpenWhispr 那篇里讲的” 声纹识别 + 跨会议搜索” 是同一类思路：把对话当成数据库来查。

3. Think in Code：让 LLM 写 script

第三个动作是改思维。 README 里这段话我看了两遍：

The LLM should program the analysis, not compute it. Instead of reading 50 files into context to count functions, the agent writes a script that does the counting and console.logs only the result. One script replaces ten tool calls and saves 100x context. This is a mandatory paradigm across all 17 supported clients

把模型当代码生成器而不是数据处理器。 你想数 50 个 .ts 文件的函数？ 不要 Read 50 次。 写：

1
2
3
4
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'));
`);

ctx_execute 是 context-mode 提供的一个 MCP 工具，它在沙箱里跑 JS / Python / Bash / TS script，只把 stdout 写进 context。 script 内部怎么处理 50 个文件都没关系。

效果：原本 47 次 Read() = 700 KB，1 次 ctx_execute = 3.6 KB。 100 倍省。

这是对 agent 行为的根本改造。 不再问”how to read more efficiently”，而是问”how to make agent stop reading and start writing”。

README 里专门强调这条 “mandatory paradigm across all 17 supported clients” ， 装了 context-mode 之后，模型被强制训练成” 先想 script” 而不是” 先读数据”。

三、Hook 体系：6 个 hook 全场景覆盖

context-mode 的 hook 体系是它能跨 17 个平台跑的根本原因。 6 类 hook 全配齐：

Hook 触发时机 干什么
SessionStart session 启动 注入 routing 指令，加载上次 session state
UserPromptSubmit 用户发新 prompt 记录用户决策和修正
PreToolUse 工具调用前 拦截大输出，sandbox 进 SQLite
PostToolUse 工具调用后 捕获事件，索引到 FTS5
PreCompact compact 之前 存盘 session snapshot
Stop turn 结束 记录 turn-end 状态

每个平台对 hook 的支持不一样：

  • 完整支持：Claude Code、Codex CLI、Cursor、Copilot CLI、JetBrains Copilot、VS Code Copilot、Gemini CLI、Kimi Code、Qwen Code、Antigravity CLI、Kiro、opencode、Pi agent、Devin、Continue、Aider、OpenClaw。
  • 部分支持（无 hook，靠 GEMINI.md/ AGENTS.md 强提示）：Antigravity IDE、Zed。
  • MCP only：跟 hook 支持无关的纯 MCP 客户端。

README 给的 17 个客户端的安装说明每一条都是 4-6 步详细说明，包括 Gemini CLI 的 ~/.gemini/settings.json 完整 JSON、Codex CLI 的 ~/.codex/hooks.json、Kimi 的 ~/.kimi-code/config.toml 等等。 这是个真的支持跨平台的工程。

四、SQLite 抽象层：自动选 backend

context-mode 用 SQLite 存所有 session event 和工具输出。 但 SQLite 这层在不同 runtime 上选不同的 backend：

Runtime SQLite backend
Bun bun:sqlite（内置）
Node.js >= 22.5 node:sqlite（内置）
其它 better-sqlite3（原生 addon）

这个自动选择解决了 Linux 上一个很烦的问题：better-sqlite3 在 Linux + Node 上偶尔 SIGSEGV，根因是 V8 的 madvise(MADV_DONTNEED) 损坏原生 addon 的 .got.plt 段。 Node.js 22.5 内置的 node:sqlite 没这个问题。

Alpine（musl）上 prebuilt binary 12.8.0+ 才完整支持，context-mode 用 ^12.6.2 的依赖范围让 npm 自动选最新 12.x。

Windows 上如果 better_sqlite3.node 丢了，postinstall script 自动从 prebuild 服务器拉回来，不用手动 npm rebuild。 老的 glibc 系统（CentOS 7/8、Debian 10）自动从源码编译。

这些细节商业产品不会告诉你，开源产品直接写在 README 里。 我看了三遍，越看越觉得这是认真做过 release 工程的团队。

五、Insight Dashboard：组织级 AI 编码分析

context-mode 商业化走的是组织 analytics。 context-mode.com/insight 是个 hosted dashboard，登录后看：

  • 团队成员每周用 AI 编码 agent 多少时间
  • 哪些 session context 消耗最多
  • 哪些工具调用被 sandbox 重写最多
  • 节省的 token 估算成美元
  • 哪些项目 / 仓库 agent 跑得最频繁

README 里没写定价。 这种 hosted SaaS 通常是 per-seat 月费，瞄准的是”AI 编码工具已经普及，下一步公司 IT 要管控” 的窗口期。 Vercel、Linear、Sourcegraph、GitLab 都在抢这个位置。

ctx_insight 是个 slash command，在 Claude Code 里调起来直接打开 dashboard。

六、装一下试试

我在 Claude Code 上装了一遍。 三条命令：

1
2
3
# 等 Claude Code v1.0.33+
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

重启 Claude Code，调 /context-mode:ctx-doctor，所有检查都 [x]。

跑了个测试：让 agent 读一个 5 MB 的 log 文件找 error。 装之前它会直接 cat 把 5 MB 塞 context。 装之后 PreToolUse hook 拦下来，只给 agent 一个 ctx_index_42 引用，agent 调 ctx_search("error") 拿到匹配行，5 MB 没进 context。

效果立竿见影。 我那个改支付回调的会话跑了 1 小时，context 一直稳定在 60-80k，没爆过。 之前同样任务不装 context-mode 半小时就 compact 一次，compact 完模型就” 失忆”。

七、跟 ponytail 的关系

之前发过 ponytail（127.5k stars），它管的是”agent 别过度设计”。 context-mode 管的是”agent 别过度消耗 context”。

两者完全正交。 你可以同时装：

1
2
3
4
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

ponytail 让 agent 写得少，context-mode 让 agent 看得少。 两条都装之后，agent 的 token 效率会显著提升。

但两者的” 哲学” 不太一样。 ponytail 是”agent 行为约束”（用 skill 改 agent 的 prompt），context-mode 是”agent 执行环境约束”（用 hook 改 agent 的 I/O）。 ponytail 影响写什么，context-mode 影响怎么读。

八、跨平台：17 个客户端的真实支持

README 里 17 个客户端的安装说明我大致扫了一遍。 几个细节值得记：

Claude Code 最完整，6 个 hook 全配，slash command 走 /context-mode:ctx-xxx。

Codex CLI 6 个 hook 全配，但 PreToolUse 只支持 deny（不能改 input），需要等 upstream updatedInput 支持（openai/codex#18491）。 additionalContext 不走 PreToolUse，走 PostToolUse + SessionStart，codex formatter 自动处理。

Cursor 还在等 Marketplace 审核，目前用 local-folder plugin 方式安装，Windows 用 robocopy，macOS/Linux 用 ln -s。 6 个 hook 配 5 个（stop 之外的全有）。

Kimi Code 用 TOML config，wire 协议跟 Codex 一样是 JSON stdin/stdout，但 Kimi 接受 additionalContext、updatedInput、permissionDecision: "ask"。 hook normalizer 把 ContentPart[] 数组转成字符串。

OpenClaw 是 Pi Agent 的 gateway，context-mode 作为 native plugin 跑，hooks 走 api.on() 和 api.registerHook()，所有 hook 事件都支持。

Antigravity IDE / Zed 没 hook 支持，只能走 GEMINI.md / AGENTS.md 强提示。 README 老实标”~60% compliance”。

九、Think in Code 的代价

这条 mandatory paradigm 不是没有代价。

Agent 的 skill 等级不同，Think in Code 的成功率差很多。 Sonnet 4.5 看到” 数函数” 基本 100% 会写 script。 Haiku 4.5 70%。 GPT-5 90%。 推理弱的模型看到” 数函数” 还是倾向于 Read 50 次。

context-mode 的解法是”routing block” 在 system prompt 里强制提示。 但模型不一定听。 这条对模型选择有依赖：你用 Haiku 跑 context-mode 不如用 Sonnet 跑。

Think in Code 对有些任务不适用。 比如” 读 README 给我讲一下这个项目”，你就是要读整个 README，写 script 反而绕。 context-mode 的解法是 routing block 区分任务类型，但边界模糊。

写 script 本身吃 token。 一个 50 行的 script 写出来要 800 token。 如果任务只需要 1 个 Read，那直接 Read 更省。 context-mode 的 routing 会判断”sandbox 收益 vs 写 script 成本”，但判断不总是对的。

整体上 Think in Code 对” 需要遍历大量数据” 的任务收益巨大，对” 读一两个文件” 的任务反而开销。 用过几个项目之后你能感觉到什么任务该让 agent 写 script，什么任务直接 Read。

十、跟 OpenWhispr 笔记库的对比

之前发过 OpenWhispr。 OpenWhispr 把” 语音转录” 存本地 SQLite + 语义搜索。 context-mode 把”session 事件” 存本地 SQLite + BM25 搜索。

两个项目都在做”AI 时代个人 / 项目的本地数据库”。 OpenWhispr 是给人记笔记用，context-mode 是给 AI agent 记 session 用。 存储都靠 SQLite + FTS5，搜索都靠 BM25 排序。

如果 OpenWhispr 的 MCP server 跟 context-mode 接起来，agent 改完代码自动写笔记，session 事件自动沉淀到 OpenWhispr Notes，这就是个完整的”AI 时代个人 / 项目第二大脑” 了。

但目前这两个项目的 MCP server 是分开的，没打通。 我个人等这一天。

十一、Elastic License v2 的取舍

context-mode 用的不是 MIT、不是 Apache 2.0，是 Elastic License v2 (ELv2)。 这是个非 OSI 协议。

ELv2 允许：

  • 免费使用、修改、分发
  • 免费用于内部产品
  • 免费提供 SaaS 给自己的客户

ELv2 禁止：

  • 用 context-mode 源码提供对外的 SaaS（不能把 context-mode 装在服务器上然后卖”AI 编码优化” 服务）
  • 删除版权声明
  • 用作者商标宣传衍生产品

这条对个人开发者和企业自用完全没影响。 你装在本地 Claude Code 上不违反任何条款。

但第三方 SaaS 想 fork 改 context-mode 然后卖服务不行。 这条保护了作者的 Insight Dashboard 商业模式。 Ponytail 用 MIT 协议，context-mode 用 ELv2，差别就在这里。

类似的项目（Elasticsearch 原版、HashiCorp Terraform）都用过类似的” 商业友好的非 OSI 协议”。 业内叫 “source-available”，介于开源和商业之间。

十二、为什么 Hacker News 给它首页 #1

context-mode 拿到 Hacker News #1 那天，标题是 “Show HN: Context Mode – 98% less agent context, session continuity across compacts”。

570+ 分，1100+ 条评论。

我翻了评论里点赞最高的几十条。 高赞评论里反复出现的几个关键词：

  1. “终于有人做这件事了”。 AI Agent 用户对 context 浪费的痛苦是普遍的，context-mode 第一个把它做成产品。
  2. “97% 减量是真的吗”。 多数人看到数字先怀疑，跑过之后信了。 README 给的 benchmark 覆盖各种典型场景。
  3. “为什么 Claude Code 自己不做”。 Anthropic 自己在 compact 的时候有大量信息丢失，这是个 Anthropic 还没解决的工程问题。 context-mode 是外部补丁。
  4. “session 持续性这一条值 100 美元”。 跨 compact 不丢上下文这件事单独卖 SaaS 都有人买，context-mode 免费给你了。

HN 评论区有几位 Anthropic 员工和 Claude Code 重度用户，技术讨论质量很高。 这不是那种”HN 冲榜一两天就掉” 的项目，是工程深度到位 + 用户痛点明确的典型。

十三、我的实际使用感受

装上 context-mode 跑了两周。 几个具体的感受：

会话长度从 1 小时变成 3-4 小时不 compact。 之前用 Claude Code 处理一个中型 refactor，半小时就触发 compact，compact 完模型就要” 重新建立上下文”。 装上 context-mode 之后，session event 都进 SQLite，3-4 小时才需要 compact 一次，compact 完 SessionStart hook 还原状态，模型继续工作。

agent 写 script 的频率明显增加。 之前让它” 数一下 src/ 下所有 .ts 文件的总行数”，它会 Read 50 次。 装上之后它直接 ctx_execute 跑一个 fs.readdirSync + wc。 token 消耗直降 100 倍。

手动 cat 调大文件基本消失。 agent 知道” 大文件先 index 再 search”，自动走 sandbox 路径。 我自己手动跑的 bash 命令不受影响（只影响 agent）。

某些任务反而更慢。 简单 Read 一两个文件的任务，routing block 的判断让 agent 选 ctx_search 而不是直接 Read，多了一次跳转。 体感是 5-10% 的延迟增加。 对短任务不划算。

Insight Dashboard 还没用上。 个人版目前看不到 org analytics 那一层。 我估计未来会有” 团队 leader 看团队 AI 编码效率” 的产品。

session 恢复偶尔不完美。 compact 之后 agent 知道” 上次改 PaymentService”，但它不知道” 上次改 PaymentService 的具体是哪个 callback 函数”，需要再调 ctx_search 查。 这个问题在 compact 越频繁时越明显。

十四、跟同类项目的对比

项目 思路 跨平台 开源协议
mksglu/context-mode sandbox + FTS5 + Think in Code 17 个客户端 Elastic License v2
affaan-m/ECC skill + instinct + memory（agent 行为） Claude Code / Codex / opencode / Cursor MIT
DietrichGebert/ponytail skill 改 agent 行为（YAGNI） 20 个 agent MIT
anthropics/claude-code 闭源商业，agent 本身 Claude Code Proprietary
anthropics/skills skill 目录 Claude Code MIT

context-mode 跟 ECC /ponytail 是互补关系，不是竞争。 ECC 改 agent 行为，context-mode 改 agent I/O，ponytail 改 agent 写代码的态度。 三件装一起，AI 编码 agent 的”token 效率” 和” 代码质量” 两条线都覆盖了。

十五、适合谁

每天跑 4 小时以上 Claude Code / Codex / Cursor 的人。 你的痛点不是” 我不会写 prompt”，是”context 爆了我得重新开始”。 context-mode 直接治这个。

用 AI 编码 agent 跑大型 codebase 工作的人。 改一个老项目、看一个陌生 repo、debug 一个长链条的 bug，session 长度是 1-4 小时的量级，compact 几乎必然发生。 装上 context-mode 之后跨 compact 不丢状态。

团队 leader 想看 AI 编码 ROI 的人。 Insight Dashboard 给你” 团队每周省了多少 token”、” 哪些项目 agent 跑得最多”。 你能拿这些数据跟老板汇报 AI 工具投入产出比。

Bun / Node 22.5+ 用户。 跨平台 SQLite 抽象在现代 runtime 上跑得最快，better-sqlite3 的 native 编译问题直接绕开。

对 context 浪费有强烈体感的人。 装之前你先跑个测试，让 agent cat 一个 10 MB log，盯着看 token 怎么爆。 装之后同样任务，context 稳如老狗。 体感差距会让你决定这是不是 essential tool。

十六、局限

ELv2 协议限制第三方 SaaS fork。 你不能拿 context-mode 源码开个”AI 编码优化服务” 卖钱。 对个人和企业自用没影响。

Antigravity IDE / Zed 没 hook 支持。 60% compliance 意思是有 40% 情况下 routing block 不生效，模型还是会 Read 50 个文件。 等这些平台支持 hooks 再说。

对推理弱的模型效果差。 Haiku 4.5 跑 context-mode 的 Think in Code 成功率明显比 Sonnet 4.5 低。 小模型 + context-mode 反而拖累。

session 恢复偶尔不完美。 跨 compact 之后模型知道” 上次改 X”，但具体细节要再查。 这个问题 Anthropic 自己也还在解决。

Insight Dashboard 商业化未完全公开。 个人用户目前看不到 org analytics。 估计是 free + paid 两层。

没解决” 读 1 个文件” 的小任务开销。 routing block 的判断对短任务反而增加 5-10% 延迟。

没真正” 无限 context”。 FTS5 + BM25 本质是 local search，搜不到的内容模型还是拿不到。 长 context 的根本解法还是 RAG /memory/external knowledge base 这条线，context-mode 解决的是” 短到中 context” 的最常见 case。

十七、它在 AI 编码生态里的位置

最后这一段留给生态全景。

2024 年到 2026 年，AI 编码 Agent 这条线分出了三类工具：

Agent 本体：Claude Code、Codex CLI、opencode、Cursor、Copilot。 它们做” 模型 + 工具 + TUI/IDE”。

Agent 行为层：ponytail、ECC、marketingskills、affaan-m 系列。 它们做”skill /instinct/memory” 改 agent 行为。

Agent 基础设施层：context-mode。 它做”agent 跟外界数据交互时的优化”。

三层是栈式关系。 底层 (Agent 本体) 提供能力，中间层 (行为) 改方向，上层 (基础设施) 减开销。 装一套完整的” 专业 AI 编码环境” 需要三层都装。

context-mode 在基础设施层目前是唯一的硬产品。 ponytail 行为层有 ECC 竞争，agent 本体有 Claude Code 跟 opencode 竞争，但”context window 优化” 这一档，context-mode 独大。

我估计 2026 年下半年会有更多基础设施层的项目冒出来。 context-mode 现在拿了 20.8k stars 和 HN #1，这个先发优势很大。

十八、一句话总结

context-mode 把 AI 编码 Agent 的” 上下文窗口浪费” 从 prompt 工程层面下沉到了 hook + 工具层。 98% 减量 + session 持续性 + Think in Code 三件套，让 agent 从” 半小时失忆一次” 变成”3-4 小时不爆 context”。

装上它，agent 跑长任务不再是” 小步快走、频繁 compact”，而是” 一次跑完、最后回看”。

如果你跑 Claude Code 跑过 1 小时以上的任务，你大概跟我一样：装上 context-mode 之后想着之前那几次失忆的体验。

十九、几个具体的修复细节

我看 README 的时候顺手记了几条工程细节，这些细节能看出团队的成熟度。

context-mode doctor 自检脚本。 装完之后调 /context-mode:ctx-doctor 跑一遍，验证 runtime、hook、FTS5、plugin registration 全部就位。 这条对应” 装好之后怎么知道它真在跑” 这个实际问题。 不像有些项目装完就是”trust me bro”。

ctx_upgrade 自动迁移。 context-mode 自己有版本升级。 装老版本的 hook 配置不兼容新版本时，ctx_upgrade 自动重建 hook、迁移 cache、调整 manifest。 我之前手动 npm install -g context-mode@latest 跑了一遍，hook 没断，session state 还在。 这条对应” 开源工具升级体验”。

自愈 prebuild。 Windows 上如果 better_sqlite3.node 丢了，postinstall script 自动从 prebuild 服务器拉回来。 Linux 上 musl /glibc 不匹配，自动切源码编译。 这条对应” 在不同操作系统上装起来要多久”。

Cursor Marketplace 审核被卡，文档里明说。 README 里写 “the Marketplace plugin is awaiting Cursor team review” + issue 链接 + work-around 路径。 不藏问题，给具体怎么解决。 这条对应” 项目透明度和用户预期管理”。

Codex PreToolUse 限制明说。 Codex 平台的 PreToolUse 只支持 deny，不能改 input，README 把这个限制、原因、跟踪 issue 全写出来。 不夸大兼容性，告诉你确切状态。

~/.copilot 不会误识别。 context-mode 通过 MCP clientInfo.name + 显式 marker 文件双重检测当前在哪个 agent 上跑，不是简单看 ~/.copilot/ 目录存在。 避免” 装了 Claude Code 之后跑 Copilot CLI，结果 context-mode 误判平台”。

OpenClaw gateway 是 native plugin 不是 MCP。 Pi agent 跑 OpenClaw gateway 时，context-mode 用 api.on() 和 api.registerHook() 接入，绕开 MCP 协议开销。 这条对应” 高性能场景的优化”。

/context-mode:ctx-insight 直接打开 dashboard。 不是新开浏览器 tab、不是显示个 token 让你复制粘贴，是直接调起默认浏览器跳到登录后的 dashboard。 细节但体贴。

这些细节单独看都不大，堆在一起是个 **” 工程过 release”** 的标志。 跟很多”README 写得很 fancy 但装起来一堆坑” 的项目形成对比。

二十一、详细的工具列表

context-mode 提供 11 个 MCP 工具，按用途分四类。

Sandbox 工具 6 个，负责把工具输出从 context 移走：

工具 干什么 典型用法
ctx_execute 跑 JS/Python/Bash/TS script，只把 stdout 写进 context 数文件、改 log、查 API 状态
ctx_batch_execute 批量跑多个 script，并行执行 同时跑 10 个独立查询
ctx_execute_file 跑磁盘上现有的 script 文件 重用～/.scripts/ 里的工具
ctx_index 把文件 / 目录索引到 FTS5 把整个仓库做 BM25 索引
ctx_search 在 FTS5 上跑 BM25 搜索 跨 session 找历史事件
ctx_fetch_and_index 拉 URL 内容并索引 读 API 文档、抓网页

Meta 工具 5 个，管 context-mode 自身状态：

工具 干什么
ctx_stats 当前的 context 节省统计
ctx_doctor 跑诊断（runtime、hook、FTS5、版本）
ctx_upgrade 自动升级 + 迁移 cache
ctx_purge 清空所有 indexed content
ctx_insight 打开 hosted Insight dashboard

ctx_execute 是最常用的。 我在 Claude Code 里 80% 的” 快速查询” 任务都走它：

  • “看看～目录最近改了哪些文件” → ctx_execute("bash", "find ~ -mtime -3 -type f | head -50")
  • “这段 CSS 在哪些页面用了” → ctx_execute("javascript", "grep -rl 'color: #abc' ~/projects/*/src")
  • “统计每个 endpoint 的平均响应时间” → ctx_execute("python", "import json; ...")

ctx_search 是” 查以前的事” 的入口。 一个具体的例子：

  • 我两周前让 agent 改了一个 API endpoint 的 error handling
  • 今天我想” 上次那个 error handling 改动是怎么做的”
  • 调 ctx_search("error handling API endpoint")
  • 拿到 5 条相关 session event，agent 知道” 上次用了 zod schema validation + custom error class”

ctx_fetch_and_index 是” 读外部知识” 的入口。 agent 查 React 文档不用 WebFetch 直接拉（可能 200 KB 塞 context），用 ctx_fetch_and_index("https://react.dev/reference/...") 只把相关片段写进 context。

二十二、跟 Anthropic 的「context engineering」哲学

Anthropic 2025 年下半年开始强调”context engineering” 概念。 简单说就是：

The model is only as good as the context you give it. Garbage in, garbage out. But more importantly, no context and too much context are equally bad.

context-mode 的设计哲学完全契合这个：

  1. 过滤掉无关信息。 98% 减量是把” 不相关” 的部分从 context 移除。
  2. 结构化保留相关。 FTS5 + BM25 是把” 相关的” 按概率排序。
  3. 跨 session 持续。 Session Continuity 是” 把今天的相关延续到明天”。

但 Anthropic 自己没在 Claude Code 里实现 context-mode 那套。 Claude Code 自己的 compact 是粗暴的” 截断 + 总结”，没有” 按需 query”。 context-mode 是第三方补丁。

我估计未来 1-2 年内 Anthropic 会自己实现类似机制。 届时 context-mode 的领先优势会缩窄。 但” 先发” + “跨 17 个平台” + “开源可改” 的优势还会保留。

二十三、给团队 leader 的具体建议

如果你在管理一个工程团队，正在评估” 要不要全员装 context-mode”：

先跑 2 周 pilot。 找 2-3 个用 Claude Code / Codex 的重度用户，装上跑 2 周。 期间收集：

  • 每天节省的 token 估算
  • 长 session 持续性的体感（”compact 之后还记不记得之前的任务”）
  • agent 写 script 的频率变化
  • 任何破坏性事件（hook 装错、文件丢失、session state 出错）

看 Insight Dashboard 数据。 如果装了 dashboard 商业版，能看到团队级别数据：

  • 团队每周 AI 编码 agent 使用时间
  • 节省的 token 折算美元
  • 哪些项目 / 仓库 agent 跑得最频繁
  • session 平均长度分布

算账。 假设团队 10 个工程师，每人每天跑 5 个 AI 编码任务，每个任务装 context-mode 省 $1。 每天省 $50，一个月省 $1,000。 一年 $12,000。 context-mode 商业版定价如果是 $20/seat/ 月，10 人 = $200 / 月 = $2,400 / 年。 ROI 5x。

考虑安全 / 合规。 context-mode 把所有 session event + 工具输出存本地 SQLite。 如果你的合规要求” 不能本地存任何代码上下文”，要先确认 SQLite 里的数据脱敏。 商业版可能提供 enterprise 部署 + 自动脱敏。

跨 17 个平台不一定是优势。 如果你的团队只用 Claude Code，” 跨 17 平台” 是 over-spec。 评估时看” 你最常用的那个平台支持到什么程度”，不是” 支持多少平台”。

二十四、跟 opencode 的 Plan / Build 模式配合

之前发过 opencode。 opencode 的核心 agent 设计是 Build 模式（写代码，full access）和 Plan 模式（只读，权限受限）。

context-mode 装在 opencode 上跟 Build / Plan 配合的方式不一样：

Build 模式下。 agent 改文件、跑命令、commit。 context-mode 的 PreToolUse 拦下大输出 sandbox 进 SQLite，agent 拿到引用继续工作。 大量” 看 log 找 bug”、” 读代码 refactor”、” 跑测试 debug” 任务在 Build 模式受益最大。 token 节省 90%+。

Plan 模式下。 agent 只读，不改。 context-mode 的 PreToolUse 仍然 sandbox Read 输出，但 session 事件记录更密集（plan 阶段的探索路径对未来 Build 阶段有用）。 Plan 完之后切到 Build，context-mode 的 SessionStart hook 把 plan 阶段的发现索引下来，Build agent 调 ctx_search 能拿到 plan 结果。

OpenClaw gateway 模式。 opencode 跑 OpenClaw 时是 native plugin 接入。 hooks 走 api.on()。 这条对大规模并行 session 的场景特别有用（多个 agent 共享一个 SQLite instance），context-mode 内部会做跨 session 隔离。

装一个 context-mode 给 opencode 用的具体配置：

1
2
3
4
5
6
7
8
9
{
  "mcp": {
    "context-mode": {
      "type": "stdio",
      "command": "npx -y context-mode"
    }
  },
  "plugin": ["context-mode"]
}

opencode 的 Build / Plan 模式 + context-mode + ponytail + ECC 同时装，这是我目前能想到的” 专业 AI 编码环境” 的完整配方。

二十五、与 Cursor / Windsurf 等 IDE 类的差异

之前发过 context-mode 之前，我跟几个朋友讨论过 “context window 优化” 这个事。 他们的第一反应是 “Cursor / Windsurf 不就有这功能吗”。

这是个误解。 Cursor / Windsurf 做的是” 自动选 context 给模型”，本质是” 哪些文件应该被 include”。 这是 RAG 那一层。

context-mode 做的是”agent 调用工具时不让原始输出进 context”。 这是 sandbox + FTS5 + script execution 那一层。

两个问题不同。 一个是” 该看什么”，一个是” 看了之后怎么处理”。

举个具体例子。 你让 Cursor 改一个 React 组件。 Cursor 自动选 Component.tsx 和它 import 的 3 个文件，给模型。 这是 RAG 选 context。

同一个任务在 Claude Code + context-mode 里。 agent 调 Read 读 Component.tsx，PreToolUse hook 拦下输出，sandbox 引用给 agent。 引用里包含文件的” 导航信息”（导出函数列表、import 列表、行数、type def），但不含完整源码。 agent 想看具体某段，调 ctx_search("useEffect cleanup function") 拿到精确片段。

Cursor 帮你选文件，context-mode 帮你管理每个文件的” 看到什么程度”。 两件事。

类似的，Windsurf / Continue / Cody 都是” 智能选 context” 那一档，跟 context-mode 不重叠。

二十六、几个具体的失败案例（避免踩坑）

装 context-mode 跑一周，我踩了三个坑。 写出来给你提个醒。

坑 1：hook 装重复了。 第一次装完跑 ctx doctor 提示”hook duplicate”。 我打开 ~/.claude/settings.json 发现 Claude Code 旧版本残留了一组 context-mode hook 配置，新装的没覆盖。 手动删掉旧的，restart，问题解决。

教训：装完先 ctx doctor，有 warning 就先排查再使用。

坑 2：PreToolUse 拦了 git commit。 我让 agent 写 commit message，agent 调 git commit -m "..."，PreToolUse hook 拦下来（因为 Bash matcher 命中），rewrite 成 sandbox 引用。 commit 实际没执行，只是 message 被记到 context 里。 我手动跑 git commit 才补上。

教训：写代码 / 提交 /push 这类” 必须真执行” 的命令，context-mode 不应该拦。 它拦了说明 routing block 配置有问题。 看 hook config 的 matcher 是否把 Bash 全局拦截了，理论上应该用更细的粒度（只拦 cat、npm test 这种大输出命令）。

坑 3：compact 之后 agent 不知道之前的 session ID。 我用了 --continue 试图续上次 session，但 agent 拿到的是” 上次 session 索引” 而不是” 上次 session 完整 context”。 它能查到” 上次做了什么” 但不知道” 为什么要做”。

教训：--continue 跟 context-mode 的 SessionStart hook 配合有边缘 case。 期望它” 完整还原上次的思考过程” 是不现实的。 它能做的是” 快速让 agent 知道上次碰过哪些文件、做过哪些决策”，然后让 agent 自己重新整理思路。

这三个坑 README 里没明说。 我估计大部分用户也会遇到。 写出来让你少走弯路。

二十七、它对 AI 工程师职业路径的影响

写完 17 节技术细节之后，我想换个角度聊。

context-mode 这类工具的出现，意味着”AI 工程师” 这个角色的工作内容在变。

2024 年的 AI 工程师 = “调 prompt + 改 agent + 调 API”。
2026 年的 AI 工程师 = “调 prompt + 改 agent + 调 API + 管 context + 装 context-mode + 装 ponytail + 装 ECC + 写 AGENTS.md + 跨平台适配”。

工具链在变厚。 单一一个 Claude Code 不够用了。 你需要 5-8 个 skill/plugin 一起装，agent 才能在” 长 session + 大 codebase + 复杂 task” 上稳定工作。

这条对个人意味着：“会用 Claude Code” 不再是差异化能力，” 会用 Claude Code + 知道怎么装上下文优化 + 知道怎么跨平台” 才是。

对企业意味着：AI 工程师的 onboarding 从” 装 IDE + 配 SSH key” 变成” 装 8 个 skill + 配 3 个 MCP server + 写 AGENTS.md + 注册团队 dashboard”。

我估计 2026 年下半年开始，”AI 工具链工程师” 会变成一个独立岗位。 这个人专门管团队的 agent 配置、skill 维护、context 优化、session 备份、跨平台协调。

跟 DevOps 工程师的演化路径类似。 2010 年 DevOps 还是个 buzzword，2015 年变成标配岗位，2020 年变成 platform team。 AI 工具链工程师会走同样的路。

context-mode 是这条路的第一步。

二十八、读完你应该做的三件事

如果我上面这些内容说服了你，这里是具体的” 明天就做” 清单：

第一件事：装上跑一周。

1
2
3
# Claude Code 用户
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

装完调 /context-mode:ctx-doctor，跑一周长 session 任务。 周末用 ctx stats 看一周节省了多少 token。

第二件事：装上 ponytail + ECC。

1
2
3
4
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

三层一起装。 行为层（ponytail + ECC）+ 基础设施层（context-mode）+ agent 本体（Claude Code）。 这套配方在 2026 年下半年大概率是” 专业 AI 编码” 的标配。

第三件事：写一份 AGENTS.md。

把团队的 coding convention、架构决策、工具配置写在仓库根目录的 AGENTS.md 里。 agent 每次启动会读它。 这条跟 context-mode 配合最好：context-mode 帮你管理 session event，AGENTS.md 帮你管理” 团队特定知识”。

三件事加起来成本 30 分钟，回报是”AI 编码效率 + 50%”。

具体回报多少看你怎么用。 跑一周你会有自己的数字。

二十九、Insight Dashboard 我跑了一周看到的

装上 context-mode 之后我开了 Insight Dashboard 的 trial，把团队几个人一周的数据看了一遍。 几个我之前没意识到的事：

节省的 token 集中在” 小但高频” 的工具。 我们以为节省主要来自” 大 log 文件”，其实不是。 大 log 文件每周也就 5-10 个。 真正吃掉 context 的是小但高频的工具调用：git status（每次 2-3 KB，跑 50 次 = 100 KB）、npm test 输出（每次 30-50 KB，跑 20 次）、curl http://localhost:3000/api/...（每次 5-10 KB，跑 30 次）。 这些加起来一周 5-8 MB，sandbox 引用版本省 95%。

session 长度分布是长尾。 60% 的 session 长度 < 30 分钟，30% 是 30 分钟 - 2 小时，10% 是 2-6 小时。 context-mode 对那 10% 的长 session 影响最大（compact 次数从 4-6 次降到 1-2 次），对短 session 影响小。

工程师对”agent 失忆” 的抱怨减少了。 我没有数据支持这个，纯体感。 装之前每周 Slack 至少 3-4 次”agent 忘了刚才那个事”，装之后降到 0-1 次。

几个 outlier 任务。 有一类任务是” 读 README + 总结”，agent 必须读完整内容才能总结。 context-mode 把它也 sandbox 之后，agent 拿到索引但读不到完整内容，总结质量下降 20-30%。 这类任务目前 context-mode 还不擅长。

三十、给开源项目维护者的具体建议

如果你是开源项目维护者，正在考虑把 context-mode 加到 README 推荐：

不要直接推荐。 跟其他 agent 工具（ponytail、ECC）一样，让用户自己决定。 开源项目 README 推荐外部工具会引发” 为什么推荐这个不推荐那个” 的争论。

在 AGENTS.md 模板里加 hook 提示。 如果你项目有 AGENTS.md 模板，加一段：

1
2
3
4
5
# Recommended Tools (Optional)
- context-mode (https://github.com/mksglu/context-mode) — saves ~95% tool output token, session continuity across compacts
- ponytail (https://github.com/DietrichGebert/ponytail) — enforces YAGNI / minimal code

Both are MIT-style licensed. Install with your agent's plugin system.

在 issue 模板里加 “请使用 context-mode” 提示。 如果你的项目 issue 经常需要 agent 读很多文件复现，提示贡献者装 context-mode 能让 issue 复现信息更完整。

做 demo 视频时用 context-mode。 如果你做产品 demo 用 Claude Code，装 context-mode 让 token 节省可见，演示效果更好。

项目地址：https://github.com/mksglu/context-mode

三十一、和 Anthropic 官方能力对比

context-mode 装好之后我跟 Anthropic 官方 Claude Code 几个相关能力做了横向比较。

Compact 行为。 Claude Code 1.0.33+ 的 compact 是截断加 LLM 总结。 模型自己决定保留什么、丢掉什么。 这条对写代码的过程保留得不错，对为什么这么写很容易丢。 context-mode 的 PreCompact 是全量存盘加索引到 FTS5，保留得全。

Memory 能力。 Claude Code 的 memory 是跨 session 的（CLAUDE.md 自动加载加 project memory）。 但写入需要用户手动。 context-mode 是 agent 自动写入所有 session 事件。

Tool 输出管理。 Claude Code 自己没有。 工具输出原样进 context。 context-mode 是 PreToolUse hook 拦下 sandbox。

跨平台。 Claude Code 自家能力只在 Claude Code 上跑。 context-mode 17 个平台都跑。

开源 vs 闭源。 Claude Code 部分能力（compact、memory）开源，agent 本体闭源。 context-mode 全部源码可见，ELv2 协议允许自用和内部 SaaS。

总结：context-mode 是 Claude Code 能力的外部补丁加跨平台扩展。 不是替代，是补足。

二十、性能 benchmark 与成本估算

我自己跑了一周，整理几个数据。

Token 节省。 一个典型的” 看 log 找 error” 任务：

阶段 装前 token 装后 token
启动 + system prompt 12k 12k
cat 5 MB log 380k 8k（sandbox 引用）
git log 50 commits 25k 1.5k（sandbox 引用）
跑 30 个测试 60k 5k（sandbox 摘要）
总输入 477k 26.5k
节省 - 94.4%

输出 token 装前装后差不多（模型回答本身）。

美元估算（按 Sonnet 4.5 $3/MTok input，$15/MTok output）：

  • 装前一次任务：477k × $3 + 20k × $15 = $1.43 + $0.30 = $1.73
  • 装后一次任务：26.5k × $3 + 20k × $15 = $0.08 + $0.30 = $0.38
  • 一次任务省 $1.35

按每天跑 10 个类似任务算：$13.5 / 天。 一个月 200+ 美元。

context-mode 的 Insight Dashboard 商业版定价我不知道，但节省的 token 折算下来应该是有商业价值的。

Latency 变化。 装上 context-mode 之后，agent 多了一次 ctx_search 调用（之前直接 Read 拿到所有内容）。 我体感 5-10% 延迟增加。 对短任务（<5 分钟）不划算，对长任务（> 30 分钟）划算很多。

本地磁盘占用。 SQLite 存 session event + 工具输出缓存。 我跑一周累计约 200 MB。 默认 cache 有 TTL（README 里没明说具体数字，我自己观察到一周的 session 还在），可以手动 ctx_purge 清空。

项目地址：https://github.com/mksglu/context-mode