1. 为什么我要给 OpenCode 写一个 Token 监控插件用 OpenCode 写代码这件事一旦上手就很难回去了。它把终端、编辑器、模型调用串成一条顺滑的链路敲几行指令就能让模型帮你改文件、跑测试、补注释。但用得越久我心里越没底——我根本不知道每次对话到底烧了多少 Token缓存命中率是高是低响应速度是快是慢。这种感觉就像开车不看油表跑到半路熄火才知道没油了。市面上大部分 AI 编程工具的用量统计都藏在网页后台要切浏览器、登录、翻菜单一套流程下来思路全断了。我想要的很简单在 OpenCode 界面里直接看到实时数据——当前会话累计消耗多少 Token、缓存命中率多少、每秒输出多少 Token。这三个指标基本能反映一次对话的性价比Token 用量告诉你花了多少钱命中率告诉你省了多少钱速度告诉你等得值不值。这个插件就是干这个的。它挂在 OpenCode 的会话生命周期上监听每一次模型请求和响应把 usage 字段里的数据抓出来实时渲染到状态栏或者侧边面板。目前已适配 V2 版本的接口协议V1 的老用户升级后也能平滑迁移。适合谁用三类人一是天天泡在 OpenCode 里写代码的重度用户二是需要控制 API 成本的小团队三是想搞清楚缓存到底有没有生效的技术控。下面我把整个插件的设计思路、核心实现、踩过的坑全部摊开讲。2. 插件整体设计与核心思路拆解2.1 需求拆解三个指标到底在解决什么问题先把这个插件要展示的三个核心指标说清楚不然后面的实现逻辑没法展开。Token 速度准确说是输出速率tokens per secondTPS指的是模型每秒生成多少个 Token。这个指标直接决定你的等待体验。实测下来主流模型在正常负载下 TPS 在 30 到 80 之间低于 20 就会明显感觉卡顿高于 100 基本是秒出。注意这里要区分首 Token 延迟TTFT和持续输出速率前者反映的是排队和预填充时间后者才是真正的生成速度。我的插件两个都统计但状态栏默认显示 TPS因为更直观。命中率指的是缓存命中率cache hit rate。现在主流模型服务都支持 prompt caching你重复发送的系统提示词、上下文前缀如果命中缓存价格能便宜到十分之一甚至更低。命中率的计算公式是命中率 缓存命中的 Token 数 / 总输入 Token 数 × 100%这个数字低于 50% 就说明你的提示词结构有问题缓存没吃上钱白花了。我见过有人命中率长期在 10% 以下一问才知道他把每次都变的时间戳塞在了系统提示词最前面缓存直接失效。Token 用量包括输入 Token、输出 Token、缓存读取 Token、缓存写入 Token 四个部分。这四个数字加起来才是真实成本。很多人只看输入输出忽略了缓存写入其实也是要收费的虽然比正常输入便宜算总账的时候对不上。2.2 技术选型为什么用插件而不是改源码OpenCode 本身是开源的理论上我可以直接改源码加统计逻辑。但我没这么干原因有三个。第一升级成本。OpenCode 迭代很快V1 到 V2 接口协议就变了不少。改源码意味着每次升级都要重新 merge冲突处理起来很烦。插件走的是官方扩展点接口稳定升级基本无感。第二职责分离。统计逻辑和核心功能耦合在一起出问题不好排查。插件崩了顶多不显示数据不影响正常写代码。这个隔离性在实际使用中太重要了我踩过一次坑早期版本统计逻辑里有个未捕获的异常直接把整个会话搞挂了后来全部改成 try-catch 兜底。第三可配置性。不同人对指标的关注点不一样有人只关心钱有人只关心速度。插件可以做成配置项让用户自己选显示哪些、刷新频率多少、阈值告警怎么设。改源码做不到这么灵活。具体技术栈上插件用 TypeScript 写跑在 OpenCode 的插件运行时里。数据采集走的是事件钩子hook机制监听message.completed这类事件从事件 payload 里拿 usage 数据。渲染层用 OpenCode 提供的 UI API支持状态栏和面板两种模式。2.3 V2 适配的关键变化V2 版本最大的变化是 usage 数据的结构。V1 时代 usage 字段比较扁平大概长这样{ prompt_tokens: 1200, completion_tokens: 350, total_tokens: 1550 }V2 把缓存相关的字段拆得更细了变成了嵌套结构{ usage: { input_tokens: 1200, output_tokens: 350, cache_read_input_tokens: 800, cache_creation_input_tokens: 200 } }这个变化看着小但影响很大。V1 时代你根本不知道缓存有没有生效V2 才能算出真实命中率。我的插件在适配时做了版本探测启动时读一次 OpenCode 的版本号V1 走老解析逻辑V2 走新逻辑中间用适配器模式隔开。这样老用户升级 OpenCode 不会导致插件报错。提示如果你是从 V1 升级上来的第一次看到命中率数据可能会吓一跳——很多人以为自己缓存用得挺好实际一测发现命中率只有 20% 多。别慌这是正常的后面我会讲怎么优化。3. 核心细节解析与实操要点3.1 数据采集钩子怎么挂、数据怎么拿插件的数据来源只有一个OpenCode 在每次模型响应完成后触发的事件。这个事件的 payload 里带着完整的 usage 信息。核心代码大概是这样export function activate(context: ExtensionContext) { const disposable context.events.on(message.completed, (event) { try { const usage extractUsage(event); if (!usage) return; statsCollector.record(usage); ui.update(statsCollector.snapshot()); } catch (err) { logger.warn(usage extract failed, err); } }); context.subscriptions.push(disposable); }这里有几个细节值得说。第一事件可能不携带 usage。比如用户中途取消、网络中断、模型返回错误这些情况下 payload 里可能没有 usage 字段。所以extractUsage必须做空值判断拿不到就静默跳过不能抛异常。第二事件触发频率可能很高。如果你开了流式输出某些实现会在每个 chunk 都触发事件。这时候要做节流throttle我设的是 200ms 一次既保证实时性又不会把 UI 刷爆。第三多会话并发。OpenCode 支持同时开多个会话每个会话的统计数据要分开算。我用 sessionId 做 key维护一个 MapUI 上只显示当前活跃会话的数据但历史数据保留方便你回看。3.2 速度计算别被平均值骗了Token 速度的计算看着简单实际有坑。最朴素的做法是TPS 输出 Token 数 / 总耗时但这个算法有两个问题。一是首 Token 延迟被算进去了如果模型排队排了 3 秒实际生成只用了 1 秒算出来 TPS 会低得离谱。二是流式输出的时间戳不好拿你只能拿到开始和结束时间。我的做法是分段计算。从事件 payload 里尽量拿到首 Token 的时间戳V2 协议里有first_token_at字段然后TTFT first_token_at - request_start_at TPS output_tokens / (response_end_at - first_token_at)这样算出来的 TPS 才是真实的生成速度。如果拿不到首 Token 时间戳就退化成整体计算但在 UI 上标注估算值。还有一个细节滑动窗口。单次请求的 TPS 波动很大有时候模型抽风生成特别快有时候特别慢。我维护了一个最近 10 次请求的滑动窗口显示的是窗口内的加权平均。这样数字更稳定不会一直跳。3.3 命中率计算分子分母都要抠清楚命中率的计算是重灾区很多人算错。正确的公式是命中率 cache_read_input_tokens / (input_tokens cache_read_input_tokens cache_creation_input_tokens)注意分母是所有输入侧的 Token包括正常输入、缓存读取、缓存写入三部分。为什么缓存写入也要算进分母因为它也是你这次请求实际处理的输入量只是走了不同的计费通道。我见过有人把分母写成input_tokens cache_read_input_tokens漏掉了 cache_creation结果命中率虚高。还有人把输出 Token 也算进分母那就更离谱了。另外命中率要按会话累计不要按单次请求看。单次请求的命中率波动极大第一次请求命中率必然是 0因为还没建立缓存第二次可能就跳到 80%。看累计值才有意义。我的插件默认显示会话累计命中率同时保留最近一次请求的命中率作为参考。3.4 UI 渲染状态栏还是面板OpenCode 提供了两种 UI 挂载点状态栏status bar和侧边面板panel。我的插件两种都支持用户自己选。状态栏适合极简显示一行字搞定TPS 45.2 | 命中 78% | 12.3k tok面板适合详细展示可以放表格、图表、历史记录。我做了个简单的柱状图显示最近 20 次请求的 TPS 变化一眼就能看出模型什么时候在抽风。渲染性能上有个坑不要每次事件都全量重绘。我一开始图省事每次数据更新就重建整个 DOM结果高频事件下 CPU 直接飙到 30%。后来改成差量更新只改变化的文本节点CPU 降到 2% 以下。注意状态栏的宽度有限数字要格式化。Token 数超过 1000 用 k 表示超过 100 万用 M 表示。TPS 保留一位小数命中率取整。别把一堆小数位堆上去看着累。4. 实操过程与核心环节实现4.1 环境准备与插件安装先把环境理清楚。你需要OpenCode 本体V2 版本V1 也能用但部分功能受限Node.js 18 以上一个能正常调用的模型服务安装插件有三种方式我推荐第二种。方式一从插件市场装。OpenCode 有内置的插件市场搜 token-stats 就能找到。点安装重启生效。最省事但版本更新可能滞后。方式二从源码装。克隆仓库npm install npm run build然后把产物目录软链到 OpenCode 的插件目录。适合想改代码的人。git clone repo-url opencode-token-stats cd opencode-token-stats npm install npm run build ln -s $(pwd)/dist ~/.opencode/plugins/token-stats方式三手动配置。在 OpenCode 的配置文件里加一行{ plugins: [ { name: token-stats, path: /path/to/plugin } ] }装完之后重启 OpenCode状态栏应该会出现数据。如果没出现先看日志日志里会打印插件加载情况。4.2 配置项详解与参数选择插件有一份配置文件放在~/.opencode/token-stats.json。默认配置长这样{ display: statusbar, refreshInterval: 200, windowSize: 10, showTTFT: false, alertThreshold: { tpsLow: 20, hitRateLow: 50 }, format: { tokenUnit: k, tpsPrecision: 1 } }逐个说下参数怎么选。displaystatusbar或panel。屏幕小的选 statusbar屏幕大的选 panel。我平时用 statusbar需要看历史的时候临时切 panel。refreshInterval刷新间隔单位毫秒。默认 200。设太小 UI 会抖设太大实时性差。200 是实测下来最舒服的值。windowSize滑动窗口大小。默认 10。窗口越大数字越稳但越滞后窗口越小越灵敏但越跳。10 次请求大概覆盖 1 到 2 分钟的使用比较合适。showTTFT是否显示首 Token 延迟。默认关。TTFT 对普通用户意义不大但对调优的人很重要。如果你在排查为什么感觉卡打开它。alertThreshold告警阈值。TPS 低于 20 或者命中率低于 50% 时状态栏数字变红。这个阈值可以按你的模型调整有些小模型 TPS 本来就低阈值要往下调。4.3 一次完整的实测记录我拿一个真实项目跑了一遍记录下数据。项目是一个中等规模的 TypeScript 后端大概 50 个文件。我用 OpenCode 让它帮我重构一个模块。第一次请求输入 3200 Token输出 800 Token缓存读取 0缓存写入 3200。命中率 0%正常第一次没缓存。TPS 42.3TTFT 1.2 秒。第二次请求输入 3400 Token输出 600 Token缓存读取 3000缓存写入 400。命中率 88%。TPS 51.7TTFT 0.4 秒。注意 TTFT 大幅下降这就是缓存的威力。第十次请求累计输入 35000 Token累计输出 7000 Token累计缓存读取 28000。会话累计命中率 80%。平均 TPS 48.5。成本对比如果不用缓存这十次请求的输入成本是 35000 Token 全价。用了缓存之后28000 Token 走缓存价假设是 1/10 价格实际成本相当于 35000 - 28000 2800 9800 Token 全价。省了 72%。这个数字是实打实的插件把它算出来之后我才真正意识到缓存有多重要。4.4 命中率优化的实操技巧看到命中率数据之后我做了几件事把命中率从 80% 提到了 95% 以上分享下。第一把稳定内容放前面。系统提示词、项目背景、代码规范这些不变的内容全部放在 prompt 最前面。变化的内容用户当前问题、临时上下文放后面。缓存是按前缀匹配的前缀越稳定命中率越高。第二去掉时间戳和随机 ID。我之前的系统提示词里有个当前时间xxx每次都不一样直接把缓存打穿。改成让模型自己判断时间或者把时间放到用户消息里。第三控制上下文长度。缓存有最小长度要求不同模型不一样一般 1024 Token 起太短的 prompt 不缓存。但也不是越长越好超过模型上限会被截断反而破坏缓存。我一般控制在 2000 到 8000 Token 之间。第四注意缓存过期。缓存有 TTL一般是 5 分钟。如果你两次请求间隔超过 5 分钟缓存就失效了。所以连续工作时命中率高断断续续工作时命中率低这是正常的。5. 常见问题与排查技巧实录5.1 数据不显示或显示为 0这是最常见的问题。排查顺序如下。第一步看插件有没有加载。打开 OpenCode 的日志搜 token-stats。如果没有任何输出说明插件没加载成功。检查插件路径、配置文件格式、Node 版本。第二步看事件有没有触发。在插件代码里临时加一行console.log(event)看message.completed事件有没有来。如果没来可能是 OpenCode 版本不匹配V2 的事件名可能和 V1 不一样。第三步看 usage 字段有没有。事件来了但数据是 0说明 payload 里没有 usage。这种情况通常是模型服务没返回 usage 信息或者返回的字段名和预期不符。打印完整 payload 看看实际结构。第四步看解析逻辑。字段名对不上是最隐蔽的问题。V2 协议里是cache_read_input_tokens有些服务可能写成cache_read_tokens。我的插件做了字段名兼容但如果你用的是魔改版服务可能还要再加。5.2 命中率异常高或异常低异常高接近 100%先怀疑是不是算错了。检查分母有没有漏掉 cache_creation。如果分母算对了还是 100%那可能是模型服务把没命中的也报成命中了这种情况少见但存在。异常低长期低于 30%大概率是 prompt 结构问题。按我上面说的四条优化。还有一个可能你的请求间隔太长缓存一直过期。试试连续快速发几次请求看命中率会不会上去。忽高忽低正常现象。第一次请求命中率 0第二次可能 90%第三次可能 60%因为上下文变了。看累计值别看单次。5.3 TPS 显示异常TPS 显示为 0 或负数时间戳计算出问题了。检查first_token_at和response_end_at的差值如果是负数说明时钟不同步或者字段拿反了。TPS 高得离谱几百上千可能是把缓存读取的 Token 也算进输出里了。输出 Token 只算output_tokens别把输入侧的算进来。TPS 一直很低先排除网络问题。如果网络正常可能是模型服务负载高。换个时间段试试或者换个模型对比。5.4 常见问题速查表现象可能原因排查方法解决方案数据完全不显示插件未加载查日志搜插件名检查路径和配置数据全为 0usage 字段缺失打印完整 payload确认模型服务版本命中率算错分母漏项核对公式补上 cache_creationTPS 异常时间戳错误打印时间字段修正计算逻辑UI 卡顿全量重绘看 CPU 占用改差量更新多会话数据串了sessionId 未隔离打印 sessionId按会话分 Map5.5 几个我踩过的坑坑一异常没兜住导致会话崩溃。早期版本我在事件回调里直接抛异常结果一次解析失败把整个会话搞挂了。后来所有回调都包了 try-catch出错只记日志不影响主流程。这个教训很深刻插件的第一原则是不能影响宿主。坑二内存泄漏。我用 Map 存历史数据但从来没清理过。跑了一整天之后内存涨到几百兆。后来加了 LRU 淘汰只保留最近 100 个会话的数据。坑三格式化函数性能问题。Token 数格式化我一开始用正则高频调用下成了瓶颈。后来改成简单的数学运算加查表性能提升明显。坑四V2 升级后字段名变了没发现。V2 刚出的时候我直接升级结果数据全 0。查了半天才发现字段名从prompt_tokens变成了input_tokens。后来加了版本探测和字段名兼容才算稳了。提示如果你要自己改这个插件记住一条铁律——任何可能抛异常的地方都要兜住。插件崩了事小把用户的会话搞崩了事大。6. 后续可以怎么扩展这个插件目前只做了最基础的统计和展示能扩展的方向不少。我自己在琢磨的有几个。成本估算。现在只显示 Token 数不显示钱。如果能配置每个模型的单价就能实时算出这次会话花了多少钱。这个功能对团队用户特别有用可以设个预算告警。历史趋势图。现在只有最近 20 次的柱状图如果能存历史数据画个按天/按周的趋势图就能看出使用习惯的变化。自动优化建议。根据命中率和 TPS 数据自动给出优化建议。比如你的命中率偏低建议把系统提示词里的动态内容移到用户消息。多模型对比。同一个任务用不同模型跑对比 TPS、命中率、成本帮你选最合适的模型。这些扩展都不难核心数据采集层已经搭好了剩下的就是加 UI 和逻辑。我个人的体会是监控类工具的价值不在于数据本身而在于数据带来的行为改变。装了插件之前我从来不看 Token 用量装了之后我会主动优化 prompt 结构一个月下来 API 成本降了将近一半。这个投入产出比比任何优化技巧都高。最后分享一个小技巧如果你觉得状态栏太占地方可以设成只在鼠标悬停时展开。平时就显示一个极简的图标需要看数据的时候再展开。这样既不干扰写代码又能随时掌握情况。