pi-ptc-meter 1.0.18 → 1.0.20

package/README.md

@@ -64,26 +64,27 @@ pi install npm:pi-ptc-meter
 
 ```mermaid
 flowchart TD
-    A[tool_call] -->|计数 +1| B[turn_end<br/>记录次数与耗时]
-    B --> C[agent_end<br/>落盘一行日志]
-    C --> D[before_agent_start<br/>结算上一轮]
-    D -->|nextTurn 尾部消息<br/>次数 / 耗时 / 偏差 / 中位| A
-    D -.->|system 只留静态骨架| S[ptc_meter section]
+    A[本轮开工前<br/>声明 预计 N 次 / 预计 Ns] --> B[tool_call<br/>计数 +1]
+    B --> C[turn_end<br/>记录实际次数与耗时 + 解析预计值]
+    C --> D[agent_end<br/>落盘一行日志（含预计）]
+    D --> E[before_agent_start<br/>结算上一轮]
+    E --> F[对比：实际 vs 预计 → 偏差 %]
+    F -->|nextTurn 尾部消息| A
+    F -.->|system 只留静态骨架| S[ptc_meter section]
 ```
 
 ## 原理（小白）
 
-像计步器：这一趟跑了多少步（调用了几次工具），下一趟出发前告诉你「上次 40 步，比平时多」，你自己决定要不要合并行程。
+**像记账对账**：开工前先说「这趟大概 5 步」，收工后对账「实际 7 步，比预计多 40%」，下次开工前把账报给你。
 
 ```mermaid
-flowchart LR
-    A[这一轮干活] --> B[计步：用了几次工具]
-    B --> C[记下来]
-    C --> D[下一轮开始时报数]
+flowchart TD
+    A[开工前先估：预计几步] --> B[干活：实际跑几步]
+    B --> C[收工对比：实际 vs 预计]
+    C --> D[下次开工时报出偏差]
     D --> A
 ```
 
-
 ## License
 
 MIT
@@ -151,21 +152,24 @@ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no enviro
 
 ```mermaid
 flowchart TD
-    A[tool_call] -->|counter +1| B[turn_end<br/>record calls and duration]
-    B --> C[agent_end<br/>write one log line]
-    C --> D[before_agent_start<br/>settle previous turn]
-    D -->|nextTurn message<br/>calls / duration / deviation / median| A
-    D -.->|system keeps a static skeleton| S[ptc_meter section]
+    A[before the turn<br/>declare: about N calls / Ns] --> B[tool_call<br/>counter +1]
+    B --> C[turn_end<br/>record actual calls and duration + parse estimate]
+    C --> D[agent_end<br/>write one log line (includes estimate)]
+    D --> E[before_agent_start<br/>settle the previous turn]
+    E --> F[compare: actual vs estimate -> deviation %]
+    F -->|nextTurn message| A
+    F -.->|system keeps a static skeleton| S[ptc_meter section]
+```
 
 ## How it works (plain words)
 
-Like a pedometer: counts how many steps (tool calls) this trip took, then tells you before the next trip that last one was 40 steps, above your usual — you decide whether to combine errands.
+**Like a ledger**: you estimate "about 5 steps" before starting, the ledger compares it with the actual 7 (40% over), and reports the gap before the next job.
 
 ```mermaid
-flowchart LR
-    A[this turn's work] --> B[count: how many tool calls]
-    B --> C[record it]
-    C --> D[report at the start of the next turn]
+flowchart TD
+    A[before starting: guess N steps] --> B[work: actually N steps]
+    B --> C[at the end: actual vs guess]
+    C --> D[report the gap next time]
     D --> A
 ```
 flowchart TD
@@ -174,7 +178,6 @@ flowchart TD
     C --> D[before_agent_start<br/>settle previous turn]
     D -->|nextTurn message<br/>calls / duration / deviation / median| A
     D -.->|system keeps a static skeleton| S[ptc_meter section]
-```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-meter",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
   "type": "module",
   "license": "MIT",