# pi-sysmon
**在 [pi](https://github.com/earendil-works/pi) 里显示 bottom 风格的 braille 折线图**
CPU · 内存 · 网络 · Tokens —— 用盲文点阵字符画的实时历史曲线
[](#测试)
[](LICENSE)
150 列宽下的默认四图。曲线由盲文字符绘制，y 刻度叠印在绘图区内侧、
时间标签嵌在下边框里。
终端变窄时排成 2×2，再窄就变 1 列竖排。断点在 96 列：
≥ 96 是四图并排一行（上方那张），< 96 就降到 2×2（这张是 95 列）。
bottom 在同样宽度下会把四张图硬挤成一行（每张 16 列左右），曲线就不可读了。
### Tokens 图的上下行
```
┌ Tokens ─ ~58t/s ·92% ⌀87% ↑5.9k ↓60 R2.7k ─┐
```
读数与 pi 自己的状态栏同口径（`↑` 上行 input / `↓` 下行 output / `R` 缓存读），
所以两边可以直接对照。几个细节：
- **主曲线只画下行速率**。两个方向的时间形状完全不同（上行是一次性整块上传、
下行是逐字流式，实测比例约 516:1），画同一根轴上会将下行压成 0.2% 高度。
- **`~` 只加在速率上** —— 它是从流式增量估算的；累计值来自 provider 的
精确 `usage`，所以不带 `~`。哪个数字可信，一眼能看出来。
- 块变窄时按重要度逐段丢弃：速率 → 瞬时命中率 → 累计命中率 → 上行 → 下行 → 缓存读。
### 缓存命中率：第二根曲线
缓存命中的 prompt token 计费远低于全新输入，所以命中率是唯一能回答“缓存到底有没有起作用”
的数字。Tokens 块从两个视角展示它：
- **`⌀N%` —— 会话累计命中率**（黄色曲线）。`⌀` 读作“平均”；每次消息落地时从会话累计值
重新计算，因此曲线是阶梯状 —— 这是诚实的：底层数字是 provider 精确上报的总量，
两个消息之间没有更细的信息可画。
- **`·N%` —— 瞬时命中率**（仅标题栏）。最近一轮自己的
`cacheRead / (cacheRead + input)` 比例；这才是可据以行动的数字 ——
累计平均值会把一轮未命中缓存的请求藏很久。
黄色曲线有**自己固定的 0–100% 量程**，预先映射到 TPS 轴上且不参与 y 轴量程计算：
90% 的命中率永远渲染为绘图区高度的 90%，哪怕 3000 t/s 的流式尖峰把 TPS 轴顶抬高。
刻度列仍然只显示 TPS —— 靠颜色绑定（黄色曲线 ⇄ `⌀` 读数）区分两根线。
两个读数只在 provider 上报过缓存读（`R`）之后才出现；从未碰过缓存的会话会原样退回
之前的单曲线块。`line` 模式同样显示 `·N%`/`⌀N%`（门控条件完全一致），并且 token 组
在重要度顺序中排到了 NET 之前 —— line 放不下时整组从尾部丢弃，而 token 读数比网络
速率更难从屏幕其他地方找回。
## 安装
### 用 pi 安装（推荐）
```bash
# 从 npm 装最新版
pi install npm:pi-sysmon
# 或锁定具体版本
pi install npm:pi-sysmon@0.4.0
# 或直接装 git 源
pi install git:github.com/zzjcool/pi-sysmon
```
重启 pi 即可看到曲线，**默认就是开启的**。升级用 `pi update npm:pi-sysmon`，
卸载用 `pi remove npm:pi-sysmon`。
### 从 git clone 装：单文件（手动安装里最简单）
```bash
git clone https://github.com/zzjcool/pi-sysmon && cd pi-sysmon && npm install
npm run build:single # 生成 dist/pi-sysmon.ts
cp dist/pi-sysmon.ts ~/.pi/agent/extensions/pi-sysmon.ts
```
### 从 git clone 装：目录形式（多文件）
```bash
git clone https://github.com/zzjcool/pi-sysmon
cp -r pi-sysmon ~/.pi/agent/extensions/pi-sysmon
```
> ⚠️ 目录形式**必须放在子目录里**。pi 的自动发现会把 `extensions/` 下的每个 `.ts`
> 都当成扩展加载，平铺多个文件会导致 `braille.ts` 被当作扩展而整个加载失败。
### 不安装先试用
```bash
pi -e npm:pi-sysmon
```
## 使用
```text
/sysmon 开 / 关（**只影响当前会话**）
/sysmon on | off 显式开 / 关（只影响当前会话）
/sysmon global on | off 设置**新会话**的默认开关（同时立即作用于当前会话）
/sysmon chart 图表模式（默认）
/sysmon below|above 图表 / line 放编辑器下方（默认）/ 上方（持久化）
/sysmon line 一行文字模式（显示 `CPU … TOK …` 的那一行；别名 `status`）
/sysmon footer 用图表替换整个底部（可以比 widget 模式更高）
```
`chart` / `line` 是**互斥的显示模式**（点某个模式名 = 切过去并打开，不会把监控关掉）；
`on` / `off` / `above` / `below` 与模式正交。
### 点击切换模式（仅 fullscreen TUI）
在 pi 的 **fullscreen** TUI 模式下（`--tui-mode fullscreen`，或在 `/settings` 里切 **TUI mode**），
面板右下角会出现一个可点击的 `[line]` / `[chart]` 小标签 —— 点一下就在 chart 和 line
之间切换，不用敲命令：
```text
┌ CPU ─ 12% ───────────────────────┐
│ ⡿⢸⣿⡇ ... │
└ 60s ──────────────────────── 0s ┘
[line]
```
- 点击走的是和 `/sysmon chart` / `/sysmon line` **同一条路径** —— 模式切换作为全局显示偏好持久化，
会话级开关状态完全不受影响。
- `line` 模式下标签和文字同行（行高仍严格为 1 行 —— 标签的列从指标文字里借，指标照旧
从尾部整段丢弃）。
- fullscreen 下图表用**自己的行预算**支付 chip 那一行，面板总行数不会超过 `WIDGET_MAX_ROWS`。
- 标签以外的点击不会被吞：在面板上拖拽选中文字的行为和以前完全一样。
- `regular` 模式（默认）完全不接管鼠标 —— 那时终端拥有回滚区 —— 所以不渲染标签，
面板行为和以前一模一样。请用 `/sysmon chart | line` 切换。
为什么标签没有悬停高亮：tmux/zellij/screen 下 pi 只开启 button-motion 鼠标上报（没有
`move` 事件），所以标签必须在没有任何悬停反馈的情况下也看起来能点。
### 会话级 vs 全局级
`/sysmon on|off` 是**会话级**的：写在当前会话自己的 entry 里，所以 `/resume` 回到这个会话时
开关和离开时一模一样，而**其它会话、以后新开的会话都不受影响** —— 在某个项目里关掉，
只在这个会话里关掉。
`/sysmon global on|off` 把**新会话的默认值**写进 `