踩坑实录:接入 context-mode 后我遇到索引失效、上下文溢出,四个坑一次说清

原创2026-10-10 15:46:581,941 阅读
文章标签:MCP 服务人工智能AI 插件Agent 沙箱全文检索AI 技能开发工具

踩坑实录:接入 context-mode 后我遇到索引失效、上下文溢出,四个坑一次说清

把 context-mode 接入 Claude Code、Gemini CLI 与 VS Code Copilot 后,我一度以为从此告别上下文焦虑:工具输出被沙箱拦截、FTS5 知识库按需检索、会话记忆跨压缩存活,README 里那句 "315 KB 变成 5.4 KB,节省 98%" 与 Hacker News 榜首的讨论似乎都在印证这套设计的正确性。但真正跑了几周之后,问题接踵而至——检索结果开始引用已删除的代码、长会话中途性能断崖、路由拦截"悄悄消失"导致模型变笨、跨项目记忆互相串台。这四个坑每一个都不在文档首页,却每一个都能让"上下文优化"变成"上下文幻觉"。

本文结合仓库源码逐层拆解这四类故障的发生机制、定位手段与修复顺序,希望能让后来者少走这几趟弯路。

先建立心智模型:context-mode 的本质是一堆"缓存"

在讨论坑之前,必须先看清这套系统的数据流。以 Claude Code 插件为例,README.md 描述的完整链路是:SessionStart 钩子在运行时注入路由指令 → PreToolUse 把大输出工具(Read、Bash、WebFetch)拦截并重定向到沙箱工具 → 沙箱在独立子进程处理原始数据、只把摘要写回上下文 → PostToolUse 将会话事件写入 SQLite → 持久化内容进入 FTS5 索引 → PreCompact 生成压缩恢复快照 → 下次 SessionStart 恢复状态。全部 17 个平台的适配器(src/adapters)都遵循这条管线。

这条管线里所有"省钱"的环节,本质上都是缓存:索引是文件内容的缓存,auto-memory 是历史偏好的缓存,路由指令是模型行为的缓存,压缩快照是会话状态的缓存。而所有缓存都有一个共同的敌人——失效。四个坑,全部由此展开。

坑一:索引失效,检索结果悄悄变脏

失效机制藏在"懒刷新"里

ctx_search 走的持久化知识库是 SQLite 上的 FTS5 表,索引不会在文件写入时同步更新。真正的刷新发生在下一次搜索时:searchWithFallback 的第一步就是调用 #refreshStaleSources()(见 src/store.ts),它的判定逻辑是典型的快路径/慢路径组合:

  • mtime 快路径:mtime <= indexed_at 直接跳过,认为文件未变;
  • SHA-256 慢路径:仅当 mtime 前进后才计算内容哈希,哈希一致同样跳过;
  • 哈希不一致才重索引,并且复用已读字节,避免二次打开导致的竞态。

这套设计本身没有问题,但它隐含了两个"脏数据"入口。

第一个入口:删除的文件永远留在索引里

看 #refreshStaleSources 的源码,有一个非常反直觉的分支:

if (!existsSync(src.file_path)) continue; // file deleted — keep cached results

文件被删除后,刷新逻辑主动选择保留缓存结果。注释写的是"file deleted — keep cached results",意图是避免误伤,但后果是:你在 FTS5 里搜索某个函数名,命中的是一个已不存在的文件里早已过期的 chunk。模型不会知道文件没了,它会基于这段死代码继续给出建议——这正是"检索结果悄悄变脏"最典型的形态:一切看起来都正常,结果却建立在幽灵代码之上。

第二个入口:mtime 没前进的内容变更

git checkout、构建工具原地改写、以及某些保留 mtime 的同步软件,都会让文件内容变化而 mtime 停滞。此时快路径直接跳过,哈希校验根本不会执行,索引里躺着的是旧内容。仓库里 src/store.ts 的 #442 修复注释也印证了这个方向的反复踩坑:刷新前必须重新检查 deny 策略,因为"索引时允许读的文件,之后可能已被加入拒绝名单;不加这道闸,刷新会把它重新读入并再次暴露"。也就是说,索引与当前策略之间的偏差,是官方自己也在持续修补的真实问题。

