pi-ptc-meter 1.0.23 → 1.0.25

package/README.en.md

@@ -1,40 +1,9 @@
 # pi-ptc-meter
 
-Per-turn tool-call metering: counts calls and duration, then feeds the numbers back to the model.
+Per-turn tool-call metering, fed back to the model in a tail message.
 
-## Install
+**English documentation:** [open the English section](README.md#english) · **中文文档：** [中文](README.md#zh)
 
-```bash
-pi install npm:pi-ptc-meter
-```
+    pi install npm:pi-ptc-meter
 
-## Configuration
-
-Config file `~/.pi/ptc-meter.json` (optional; invalid JSON falls back):
-
-| Key | Default | Description |
-| --- | --- | --- |
-| `threshold` | `39` | Per-turn call threshold (> 0) |
-| `inject` | `true` | Enable the feedback message |
-| `notify` | `false` | Use UI notifications instead |
-
-Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no environment variables.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `/ptc [n]` | Last n turns: counts, duration, estimates, median, over-threshold |
-
-## What it does (source facts)
-
-- `tool_call`: increments a counter (never intercepts or rewrites).
-- `turn_end`: records calls and duration (no disk write).
-- `agent_end`: writes one log line per run.
-- `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation and the baseline median as a `nextTurn` trailing message.
-- `session_start`: resets module-level counters.
-- The `ptc_meter` system section holds only a byte-stable skeleton.
-
-## License
-
-MIT
+Source: https://github.com/op15066212/pi-plugins-publish

package/README.md

@@ -7,6 +7,8 @@
 
 # pi-ptc-meter
 
+> 适用 pi ≥ 0.74 · Node ≥ 20 · MIT · 无运行时依赖（仅 peer: @earendil-works/pi-coding-agent）
+
 每轮工具调用计量：记录调用次数与耗时，与开工前声明的估算对比后，把实际值与偏差回灌给模型。
 
 ## 快速事实
@@ -57,7 +59,14 @@ pi install npm:pi-ptc-meter
 - `tool_call`：计数 +1（不拦截、不改调用）。
 - `turn_end`：记录本轮次数与耗时（不落盘）。
 - `agent_end`：每 run 落盘一行日志。
-- `before_agent_start`：结算上一轮并以 `nextTurn` 尾部消息回灌计数、耗时、偏差、基线中位。
+- `before_agent_start`：结算上一轮并以 `nextTurn` 尾部消息回灌——计数、耗时、偏差、基线中位、**缓存命中率**（仅当该轮有 usage 数据时出现；< 90% 标「低」）——（`display: false`）。
+
+**注入样例（示意，字段可能随版本增删）**
+
+```text
+PTC 计量：上一轮 9 次工具调用 · 实际 34s · 命中 92% · 预计 8 次 / 实际 9 次（偏差 +13%）
+ · 会话中位 25 · 阈值 50 · 判据 = 本轮计数不超阈值且无同类调用可并
+```
 - `session_start`：模块级计量归零。
 - system 内 section `ptc_meter` 只含逐字不变的骨架。
 
@@ -146,7 +155,14 @@ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no enviro
 - `tool_call`: increments a counter (never intercepts or rewrites).
 - `turn_end`: records calls and duration (no disk write).
 - `agent_end`: writes one log line per run.
-- `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation and the baseline median as a `nextTurn` trailing message.
+- `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation, the baseline median and the **cache hit rate** (only when that turn reported usage; flagged low below 90%) as a `nextTurn` trailing message (`display: false`).
+
+**Sample injection (illustrative; fields may change between versions)**
+
+```text
+PTC metering: last turn 9 tool calls · 34s actual · 92% cache hit · estimated 8 / actual 9 (+13%)
+ · session median 25 · threshold 50 · verdict: under threshold, no obvious merge candidates
+```
 - `session_start`: resets module-level counters.
 - The `ptc_meter` system section holds only a byte-stable skeleton.
 

package/index.ts

@@ -30,7 +30,7 @@
  *
  * ## 配置
  * `~/.pi/ptc-meter.json`：{ "threshold": 39, "notify": false, "inject": true }
- *   threshold 超标线 · **notify 超标时弹窗（默认关**——反馈走 section 注入，弹窗只在你想被打扰时才开）· inject 是否写 section（关掉就退回纯计量）
+ *   threshold 超标线 · **notify 超标时弹窗（默认关**——反馈走 section 注入，弹窗只在你想被打扰时才开）· inject 是否注入尾部回灌消息（关掉就退回纯计量）
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { appendFileSync, closeSync, existsSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
@@ -103,7 +103,7 @@ function sidOf(ctx: ExtensionContext): string {
 }
 
 
-type Row = { calls: number; ms: number; est: number | null; estCalls?: number | null };
+type Row = { calls: number; ms: number; est: number | null; estCalls: number | null };
 
 /** 只读文件尾部至多 maxBytes 字节并按行切分；起点不在文件头时丢弃首行残片。 */
 function tailText(file: string, maxBytes: number): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-meter",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,11 @@
     "pi",
     "pi-extension",
     "pi-coding-agent",
-    "pi-package"
+    "pi-package",
+    "metrics",
+    "tool-calls",
+    "observability",
+    "benchmarking"
   ],
   "pi": {
     "extensions": [
@@ -24,8 +28,11 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
-  "author": "15066212pp",
-  "homepage": "https://github.com/op15066212/pi-plugins-publish/tree/main/pi-ptc-meter",
+  "author": {
+    "name": "15066212pp",
+    "url": "https://github.com/op15066212"
+  },
+  "homepage": "https://github.com/op15066212/pi-plugins-publish/tree/main/pi-ptc-meter#readme",
   "bugs": {
     "url": "https://github.com/op15066212/pi-plugins-publish/issues"
   },
@@ -36,5 +43,8 @@
   },
   "scripts": {
     "prepublishOnly": "node ../publish-check.mjs"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }