pi-metrics 0.7.1 → 0.8.0

package/README.md

@@ -11,7 +11,7 @@ Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi):
   - `on-stop` (default): the transcript stays quiet during the run. When the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), one summary line reports the total elapsed time, blended TPS, TTFT, summed in/out tokens, stalls, and blended cost.
   - `live`: one line per turn, right when the turn ends (the line already carries the turn duration, so no separate elapsed notice is emitted). A multi-turn run also gets a final `⏱ <duration>` line.
 - Telemetry for every turn is persisted as `tps` custom session entries in both modes, 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 `/config:metrics enable|disable|live|on-stop|reset` to change a setting directly.
+- Metrics are exposed through session entries and notifications. Use `/config:metrics` to open the TUI settings panel, or `/config:metrics enable|disable|live|on-stop|reset` to change a setting directly.
 
 ## Configuration
 
@@ -29,7 +29,7 @@ The configuration file is `<pi-agent-dir>/extensions/pi-metrics/config.json`:
 | `enabled` | `true` / `false` | `true` | Master switch. `false` registers no metric handlers at all. |
 | `display` | `"on-stop"` / `"live"` | `"on-stop"` | When metric lines appear: one summary line after the run stops, or one line per turn. |
 
-Use `/config:metrics` for the interactive menu (each selection is saved and the menu reopens until you pick **Done**), or the direct form to change one field. Run `/reload` after editing the file by hand.
+Use `/config:metrics` for the settings panel (Enter toggles the master switch in place and opens a picker for the display timing; every change is saved and applied immediately, so no `/reload` is needed), or the direct form to change one field. Run `/reload` after editing the file by hand.
 
 ## How the summary line is computed
 

package/README.zh-CN.md

@@ -11,7 +11,7 @@
   - `on-stop`（默认）：运行过程中对话区保持干净；AI 完全停止（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）后只出一行汇总：总耗时、混合 TPS、TTFT、in/out 合计、stall 和综合费率。
   - `live`：每轮结束时立刻出一行（该行已包含本轮耗时，不再单独发耗时提示）；整段超过一轮时再补一行 `⏱ <耗时>`。
 - 两种模式都会把每轮遥测写进 `tps` custom session entry，恢复 session 或 `/tree` 后照常恢复显示。
-- Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置菜单，或用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。
+- Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置面板，或用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。
 
 ## 配置
 
@@ -29,7 +29,7 @@
 | `enabled` | `true` / `false` | `true` | 总开关；`false` 时完全不注册指标处理器。 |
 | `display` | `"on-stop"` / `"live"` | `"on-stop"` | 指标行何时出现：整段停下后汇总一行，还是每轮一行。 |
 
-用 `/config:metrics` 打开交互菜单（每次选择都会保存并重新打开菜单，选「完成」退出），或用带参数的形式改单个字段；手动修改文件后执行 `/reload`。可参考 [`config.example.json`](./config.example.json)。
+用 `/config:metrics` 打开配置面板（总开关回车切换，显示时机回车选；每改一项立即写盘并生效，不需要 `/reload`），或用带参数的形式改单个字段；手动修改文件后执行 `/reload`。可参考 [`config.example.json`](./config.example.json)。
 
 ## 汇总行是怎么算的
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: "启用与排查 pi-metrics 的耗时、TPS、TTFT、token 和成
 
 # 配置 pi-metrics
 
-配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`，字段有 `enabled`（默认 `true`）和 `display`（`"on-stop"` 默认 / `"live"`）。可以使用 `/config:metrics` 打开 TUI 菜单（每次选择都会保存并重新打开，选「完成」退出），或用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。手动修改配置文件后执行 `/reload`。
+配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`，字段有 `enabled`（默认 `true`）和 `display`（`"on-stop"` 默认 / `"live"`）。使用 `/config:metrics` 打开 TUI 配置面板：总开关回车原地切换，显示时机回车打开二级列表；每改一项立即写盘并生效，不需要 `/reload`。也可用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。手动修改配置文件后执行 `/reload`。
 
 `display` 决定指标行何时出现：`on-stop` 只在整段运行停下后出一行汇总（总耗时 · 混合 TPS · TTFT · in/out · stall · 费率），`live` 每轮结束就出一行。spinner 上的实时耗时两种模式都有。
 