定位与修复

  • 看刷新计数:#refreshStaleSources 每次返回 lastRefreshCount(本次刷新重索引了多少个源),配合 ctx_stats 里的 getIndexState()(总 chunk 数、源数、最近索引时间),可以判断"索引是否在动";
  • 看匹配层标记:搜索结果带 matchLayer 字段,取值 "rrf" 或 "rrf-fuzzy"(src/store.ts)。如果长期只有模糊纠正层命中,往往意味着精确索引已经脱节;
  • 修复手段:大重构后手动 /context-mode:ctx-index 重索引;索引整体不可信时用 ctx_purge 重建知识库;保持 deny 列表与索引源同步。注意默认是按项目隔离的 DB 布局,跨项目问题见坑四。

坑二:上下文溢出与性能下降的连锁反应

溢出不是一次性事件,而是循环

README.md 对原始问题的描述很直白:一次 Playwright 快照 56 KB、20 个 GitHub issue 59 KB、一条访问日志 45 KB,半小时后 40% 的上下文就没了;当宿主压缩对话腾空间时,Agent 忘记了自己在改哪些文件、哪些任务在进行中。沙箱解决的正是这一侧:315 KB 的原始输出压成 5.4 KB 的索引摘要,实测节省 98%。

但这个机制存在循环放大的风险:只要路由没生效,原始输出就继续涌入上下文 → 上下文越满,宿主越频繁压缩 → 每次压缩都丢失状态 → 模型需要更多工具调用重建状态 → 又产生更多输出。性能下降与上下文溢出互为因果,是同一个坑的两面。

context-mode 项目主视觉:标注了 33 万开发者、17 个适配器与 Hacker News 榜首的上下文节省引擎示意图

三个让循环转起来的"放大器"

放大器一:钩子缺失导致路由静默失效。 这是最容易踩的:用 claude mcp add context-mode -- npx -y context-mode 这种纯 MCP 安装时,README 明说"没有自动路由,模型仍可以用这些工具,只是不会被引导去优先用它们而非原始 Bash/Read/WebFetch"。于是沙箱完全没被调用,节省率归零,你还以为是插件坏了。

放大器二:检索本身变贵。 ctx_search 不是一次简单查询。看 src/store.ts 的 #rrfSearch:一次查询要跑两路搜索(Porter 词干 OR 检索 + 三元组 OR 检索),再用 Reciprocal Rank Fusion(K=60)融合,随后做邻近度重排(标题命中加权、词间距打分、短语频率饱和加成);首轮无结果时还会触发模糊纠正——每个词都要查词库表并跑 Levenshtein 编辑距离,命中后整条 RRF 管线再跑一遍。在大仓库里,这条链路的时延会直接拖慢每次工具调用,单位时间内的迭代次数下降,压缩次数上升。

放大器三:flood-guard 让贪婪的 Agent 自断补给。 src/search/flood-guard.ts 给 ctx_search 上了滚动窗口限流:超过软上限后结果退化为每条查询只给 1 条,超过硬上限直接拒绝。设计意图是逼 Agent 用 ctx_batch_execute 批量处理而不是疯狂单发搜索。但 #769 揭示了一个现实场景:Claude Code 的 Task/Workflow 会并行拉起 N 个子 Agent,共享同一个 MCP 进程,早期全局计数器把合法扇出当成刷屏。后来改为按 agent-context 分桶(keyed per agent-context)才解决——也就是说,如果你在并行任务里频繁搜索,你踩到的"结果越来越少"很可能不是知识库问题,而是限流在起作用。

