pi-ptc-meter 1.0.16 → 1.0.18

package/README.md

@@ -9,6 +9,24 @@
 
 每轮工具调用计量：统计调用次数与耗时，并把数字回灌给模型。
 
+## 快速事实
+
+| 项 | 说明 |
+| --- | --- |
+| 配置文件 | ~/.pi/ptc-meter.json（可省略） |
+| 命令行 | /ptc [n]（默认 20） |
+| 调用方式 | **全自动**：计数与回灌无需触发；命令只查看 |
+
+完整配置（全部键与默认值）：
+
+```json
+{
+  "threshold": 39,
+  "inject": true,
+  "notify": false
+}
+```
+
 ## 安装
 
 ```bash
@@ -42,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/>记录次数与耗时]
@@ -51,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
@@ -63,6 +96,24 @@ MIT
 
 Per-turn tool-call metering: counts calls and duration, then feeds the numbers back to the model.
 
+## At a glance
+
+| Item | Description |
+| --- | --- |
+| Config file | ~/.pi/ptc-meter.json (optional) |
+| Commands | /ptc [n] (default 20) |
+| Automation | **Fully automatic**: metering and feedback need no trigger; the command only reads |
+
+Full config (all keys and defaults):
+
+```json
+{
+  "threshold": 39,
+  "inject": true,
+  "notify": false
+}
+```
+
 ## Install
 
 ```bash
@@ -96,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.16",
+  "version": "1.0.18",
   "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
   "type": "module",
   "license": "MIT",