pi-ptc-meter 1.0.8 → 1.0.10

package/README.en.md

@@ -1,28 +1,16 @@
-# pi-ptc-meter — per-turn tool-call metering (pi extension)
+# pi-ptc-meter — per-turn tool-call metering and feedback (pi extension)
 
-Turns "one tool call = one round trip" into visible numbers, and feeds them back to the model when a turn runs long.
+> Requires pi >= 0.74 · Node >= 20 · MIT · no runtime dependencies
 
-## Features
-
-- Counts tool calls, wall time and the predicted count declared before the turn.
-- Flags turns above the threshold (default 39) for a merge review.
-- Numbers travel in a tail message; the system section stays byte-identical (prefix cache safe).
-- Log: `~/.pi/ptc-meter.jsonl`, one JSON line per turn.
-- `/ptc [n]` shows the last n turns: calls, time, prediction, median, over-threshold.
-
-## Defaults
-
-| Item | Default | Note |
-| --- | --- | --- |
-| Threshold | 39 calls/turn | `threshold` in `~/.pi/ptc-meter.json` |
-| Injection | on | `inject: false` disables |
-| Popup | off | `notify: true` enables (silent by default) |
-| Log | `~/.pi/ptc-meter.jsonl` | keeps whole trailing lines over 1 MiB |
-| Language | Chinese | injected text and command output |
+Turns "one tool call = one round trip" into a visible number: counts tool calls and elapsed time each turn, then feeds the figures back to the model on the next turn.
 
-## Credits
+## Features
 
-Original work; no upstream implementation. The "PTC (parallel tool calls)" discipline comes from the author's working rules; this package is its metering and feedback implementation.
+- Tracks tool calls per turn, actual elapsed time, and the estimated calls / duration declared up front.
+- Feeds back counts, duration, baseline median and deviation; flags turns above the threshold for a merge review.
+- Numbers travel as trailing messages; the system section keeps a byte-stable skeleton (prefix-cache friendly).
+- Log at `~/.pi/ptc-meter.jsonl` — turn, calls, duration, estimates, session id per line.
+- Command `/ptc [n]`: last n turns with counts, duration, estimates, median and over-threshold flags.
 
 ## Install
 
@@ -31,7 +19,27 @@ pi install npm:pi-ptc-meter
 pi install ./pi-ptc-meter
 ```
 
-## Config
+## Configuration
+
+### File `~/.pi/ptc-meter.json`
+
+Every key is optional; invalid JSON falls back to defaults.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `threshold` | number | `39` | Per-turn call threshold, **39 calls/turn** (must be > 0; p75 calibration — 12 would fire on 62% of turns) |
+| `inject` | boolean | `true` | Enable the feedback message |
+| `notify` | boolean | `false` | Use UI notifications instead of silent injection |
+
+### Other
+
+| Item | Default | Description |
+| --- | --- | --- |
+| Log `~/.pi/ptc-meter.jsonl` | on | Tail-preserving truncation at 1 MiB |
+| Language | Chinese | Feedback text and command output |
+| UI notifications | off | See `notify` |
+
+### Example
 
 ```json
 { "threshold": 39, "inject": true, "notify": false }
@@ -39,10 +47,16 @@ pi install ./pi-ptc-meter
 
 ## How it works
 
-- `tool_call` counts → `turn_end` records → next `before_agent_start` settles and feeds back.
-- Only the tail message changes; the section is stable.
+- `tool_call` increments the counter; `turn_end` records the turn; the next `before_agent_start` settles and injects.
+- Only trailing messages change, so the system section is byte-identical each turn (cache friendly).
+- Estimates are parsed from the reply text (`预计 Ns` / `预计 Nm` / `预计 N 次`); when absent it reports only the actual value and the peer median.
+
+## Limitations
+
+- Counts reflect call volume only; whether calls could actually be merged still needs human review.
+- It does not intercept, rewrite input, or read conversation content.
+- Estimate parsing is text heuristics; non-matching formats count as "not declared".
 
-## Limits
+## License
 
-- Counts calls only; whether they could be merged still needs a human check.
-- Does not intercept input or read conversation content.
+MIT

package/README.md

@@ -1,28 +1,16 @@
-# pi-ptc-meter — 每轮工具调用计量与回灌（pi 扩展）
+# pi-ptc-meter —— 每轮工具调用计量与回灌（pi 扩展）
 
