pi-ptc-meter 1.0.9 → 1.0.11

package/README.en.md

@@ -1,28 +1,17 @@
-# 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
+## What it solves
 
-| 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 |
+"One tool call = one round trip" is the biggest systematic waste in agent execution, and it is invisible. This extension turns call counts, duration and deviation into a number that appears every turn, and flags turns above the threshold for a merge review.
 
-## 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 calls per turn, actual duration, and declared estimates.
+- Feeds back counts, duration, baseline median and deviation; flags over-threshold turns (default 39 calls/turn).
+- Numbers travel as trailing messages; the system section keeps a byte-stable skeleton.
+- Log `~/.pi/ptc-meter.jsonl`; command `/ptc [n]`.
 
 ## Install
 
@@ -31,18 +20,67 @@ pi install npm:pi-ptc-meter
 pi install ./pi-ptc-meter
 ```
 
-## Config
+## Configuration
+
+### 1 · Config file `~/.pi/ptc-meter.json`
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `threshold` | number | `39` | Per-turn threshold, **39 calls/turn** (p75 calibration; 12 would fire on 62% of turns) |
+| `inject` | boolean | `true` | Enable feedback message |
+| `notify` | boolean | `false` | Use UI notifications instead of silent injection |
 
 ```json
 { "threshold": 39, "inject": true, "notify": false }
 ```
 
+### 2 · Environment
+
+None.
+
+### 3 · Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/ptc` / `/ptc <n>` | Last n turns: counts, duration, estimates, median, over-threshold |
+
+### 4 · Log
+
+| Path | Content |
+| --- | --- |
+| `~/.pi/ptc-meter.jsonl` | turn, calls, duration, estimated calls/duration, session id; tail-preserving at 1 MiB |
+
+## Where it acts (execution path, not thinking)
+
+| Stage | Does |
+| --- | --- |
+| `tool_call` | Increments the counter (counts only; never intercepts) |
+| `turn_end` | Records counts and duration (no disk write) |
+| `agent_end` | Writes one log line per run |
+
+## Feedback path
+
+| Item | Path | Why |
+| --- | --- | --- |
+| Previous calls / duration / deviation | Trailing message, `nextTurn`, `display:false` | Changing numbers in the system prompt invalidate the conversation's prefix cache |
+| `ptc_meter` section | Byte-identical skeleton only | Stable bytes keep the cache intact |
+| Baseline median / systematic bias | "recent N turns median +x% -> report ~k times" | An executable multiplier, not "be more precise" |
+| No estimate declared | Actual value + peer median | The mechanism must not depend on declarations |
+
+**Boundary**: it reports how many calls were used, not whether they could be merged.
+
 ## 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; `turn_end` records; the next `before_agent_start` settles and injects.
+- Estimates parse from reply text (`预计 Ns` / `预计 Nm` / `预计 N 次`), last match in a trailing window.
+- Counters reset on session change; history for the same sid is merged across restarts.
+
+## Limitations
+
+- Counts only; no mergeability judgement.
+- Never intercepts, rewrites input, or reads content.
+- Estimate parsing is heuristic; duration is wall-clock (includes waiting and network).
 
-## 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,17 @@
-# 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 保留尾部整行 |
-| 语言 | 中文 | 注入文本与命令输出 |
+- 统计每轮调用次数、实际耗时、开工前声明的预计次数 / 时长。
+- 回灌计数、耗时、基线中位与偏差；超阈值（默认 39 次/轮）时标注需复核。
+- 数字走对话尾部消息，system 只留逐字稳定的骨架（保护前缀缓存）。
+- 日志 `~/.pi/ptc-meter.jsonl`；命令 `/ptc [n]`。
 
 ## 安装
 
@@ -33,16 +22,65 @@ pi install ./pi-ptc-meter
 
 ## 配置
 
+### 1 · 配置文件 `~/.pi/ptc-meter.json`
+
+| 键 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `threshold` | number | `39` | 每轮调用数阈值 **39 次/轮**（> 0；p75 口径，12 会触发 62% 的轮次） |
+| `inject` | boolean | `true` | 是否注入回灌消息 |
+| `notify` | boolean | `false` | 改用弹窗提示（默认静默注入） |
+
 ```json
 { "threshold": 39, "inject": true, "notify": false }
 ```
 
+### 2 · 环境变量
+
+无（不读环境变量）。
+
+### 3 · 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/ptc` / `/ptc <n>` | 最近 n 轮：次数、时长、预计、中位、超标 |
+
+### 4 · 日志
+
+| 路径 | 内容 |
+| --- | --- |
+| `~/.pi/ptc-meter.jsonl` | 轮次、调用数、时长、预计次数、预计耗时、会话 id；超 1 MiB 保留尾部整行 |
+
+## 作用点（执行通路，不碰 thinking）
+
+| 阶段 | 做什么 |
+| --- | --- |
+| `tool_call` | 计数 +1（只数，不拦截、不改调用） |
+| `turn_end` | 记录本轮次数与耗时（不落盘） |
+| `agent_end` | 每 run 落盘一行日志 |
+
+## 回灌（反馈回到模型的通路）
+
+| 项 | 通路 | 设计理由 |
+| --- | --- | --- |
+| 上轮调用数 / 耗时 / 偏差 | 尾部消息，`nextTurn`，`display:false` | 变化数字进 system → 整段对话前缀缓存失效 |
+| `ptc_meter` section | 只放逐字不变的骨架（阈值口径 + 工程自问索引） | 字节稳定才不毁缓存 |
+| 基线中位 / 系统性偏差 | 附「近 N 轮中位 +x% → 本轮按约 k 倍报」 | 给可执行的倍数，而非抽象的「注意精度」 |
+| 未声明预计 | 只报实际 + 同类中位 | 机制不依赖模型是否声明 |
+
+**边界**：只报「上一轮用了多少次」，不判断调用是否真能合并——可并性需人工复核。
+
 ## 机制
 
-- `tool_call` 计数 → `turn_end` 记录 → 下轮 `before_agent_start` 结算并回灌。
-- 只在尾部消息里变化，system section 每轮字节相同。
+- `tool_call` 计数 → `turn_end` 记录 → 下次 `before_agent_start` 结算注入。
+- 预计值从回复文本解析（`预计 Ns` / `预计 Nm` / `预计 N 次`），取尾部窗口最后一次匹配。
+- 会话切换后计数归零；同 sid 跨重启合并历史。
 
 ## 限制
 
-- 计数只反映调用次数，不判断调用是否真的可合并；可并性需要自行复核。
-- 不拦截、不改输入、不读取对话内容。
+- 只数次数，不判断可并性。
+- 不拦截、不改输入、不读对话内容。
+- 预计解析是文本启发式；耗时是墙钟时间（含等待与网络）。
+
+## License
+
+MIT

package/package.json

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