1. 为什么要在编辑器里盯住 Token 速度和命中率用 OpenCode 这类 AI 编程助手写代码最让人心里没底的不是模型答得好不好而是你根本不知道它这一下花了多少、省了多少。我刚开始用的时候经常出现一种情况同一个问题问两遍第一遍秒回第二遍卡了七八秒才吐字但我完全不知道是网络抖动、模型排队还是上下文太长导致推理变慢。更麻烦的是缓存命中这件事——如果命中率高同样的上下文重复请求会便宜很多、快很多命中率低那你的额度就像漏水一样哗哗往下掉。这就是我动手做这个 OpenCode 插件的出发点把Token 速度每秒输出多少 token和缓存命中率命中缓存的 token 占比实时显示在编辑器状态栏里。它解决的核心问题是可观测性——让你在写代码的过程中随时能看到当前这次请求的性能和成本表现而不是等到月底看账单才后知后觉。这个插件适合几类人一是天天泡在 OpenCode 里写业务代码、对响应速度敏感的开发者二是需要控制 AI 调用成本、想搞清楚钱花在哪的团队三是喜欢折腾插件、想了解 OpenCode 扩展机制的技术爱好者。哪怕你只是刚装上 OpenCode 的新手装上它也能立刻对AI 到底快不快、省不省有个直观感受。需要先说明一点OpenCode 的插件生态和具体 API 在不同版本间有差异下面讲到的实现思路、字段名和事件钩子是基于我实际调试 V2 版本时总结的常见做法。如果你的版本对不上思路是通用的具体字段名以你本地 SDK 为准。2. 拆解 OpenCode 插件的事件流与数据来源2.1 插件到底挂在哪几个钩子上OpenCode 的插件本质上是一段在宿主进程里运行的扩展代码它通过订阅宿主抛出的事件来介入整个请求生命周期。要拿到 Token 速度和命中率你得先搞清楚一次完整的对话请求会经过哪些阶段。我实测下来关键节点大致有这么几个请求发起前宿主准备消息体、拼上下文这时候你能拿到本次请求的模型、消息条数、预估输入长度。流式响应中模型开始吐 token宿主会持续抛出增量事件每个事件带一小段文本或一个 token。响应结束宿主收到结束标记同时附带本次请求的用量统计usage这里面就藏着命中率的关键数据。错误与中断请求失败或被取消时也会抛事件这时候速度统计要做兜底处理否则状态栏会卡在一个错误值上。我一开始图省事只在响应结束这一个钩子上做统计结果发现速度根本算不准——因为结束事件只告诉你总耗时和总 token 数但流式输出中间可能有停顿平均速度会掩盖掉前快后慢这种真实体验。后来改成在流式事件里累计 token 数、记录首 token 时间才算把速度算明白。2.2 速度指标怎么定义才不误导人Token 速度这个词其实很含糊业内至少有三种算法含义完全不同指标名称计算方式反映的问题首 Token 延迟TTFT从发请求到收到第一个 token 的时间模型排队、网络往返、上下文预处理开销生成速度TPS输出 token 数 / 纯生成耗时模型推理吞吐能力端到端速度输出 token 数 / 总耗时用户实际感受到的整体快慢我最后在状态栏里同时显示了 TTFT 和 TPS 两个值因为单看任何一个都会误判。举个例子某次请求 TTFT 高达 3 秒但 TPS 有 60说明是排队慢、生成快另一次 TTFT 只有 200 毫秒TPS 却只有 8那就是模型本身在慢慢磨。这两种情况对应的优化手段完全不一样前者你可能要换时段或换模型后者可能要考虑精简上下文。提示TTFT 的计时起点一定要放在请求真正发出的那一刻而不是用户按下回车的瞬间。中间还有本地拼上下文、序列化的耗时如果算进去TTFT 会被虚高误导判断。2.3 命中率的数据藏在 usage 字段里命中率是成本控制的核心。OpenCode 对接的模型服务在返回用量时通常会区分几类 token输入 token、输出 token以及输入里命中缓存的部分。命中率就是命中缓存的输入 token 除以总输入 token。这里有个坑我踩过不同服务商对缓存字段的命名五花八门有的叫cached_tokens有的叫cache_read_input_tokens还有的把它塞在prompt_tokens_details这种嵌套结构里。如果你只按一种字段名去读换个模型就显示 0看起来像缓存完全没生效其实是没读到。我的做法是写一个兼容读取函数按优先级依次尝试几个常见字段路径读不到就显示—而不是显示 0避免误导。function extractCacheHit(usage) { if (!usage) return null; // 依次尝试常见的缓存命中字段路径 const candidates [ usage.cached_tokens, usage.cache_read_input_tokens, usage.prompt_tokens_details?.cached_tokens, usage.input_tokens_details?.cached_tokens, ]; for (const v of candidates) { if (typeof v number) return v; } return null; // 读不到就返回 nullUI 显示为未知 }命中率这个数字对写代码的人其实很有指导意义。比如你在一个长文件里反复让 AI 改同一个函数如果命中率高说明上下文被有效复用了成本可控如果命中率一直是 0那你要反思是不是每次都在改上下文前缀导致缓存全部失效。3. 从零把插件跑起来环境、骨架与状态栏接入3.1 环境准备里最容易忽略的两件事装插件之前先把基础环境理顺。我建议按这个顺序来确认 OpenCode 本体能正常跑通一次对话排除账号、额度、网络这些前置问题。确认你的 OpenCode 版本号V2 和更早版本的插件接口不兼容别拿旧教程硬套。准备一个独立的插件目录不要直接改宿主自带的插件方便回滚。最容易忽略的第一件事是版本匹配。我有一次照着网上教程写插件怎么都不生效折腾半天才发现教程是给旧版写的事件名对不上。第二件事是日志出口。插件跑在宿主进程里console.log不一定能看到你得先找到宿主的日志文件位置或者用宿主提供的调试通道否则出了问题两眼一抹黑。注意动手写逻辑之前先写一个最小可运行插件——只做一件事比如在加载时打印一行日志。确认这行日志能出现再往上加功能。这一步能帮你排除掉 90% 的环境问题。3.2 插件骨架注册、订阅、销毁一个结构清晰的插件应该包含三部分注册入口、事件订阅、资源清理。下面是我用的骨架去掉了业务细节保留结构export function activate(ctx) { // 1. 初始化状态 const state { firstTokenAt: null, outputTokens: 0, startAt: null, cacheHit: null, inputTokens: null, }; // 2. 订阅请求开始 const offStart ctx.events.on(request.start, (e) { state.startAt Date.now(); state.firstTokenAt null; state.outputTokens 0; state.cacheHit null; state.inputTokens null; ctx.statusBar.set(Token: 等待中…); }); // 3. 订阅流式增量 const offDelta ctx.events.on(response.delta, (e) { if (state.firstTokenAt null) { state.firstTokenAt Date.now(); } state.outputTokens e.tokenCount ?? 1; render(ctx, state); }); // 4. 订阅响应结束读取用量 const offEnd ctx.events.on(response.end, (e) { const usage e.usage; state.inputTokens usage?.input_tokens ?? null; state.cacheHit extractCacheHit(usage); render(ctx, state); }); // 5. 返回销毁函数插件卸载时调用 return () { offStart(); offDelta(); offEnd(); }; }这个骨架里activate返回的销毁函数特别重要。插件热重载或者被禁用时如果不取消订阅旧的事件回调会一直挂着导致状态栏数字乱跳、内存缓慢泄漏。我早期版本就漏了这一步用久了编辑器越来越卡排查了好久才定位到是订阅没清理。3.3 状态栏渲染别让刷新拖慢编辑器状态栏更新看着简单其实有个性能陷阱流式响应时增量事件可能每秒触发几十次如果你每次都去重建 DOM 或者触发一次完整的 UI 重排编辑器会明显发卡。我的处理办法是节流渲染——用一个定时器把渲染频率限制在每秒 4 到 5 次中间的状态变化只更新内存变量到点再统一刷一次。let renderTimer null; function render(ctx, state) { if (renderTimer) return; renderTimer setTimeout(() { renderTimer null; const text formatStatus(state); ctx.statusBar.set(text); }, 200); // 200ms 节流约每秒 5 次 }formatStatus负责把原始数字变成人看的字符串比如把 1234 个 token 显示成1.2k把速度显示成58 tok/s命中率显示成72%。格式化逻辑单独抽出来还有个好处方便写单元测试不用起整个编辑器就能验证边界情况。4. 速度与命中率的计算细节和边界处理4.1 首 Token 延迟和生成速度的精确算法把前面收集的时间戳和 token 数组合起来就能算出两个核心指标。逻辑不复杂但边界要处理干净function computeMetrics(state) { const result { ttft: null, tps: null, hitRate: null }; // 首 token 延迟 if (state.startAt state.firstTokenAt) { result.ttft state.firstTokenAt - state.startAt; } // 生成速度用首 token 之后的时间做分母排除排队时间 if (state.firstTokenAt state.outputTokens 0) { const genMs Date.now() - state.firstTokenAt; if (genMs 0) { result.tps (state.outputTokens / genMs) * 1000; } } // 命中率 if (state.inputTokens state.cacheHit ! null) { result.hitRate state.cacheHit / state.inputTokens; } return result; }这里有个细节值得说生成速度的分母我用的是首 token 之后的时间而不是总耗时。原因前面提过总耗时会混入排队时间把速度算低。但这样算也有个副作用——如果响应特别短比如只输出两三个 token分母很小算出来的 TPS 会虚高得离谱。所以我在展示时加了个保护输出 token 少于 5 个时速度显示为—因为样本太小没有参考价值。4.2 命中率读不到时该显示什么前面强调过命中率字段可能读不到。这时候 UI 上显示什么直接决定了这个插件是有用还是添乱。我的原则是宁可显示未知也不显示错误的 0。因为 0 会让人误以为缓存完全没生效从而去做无谓的优化而—明确告诉用户这个数据当前拿不到。另外还有一种情况某些请求压根不涉及缓存比如首次对话、上下文全变。这时候命中率天然就是 0和读不到是两码事。我在代码里用null表示读不到用0表示真实的零命中UI 上分别显示—和0%这样用户能区分开。情况内部值UI 显示含义字段缺失null—当前模型/版本不提供该数据真实零命中00%缓存未生效上下文全变正常命中0~1如 72%缓存有效复用4.3 请求失败和中断时的兜底流式请求最怕中途断掉。网络抖动、手动取消、服务端报错都会让响应结束事件永远不来。如果插件只依赖结束事件来收尾状态栏就会一直停在生成中…数字也不再更新看起来像卡死了。我的兜底方案是监听错误和取消事件一旦触发就立刻把状态标记为已中断并把已经统计到的部分数据展示出来同时停止计时。这样即使请求失败你也能看到这次跑到一半断了已经生成了 300 个 token对排查问题很有帮助。ctx.events.on(response.error, () finalize(ctx, state, error)); ctx.events.on(response.cancel, () finalize(ctx, state, cancel)); function finalize(ctx, state, reason) { state.finished true; const m computeMetrics(state); const suffix reason error ? [失败] : [已取消]; ctx.statusBar.set(formatStatus(state, m) suffix); }5. 适配 V2 时踩过的坑与排查链路5.1 事件名对不上从完全没反应到定位刚升级到 V2 的时候我的插件突然完全不工作了状态栏一直是空的。排查过程我完整记录一下因为这套思路对任何插件失效问题都通用。第一步确认插件有没有被加载。我在activate函数第一行加了日志结果日志根本没出现——说明插件压根没被宿主加载问题不在事件逻辑而在加载环节。第二步检查插件清单文件发现 V2 对清单里的字段做了调整我沿用了旧版的字段名宿主直接忽略了整个插件。第三步对照 V2 的清单规范改字段日志出现了插件被加载了。但加载之后状态栏还是不动。第四步我把所有订阅的事件名都打印出来发现 V2 把response.delta改名了。第五步改成新事件名终于跑通。整个过程最耗时的不是改代码而是确认问题出在哪一层——是没加载、加载了没订阅、订阅了没触发还是触发了逻辑错。分层排查能让你少走很多弯路。5.2 流式增量里 token 数不准的问题V2 的流式事件里增量数据不一定每次都带明确的 token 计数。有的版本给的是文本片段你得自己估算 token 数。我一开始简单粗暴地按一个字符一个 token算结果中文场景下严重高估——中文一个字往往对应一到两个 token但英文一个单词可能才一个多 token混在一起误差很大。后来我改成优先读事件里自带的计数读不到再用一个粗略的估算函数兜底并且明确标注这是估算值。估算函数对中英文分别处理中文按字符数乘一个系数英文按空格分词再乘另一个系数。虽然不精确但比字符数等于 token 数靠谱得多。提示如果你的场景对 token 计数精度要求高最好直接以服务端返回的 usage 为准流式过程中的数字只作为实时参考最终以结束事件的数据覆盖。5.3 状态栏闪烁和数字跳变跑通之后遇到一个体验问题状态栏数字跳得很厉害速度一会儿 80 一会儿 20看着心烦。原因是瞬时速度波动大尤其是流式输出有停顿的时候。解决办法是加一个滑动平均——保留最近几次的速度采样显示平均值而不是瞬时值。const speedWindow []; function pushSpeed(v) { speedWindow.push(v); if (speedWindow.length 5) speedWindow.shift(); return speedWindow.reduce((a, b) a b, 0) / speedWindow.length; }窗口大小我试过 3、5、10最后定在 5。太小了还是抖太大了反应迟钝5 次采样在平滑和灵敏之间比较平衡。这个值没有标准答案你可以根据自己的习惯调。6. 让插件真正好用的几个进阶思路6.1 把历史数据留下来做趋势观察只显示当前一次请求的数据价值有限。真正有用的是趋势——比如你发现最近命中率整体在下降那可能是你的使用习惯变了上下文前缀越来越不稳定。我在插件里加了一个轻量的历史记录把每次请求的 TTFT、TPS、命中率存到内存里可选持久化到本地文件然后在状态栏悬停时展示最近 20 次的平均值。这个功能帮我发现过一个真实问题我在某个项目里命中率长期只有 10% 左右排查后发现是我每次都在对话开头粘贴一大段会变动的日志导致缓存前缀每次都不同。把日志挪到对话末尾之后命中率直接上到 60% 以上响应也快了不少。6.2 按模型区分统计口径不同模型的正常速度区间差别很大拿同一个标准去衡量会误判。比如轻量模型 TPS 到 100 很正常而大模型 TPS 30 就算不错了。所以我在展示时会把模型名一起带上历史统计也按模型分组。这样你看到某模型 TPS 25时心里有个对应的基准而不是笼统地觉得慢。模型档位典型 TTFT典型 TPS命中率参考轻量快速型200~500ms80~150视上下文而定均衡型500ms~1.5s40~80视上下文而定高能力型1~3s15~40视上下文而定表里的数字是我个人使用中的经验区间不是官方指标仅供你建立直觉参考。真实值受网络、时段、上下文长度影响很大。6.3 阈值告警慢的时候主动提醒你盯着状态栏看毕竟费神。我后来加了个简单的阈值告警当 TTFT 超过某个值或者命中率低于某个值状态栏的颜色变一下提醒你注意。比如 TTFT 超过 3 秒标黄命中率低于 20% 标红。这样你不用一直盯着数字扫一眼颜色就知道这次请求正不正常。阈值不要设得太敏感否则天天报警就麻木了。我的建议是先跑一段时间收集数据看看你自己的正常区间在哪再把阈值设在正常区间的边缘而不是拍脑袋定一个数。6.4 几个实际使用中的小体会用下来这段时间有几个体会值得分享。第一别把速度当成唯一指标。有时候慢一点但答案质量高反而更省事追求极致速度可能得不偿失。第二命中率是可以主动优化的。保持对话前缀稳定、把变动内容往后放命中率会有明显提升。第三插件本身要轻。它跑在编辑器主进程里任何卡顿都会被放大所以计算要简单、渲染要节流、订阅要清理。如果你也想自己动手做一个类似的插件我的建议是从最小可运行开始先让一个数字显示出来再逐步加指标、加历史、加告警。每加一个功能都确认它没有拖慢编辑器这样最后得到的东西才是真正能长期用下去的而不是一个跑两天就被你关掉的玩具。