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: Can't 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 预估用量和模型任务完成情况。

实际跑下来，压缩率稳定在 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 排查速查表

最后整理一张速查表，方便你实际开发时对照使用。这张表里收集的是我这段时间在实际项目中遇到的最常见问题，每一行都是一个真实的排障过程。你不需要背下来，只要遇到问题时回来翻一眼，通常能省下不少冤枉时间。

这张表我贴在工位旁边已经好几个月了，每次新问题出现都会往上加一行，现在它几乎成了团队里 Coding Agent 问题的第一处排查入口。你也可以建立一份自己的速查表，因为每个项目的日志格式和易错点都不一样，长期积累的价值会越来越大。

坦白说，这套剪枝方案并不是什么高深的技术，它本质上就是一个“信息过滤器”。但它带来的收益远超我的预期——不只是省了 Token，更重要的是让 Coding Agent 把注意力放到了它真正该处理的问题上。我在实际使用中最深的体会是：工具的能力上限，往往不是由模型决定的，而是由你喂给它的信息质量决定的。输出剪枝只是上下文工程里的第一步，顺着“让每一段输入都有价值”这个思路往下走，你可以做会话压缩、自动摘要、按需检索，甚至可以针对自己团队的代码库定制一套完全个性化的工作流。最后再分享一个小建议：不要只盯着压缩率数字，多观察模型在剪枝后能不能更快地定位到根因，那才是这套方案真正的价值所在。