pi-metrics 0.4.2 → 0.6.0

package/README.md

@@ -7,8 +7,8 @@ Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi):
 ## Features
 
 - While the agent is working, the spinner shows the **total elapsed time since you sent the message** (for example `⏱ 47s`). It keeps counting across turns instead of resetting per turn.
-- When each turn ends, a dim line shows that turn's precise duration (`⏱ Turn elapsed 8.2s`).
-- When the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), a final line shows the **total elapsed time from message send to stop** (`⏱ Total elapsed 18.9s`).
+- When each turn ends, one line reports TPS, TTFT, token counts, generation time, stalls, and blended cost (the line already carries the turn duration, so no separate elapsed notice is emitted).
+- When a run spans more than one turn and the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), a final line adds the **total elapsed time from message send to stop** (`⏱ Total elapsed 18.9s`). Single-turn runs do not repeat it.
 - After each LLM turn, a notification reports TPS, TTFT, token counts, generation time, stalls, and blended cost when available.
 - Telemetry is persisted as `tps` custom session entries and restored after session resume or `/tree` navigation.
 - Metrics are exposed through session entries and notifications. Use `/config:metrics` to open the TUI settings menu, or use `/config:metrics enable|disable` to change the setting directly.

package/README.zh-CN.md

@@ -7,8 +7,8 @@
 ## 功能
 
 - 工作期间 spinner 显示**从发出消息起的全程耗时**（如 `⏱ 47s`），跨轮次持续累加，不再每轮回零。
-- 每个轮次结束时插入一条灰色文本，显示该轮精确耗时（`⏱ 本轮耗时 8.2s`）。
-- AI 完全停止时（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）追加一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）。
+- 每个轮次结束时显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本（一行指标里已包含本轮耗时，不再单独发一条）。
+- 整段运行超过一轮时，AI 完全停止（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）再补一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）；单轮运行不重复报。
 - 每轮 LLM 调用结束后显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本。
 - Telemetry 以 `tps` custom session entry 持久化，并在恢复 session 或 `/tree` 后恢复显示。
 - Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置菜单，也可以使用 `/config:metrics enable|disable` 直接切换。

package/SKILL.md

@@ -15,4 +15,4 @@ description: "启用与排查 pi-metrics 的耗时、TPS、TTFT、token 和成
 
 ## 验证
 
-在 TUI 中完成一次真实模型回合，观察 working spinner、轮次耗时、总耗时和可用的 TPS/TTFT/token/cost。RPC/print 模式不会启动 UI 定时器或通知；provider 未返回 usage 时部分指标不可用。真实模型回合属于 E2E，执行前遵守当前任务授权边界；未运行时明确报告 `NOT_RUN`。
+在 TUI 中完成一次真实模型回合，观察 working spinner、每轮的 TPS/TTFT/token 指标行（含本轮耗时）和可用的 cost；如果一次运行跑了多轮，停下时还应看到一条 `⏱ 总耗时`。RPC/print 模式不会启动 UI 定时器或通知；provider 未返回 usage 时部分指标不可用。真实模型回合属于 E2E，执行前遵守当前任务授权边界；未运行时明确报告 `NOT_RUN`。

package/locales/index.json

@@ -3,10 +3,6 @@
     "zh-CN": "⏱ {value}",
     "en-US": "⏱ {value}"
   },
