# Zcode Tps Monitor

> ZCode 会话级 Token 速率监控插件:每轮回复末尾显示真实 tok/s(读取 ZCode usage 数据库),附实时监控大屏、/tps 命令、MCP 工具与业务 TPS 监控

- **Type:** MCP server
- **Install:** `agentstack add mcp-shy3130-zcode-tps-monitor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shy3130](https://agentstack.voostack.com/s/shy3130)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shy3130](https://github.com/shy3130)
- **Source:** https://github.com/shy3130/zcode-tps-monitor

## Install

```sh
agentstack add mcp-shy3130-zcode-tps-monitor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 中执行:

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

### 方式二:本地目录

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

### 更新

```text
/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` |

示例接口返回:

```json
{"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](https://github.com/shy3130)
- **Source:** [shy3130/zcode-tps-monitor](https://github.com/shy3130/zcode-tps-monitor)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shy3130-zcode-tps-monitor
- Seller: https://agentstack.voostack.com/s/shy3130
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.