pi-ptc-meter 1.0.10 → 1.0.11

package/README.en.md

@@ -2,15 +2,16 @@
 
 > Requires pi >= 0.74 · Node >= 20 · MIT · no runtime dependencies
 
-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.
+## What it solves
+
+"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.
 
 ## Features
 
-- 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.
+- 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
 
@@ -21,41 +22,64 @@ pi install ./pi-ptc-meter
 
 ## Configuration
 
-### File `~/.pi/ptc-meter.json`
-
-Every key is optional; invalid JSON falls back to defaults.
+### 1 · Config file `~/.pi/ptc-meter.json`
 
 | 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 |
+| `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 |
 
-### 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 }
 ```
 
+### 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` 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.
+- `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 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".
+- Counts only; no mergeability judgement.
+- Never intercepts, rewrites input, or reads content.
+- Estimate parsing is heuristic; duration is wall-clock (includes waiting and network).
 
 ## License
 

package/README.md

@@ -2,15 +2,16 @@
 
 > 适用 pi ≥ 0.74 · Node ≥ 20 · MIT · 无运行时依赖
 
-把「一次工具调用 = 一次往返」的浪费变成可见数字：统计每轮调用次数与时长，并在下一轮把数字回灌给模型。
+## 它解决什么问题
+
+「一次工具调用 = 一次往返」是代理执行里最大的系统性浪费，却不可见。本扩展把每轮调用次数、耗时与偏差变成每轮都会出现的数字，并在超阈值时点明「这一轮有没有可合并的调用」。
 
 ## 功能
 
-- 统计每轮工具调用次数、实际耗时、开工前声明的预计次数 / 预计时长。
-- 回灌计数、耗时、基线中位与偏差；超阈值时标注「需复核是否有可合并的调用」。
-- 数字走对话尾部消息，system 内只留逐字稳定的骨架（保护前缀缓存）。
-- 日志 `~/.pi/ptc-meter.jsonl`，每行含轮次、次数、时长、预计值、会话 id。
-- 命令 `/ptc [n]`：最近 n 轮的次数、时长、预计、中位、超标情况。
+- 统计每轮调用次数、实际耗时、开工前声明的预计次数 / 时长。
+- 回灌计数、耗时、基线中位与偏差；超阈值（默认 39 次/轮）时标注需复核。
+- 数字走对话尾部消息，system 只留逐字稳定的骨架（保护前缀缓存）。
+- 日志 `~/.pi/ptc-meter.jsonl`；命令 `/ptc [n]`。
 
 ## 安装
 
@@ -21,41 +22,64 @@ pi install ./pi-ptc-meter
 
 ## 配置
 
-### 配置文件 `~/.pi/ptc-meter.json`
-
-所有键可省略；非法 JSON 自动回退默认。
+### 1 · 配置文件 `~/.pi/ptc-meter.json`
 
 | 键 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `threshold` | number | `39` | 每轮调用数阈值 **39 次/轮**（> 0；按 p75 实测口径，12 会触发 62% 的轮次） |
+| `threshold` | number | `39` | 每轮调用数阈值 **39 次/轮**（> 0；p75 口径，12 会触发 62% 的轮次） |
 | `inject` | boolean | `true` | 是否注入回灌消息 |
-| `notify` | boolean | `false` | 是否用弹窗提示（默认走静默注入） |
-
-### 其他
-
-| 项 | 默认 | 说明 |
-| --- | --- | --- |
-| 日志 `~/.pi/ptc-meter.jsonl` | 开 | 超 1 MiB 保留尾部整行 |
-| 语言 | 中文 | 注入文本与命令输出 |
-| 弹窗 | 关 | 见 `notify` |
-
-### 示例
+| `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 每轮字节相同（缓存友好）。
-- 预计值从回复文本解析（`预计 Ns` / `预计 Nm` / `预计 N 次`）；未声明则只报实际值与同类中位。
+- `tool_call` 计数 → `turn_end` 记录 → 下次 `before_agent_start` 结算注入。
+- 预计值从回复文本解析（`预计 Ns` / `预计 Nm` / `预计 N 次`），取尾部窗口最后一次匹配。
+- 会话切换后计数归零；同 sid 跨重启合并历史。
 
 ## 限制
 
-- 计数只反映调用次数，不判断调用是否真的可合并；可并性需人工复核。
-- 不拦截、不改输入、不读取对话内容。
-- 预计解析是基于文本的启发式，格式不符时视为未声明。
+- 只数次数，不判断可并性。
+- 不拦截、不改输入、不读对话内容。
+- 预计解析是文本启发式；耗时是墙钟时间（含等待与网络）。
 
 ## License
 

package/package.json

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