最近在项目里重度使用 Coding Agent 做日常开发我最大的感受是这玩意儿确实是干活利器但论吃 Token 的速度也确实是刺客级别的。尤其是当你让它自己跑一遍构建、执行一轮测试终端里哗啦啦滚出上千行日志如果 Agent 把这些文本一股脑全读进上下文那后面基本就不用干了——上下文被日志填满模型开始“失忆”刚才还在处理的需求转头就忘更别提那肉眼可见飞涨的账单。这个场景我用一句话总结Token 刺客 上下文爆仓一个治钱一个治命。这篇文章不打算聊选模型也不聊怎么写提示词而是聚焦一个被很多人忽略、但几乎所有重度用户都会撞上的环节终端输出处理。核心思路是给 Coding Agent 的输出通道加一层“剪枝逻辑”把终端输出里的无效信息压掉 98% 左右只把错误、警告和关键摘要放进上下文。原理不复杂实现也谈不上难但做完之后Token 消耗下降非常明显上下文能被用在真正该用的地方Agent 干活时的连贯性和准确率都会有肉眼可见的提升。不管你是用 Claude Code、Codex CLI还是自己在写 multi-agent 框架这套思路都能直接套。1. 痛点的本质终端输出不是“信息”而是“噪音”1.1 一次构建测试到底烧掉了多少 Token先算一笔账。很多 Agent 工具会把终端输出以对话消息的形式注入上下文你看着是几千行日志实际上每一行都在“真金白银”地消耗 Token。假设一次 Java 构建输出 2000 行日志平均每行 60 个字符——这在 Maven/Gradle 输出里已经算很收敛了毕竟很多时候光依赖下载进度和任务列表就远不止这个量。那么总字符数约 12 万。按照英文为主的日志粗略换算4 个字符约等于 1 个 Token这就是 3 万 Token如果是中文日志或者带上了堆栈信息Token 数还会更高。3 万 Token 是什么概念它相当于一篇中等长度的技术文档全文。换句话说你让 Agent 跑一次构建还没开始分析问题就已经把三篇技术文档的“阅读量”喂给它了。跑两三次构建、执行几轮测试上下文窗口就已经被这些日志塞得差不多了。而且这还只是构建场景。真正的重灾区是测试场景一次全量跑出几百上千条测试结果每条结果包含测试名、耗时、通过/失败状态有的还会带断言差异和堆栈。如果完整发给 Agent动辄就是几十万字符换算下来接近十万级 Token。我见过最夸张的一次是某个同事在 Agent 会话里连续跑了三轮测试每次终端输出都有四五千行。三轮下来光测试日志就占了 30 多万 Token 的上下文整个会话直接废掉——模型开始反复重复自己说过的话连用户指定的目录路径都会记错。所以问题的核心不是“终端输出了多少行”而是“Agent 的输入通道把多少噪音当成信号读了进去”。要想让 Coding Agent 高效工作第一步就是把终端输出当作一道数据管道来处理而不是当作对话消息直接灌给模型。1.2 上下文爆仓不是“提示词工程”能解决的很多朋友遇到上下文效果变差第一反应是修改提示词或者换更大的上下文窗口。这两个方向都治标不治本。先说提示词。提示词能约束模型的行为偏好但没法改变模型接收到的输入质量。终端日志里有大量重复性内容比如 Maven 下载依赖的进度条、Webpack 的编译模块列表、Docker 构建过程中的中间层提示——这些内容无论提示词写得多么精妙模型读进去之后照样会占据注意力资源和上下文空间。有个生活化的类比你让一个助理帮你分析仓库的问题结果你把整个仓库的杂物清单都丢给他让他自己筛。他确实能筛但费时费力而且容易漏掉真正重要的东西。提示词就是告诉他“仔细一点”但杂物清单本身仍然在消耗他的精力。再说扩大上下文窗口。现在 Claude Code 这类工具已经有 1M 上下文的选项听起来很大但别忘了上下文窗口变大模型要处理的输入规模也变大单次请求延迟和开销都会上升而且当窗口被无效内容占满时和 100K 窗口被占满的效果是一样的——模型一样会失忆、一样会跑偏只是“爆仓”的时间点延后了。更关键的是大上下文窗口本身就意味着更高昂的成本日志这种低密度信息根本不配占用这么贵的资源。这里我想重点说一下实践中的体会上下文工程和提示词工程一样重要但前者常常被忽略。上下文工程的核心不是“把窗口撑大”而是“让进入窗口的每一段文字都有明确用处”。终端输出剪枝就是上下文工程里最基础、也最容易出效果的一环。它不是让你牺牲信息量而是帮模型过滤掉 98% 的垃圾把精力集中在真正解决问题的那 2% 上。1.3 “98% 剪枝”不是拍脑袋是统计出来的很多人看到“98% 输出剪枝”这种说法第一反应可能是夸张。我当时也怀疑过但做过一次统计之后就信了。挑一个典型的构建失败场景来做样本原始终端输出大概有 2600 行。我人工标注了一番真正需要模型看的内容包括编译错误的位置和原因描述、失败任务的名称、几个相关的警告、最后的状态码加上出错前后的少量上下文行。我数了一下这些关键内容加起来大概 40 行出头。从 2600 行到 40 行压缩率是 98.5%。再举一个测试场景的例子一次测试跑了 4800 条用例终端输出大约 8000 行其中绝大部分是进度和通过状态。失败用例只有 13 条每条的关键信息用例名、断言差异、堆栈首行加起来不到 60 行。压缩率也在 98% 以上。你会发现一个规律终端输出绝大多数是“状态类信息”而不是“问题类信息”。状态类信息的特点是数量巨大、内容重复、对模型决策帮助有限问题类信息的特点是数量稀少、上下文敏感、恰恰是模型真正需要的东西。所谓剪枝就是在管道层把这两类信息拆开优先保证问题类信息无损进入上下文再对状态类信息做少量保留用于给模型提供整体判断的依据。这个思路和剪枝算法在传统机器学习里的用法是相通的。决策树后剪枝里我们砍掉那些对分类贡献小的分支保留决策能力最强的路径这里的“终端输出剪枝”砍掉的是对决策贡献最小的日志行保留能够帮助模型定位问题的关键路径。本质都是“去除冗余、保留信息密度”。明确了这一点之后剩下的问题就是怎么设计了。2. 方案选型四种终端输出策略我为什么选了分级剪枝2.1 硬截断把尾巴留下但经常把错误也剪掉最早我采用的是最简单的办法让 Agent 执行命令后只把终端输出的最后 N 行发给它比如 tail -n 100。这个方案实现成本极低也确实能大幅减少 Token 消耗但用了几天就发现一个严重问题很多错误信息并不在尾部。编译错误出现在日志中间测试失败散落在各个阶段异常堆栈印在报错的瞬间——这些关键信息根本不在文件的最后 100 行里。tail 截断等于把最重要的信息随随便便丢掉了。最典型的场景是构建到一半失败错误出现在第 500 行到第 800 行之间尾部只有一堆任务取消和状态清理的日志。你只给 Agent 看最后 100 行它看到一个“失败”的结果但完全看不到失败的原因只能瞎猜。硬截断适合的场景是你明确知道这个命令的输出结构比如 git status 的输出本来就几十行tail -n 20 完全够用。但在构建、测试、部署这类输出结构不可预测的命令上硬截断就是在玩火。2.2 关键词过滤精准但容易漏上下文第二个想法是关键词过滤核心是用 grep 提取包含 ERROR、FAILED、Exception 等关键词的行把这些行发给 Agent。这个方案比 tail 靠谱得多因为它是“按内容保序”而不是“按位置截断”。实际用下来关键词过滤有两个痛处。一是过度依赖关键词的完备性。我踩过最典型的坑某次前端构建报错的关键词是 “[!]” 和 “Build failed”我的过滤规则里只写了 ERROR 和 error结果所有有效信息全被 filter 掉了Agent 看到的是一段完全正常的输出——它还真以为构建成功了开始兴致勃勃地分析别的。二是过滤出来的行“太干”。错误行往往需要结合前后几行才能看懂比如 “Module not found: Cant resolve xxx” 只给这一行不给 import 语句的上下文Agent 并不知道是哪个文件里的哪个导入出了问题。关键词过滤适合用来做“预筛”但不适合作为最终交付。它更大的价值是作为一个模块放在剪枝管道里承担第一道粗筛的工作。2.3 LLM 压缩摘要看着高级成本反而更高第三种方案是让大模型自己来压缩。理论上很优雅执行完命令后先让一个轻量模型读完整份日志输出摘要再把这个摘要交给主 Agent。这样信息密度高而且摘要可以用很自然的方式保留逻辑重点。但算一笔账就发现不对劲。如果原始终端输出是 10 万字符折合约 2.5 万 Token让轻量模型读 2.5 万 Token、输出 2000 Token 的摘要成本大约是多一次模型调用的费用。一次两次还能接受问题是每次运行构建都要走这个流程累积下来比直接给主 Agent 读完整日志更贵。要是团队里几十个人都在用这笔费用会非常可观。更隐蔽的问题是摘要模型本身也有可能漏信息。日志里的错误很可能是“意外模式”不符合摘要模型“把重点归纳出来”的倾向它在压缩时可能把某个隐藏很深的异常丢掉了而下游主 Agent 根本无从知晓这个缺失。这一点是最致命的——我们做剪枝的目的就是提高信息确定性结果摘要环节反而引入了一层新的不确定性。LLM 压缩不是不能用但它更适合用在那些“内容本身很短、但需要跨大段信息归纳”的场景比如让 Agent 总结一天的会话记录。对于终端输出这种高噪声、低密度的数据流让 LLM 当中间商性价比很低。2.4 分级剪枝把“信息”和“噪音”分开处理综合前面几次踩坑最终确定的设计是分级剪枝管道。核心思路就一句话不统一规则而是按信息优先级分层处理。第一层是预过滤。把不需要逐行分析的内容直接丢掉比如依赖下载进度、构建任务列表、测试通过的逐条结果。这些内容出现频率高、信息量低即使偶尔对整体判断有点用也可以被后续的关键摘要替代。预过滤最粗暴的实现就是关键词过滤加上行模式匹配比如匹配到成功的状态标记就跳过。第二层是核心抽取。针对错误、警告、失败等关键信号连同它们前后若干行一起提取。这里有一个关键点不单独提取出错的这一行而是保留“信号行 上下文行”这样模型可以看到错误是在什么环境下发生的而不是面对一句孤立的话凭空猜测。第三层是尾部摘要。保留终端输出的最后若干行让模型感知到命令整体的收尾状态尤其是退出码、失败汇总、总体统计等信息。之所以保留尾部是因为很多命令行工具包括 JUnit、pytest、Gradle都会在输出末尾做一次总结。第四层是行数预算控制。给每一层设定 Token 配额一旦超出就按优先级截断。总预算通常设置在 1500 到 3000 Token 之间足够覆盖绝大多数日志场景。这套方案的好处是它不是“选一种方式处理所有输出”而是对不同类型的行采取不同的处理方式。它既保留了硬截断的成本控制力又兼顾了关键词过滤的信息提取精度还避免了 LLM 压缩的额外开销。我实际用了一个多月体感非常稳下面的篇幅我会把具体实现和跑出来的效果数据写出来。3. 实操给 Coding Agent 装一条剪枝管道3.1 设计原则在 Agent 的“手”前面加一道闸先说清楚一个关键点Coding Agent 执行终端命令的方式本质上是把命令交到系统的子进程里跑然后把子进程的输出捕获回来作为模型的输入。所以我们要做的就是在“子进程输出”和“模型输入”之间加一道闸。这道闸的实现方式取决于你用的是哪种工具。用 Claude Code、Codex CLI 这类现成产品时一般没法直接改它的内部数据流但有两条可行的路径一是修改工具配置里的命令执行前端。比如在 Claude Code 里通过钩子函数hook在工具调用后对输出做一步后处理在 Codex CLI 里某些版本也支持通过自定义工具或插件方式接管输出。二是更通用的做法不让 Agent 直接执行重命令而是让它执行一个包装脚本脚本负责跑原始命令、把完整输出落盘到临时文件、执行剪枝逻辑、再把剪枝后的结果返回。这样无论底层工具是什么都能在不改工具内部的前提下完成剪枝。我自己用的是第二种方式因为它在不同工具之间可迁移性最强而且出了问题可以直接对着脚本排查不用翻工具的源码。下面给出一套可以照搬的简化实现。3.2 核心实现一套可复制的剪枝脚本我用 Node.js 实现了一套剪枝脚本直接用 Python、Shell 重写也没问题核心逻辑是一致的。// prune-output.js // 用法: node prune-output.js log-file [max-tokens] const fs require(fs); // 信号正则按优先级排序 const SIGNAL_PATTERNS [ { type: error, regex: /\b(error|exception|failed|failure|fatal|error:)\b/i }, { type: warning, regex: /\b(warn|warning|cannot|unable|no such)\b/i }, { type: summary, regex: /\b(tests?\s*(run|passed|failed)|build\s*(success|failed)|exit\s*code|total)\b/i }, ]; const CONTEXT_BEFORE 2; // 信号行前保留行数 const CONTEXT_AFTER 3; // 信号行后保留行数 const OUTPUT_LIMIT 2500; // 剪枝后输出 Token 上限估算 function estimateTokens(text) { // 粗略估算英文约 4 字符/Token中文约 0.6 字/Token // 这里统一用字符数除以 3 近似 return Math.ceil(text.length / 3); } function prune(logPath) { const raw fs.readFileSync(logPath, utf8); const lines raw.split(/\r?\n/); const selected new Set(); const signals []; for (let i 0; i lines.length; i) { const line lines[i]; for (const p of SIGNAL_PATTERNS) { if (p.regex.test(line)) { signals.push({ index: i, type: p.type, line }); // 保留信号行及上下文行 for (let j Math.max(0, i - CONTEXT_BEFORE); j Math.min(lines.length - 1, i CONTEXT_AFTER); j) { selected.add(j); } break; } } } // 尾部摘要保留最后 30 行 const tailStart Math.max(0, lines.length - 30); for (let i tailStart; i lines.length; i) selected.add(i); // 按行号排序输出 const cleaned [...selected].sort((a, b) a - b).map(i lines[i]); // 如果超出预算优先截断尾部摘要 let result cleaned.join(\n); while (estimateTokens(result) OUTPUT_LIMIT cleaned.length 10) { cleaned.splice(cleaned.length - 1); result cleaned.join(\n); } return { originalLines: lines.length, outputLines: cleaned.length, signals, pruned: result, }; } const logPath process.argv[2]; if (!logPath) { console.error(请指定日志文件路径); process.exit(1); } const result prune(logPath); console.log( 剪枝统计 ); console.log(原始行数: ${result.originalLines}); console.log(剪枝后行数: ${result.outputLines}); console.log(压缩率: ${((1 - result.outputLines / result.originalLines) * 100).toFixed(1)}%); console.log(捕获信号数: ${result.signals.length}${result.signals.map(s s.type).join(, )}); console.log( 剪枝后内容 ); console.log(result.pruned);这套脚本的逻辑分成四块第一块是信号匹配预定义了三类信号错误、警告、总结。匹配顺序很关键错误优先级最高、警告次之、总结最低。这样同一行命中多个模式时不会重复标记。针对实际项目可以把 ERROR、FAILED 之外的自定义关键词加进去比如团队内部约定好的错误前缀。第二块是上下文行的保留。这是 2.2 节讲过的坑的解决方案信号行前后各保留几行让模型能理解错误发生的环境。默认是前 2 后 3针对堆栈信息比较密集的场景可以把前 5 后 8 调大。第三块是尾部摘要。保留最后 30 行让模型知道命令的最终状态。注意尾部摘要和信号行要按原始顺序合并输出不要去重保持时间顺序很重要。第四块是 Token 预算控制。用字符数除以 3 来估算 Token 数虽然不够严谨但作为工程上的近似够用了。一旦剪枝结果超出预算就从行尾部开始截——因为尾部摘要的优先级低于信号内容但高于普通噪音。脚本本身不直接与 Agent 交互它只负责“处理日志文件”。配合上一层封装就能接入到 Agent 流程里了。3.3 与 Agent 提示词配合让模型知道“你看到的是剪过的内容”剪枝脚本给 Agent 的内容越干净模型就越依赖你说清楚“什么被剪掉了”。这是很多人会忽略的一步。我的通用做法是在 Agent 的系统提示词里加这样一段终端输出说明 - 命令执行过程中终端输出已经过剪枝处理原始完整日志保存在 /tmp/agent-logs/{command-id}.log。 - 当前提供给模型的是剪枝后的内容仅包含错误信号、警告信号、关键上下文和尾部摘要。 - 如果剪枝后的内容不足以定位问题优先读取原始日志文件中的对应区域而不是猜测错误原因。 - 剪枝统计会在内容开头提供原始行数、剪枝后行数和压缩率可以参考压缩率判断信息的完整度。这段提示词并非可有可无。它实际上承担了三个职责一是防止模型在信息不足时强行推理二是告诉模型“原始日志在哪里”给了它一个主动回溯的入口三是让模型理解剪枝统计的含义比如压缩率高达 99% 时说明原始输出里绝大多数都是噪音模型应该相信剩下的内容是重点。在遇到剪枝后仍然无法定位问题的场景时我会让 Agent 主动去读原始日志文件里对应行号附近的内容。因为剪枝脚本支持输出保留行的原始行号我在生产环境里的版本会把行号信息也带上比如[L123] [error] com.example.api.AuthService: token validation failed [L122] at com.example.api.AuthController.checkAuth(AuthController.java:45)这样模型拿到剪枝内容后如果觉得信息不够可以直接定位到原始日志的第 122 到 123 行附近做二次阅读。这个设计相当于给剪枝装了一个“可追溯性”的保险既默认提供高密度信息又保留了按需回溯原始上下文的能力。3.4 效果验证数据说话脚本落到生产环境之后我在真实项目里跑了三周挑了三种典型命令做对比Maven 构建、pytest 全量测试、npm 构建。记录剪枝前后 Token 预估用量和模型任务完成情况。场景原始行数原始 Token 估算剪枝后行数剪枝后 Token 估算压缩率Maven 构建失败2630约 3200046约 110096.6%pytest 全量测试4800 条用例8200约 4900058约 140097.2%npm 构建 部署3700约 2300035约 90098.4%实际跑下来压缩率稳定在 96% 到 98.5% 之间和文章标题里说的 98% 基本吻合。更重要的是任务完成质量同样一个构建失败剪枝前 Agent 要花三四轮去翻日志找原因剪枝后通常一两轮就能定位到根因因为它一上来就看到了错误行本身而不是被埋在几千行日志里。这里要特别提醒一点压缩率只是一个参考指标不要为了追求数据好看而疯狂压缩。核心指标应该是“模型解决任务的成功率”。我见过有人把输出预算压到 500 Token 以内结果错误信息本身就被截掉了Agent 开始输出一堆猜测反倒多花了好几轮对话。剪枝的目标是让信息密度足够高而不是削到只剩骨头。还有一个容易被忽略的收益剪枝之后单轮对话的响应时延会明显下降。因为模型输入变短了prefill 阶段的计算量大幅减少整个请求的处理速度都会更快。终端输出动辄几万 Token 的场景里剪枝后的单轮时延从十几秒降到了五六秒这个体感提升非常明显。4. 上下文治理与 Token 预算的立体打法4.1 剪枝只是治标治本要靠会话结构管理剪枝解决了“终端输出塞爆上下文”的急性问题但如果一个 Coding Agent 会话里做了很多件不同的事、讨论了很多个文件上下文仍然会被正常的业务内容填满。所以我说剪枝是治标真正要把上下文管好还要配合会话结构管理。我的习惯是“一个会话只干一件事”。比如这次会话就修这个 bug或者就做这个功能模块。如果中间要穿插别的任务我会先让 Agent 把当前任务的结论、下一步计划和关键文件路径整理成摘要然后新开会话把摘要和原任务的关键信息带过去。这个动作只花几分钟但能保证每个会话的上下文都保持在一个可控的密度上。这背后其实是一个工程取舍长会话的优势是“记忆连续性”但代价是上下文里累积了大量中间过程包括各种试错、中间版本、被推翻的方案。这些中间过程有信息价值但对最终决策来说是冗余的。和代码版本管理一样上下文也可以做 commit——定期总结、压缩、把最新的状态固化下来而不是把所有的 diff 都堆在一个超长会话里。4.2 Token 生命周期管理与“续签”机制接下来聊点偏工程的话题Token 的生命周期。这里说的 Token 有两种一个是我们一直在讨论的模型 Token另一个是登录认证用的 Token。模型 Token 的预算管理本质上就是“会话的钱包管理”。我在实践中给每个会话设定一个预算上限比如 5 万 Token。当用量接近上限时主动让 Agent 做一次中期总结把中间过程沉淀成结论然后决定是继续如果任务即将完成还是新开会话如果任务还很长。这个策略有点像 JWT 的 access token 和 refresh token 的关系access token 有效期短保证单次会话的安全和控制refresh token 有效期长负责在需要时延续会话。我们的“会话摘要”就是那个 refresh token新会话通过读取摘要来延续上下文而不是带着全部历史数据重新开始。再说登录认证 Token。这段时间“token exchange failed”在开发者社区里的求助非常多我自己也踩过。常见的报错包括 sign-in could not be completed、token endpoint returned 403、token exchange failed: error sending request 等。这类问题大多数是环境层面的和 Agent 本身的代码逻辑无关。我总结出一套三层排查法第一层检查本地配置。很多 CLI 工具把认证信息存在用户目录下的配置文件里比如 ~/.codex/config.toml 或类似路径。这些文件经常在升级后被重置或者被其他的工具覆盖写入导致 Token 丢失或过期。处理方法通常是重新执行登录流程让工具重新生成认证信息。第二层检查环境变量和系统时间。工具通过环境变量读取 token如果换了个终端、加载过不同的 shell 配置环境变量没带上就会出问题。系统时间偏差也会导致 JWT 的过期校验失败这是个特别隐蔽的原因——时间快慢了十几分钟token 要么提前过期要么被当成“未来签发”的无效凭证。第三层检查工具版本。CLI 工具的认证逻辑会随版本迭代变化如果还停在旧版本而后端已经升级了认证接口就会出现 token exchange 失败。这种情况升级到最新版本基本能解决。处理这些报错时的一个体感是不要一上来就怀疑工具坏了。绝大多数 token 类报错都出在配置、环境、版本三件事上按这个顺序排查效率最高。4.3 压缩、检索、剪枝的组合拳最后说说剪枝和其他上下文管理手段怎么配合。剪枝负责“入口控制”保证进入上下文的内容信息密度高会话摘要负责“出口沉淀”把中间过程压缩成可复用的结论RAG 式检索负责“按需读取”在需要时去原始日志或代码库里找细节。三层各管一段组合起来才是完整的上下文工程。拿一个具体场景举例Agent 在分析一次线上问题它拿到了经过剪枝的报错信息、看到了异常栈的首行但需要更完整的堆栈才能定位问题。这时候它可以按行号去原始日志文件里查询对应区域。这个查询本身产生的 Token 是定向的只读需要的几十行而不是把整份日志重新灌进来。这其实就是 RAG 的思路不要一次性把所有信息塞进上下文而是提供“查询接口”让模型按需获取。压缩策略触发时机也很关键。我一般设定上下文占用 70% 作为警戒线超过之后主动触发一次会话压缩把已有的讨论和结论提炼成摘要如果压缩后仍然接近上限就完整地做一次交接开一个新会话继续。这个 70% 是经验值不是算法算出来的但实测下来比等到“爆仓”再处理舒服得多。5. 踩坑实录与排查速查表5.1 登录态失效与 Token 刷新失败怎么排查这部分在 4.2 节已经讲了核心思路这里把可能会碰到的具体情况列出来。第一类sign-in could not be completed, token exchange failed。这类报错最常见的触发场景是换了网络环境后重新登录或者多个工具共用一套认证凭据导致冲突。排查顺序先重新执行官方登录流程看能不能恢复不行就检查配置文件里是否有多余的旧 token 残留再检查环境变量有没有把 token 传给当前进程。第二类token endpoint returned 403。这个报错往往意味着认证服务器拒绝了你当前的凭据。重点检查权限范围是否被收窄以及凭据是否在团队内被共享/轮换。如果有管理员后台看下操作日志里最近有没有异常的失败记录。第三类login server error: error sending request。这类报错偏网络层面但大多数根因还是承载认证请求的客户端配置出了问题比如本地网络环境中的转发配置、证书链异常等。建议按“配置文件 → 环境变量 → 工具升级”的顺序逐步排查。排查几轮还不行最稳妥的做法是把配置目录移走比如改名备份强制工具重新走一遍初始化流程这样至少能排除“配置损坏”这个最常见的坑。我遇到过一个很刁钻的情况某个工具在旧版本里写入的配置格式和新版本不兼容导致新版本起来后一直拿不到 token最终是靠重置配置目录解决的。5.2 “上下文已使用满”时先做这四件事上下文爆仓是每个重度使用者都绕不开的坎。不同工具报错文案不同有的显示“上下文已使用满”有的告诉你“请启用更大上下文后重试”但处理思路是一致的。第一件事确认占用来源。用工具自带的上下文统计功能看看哪些内容占了大头。如果发现大量对话轮次都是终端输出说明剪枝没生效回上一节看看配置。第二件事给 Agent 下达“总结并交接”指令。让它把当前对话里已经确定的事实、结论、未完成事项、关键文件路径整理成一页纸的摘要然后把摘要复制出来。第三件事保存现场并新开会话。新会话里先把摘要粘贴进去再用一句话描述接下来的任务目标。这个过程的本质是“换一种更高效的方式延续上下文”而不是真的从头再来。第四件事去复盘为什么会爆。是单轮终端输出太大是会话拖太长还是中间过程太多针对原因做定向调整而不是每次都靠开新会话续命。我用一个数据来体现这个流程的重要性有一次排查一个并行测试框架的偶发死锁旧会话从早上挂到下午上下文早已爆满Agent 开始反复推荐一些明显不相关的方案。我把当天讨论的结论做成摘要、开新会话十分钟内就定位到了问题所在——并不是模型变聪明了而是它的上下文里终于没有了那些已经过时的中间猜测。5.3 剪枝过度导致“信息失踪”的对策剪枝系统做得越激进遇到“关键信息被剪掉”的概率就越大。我自己至少撞过三次每次都很典型。第一次错误关键词没覆盖住。某个测试框架输出的是 “Process crashed with exit code 2”既不包含 error 也不包含 failed我的正则没匹配到。结果是 Agent 看到一段没有异常标记的日志认为测试通过了继续做后面的任务直到我人工发现不对劲。解决办法是把 “crashed”“exit code” 这类表达也加进信号正则。第二次上下文行太少。有一个运行时异常真正的原因写在错误发生前 20 行的一处资源释放逻辑里我默认只保留前 2 行模型看到的是一个孤立异常完全不知道前置逻辑。后来把构建场景的信号上下文行数调到前 5 后 8情况好很多。第三次尾部摘要被截断。测试失败汇总打印在输出的倒数第 40 行而我的尾部摘要只保留最后 30 行结果失败汇总被裁掉了。这个问题也简单把尾部保留行数从 30 调到 60或者干脆在日志落盘时把最终的 summary 单独记录到另一个文件。这些坑说明一个问题剪枝规则是有“盲区意识”的。你永远不可能用几条正则覆盖所有日志形状所以要设计一个兜底机制当剪枝结果里没有匹配到任何 signal 时不要直接返回“空内容”给模型而是把尾部摘要扩展到更多行并声明“本条命令没有检测到已知信号请人工确认”。这个兜底机制在我后来又遇到几类不常见日志格式时帮我避免了很多次误判。提示剪枝回归到本质其实是“知道什么该留”比“知道什么该丢”更重要。宁可让 Agent 偶尔多读几行冗余信息也不要让它因为信息缺失而产生错误判断。5.4 排查速查表最后整理一张速查表方便你实际开发时对照使用。这张表里收集的是我这段时间在实际项目中遇到的最常见问题每一行都是一个真实的排障过程。你不需要背下来只要遇到问题时回来翻一眼通常能省下不少冤枉时间。症状可能原因处理建议Token 消耗暴涨完整终端输出灌入上下文启动剪枝限制单条命令输出 Token 上限上下文快速爆仓日志/中间过程占比过高定期做会话摘要分段任务Agent 反复猜测但找不对原因关键错误被剪掉检查信号正则覆盖度增大上下文行数模型认为命令执行成功实则失败失败信号未被捕获增加 crash、exit code 等信号词启用兜底机制sign-in could not be completed配置损坏或凭据过期备份并重置配置目录重新走登录流程token endpoint returned 403权限范围或凭据问题检查权限配置确认 token 未被轮换或共享login server error客户端配置异常按配置文件、环境变量、工具版本顺序排查这张表我贴在工位旁边已经好几个月了每次新问题出现都会往上加一行现在它几乎成了团队里 Coding Agent 问题的第一处排查入口。你也可以建立一份自己的速查表因为每个项目的日志格式和易错点都不一样长期积累的价值会越来越大。坦白说这套剪枝方案并不是什么高深的技术它本质上就是一个“信息过滤器”。但它带来的收益远超我的预期——不只是省了 Token更重要的是让 Coding Agent 把注意力放到了它真正该处理的问题上。我在实际使用中最深的体会是工具的能力上限往往不是由模型决定的而是由你喂给它的信息质量决定的。输出剪枝只是上下文工程里的第一步顺着“让每一段输入都有价值”这个思路往下走你可以做会话压缩、自动摘要、按需检索甚至可以针对自己团队的代码库定制一套完全个性化的工作流。最后再分享一个小建议不要只盯着压缩率数字多观察模型在剪枝后能不能更快地定位到根因那才是这套方案真正的价值所在。
Coding Agent 终端输出剪枝：Token 消耗降 98%，上下文不再爆仓
最近在项目里重度使用 Coding Agent 做日常开发我最大的感受是这玩意儿确实是干活利器但论吃 Token 的速度也确实是刺客级别的。尤其是当你让它自己跑一遍构建、执行一轮测试终端里哗啦啦滚出上千行日志如果 Agent 把这些文本一股脑全读进上下文那后面基本就不用干了——上下文被日志填满模型开始“失忆”刚才还在处理的需求转头就忘更别提那肉眼可见飞涨的账单。这个场景我用一句话总结Token 刺客 上下文爆仓一个治钱一个治命。这篇文章不打算聊选模型也不聊怎么写提示词而是聚焦一个被很多人忽略、但几乎所有重度用户都会撞上的环节终端输出处理。核心思路是给 Coding Agent 的输出通道加一层“剪枝逻辑”把终端输出里的无效信息压掉 98% 左右只把错误、警告和关键摘要放进上下文。原理不复杂实现也谈不上难但做完之后Token 消耗下降非常明显上下文能被用在真正该用的地方Agent 干活时的连贯性和准确率都会有肉眼可见的提升。不管你是用 Claude Code、Codex CLI还是自己在写 multi-agent 框架这套思路都能直接套。1. 痛点的本质终端输出不是“信息”而是“噪音”1.1 一次构建测试到底烧掉了多少 Token先算一笔账。很多 Agent 工具会把终端输出以对话消息的形式注入上下文你看着是几千行日志实际上每一行都在“真金白银”地消耗 Token。假设一次 Java 构建输出 2000 行日志平均每行 60 个字符——这在 Maven/Gradle 输出里已经算很收敛了毕竟很多时候光依赖下载进度和任务列表就远不止这个量。那么总字符数约 12 万。按照英文为主的日志粗略换算4 个字符约等于 1 个 Token这就是 3 万 Token如果是中文日志或者带上了堆栈信息Token 数还会更高。3 万 Token 是什么概念它相当于一篇中等长度的技术文档全文。换句话说你让 Agent 跑一次构建还没开始分析问题就已经把三篇技术文档的“阅读量”喂给它了。跑两三次构建、执行几轮测试上下文窗口就已经被这些日志塞得差不多了。而且这还只是构建场景。真正的重灾区是测试场景一次全量跑出几百上千条测试结果每条结果包含测试名、耗时、通过/失败状态有的还会带断言差异和堆栈。如果完整发给 Agent动辄就是几十万字符换算下来接近十万级 Token。我见过最夸张的一次是某个同事在 Agent 会话里连续跑了三轮测试每次终端输出都有四五千行。三轮下来光测试日志就占了 30 多万 Token 的上下文整个会话直接废掉——模型开始反复重复自己说过的话连用户指定的目录路径都会记错。所以问题的核心不是“终端输出了多少行”而是“Agent 的输入通道把多少噪音当成信号读了进去”。要想让 Coding Agent 高效工作第一步就是把终端输出当作一道数据管道来处理而不是当作对话消息直接灌给模型。1.2 上下文爆仓不是“提示词工程”能解决的很多朋友遇到上下文效果变差第一反应是修改提示词或者换更大的上下文窗口。这两个方向都治标不治本。先说提示词。提示词能约束模型的行为偏好但没法改变模型接收到的输入质量。终端日志里有大量重复性内容比如 Maven 下载依赖的进度条、Webpack 的编译模块列表、Docker 构建过程中的中间层提示——这些内容无论提示词写得多么精妙模型读进去之后照样会占据注意力资源和上下文空间。有个生活化的类比你让一个助理帮你分析仓库的问题结果你把整个仓库的杂物清单都丢给他让他自己筛。他确实能筛但费时费力而且容易漏掉真正重要的东西。提示词就是告诉他“仔细一点”但杂物清单本身仍然在消耗他的精力。再说扩大上下文窗口。现在 Claude Code 这类工具已经有 1M 上下文的选项听起来很大但别忘了上下文窗口变大模型要处理的输入规模也变大单次请求延迟和开销都会上升而且当窗口被无效内容占满时和 100K 窗口被占满的效果是一样的——模型一样会失忆、一样会跑偏只是“爆仓”的时间点延后了。更关键的是大上下文窗口本身就意味着更高昂的成本日志这种低密度信息根本不配占用这么贵的资源。这里我想重点说一下实践中的体会上下文工程和提示词工程一样重要但前者常常被忽略。上下文工程的核心不是“把窗口撑大”而是“让进入窗口的每一段文字都有明确用处”。终端输出剪枝就是上下文工程里最基础、也最容易出效果的一环。它不是让你牺牲信息量而是帮模型过滤掉 98% 的垃圾把精力集中在真正解决问题的那 2% 上。1.3 “98% 剪枝”不是拍脑袋是统计出来的很多人看到“98% 输出剪枝”这种说法第一反应可能是夸张。我当时也怀疑过但做过一次统计之后就信了。挑一个典型的构建失败场景来做样本原始终端输出大概有 2600 行。我人工标注了一番真正需要模型看的内容包括编译错误的位置和原因描述、失败任务的名称、几个相关的警告、最后的状态码加上出错前后的少量上下文行。我数了一下这些关键内容加起来大概 40 行出头。从 2600 行到 40 行压缩率是 98.5%。再举一个测试场景的例子一次测试跑了 4800 条用例终端输出大约 8000 行其中绝大部分是进度和通过状态。失败用例只有 13 条每条的关键信息用例名、断言差异、堆栈首行加起来不到 60 行。压缩率也在 98% 以上。你会发现一个规律终端输出绝大多数是“状态类信息”而不是“问题类信息”。状态类信息的特点是数量巨大、内容重复、对模型决策帮助有限问题类信息的特点是数量稀少、上下文敏感、恰恰是模型真正需要的东西。所谓剪枝就是在管道层把这两类信息拆开优先保证问题类信息无损进入上下文再对状态类信息做少量保留用于给模型提供整体判断的依据。这个思路和剪枝算法在传统机器学习里的用法是相通的。决策树后剪枝里我们砍掉那些对分类贡献小的分支保留决策能力最强的路径这里的“终端输出剪枝”砍掉的是对决策贡献最小的日志行保留能够帮助模型定位问题的关键路径。本质都是“去除冗余、保留信息密度”。明确了这一点之后剩下的问题就是怎么设计了。2. 方案选型四种终端输出策略我为什么选了分级剪枝2.1 硬截断把尾巴留下但经常把错误也剪掉最早我采用的是最简单的办法让 Agent 执行命令后只把终端输出的最后 N 行发给它比如 tail -n 100。这个方案实现成本极低也确实能大幅减少 Token 消耗但用了几天就发现一个严重问题很多错误信息并不在尾部。编译错误出现在日志中间测试失败散落在各个阶段异常堆栈印在报错的瞬间——这些关键信息根本不在文件的最后 100 行里。tail 截断等于把最重要的信息随随便便丢掉了。最典型的场景是构建到一半失败错误出现在第 500 行到第 800 行之间尾部只有一堆任务取消和状态清理的日志。你只给 Agent 看最后 100 行它看到一个“失败”的结果但完全看不到失败的原因只能瞎猜。硬截断适合的场景是你明确知道这个命令的输出结构比如 git status 的输出本来就几十行tail -n 20 完全够用。但在构建、测试、部署这类输出结构不可预测的命令上硬截断就是在玩火。2.2 关键词过滤精准但容易漏上下文第二个想法是关键词过滤核心是用 grep 提取包含 ERROR、FAILED、Exception 等关键词的行把这些行发给 Agent。这个方案比 tail 靠谱得多因为它是“按内容保序”而不是“按位置截断”。实际用下来关键词过滤有两个痛处。一是过度依赖关键词的完备性。我踩过最典型的坑某次前端构建报错的关键词是 “[!]” 和 “Build failed”我的过滤规则里只写了 ERROR 和 error结果所有有效信息全被 filter 掉了Agent 看到的是一段完全正常的输出——它还真以为构建成功了开始兴致勃勃地分析别的。二是过滤出来的行“太干”。错误行往往需要结合前后几行才能看懂比如 “Module not found: Cant resolve xxx” 只给这一行不给 import 语句的上下文Agent 并不知道是哪个文件里的哪个导入出了问题。关键词过滤适合用来做“预筛”但不适合作为最终交付。它更大的价值是作为一个模块放在剪枝管道里承担第一道粗筛的工作。2.3 LLM 压缩摘要看着高级成本反而更高第三种方案是让大模型自己来压缩。理论上很优雅执行完命令后先让一个轻量模型读完整份日志输出摘要再把这个摘要交给主 Agent。这样信息密度高而且摘要可以用很自然的方式保留逻辑重点。但算一笔账就发现不对劲。如果原始终端输出是 10 万字符折合约 2.5 万 Token让轻量模型读 2.5 万 Token、输出 2000 Token 的摘要成本大约是多一次模型调用的费用。一次两次还能接受问题是每次运行构建都要走这个流程累积下来比直接给主 Agent 读完整日志更贵。要是团队里几十个人都在用这笔费用会非常可观。更隐蔽的问题是摘要模型本身也有可能漏信息。日志里的错误很可能是“意外模式”不符合摘要模型“把重点归纳出来”的倾向它在压缩时可能把某个隐藏很深的异常丢掉了而下游主 Agent 根本无从知晓这个缺失。这一点是最致命的——我们做剪枝的目的就是提高信息确定性结果摘要环节反而引入了一层新的不确定性。LLM 压缩不是不能用但它更适合用在那些“内容本身很短、但需要跨大段信息归纳”的场景比如让 Agent 总结一天的会话记录。对于终端输出这种高噪声、低密度的数据流让 LLM 当中间商性价比很低。2.4 分级剪枝把“信息”和“噪音”分开处理综合前面几次踩坑最终确定的设计是分级剪枝管道。核心思路就一句话不统一规则而是按信息优先级分层处理。第一层是预过滤。把不需要逐行分析的内容直接丢掉比如依赖下载进度、构建任务列表、测试通过的逐条结果。这些内容出现频率高、信息量低即使偶尔对整体判断有点用也可以被后续的关键摘要替代。预过滤最粗暴的实现就是关键词过滤加上行模式匹配比如匹配到成功的状态标记就跳过。第二层是核心抽取。针对错误、警告、失败等关键信号连同它们前后若干行一起提取。这里有一个关键点不单独提取出错的这一行而是保留“信号行 上下文行”这样模型可以看到错误是在什么环境下发生的而不是面对一句孤立的话凭空猜测。第三层是尾部摘要。保留终端输出的最后若干行让模型感知到命令整体的收尾状态尤其是退出码、失败汇总、总体统计等信息。之所以保留尾部是因为很多命令行工具包括 JUnit、pytest、Gradle都会在输出末尾做一次总结。第四层是行数预算控制。给每一层设定 Token 配额一旦超出就按优先级截断。总预算通常设置在 1500 到 3000 Token 之间足够覆盖绝大多数日志场景。这套方案的好处是它不是“选一种方式处理所有输出”而是对不同类型的行采取不同的处理方式。它既保留了硬截断的成本控制力又兼顾了关键词过滤的信息提取精度还避免了 LLM 压缩的额外开销。我实际用了一个多月体感非常稳下面的篇幅我会把具体实现和跑出来的效果数据写出来。3. 实操给 Coding Agent 装一条剪枝管道3.1 设计原则在 Agent 的“手”前面加一道闸先说清楚一个关键点Coding Agent 执行终端命令的方式本质上是把命令交到系统的子进程里跑然后把子进程的输出捕获回来作为模型的输入。所以我们要做的就是在“子进程输出”和“模型输入”之间加一道闸。这道闸的实现方式取决于你用的是哪种工具。用 Claude Code、Codex CLI 这类现成产品时一般没法直接改它的内部数据流但有两条可行的路径一是修改工具配置里的命令执行前端。比如在 Claude Code 里通过钩子函数hook在工具调用后对输出做一步后处理在 Codex CLI 里某些版本也支持通过自定义工具或插件方式接管输出。二是更通用的做法不让 Agent 直接执行重命令而是让它执行一个包装脚本脚本负责跑原始命令、把完整输出落盘到临时文件、执行剪枝逻辑、再把剪枝后的结果返回。这样无论底层工具是什么都能在不改工具内部的前提下完成剪枝。我自己用的是第二种方式因为它在不同工具之间可迁移性最强而且出了问题可以直接对着脚本排查不用翻工具的源码。下面给出一套可以照搬的简化实现。3.2 核心实现一套可复制的剪枝脚本我用 Node.js 实现了一套剪枝脚本直接用 Python、Shell 重写也没问题核心逻辑是一致的。// prune-output.js // 用法: node prune-output.js log-file [max-tokens] const fs require(fs); // 信号正则按优先级排序 const SIGNAL_PATTERNS [ { type: error, regex: /\b(error|exception|failed|failure|fatal|error:)\b/i }, { type: warning, regex: /\b(warn|warning|cannot|unable|no such)\b/i }, { type: summary, regex: /\b(tests?\s*(run|passed|failed)|build\s*(success|failed)|exit\s*code|total)\b/i }, ]; const CONTEXT_BEFORE 2; // 信号行前保留行数 const CONTEXT_AFTER 3; // 信号行后保留行数 const OUTPUT_LIMIT 2500; // 剪枝后输出 Token 上限估算 function estimateTokens(text) { // 粗略估算英文约 4 字符/Token中文约 0.6 字/Token // 这里统一用字符数除以 3 近似 return Math.ceil(text.length / 3); } function prune(logPath) { const raw fs.readFileSync(logPath, utf8); const lines raw.split(/\r?\n/); const selected new Set(); const signals []; for (let i 0; i lines.length; i) { const line lines[i]; for (const p of SIGNAL_PATTERNS) { if (p.regex.test(line)) { signals.push({ index: i, type: p.type, line }); // 保留信号行及上下文行 for (let j Math.max(0, i - CONTEXT_BEFORE); j Math.min(lines.length - 1, i CONTEXT_AFTER); j) { selected.add(j); } break; } } } // 尾部摘要保留最后 30 行 const tailStart Math.max(0, lines.length - 30); for (let i tailStart; i lines.length; i) selected.add(i); // 按行号排序输出 const cleaned [...selected].sort((a, b) a - b).map(i lines[i]); // 如果超出预算优先截断尾部摘要 let result cleaned.join(\n); while (estimateTokens(result) OUTPUT_LIMIT cleaned.length 10) { cleaned.splice(cleaned.length - 1); result cleaned.join(\n); } return { originalLines: lines.length, outputLines: cleaned.length, signals, pruned: result, }; } const logPath process.argv[2]; if (!logPath) { console.error(请指定日志文件路径); process.exit(1); } const result prune(logPath); console.log( 剪枝统计 ); console.log(原始行数: ${result.originalLines}); console.log(剪枝后行数: ${result.outputLines}); console.log(压缩率: ${((1 - result.outputLines / result.originalLines) * 100).toFixed(1)}%); console.log(捕获信号数: ${result.signals.length}${result.signals.map(s s.type).join(, )}); console.log( 剪枝后内容 ); console.log(result.pruned);这套脚本的逻辑分成四块第一块是信号匹配预定义了三类信号错误、警告、总结。匹配顺序很关键错误优先级最高、警告次之、总结最低。这样同一行命中多个模式时不会重复标记。针对实际项目可以把 ERROR、FAILED 之外的自定义关键词加进去比如团队内部约定好的错误前缀。第二块是上下文行的保留。这是 2.2 节讲过的坑的解决方案信号行前后各保留几行让模型能理解错误发生的环境。默认是前 2 后 3针对堆栈信息比较密集的场景可以把前 5 后 8 调大。第三块是尾部摘要。保留最后 30 行让模型知道命令的最终状态。注意尾部摘要和信号行要按原始顺序合并输出不要去重保持时间顺序很重要。第四块是 Token 预算控制。用字符数除以 3 来估算 Token 数虽然不够严谨但作为工程上的近似够用了。一旦剪枝结果超出预算就从行尾部开始截——因为尾部摘要的优先级低于信号内容但高于普通噪音。脚本本身不直接与 Agent 交互它只负责“处理日志文件”。配合上一层封装就能接入到 Agent 流程里了。3.3 与 Agent 提示词配合让模型知道“你看到的是剪过的内容”剪枝脚本给 Agent 的内容越干净模型就越依赖你说清楚“什么被剪掉了”。这是很多人会忽略的一步。我的通用做法是在 Agent 的系统提示词里加这样一段终端输出说明 - 命令执行过程中终端输出已经过剪枝处理原始完整日志保存在 /tmp/agent-logs/{command-id}.log。 - 当前提供给模型的是剪枝后的内容仅包含错误信号、警告信号、关键上下文和尾部摘要。 - 如果剪枝后的内容不足以定位问题优先读取原始日志文件中的对应区域而不是猜测错误原因。 - 剪枝统计会在内容开头提供原始行数、剪枝后行数和压缩率可以参考压缩率判断信息的完整度。这段提示词并非可有可无。它实际上承担了三个职责一是防止模型在信息不足时强行推理二是告诉模型“原始日志在哪里”给了它一个主动回溯的入口三是让模型理解剪枝统计的含义比如压缩率高达 99% 时说明原始输出里绝大多数都是噪音模型应该相信剩下的内容是重点。在遇到剪枝后仍然无法定位问题的场景时我会让 Agent 主动去读原始日志文件里对应行号附近的内容。因为剪枝脚本支持输出保留行的原始行号我在生产环境里的版本会把行号信息也带上比如[L123] [error] com.example.api.AuthService: token validation failed [L122] at com.example.api.AuthController.checkAuth(AuthController.java:45)这样模型拿到剪枝内容后如果觉得信息不够可以直接定位到原始日志的第 122 到 123 行附近做二次阅读。这个设计相当于给剪枝装了一个“可追溯性”的保险既默认提供高密度信息又保留了按需回溯原始上下文的能力。3.4 效果验证数据说话脚本落到生产环境之后我在真实项目里跑了三周挑了三种典型命令做对比Maven 构建、pytest 全量测试、npm 构建。记录剪枝前后 Token 预估用量和模型任务完成情况。场景原始行数原始 Token 估算剪枝后行数剪枝后 Token 估算压缩率Maven 构建失败2630约 3200046约 110096.6%pytest 全量测试4800 条用例8200约 4900058约 140097.2%npm 构建 部署3700约 2300035约 90098.4%实际跑下来压缩率稳定在 96% 到 98.5% 之间和文章标题里说的 98% 基本吻合。更重要的是任务完成质量同样一个构建失败剪枝前 Agent 要花三四轮去翻日志找原因剪枝后通常一两轮就能定位到根因因为它一上来就看到了错误行本身而不是被埋在几千行日志里。这里要特别提醒一点压缩率只是一个参考指标不要为了追求数据好看而疯狂压缩。核心指标应该是“模型解决任务的成功率”。我见过有人把输出预算压到 500 Token 以内结果错误信息本身就被截掉了Agent 开始输出一堆猜测反倒多花了好几轮对话。剪枝的目标是让信息密度足够高而不是削到只剩骨头。还有一个容易被忽略的收益剪枝之后单轮对话的响应时延会明显下降。因为模型输入变短了prefill 阶段的计算量大幅减少整个请求的处理速度都会更快。终端输出动辄几万 Token 的场景里剪枝后的单轮时延从十几秒降到了五六秒这个体感提升非常明显。4. 上下文治理与 Token 预算的立体打法4.1 剪枝只是治标治本要靠会话结构管理剪枝解决了“终端输出塞爆上下文”的急性问题但如果一个 Coding Agent 会话里做了很多件不同的事、讨论了很多个文件上下文仍然会被正常的业务内容填满。所以我说剪枝是治标真正要把上下文管好还要配合会话结构管理。我的习惯是“一个会话只干一件事”。比如这次会话就修这个 bug或者就做这个功能模块。如果中间要穿插别的任务我会先让 Agent 把当前任务的结论、下一步计划和关键文件路径整理成摘要然后新开会话把摘要和原任务的关键信息带过去。这个动作只花几分钟但能保证每个会话的上下文都保持在一个可控的密度上。这背后其实是一个工程取舍长会话的优势是“记忆连续性”但代价是上下文里累积了大量中间过程包括各种试错、中间版本、被推翻的方案。这些中间过程有信息价值但对最终决策来说是冗余的。和代码版本管理一样上下文也可以做 commit——定期总结、压缩、把最新的状态固化下来而不是把所有的 diff 都堆在一个超长会话里。4.2 Token 生命周期管理与“续签”机制接下来聊点偏工程的话题Token 的生命周期。这里说的 Token 有两种一个是我们一直在讨论的模型 Token另一个是登录认证用的 Token。模型 Token 的预算管理本质上就是“会话的钱包管理”。我在实践中给每个会话设定一个预算上限比如 5 万 Token。当用量接近上限时主动让 Agent 做一次中期总结把中间过程沉淀成结论然后决定是继续如果任务即将完成还是新开会话如果任务还很长。这个策略有点像 JWT 的 access token 和 refresh token 的关系access token 有效期短保证单次会话的安全和控制refresh token 有效期长负责在需要时延续会话。我们的“会话摘要”就是那个 refresh token新会话通过读取摘要来延续上下文而不是带着全部历史数据重新开始。再说登录认证 Token。这段时间“token exchange failed”在开发者社区里的求助非常多我自己也踩过。常见的报错包括 sign-in could not be completed、token endpoint returned 403、token exchange failed: error sending request 等。这类问题大多数是环境层面的和 Agent 本身的代码逻辑无关。我总结出一套三层排查法第一层检查本地配置。很多 CLI 工具把认证信息存在用户目录下的配置文件里比如 ~/.codex/config.toml 或类似路径。这些文件经常在升级后被重置或者被其他的工具覆盖写入导致 Token 丢失或过期。处理方法通常是重新执行登录流程让工具重新生成认证信息。第二层检查环境变量和系统时间。工具通过环境变量读取 token如果换了个终端、加载过不同的 shell 配置环境变量没带上就会出问题。系统时间偏差也会导致 JWT 的过期校验失败这是个特别隐蔽的原因——时间快慢了十几分钟token 要么提前过期要么被当成“未来签发”的无效凭证。第三层检查工具版本。CLI 工具的认证逻辑会随版本迭代变化如果还停在旧版本而后端已经升级了认证接口就会出现 token exchange 失败。这种情况升级到最新版本基本能解决。处理这些报错时的一个体感是不要一上来就怀疑工具坏了。绝大多数 token 类报错都出在配置、环境、版本三件事上按这个顺序排查效率最高。4.3 压缩、检索、剪枝的组合拳最后说说剪枝和其他上下文管理手段怎么配合。剪枝负责“入口控制”保证进入上下文的内容信息密度高会话摘要负责“出口沉淀”把中间过程压缩成可复用的结论RAG 式检索负责“按需读取”在需要时去原始日志或代码库里找细节。三层各管一段组合起来才是完整的上下文工程。拿一个具体场景举例Agent 在分析一次线上问题它拿到了经过剪枝的报错信息、看到了异常栈的首行但需要更完整的堆栈才能定位问题。这时候它可以按行号去原始日志文件里查询对应区域。这个查询本身产生的 Token 是定向的只读需要的几十行而不是把整份日志重新灌进来。这其实就是 RAG 的思路不要一次性把所有信息塞进上下文而是提供“查询接口”让模型按需获取。压缩策略触发时机也很关键。我一般设定上下文占用 70% 作为警戒线超过之后主动触发一次会话压缩把已有的讨论和结论提炼成摘要如果压缩后仍然接近上限就完整地做一次交接开一个新会话继续。这个 70% 是经验值不是算法算出来的但实测下来比等到“爆仓”再处理舒服得多。5. 踩坑实录与排查速查表5.1 登录态失效与 Token 刷新失败怎么排查这部分在 4.2 节已经讲了核心思路这里把可能会碰到的具体情况列出来。第一类sign-in could not be completed, token exchange failed。这类报错最常见的触发场景是换了网络环境后重新登录或者多个工具共用一套认证凭据导致冲突。排查顺序先重新执行官方登录流程看能不能恢复不行就检查配置文件里是否有多余的旧 token 残留再检查环境变量有没有把 token 传给当前进程。第二类token endpoint returned 403。这个报错往往意味着认证服务器拒绝了你当前的凭据。重点检查权限范围是否被收窄以及凭据是否在团队内被共享/轮换。如果有管理员后台看下操作日志里最近有没有异常的失败记录。第三类login server error: error sending request。这类报错偏网络层面但大多数根因还是承载认证请求的客户端配置出了问题比如本地网络环境中的转发配置、证书链异常等。建议按“配置文件 → 环境变量 → 工具升级”的顺序逐步排查。排查几轮还不行最稳妥的做法是把配置目录移走比如改名备份强制工具重新走一遍初始化流程这样至少能排除“配置损坏”这个最常见的坑。我遇到过一个很刁钻的情况某个工具在旧版本里写入的配置格式和新版本不兼容导致新版本起来后一直拿不到 token最终是靠重置配置目录解决的。5.2 “上下文已使用满”时先做这四件事上下文爆仓是每个重度使用者都绕不开的坎。不同工具报错文案不同有的显示“上下文已使用满”有的告诉你“请启用更大上下文后重试”但处理思路是一致的。第一件事确认占用来源。用工具自带的上下文统计功能看看哪些内容占了大头。如果发现大量对话轮次都是终端输出说明剪枝没生效回上一节看看配置。第二件事给 Agent 下达“总结并交接”指令。让它把当前对话里已经确定的事实、结论、未完成事项、关键文件路径整理成一页纸的摘要然后把摘要复制出来。第三件事保存现场并新开会话。新会话里先把摘要粘贴进去再用一句话描述接下来的任务目标。这个过程的本质是“换一种更高效的方式延续上下文”而不是真的从头再来。第四件事去复盘为什么会爆。是单轮终端输出太大是会话拖太长还是中间过程太多针对原因做定向调整而不是每次都靠开新会话续命。我用一个数据来体现这个流程的重要性有一次排查一个并行测试框架的偶发死锁旧会话从早上挂到下午上下文早已爆满Agent 开始反复推荐一些明显不相关的方案。我把当天讨论的结论做成摘要、开新会话十分钟内就定位到了问题所在——并不是模型变聪明了而是它的上下文里终于没有了那些已经过时的中间猜测。5.3 剪枝过度导致“信息失踪”的对策剪枝系统做得越激进遇到“关键信息被剪掉”的概率就越大。我自己至少撞过三次每次都很典型。第一次错误关键词没覆盖住。某个测试框架输出的是 “Process crashed with exit code 2”既不包含 error 也不包含 failed我的正则没匹配到。结果是 Agent 看到一段没有异常标记的日志认为测试通过了继续做后面的任务直到我人工发现不对劲。解决办法是把 “crashed”“exit code” 这类表达也加进信号正则。第二次上下文行太少。有一个运行时异常真正的原因写在错误发生前 20 行的一处资源释放逻辑里我默认只保留前 2 行模型看到的是一个孤立异常完全不知道前置逻辑。后来把构建场景的信号上下文行数调到前 5 后 8情况好很多。第三次尾部摘要被截断。测试失败汇总打印在输出的倒数第 40 行而我的尾部摘要只保留最后 30 行结果失败汇总被裁掉了。这个问题也简单把尾部保留行数从 30 调到 60或者干脆在日志落盘时把最终的 summary 单独记录到另一个文件。这些坑说明一个问题剪枝规则是有“盲区意识”的。你永远不可能用几条正则覆盖所有日志形状所以要设计一个兜底机制当剪枝结果里没有匹配到任何 signal 时不要直接返回“空内容”给模型而是把尾部摘要扩展到更多行并声明“本条命令没有检测到已知信号请人工确认”。这个兜底机制在我后来又遇到几类不常见日志格式时帮我避免了很多次误判。提示剪枝回归到本质其实是“知道什么该留”比“知道什么该丢”更重要。宁可让 Agent 偶尔多读几行冗余信息也不要让它因为信息缺失而产生错误判断。5.4 排查速查表最后整理一张速查表方便你实际开发时对照使用。这张表里收集的是我这段时间在实际项目中遇到的最常见问题每一行都是一个真实的排障过程。你不需要背下来只要遇到问题时回来翻一眼通常能省下不少冤枉时间。症状可能原因处理建议Token 消耗暴涨完整终端输出灌入上下文启动剪枝限制单条命令输出 Token 上限上下文快速爆仓日志/中间过程占比过高定期做会话摘要分段任务Agent 反复猜测但找不对原因关键错误被剪掉检查信号正则覆盖度增大上下文行数模型认为命令执行成功实则失败失败信号未被捕获增加 crash、exit code 等信号词启用兜底机制sign-in could not be completed配置损坏或凭据过期备份并重置配置目录重新走登录流程token endpoint returned 403权限范围或凭据问题检查权限配置确认 token 未被轮换或共享login server error客户端配置异常按配置文件、环境变量、工具版本顺序排查这张表我贴在工位旁边已经好几个月了每次新问题出现都会往上加一行现在它几乎成了团队里 Coding Agent 问题的第一处排查入口。你也可以建立一份自己的速查表因为每个项目的日志格式和易错点都不一样长期积累的价值会越来越大。坦白说这套剪枝方案并不是什么高深的技术它本质上就是一个“信息过滤器”。但它带来的收益远超我的预期——不只是省了 Token更重要的是让 Coding Agent 把注意力放到了它真正该处理的问题上。我在实际使用中最深的体会是工具的能力上限往往不是由模型决定的而是由你喂给它的信息质量决定的。输出剪枝只是上下文工程里的第一步顺着“让每一段输入都有价值”这个思路往下走你可以做会话压缩、自动摘要、按需检索甚至可以针对自己团队的代码库定制一套完全个性化的工作流。最后再分享一个小建议不要只盯着压缩率数字多观察模型在剪枝后能不能更快地定位到根因那才是这套方案真正的价值所在。