pi-metrics 0.3.0 → 0.4.0

package/README.md

@@ -11,9 +11,19 @@ Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi):
 - 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`).
 - 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; this package does not register export slash commands.
+- 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.
 
-## Migration from pi-tps
+## Configuration
+
+The configuration file is `<pi-agent-dir>/extensions/pi-metrics/config.json`:
+
+```json
+{
+  "enabled": true
+}
+```
+
+Use `/config:metrics enable` or `/config:metrics disable` to update it, or open the normal TUI menu with `/config:metrics`. Run `/reload` after manually editing the file.
 
 The TPS implementation is maintained in this package. Remove the standalone `npm:@monotykamary/pi-tps` entry from Pi settings before enabling this package, otherwise both extensions will record duplicate `tps` entries and notifications.
 

package/README.zh-CN.md

@@ -11,7 +11,19 @@
 - AI 完全停止时（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）追加一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）。
 - 每轮 LLM 调用结束后显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本。
 - Telemetry 以 `tps` custom session entry 持久化，并在恢复 session 或 `/tree` 后恢复显示。
-- Metrics 通过 session entry 和通知提供；本包不再注册导出类斜杠命令。
+- Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置菜单，也可以使用 `/config:metrics enable|disable` 直接切换。
+
+## 配置
+
+配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`：
+
+```json
+{
+  "enabled": true
+}
+```
+
+使用 `/config:metrics enable` 或 `/config:metrics disable` 修改配置，也可以使用 `/config:metrics` 打开常规 TUI 菜单；手动修改文件后执行 `/reload`。可参考 [`config.example.json`](./config.example.json)。
 
 ## 从 pi-tps 迁移
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: "启用与排查 pi-metrics 的耗时、TPS、TTFT、token 和成
 
 # 配置 pi-metrics
 
-`pi-metrics` 当前没有配置文件或配置命令；不要编造开关、阈值或导出命令。配置动作仅限安装、启用或禁用该 package，以及共享语言设置。
+配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`，字段只有 `enabled`，默认是 `true`。可以使用 `/config:metrics` 打开 TUI 菜单，或使用 `/config:metrics enable|disable` 直接修改并持久化。手动修改配置文件后执行 `/reload`。
 
 ## 诊断与修改
 

package/locales/index.json

@@ -38,5 +38,53 @@
   "tpsRate": {
     "zh-CN": "${value}/M",
     "en-US": "${value}/M"
+  },
+  "configCommandDescription": {
+    "zh-CN": "配置指标显示",
+    "en-US": "Configure metrics display"
+  },
+  "configCommandUsage": {
+    "zh-CN": "用法：/config:metrics（打开配置菜单）、enable、disable 或 reset",
+    "en-US": "Usage: /config:metrics (open settings), enable, disable, or reset"
+  },
+  "configMenuTitle": {
+    "zh-CN": "指标配置",
+    "en-US": "Metrics settings"
+  },
+  "configEnabled": {
+    "zh-CN": "启用指标：{value}",
+    "en-US": "Metrics enabled: {value}"
+  },
+  "configDisabled": {
+    "zh-CN": "禁用指标：{value}",
+    "en-US": "Metrics disabled: {value}"
+  },
+  "configOn": {
+    "zh-CN": "开",
+    "en-US": "on"
+  },
+  "configOff": {
+    "zh-CN": "关",
+    "en-US": "off"
+  },
+  "configDone": {
+    "zh-CN": "完成",
+    "en-US": "Done"
+  },
+  "configCommandInteractiveOnly": {
+    "zh-CN": "指标配置需要在 TUI 中修改；请在交互式 Pi 会话中执行命令。",
+    "en-US": "Metrics configuration requires the TUI; run this command in an interactive Pi session."
+  },
+  "configCommandSaved": {
+    "zh-CN": "指标配置已保存：{path}。请执行 /reload 使配置生效。",
+    "en-US": "Metrics configuration saved to {path}. Run /reload to apply it."
+  },
+  "configCommandInvalid": {
+    "zh-CN": "指标配置无效：{error}",
+    "en-US": "Invalid metrics configuration: {error}"
+  },
+  "configLoadFailed": {
+    "zh-CN": "指标配置读取失败：{path}（{error}）。当前继续启用指标。",
+    "en-US": "Failed to read metrics configuration: {path} ({error}). Metrics remain enabled."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-metrics",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pi metrics extension: elapsed-time HUD and resilient TPS telemetry",
   "type": "module",
   "main": "./index.ts",

package/src/config.ts

@@ -0,0 +1,52 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const EXTENSIONS_DIRECTORY = "extensions";
+const PACKAGE_NAME = "pi-metrics";
+const CONFIG_FILE_NAME = "config.json";
+const UTF8_ENCODING = "utf8";
+const FILE_NOT_FOUND_CODE = "ENOENT";
+
+export interface MetricsConfig {
+  enabled: boolean;
+}
+
+export const DEFAULT_METRICS_CONFIG: MetricsConfig = { enabled: true };
+
+/** 返回 pi-metrics 配置文件路径。 */
+export function configPath(agentDir = getAgentDir()): string {
+  return join(agentDir, EXTENSIONS_DIRECTORY, PACKAGE_NAME, CONFIG_FILE_NAME);
+}
+
+/** 解析并校验 pi-metrics 配置。 */
+export function parseConfig(value: unknown): MetricsConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("configuration must be an object");
+  }
+  const raw = value as Record<string, unknown>;
+  for (const key of Object.keys(raw)) {
+    if (key !== "enabled") throw new Error(`unknown configuration field: ${key}`);
+  }
+  if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") {
+    throw new Error("enabled must be a boolean");
+  }
+  return { enabled: (raw.enabled as boolean | undefined) ?? DEFAULT_METRICS_CONFIG.enabled };
+}
+
+/** 读取配置文件；缺少文件时使用默认启用状态。 */
+export function loadConfig(path = configPath()): MetricsConfig {
+  try {
+    return parseConfig(JSON.parse(readFileSync(path, UTF8_ENCODING)));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === FILE_NOT_FOUND_CODE) return { ...DEFAULT_METRICS_CONFIG };
+    throw error;
+  }
+}
+
+/** 将经过校验的配置写入配置文件。 */
+export function saveConfig(config: MetricsConfig, path = configPath()): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, UTF8_ENCODING);
+  return path;
+}

package/src/index.ts

@@ -1,12 +1,111 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
 import turnElapsed from "./turn-elapsed.ts";
 import tps from "./tps.ts";
+import { configPath, loadConfig, parseConfig, saveConfig, type MetricsConfig } from "./config.ts";
 
+const messages = loadCatalog(new URL("../locales/index.json", import.meta.url));
+const i18n = createTranslator(messages);
+const CONFIG_COMMAND_ALIASES = ["config:metrics", "metrics-config", "pi-metrics-config"] as const;
+const CONFIG_RESET_COMMAND = "reset";
+const CONFIG_CHOICE = { enabled: 0, disabled: 1 } as const;
+const ENABLE_COMMAND = "enable";
+const DISABLE_COMMAND = "disable";
+const NOTICE_WARNING = "warning" as const;
+const NOTICE_INFO = "info" as const;
+const NOTICE_ERROR = "error" as const;
+
+/** 注册配置命令，通过 TUI 选择是否启用指标。 */
+function registerConfigCommand(pi: ExtensionAPI): void {
+  const command = {
+    description: i18n.t("configCommandDescription"),
+    /** Completes the supported reset action. */
+    getArgumentCompletions: () => [{ value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND }],
+    /** Selects and persists the enabled state. */
+    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);
+        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);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), NOTICE_ERROR);
+        }
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("configCommandInteractiveOnly"), NOTICE_WARNING);
+        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);
+        return;
+      }
+      const enabledChoice = i18n.t("configEnabled", { value: i18n.t(current.enabled ? "configOn" : "configOff") });
+      const disabledChoice = i18n.t("configDisabled", { value: i18n.t(current.enabled ? "configOff" : "configOn") });
+      const doneChoice = i18n.t("configDone");
+      const selected = await ctx.ui.select(i18n.t("configMenuTitle"), [
+        enabledChoice,
+        disabledChoice,
+        doneChoice,
+      ]);
+      if (selected === undefined || selected === doneChoice) return;
+      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);
+      } catch (error) {
+        ctx.ui.notify(i18n.t("configCommandInvalid", {
+          error: error instanceof Error ? error.message : String(error),
+        }), NOTICE_ERROR);
+      }
+    },
+  };
+  for (const name of CONFIG_COMMAND_ALIASES) pi.registerCommand(name, command);
+}
+
+/** 注册耗时和 TPS 指标事件；配置关闭时不注册指标处理器。 */
 export default function piHud(pi: ExtensionAPI): void {
+  registerConfigCommand(pi);
+  let config: MetricsConfig;
+  let configError: unknown;
+  try {
+    config = loadConfig();
+  } catch (error) {
+    config = { enabled: true };
+    configError = error;
+  }
+  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);
+    });
+  }
+  if (!config.enabled) return;
   turnElapsed(pi);
   tps(pi);
 }
 
+export { configPath, loadConfig, parseConfig, saveConfig } from "./config.ts";
+export type { MetricsConfig } from "./config.ts";
 export { default as turnElapsed } from "./turn-elapsed.ts";
 export { default as tps } from "./tps.ts";
 export * from "./format-utils.ts";