-把「一次工具调用 = 一次往返」的浪费变成可见数字：统计每轮调用次数与时长，每轮把数字回灌给模型（超阈值时单独标注）。
+> 适用 pi ≥ 0.74 · Node ≥ 20 · MIT · 无运行时依赖
 
-## 来源与借鉴
-
-原创，无上游实现。「PTC（执行合并）」纪律出自作者的个人工作手册，本包是该纪律的计量与回灌实现。
+把「一次工具调用 = 一次往返」的浪费变成可见数字：统计每轮调用次数与时长，并在下一轮把数字回灌给模型。
 
 ## 功能
 
-- 统计每轮工具调用次数、实际耗时、开工前声明的预计值。
-- 每轮回灌计数、耗时与基线；超阈值（默认 39 次/轮）时标注需复核「是否有可合并的调用」。
-- 数字走对话尾部消息回灌，system 内只留逐字稳定的骨架（保护前缀缓存）。
-- 日志 `~/.pi/ptc-meter.jsonl`，每行含轮次、次数、时长、预计次数、预计耗时、会话 id。
-- 命令 `/ptc [n]`：最近 n 轮的次数、时长、预计、中位、超标。
-
-## 默认配置
-
-| 项 | 默认 | 说明 |
-| --- | --- | --- |
-| 阈值 | 39 次/轮 | `~/.pi/ptc-meter.json` 的 `threshold` |
-| 注入回灌 | 开 | `inject: false` 关闭 |
-| 弹窗提示 | 关 | `notify: true` 开启（默认走静默注入） |
-| 日志 | `~/.pi/ptc-meter.jsonl` | 超过 1 MiB 保留尾部整行 |
-| 语言 | 中文 | 注入文本与命令输出 |
+- 统计每轮工具调用次数、实际耗时、开工前声明的预计次数 / 预计时长。
+- 回灌计数、耗时、基线中位与偏差；超阈值时标注「需复核是否有可合并的调用」。
+- 数字走对话尾部消息，system 内只留逐字稳定的骨架（保护前缀缓存）。
+- 日志 `~/.pi/ptc-meter.jsonl`，每行含轮次、次数、时长、预计值、会话 id。
+- 命令 `/ptc [n]`：最近 n 轮的次数、时长、预计、中位、超标情况。
 
 ## 安装
 
@@ -33,16 +21,42 @@ pi install ./pi-ptc-meter
 
 ## 配置
 
+### 配置文件 `~/.pi/ptc-meter.json`
+
+所有键可省略；非法 JSON 自动回退默认。
+
+| 键 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `threshold` | number | `39` | 每轮调用数阈值 **39 次/轮**（> 0；按 p75 实测口径，12 会触发 62% 的轮次） |
+| `inject` | boolean | `true` | 是否注入回灌消息 |
+| `notify` | boolean | `false` | 是否用弹窗提示（默认走静默注入） |
+
+### 其他
+
+| 项 | 默认 | 说明 |
+| --- | --- | --- |
+| 日志 `~/.pi/ptc-meter.jsonl` | 开 | 超 1 MiB 保留尾部整行 |
+| 语言 | 中文 | 注入文本与命令输出 |
+| 弹窗 | 关 | 见 `notify` |
+
+### 示例
+
 ```json
 { "threshold": 39, "inject": true, "notify": false }
 ```
 
 ## 机制
 
-- `tool_call` 计数 → `turn_end` 记录 → 下轮 `before_agent_start` 结算并回灌。
-- 只在尾部消息里变化，system section 每轮字节相同。
+- `tool_call` 计数 → `turn_end` 记录 → 下一次 `before_agent_start` 结算并回灌。
+- 只有尾部消息变化，system section 每轮字节相同（缓存友好）。
+- 预计值从回复文本解析（`预计 Ns` / `预计 Nm` / `预计 N 次`）；未声明则只报实际值与同类中位。
 
 ## 限制
 
-- 计数只反映调用次数，不判断调用是否真的可合并；可并性需要自行复核。
+- 计数只反映调用次数，不判断调用是否真的可合并；可并性需人工复核。
 - 不拦截、不改输入、不读取对话内容。
+- 预计解析是基于文本的启发式，格式不符时视为未声明。
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-meter",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,10 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "author": "15066212pp",
+  "homepage": "https://github.com/op15066212/pi-plugins-publish/tree/main/pi-ptc-meter",
+  "bugs": {
+    "url": "https://github.com/op15066212/pi-plugins-publish/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/op15066212/pi-plugins-publish.git",