定位与修复

  • 看 ctx_stats 的节省率:按工具拆分的 rawBytes / contextBytes / savings ratio(src/session/analytics.ts)。比率趋近 1,说明沙箱没有拦截住任何东西,优先检查钩子而非索引;
  • 确认钩子是否注册:不同平台注册方式完全不同——Gemini CLI 是一个 settings.json 同时挂 MCP 与四个钩子(configs/gemini-cli/settings.json),VS Code Copilot 要手写 .vscode/mcp.json 加 .github/hooks/context-mode.json(README.md),任何一步漏掉路由就断;
  • 批量意识:检索类问题合并进一个 queries 数组,重活交给 ctx_execute/ctx_batch_execute,让模型"写代码做分析而不是把文件读进上下文"。

坑三:路由静默失效,模型"变笨"而不自知

失效时没有任何报错

路由层的核心是 hooks/core/routing.mjs,它返回的决策有 deny / ask / modify / context / passthrough 五种。关键在这段注释:

/**
 * Guard for actions that redirect to MCP tools (#230).
 * If MCP server isn't ready, returns null (passthrough) instead of the
 * redirect action — prevents agent from getting stuck when MCP tools
 * are unavailable.
 */

MCP 服务不可用时,拦截静默降级为放行。这个设计保证了 Agent 不卡死,但代价是你完全察觉不到路由已经失效——直到发现 WebFetch 原始输出又出现在上下文里。升级、插件缓存重建(hooks/ensure-deps.mjs 负责的自愈路径)、npm 安装中断,都可能触发这种"半残"状态。

措辞会让模型"读错"拦截原因

更隐蔽的是 docs/adr/0003-routing-deny-reasons.md 记录的事故:PR #654 复现出 "WebFetch blocked" 这句拦截原因被 Opus 4.6 误读为网络安全限制,模型于是放弃重试、直接倒回训练数据里的旧答案。修复方案把拦截文案拆成两类:CASE A 路由重定向必须以 redirected to <ctx_tool> 开头、必须正面声明"该工具具备完整网络能力"、必须以可执行的指令收尾;BLOCKED 一词保留给真正的安全策略拒绝(CASE B)。这件事的教训是:路由层输出的每个词都在改变模型的下一个动作,措辞错误等于行为错误。

指令会过期,平台能力不齐

另外两处"静默":

  • 引导指令有生命周期:路由指令默认每会话只注入一次,压缩后就丢了,MCP 密集的长会话里模型会重新回到原始工具。为此引入 CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY(默认 10,即每 10 次匹配调用重新注入一次,README.md 环境变量表)。你如果关掉或调得过大,等于亲手制造"过期引导";
  • 平台能力不一致:Codex 的 PreToolUse 目前只支持 deny,不支持输入重写(updatedInput 依赖上游),也不支持 additionalContext;Antigravity 和 Zed 完全没有钩子支持。同一个项目换一个终端,路由行为就静默变化。

