pi-ptc-meter 1.0.19 → 1.0.21

package/README.md

@@ -64,22 +64,24 @@ 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 TD
-    A[干活：调用工具] --> B[计步：几次]
-    B --> C[记下来]
-    C --> D[下轮开始时报数]
+    A[开工前先估：预计几步] --> B[干活：实际跑几步]
+    B --> C[收工对比：实际 vs 预计]
+    C --> D[下次开工时报出偏差]
     D --> A
 ```
 
@@ -150,32 +152,26 @@ 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 TD
-    A[work: tool calls] --> B[count: how many]
-    B --> C[record it]
-    C --> D[report next turn]
+    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
-    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]
-
 ## License
 
 MIT

package/package.json

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