# pi-turn-metrics

[![npm](https://img.shields.io/npm/v/pi-turn-metrics.svg)](https://www.npmjs.com/package/pi-turn-metrics)
[![pi-package](https://img.shields.io/badge/pi--package-extension-blue.svg)](https://pi.dev)
[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[English](README.md) | [中文说明](README.zh.md)

**pi-turn-metrics** 是一个为 [Pi Coding Agent](https://pi.dev) 打造的底部状态栏扩展插件，用于实时监控对话与任务执行过程中的 **轮次 (Turns)**、**步数 (Steps)**、**模型耗时 (LLM Duration)**、**工具耗时 (Tool Duration)**、**首字延迟 (TTFT)** 与 **生成速率 (TPS)**。

算法与展示规则 100% 对齐 **Deepseek Harness** 官方规范，并支持终端窗口宽度的动态自适应排版。

---

## 📸 效果预览

```text
# 标准风格（默认 / 终端宽度 ≥ 80 列）
1 turns · 4 steps | LLM 34.1s · Tool call 0.6s | TTFT avg 3.9s · 68 tok/s

# 紧凑风格（窄屏窗口或宽度受限时自动切换）
1t·4s | LLM 34.1s · Tool 0.6s | TTFT 3.9s · 68 tok/s
```

---

## ⚡ 快速安装

```bash
# 通过 npm 安装
pi install npm:pi-turn-metrics

# 或通过 git 安装
pi install git:github.com/leon-zym/pi-turn-metrics

# 临时体验（无需安装）
pi -e npm:pi-turn-metrics
```

在运行中的 Pi 会话中，输入 `/reload` 即可热重载生效。

---

## 🎯 展示内容与特性

Pi 原生状态行主要展示 **Token 账目与上下文占用**（`↑ 输入`、`↓ 输出`、`R 缓存读取`、`CH 缓存命中率`、`已用上下文 / 最大容量`），**pi-turn-metrics** 补充了执行流与时间维度的核心指标：

| 模块 | 展示示例 | 含义说明 |
| :--- | :--- | :--- |
| **执行计数 (Counts)** | `1 turns · 4 steps` | 用户发起的交互轮次，以及 Agent 自治调用的内部步骤数。 |
| **执行耗时 (Durations)** | `LLM 34.1s · Tool call 0.6s` | 细分纯模型推理生成耗时与本地工具/命令执行耗时。 |
| **流式性能 (Speeds)** | `TTFT avg 3.9s · 68 tok/s` | 平均首字延迟（TTFT）与解码吞吐速率（TPS）。 |

- **耗时瓶颈直观诊断**：一眼分辨耗时是在等模型生成还是本地命令（构建、测试或安装）。
- **终端宽度自适应**：监听终端列宽及 `resize` 事件，在标准 Pipe 风格与紧凑缩写风格间自适应切换，避免被终端粗暴截断。

---

## 📐 计算逻辑（对齐 Deepseek Harness）

指标计算严格对齐 [Deepseek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 `sessionStats` 规范：

- **Turns & Steps**：用户每次提问 `turns + 1`；模型每完成一次响应 `steps + 1`。
- **LLM & Tool 耗时**：`LLM` 累加请求发起至组装完成的耗时；`Tool call` 按工具调用 ID 配对累加执行毫秒数（天然支持并发）。
- **TTFT (首字延迟)**：捕获首个有效 token delta chunk（文本、思考过程或工具调用）并求各步平均值。
- **TPS (解码吞吐)**：模型实际输出 Token 总数除以解码总耗时（首 token 到消息结束）。

---

## 📄 开源许可证

MIT © 2026 [zhangyiming](https://github.com/leon-zym)