有段时间我在维护一个自动化文档助手，用户反馈最多的不是功能缺失，而是“AI莫名自信”：它明明没有我仓库里的最新代码，却能斩钉截铁地告诉我某个函数已被弃用；明明没读某个文件，却引用了一段旧版注释当依据。我查日志时发现，它把几轮之前一段被否定的临时想法当成了长期事实，又混进了另一个项目的缓存片段。那次排查之后，我给工具加了一个“context-mode”，也就是上下文模式，一个能实时显示模型正在使用哪些信息的调试面板。打开之后，所有迷雾都清楚了。
所谓context-mode，就是把“喂给模型的信息清单”可视化。它不是什么玄学概念，简单说，就是让你能看见AI“在想什么”。它可以显示当前对话历史、被检索进来的文件片段、系统提示词、记忆单元、工具返回值，甚至已经过滤掉的敏感片段。对AI辅助编程、智能问答、文档助手这类工具来说，这个模式的价值不在于炫技，而在于把黑盒变成白盒。
它能解决的问题非常直接：
- 回答引用了不存在的文件或过时依赖时，快速定位脏上下文来源；
- 调试提示词时，确认关键指令是否真的被传进模型；
- 评估调用成本时，看清每条上下文占了多少Token预算；
- 复现用户反馈的“乱回答”问题时，确认是上下文组装出错，还是模型推理出错。
这篇文章想覆盖一条完整链路：先从底层讲上下文是怎么被组装的，再讲context-mode面板的设计与实现，然后结合实际经验讲调试方法和常见坑。无论你是AI工具的普通用户，还是正在做插件、做助手的开发者，都能从中找到可以落地的部分。
1. context-mode是什么：从一次“幽灵引用”事故说起
1.1 一次让我决定做context-mode的故障排查
当时的情景是这样的：某用户问我的文档助手“某模块的配置项为什么没生效”，助手给出了一个看似合理的解释，说该模块读取了config.yaml里的retry_count字段，并引用了一段“源代码”作为证据。但我核查后发现，那行代码来自用户两周前上传的临时草稿文件，而且字段名是retryCount，根本不是retry_count。
助手怎么会拿到这份草稿？我追查了当时的上下文组装日志，发现原因是：该草稿文件在矢量数据库里被较早插入，检索阶段跟用户当前问题“配置不生效”的向量相似度很高，被排进了Top 5。再加上对话历史里有一轮用户确实提过retry_count这个写法，模型就把“草稿里的旧代码”和“对话里的旧字段名”缝合在了一起。
如果没有一个能随时查看“模型看到了什么”的模式，这类问题只能靠猜。所以context-mode的第一使命不是展现“AI的思考过程”，而是展现“AI的输入材料”。这两者差别很大：前者会误导人以为模型真的有“推理过程”可以展示；后者则是确定的、可审计的、可回滚的。
1.2 上下文模式里到底能看到什么
我用过的几种实现方式，信息组织大同小异：
| 信息类型 | 来源 | 典型展示形式 |
|---|---|---|
| 系统提示词 | 开发者预设 | 可展开的密文/纯文本 |
| 对话历史 | 会话记录 | 按轮次折叠的对话列表 |
| 检索片段 | 矢量库/Bug报告/文档库 | 文件名、行号、相似度评分 |
| 文件快照 | 当前打开文件/变更文件 | 文件路径、摘要、片段预览 |
| 记忆单元 | 长期记忆模块 | 键值对、创建时间、置信度 |
| 工具结果 | 代码搜索、命令行、API返回值 | 执行命令、返回摘要 |
一个合格的context-mode面板，至少要能回答三个问题：这条上下文是哪来的？占了多少Token？在模型眼里有多重要（排序权重）？如果做不到这三点，那它只是一个“文件预览器”，不是真正的上下文调试器。
1.3 谁需要context-mode
我做context-mode之后的体会是，它会改变三类人的工作方式。
第一类是AI工具开发者。上下文组装是AI应用的一大块复杂逻辑，没有可视化，你连调优都无从下手。第二类是重度使用AI辅助编程的开发者。他们需要判断“为什么这次回答方向偏了”，而不是无脑重试。第三类是负责评估系统效果、做质量回归的测试人员。他们可以用context-mode快速标注一次回答的“上下文质量分”。
如果你只是偶尔用AI查个资料，那context-mode未必对你有直接价值。但一旦你开始依赖AI完成复杂任务，早晚会遇到“AI用你没让它用的信息回答你”的问题，那时候你就会明白这个模式存在的意义。
2. 上下文组装的核心机制：从原始输入到最终Token
既然要理解context-mode，就不能只看它表面的展示层，得先搞清楚上下文本身是怎么被组装出来的。
2.1 一条完整提示词的四个来源
模型每次生成，拿到的不是用户敲的那句话，而是一个被打包好的提示词结构。我拆解过的绝大多数实现，都包含下面几层：
- 系统提示词（System Prompt）：固定的角色设定、输出格式、工具使用规则。这一层最稳定，但也最容易被开发者忽视。我见过不少项目把50条规则塞进系统提示词，结果上下文窗口被占掉四分之一。
- 对话历史（History）：最近几轮用户消息和助手回复。一般会做截断，保留最近的10~20轮，并按时间倒序排列。
- 检索结果（Retrieval）：从外部知识库、代码仓库、内部文档里检索出来的片段，通常带文件名、页码范围、相似度分数。
- 空间状态（Scratchpad / Memory）：临时变量、任务列表、长期记忆中的相关条目，这部分在Agent类应用里尤其重要。
这四个来源各自独立，但最后会被拼成一串文本。拼的方式看起来简单，效果差异却很大。
2.2 检索排序与Top-N截断：上下文不只是“越多越好”
我见过一个很普遍的错误——把检索到的前20条相关性结果全塞进上下文，理由是“反正模型能处理长文本”。这造成的后果很典型：无关内容稀释了关键信息，模型回答变得又长又虚。
正确的做法是“检索-压缩-截断”三步走：先用混合检索拿到候选，再按类型做去重、压缩、合并，最后按Token预算截断。混合检索一般指同时用关键词检索和向量检索，常用策略是把两路得分做加权，比如向量相似度占0.6、关键词命中占0.4，再取加权后的Top 5~10条。
压缩阶段有几种实用技巧：
- 太长的片段只保留“核心段落+首尾句”，防止切断关键结论；
- 同文件的多段命中合并成一条，用文件名+开始行号作为龙头；
- 重复内容按哈希去重，避免同一种事实被塞进去三遍。
截断阶段则要遵循“头尾占据、中部可丢”的原则。我实测下来，每条检索结果如果超过200个Token，末尾部分的作用会急剧下降。所以在context-mode里，我会把“这条片段被截断了多少”也统计出来，这是判断信息完整度的重要指标。
2.3 Token预算与排序策略：像一个行李箱，先放必需品
上下文组装可以类比成一个行李箱的收纳过程。你有一个固定容量（模型上下文上限），要放的东西有优先级：系统提示、工具定义、关键文件、对话历史、检索片段。
我常用的优先级是：
- 系统提示词中的核心指令（必须完整）；
- 当前请求的核心参数（比如用户刚指定的文件路径、命令）；
- 与当前请求最相关的前3条检索结果；
- 最近2轮对话；
- 更早的历史、旁支检索结果、工具调试信息。
关键是这样定优先级后，当预算超限，最先被裁剪的是低优先级内容，而高优先级内容完整保留。这比“把超长对话直接截断尾部”要合理得多——因为真正决定回答质量的核心信息，往往在对话中部，而不在最后。
在context-mode面板里，我会给每条上下文标出一个“是否被截断”的红点，以及一个“当前优先级”的标签。装行李的人最怕不知道哪件衣服被挤在了最底层，面板就是干这个的。
2.4 缓存与记忆的“时间炸弹”
上下文组装里最隐蔽的问题是缓存。很多实现为了降本会做“前缀缓存”，也就是把系统提示词和对话历史的前半段固定住，只把新的部分传进去。这在性能上是好事，但有个致命隐患：如果素材更新了，缓存里的旧版本却还在继续被使用。
我遇到过一种典型情况：用户修改了某个配置文件，但工具还带着缓存里的旧配置回答“你当前使用的是旧参数，修改后需要重启”。究其原因，是缓存键没包含文件的修改时间。解决方案其实很简单，在上下文对象上维护一个内容哈希，缓存命中时校验哈希，不一致就强制失效重读。
这个细节放进context-mode里，就是每条上下文要显示更新时间，甚至显示“基于缓存快照”还是“基于实时读取”。别小看这一行标注，调试时能帮你省掉大量翻日志的时间。
3. 让上下文可视化：context-mode面板的设计与实现
有了底层机制，接下来就是把它们呈现出来。这一部分我会分享我实际搭建一个面板时的架构思路和踩坑记录。
3.1 整体架构：事件驱动，而不是轮询对比
我最初的做法是让前端每两秒拉一次后端状态，拿到完整上下文列表再整体渲染。结果在长对话场景下，既浪费流量，交互也卡顿。后来改成了事件驱动的架构，数据流变成：模型调用层在每次“即将发送提示词”和“接收完响应”时，各抛出一个上下文快照事件。
快照事件携带的数据结构大致如下：
{ "trace_id": "55f0c8", "context_units": [ { "id": "u1", "type": "system_prompt", "source": "builtin", "token_count": 210, "priority": 1, "status": "included", "meta": { "version": "v3" } }, { "id": "u2", "type": "retrieved_chunk", "source": "docs/doc1.md#L12-L34", "token_count": 320, "priority": 3, "status": "truncated", "similarity_score": 0.82, "ref": "vector_db_chunk_id" } ], "total_tokens": 6120 }前端只做两件事：收到事件就更新本地状态，状态变化就触发按需渲染。这样用户不需要“刷新页面”就能看到“本次生成用了哪些上下文”，整个面板像是贴在模型调用链上的一个实时监视器。
3.2 数据模型与UI布局：信息密度要压得住
面板的UI布局，我试验过三版，最终固定成左中右三段式：
- 左侧是“上下文来源列表”，按来源类型分类，可以折叠；
- 中间是“详情区”，选中某条来源后展示逐条内容，比如文件路径、命中行号、命中文本、截断状态；
- 右侧是“审计信息”，包括Token占比、优先级、缓存状态、相似度评分。
三个区各司其职，避免把所有信息平铺在一个页面里给人“满屏乱码”的压迫感。实际使用中，用户最常用的动作不外乎三种：看“这次有没有把某文件加进去”、看“哪条来源占了最多Token”、看“某片段为什么被截断了”。所以我把这三个动作对应的信息都放到了不需要滚动超过两屏的位置。
3.3 两个容易踩的渲染坑
第一次做面板时，我踩了三个典型的坑，值得分享给要做类似功能的人：
坑一：整树渲染导致丢焦点。原始方案是每次事件到达就重建整个列表，结果用户正在点击“展开某条片段详情”，焦点被强制重置，展开状态全丢。改成按条目更新后，只更新状态变化的节点，问题消失。
坑二：Token数统计口径混乱。不同模型的分词器不一样，有的按字符近似，有的按词元精确计数。我一开始直接用字符串长度除以4来估算，结果跟实际发送给模型的Token数差出30%。后来统一改成调用模型自带的分词器做精确统计，并在面板标注“统计口径”。
坑三：长度极高的片段渲染卡顿。检索结果里有不少整篇文档级别的大块头，直接渲染字符串列表，长上下文场景下滚动能感觉到掉帧。解决办法是主要列表用虚拟滚动，只有当前选中项才渲染全文。
3.4 可操作项：不只是“看”，还要能“干预”
只读的面板价值有限，我把“干预”做成了面板的杀手锏功能。
操作项分三个级别：
- 弱干预：临时标记“此来源忽略”，也就是本次生成不再使用该片段；
- 中干预：手动调整该来源的优先级排序，强制让某条片段排到前面；
- 强干预：直接编辑该片段内容再重新生成，既改上下文，也改模型依据。
这三个操作都会触发一次新的生成，同时把变更记录写入审计日志。这样用户可以现场“做实验”：去掉某条可疑片段再生成一次，如果回答变了，那问题大概率就出在这条上下文里。
对使用者来说，这比“重新描述一遍问题”高效得多，因为问题可能根本不在用户描述，而在上下文组装。
4. 实战中的噪声治理：context-mode暴露出来的一堆问题
context-mode最令我意外的价值，不是“发现问题”，而是“发现问题长什么样”。接入面板之后，我在短时间之内归纳出了一系列高频噪声模式，这里挑几条最有代表性的讲。
4.1 项目代码的“肥胖病”：往上下文里塞整个仓库
我先说一个最普遍的问题：检索阶段不小心把整个仓库的代码地图塞了进去。很多向量检索方案会把源码切块后全部入库，一旦命中了一个热门符号，相关的几十个文件片段都会被拉进上下文。
context-mode帮我看清了这一点：在某个只有几万行代码的小项目里，一次普通提问居然带进来了37个代码片段，Token总量接近2万。回答质量并没有因此提高，反而因为无关代码太多，模型频繁生成了“推荐你用另一个模块的API”这种发散回答。
我后来的处理方式是引入“路径感知的倒排过滤”：片段入库时记录所属目录，检索时按用户当前工作的目录做一次过滤，同目录外的代码片段最多取2条，其余直接不参与。这个改动对回答准确率的提升，比增加检索结果数量明显得多。
4.2 会话记忆的“回音壁”：旧共识覆盖新事实
第二条高频问题来自会话记忆。助手会把历史对话中的重要结论写进长期记忆，这本是个好设计。但问题在于：一条记忆一旦写入，权重就长期偏高，即使后来用户明确否定了它，旧记忆仍然排在所有新材料之前。
我用context-mode抓到一个典型案例：用户在第一轮说“我准备用A方案”，助手把“A方案”记成了长期偏好。一个小时后用户在第三轮说“算了，A方案不行，我们改用B”。到第五轮提问时，模型却仍然优先引用第一条记忆说“根据你之前的偏好，我推荐使用A方案”。
这个问题本质上是“记忆置信度没有被更新”。我后来在记忆模块加了一条规则：当用户对关键实体做了显式否定时，将该实体相关的记忆置信度减半，并在上下文中插入一条“拒绝记忆”记录，权重设为负。context-mode面板里要能看到这条负权重记录，用户才能理解“为什么这次助手不再提A方案”，否则看着像玄学。
4.3 不该进来的敏感信息：权限与脱敏的一层薄纱
第三个问题让我意识到，上下文面板不仅是调试工具，在某种程度也是合规探针。有一次测试人员故意问助手“读取密钥”，助手回答说“没有相关权限”。但context-mode显示，检索到的片段里其实包含一段写有明文密钥的日志内容，只是模型在生成时“忘了”引用它。
这就很危险：模型没有引用，不代表信息没有进入上下文。如果模型恰好结合上下文里的密钥猜测出正确值，那一次安全意识再强的回答也挡不住数据已经过境的事实。
我建议所有做AI工具的团队，把“检前过滤”和“生成后审计”作为两道闸门：检索结果进入上下文之前，先跑一遍正则和敏感词过滤器；生成完成之后，再对实际进入上下文的文本做一次离线扫描，确认没有敏感信息漏网。context-mode应该把这两道闸门的状态都摆出来，而不是等到用户自己测出来。
4.4 一套可复用的上下文调试方法
结合上面的案例，我总结了一套复用性很强的调试流程，取名为“上下文体检三步走”：
- 复现提问：打开context-mode执行同一条问题，截图上下文快照；
- 剥离变量：依次删除“记忆单元”“历史对话”“检索片段”三大类来源，看回答有没有显著变化，用“可控变量法”定位关键来源；
- 最小化重构：把最终能保持回答质量的那几条上下文固定成模板，作为后续该类型问题的基础上下文。
这套方法不依赖具体框架，任何有context-mode的AI工具都适用。我多次靠它把一个“看起来是模型问题”的问题变成“一个上下文组装顺序的问题”，后者的修复成本往往低一个数量级。
5. 扩展思路：从透明走向协同的上下文工作流
面板做完以后，我开始思考它的下一个形态，因为本质上“可视化”只是第一步，价值更大的是“让用户和AI共同管理上下文”。
5.1 让用户直接编辑上下文
目前多数AI工具把上下文组装完全交给系统，用户只有“重新提问”这一招。但在复杂的开发场景里，用户往往比任何算法都更清楚哪些文件当前重要、哪些历史根本不相关。
我在新版本中做了一个实验功能：允许用户在提问发出前，用类似“置顶”“忽略”“拖走”的手势直接调整上下文清单。结果使用频率非常高，尤其在看文档相关代码时，用户会把当前正在写的文件置顶，把检索出来的下一级依赖直接忽略。
这个机制可以叫“显式上下文偏好”，它跟系统自动组装形成互补。用户表达偏好越明确，模型回答的稳定性就越高。context-mode自然就成了这个交互的场所。
5.2 把上下文导出为团队可读报告
团队协作中，我最常收到的一句反馈是“我不知道这个回答是基于什么依据”。context-mode提供了依据列表，但它是机器视角的。
我做了一个导出功能：每次关键生成本结束时，把上下文快照导出为可阅读的Markdown报告，包含“本次使用了哪些文件”“哪些片段被截断”“Token分配占比”“存在什么风险项”。测试团队可以直接把报告附在Bug单里，就不需要反复录屏或用语言描述“为什么它会引用那段代码”。
这个功能上线后，跨团队沟通成本下降得意外明显，因为在报告里一眼就能看出“是上下文缺失，不是模型幻觉”这类结论。
5.3 下一步：主动推荐上下文调整
如果要做更有野心的演进，我觉得方向是“上下文预训练与推荐”。具体来说，根据用户过去几轮的上下文编辑习惯，学习他更偏好引用哪类片段、忽略哪类片段，然后在新的一轮生成前，直接主动提出建议：“根据你的习惯，我已经把第三方SDK文档设为忽略，建议把测试文件置顶，是否确认？”
这本质上是把上下文管理从“事后调试”变成“事前优化”。它能走的路径还很长，但从产品逻辑上看，context-mode已经为它准备好了一块非常好的试验田。
5.4 一点个人体会
做context-mode这段时间，我最深的体会是，AI应用真正难的不是模型选型和接口对接，而是“模型接收的材料管理”。材料管理者往往没人看得见，可它的错误会被模型放得很大。context-mode其实就是给这个角色装了一块玻璃，让人能看清楚材料长什么样，然后想办法优化材料。这块玻璃成本不高，带来的透明感却是一整套排查方法的基础。如果你的项目正在被“AI莫名回答”这类问题困扰，不妨先给自己的上下文装一块同款玻璃。