package/locales/index.json

@@ -47,17 +47,21 @@
     "zh-CN": "指标配置",
     "en-US": "Metrics settings"
   },
-  "configEnabled": {
-    "zh-CN": "启用指标：{value}",
-    "en-US": "Metrics enabled: {value}"
+  "configLabelEnabled": {
+    "zh-CN": "启用指标",
+    "en-US": "Enable metrics"
   },
-  "configDisabled": {
-    "zh-CN": "禁用指标：{value}",
-    "en-US": "Metrics disabled: {value}"
+  "configLabelDisplay": {
+    "zh-CN": "显示时机",
+    "en-US": "Display timing"
   },
-  "configDisplay": {
-    "zh-CN": "显示时机：{value}",
-    "en-US": "Display: {value}"
+  "configDescEnabled": {
+    "zh-CN": "关闭后不注册任何指标处理器",
+    "en-US": "Turn off to register no metric handlers"
+  },
+  "configDescDisplay": {
+    "zh-CN": "每轮实时一行，或停下后只汇总一行",
+    "en-US": "One line per turn, or a single summary line when stopped"
   },
   "configDisplayLive": {
     "zh-CN": "每轮实时一行",
@@ -75,17 +79,13 @@
     "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."
+    "zh-CN": "指标配置已保存：{path}。",
+    "en-US": "Metrics configuration saved to {path}."
   },
   "configCommandInvalid": {
     "zh-CN": "指标配置无效：{error}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-metrics",
-  "version": "0.7.1",
+  "version": "0.8.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.8.0"
+    "pi-extensions-i18n": "^0.9.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.85.1",

package/src/config-panel.ts

@@ -0,0 +1,252 @@
+/**
+ * pi-metrics 的 TUI 配置面板。
+ *
+ * 原来用 `ctx.ui.select` 链式菜单：每选一项都要重新弹一轮菜单，屏幕上既看不出哪个是
+ * 状态、哪个是按钮。这里改用 Pi 自带 `SettingsList`：左边字段名、右边当前值，选中项
+ * 下方给一行说明。开关回车原地切换，枚举回车打开二级列表。
+ *
+ * 改动即时生效：面板每次读配置都走 `getConfig()`（入口注入的读取函数），写完由入口
+ * 保存并立刻按新配置重装指标处理器，关掉面板不用 /reload。
+ */
+
+import {
+  getSelectListTheme,
+  getSettingsListTheme,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  SelectList,
+  SettingsList,
+  Text,
+  type Component,
+  type SelectItem,
+  type SettingItem,
+} from "@earendil-works/pi-tui";
+import { parseConfig, type MetricsConfig, type MetricsDisplay } from "./config.ts";
+import { i18n } from "./i18n.ts";
+
+/** 面板上的一项取值方式：开关原地切换，枚举回车开二级列表。 */
+const PANEL_KIND = {
+  /** 开关：Enter/空格在开与关之间切换。 */
+  toggle: "toggle",
+  /** 枚举：Enter 打开二级选择列表。 */
+  choice: "choice",
+} as const;
+
+/** 面板项定义。 */
+interface PanelItemSpec {
+  /** 配置字段名。 */
+  id: PanelFieldId;
+  /** 取值方式。 */
+  kind: (typeof PANEL_KIND)[keyof typeof PANEL_KIND];
+  /** 行标题的文案 key。 */
+  labelKey: string;
+  /** 说明行的文案 key。 */
+  descriptionKey: string;
+}
+
+/** 面板覆盖的配置字段名。 */
+export type PanelFieldId = "enabled" | "display";
+
+/** 显示时机的候选值。 */
+const DISPLAY_VALUES: readonly MetricsDisplay[] = ["on-stop", "live"];
+
+/** 显示时机取值到文案 key 的映射。 */
+const DISPLAY_LABEL_KEYS: Record<MetricsDisplay, string> = {
+  "on-stop": "configDisplayOnStop",
+  live: "configDisplayLive",
+};
+
+/** 二级列表最多同时显示几行。 */
+const CHOICE_MENU_MAX_VISIBLE = 8;
+
+/** 配置里存的开关值，避免把本地化文案写回配置。 */
+const TOGGLE_ON = "on";
+const TOGGLE_OFF = "off";
+
+/** 面板项顺序：先总开关，再显示时机。 */
+const PANEL_ITEMS: readonly PanelItemSpec[] = [
+  {
+    id: "enabled",
+    kind: PANEL_KIND.toggle,
+    labelKey: "configLabelEnabled",
+    descriptionKey: "configDescEnabled",
+  },
+  {
+    id: "display",
+    kind: PANEL_KIND.choice,
+    labelKey: "configLabelDisplay",
+    descriptionKey: "configDescDisplay",
+  },
+];
+
+/** 面板覆盖的配置字段名，测试用它核对没有字段漏在面板外。 */
+export const CONFIG_PANEL_IDS: readonly string[] = PANEL_ITEMS.map((item) => item.id);
+
+/** 二级列表的一项：label 是展示文本，value 是写回配置的值。 */
+export interface PanelOption {
+  /** 展示文本。 */
+  label: string;
+  /** 写回配置的值。 */
+  value: string;
+}
+
+/** 取本地化后的开关文案。 */
+function toggleLabels(): { on: string; off: string } {
+  return { on: i18n.t("configOn"), off: i18n.t("configOff") };
+}
+
+/** 开关的候选项。 */
+function toggleOptions(): PanelOption[] {
+  const labels = toggleLabels();
+  return [
+    { label: labels.on, value: TOGGLE_ON },
+    { label: labels.off, value: TOGGLE_OFF },
+  ];
+}
+
+/** 显示时机的候选项。 */
+function displayOptions(): PanelOption[] {
+  return DISPLAY_VALUES.map((value) => ({ label: i18n.t(DISPLAY_LABEL_KEYS[value]), value }));
+}
+
+/** 按字段取候选项。 */
+function fieldOptions(id: PanelFieldId): PanelOption[] {
+  return id === "enabled" ? toggleOptions() : displayOptions();
+}
+
+/** 按配置值取展示文本；不在候选表里就直接显示原值。 */
+export function optionLabelForValue(options: readonly PanelOption[], value: string): string {
+  return options.find((option) => option.value === value)?.label ?? value;
+}
+
+/** 按展示文本反查写回值；找不到说明候选表变了，返回 undefined。 */
+export function optionValueFromLabel(
+  options: readonly PanelOption[],
+  label: string,
+): string | undefined {
+  return options.find((option) => option.label === label)?.value;
+}
+
+/**
+ * 二级选择列表：Enter 选定并回传展示文本，Esc 不改动直接返回。
+ *
+ * 列表项的 value 与 label 取同一段文本：SettingsList 会把回传值直接显示在右侧，
+ * 回传展示文本才能让「每轮实时一行」这类文案在选中后仍然可读。
+ */
+function createChoiceSubmenu(
+  options: readonly PanelOption[],
+  currentLabel: string,
+  done: (selectedLabel?: string) => void,
+): Component {
+  /** 建一份列表快照，能对上当前值就预选中它。 */
+  const buildList = (list: readonly PanelOption[]): SelectList => {
+    const items: SelectItem[] = list.map((option) => ({ value: option.label, label: option.label }));
+    const selectList = new SelectList(
+      items,
+      Math.max(1, Math.min(items.length, CHOICE_MENU_MAX_VISIBLE)),
+      getSelectListTheme(),
+    );
+    const currentIndex = list.findIndex((option) => option.label === currentLabel);
+    if (currentIndex >= 0) selectList.setSelectedIndex(currentIndex);
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(undefined);
+    return selectList;
+  };
+  return buildList(options);
+}
+
+/** 把当前配置转成 Pi 设置列表的条目。 */
+export function toSettingItems(config: MetricsConfig): SettingItem[] {
+  const labels = toggleLabels();
+  return PANEL_ITEMS.map((item) => {
+    const label = i18n.t(item.labelKey);
+    const description = i18n.t(item.descriptionKey);
+    const options = fieldOptions(item.id);
+    if (item.kind === PANEL_KIND.toggle) {
+      return {
+        id: item.id,
+        label,
+        description,
+        currentValue: config.enabled ? labels.on : labels.off,
+        values: [labels.on, labels.off],
+      };
+    }
+    return {
+      id: item.id,
+      label,
+      description,
+      currentValue: optionLabelForValue(options, config.display),
+      // 二级列表接管 Enter，避免在枚举值之间反复循环而不显示候选。
+      submenu: (currentLabel: string, done) => createChoiceSubmenu(options, currentLabel, done),
+    };
+  });
+}
+
+/**
+ * 把面板返回的展示文本写回配置；无法识别时返回 undefined，由调用方保持不变。
+ *
+ * 结果统一过一遍 parseConfig，保证写盘的值仍在校验规则允许的范围内。
+ */
+export function applyPanelChange(
+  config: MetricsConfig,
+  id: string,
+  value: string,
+): MetricsConfig | undefined {
+  if (id === "enabled") {
+    const labels = toggleLabels();
+    if (value !== labels.on && value !== labels.off) return undefined;
+    return parseConfig({ ...config, enabled: value === labels.on });
+  }
+  if (id === "display") {
+    const stored = optionValueFromLabel(displayOptions(), value);
+    return stored === undefined ? undefined : parseConfig({ ...config, display: stored });
+  }
+  return undefined;
+}
+
+/** 面板与宿主之间的接口；配置读写与实时生效都由入口注入。 */
+export interface ConfigPanelHandlers {
+  /** 读取当前配置。 */
+  getConfig(): MetricsConfig;
+  /** 某一项被改动后调用，由入口负责保存并按新配置重装指标处理器。 */
+  onChange(config: MetricsConfig): void;
+}
+
+/** 打开配置面板；改动即时生效，Esc 关闭。 */
+export async function openConfigPanel(
+  ctx: ExtensionCommandContext,
+  handlers: ConfigPanelHandlers,
+): Promise<void> {
+  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+    const container = new Container();
+    container.addChild(new Text(theme.fg("accent", theme.bold(i18n.t("configMenuTitle"))), 1, 1));
+
+    const settingsList = new SettingsList(
+      toSettingItems(handlers.getConfig()),
+      PANEL_ITEMS.length,
+      getSettingsListTheme(),
+      (id, newValue) => {
+        const next = applyPanelChange(handlers.getConfig(), id, newValue);
+        if (next) handlers.onChange(next);
+      },
+      () => done(undefined),
+    );
+    container.addChild(settingsList);
+
+    // ctx.ui.custom 要求返回 Component：布局交给 Container，键盘转给设置列表，
+    // 列表改了数据后必须 requestRender，否则画面停在上一帧。
+    return {
+      /** 面板整体按 Container 布局渲染。 */
+      render: (width) => container.render(width),
+      /** 无本地缓存，交给 Container 清理。 */
+      invalidate: () => container.invalidate(),
+      /** 键盘输入交给设置列表，并触发一次重绘。 */
+      handleInput: (data) => {
+        settingsList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource } from "pi-extensions-i18n";
+import { openConfigPanel } from "./config-panel.ts";
 import { NOTICE_SOURCE } from "./notice.ts";
 import turnElapsed, { createElapsedTracker } from "./turn-elapsed.ts";
 import tps from "./tps.ts";
@@ -13,7 +14,6 @@ import {
   loadConfig,
   saveConfig,
   type MetricsConfig,
-  type MetricsDisplay,
 } from "./config.ts";
 
 const messages = loadCatalog(new URL("../locales/index.json", import.meta.url));
@@ -27,10 +27,6 @@ const DISPLAY_ON_STOP_COMMAND = "on-stop";
 const NOTICE_WARNING = "warning" as const;
 const NOTICE_INFO = "info" as const;
 const NOTICE_ERROR = "error" as const;
-const DISPLAY_FLIP: Record<MetricsDisplay, MetricsDisplay> = {
-  [DISPLAY_LIVE_COMMAND]: DISPLAY_ON_STOP_COMMAND,
-  [DISPLAY_ON_STOP_COMMAND]: DISPLAY_LIVE_COMMAND,
-};
 
 /** 命令参数到配置片段的映射：直接改配置时要覆盖的字段。 */
 const COMMAND_CONFIG_PATCH: ReadonlyMap<string, Partial<MetricsConfig>> = new Map([
@@ -40,11 +36,6 @@ const COMMAND_CONFIG_PATCH: ReadonlyMap<string, Partial<MetricsConfig>> = new Ma
   [DISPLAY_ON_STOP_COMMAND, { display: "on-stop" }],
 ]);
 
-/** 配置值对应的菜单文案。 */
-function displayLabel(display: MetricsDisplay): string {
-  return i18n.t(display === "on-stop" ? "configDisplayOnStop" : "configDisplayLive");
-}
-
 /** 保存配置并提示结果；写盘失败时只提示不抛出，返回是否成功。 */
 function persistConfig(ctx: ExtensionCommandContext, config: MetricsConfig): boolean {
   try {
@@ -77,25 +68,6 @@ function reportConfigError(ctx: ExtensionCommandContext, error: unknown): false
   return false;
 }
 
-/**
- * 弹出配置菜单，返回用户改动后的配置。
- * 只调用 TUI 选择，不写盘：选择「完成」或按 Esc 时返回 null，由调用方结束编辑；
- * 返回的配置还需要调用方自己落盘。
- */
-async function promptConfigChange(
-  ctx: ExtensionCommandContext,
-  current: MetricsConfig,
-): Promise<MetricsConfig | null> {
-  const enabledChoice = i18n.t("configEnabled", { value: i18n.t(current.enabled ? "configOn" : "configOff") });
-  const displayChoice = i18n.t("configDisplay", { value: displayLabel(current.display) });
-  const doneChoice = i18n.t("configDone");
-  const selected = await ctx.ui.select(i18n.t("configMenuTitle"), [enabledChoice, displayChoice, doneChoice]);
-  if (selected === undefined || selected === doneChoice) return null;
-  return selected === enabledChoice
-    ? { ...current, enabled: !current.enabled }
-    : { ...current, display: DISPLAY_FLIP[current.display] };
-}
-
 /** 取命令参数对应的配置补丁；`reset` 用整份默认配置覆盖当前值，未知参数返回 null。 */
 function configPatchFor(value: string): Partial<MetricsConfig> | null {
   if (value === CONFIG_RESET_COMMAND) return { ...DEFAULT_METRICS_CONFIG };
@@ -105,25 +77,30 @@ function configPatchFor(value: string): Partial<MetricsConfig> | null {
 /**
  * 应用直接参数形式的配置命令：读当前配置、叠加一个补丁后写回。
  * 未知参数只提示用法；写盘失败由 persistConfig 自己提示，本函数不抛出。
+ * 返回生效后的配置，参数无效或写盘失败时返回 null，调用方据此决定是否重装处理器。
  */
-function applyCommandSetting(value: string, ctx: ExtensionCommandContext): void {
+function applyCommandSetting(value: string, ctx: ExtensionCommandContext): MetricsConfig | null {
   const patch = configPatchFor(value);
   if (patch === null) {
     notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandUsage") });
-    return;
+    return null;
   }
   let current: MetricsConfig;
   try {
     current = loadConfig();
   } catch (error) {
     reportConfigError(ctx, error);
-    return;
+    return null;
   }
-  persistConfig(ctx, { ...current, ...patch });
+  const next = { ...current, ...patch };
+  return persistConfig(ctx, next) ? next : null;
 }
 
-/** 注册配置命令，通过 TUI 循环编辑，或直接用参数改一项。 */
-function registerConfigCommand(pi: ExtensionAPI): void {
+/** 注册配置命令：不带参数打开面板，带参数时直接改一项。 */
+function registerConfigCommand(
+  pi: ExtensionAPI,
+  applyConfig: (config: MetricsConfig) => void,
+): void {
   const command = {
     description: i18n.t("configCommandDescription"),
     /** Completes the supported direct settings. */
@@ -135,32 +112,33 @@ function registerConfigCommand(pi: ExtensionAPI): void {
       { value: DISPLAY_ON_STOP_COMMAND, label: DISPLAY_ON_STOP_COMMAND },
     ],
     /**
-     * 处理命令：带参数时直改一项，不带参数时进入 TUI 菜单循环；
-     * 写盘和提示都是副作用，配置改动需要 /reload 才生效。
+     * 处理命令：带参数时直改一项，不带参数时打开配置面板。
+     * 两种路径都在写盘后立刻把新配置应用到当前会话，不需要 /reload。
      */
     handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
       const value = args.trim();
       if (value) {
-        applyCommandSetting(value, ctx);
+        const next = applyCommandSetting(value, ctx);
+        if (next) applyConfig(next);
         return;
       }
       if (!ctx.hasUI) {
         notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandInteractiveOnly") });
         return;
       }
-      let current: MetricsConfig;
       try {
-        current = loadConfig();
+        loadConfig();
       } catch (error) {
         reportConfigError(ctx, error);
         return;
       }
-      // 每选一项就落盘并重新打开菜单，直到用户选「完成」或按 Esc。
-      for (;;) {
-        const next = await promptConfigChange(ctx, current);
-        if (next === null) return;
-        if (persistConfig(ctx, next)) current = next;
-      }
+      // 面板每改一项就落盘并立刻生效；Esc 关闭面板后结束。
+      await openConfigPanel(ctx, {
+        getConfig: loadConfig,
+        onChange: (config) => {
+          if (persistConfig(ctx, config)) applyConfig(config);
+        },
+      });
     },
   };
   for (const name of CONFIG_COMMAND_ALIASES) pi.registerCommand(name, command);
@@ -170,14 +148,34 @@ function registerConfigCommand(pi: ExtensionAPI): void {
 export default function piHud(pi: ExtensionAPI): void {
   // 提示画成会话区里的带底色消息块；渲染器在本包这个模块实例里注册一次。
   installNoticeRenderer(pi);
-  registerConfigCommand(pi);
-  let config: MetricsConfig;
+
+  /** 已停用的指标处理器；重装前先解引用，让旧闭包可回收。 */
+  let disposeHandlers: (() => void) | undefined;
+
+  /**
+   * 按一份配置重装指标处理器。
+   * 关闭时只解掉旧闭包，因此面板里关掉开关立即不再注册新处理器，打开开关立即恢复，
+   * 不需要 /reload（原来只在扩展加载时读一次配置，改了要重启会话）。
+   */
+  const applyConfig = (next: MetricsConfig): void => {
+    disposeHandlers?.();
+    disposeHandlers = undefined;
+    if (!next.enabled) return;
+    // 两个模块共用同一个运行时钟：on-stop 汇总行里的整段耗时和 spinner 显示的是同一段。
+    const tracker = createElapsedTracker();
+    // 两个模块的注册函数都返回 void：Pi 在 /reload 时按模块清掉监听，这里只解引用。
+    turnElapsed(pi, { tracker, display: next.display });
+    tps(pi, { tracker, display: next.display });
+  };
+
+  registerConfigCommand(pi, applyConfig);
+
   let configError: unknown;
   try {
-    config = loadConfig();
+    applyConfig(loadConfig());
   } catch (error) {
-    config = { ...DEFAULT_METRICS_CONFIG };
     configError = error;
+    applyConfig({ ...DEFAULT_METRICS_CONFIG });
   }
   if (configError !== undefined) {
     pi.on("session_start", (_event, ctx: ExtensionContext) => {
@@ -192,17 +190,13 @@ export default function piHud(pi: ExtensionAPI): void {
       });
     });
   }
-  if (!config.enabled) return;
-  // 两个模块共用同一个运行时钟：on-stop 汇总行里的整段耗时和 spinner 显示的是同一段。
-  const tracker = createElapsedTracker();
-  turnElapsed(pi, { tracker, display: config.display });
-  tps(pi, { tracker, display: config.display });
 }
 
 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 "./config-panel.ts";
 export * from "./format-utils.ts";
 export * from "./run-summary.ts";
 export * from "./tps.ts";