你搜到 context-mode 这个词大概率是碰到了同一个痛手里的 AI 工具明明很能打可一聊上下文就掉链子——刚让它分析完 logger.py 的并发实现转头问它“那 handler 里有没有同样的问题”它直接给你扯到数据库连接池。不是模型不行而是你压根没给它“记忆”。context-mode翻译过来就是“上下文模式”它要做的事情其实很朴素把 AI 需要知道的背景信息在每次调用前系统性地收集、整理、注入进去让模型从“每一次都是第一次见面”变成“一个真正懂你的老搭档”。这篇文章的目标读者很明确正在做 AI 应用、AI 工具链或者想把自己常用模型接入工作流的开发者。无论你用 Python 还是 TypeScript无论你对接的是哪个模型服务只要你的应用里存在“需要模型记住之前聊了什么、读懂了当前项目”这类需求这套 context-mode 的拆解思路和最小实现都能直接抄作业。我会从原理讲到代码再从代码讲到避坑尽量少说空话。1. context-mode 到底是什么先解决“模型失忆”这个根源问题1.1 模型失忆的根源你每次调用都是“第一次见面”先说清楚一个本质大模型本身是无状态的。你每次调用模型接口本质上就是丢进去一堆文字、吐出来一堆文字。它不记得你上一次问了什么也没有一个“心里的小本本”去记录你们之间的聊天过程。所谓的“多轮对话”其实是前端把之前所有轮次的对话重新拼起来再次塞给模型而已。这个现象可以用一个很生活化的场景来理解你每次见一个网友都得从头自我介绍一遍告诉它你叫什么、养了什么猫、上次聊到哪了。对方才能勉勉强强接上话。而 context-mode 就是帮你自动完成这个“复述”的过程并且复述得更聪明——它不是简单地把历史记录原样倒回去而是会判断哪些信息值得给模型、哪些信息可以舍弃、哪些信息需要从外部环境中补充进来。我还想强调一个点所谓“context window”只是模型输入缓冲区的大小它不代表模型真的“记住了”。你把 8K 的窗口全部塞满对话记录模型确实能看到这些文字但看到不等于理解优先级更不等于它知道该重点依赖哪一段。所以 context-mode 真正要做的事情不是“塞更多”而是“塞得更准”。1.2 三种常见形态会话记忆、项目感知、知识库增强context-mode 在不同产品里长得很不一样但归纳起来基本是三种形态它们的上下文来源完全不同使用场景也有明显边界。形态上下文来源典型场景核心优势主要短板会话级历史对话、用户画像连续问答、内容创作实现简单效果立竿见影长时间对话容易超长项目级文件结构、源码、配置文件代码生成、Bug 排查贴合开发场景实用性强采集逻辑复杂成本较高知识库级文档、数据库、检索结果企业问答、智能客服信息精准覆盖面广强依赖检索质量工程量大会话级是大家最容易理解的就是 ChatGPT 网页版那种效果——它能“记得”你五分钟前提到的需求。项目级则是 Cursor、Copilot 这类工具的核心竞争力AI 能感知你当前打开了哪个文件、项目目录长什么样。知识库级则多见于企业私有部署把内部文档切开、建索引让模型在回答之前先“查资料”。我自己的项目里主要做的是项目级 会话级组合也就是既能感知当前工作区的文件又能记住我们之前聊到哪了。这种组合覆盖了绝大多数开发场景也是我觉得性价比最高的一种方案。2. 核心设计思路上下文从哪来、怎么存、怎么塞2.1 上下文采集四类信息来源与三条采集原则要设计 context-mode首先得回答一个问题上下文到底从哪里来我在实践中整理了四类最可靠的来源。第一是显式指定。用户直接在对话里说“参考 src/logger.py 这个文件”这种指令的优先级最高必须无条件采纳。第二是环境感知通过检测当前工作区的目录树、最近修改时间、Git 分支信息等自动判断用户大概在做什么。第三是历史行为比如用户最近打开了哪些文件、编辑过哪些代码片段这种信息能很好地反映“此刻他关心的对象”。第四是外部检索需要从数据库、文档库或者搜索引擎里拉取相关内容常见于知识库型应用。明确了来源接下来是采集原则。我有三条“军规”每条都是用真实教训换来的永远不要一次性把整个仓库读进来。先读目录树tree再按需读文件这是一个铁律。单个文件的内容要做长度限制比如只取前 2000 字符和末尾 500 字符。因为代码文件的信息密度通常集中在头部import 和配置和尾部入口函数和 main。隐藏文件、密钥文件、二进制文件直接跳过不商量。采集前先过一层过滤名单。2.2 上下文压缩滑窗、摘要、关键信息提取上下文采集回来之后更大的挑战是“塞不下”。模型有 token 上限你不能把一整本小说都倒进去。常用的压缩策略有三种我分别说下适用场景。滑窗法最朴素只保留最近 N 轮对话。比如设置“最多保留 8 轮”超出的部分直接丢弃。它的优点是快、稳、不消耗额外调用缺点是如果早期对话里有重要的任务目标会被一起丢掉。所以滑窗必须配合“任务目标重置”使用——每一轮组装 prompt 时把当前任务目标放在最前面重新声明一次相当于不断给模型“提个醒”。摘要法更聪明一点当历史超过一定轮数时先让模型自己把之前的对话压缩成一段 150 字以内的结构化摘要下一轮调用时把摘要注入进去。摘要里必须保留三样东西当前任务目标、已确认的决策、遗留问题。这个方案多消耗一次模型调用但效果远好于粗暴截断尤其是在长对话场景下。关键信息提取是摘要法的进阶版设定固定规则比如从历史中提取“路径、变量名、函数名、结论、待办事项”五类信息生成一张结构化的清单。它的好处是模型在下一次回答时容易“引用”具体信息而不是泛泛而谈。这三种策略不冲突可以组合先滑窗再对滑窗之外的部分做摘要最后从摘要里提取关键信息。2.3 注入顺序为什么任务目标必须放在最前面很多人在做 context-mode 时只关注“塞了什么”却忽略了“按什么顺序塞”。我做过一堆对比实验结论非常明显prompt 最前面的 200 字对回答风格和任务方向的引导作用最强末尾 200 字直接影响模型“即将回答的那句话”的走向中间部分的信息最容易被稀释。所以我的注入顺序是固定的当前任务目标放在最前面相当于给模型立一个“军令状”然后是相关文件内容提供事实依据接着是历史对话的摘要或滑窗内容保持连续性最后才放用户当前的输入。这个顺序看起来简单但能明显减少“答非所问”和“废话连篇”的情况。我把这个顺序做成了一个优先级表方便你在自己的实现里参考注入顺序内容类型示例作用1任务目标“排查日志模块并发丢消息问题”设定整体方向2相关文件src/logger.py 的关键片段提供事实依据3历史摘要/滑窗之前确认过的决策和遗留问题保持连续性4通用背景技术栈、环境说明兜底补充5用户当前输入“Queue 已经加锁为什么还丢消息”触发最终回答理解了这个设计逻辑接下来就可以动手写代码了。下面的章节我会给出一份最小可用的实现整个项目只有一个文件大概两百多行你拿到之后改改路径就能跑。3. 从 0 到 1 实现最小可用的 context-mode3.1 先定义好“上下文单元”这个基础数据结构任何 context-mode 实现的第一步都是定义数据模型。我习惯用一个ContextItem来表示一条独立的上下文片段再用一个ContextBundle来聚合多个片段。这里我用 Python 的 dataclass 来做逻辑清晰改起来也方便。from dataclasses import dataclass, field from typing import Dict, List, Optional dataclass class ContextItem: source: str # 来源标识如 file:src/logger.py, chat_history content: str # 实际要注入的内容 rank: int 100 # 注入顺序数值越小越靠前 token_estimate: int 0 # 预估 token 数用于预算控制 dataclass class ContextBundle: purpose: str # 当前任务目标永远排在最前 items: List[ContextItem] field(default_factorylist) max_input_tokens: int 4096 # 输入预算上限 reserve_tokens: int 1024 # 给模型输出预留的 tokenrank字段就对应上一节说的注入顺序任务目标固定 rank 最小文件内容其次历史对话再往后用户输入最后。token_estimate是给后续的预算控制用的我一般用字符数估算中文约一个字符算 12 个 token英文约 4 个字符算 1 个 token。这里可以快速写一个估算函数def estimate_tokens(text: str) - int: # 中文场景的粗略估算生产环境建议使用具体模型的 tokenizer return max(1, len(text) // 2)3.2 实现文件采集器读取、截断、过滤一次搞定文件采集是项目级 context-mode 的主要数据来源。我封装了一个collect_file_context函数接收一个项目根路径和一组相对路径白名单逐个读取文件内容并转换成ContextItem。import os from pathlib import Path from typing import List # 敏感文件和目录采集时必须跳过 DEFAULT_DENY_SUFFIX {.env, .pem, .key, .p12, .cer, .crt} DEFAULT_DENY_PREFIX {., node_modules, dist, build, vendor, venv} def should_include(rel: str) - bool: name rel.lower() if any(name.endswith(s) for s in DEFAULT_DENY_SUFFIX): return False if any(name.startswith(p) for p in DEFAULT_DENY_PREFIX): return False return True def safe_read(path: Path, max_chars: int) - str: 读取文件超长时只保留头部和尾部 try: text path.read_text(encodingutf-8, errorsignore) except Exception as e: print(f[error] 读取失败: {path} - {e}) return if len(text) max_chars: return text head text[: max_chars // 2] tail text[-max_chars // 2 :] return head \n...(中间内容省略)...\n tail def collect_file_context( root: Path, include: List[str], max_chars: int 4000, max_files: int 5, ) - List[ContextItem]: items [] for rel in include: if len(items) max_files: break p root / rel if not p.exists() or not p.is_file(): print(f[warn] 文件不存在: {rel}) continue if not should_include(rel): print(f[warn] 已跳过敏感文件: {rel}) continue content safe_read(p, max_chars) if not content: continue items.append( ContextItem( sourceffile:{rel}, contentcontent, rank50, token_estimateestimate_tokens(content), ) ) return items这个实现里有两个细节值得你留意。第一个是safe_read的“头尾保留”策略头部通常有 import 和配置尾部通常是入口函数和 main中间细节反而对模型没太大帮助掐掉能省大量 token。第二个是max_files参数我建议默认不超过 5 个文件文件越多模型注意力越分散回答质量反而下降。这是一个反直觉但极其重要的经验。should_include这个过滤函数做了一件很重要的安全保护它会主动拦截 .env、密钥证书这类文件。你可能会想“我只是读取又不提交”但问题是很多日志系统和缓存系统会把读取内容记录下来一旦泄露就是事故。denylist 必须在采集环节就挡掉不能指望后续环节来做清理。3.3 实现历史管理滑窗裁剪和摘要生成对话历史的处理是 context-mode 的另一个关键部分。我做了一个trim_history做滑窗裁剪再做了一个rollup_summary做摘要生成。from typing import Dict, List def trim_history( history: List[Dict], max_chars: int 3000, max_rounds: int 8, ) - List[Dict]: 滑窗裁剪优先保留最近的对话同时控制总长度 kept [] used 0 for turn in reversed(history[-max_rounds:]): msg turn.get(content, ) if used len(msg) max_chars: break kept.insert(0, turn) used len(msg) return kept def history_to_items(history: List[Dict], rank: int 80) - List[ContextItem]: return [ ContextItem( sourcechat_history, contentf{turn.get(role)}: {turn.get(content, )}, rankrank, token_estimateestimate_tokens(turn.get(content, )), ) for turn in history ]滑窗裁剪的逻辑是从最近的对话往前倒序扫描能放多少放多少直到达到字数上限或者轮数上限。这样做既保住了“最近聊了什么”又不会让历史无序膨胀。摘要生成的实现稍微复杂一些因为它需要调用模型本身。我通常把历史对话打包成 JSON让模型生成长度可控的摘要def rollup_summary(history: List[Dict], llm_call) - str: 把超长历史压缩成结构化摘要需要传入一个 llm_call 函数 target history[-20:] dump json.dumps(target, ensure_asciiFalse, indent2) prompt ( 请把下面的对话压缩成 150 字以内的摘要必须保留三部分 1) 当前任务目标2) 已确认的决策3) 未解决的问题。\n\n f{dump} ) return llm_call(prompt)这里我故意把llm_call设计成参数而不是直接 import 某个 SDK就是为了让你能无缝对接自己项目里的模型封装。它本质上就是一个“输入字符串、输出字符串”的函数。使用摘要的时候你可以把它作为一个 rank 更靠前的ContextItem注入到下一轮对话中替代被裁掉的早期历史。3.4 组装 prompt 并调用模型一个完整可运行示例上下文都准备好之后最后一步就是按 rank 排序、组装成一个完整的 prompt然后发给模型。这一步是整个 context-mode 的临门一脚我把它封装成了一个build_prompt函数def build_prompt(bundle: ContextBundle, user_input: str) - str: sections [] if bundle.purpose: sections.append(f【当前任务】{bundle.purpose}) sorted_items sorted(bundle.items, keylambda item: item.rank) for item in sorted_items: sections.append(f【{item.source}】\n{item.content}) sections.append(f【用户提问】{user_input}) return \n\n.join(sections)你可以看到无论bundle.items里的顺序怎么乱最终都会按rank重新排序。这个设计保证了后续任何模块往items里追加内容时都不需要关心顺序问题。最后把用户当前输入放在 prompt 末尾让模型能直接对“问题本身”给出回应。接下来是一个完整的调用示例。假设你现在有一个项目/home/dev/myproj里面有一个日志模块和一个请求处理模块你想让 AI 帮你排查并发问题。完整的调用流程如下def chat_with_context(bundle: ContextBundle, user_input: str, llm_call) - str: prompt build_prompt(bundle, user_input) # 如果你用的是某官方 SDK这里就是把你的 prompt 放进 user 字段 return llm_call(prompt) def main(): root Path(/home/dev/myproj) bundle ContextBundle( purpose排查日志模块在高并发下丢失消息的问题, max_input_tokens4096, reserve_tokens1024, ) # 1. 采集项目文件 bundle.items collect_file_context( root, [src/logger.py, src/handler.py, config/app.yaml], ) # 2. 加入历史对话模拟 history [ {role: user, content: 项目结构我看过了重点在日志和 handler 两个文件。}, {role: assistant, content: 明白我会重点分析这两个文件在高并发下的表现。}, ] bundle.items history_to_items(trim_history(history, max_chars2000)) # 3. 调用模型 answer chat_with_context(bundle, Queue 已经做了加锁为什么还会丢消息, llm_call) print(answer)整个流程一共三步先定义任务目标和预算再采集文件和历史最后组装并调用。你可以在自己的应用里把bundle透传到各个工具函数之间保证每次调用都能按这个流水线走一遍。上面这段逻辑我实际跑下来基本能满足日常开发辅助的需求。4. 实战避坑指南与常见问题速查4.1 上下文爆炸输入超限被拒绝怎么办我见过最多的报错就是“token 超限”或者模型直接返回 400。这通常不是单一原因导致的而是采集、压缩、预算三个环节都没控制好。解决办法是给 context-mode 加一个预算控制函数。它的逻辑很简单先预留出用户输入和模型输出的 token剩下的才分配给上下文内容然后按 rank 从高到低依次放行放不下的就直接丢弃。def enforce_budget( items: List[ContextItem], max_tokens: int, reserve_tokens: int, user_input: str, ) - List[ContextItem]: budget max_tokens - reserve_tokens - estimate_tokens(user_input) sorted_items sorted(items, keylambda item: item.rank) used 0 kept [] for item in sorted_items: if used item.token_estimate budget: kept.append(item) used item.token_estimate else: break # 预算不够直接丢弃后面的低优先级内容 return kept把这个函数加在build_prompt之前你就再也不用担心超限了。需要注意一点很多模型服务对“输入 输出”的总量有限制而不是只限制输入。所以reserve_tokens一定要留足我一般按 20%25% 的比例预留防止模型回答到一半被截断。4.2 回答质量飘忽不定先排查这三处如果你的 context-mode 已经跑通但回答质量时好时坏我建议按下面三个顺序排查。第一检查任务目标是否真的在 prompt 最前面。有时候代码改着改着某个模块往sections里提前插了内容任务目标就被挤到了后面。这会导致模型对“你到底要我干什么”理解不到位回答方向飘忽。第二检查文件内容是否过期。如果你用缓存机制比如只读一次文件就缓存内容请确保在文件变更后缓存能失效。我碰到过一个很隐蔽的问题改完代码之后模型还在基于旧代码回答让我足足排查了两小时。第三检查历史对话里是否有相互矛盾的旧结论。滑窗裁剪后早期一个错误结论可能已经被裁掉了但模型在后续对话里还是会“顺着说”。解决办法是定期用rollup_summary生成结构化摘要把“已确认的决策”固定下来避免模型被早期噪声带偏。我把常见问题整理成了一个速查表方便你直接对照症状可能原因排查方向模型答非所问任务目标被挤到后面检查 prompt 最前 200 字回答内容陈旧文件缓存未失效检查采集器的缓存逻辑上下文超限报错预算未控制启用 enforce_budget模型忘记之前的结论历史被滑窗裁掉增加 rollup_summary 摘要层回答越来越啰嗦塞入了过多无关文件收紧 include 白名单4.3 隐私红线哪些文件永远别进 context-mode关于隐私和数据安全我必须有单独一节来说因为这是 context-mode 项目里最不能让步的部分。我见过不止一次事故开发者为图省事直接自动采集项目所有文件结果把.env里的数据库密码连同代码一起发给了模型。虽然模型不会主动泄露但你的 API 请求日志、服务商侧的数据记录都等于把密码裸奔了一遍。所以我的建议很明确denylist 只是一道兜底真正的红线是默认不采集任何非白名单文件。也就是说与其维护“哪些文件不能读”不如维护“哪些文件可以读”。上下文里出现的每一个文件都应该是你明确知道“它没问题”的文件。以下四类文件永远不要进 context-mode密钥与配置文件.env、.pem、*.key、credentials 等、包含大量个人数据的文件通讯录、日志脱敏前的原始数据、临时产物node_modules、dist、build、缓存目录、以及任何你没有权限读取的文件。如果一定要处理这些信息先做脱敏或抽离出“非敏感摘要”再注入。4.4 context-mode 的下一个台阶缓存、检索与多级摘要如果你的 context-mode 已经稳定运行可以往这三个方向扩展。缓存是最容易做的优化。给每个文件的读取结果加上 hash 校验文件没变就直接复用旧的ContextItem能省下大量磁盘 IO 时间。我实测下来在项目级场景里缓存命中率能到 70% 以上响应速度提升非常明显。知识库检索则是把 context-mode 从“项目级”升到“企业级”的必经之路。当文档量超过几十个文件时全量注入已经不现实了。这时候你需要一台向量数据库把文档切片建索引每次调用前先根据用户输入做一次召回再把召回的 Top 5 片段作为上下文注入。记得给召回的每个片段也设一个 rank一般来说匹配度越高rank 越靠前。多级摘要适合对话特别长的场景。不要把整段超长历史压成一条摘要而是按主题拆分成多条子摘要。比如一条摘要记录“技术方案讨论”另一条记录“Bug 排查进展”每次只注入和当前问题相关的摘要。这个方向做起来工程量大一些但能显著延长 context-mode 的“有效生命周期”。写在最后的小实践建议从我实际落地的经验看context-mode 最难的从来不是代码而是判断“什么该进上下文、什么不该进”。我一开始贪多把所有能采集的文件全塞进去结果回答反而变得平庸后来改成“任务目标 最多 3 个相关文件 精简历史”效果立竿见影。如果你也要做类似的东西我建议先把“最小够用”跑通再谈优化。第一版只需要支持文件采集和滑窗历史其余统统砍掉。跑通之后再逐步加摘要、加缓存、加检索。每加一层都单独验证效果不要一口气全上。这样出了问题你才能精准定位是哪个环节拖了后腿而不是对着一个巨石结构无从下手。