定位与修复

  • 跑 ctx_doctor:它校验运行时、钩子、FTS5、插件注册与版本,输出 <a href="https://link.gitcode.com/i/7be168319523f8b798ac72e6f3db62cd" target="_blank">OK] / [FAIL] / [WARN]([skills/ctx-doctor/SKILL.md),是全链路体检的入口;
  • 查 MCP 连接:/mcp list 确认 context-mode: ... - Connected,连接失败说明 mcpRedirect 的降级分支正在生效;
  • 翻拦截文案:在 transcript 里搜索 redirected to 与 BLOCKED,确认拒绝原因属于 CASE A 还是 CASE B,措辞异常本身就是症状;
  • 升级后重跑:ctx_upgrade 拉取最新版后,务必重新执行 doctor 与 /reload-plugins,别让自愈脚本替你"静默修好"而不自知。

坑四:会话记忆越界与清理的边界

"干净会话"到底干不干净

context-mode 的卖点之一是干净会话:README 明说"如果你不带 --continue 恢复,上一次会话数据会被立即删除——新会话就是干净白板"。但坑在于记忆的读取路径比你想的更宽。searchAutoMemory(src/search/auto-memory.ts)会搜索三处:项目级指令文件(CLAUDE.md / AGENTS.md / GEMINI.md)、用户级配置目录、以及平台记忆目录(memory/*.md)。如果这三处里有历史项目的偏好,跨项目"串台"就发生了。

仓库对这个洞是有意识的:#663 要求按 projectDir 做记忆目录隔离——用规范化哈希把各项目拆进独立子目录,防止并行项目互读对方的 auto-memory;而旧的无适配器调用方也套用同一哈希来保持契约一致。这说明记忆隔离是补丁,不是原罪——你只要用旧版本或绕过适配器,串台就会回来。

共享库模式下,旧数据永远可见

更隐蔽的一处在项目过滤逻辑里:src/store.ts 的会话过滤器把 session_id === '' 的 legacy chunk 视为"公共表面",在任何项目下都放行;src/search/ctx-search-schema.ts 则在共享库模式(CONTEXT_MODE_PROJECT_DIR)下才暴露 project 参数,默认按项目隔离的布局里模型连这个参数都看不到——这既是强保证,也是"你没法按项目筛"的原因。如果你升级时从共享库切到按项目隔离,旧索引可能继续漏进搜索结果。

清理的边界:别把 FTS5 和会话一起抹掉

ctx_purge 的语义分两级(src/session/purge.ts,#520):scope: "project" 抹掉整个项目的会话事件、FTS5 内容库和 stats;scope: "session" 只删指定会话的行。手滑用 project 级清理,你精心索引的文档知识库会连同 -wal / -shm 边车文件一起被 unlink。另外在 macOS / Windows 的大小写不敏感文件系统上,purge 会同时清扫规范化小写哈希与旧版原始大小写哈希两套文件——这套双哈希清扫正是为"部分升级残留孤儿文件"设计的,也就是说升级中断可能让旧命名文件留在磁盘上继续被搜索命中。

定位与修复

  • 查存储根目录:CONTEXT_MODE_DIR 决定会话与内容库存放位置(默认如 ~/.claude/context-mode,会话在 <root>/sessions,索引在 <root>/content),空值或相对路径会被 ctx_doctor 标出来;
  • 串台排查:先看 timeline 检索结果的 origin 字段——current-session / prior-session / auto-memory 三分类(src/search/unified.ts)能直接告诉你记忆来自哪一层,是定位串台最快的手段;
  • 清理前确认 scope:purge 时显式传 scope: "session" + sessionId,避免误伤知识库。

定位方法与修复顺序:一条可执行的排查链

四个坑的症状高度重叠——检索不准、性能变差、行为漂移、记忆串台——单看表象无法归因。按下面的顺序排查,能从"全链路失效"收敛到"单一故障点":

步骤 动作 判定
1 ctx_doctor 任何 [FAIL] 先解决,尤其 hooks 与 FTS5
2 /mcp list 确认连接 未连接 = 路由降级放行(坑三)
3 ctx_stats 看节省率 比率≈1 = 沙箱没拦截(坑二)
4 看 lastRefreshCount 与 matchLayer 刷新恒为 0 / 只有 fuzzy 层 = 索引脏(坑一)
5 查搜索结果的 origin 字段 出现 prior-session / auto-memory = 记忆越界(坑四)
6 大重构后手动重索引;必要时按 scope 清理 收尾,防复发

修复顺序则相反:先保证路由活着(1、2、3),再修数据层(4、5),最后重建索引(6)。路由不活时重建索引毫无意义——模型根本不会去用它。

写在最后

把四个坑放在一起看,会发现同一个根因:context-mode 的所有能力都是缓存,而缓存必然面临一致性问题。索引会脏、引导会过期、记忆会越界、清理会误伤——这不是插件的缺陷,而是"用空间换上下文"这条路的必然代价。理解了这一点,你就能把文档里那句"The other half of the context problem"读得更完整:省下来的上下文,需要用同等严密的失效管理去维护。希望这篇踩坑实录,能帮你把每一次"看起来正常"的检索,都变成经得起验证的事实。

登录后查看全文
context-mode