pi-ptc-meter 1.0.17 → 1.0.18

package/README.md

@@ -60,6 +60,8 @@ pi install npm:pi-ptc-meter
 - `session_start`：模块级计量归零。
 - system 内 section `ptc_meter` 只含逐字不变的骨架。
 
+## 原理（专业）
+
 ```mermaid
 flowchart TD
     A[tool_call] -->|计数 +1| B[turn_end<br/>记录次数与耗时]
@@ -69,6 +71,19 @@ flowchart TD
     D -.->|system 只留静态骨架| S[ptc_meter section]
 ```
 
+## 原理（小白）
+
+像计步器：这一趟跑了多少步（调用了几次工具），下一趟出发前告诉你「上次 40 步，比平时多」，你自己决定要不要合并行程。
+
+```mermaid
+flowchart LR
+    A[这一轮干活] --> B[计步：用了几次工具]
+    B --> C[记下来]
+    C --> D[下一轮开始时报数]
+    D --> A
+```
+
+
 ## License
 
 MIT
@@ -132,7 +147,27 @@ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no enviro
 - `session_start`: resets module-level counters.
 - The `ptc_meter` system section holds only a byte-stable skeleton.
 
+## How it works (technical)
+
 ```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]
+
+## 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.
+
+```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]
+    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]

package/package.json

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