用OpenCode跑了快两个月Agent任务说实话最让我心里没底的从来不是“模型会不会写错代码”而是“我这会儿到底烧了多少Token”。OpenCode是一款跑在终端里的AI编程助手可以读仓库、改代码、执行命令相当于命令行里的结对编程搭档可它的默认状态行信息非常克制模型名、会话状态都有偏偏没有Token的消耗速度和缓存命中情况。项目跑到一半你只能盯着转圈猜这是模型想清楚了在输出还是卡在排队刚才那段超长上下文的请求缓存到底命中了没有费用是按全量算还是按折扣算全是未知数。所以我动手写了个OpenCode插件在状态行里实时刷新显示Token速度和命中率后来又补上了OpenCode V2的插件接口适配把统计口径理顺、加了一层字段兼容顺手把配置迁移也做了现在团队里几位同事也在用。这篇就把这套东西从设计思路到实现细节完整拆开讲一遍包含我踩过的坑和调试技巧。如果你也在用OpenCode写代码、跑长会话或者批量任务并且想对Token费用和生成速度心里有数应该能省不少事。下文代码和配置以我实际跑通的版本为例不同版本可能有细微差异但思路是通用的。1. 项目设计与核心思路1.1 做这个插件的起因看不见的Token才是最贵的先讲一个真实场景。上个月我让OpenCode跑一个“重构整个工具库”的长任务上下文里塞了十几个文件加起来几万行。任务本身跑了大概45分钟期间我切出去干别的回来一看模型已经把代码改完了但账单上那个数字让我愣了半天——光那一次会话就消耗了两百多万Token。问题不是OpenCode不能统计Token而是它默认不把“速率”和“命中率”这两个关键指标摆到你眼前。看累计值你只知道结果看不到过程看不到过程你就没法在任务中途做判断这个任务每小时大概烧多少Token按这个速度继续跑会不会超预算响应变慢了是因为模型输出速度本身慢还是因为每次都写入了大量缓存频繁切换上下文之后缓存命中率是不是已经跌到不能看的程度该不该换一个会话继续这些信息默认界面都不会告诉你。累计Token数当然也有但它是“事后账本”不是“实时仪表盘”。作为一个把AI编程工具当日常生产力的人我需要的是那种在开着任务的同时余光扫一眼就能得到的反馈。这就是插件最初的出发点做一个不打扰、实时刷新、一眼能看懂Token速度与命中率的仪表盘。1.2 指标选型速度不是越快越好命中率更要分清口径插件要做哪些指标这问题我想了很久。市面上的监控方案动不动就是一个大面板十几个图表实际用起来没人看。我的原则是宁缺毋滥最终只保留三组核心指标。第一组是Token消耗速度。这里要区分两条链路输入Token是一回事输出Token是另一回事。对于写代码的交互场景你真正关心的大多是输出速度也就是每秒生成多少个Token因为它决定了你等多久才能看到下一段代码而输入速度往往是一瞬间的事件塞上下文的那一下看累计值就够了。实际操作中我把两者分开展示显眼的位置放Output速率累计总量单独放在旁边。第二组是缓存命中率。这个指标的重要性很多人第一次接触会低估。拿Anthropic系的接口举例一次请求如果输入5万Token其中4.5万Token命中了之前的缓存那么计费只按剩余的5000 Token算价格差了接近一个数量级响应速度也会快很多。所以说命中率直接关系到两件事账单金额以及等待时间。我展示的是“会话累计命中率”累计缓存读取Token除以累计输入Token同时把“缓存写入占比”作为辅助信息因为首次写入缓存的那部分虽然暂时“贵”但它会让后续请求受益。第三组是累计消耗和会话时长。这一组是辅助值用来回答“这个会话到底烧了多少、跑了多久”。提示速度值并不是越高越好。这里说的“速度”指的是模型实际吐Token的瞬时速率受模型本身能力和服务端负载影响。如果你发现速度掉到平时的三分之一同时缓存写入值突然升高很可能是因为模型正在处理一段从未见过的新内容正在冷启动写缓存过一会儿会恢复。1.3 技术方案权衡三条路里为什么选了插件Hook确定指标之后接下来是“数据从哪来”的问题。我认真对比过三条路。第一条路解析OpenCode的日志文件。OpenCode运行时会打印结构化日志里面能看到完整的消息记录和Token统计。优点是实现简单不碰任何内部机制缺点也很明显——日志是周期性落盘的拿不到毫秒级实时而且一个任务并发多个请求时日志里的条目顺序和实际时间戳对不上统计容易错。第二条路在本地架一个转发层把所有发给模型提供商的请求和响应都过一遍自己统计。这条路最灵活想算什么都行但侵入性太强。你不仅要处理不同提供商的认证格式还得处理流式响应、工具调用、多会话混跑等于把OpenCode的通信层重写了一遍维护成本极高。第三条路利用OpenCode插件系统提供的事件Hook。OpenCode本身会在消息流转、会话更新的关键节点广播事件事件数据里就带着usage信息。插件只需要挂上监听拿到数据后自己做聚合计算再渲染到状态行或者自绘面板。这条路几乎不侵入工具本身数据也是程序内部直接推送的比日志解析更快更准。我选了第三条路原因很实际OpenCode插件机制本来就是官方支持的扩展点事件字段在V2里标准化得很不错插件的维护成本低用户安装也方便。后面所有实现都是围绕这条路展开的。2. 核心原理与实现细节2.1 数据怎么流到插件事件流里的usage字段要做一个能实时刷新的插件第一步就是搞明白数据在哪里。OpenCode的消息流是事件驱动模型一次完整的模型响应会经历多个阶段插件侧能拿到的关键事件分两类流式增量事件模型每吐出一批内容就触发一次携带本次新增的内容片段和对应的Token增量。这类事件是算实时速度的原料。消息完成事件整个响应结束时触发携带最终usage对象。这里能看到本次请求的累计输入、输出、缓存命中等完整数据是刷新面板总值的好时机。这里有个容易被新手忽略的点usage对象在不同版本里的字段名不一样。OpenAI兼容风格的接口用的是prompt_tokens / completion_tokens / total_tokens而Anthropic风格用的是input_tokens / output_tokens / cache_read_input_tokens / cache_creation_input_tokens。V2适配的工作很大一部分就是把这两套字段统一成插件内部的标准结构后面计算才不会被字段名绊住。我实际用的提取函数长这样function extractUsage(payload) { const u payload.usage || {}; const input u.input_tokens ?? u.prompt_tokens ?? 0; const output u.output_tokens ?? u.completion_tokens ?? 0; const cacheRead u.cache_read_input_tokens ?? u.prompt_tokens_details?.cached_tokens ?? 0; const cacheWrite u.cache_creation_input_tokens ?? 0; return { input, output, cacheRead, cacheWrite }; }这个函数兼容两种主流字段风格只要模型提供商按惯例填了usage插件就能拿到数字。后面所有统计都是从它输出的标准对象开始的。2.2 实时速度计算为什么瞬时值不能用滑动窗口和EMA怎么选拿到增量事件之后最简单的速度算法是用一次增量的Token数除以两次事件的时间间隔得到瞬时速度。但真这么干界面上出现的就是一条疯狂跳动的曲线——模型输出是突发式的有时一个chunk吐出几百Token有时一次只有几十Token瞬时速度能在几十和几千之间来回横跳根本没法看。我试过两种平滑方案效果差别很大。第一种是滑动窗口平均维护一个近60秒的样本队列每次新样本入队就把窗口内所有Token加起来除以窗口时间。它的优点是绝对平滑缺点是反应慢——速度突然掉了半分钟界面上的数字要等窗口滚完才体现出来。第二种是指数移动平均EMA给当前速度算一个权重新样本只占一小部分历史值占大部分数学形式是ema 0.8 * ema 0.2 * instant。它的优点是反应快、参数好调缺点是参数选得不好会显得敏感。我最终采用“EMA为主、滑动窗口为辅”的组合面板大数字用EMA短时间内的波动一目了然面板角落里再放一个基于60秒窗口的平均速度做趋势参考。两个值同时看既能感觉瞬时变化又不至于被噪声影响判断。实际代码是维护一个每秒采样一次的规程把每次事件带来的输出Token累加到当前秒的桶里然后每秒计算EMAconst SPEED_EMA_ALPHA 0.2; let emaOutputTokensPerSec 0; let bucketTokens 0; let lastBucketTime Date.now(); function onTokenDelta(deltaTokens) { bucketTokens deltaTokens; } setInterval(() { const now Date.now(); const dt (now - lastBucketTime) / 1000; const instant dt 0 ? bucketTokens / dt : 0; emaOutputTokensPerSec emaOutputTokensPerSec 0 ? instant : SPEED_EMA_ALPHA * instant (1 - SPEED_EMA_ALPHA) * emaOutputTokensPerSec; bucketTokens 0; lastBucketTime now; }, 1000);提示EMA系数0.2是我调试下来比较舒服的值。0.1更平滑但迟钝0.3更灵敏但数字会跳动。如果你跑的是代码生成这类高突发任务建议往低调如果只是普通对话可以往高调。2.3 命中率计算三种口径要分清否则统计就是错的命中率是这类插件里最容易算错的地方。我见过一些网上代码把cache_write误当成cache_read算出来的“命中率”超过100%一眼假。这里必须把口径理清楚。主流接口里的缓存相关Token一般分两类cache_read_input_tokens本次请求命中缓存、被免费或大幅优惠读取的输入Token。cache_creation_input_tokens本次请求首次写入缓存的Token正常情况下只出现一次后续相同前缀的请求才能命中。所以命中率就该这么算命中率 累计cacheRead / 累计input这里input是总输入Token而cacheRead是其中命中的那部分。单看一次请求命中率可能很低比如首次请求没有缓存但累计看一个长会话命中率通常会慢慢爬升因为上下文前缀大部分是重复的。我还会额外展示一个辅助指标“缓存写入占比”写入占比 累计cacheWrite / 累计input这个值偏高不是什么坏事反而说明接下来命中率大概率要涨。有一次我看到某次任务写入占比高达30%继续让模型往下跑后面几次请求的命中率果然冲到80%以上。把这个逻辑讲给团队听之后大家再看到“写入占比高”就不慌了。2.4 实时刷新机制事件驱动为主节流兜底有了数据和计算逻辑还差最后一块怎么把数字实时画到界面上。最容易想到的做法是setInterval每秒重绘一次但我没用它作为主力原因有两条。一是无谓开销。OpenCode状态行渲染本身不重但如果你把图表做成了WebView面板每秒全量重绘纯属浪费。二是不必要的闪烁。界面上任何一次重绘都有可能引起光标闪烁、布局抖动尤其在做长时间Agent运行时这种干扰很招人烦。我的做法是事件驱动刷新每当消息完成事件到达把新数据写进插件内部的状态存储如果距离上次渲染超过了300毫秒就触发一次渲染否则只更新内存数据等下一个事件过来时再一起画。这个“渲染节流”保证了高频消息流下不会做无谓的UI更新低频任务下又能及时反映状态。if (now - lastRenderTime 300) { renderStatusLine(snapshot); lastRenderTime now; }注意判断“是否需要渲染”用时间戳比较不要用简单的计数器取模。消息到达的间隔是不均匀的用模运算会在突发流量下把重要的UI更新挤掉。2.5 显示层选型状态行轻量面板兜底最后说显示。OpenCode有两种主流展示位置状态行和浮动面板。状态行是OpenCode界面底部或顶部的一行文字始终可见不遮挡消息区。我三个核心指标实时速度、会话累计Token、命中率全部放在状态行里格式化后长这样模型输出 42.5 tok/s | 累计 238.7K tok | 命中率 86.3%浮动面板适合放更多信息比如缓存写入占比、请求次数、最近一分钟的速度曲线、会话时长。但面板会遮住内容如果面板占据半个屏幕写代码时反而碍事。我给面板做了一个开关快捷键默认折叠需要看明细时再展开。3. 实操从零实现并适配V23.1 插件工程初始化和目录结构搭工程不复杂但结构一开始就要理清楚不然后面改起来想哭。我的插件目录长这样opencode-token-meter/ ├── plugin.json # 插件清单声明名称、入口、版本 ├── dist/ # 编译后的产物目录 │ └── index.js ├── src/ │ ├── index.js # 插件入口注册事件监听 │ ├── stats.js # 统计与EMA/滑动窗口逻辑 │ ├── render.js # 状态行与面板渲染 │ └── compat.js # V1/V2字段兼容层 └── README.md插件清单是最先要写的文件。OpenCode通过它找到插件入口识别插件支持的接口版本。我这里的写法{ name: opencode-token-meter, version: 2.1.0, main: dist/index.js, apis: [plugin-events, status-line], supportedV2: true }apis字段声明了插件希望使用插件事件和状态行两种扩展能力。如果OpenCode在V2里还没有完全启用某个API它会自动降级到旧路径不会直接报错。3.2 统计模块状态存储和重置时机统计模块的核心是一个小小的状态对象const state { inputTotal: 0, outputTotal: 0, cacheReadTotal: 0, cacheWriteTotal: 0, requests: 0, sessionStart: Date.now(), };每次收到消息完成事件就把extractUsage的结果累加进去。关键问题是什么时候重置我踩过一次坑。本来我把统计做成“每次开启新会话就清零”结果用户反馈说“命中率怎么一重启就没”因为OpenCode在同一个进程里可能恢复历史会话恢复后事件又继续来但我的状态已经按新会话清空了。后来我改成两层设计会话级统计跟随session.id宿主级统计跟随进程生命周期。插件记住当前活跃session.id如果事件里的session.id变了就把会话级统计清零宿主级保留状态行默认展示会话级数据。这样既符合“换会话看当前任务”又保留了“跨会话看总体消耗”的口径。3.3 状态行接入与格式化渲染这块我先写了一个纯函数负责把state对象格式化成一行字符串function formatStatusLine(s) { const speed s.outputTokensPerSec.toFixed(1); const total formatK(s.outputTotal s.inputTotal); const hitRate s.inputTotal 0 ? ((s.cacheReadTotal / s.inputTotal) * 100).toFixed(1) : 0.0; return 模型输出 ${speed} tok/s | 累计 ${total} tok | 命中率 ${hitRate}%; }状态行的接入方式在V2里是返回一个“状态行渲染函数”给宿主。插件通过一个注册接口把函数挂上去宿主会在合适的时机调用它宿主用什么频率调用都不需要插件操心插件只管返回字符串。注意状态行渲染函数必须是同步纯函数不能在里面做任何I/O操作。如果需要在渲染前拿到最新数据提前在事件回调里更新state即可。在渲染函数里做计算是自找麻烦宿主可能一分钟调用N次任何额外耗时都会被放大。3.4 V2适配字段兼容层和配置迁移V2适配是我花时间最多的地方。OpenCode升级到V2之后插件接口有几处明显变化老写法直接搬过来会失效。第一是事件名。V1里消息更新走的是message.updatedV2统一收敛成session.updated并且事件对象里新增了state字段里面是标准化后的状态快照。老插件如果还监听message.updated在V2里什么都收不到。第二是usage字段。V2虽然是标准化的但不同模型提供商仍然会往里塞各自的原生字段。我写了一个compat模块把所有可能的字段别名都映射到统一结构上一次映射全仓使用。第三是插件加载时机。V2默认对本地插件做了懒加载优化插件文件不是在启动时立即加载而是等第一次需要用到它的功能时才加载。如果你的插件在启动后立刻要注册事件监听可能因为加载时机变化而漏掉早期的请求事件。解决办法是在插件清单里声明一个“被动初始化”标记或者把关键监听放到OpenCode的启动事件里再注册。配置迁移方面也不复杂。老版插件把配置写在插件目录下单独的config.json里V2统一收编到opencode.json的插件配置块下。我做了一个合并逻辑优先读新位置找不到再读旧位置同时打印一条迁移提示引导用户把配置复制过去。3.5 分发与安装发布版本时建议做两件事生成一份changelog记录每次改动对应的V2接口变化同时提供dist产物让用户可以直接把目录拷到插件目录使用。安装方式我写了两种。一种是本地手动安装把整个目录放进OpenCode的插件目录重载即可。另一种是通过仓库分发构建工具会自动下载dist适合在团队内部共享。README开头我会放一行使用说明明确最低支持的OpenCode V2版本号。4. 常见问题与排查技巧实录4.1 状态行一直是0哪里断了如果插件装好但状态行一直是0优先检查三件事。第一事件有没有真正订阅上。很多人在插件入口写了监听函数但没确认插件被加载。排查方法是在插件启动时往控制台打一行日志看进程启动日志里有没有这一行。V2的懒加载机制下插件可能压根没被初始化日志直接就能看出来。第二usage字段是不是空对象。不同提供商差异很大有的模型走兼容接口时压根不填usage事件里是一个空对象。compat层里我加了一句兜底如果usage完全为空状态行显示“等待数据”而不是显示一个误导性的0。第三状态行渲染函数有没有注册成功。V2里如果apis字段没声明支持状态行能力渲染函数不会生效但插件本身不报错。把apis字段对照插件文档逐项过一遍是最快的修复路径。4.2 命中率突然掉到0正常吗这个现象很多用户遇到最开始我也慌过。排查了一圈后发现大部分原因不在插件而在会话状态。最常见的场景是你新建了一个会话或者切换了上下文目录。模型提供商的缓存是基于“请求前缀”做匹配的新的上下文前缀里没有任何已有缓存第一次请求自然0命中。这时候别着急让对话继续缓存写入后后续请求命中率会快速回升。如果跑了四五轮还是0命中才需要进一步怀疑是配置问题。另外一个可能性是提供商端缓存时间策略。有些缓存是短时效的超过一定时间不访问就会过期。如果你习惯开着会话思考很久再继续第一次继续请求通常都会先“重新写入缓存”表现就是写入占比高、命中率低。注意这类问题不要一看到命中率低就怪插件统计错了。插件只是如实展示接口返回的数据真正决定命中率的是你的会话行为和服务商的缓存策略。4.3 速度数字疯狂跳动怎么调数字跳动绝大多数是EMA系数太灵敏。模型输出本来就是突发式的一个快chunk过来瞬间速度飙到几千下一秒小chunk过来又掉回几十。EMA系数0.2已经算稳定了如果还是觉得跳往0.1调。第二个原因可能是统计里混入了多个并发请求。OpenCode里并行Agent任务可能同时有多个请求在流式返回如果不做session隔离多个请求的增量Token会被合进同一个速度计算里数字自然乱跳。我后来加了按session.id隔离的桶只有当前活跃会话的增量才参与速度计算。第三个容易忽略的点不要把手字延迟第一个Token出现前的等待时间算进速度里。那段时间确实在“等”但模型没有输出任何Token分母时间却一直在涨算出来的平均速度会失真。我的做法是只有当某个流式请求第一个增量来了之后才开始计时。4.4 V2升级后插件失效怎么救升级OpenCode V2后插件失灵十次里有八次是事件名或配置文件路径问题。建议按这个顺序排查先看插件文档里V2的事件对照表把代码里所有监听事件逐个替换。然后检查usage字段的取值逻辑V2的标准化字段如果和提供商原生字段冲突以提供商字段为准compat层里做一次二选一。最后确认插件清单里的apis字段准确声明了用到的扩展点。少声明会静默失效多声明一般没坏处。修复完之后我建议保留一个V1兼容分支。V2并不是所有用户都第一时间升级总有人还在旧版本。我在代码里加了一个运行时版本检测根据宿主版本自动选择走新事件还是旧事件一个插件同时兼容两个大版本。这个改动让我少收到至少一半的“装不上去”反馈。4.5 常见问题速查表现象可能原因解决办法状态行一直显示0插件未加载 / 事件未订阅 / usage为空查启动日志、确认apis声明、看兜底提示命中率长期为0新会话无缓存 / 上下文前缀变化 / 缓存过期多跑几轮确认检查是否频繁切会话速度数字剧烈跳动EMA系数过大 / 多请求混入 / 手字延迟计入调低系数、按session隔离、首chunk后再计时升级V2后失效事件名变了 / 配置路径迁移 / apis未声明按V2事件对照表改使用compat层统计数字和API账单对不上厂商费用口径包含缓存写入折扣或免费额度以接口文档字段为准插件展示的是原生usage最后再分享一点个人体会。做完这个插件之后我才真正意识到所谓“实时监控”最大的价值其实不在于精确计算每一分钱而在于帮你建立对AI编程过程的体感。当你亲眼看到某次重构任务里命中率从20%慢慢爬到85%你就知道让Agent连续工作在长上下文里到底有多划算当你看到一次冷启动请求的写入占比飙升你就能理解为什么有时候第一问特别贵。工具帮你看到数字数字帮你做判断——这比任何账单页上的汇总数字都有用。如果你也想跑一个类似的插件我的建议是从最小集开始先实现状态行里的三个数字跑通事件流和EMA再一步步加上面板、兼容层千万别一开始就追求大而全。另外遇到“token exchange failed”这类登录报错不要和插件统计混淆那是认证环节的问题优先检查API Key和接口地址配置。好好用你的OpenCode让每一秒生成速度和每一次缓存命中都在你的掌控之内。