-  "elapsedDone": {
-    "zh-CN": "⏱ 本轮耗时 {value}",
-    "en-US": "⏱ Turn elapsed {value}"
-  },
   "elapsedTotal": {
     "zh-CN": "⏱ 总耗时 {value}",
     "en-US": "⏱ Total elapsed {value}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-metrics",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Pi metrics extension: elapsed-time HUD and resilient TPS telemetry",
   "type": "module",
   "main": "./index.ts",
@@ -62,7 +62,7 @@
     "@earendil-works/pi-tui": ">=0.80.0"
   },
   "dependencies": {
-    "pi-extensions-i18n": "^0.4.1"
+    "pi-extensions-i18n": "^0.6.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.85.1",

package/src/index.ts

@@ -3,7 +3,8 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+import { createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource } from "pi-extensions-i18n";
+import { NOTICE_SOURCE } from "./notice.ts";
 import turnElapsed from "./turn-elapsed.ts";
 import tps from "./tps.ts";
 import { configPath, loadConfig, parseConfig, saveConfig, type MetricsConfig } from "./config.ts";
@@ -29,32 +30,42 @@ function registerConfigCommand(pi: ExtensionAPI): void {
     handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
       const value = args.trim();
       if (value && value !== CONFIG_RESET_COMMAND && value !== ENABLE_COMMAND && value !== DISABLE_COMMAND) {
-        ctx.ui.notify(i18n.t("configCommandUsage"), NOTICE_WARNING);
+        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandUsage") });
         return;
       }
       if (value === CONFIG_RESET_COMMAND || value === ENABLE_COMMAND || value === DISABLE_COMMAND) {
         try {
           const config = parseConfig(value === CONFIG_RESET_COMMAND ? {} : { enabled: value === ENABLE_COMMAND });
           const path = saveConfig(config);
-          ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+          notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_INFO, message: i18n.t("configCommandSaved", { path }) });
         } catch (error) {
-          ctx.ui.notify(i18n.t("configCommandInvalid", {
-            error: error instanceof Error ? error.message : String(error),
-          }), NOTICE_ERROR);
+          notifyWithSource({
+            ctx,
+            source: NOTICE_SOURCE,
+            level: NOTICE_ERROR,
+            message: i18n.t("configCommandInvalid", {
+              error: error instanceof Error ? error.message : String(error),
+            }),
+          });
         }
         return;
       }
       if (!ctx.hasUI) {
-        ctx.ui.notify(i18n.t("configCommandInteractiveOnly"), NOTICE_WARNING);
+        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandInteractiveOnly") });
         return;
       }
       let current: MetricsConfig;
       try {
         current = loadConfig();
       } catch (error) {
-        ctx.ui.notify(i18n.t("configCommandInvalid", {
-          error: error instanceof Error ? error.message : String(error),
-        }), NOTICE_ERROR);
+        notifyWithSource({
+          ctx,
+          source: NOTICE_SOURCE,
+          level: NOTICE_ERROR,
+          message: i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        });
         return;
       }
       const enabledChoice = i18n.t("configEnabled", { value: i18n.t(current.enabled ? "configOn" : "configOff") });
@@ -69,11 +80,16 @@ function registerConfigCommand(pi: ExtensionAPI): void {
       const choice = selected === enabledChoice ? CONFIG_CHOICE.enabled : CONFIG_CHOICE.disabled;
       try {
         const path = saveConfig({ enabled: choice === CONFIG_CHOICE.enabled });
-        ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_INFO, message: i18n.t("configCommandSaved", { path }) });
       } catch (error) {
-        ctx.ui.notify(i18n.t("configCommandInvalid", {
-          error: error instanceof Error ? error.message : String(error),
-        }), NOTICE_ERROR);
+        notifyWithSource({
+          ctx,
+          source: NOTICE_SOURCE,
+          level: NOTICE_ERROR,
+          message: i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        });
       }
     },
   };
@@ -82,6 +98,8 @@ function registerConfigCommand(pi: ExtensionAPI): void {
 
 /** 注册耗时和 TPS 指标事件；配置关闭时不注册指标处理器。 */
 export default function piHud(pi: ExtensionAPI): void {
+  // 提示画成会话区里的带底色消息块；渲染器在本包这个模块实例里注册一次。
+  installNoticeRenderer(pi);
   registerConfigCommand(pi);
   let config: MetricsConfig;
   let configError: unknown;
@@ -93,10 +111,15 @@ export default function piHud(pi: ExtensionAPI): void {
   }
   if (configError !== undefined) {
     pi.on("session_start", (_event, ctx: ExtensionContext) => {
-      ctx.ui.notify(i18n.t("configLoadFailed", {
-        path: configPath(),
-        error: configError instanceof Error ? configError.message : String(configError),
-      }), NOTICE_WARNING);
+      notifyWithSource({
+        ctx,
+        source: NOTICE_SOURCE,
+        level: NOTICE_WARNING,
+        message: i18n.t("configLoadFailed", {
+          path: configPath(),
+          error: configError instanceof Error ? configError.message : String(configError),
+        }),
+      });
     });
   }
   if (!config.enabled) return;

package/src/notice.ts

@@ -0,0 +1,13 @@
+/**
+ * 本扩展统一的提示来源定义。
+ * 所有 notifyWithSource 调用共用同一份标签与颜色，避免两个入口不一致。
+ */
+
+import type { NoticeColor, NoticeSource } from "pi-extensions-i18n";
+
+/** 本扩展的提示标签；短且唯一，便于在会话里定位来源。 */
+export const NOTICE_TAG = "metrics";
+/** 提示标签颜色；与其它扩展错开，避免看起来像同一条消息。 */
+export const NOTICE_COLOR: NoticeColor = "dim";
+/** 本扩展的提示来源。 */
+export const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };

package/src/tps.ts

@@ -11,7 +11,9 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { notifyWithSource } from "pi-extensions-i18n";
 import { i18n } from "./i18n.ts";
+import { NOTICE_SOURCE } from "./notice.ts";
 
 interface TurnStartEvent {
   type: "turn_start";
@@ -330,11 +332,11 @@ function restoreTPSNotification(
     const data = entry.data as Record<string, unknown> | null | undefined;
     if (!data) continue;
     if (typeof data.model === "object" && data.model !== null) {
-      schedule(() => ctx.ui.notify(composeDisplayString(data as unknown as TurnTelemetry), "info"));
+      schedule(() => notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: composeDisplayString(data as unknown as TurnTelemetry) }));
       return;
     }
     if (typeof data.message === "string") {
-      schedule(() => ctx.ui.notify(data.message as string, "info"));
+      schedule(() => notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: data.message as string }));
       return;
     }
   }
