Skip to content

About

Codex++ 实时吞吐速度、缓存命中率与消耗量监控拓展包(TokenPulse)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

TokenPulse · 吞吐与消耗监控

为 Codex++ 桌面端打造的轻量级实时状态栏拓展:在输入栏底部直接显示当前会话的 生成速度(tok/s)、缓存命中率(%) 与 累计消耗量(如 5.2M),悬停即可展开完整的吞吐分析、工具耗时拆解、上下文占用与多时段消耗统计面板。

本项目基于 MIT 开源项目 LingYingNX/TokenLens-for-Codex 进行增强与封装,完善了会话切换稳定性、状态栏消耗量直观展示与 Codex++ 标准拓展包支持。


核心功能

1. 输入栏底部实时状态栏

  • 实时吞吐速度:仪表盘指针随当前速率动态摆动,数值实时显示 tok/s。
  • 缓存命中率:直观展示当前任务的 Prompt 缓存命中比例(cached / input)。
  • 紧凑消耗量:采用同风格火焰图标 + 紧凑数值格式(如 850、12.3K、5.2M),与弹窗中的统计口径保持一致(默认显示「任务消耗」,并在切换时段后同步联动)。

2. 悬停详情面板

  • 速度与平均速度:顶部展示实时 tok/s 与本轮 token 加权平均速度,支持右上角亮色 / 暗色主题独立切换(保存在 tokenlens-theme)。
  • 上下文进度条:实时读取当前会话的上下文占用百分比与窗口上限(如 23.3%/1M)。
  • 工具执行拆解:按记忆库、Skills、MCP、Hook、图像生成、网页搜索、代码审查、等待、上下文压缩、其他工具分类汇总次数与累计耗时;Skills / MCP 自动识别来源名称。
  • Token 明细与多时段统计:
    • 展开查看 输入、输出、缓存读取、缓存命中 与总消耗。
    • 支持 任务 / 今天 / 昨天 / 近 7 天 / 自定义北京时间区间 切换。
    • 若本机运行了 Magpie,每 2 秒只读同步一次本地实时接口(失败按 2/4/8/16/30 秒指数退避);未安装或不可用时自动回退至本地 60 天 localStorage 账本与每日用量接口。
  • 调用柱状图与 TOP 3 排行:
    • 展示本轮调用次数、总轮次、会话累计调用次数。
    • 高亮单次总消耗 TOP 1 / TOP 2 / TOP 3,底部柱状图自适应倍增刻度并支持横向滚动(最多保留最近 200 次调用,排行仍基于完整样本)。

相比原版的优化点

  1. 修复切换会话回来后速度持续掉落:
    • 当切到其他会话期间漏收 turn/completed 或仅收到未闭环通知时,无新事件或超时解码区间会自动冻结在最后有效事件时刻(lastEventAt),不再随空转墙钟持续掉速。
    • 重复回放的 thread/tokenUsage/updated 通知不会推后事件时间戳;从历史记录回填已有未完成轮次时同步对齐起止时间。
    • 切入尚未缓存的会话时自动补齐历史与任务消耗,减少切回后的 -- 等待时间。
  2. 底栏新增紧凑消耗量展示:
    • 在状态栏末尾增加同尺寸火焰描边图标与紧凑消耗值(如 5.2M),无需悬停打开面板即可随时掌握当前任务或选定时段的累计消耗。
  3. 完善 Codex++ 拓展包结构:
    • 增加 codexpp.json 清单、专属图标 assets/icon.svg 与规范化的中文详情文档,在 Codex++ 管理器中可正常展示名称、图标、能力权限与完整 README。

吞吐量与消耗口径

实时速度与平均速度

  • 解码速度优先:优先统计每次有效模型调用从首个 token 到调用结束的纯解码时长,剔除首 token 等待(TTFT)、工具执行与调用间空档:
    有效样本 = 单次解码时长 >= 1000 ms、输出 >= 30 token、速率 <= 400 tok/s
    实时速度 = 最近 3 秒内有效样本输出之和 / 对应解码时长之和(上限 400 tok/s)
    平均速度 = 本轮全部有效样本输出之和 / 本轮全部有效解码时长之和
    
  • 批量推送过滤:不足 1000 ms、少于 30 输出 token 或超过 400 tok/s 的突发样本不参与速度计算,避免失真尖峰。
  • 兜底机制:仅在尚无逐调用时间轴(例如历史回填或未收到流式 delta)时,才使用剔除首 token 等待与工具耗时后的轮次窗口作为回退;无新事件后冻结在最后一次有效事件时刻,保持数值稳定。

消耗量格式化规则

范围 状态栏显示格式 示例
< 1,000 整数原值 850
1,000 ~ 999,949 K 单位(最多 1 位小数) 12.3K
999,950 ~ 999,949,999 M 单位(最多 1 位小数) 5.2M
>= 999,950,000 B 单位(最多 1 位小数) 1.3B

安装与使用

方式一:作为 Codex++ 拓展包安装(推荐)

将包含 codexpp.json、tokenlens.js、README.md 与 assets/icon.svg 的目录放入 Codex++ 用户脚本目录的 token-pulse/ 子文件夹中:

  • Windows:%APPDATA%\Codex++\user_scripts\token-pulse\
  • macOS:~/.config/Codex++/user_scripts/token-pulse/

放入后打开 Codex++ 管理器 → 拓展 → 本地拓展,点击刷新并启用 TokenPulse · 吞吐与消耗监控,然后点击 热重载拓展 即可。

方式二:单文件用户脚本安装

如果仅使用单文件模式,可将 tokenlens.js 直接复制到:

  • Windows:%APPDATA%\Codex++\user_scripts\tokenlens.js
  • macOS:~/.config/Codex++/user_scripts/tokenlens.js

如果此前已安装市场原版 TokenLens for Codex(market-tokenlens-for-codex.js),请先在管理器中停用原版,再启用新版本并热重载,避免两个状态栏互相覆盖。


隐私与数据边界

  • 不读取对话内容:仅监听 Codex 本地状态事件、会话用量统计与滚动记录,不读取或上传任何对话正文、提示词或代码内容。
  • 只读本地接口:仅在启用时按需向本机 Magpie(http://127.0.0.1:3425/v1/magpie/usage/requests?...&agent=codex&limit=1)发起只读请求,统计范围仅限 codex Agent(input + output + cache_read),排除后台非任务调用。
  • 本地存储:仅在浏览器 localStorage 中保存主题偏好(tokenlens-theme)和最近 60 天的每日用量汇总账本(tokenlens-daily-usage)。

开发与测试

本仓库无第三方 npm 依赖,使用 Node.js 22+(已验证 Node.js 24)运行语法检查与单元测试:

node --check tokenlens.js
node --test tests/*.test.js

开源协议与致谢

About

Codex++ 实时吞吐速度、缓存命中率与消耗量监控拓展包(TokenPulse)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages