做 AI 终端助手那段时间我几乎所有深夜都在跟“上下文”这三个字较劲。模型逻辑能力再强只要你没把该给的信息递到它面前输出就是会漂。后来我把上下文处理收敛成一个可切换的开关也就是context-mode整个工具才算真正“能用”。这篇文章想把我踩过的坑、最后落地的方案、以及每个选择背后的理由完整记录下来。它适合正在用大模型 API 做 CLI 工具或自动化脚本的开发者也适合研究上下文工程、被 context window 困扰的同学。看完之后你可以直接把这套设计搬进自己的项目里。简单说context-mode 解决的是这样一个问题同样是调用同一个模型为什么有时候它像懂你的老同事有时候又像第一次见面的陌生人差别不在模型而在请求里携带的上下文。这个开关真正控制的就是“这几百 K 的窗口里我到底放什么东西进去”。后面你会看到这远不是一个参数调整那么简单而是一整套策略涉及 token 预算、历史压缩、信息筛选和会话状态管理。1. 为什么需要 context-mode上下文工程的痛点1.1 一次调用的真实链路在动手写任何代码之前先搞清楚大模型 API 调用时“上下文”到底经历了什么。以 OpenAI 系的接口为例一次完整的请求大概是这样的开发者把messages数组发给服务端这个数组里包含system、user、assistant三种角色消息然后服务端把整个数组编码成 token 序列送入模型。模型不是“记住”了你的历史而是每次都在窗口限制内重新“阅读”你给的全部内容。窗口有限比如 128K你塞进去 110K 的历史和文件片段真正留给模型思考、生成的空间就很拥挤了。有个比喻我一直觉得特别贴切大模型就像一个每次上班都只看你递过来的一张纸条的临时工。纸条上写了什么它就知道什么纸条没写的它再聪明也无从谈起。而且这张纸条有字数上限你不可能把公司所有资料都抄上去。必须有个“人”在写给模型之前先替它做一轮取舍——这就是 context-mode 存在的最根本原因。还有一个容易被忽略的细节每次请求都是无状态的。所谓“多轮对话”本质上是客户端把前面的对话记录全部积攒下来再带着它们一起发给模型。所以对话轮数越多请求体积就越大成本也越高。你问一个三句话的小问题可能背后背着 30 轮的历史包袱。这就是工程上需要管理的东西。1.2 三个典型的上下文困境第一个困境叫上下文爆炸。对话轮数越多、附加文件越多messages 列表就越臃肿。我最早做原型的时候为了省事直接把当前目录下所有代码文件读进来塞进请求里。一个小项目几百个文件一轮下来 token 数直接破万多问几轮窗口就快撑爆了。更麻烦的是这种方案下一旦报错你都不知道是代码问题还是上下文太大导致的。第二个困境是关键信息被淹没。这是最坑的一点。模型对输入长文的注意力天然是有限的越靠中间的内容、越早期的约束条件越容易被“稀释”。我遇到过特别典型的情况用户在第三轮明确说了“不要修改数据库结构”到第三十轮的时候模型已经开始生成改表结构的 DDL 了。不是模型变笨了而是早期的约束被后面几百条消息挤到了角落里。第三个困境是成本失控。所有的 token 都是要花钱的发送一整段历史、文件、检索片段每一轮都是在为“过去”买单。如果你的工具一天要被调用几千次历史消息每多一 K token账单上就是实实在在的支出。我见过不少团队做了很漂亮的 Agent最后因为一直没有清理上下文API 成本比预想高出一个数量级。1.3 为什么用“模式”而不是“自动方案”看到这里你可能会想既然上下文管理这么麻烦为什么不做成全自动的算法让程序自己判断该保留什么我一开始也是这么想的但后来发现全自动方案有个致命问题不可预测。你无法在线上环境里复现“为什么这条消息被丢了”也无法向队友解释“为什么这次回答质量突然下降”。上下文策略一旦变成黑盒调试成本会无限拉高。所以我采用了模式化的思路把上下文策略拆成几个明确的枚举值每个模式对应一套可预期的规则。这个类比就像是相机的自动挡和手动挡——自动挡省心但遇到特殊场景专业人士宁可切到手动模式因为此时一切参数都在掌控中。context-mode 也遵循同样的哲学默认可能选 auto但每一个模式都必须能被单独解释、单独调优。2. context-mode 的总体设计三种模式与取舍逻辑2.1 模式清单full、compact、auto我给 context-mode 设计了三种模式名字直接暴露意图避免花里胡哨full全量保留完整对话历史同时根据需求注入当前目录结构、文件内容或检索片段。适合调试、代码走读、对信息完整性要求极高的场景。compact对话历史超过一定阈值时先压缩成一份结构化摘要保留最近若干轮原文。适合长会话、日常问答、成本敏感的场景。auto结合规则与启发式评分动态决定每条历史消息、每个候选文件是否值得进入请求。适合大多数日常使用。三种模式不是简单的好坏关系而是在“信息完整度”“token 成本”“响应速度”三条轴上做取舍。做一个可选方案日常聊天用 compact查日志用 full写复杂代码功能时用 auto。有了显式模式发生问题时你能立刻复原出“当时是哪种模式导致的行为”再根据实际效果去调整具体规则。2.2 核心参数与 token 预算计算每个模式背后都依赖一组参数。我把这些参数全部集中在一个配置对象里避免到处硬编码。核心参数大概是这些参数名称含义示例值max_context_tokens模型允许的最大上下文长度128000max_response_tokens给模型生成回答预留的空间4096compact_trigger_ratio触发压缩的阈值比例0.6recent_rounds_keptcompact 模式下保留最近几轮原文6retrieval_top_kauto 模式下最多注入片段数量5这里有一个非常重要的计算逻辑可用上下文预算并不是max_context_tokens而是要减去max_response_tokens再减去 system prompt、工具定义、消息格式开销等。比如 128K 的模型你预留 4K 作为输出再扣掉 2K 的系统提示与格式开销真正可以自由分配的输入历史大约是 122K。如果超过了这个数就必须触发压缩或截断。我最初犯过一个错误只看模型文档说窗口 128K就把整个项目代码全部塞进去结果经常在长对话中突然报错 context length exceeded。后来我把预算计算写成一个函数每次请求前打印一份“预算账单”把所有占用都列出来问题一下子就清晰了。2.3 显式枚举模式带来的工程收益为什么要坚持显式枚举而不是一个总开关我想强调一个工程价值可测试性与可回滚性。当你把上下文策略变成枚举后你可以针对每个模式写独立的测试用例。比如“compact 模式下超过阈值的旧消息必须被摘要替换”“auto 模式下关键词不命中的历史消息应该被丢弃”。这样每次改规则跑一遍测试就能知道有没有破坏既有行为。第二个收益是灰度发布。团队协作时你可以让一部分人默认走 auto另一部分人走 compact线上对比效果而不是一把梭全自动。正因为模式是显式的你才能在问题出现时快速锁定变量。3. 核心实现token 计算、历史压缩与上下文注入3.1 token 计算的正确姿势不要用“一个汉字约等于一个 token”这种粗略估算来管理上下文。不同模型的 tokenizer 差异很大代码里的空格、缩进、中英文混排都会影响实际 token 数。正确做法是用模型对应的 tokenizer 库来精确统计。Python 生态里最常用的就是tiktoken。下面是我在项目里用的一个工具函数逻辑上参考了 OpenAI 官方 cookbook 的计数思路import tiktoken def count_message_tokens(messages, modelgpt-4o): try: encoder tiktoken.encoding_for_model(model) except KeyError: encoder tiktoken.get_encoding(cl100k_base) tokens_per_message 3 tokens_per_name 1 total 0 for msg in messages: total tokens_per_message if role : msg.get(role): total len(encoder.encode(role)) if name : msg.get(name): total tokens_per_name len(encoder.encode(name)) if content : msg.get(content): total len(encoder.encode(content)) # 每个完整的请求末尾还有一个格式提示 token total 3 return total注意这里的细节role本身也占 token因为协议里是明文记录的每条消息有一个基础格式开销大约是 3 个 token。很多人在本地估算时只看 content 长度结果实际请求到服务端总是略微超出就是因为漏了这些隐形成本。计数函数返回的是整个messages数组的合计值后面所有压缩判断都以这个值为准。3.2 compact 模式的实现摘要压缩还是截断裁剪compact 是长对话场景下最关键的兜底方案。但“压缩历史”有两个容易混淆的做法很多人直接二选一却不知道它们各有适用场景。第一种叫截断裁剪简单来说就是只保留最近 N 轮对话更早的全部丢弃。实现成本最低但副作用很明显早期约定的关键约束、已经确认过的事实都会丢失。第二种叫摘要压缩用一个较便宜的模型把整段历史转写成结构化摘要把“过程”浓缩成“结论”。它能保留住核心信息但会引入额外一次模型调用并且存在摘要模型本身出错的风险。我实际采用的是混合策略当历史 token 超过阈值时先用摘要模型把最旧的部分转成一段摘要插入 system 位置同时保留最近几轮原文。这样既保住了长期约束又让近期对话保持完整细节。触发压缩的代码可以抽象成这样def maybe_compact(self, messages, current_total): budget self.max_context_tokens - self.max_response_tokens if current_total budget * self.compact_trigger_ratio: return messages, False old_part messages[:-self.recent_rounds_kept * 2] recent_part messages[-self.recent_rounds_kept * 2:] if len(old_part) 2: return recent_part, True summary self.summarize(old_part, target_tokensint(budget * 0.2)) compacted [{ role: system, content: 以下是更早对话的结构化摘要其中的事实和约束必须遵守 summary }] recent_part return compacted, True这里recent_rounds_kept * 2是因为每一轮对话至少包含一条 user 和一条 assistant 消息取两倍才能完整保留 N 轮。压缩目标控制在总预算的 20%是为了给后续可能追加的文件内容留出空间。3.3 auto 模式的实现动态保留哪些上下文auto 模式的难点在于“判断”。完整做法是用 embedding 做语义相似度检索但如果你只是做一个命令行工具第一版完全可以用轻量规则完成效果也不差。我的方案是一个两层筛选第一层是硬性规则比如 system 指令永远保留、用户手动标记为固定内容比如写[PIN]的片段强制保留、最近两轮对话无条件保留。第二层是相关性打分用当前用户输入与每条历史消息做关键词重叠计算分数过低的早期历史直接丢弃。相关性打分函数大概长这样我用正则抽取出中英文词元再计算交集占比import re def relevance_score(question: str, message: str) - float: def tokens(text): return set(re.findall(r[a-zA-Z0-9\u4e00-\u9fff], text.lower())) q_tokens tokens(question) m_tokens tokens(message) if not q_tokens: return 0.0 return len(q_tokens m_tokens) / len(q_tokens)这个方法说白了就是“如果历史消息里包含当前问题里的关键词保留价值就高”。对于写代码、查日志这类任务其实很有效因为问题里通常包含函数名、文件名、端口号等强信号词。等基础版本跑通后再切换到 embedding 向量检索也不迟两者在结构上可以无缝替换。auto 模式还有个细节文件注入也要做相关性筛选而不是一股脑把目录下所有文件读进来。我会生成目录树让模型自己告诉我它需要哪个文件或者根据扩展名排除node_modules、.git、__pycache__这类噪声文件夹。3.4 核心类的完整骨架把上面这些逻辑整合起来核心的ContextManager类大概长这样dataclass class ContextManager: mode: str auto model: str gpt-4o max_context_tokens: int 128000 max_response_tokens: int 4096 compact_trigger_ratio: float 0.6 recent_rounds_kept: int 6 def build_messages(self, session, user_input, search_resultsNone): history list(session[messages]) if search_results: context_block format_search_results(search_results) user_input f{context_block}\n\n{user_input} history.append({role: user, content: user_input}) if self.mode compact: history, _ self.maybe_compact(history) if self.mode auto: history self.filter_relevant_history(history, user_input) return history值得注意的一点是build_messages不修改session[messages]本身只返回新的副本。这样下次请求仍然基于原始会话而不是基于被截断或压缩过的临时消息。很多出问题的项目就是因为这里偷懒直接改了原始状态导致一次压缩后所有后续轮次的历史都“永久失忆”。4. 实操全过程从零打造支持 context-mode 的 AI 命令行助手4.1 环境准备与依赖选择为了让这套方案能立刻跑起来我以 Python 3.11 为例构建了一个最小可用的 CLI 工具。依赖只有四个openai负责大模型 API 调用tiktoken负责 token 计数typer负责命令行参数解析rich负责终端输出美化。安装命令一行搞定pip install openai tiktoken typer rich项目目录结构也很简单我习惯从一开始就分模块避免什么逻辑都堆在入口文件里ai-cli/ ├── main.py # CLI 入口 ├── context_manager.py # 上下文策略核心 ├── session_store.py # 会话持久化 └── requirements.txt选用typer而不是标准库argparse是因为它写起来更贴近业务逻辑而且能自动生成帮助文档。命令行工具对参数提示的友好度很重要毕竟是给自己天天用的帮助信息写得清不清楚直接决定使用体验。4.2 实现步骤与关键代码第一步定义 CLI 入口。我给--context-mode设置了三个可选值并让它成为日常使用中可以被随时切换的开关ai --context-mode auto 帮我检查当前目录的代码有没有潜在 bug ai --context-mode full --file error.log 分析这个报错 ai --context-mode compact --new-session 继续聊昨天那个爬虫方案第二步实现会话持久化。为了简单起见我用 JSON 文件存储对话历史每个会话一个文件文件名就是会话 ID。关键是文件里要同时记录这条会话当时使用的是哪个 context-mode否则后期切换模式时很容易出问题。第三步在main.py里组装逻辑读取配置、加载会话、调用ContextManager.build_messages、把最终 messages 发给模型、流式打印结果。最后把这次的 user 和 assistant 消息写回会话文件。我给一段极简的核心调用代码供参考import typer from openai import OpenAI from context_manager import ContextManager from session_store import load_session, save_session app typer.Typer() client OpenAI() app.command() def run( prompt: str, context_mode: str typer.Option(auto, --context-mode), new_session: bool typer.Option(False, --new-session), ): sid default if not new_session else uuid4().hex session load_session(sid) manager ContextManager(modecontext_mode) messages manager.build_messages(session, prompt) resp client.chat.completions.create( modelgpt-4o, messagesmessages, max_tokensmanager.max_response_tokens, ) reply resp.choices[0].message.content print(reply) session[messages].append({role: user, content: prompt}) session[messages].append({role: assistant, content: reply}) save_session(sid, session) if __name__ __main__: app()到这一步工具已经可以用了但还只是一般意义上的“带记忆的 CLI”context-mode 的价值要在多轮对话和文件注入的混合场景下才会完全显现。4.3 实测效果对比与现场记录为了直观展示三种模式的差异我设计了一个实验。场景是一个 Python 项目包含src/、tests/、pyproject.toml和一份 README。第一轮问模型“这个项目的入口文件在哪里依赖管理用的什么工具”第二轮接着问“入口文件里的 main 函数大致做了什么”实测结果记录如下模式第一轮消耗第二轮消耗回答准确度备注full3.1K tokens8.4K tokens较高但夹杂冗余信息把所有文件都读进来耗时明显偏长compact3.1K tokens3.9K tokens中等若摘要丢掉了函数名第二轮会回答不准auto3.1K tokens4.2K tokens高只注入了 README、pyproject.toml 和入口文件速度快full 模式第二轮是把第一轮的完整对话再带上所以 token 接近翻倍compact 模式把第一轮压缩成摘要正文信息大幅减少auto 模式依靠关键词匹配保留了第一轮里关于“入口函数”的描述并重新注入了目标文件所以在成本和准确度之间取得了平衡。这个结果完全符合预期。对于我这个场景auto 是日常最佳选择但调试复杂问题的时候我仍然会切换到 full宁可多花 token也要保证模型看到的每一处细节都是原文。5. 常见问题与排查技巧实录5.1 请求一直报 context length exceeded这个报错几乎是上下文工程入门的必经一课。报错信息通常会直接写明当前模型最大支持多少 token以及本次请求用了多少 token。但问题是它给出的数字往往比你本地统计的高出一截因为 SDK 还会自动加入一些你未必感知到的内容。我的排查习惯是在发起请求前先打印一份完整的预算账单包含 messages 总数、system prompt 字数、注入文件片段大小、max_tokens 值然后逐项相加。如果本地统计正常但服务端还是报超限重点检查是否有多处代码重复追加了同一段历史。最常见的情况就是 session 里的消息已经被build_messages添加了一遍调用处又傻乎乎地把新用户输入再追加了一次。5.2 模型越往后越“笨”忘了早期要求如果你发现对话超过二十轮后模型开始忽略你在前面明确说过的约束先别怪模型。大概率是你的请求里历史消息过长模型窗口接近上限服务端或 SDK 选择静默丢弃了最旧的部分。这种情况不会报错但行为上就是“失忆”。要验证这一点只需在请求前对比窗口预算和实际消息总 token。如果已经超过预算并且你没有走压缩逻辑那就是这个原因。解决办法是在build_messages里强制调用maybe_compact把压缩作为兜底而不是可选项。另外一个经验是重要约束写两遍一遍放在 system prompt 里一遍在用户首次提出时用[PIN]标记这样即使历史被压缩关键信息也不会丢。5.3 切换 context-mode 后上下文混乱这个问题非常有代表性。假设你前二十轮用的 compact 模式会话文件里已经存了一段摘要消息后来又切换成 full 模式。此时如果你直接把新旧消息混合发送模型会同时看到“摘要版本的旧历史”和“完整版本的旧历史”内容互相重复甚至矛盾回答质量断崖式下降。解决办法很简单会话状态里记录当前模式一旦检测到切换先根据新模式重建上下文。例如切到 compact 时重新生成摘要并丢掉过长的原文切到 full 时如果本地存储里没有完整历史就明确告诉模型“之前的对话已丢失请从摘要中恢复关键信息”。不要指望一份原始 messages 通吃所有模式。5.4 多终端并发导致会话串线开发 CLI 工具时如果只是单进程跑通常不会遇到这个问题。但当你用 tmux 同时开了几个窗口每个窗口跑一个ai命令时就可能出现 A 窗口的回答带上了 B 窗口的历史。原因十有八九是代码里用了一个全局变量保存 messages而不是以会话 ID 为单位隔离状态。排查方向也直接检查是不是存在模块级messages []这种写法。任何生产级工具都建议用会话文件或键值数据库做存储并且在每个请求入口显式传入 session_id。全局可变状态是这类 bug 的温床尽早消灭。下面整理成一张速查表方便遇到问题时对号入座现象可能原因解决动作报 context length exceeded历史消息和文件注入超过窗口预算触发提前压缩或降低 max_response_tokens模型忘了早期约束历史过长被静默截断开启 compact关键约束写进 system prompt切换模式后回答重复或矛盾摘要消息和完整历史被同时发送模式切换时重建会话上下文多个终端窗口上下文串线全局变量保存了 messages按会话 ID 隔离状态禁止全局列表最后分享两个我实测后沉淀下来的小技巧第一个技巧是给每个任务固定默认模式。比如我用alias ai-codeai --context-mode auto、alias ai-logai --context-mode full这种形式让不同类型的任务自动落到最合适的模式上而不是天天手动去记“这次该用哪个”。实践下来比单一全智能的默认模式可靠得多。第二个技巧是在 system prompt 里告诉模型一个特殊约定一旦它发现自己的上下文序列里出现了“被压缩摘要”这样的段落并且后续回答需要某个摘要里没有的细节它可以主动提示我“该切回 full 模式重新加载完整历史”。这相当于把模式判断的一部分决策权交给模型让它在关键时刻给出补救建议。这个小改动并不复杂却让工具在长会话里的可用性提升了一个档次。