@@ -392,7 +394,7 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     committed.telemetry = corrected;
     pi.appendEntry("tps", corrected);
     pi.events?.emit("tps:telemetry", corrected);
-    if (committed.ctx.hasUI) committed.ctx.ui.notify(composeDisplayString(corrected), "info");
+    if (committed.ctx.hasUI) notifyWithSource({ ctx: committed.ctx, source: NOTICE_SOURCE, level: "info", message: composeDisplayString(corrected) });
   });
 
   pi.on("session_shutdown", () => {
@@ -513,7 +515,7 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     };
     pi.appendEntry("tps", telemetry);
     pi.events?.emit("tps:telemetry", telemetry);
-    if (ctx.hasUI) ctx.ui.notify(composeDisplayString(telemetry), "info");
+    if (ctx.hasUI) notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: composeDisplayString(telemetry) });
   });
 
 }

package/src/turn-elapsed.ts

@@ -3,10 +3,13 @@
  *
  * - working 期间：实时更新 spinner 文字，显示从用户发出消息起的全程耗时（如 "⏱ 47s"），
  *   跨轮不归零 —— 用户等待时最关心的是"一共等了多久"
- * - turn 结束时：在 chat 流插入一条 dim 灰文本，提示本轮耗时（如 "✓ 本轮耗时 12.3s"）
- * - agent 完全停止时（agent_settled）：再插入一条总耗时，覆盖从用户发出消息到 AI 停止
+ * - agent 完全停止时（agent_settled）：插入一条总耗时，覆盖从用户发出消息到 AI 停止
  *   的整段过程（跨越多轮工具调用、自动重试和 compaction 续跑）
  *
+ * 关于「本轮耗时」：它已经包含在 tps 的那条指标提示里（TPS/TTFT/耗时/tokens 一行），
+ * 所以这里不再单独发一条，避免同一轮冒两条指标提示。
+ * 只有整段运行超过一轮时才发总耗时：单轮运行的总耗时只比本轮多一点收尾开销，是噪声。
+ *
  * 设计取舍：
  * - 用 setWorkingMessage 改 spinner 文字会覆盖 pi 默认的 "Working... (Esc to interrupt)"。
  *   为了让耗时最显眼，接受这个 trade-off —— 用户更关心"等了多久"而非"怎么中断"。
@@ -18,14 +21,82 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { notifyWithSource } from "pi-extensions-i18n";
 import { formatDone, formatTick } from "./format-utils.ts";
 import { i18n } from "./i18n.ts";
+import { NOTICE_SOURCE } from "./notice.ts";
 
 const TICK_MS = 1000;
 
-export default function (pi: ExtensionAPI) {
-  let turnStartTime = 0;
+/** 至少跑满两轮才值得单独报一次总耗时；单轮的总耗时是噪声。 */
+const MIN_TURNS_FOR_TOTAL = 2;
+
+/** 计时状态：与 Pi 事件解耦，便于直接测试判定规则。 */
+export interface ElapsedTracker {
+  /** 用户发出消息（或没有 input 事件时的兜底）开始记一段运行；运行中重复调用不改起点。 */
+  startRun(): void;
+  /** 本段运行的已耗时（毫秒）；没有进行中的运行时返回 0。 */
+  runElapsed(): number;
+  /** 标记本轮已开始（只用计轮数，不再单独算本轮耗时）。 */
+  startTurn(): void;
+  /** 一轮结束：累计轮次并清掉本轮状态。 */
+  endTurn(): void;
+  /** AI 停下：跑满两轮时返回本段总耗时（毫秒），否则返回 undefined。 */
+  settle(): number | undefined;
+  /** 清掉本轮起点（agent_end 用）。 */
+  clearTurn(): void;
+}
+
+/** 造一个计时状态；now 可注入，便于测试确定性地推进时间。 */
+export function createElapsedTracker(now: () => number = () => Date.now()): ElapsedTracker {
+  /** 是否已开始一段运行；不用时间戳做哨兵，时钟可以从 0 开始。 */
+  let running = false;
+  /** 本段运行起点（毫秒）。 */
   let runStartTime = 0;
+  /** 当前轮是否已开始。 */
+  let inTurn = false;
+  /** 本段运行已跑完的轮数。 */
+  let turnCount = 0;
+  return {
+    /** 开始记一段运行；运行中重复调用不改起点。 */
+    startRun(): void {
+      if (running) return;
+      running = true;
+      runStartTime = now();
+      turnCount = 0;
+    },
+    /** 本段运行的已耗时（毫秒）；没有进行中的运行时返回 0。 */
+    runElapsed(): number {
+      return running ? now() - runStartTime : 0;
+    },
+    /** 标记本轮已开始（只用计轮数）。 */
+    startTurn(): void {
+      inTurn = true;
+    },
+    /** 一轮结束：累计轮次并清掉本轮状态。 */
+    endTurn(): void {
+      if (inTurn) turnCount += 1;
+      inTurn = false;
+    },
+    /** AI 停下：跑满两轮时返回本段总耗时（毫秒），否则返回 undefined。 */
+    settle(): number | undefined {
+      const elapsed = running ? now() - runStartTime : 0;
+      const turns = turnCount;
+      running = false;
+      inTurn = false;
+      runStartTime = 0;
+      turnCount = 0;
+      return elapsed > 0 && turns >= MIN_TURNS_FOR_TOTAL ? elapsed : undefined;
+    },
+    /** 清掉本轮状态（agent_end 用）。 */
+    clearTurn(): void {
+      inTurn = false;
+    },
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  const tracker = createElapsedTracker();
   let tickHandle: ReturnType<typeof setInterval> | null = null;
 
   const stopTick = () => {
@@ -37,28 +108,24 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("input", async (event) => {
     // 只在空闲时收到用户消息才记总耗时起点；运行中的 steer/followUp 保留原起点
-    if (runStartTime === 0 && (event.source === "interactive" || event.source === "rpc")) {
-      runStartTime = Date.now();
-    }
+    if (event.source === "interactive" || event.source === "rpc") tracker.startRun();
   });
 
   pi.on("agent_start", async () => {
     // 兜底：extension 注入消息触发的运行没有用户 input 事件
-    if (runStartTime === 0) runStartTime = Date.now();
+    tracker.startRun();
   });
 
-  pi.on("turn_start", async (event, ctx) => {
+  pi.on("turn_start", async (_event, ctx) => {
     stopTick();
-    // 优先用事件自带的时间戳，避免 handler 调度延迟
-    turnStartTime = event.timestamp || Date.now();
+    tracker.startTurn();
     if (!ctx.hasUI) return;
 
     const tick = () => {
-      // spinner 显示全程总耗时（从用户发出消息起），跨轮不归零；
-      // runStartTime 尚未记录时（理论上不会）退化为本轮起点
-      const base = runStartTime || turnStartTime;
-      if (!base) return;
-      ctx.ui.setWorkingMessage(i18n.t("elapsedWorking", { value: formatTick(Date.now() - base) }));
+      // spinner 显示全程总耗时（从用户发出消息起），跨轮不归零
+      const elapsed = tracker.runElapsed();
+      if (elapsed <= 0) return;
+      ctx.ui.setWorkingMessage(i18n.t("elapsedWorking", { value: formatTick(elapsed) }));
     };
     tick();
     tickHandle = setInterval(tick, TICK_MS);
@@ -66,34 +133,29 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("turn_end", async (_event, ctx) => {
     stopTick();
-    if (!turnStartTime) return;
-    const elapsed = Date.now() - turnStartTime;
-    turnStartTime = 0;
+    tracker.endTurn();
     if (!ctx.hasUI) return;
 
-    // 恢复 pi 默认 working 文字（下次 streaming 由 pi 内部重置）
+    // 恢复 pi 默认 working 文字（下次 streaming 由 pi 内部重置）；
+    // 本轮耗时由 tps 那条指标提示带上，不在这里重复发。
     ctx.ui.setWorkingMessage(undefined);
-    // 在 chat 流末尾插入一条 dim 灰文本
-    ctx.ui.notify(i18n.t("elapsedDone", { value: formatDone(elapsed) }), "info");
   });
 
   pi.on("agent_end", async (_event, ctx) => {
     stopTick();
-    turnStartTime = 0;
+    tracker.clearTurn();
     if (!ctx.hasUI) return;
     ctx.ui.setWorkingMessage(undefined);
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
     stopTick();
-    const runElapsed = runStartTime ? Date.now() - runStartTime : 0;
-    runStartTime = 0;
-    turnStartTime = 0;
+    const runElapsed = tracker.settle();
     if (!ctx.hasUI) return;
 
     ctx.ui.setWorkingMessage(undefined);
-    if (runElapsed > 0) {
-      ctx.ui.notify(i18n.t("elapsedTotal", { value: formatDone(runElapsed) }), "info");
+    if (runElapsed !== undefined) {
+      notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: i18n.t("elapsedTotal", { value: formatDone(runElapsed) }) });
     }
   });
 }