pi-ptc-meter 1.0.32 → 1.0.34

package/README.md

@@ -9,7 +9,7 @@
 
 > 适用 pi · Node ≥ 22.19 · MIT · 无运行时依赖（仅 peer: @earendil-works/pi-coding-agent）
 
-每轮工具调用计量：记录调用次数与耗时，与开工前声明的估算对比后，把实际值与偏差回灌给模型。
+每轮工具调用计量：记录调用次数与耗时，回灌实际值与会话中位。不做预估、不算偏差（1.0.32 起两处预估均已移除）。
 
 ## 快速事实
 
@@ -17,7 +17,7 @@
 | --- | --- |
 | 配置文件 | ~/.pi/ptc-meter.json（可省略） |
 | 命令行 | /ptc [n]（默认 20） |
-| 调用方式 | **全自动**：计数与回灌无需触发；估算由模型在回复中自行声明（如「预计 40 次」），扩展只负责解析与对比 |
+| 调用方式 | **全自动**：每轮计数与回灌无需触发；只回灌实际值与中位，不收集预估（1.0.32 起调用数/耗时两处预估均已删除——实测中位误差 94% / 199%） |
 
 完整配置（全部键与默认值）：
 
@@ -52,60 +52,66 @@ pi install npm:pi-ptc-meter
 
 | 命令 | 作用 |
 | --- | --- |
-| `/ptc [n]` | 最近 n 轮：次数、时长、预计、中位、超标 |
+| `/ptc [n]` | 最近 n 轮：次数、时长、中位、超标 |
+
+## 模拟测试
+
+pi-ptc-meter 的改动在**隔离副本**上做回放验证后才发版；当前版本通过 **10,011 条断言**。
+
+| 测试面 | 规模 | 结果 |
+| --- | --- | --- |
+| 真实日志回放 | 4,349 轮 | 🟢 |
+| 随机状态 | 10,000 条 | 🟢 |
+| 统计函数边界 | 11 项 | 🟢 |
+
+🟢 **结论**：预估功能已删除——412 个声明点上 6 种预测器全部落在 71–94% 误差，预估恰好在它被需要的那一刻不可预测。
+
+改动：删调用数预估 + 耗时预估。依据：预估在声明点不可预测：412 个声明点上 6 种预测器全部 71–94% 误差；耗时中位误差 199%。
 
 ## 作用（源码事实）
 
 - `tool_call`：顶层调用计数 +1（codemode 内层调用不另计；不拦截、不改调用）。
-- `turn_end`：记录本轮次数与耗时（不落盘）。
-- `agent_end`：每 run 落盘一行日志；goal 自动续轮共享同一 run 时，`turn_end` 超阈值即提示一次（每 run 一次），避免回路整段失效。
-- `before_agent_start`：结算上一轮并以 `nextTurn` 尾部消息回灌——计数、耗时、偏差、基线中位、**缓存命中率**（仅当该轮有 usage 数据时出现；< 90% 标「低」）——（`display: false`）。
+- `turn_end`：记录本轮次数与耗时（不落盘）；超阈值时每 run 提示一次（goal 自动续轮共享同一 run 时 `agent_end` 可能整段不触发，避免回路失效）。
+- `agent_end`：每 run 落盘一行日志。
+- `before_agent_start`：结算上一轮并以 `nextTurn` 尾部消息回灌——计数、耗时、**缓存命中率**（仅当该轮有 usage 数据时出现；< 90% 标「低」）、会话中位、阈值判定（`display: false`）。
+- **1.0.32 起不再回灌「预计 / 实际 / 偏差」**：声明率虽升到 65%，中位误差仍为 94%（调用数）与 199%（耗时），且 412 个声明点上 6 种预测器（常量 12/16、1.1× 上轮、2.0× 上轮、全局中位、区间 3~40）全部落在 71–94% 误差。
 
 **注入样例（示意，字段可能随版本增删）**
 
 ```text
-PTC 计量：上一轮 9 次工具调用 · 实际 34s · 命中 92% · 预计 8 次 / 实际 9 次（偏差 +13%）
- · 会话中位 25 · 阈值 50 · 判据 = 本轮计数不超阈值且无同类调用可并
+PTC 计量：上一轮 9 次工具调用 · 实际 34s · 命中 92% · 会话中位 25 · 阈值 50 · 判据 = 本轮计数不超阈值且无同类调用可并
 ```
 - `session_start`：模块级计量归零。
 - system 内 section `ptc_meter` 只含逐字不变的骨架。
-
 ## 原理（专业）
 
 ```text
-本轮开工前 ─ 声明「预计 N 次 / 预计 Ns」
-        ↓
 tool_call ─ 仅顶层调用计数 +1
         ↓
-turn_end ─ 记录实际次数与耗时 + 解析预计值
+turn_end ─ 记录实际次数与耗时
         ↓
-agent_end ─ 落盘一行日志（含预计）
+agent_end ─ 落盘一行日志
         ↓
 before_agent_start ─ 结算上一轮
         ↓
-对比：实际 vs 预计 → 偏差 %
+回灌：实际次数 / 耗时 / 命中率 / 会话中位 / 阈值判定
         ↓ nextTurn 尾部消息
-（回到本轮开工前）
 
 system 只留静态骨架（ptc_meter section）
 ```
-
 ## 原理（小白）
 
