最近做 AI 辅助工具的时候，团队里聊得最多、也踩坑最多的一个词就是 context-mode。这个词翻译成中文就是“上下文模式”，但真正动手做过的朋友应该清楚，它远不是往提示词里塞几段代码那么简单。项目推进到一定阶段后你会发现，模型能力反而不再是瓶颈，真正的瓶颈变成了“模型到底能不能看到它该看的东西”。
我这个项目本质上就是给一个 AI 代码助手增加了一套 context-mode。核心目标很明确：让 AI 在回答问题时，能够自动感知当前项目的文件结构、最近改动、历史讨论，甚至用户当下的操作意图，从而给出贴合真实场景的答案，而不是一本正经地胡说八道。内容适合两类人看：一类是正在做 AI 应用、AI 编程助手或知识库问答系统的开发者，另一类是重度使用 AI 工具、天天抱怨“AI 答非所问”的普通用户。很多人把问题归结为模型笨，其实大部分时候是上下文压根没喂对。这篇就把 context-mode 的概念、设计思路、核心实现和踩过的坑一次讲透，你看完基本能照着思路改造自己的项目。
1. 项目概述：context-mode 到底解决什么问题
1.1 从一个典型的“翻车现场”说起
先讲一个我真实遇到的场景。同事用 AI 助手重构一个 Python 模块，模型给出的建议从语法层面看毫无问题，但一落地就报错。原因很典型：这个模块依赖项目里一个自定义的消息队列封装，而 AI 完全不知道有这个封装存在，于是自己“合理”地假设了一个标准接口。
这就是所谓“答非所问”的本质。模型不是不会写代码，而是它看到的只有你粘贴的那一小段内容，没有项目背景、没有依赖关系、没有历史决策记录。你在 IDE 里看到的上下文是极其丰富的——左侧目录树、打开的标签页、Git 改动、最近搜索记录，这些信息在你脑子里构成了对问题的完整理解。但对模型来说，它就是个“失忆的专家”，每一轮对话都像第一次见面。
context-mode 要解决的，正是这个信息不对称的问题：把散落在项目里、会话里、操作行为里的上下文，按照需求和优先级组织起来，在合适的时机交给模型。
1.2 context-mode 的准确定位
我比较认可的定义是：context-mode 是一种让系统能够自动采集、组织、筛选并注入上下文的工作模式，核心目标是让模型的输出基于真实场景，而不是基于统计概率的合理猜测。
它不是一个单纯的功能点，而是一套处理流程，典型包含四个环节：
- 采集：从文件系统、版本控制、对话历史、编辑器状态等源头获取原始信息
- 组织：对原始信息做结构化处理，按主题和时间线归拢
- 筛选：根据当前问题计算相关性，决定哪些信息进入模型视野
- 注入：按约定的格式把筛选后的上下文拼装进提示词
这四个环节缺一不可。很多早期方案只做了“采集”和“注入”，把所有内容一股脑塞给模型，看起来简单粗暴，但实际效果往往很差——上下文塞得越多，模型越分不清主次，响应速度和成本也水涨船高。只有把“组织”和“筛选”做到位，context-mode 才真正有工程价值。
1.3 适合谁来参考
如果你是应用开发者，这篇里的分层设计、token 预算分配、裁剪策略可以直接用到你的 AI 应用里。如果你是工具的普通用户，读完你会明白为什么同一个模型在别人手里那么好用、在你手里却总是不靠谱——差异往往就在于你有没有给它足够有效的上下文，或者说你用的工具够不够聪明地帮你组织上下文。
2. 核心思路拆解：context-mode 的设计逻辑
2.1 上下文不是越多越好
刚开始做 context-mode 时，团队最容易犯的一个错误就是“贪多”。总担心模型看不到关键信息，于是把整个项目的文件列表、全部 Git 历史、所有对话记录都往里面塞。实测下来效果反而更差，因为上下文里充满了噪声。
用生活里的场景来类比：面试官让你评估一个候选人，给你一摞 500 份简历，其中 480 份都不相关，你要花大量时间才能找到关键的那 20 份。大模型同样面临这个问题，它的注意力是有限的，信息量超过阈值之后，关键信号会被淹没在无关内容里。
所以我在设计时定了一个原则：相关性 > 数量。一个 token 的有效价值，取决于它和当前问题的关联强度，而不是它本身的信息含量。与其给模型 10 万个 token 的项目快照，不如精心挑选 5000 个 token 的高相关片段。
2.2 上下文的分层模型
既然不能全塞，那就得给上下文分层次管理。我参考了经典的操作系统内存管理思路，把上下文分成三个层级：
- 全局层：项目的稳定信息，包括 README、技术栈说明、编码规范、业务背景、常用组件清单。这一层更新频率最低，可能一周才变一次，但决定了模型对项目的基本认知
- 会话层：当前对话内产生的动态信息，包括用户最近几轮提问、AI 之前的回答、用户对答案的修正。这一层的时效性极强，每一轮对话都在变化
- 局部层：与当前操作直接相关的即时信息，包括当前打开的文件、光标附近的代码、最近一次 Git diff、选中的代码片段。这一层是模型做具体决策时的“近距离视野”
三个层级各有各的作用，缺了任何一层都会出现明显问题。缺全局层，模型会写出风格不一致、无视项目规范的代码；缺会话层，模型会反复犯同一个错误，你刚纠正过的方向它扭头就忘；缺局部层，模型不理解你当下的具体操作，只能泛泛而谈。
2.3 为什么“拼 prompt”式的老方案不行
有人可能会问：这跟手动把相关文件复制粘贴给模型有什么区别？区别就在于“模式”二字。手动拼 prompt 有三大痛点：一是时效性差，文件改了你还得重新复制；二是主观性强，你觉得自己理解了，但可能漏掉了真正关键的信息；三是不可扩展，一次两次可以，天天做根本不现实。
context-mode 的价值在于，它把“理解上下文”这个本来要人来做的事情自动化了。系统自己监控文件变更、自己跟踪 Git diff、自己维护对话摘要、自己判断哪些文件相关。人只需要专注于发起问题，剩下的让模式去处理。
3. 实操落地：从零实现一套 context-mode
3.1 整体架构与模块划分
我实现这套 context-mode 时用的是 Python，核心分五个模块，各司其职：
| 模块 | 职责 | 对应层级 |
|---|---|---|
| collector | 采集文件、Git 状态、对话记录等原始数据 | 全部 |
| normalizer | 将采集到的原始数据统一成结构化对象 | 全部 |
| scorer | 计算每个上下文片段与当前问题的相关度 | 筛选 |
| budgeter | 按 token 预算分配各层级容量 | 筛选 |
| injector | 将最终选中的上下文渲染进提示词 | 注入 |
模块之间用纯数据接口通信，互不依赖。比如 collector 只负责产出统一的 ContextItem 数据对象，不关心后续怎么筛选；scorer 只负责对 ContextItem 打分，不关心数据从哪来。这样每个模块都可以单独替换、单独测试，出了问题也好定位。
3.2 采集层实现要点
采集层是整个 pipeline 的地基。我的 collector 核心逻辑如下：
from pathlib import Path import os SUPPORTED_SUFFIX = {".py", ".js", ".ts", ".md", ".yaml", ".json", ".sql"} def collect_project_files(root: str, max_size: int = 100_000) -> list[dict]: """扫描项目文件，返回符合条件的文件列表。 max_size 单位是字节，超过 100KB 的文件默认跳过， 避免把压缩文件或构建产物误认为源码上下文。 """ items = [] for path in Path(root).rglob("*"): # 跳过隐藏目录、虚拟环境、构建产物 if any(part.startswith(".") for part in path.parts): continue if not path.is_file(): continue if path.suffix not in SUPPORTED_SUFFIX: continue size = path.stat().st_size if size > max_size: continue items.append({ "path": str(path.relative_to(root)), "size": size, "modified": path.stat().st_mtime, }) return items这里有几个细节值得说。第一是文件大小过滤，很多人会忽略构建产物问题，比如 node_modules、dist、target 这些目录，一旦扫进去直接把 token 预算打穿。第二是不要用os.walk硬遍历全盘，用Path.rglob配合黑白名单更可控。第三是记录修改时间，后续做增量采集和缓存失效判断都要靠它。
Git diff 的采集同样重要。我封装了一个函数，只取当前未提交的改动，不碰历史记录：
git diff --stat git diff -- '*.py' '*.js' '*.ts'之所以限定后缀，是因为有时候文件里的锁文件、生成文件会产生大量无意义 diff，把它们过滤掉能显著降低噪声。
3.3 相关性打分：怎么判断“该看什么”
采集到上下文后，最核心的一步是计算相关性。我的 scorer 综合考虑三个维度：关键词重合度、位置邻近度、操作时间接近度。
def score_item(item: dict, query: str, current_file: str) -> float: score = 0.0 # 1. 文件名与查询词的字符重合度 query_terms = set(query.lower().split()) name = item["path"].lower() overlap = sum(1 for term in query_terms if term in name) score += overlap * 2.0 # 2. 当前打开文件路径重合度 cur_parts = set(Path(current_file).parts) item_parts = set(Path(item["path"]).parts) common_parts = len(cur_parts & item_parts) score += common_parts * 1.5 # 3. 修改时间接近度：越新越高 import time age_hours = (time.time() - item["modified"]) / 3600 if age_hours < 1: score += 3.0 elif age_hours < 24: score += 1.0 return score这个打分函数看着简单，但我实际跑下来的效果非常好。原因是它抓住了三个最核心的信号：语义相关性、空间邻近性、时间新鲜度。做复杂的关键词嵌入也未必比这三板斧强多少，尤其是在没有大量标注数据的情况下。
需要提醒的是，打分函数的权重得根据不同场景调整。如果是做代码生成，修改时间接近度的权重应该提高，因为用户大概率在改最近动过的文件；如果是做文档问答，关键词重合度权重应该提高，因为答案往往藏在特定的文档章节里。
3.4 注入格式与渲染
上下文筛选完，最后要解决的是“怎么把内容呈现给模型”。我的做法是给上下文加标签和层级标记，让模型明确知道每段信息的类型：
def render_context(items: list[dict], tier: str) -> str: blocks = [] for item in items: header = f"[{tier}] {item['path']}" blocks.append(f"{header}\n```\n{item['content']}\n```") return "\n\n".join(blocks)渲染后的提示词结构大概是这样的：
[global] 项目说明 项目基于 FastAPI 构建，遵循分层架构... [local] src/services/order_service.py def create_order(...): ... [local] git diff (未提交) + def cancel_order(...):在 prompt 的最前面我加了一段说明性文字，告诉模型这些是经过筛选的项目上下文，优先级从高到低排列，如果上下文与当前问题无关可以忽略。加了这句话之后，模型的“被干扰”情况明显减少——它学会了主动忽略不相关的上下文，而不是被迫逐字处理。
4. 核心参数与调优实践
4.1 关键参数一览
context-mode 在实际运行中涉及不少参数，我整理了一张常用参数表，每个参数都标注了我在项目里的经验值：
| 参数 | 含义 | 经验值 | 说明 |
|---|---|---|---|
| max_context_tokens | 上下文最大 token 数 | 8000 | 根据模型窗口自适应 |
| tier_global_ratio | 全局层占比 | 30% | 给稳定信息留足空间 |
| tier_session_ratio | 会话层占比 | 40% | 对话历史是核心 |
| tier_local_ratio | 局部层占比 | 30% | 实时操作信息 |
| max_file_size | 单文件最大大小 | 100KB | 超限直接跳过 |
| top_k_files | 局部层最多选文件数 | 5 | 防止碎片化 |
| summary_threshold | 会话摘要触发轮数 | 6 | 超过则压缩历史 |
参数之间其实有联动关系。比如top_k_files设得太大，每个文件的内容就可能很浅，模型看到的信息都是“只言片语”，反而不如集中看两三个完整文件。我最终把局部层的文件数限制在 5 个以内，保证每个文件都能获得完整展示。
4.2 参数计算过程示例
我拿一个实际项目举例。某次对话中，项目文件扫描出 30 个符合条件的源文件，加上 Git diff 和最近 10 轮对话，全部攒起来预计要 2 万 token，但模型窗口只有 16K，还得给生成结果留空间，所以我设定 max_context_tokens 为 8000。
分配过程是这样的：
total_budget = 8000 # 按比例分配 tier_budgets = { "global": int(total_budget * 0.30), # 2400 "session": int(total_budget * 0.40), # 3200 "local": int(total_budget * 0.30), # 2400 }然后对每一层分别做贪心选择：按打分从高到低拿文件，每拿一个文件先估算它的 token 数——我用的粗估方式是字符数除以 3，中文场景偏保守可以除以 2。直到该层预算用完，或者文件已经全部选完。
实际分配的时候会面临一个权衡：是让 3 个文件完整展示，还是让 5 个文件各展示一段？我的经验是前者。因为一个文件如果只保留了三分之一，它内部的函数依赖关系、类结构你是看不全的，对模型来说等于看悬疑小说只看到了线索没看到上下文。完整性优先于覆盖度，这是我在调参过程中最重要的心得。
4.3 会话摘要的兜底策略
当对话轮数太多，会话层 40% 的预算放不下完整历史时，就需要摘要兜底。我用的策略是分段摘要：每 3 轮对话生成一次小结，新对话继续用完整历史，旧对话统一替换成摘要块。
def summarize_history(conversation: list[dict], summary_model) -> str: """把超过 summary_threshold 的历史对话压缩为摘要。""" if len(conversation) <= 6: return format_history(conversation) old_turns = conversation[:-6] recent_turns = conversation[-6:] summary_text = summary_model.summarize(old_turns) return f"[摘要] {summary_text}\n\n{format_history(recent_turns)}"这个做法的好处是：近期的完整上下文保留，久远的历史以压缩形态存在，兼顾准确性和容量。但需要注意摘要本身也会损失信息，所以我会要求摘要模型保留“用户明确提出的修改要求”和“已经确认的结论”，这两类信息丢失了后续会非常被动。
5. 常见问题与排查实录
5.1 问题速查表
做 context-mode 的过程中踩了不少坑，我整理了一份问题速查表，都是实际遇到并解决的：
| 现象 | 根因 | 解决方案 |
|---|---|---|
| 响应超时 | 上下文注入过多，单次请求 token 超限 | 检查 max_context_tokens，降低局部层文件数 |
| 重要文件总被裁剪 | 打分权重偏差，关键词过于宽泛 | 提高位置邻近度权重，或手动 pin 文件 |
| 历史摘要失真 | 摘要模型丢失关键约束信息 | 摘要时明确要求保留“用户明确要求” |
| 多用户上下文串了 | 全局层缓存未按用户维度隔离 | 给缓存 key 加 user_id 维度 |
| 模型重复询问已有信息 | 会话层预算被全局层挤压 | 调整 tier 比例，给会话层更多空间 |
| 采集了不相关文件 | 扫描白名单过宽 | 加强后缀过滤，增加文件路径关键词排除 |
这里面最坑的是“多用户上下文串了”。出现这个问题的原因是会话缓存设计的时候只拿了 project_id 当缓存 key，忽略了用户维度。结果两个用户同时操作同一个项目，后一个用户的问题里带着前一个用户的操作上下文，AI 给出的答案是“混合风格”，对谁都不对。修复方案很粗暴——缓存 key 加上 user_id，同时把采集器里的本地临时文件路径也按用户隔离。
5.2 排查思路分享
遇到 context-mode 效果不理想时，我的排查顺序基本固定：先看注入的上下文内容对不对，再看上下文是否出现在提示词的正确位置，最后才怀疑模型能力。
具体操作上，我会开一个 debug 模式，把最终发送给模型的提示词完整打印到日志里。这一步能解决 80% 的问题。你打印出来一看就明白：要么是上下文压根没采到，要么是采到了但排序不对，要么是注入格式出了问题，标签没配对导致模型把代码块当成了自然语言。
另一个很实用的技巧是“消融测试”——每次只保留一个层级的上下文，看模型输出的差异。如果去掉局部层之后模型回答明显变差，说明局部层信息是关键；如果去掉全局层模型仍然能答对，说明全局层暂时可以压缩。消融测试能帮你精确定位“哪一层的信息在起作用”，而不是凭感觉调参。
5.3 性能优化记录
context-mode 的采集和打分是有性能开销的，尤其是大型项目里频繁触发文件扫描会拖慢整体响应。我用三层缓存来解决：
- 文件元信息缓存：10 分钟过期，避免每次请求都重新扫目录
- 文件内容缓存：按文件 mtime 判断，文件没变直接用缓存内容
- 打分结果缓存：相同 query 在 5 分钟内直接复用
实测优化后，上下文构建耗时从平均 1.8 秒降到了 0.2 秒左右。这组缓存带来的收益非常明显，也让 context-mode 从“影响体验的负担”变成了“感受不到存在的基础设施”。
6. 几点个人经验与后续扩展
最后分享几条在项目里沉淀下来的个人经验，这些不是教科书上写的，而是实操中一点点试出来的。
第一，context-mode 的“上下文构建”要追求确定性，而不是追求智能。早期我尝试过让 LLM 来自动决定哪些文件重要、哪些文件可以丢弃，效果非常不稳定——同一个问题隔了几分钟问，模型选文件的逻辑都不一样。后来改成规则 + 打分函数的方式，虽然看起来“笨”，但至少每一次的结果都是可预期、可debug的。智能留给模型本身，工程部分还是要回归确定性和可控性。
第二，上下文可视化比任何参数文档都有用。我给 context-mode 加了一个简单的运行时面板，显示当前请求注入了哪些文件、每个文件消耗多少 token、哪些文件被裁剪掉了。这个面板上线后，团队调试效率提升了不止一倍。很多问题你看参数表看不出来，但一看面板就明白——原来全局层的 README 每次都占了 4000 token，整整吃掉了一半预算。
第三，不要一开始就追求“全自动”。我在项目早期把 context-mode 设计成完全自动采集，结果用户的控制感很差。后来加了一个手动 pin 功能，允许用户把某个文件固定在局部层最顶端，所有自动打分都不覆盖它。这个小改动极大提升了工具的可用性。用户信任的是自己能干预的系统，不是黑盒。
后续再扩展的话，我想做两件事：一是把打分函数换成小模型embedding加规则回调，在保持确定性底线的同时增强语义理解；二是把 context-mode 做成跨 IDE 的通用层，让同一套上下文策略能服务编辑器、CLI、网页端多个入口。这些方向目前已经在实验阶段，进展顺利的话会再单独写一篇分享。
做 context-mode 这个项目的最大感受是：AI 工具的上限由模型决定，但下限往往由上下文管理决定。同一个模型，有没有一套好用的 context-mode，用起来完全是两个体验。这也是为什么我觉得这个方向值得认真做——它不是炫技，而是真正解决用户在真实场景里天天碰到的痛点。
