Zcode Tps Monitor

zcode-tps-monitor

[](LICENSE)

ZCode 会话级 Token 速率监控插件。 每轮回复结束时自动显示本轮即时 tok/s —— 数据直接读取 ZCode usage 数据库,非模型自述、非估算;另附实时监控大屏、斜杠命令、MCP 工具与可选的业务 TPS 监控。

> 本仓库同时是一个 ZCode 本地插件市场(marketplace 名称:tps-local-marketplace),插件本体位于 [plugins/zcode-tps-monitor/](plugins/zcode-tps-monitor/README.md)。

效果预览

每轮回复结束时自动显示一行速率指标,无需任何手动操作。行在回复刚结束的瞬间采样(Stop 钩子),头条就是本轮的即时速率——多段工具调用的长轮次按"总产出 / 总生成时长"加权:

| 字段 | 含义 | |---|---| | 537.3 tok/s | 本轮即时输出速率(含思考 token;多段轮次为加权速率) | | 首字 3.0s | 首 token 延迟(TTFT,本轮第一段) | | 输出 223 tok / 生成 0.4s | 本轮输出 token 数与纯生成耗时(不含段间工具等待) | | 2 段 / 峰 537.3 | 本轮的请求段数与单段峰值速率(多段轮次才显示) | | 近3次均 494.9 | 最近数轮滑动平均 | | 累计 51.3k tok | 当前会话累计输出(独立统计,不受窗口限制) | | ⏱ 10:23:04 | 采样时刻(回复结束时间) |

数字显示规则:每轮「输出」用千分位精确数字(如 2,762 tok);「累计」用紧凑单位——千以下原始、1k~1万一位小数(9.8k)、1万~100万取整(51k)、百万以上一位小数 M(73.8M)。

功能特性

• 真实 Token 速率注入(默认开启) —— 每轮回复结束时自动显示本轮即时 tok/s(含思考 token)、首字延迟、输出 token 数、生成耗时、段数/峰值与会话累计
• 实时监控大屏 —— /zcode-tps-monitor:dashboard 一键拉起,浏览器深色运维风格面板,秒级自动刷新;空闲 3 小时自动退出,不留后台进程
• 斜杠命令 —— /tps 即时快照;/tps 10 采样观察 10 秒;/tps-doctor 环境自检
• MCP 工具 —— tps_snapshot / tps_watch,供 agent 程序化取数
• 悬浮条(Windows) —— 桌面常驻文字悬浮条,随时可见当前速率
• 业务 TPS 监控(可选) —— 配置 metrics_url 接入真实业务指标接口,或使用内置演示数据

安装

方式一:从 GitHub 添加(推荐)

在 ZCode 中执行:

/plugin marketplace add shy3130/zcode-tps-monitor
/plugin install zcode-tps-monitor@tps-local-marketplace

方式二:本地目录

克隆本仓库后,在 ZCode 中打开 设置 → 插件管理 → 发现 → +,来源选择"本地目录",指向仓库根目录即可。

更新

/plugin marketplace update tps-local-marketplace

更新后重装/升级插件,并重开会话使钩子重新注册。

使用

| 场景 | 操作 | |---|---| | 查看每轮速率 | 无需操作,每轮回复结束时自动显示本轮即时速率 | | 即时快照 | 输入 /tps;或 /tps 10 持续采样 10 秒 | | 打开监控大屏 | 输入 /zcode-tps-monitor:dashboard,或手动 node dashboard/server.mjs | | 环境自检 | 速率行不见了?输入 /tps-doctor 逐项排查 | | 关闭本轮即时行 | ~/.zcode/tps-monitor.config.json 写入 {"stopHookLine": false},重开会话生效 | | 关闭全部速率注入 | 同文件写入 {"tokenRateLine": false},重开会话生效 | | 桌面悬浮条 | 运行 dashboard/overlay.ps1(Windows) | | agent 取数 | MCP 工具 tps_snapshot / tps_watch |

要求 Node ≥ 22.5(需内置 node:sqlite,Windows / macOS / Linux 相同)。

配置:接入业务 TPS(可选)

插件默认提供演示数据;若要监控真实业务吞吐,在 设置 → 插件管理 → zcode-tps-monitor 中配置 metrics_url,指向任意返回 JSON 的指标接口。字段自动兼容(支持最多三层嵌套):

| 指标 | 识别的字段名 | |---|---| | 吞吐 | tps / qps / throughput / transactionsPerSecond | | 延迟 | p50 / p95 / p99(或 latency_p50 等) | | 错误率 | error_rate / errorRate / err_rate |

示例接口返回:

{"data":{"tps":1240,"p50":11,"p95":28,"p99":46,"error_rate":0.05}}

工作原理

用户发送消息
   │
   ▼
UserPromptSubmit 钩子
   │  读取 ZCode usage 数据库,注入上一轮速率作模型上下文
   ▼
模型回复(工具调用 × N 段)
   │
   ▼
Stop 钩子(回复刚结束,本轮已全部入库)
   │  按最新 turn_id 圈定本轮全部请求,
   │  计算即时速率(总产出 / 总纯生成时长)
   ▼
systemMessage 直接显示本轮速率行

• SessionStart 钩子:会话启动时记录当前会话 ID 并注入使用提示
• UserPromptSubmit 钩子:每轮触发一次,单次为毫秒级数据库读取,开销可忽略;此刻本轮尚未发生,因此只注入上一轮数据作上下文
• Stop 钩子:回复刚结束、本轮数据已完整入库的瞬间触发,按 turn_id 精确圈定本轮(一次用户消息触发的全部请求,含多段工具调用),经 systemMessage 由客户端直接显示——无需模型转发,天然零滞后
• Token 速率与业务 TPS 相互独立:前者始终来自 ZCode 真实数据,后者取决于是否配置 metrics_url

常见问题

Q:可以在 OpenCode / Codex / Claude Code 等其他工具中使用吗?

A:插件机制、钩子与数据源均绑定 ZCode,token 速率功能是 ZCode 专属;其中业务 TPS 采集脚本与大屏是独立程序,可脱离 ZCode 运行,但离开 ZCode 没有速率数据来源。

Q:显示的速率准确吗?

A:速率由 ZCode usage 数据库中的真实 token 累计值计算得出,口径为模型输出侧 token。注意:行在发送消息瞬间采样,显示的是上一条已完成回复的速率;当前回复的速率会在下一轮显示,/tps 命令与监控大屏则是即时的。与其他工具显示的统计数字可能因统计窗口不同而略有差异。

Q:速率行突然不见了?

A:运行 /tps-doctor 自检。常见原因:Node 版本低于 22.5(需内置 node:sqlite)、ZCode 更新后表结构变化、升级插件后未重开会话(钩子需新会话注册)、或配置文件里关闭了注入。

Q:macOS / Linux 支持吗?

A:支持。钩子、命令、大屏、MCP 均为跨平台 Node 实现;usage 数据库路径按用户主目录自动解析(~/.zcode/cli/db/db.sqlite),特殊安装位置可用 ZCODE_USAGE_DB 环境变量覆盖。唯一例外是桌面悬浮条 overlay.ps1,它依赖 Windows API,仅限 Windows(macOS 用户用监控大屏即可)。

Q:演示数据怎么关掉?

A:演示数据只影响"业务 TPS"部分(Token 速率始终真实);不配置 metrics_url 即为演示模式,配置后自动切换为真实数据源。

License

[MIT](LICENSE) © 2026 shy3130

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shy3130
• Source: shy3130/zcode-tps-monitor
• License: MIT

Install and usage instructions live in the source repository linked above.