-**像记账对账**：开工前先说「这趟大概 5 步」，收工后对账「实际 7 步，比预计多 40%」，下次开工前把账报给你。
+**像仪表盘**：不看你预测，只报「刚跑了几步、这个会话通常几步」。计划由你定，仪表只给事实。
 
 ```text
-开工前先估：预计几步
-        ↓
 干活：实际跑几步
         ↓
-收工对比：实际 vs 预计
+收工记账
         ↓
-下次开工时报出偏差
+下次开工报：上一轮 7 步，会话中位 25
         ↓
-（回到开工前先估）
+你自己决定要不要合并调用
 ```
-
 ## License
 
 MIT
@@ -116,7 +122,7 @@ MIT
 
 <h1 align="center">🌐 English Version &nbsp;⬇️</h1>
 
-Per-turn tool-call metering: records calls and duration, compares them with the estimate declared before the turn, and feeds back the actuals and deviation.
+Per-turn tool-call metering: records calls and duration and feeds back the actuals plus the session median. No estimates, no deviation (1.0.32 removed both).
 
 ## At a glance
 
@@ -124,7 +130,7 @@ Per-turn tool-call metering: records calls and duration, compares them with the
 | --- | --- |
 | Config file | ~/.pi/ptc-meter.json (optional) |
 | Commands | /ptc [n] (default 20) |
-| Automation | **Fully automatic**: metering and feedback need no trigger. The estimate is declared by the model in its reply (e.g. "about 40 calls"); the extension only parses and compares |
+| Automation | **Fully automatic**: metering and feedback need no trigger. Only the actual values and the session median are fed back; no estimates are collected (1.0.32 removed both the call-count and duration estimates - measured median errors were 94% and 199%) |
 
 Full config (all keys and defaults):
 
@@ -159,58 +165,64 @@ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no enviro
 
 | Command | Purpose |
 | --- | --- |
-| `/ptc [n]` | Last n turns: counts, duration, estimates, median, over-threshold |
+| `/ptc [n]` | Last n turns: counts, duration, median, over-threshold |
+
+## Verification
+
+Changes to pi-ptc-meter were verified on an isolated copy before release; the current version passes **10,011 assertions**.
+
+| Surface | Scale | Result |
+| --- | --- | --- |
+| Real log replay | 4,349 turns | 🟢 |
+| Random states | 10,000 | 🟢 |
+| Statistic edges | 11 | 🟢 |
+
+🟢 **Result**: both estimates removed - on 412 declaration points all six predictors landed at 71-94% error, so estimating is unpredictable exactly when it is needed.
+Change: both estimates removed. Why: estimates are unpredictable at declaration points: six predictors all landed at 71-94% error; duration median error 199%.
 
 ## What it does (source facts)
 
 - `tool_call`: increments the counter for top-level calls only (nested codemode calls are not counted separately; never intercepts or rewrites).
-- `turn_end`: records calls and duration (no disk write).
-- `agent_end`: writes one log line per run.; when goal auto-continuation shares one run, `turn_end` warns once above threshold (once per run) so the loop never goes dark.
-- `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation, the baseline median and the **cache hit rate** (only when that turn reported usage; flagged low below 90%) as a `nextTurn` trailing message (`display: false`).
+- `turn_end`: records calls and duration (no disk write); when goal auto-continuation shares one run and `agent_end` never fires, it warns once above threshold (once per run).
+- `agent_end`: writes one log line per run.
+- `before_agent_start`: settles the previous turn and feeds back counts, duration, the **cache hit rate** (only when that turn reported usage; flagged low below 90%), the session median and the threshold verdict as a `nextTurn` trailing message (`display: false`).
+- **1.0.32 no longer feeds back estimate / actual / deviation**: declaration rate rose to 65% but the median error stayed at 94% (call count) and 199% (duration); on 412 declaration points all six predictors (constant 12/16, 1.1x previous, 2.0x previous, global median, interval 3-40) landed between 71% and 94% error.
 
 **Sample injection (illustrative; fields may change between versions)**
 
 ```text
-PTC metering: last turn 9 tool calls · 34s actual · 92% cache hit · estimated 8 / actual 9 (+13%)
- · session median 25 · threshold 50 · verdict: under threshold, no obvious merge candidates
+PTC metering: last turn 9 tool calls · 34s actual · 92% cache hit · session median 25 · threshold 50 · verdict: under threshold, no obvious merge candidates
 ```
 - `session_start`: resets module-level counters.
 - The `ptc_meter` system section holds only a byte-stable skeleton.
-
 ## How it works (technical)
 
 ```text
-before the turn ─ declare: about N calls / Ns
-        ↓
 tool_call ─ top-level call: counter +1
         ↓
-turn_end ─ record actual calls and duration + parse estimate
+turn_end ─ record actual calls and duration
         ↓
-agent_end ─ write one log line (includes estimate)
+agent_end ─ write one log line
         ↓
 before_agent_start ─ settle the previous turn
         ↓
-compare: actual vs estimate -> deviation %
+feed back: calls / duration / cache hit / session median / threshold verdict
         ↓ nextTurn message
-(back to before the turn)
 
 the system prompt keeps only a static skeleton (ptc_meter section)
 ```
-
 ## How it works (plain words)
 
-**Like a ledger**: you estimate "about 5 steps" before starting, the ledger compares it with the actual 7 (40% over), and reports the gap before the next job.
+**Like a dashboard**: it does not care what you predicted; it just reports how many steps the last turn took and what this session usually takes. You decide the plan; the dashboard gives facts.
 
 ```text
-before starting: guess N steps
-        ↓
-work: actually N steps
+work: N actual steps
         ↓
-at the end: actual vs guess
+log it
         ↓
-report the gap next time
+next turn reports: last turn 7 calls, session median 25
         ↓
-(back to before starting)
+you decide whether to merge calls
 ```
 ## License
 

package/package.json

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