pi-models-discovery 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-models-discovery
 
-Generic model discovery extension: reads providers marked with `"discoverModels": true` in `~/.pi/agent/models.json`, requests `GET {baseUrl}/models`, and registers the discovered models automatically — no handwritten `models` array required. After the first successful discovery the model list is persisted to a local cache, so subsequent startups read the cache and **perform no network requests**.
+Generic model discovery extension: reads providers marked with `"discoverModels": true` in `~/.pi/agent/models.json`, requests `GET {baseUrl}/models` (or a configured `modelsUrl`), and registers the discovered models automatically — no handwritten `models` array required. After the first successful discovery the model list is persisted to a local cache, so subsequent startups read the cache and **perform no network requests**.
 
 Suitable for local/self-hosted LLM proxies (one gateway exposing many models), Ollama, vLLM, and other OpenAI-compatible services.
 
@@ -18,7 +18,7 @@ pi install npm:pi-models-discovery
 /config:model-discovery
 ```
 
-Interactively add / remove / rediscover providers: enter id, baseUrl, api type, apiKey (optional), display name (optional). Changes are written to models.json and take effect **immediately** (no /reload required). A backup is written to `models.json.discovery-bak` before each write.
+Interactively add / remove / rediscover providers. The command opens a settings panel that lists every provider marked with `discoverModels`; selecting one opens its fields (enable/disable discovery, baseUrl, api type, apiKey, display name) plus actions to rediscover or remove it. Adding a provider asks for id, baseUrl, api type, apiKey (optional) and display name (optional). Changes are written to models.json and take effect **immediately** (no /reload required). A backup is written to `models.json.discovery-bak` before each write.
 
 Note: comments and custom formatting in models.json are not preserved on write (the file is reformatted with 4-space indentation).
 
@@ -40,7 +40,25 @@ Add `"discoverModels": true` to a provider in `~/.pi/agent/models.json`:
 }
 ```
 
-`baseUrl` and `api` are required; `apiKey` is optional (omit for unauthenticated services). Multiple providers sharing the same `baseUrl+apiKey` reuse a single `/models` request.
+`baseUrl` and `api` are required; `apiKey` is optional (omit for unauthenticated services). Multiple providers sharing the same model-list URL, `apiKey`, `headers`, and `compat` reuse a single discovery request.
+
+If the model catalog uses a different endpoint, set the optional `modelsUrl` in models.json to its **complete URL** (including the path and any query parameters):
+
+```json
+{
+  "providers": {
+    "foo": {
+      "baseUrl": "https://api.example.com/v1",
+      "modelsUrl": "https://catalog.example.com/v1/models",
+      "apiKey": "$FOO_API_KEY",
+      "api": "openai-completions",
+      "discoverModels": true
+    }
+  }
+}
+```
+
+`modelsUrl` is used as-is for discovery and refresh only; chat requests still use `baseUrl`. When omitted or empty, discovery uses `{baseUrl}/models`. Discovery sends the provider's existing `apiKey` and `headers` to this URL, so use a trusted endpoint. The response format remains unchanged.
 
 Hand edits require `/reload` to take effect; changes made through `/config:model-discovery` apply immediately.
 
@@ -54,7 +72,7 @@ Forces a rediscovery of every discovery provider and updates the local cache, no
 
 ## Behavior
 
-- **Startup (cache-first)**: when the cache hits, models are registered directly from the persisted list with zero network requests. The cache lives at `~/.pi/agent/extensions/pi-models-discovery/cache.json`. The cache is invalidated automatically when the provider configuration fingerprint (baseUrl+api+apiKey+headers+compat) changes, triggering a fresh network discovery.
+- **Startup (cache-first)**: when the cache hits, models are registered directly from the persisted list with zero network requests. The cache lives at `~/.pi/agent/extensions/pi-models-discovery/cache.json`. The cache is invalidated automatically when the provider configuration fingerprint (baseUrl+api+apiKey+headers+compat+modelsUrl) changes, triggering a fresh network discovery.
 - **Online refresh**: `/config:model-discovery-refresh`, or the `refreshModels` hook triggered when opening `/model`, rediscovers online and updates the cache.
 - **Offline / fetch failure**: handwritten `models` in models.json (if any) are kept as a fallback, and an explicit warning is surfaced via in-session notify — never a silent degradation. One provider failing does not affect the others.
 - **apiKey resolution** (discovery request only): supports literals and `$ENV_VAR` / `${ENV_VAR}` interpolation; `!command` values skip discovery with an explicit warning (chat requests are still resolved by pi itself and are unaffected).

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # pi-models-discovery
 
-通用模型发现插件：读取 `~/.pi/agent/models.json` 中带 `"discoverModels": true` 的 provider，请求 `GET {baseUrl}/models` 自动发现模型并注册，无需手写 `models` 数组。首次发现成功后模型列表持久化到本地缓存，之后每次启动直接读缓存，**不再请求网络**。
+通用模型发现插件：读取 `~/.pi/agent/models.json` 中带 `"discoverModels": true` 的 provider，请求 `GET {baseUrl}/models`（或配置的 `modelsUrl`）自动发现模型并注册，无需手写 `models` 数组。首次发现成功后模型列表持久化到本地缓存，之后每次启动直接读缓存，**不再请求网络**。
 
 适合本地/自建 LLM 代理（一个网关暴露多个模型）、Ollama、vLLM 等 OpenAI 兼容服务。
 
@@ -18,7 +18,7 @@ pi install npm:pi-models-discovery
 /config:model-discovery
 ```
 
-交互式添加 / 删除 / 重新发现 provider：输入 id、baseUrl、api 类型、apiKey（可留空）、显示名（可留空），确认后写入 models.json 并**立即生效**（无需 /reload）。写入前自动备份到 `models.json.discovery-bak`。
+命令打开配置面板，列出所有标记了 `discoverModels` 的 provider；选中某个 provider 打开它的字段页（发现开关、baseUrl、api 类型、apiKey、显示名），并可立即重新发现或删除它。添加 provider 时依次问 id、baseUrl、api 类型、apiKey（可留空）、显示名（可留空），写入 models.json 后**立即生效**（无需 /reload）。写入前自动备份到 `models.json.discovery-bak`。
 
 注意：写回时 models.json 中的注释与自定义排版不被保留（会格式化为 4 空格缩进）。
 
@@ -40,7 +40,25 @@ pi install npm:pi-models-discovery
 }
 ```
 
-`baseUrl` 和 `api` 必填；`apiKey` 可选（无鉴权服务可省略）。同一 `baseUrl+apiKey` 的多个 provider 共享一次 `/models` 请求。
+`baseUrl` 和 `api` 必填；`apiKey` 可选（无鉴权服务可省略）。模型列表 URL、`apiKey`、`headers` 和 `compat` 相同的多个 provider 共享一次发现请求。
+
+如果模型列表使用不同的端点，可在 models.json 中设置可选的 `modelsUrl`，值为模型列表的**完整 URL**（包含路径和所需查询参数）：
+
+```json
+{
+  "providers": {
+    "foo": {
+      "baseUrl": "https://api.example.com/v1",
+      "modelsUrl": "https://catalog.example.com/v1/models",
+      "apiKey": "$FOO_API_KEY",
+      "api": "openai-completions",
+      "discoverModels": true
+    }
+  }
+}
+```
+
+`modelsUrl` 仅用于模型发现和刷新，按原值请求；聊天请求仍使用 `baseUrl`。未配置或为空时，沿用 `{baseUrl}/models`。发现请求会将 provider 现有的 `apiKey` 和 `headers` 发送到该 URL，请使用可信端点。响应格式保持不变。
 
 手编方式修改配置后需 `/reload` 生效；`/config:model-discovery` 命令的修改立即生效。
 
@@ -54,7 +72,7 @@ pi install npm:pi-models-discovery
 
 ## 行为
 
-- **启动（缓存优先）**：缓存命中时直接用持久化的模型列表注册，零网络请求；缓存文件位于 `~/.pi/agent/extensions/pi-models-discovery/cache.json`。provider 配置指纹（baseUrl+api+apiKey+headers+compat）变化时缓存自动失效，重新走网络发现。
+- **启动（缓存优先）**：缓存命中时直接用持久化的模型列表注册，零网络请求；缓存文件位于 `~/.pi/agent/extensions/pi-models-discovery/cache.json`。provider 配置指纹（baseUrl+api+apiKey+headers+compat+modelsUrl）变化时缓存自动失效，重新走网络发现。
 - **在线刷新**：`/config:model-discovery-refresh` 或 `/model` 打开时触发的 `refreshModels` 在线重新发现，并同步更新缓存。
 - **离线 / 拉取失败**：保留 models.json 里手写的 `models`（如有，作为回退），并通过会话内 notify 显式警告，不静默降级；单个 provider 失败不影响其他 provider。
 - **apiKey 解析**（仅发现请求）：支持字面量与 `$ENV_VAR` / `${ENV_VAR}` 插值；`!command` 形式跳过发现并显式警告（聊天请求仍由 pi 自身解析执行，不受影响）。

package/SKILL.md

@@ -13,7 +13,7 @@ description: "配置与排查 models.json 的动态模型发现、缓存刷新
 - `extensions/pi-models-discovery/cache.json`：启动缓存；
 - `models.json.discovery-bak`：交互配置写回前的备份。
 
-只处理带 `discoverModels: true` 的 provider。确认 `baseUrl`、`api`、可选 `apiKey`、headers/compat 以及服务的 `GET {baseUrl}/models` 响应。
+只处理带 `discoverModels: true` 的 provider。确认 `baseUrl`、`api`、可选 `modelsUrl` / `apiKey`、headers/compat 以及服务的模型列表响应。发现请求使用 `GET modelsUrl`（完整 URL，不追加 `/models`）；未配置或为空时使用 `GET {baseUrl}/models`。`modelsUrl` 仅影响发现和刷新，不改变聊天请求的 `baseUrl`；它会接收现有鉴权信息，须使用可信端点。
 
 ## 修改
 

package/locales/index.json

@@ -182,5 +182,109 @@
   "removed": {
     "zh-CN": "已删除 {id}（备份：{backup}）",
     "en-US": "Removed {id} (backup: {backup})"
+  },
+  "panelTitle": {
+    "zh-CN": "模型发现 provider（共 {count} 个）",
+    "en-US": "Model-discovery providers ({count})"
+  },
+  "panelProviderTitle": {
+    "zh-CN": "provider：{id}",
+    "en-US": "Provider: {id}"
+  },
+  "panelLabelAdd": {
+    "zh-CN": "添加 provider",
+    "en-US": "Add provider"
+  },
+  "panelDescAdd": {
+    "zh-CN": "填入 id、baseUrl、api 后写入 models.json 并立即发现模型。",
+    "en-US": "Enter an id, baseUrl and api; the entry is written to models.json and models are discovered immediately."
+  },
+  "panelLabelEnabled": {
+    "zh-CN": "模型发现",
+    "en-US": "Model discovery"
+  },
+  "panelDescEnabled": {
+    "zh-CN": "关闭后去掉该 provider 的 discoverModels 标记，模型条目不参与发现（provider 本身保留）。",
+    "en-US": "Turning this off removes the discoverModels marker so this provider is no longer discovered; the provider entry itself is kept."
+  },
+  "panelLabelName": {
+    "zh-CN": "显示名",
+    "en-US": "Display name"
+  },
+  "panelDescName": {
+    "zh-CN": "模型列表里显示的名字；留空回落到 provider id。",
+    "en-US": "Name shown in the model list; empty falls back to the provider id."
+  },
+  "panelLabelBaseUrl": {
+    "zh-CN": "baseUrl",
+    "en-US": "baseUrl"
+  },
+  "panelDescBaseUrl": {
+    "zh-CN": "发现请求打向 {baseUrl}/models；必须以 http:// 或 https:// 开头。",
+    "en-US": "Discovery requests go to {baseUrl}/models; it must start with http:// or https://."
+  },
+  "panelLabelApi": {
+    "zh-CN": "api 类型",
+    "en-US": "API type"
+  },
+  "panelDescApi": {
+    "zh-CN": "Pi 用哪种协议与这个 provider 对话。",
+    "en-US": "Which protocol Pi uses to talk to this provider."
+  },
+  "panelLabelApiKey": {
+    "zh-CN": "apiKey",
+    "en-US": "apiKey"
+  },
+  "panelDescApiKey": {
+    "zh-CN": "可留空；支持 $ENV_VAR 插值。",
+    "en-US": "Optional; supports $ENV_VAR interpolation."
+  },
+  "panelLabelRediscover": {
+    "zh-CN": "立即重新发现模型",
+    "en-US": "Rediscover models now"
+  },
+  "panelDescRediscover": {
+    "zh-CN": "立刻请求 {baseUrl}/models 刷新模型列表并更新缓存。",
+    "en-US": "Requests {baseUrl}/models now, refreshes the model list and updates the cache."
+  },
+  "panelLabelRemove": {
+    "zh-CN": "删除此 provider",
+    "en-US": "Remove this provider"
+  },
+  "panelDescRemove": {
+    "zh-CN": "从 models.json 移除该 provider 并注销其模型，会先让你确认。",
+    "en-US": "Removes the provider and unregisters its models from models.json; you are asked to confirm first."
+  },
+  "panelActionHint": {
+    "zh-CN": "回车执行",
+    "en-US": "Press Enter to run"
+  },
+  "panelValueUnset": {
+    "zh-CN": "（未设置）",
+    "en-US": "(unset)"
+  },
+  "panelOn": {
+    "zh-CN": "开",
+    "en-US": "On"
+  },
+  "panelOff": {
+    "zh-CN": "关",
+    "en-US": "Off"
+  },
+  "panelInputPrompt": {
+    "zh-CN": "值",
+    "en-US": "Value"
+  },
+  "panelConfirmRemove": {
+    "zh-CN": "删除 provider「{id}」？",
+    "en-US": "Remove provider \"{id}\"?"
+  },
+  "panelRemoveMessage": {
+    "zh-CN": "将从 models.json 移除该 provider 并注销其模型。此操作可重新添加恢复。",
+    "en-US": "This removes the provider and unregisters its models from models.json. It can be added again later."
+  },
+  "panelProviderMissing": {
+    "zh-CN": "models.json 中找不到 provider「{id}」的条目，无法写回。",
+    "en-US": "models.json has no entry for provider \"{id}\"; the change cannot be written back."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-models-discovery",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Pi extension: discover models from {baseUrl}/models for providers marked with discoverModels in models.json",
   "type": "module",
   "main": "./index.ts",
@@ -16,7 +16,7 @@
     "SKILL.md"
   ],
   "scripts": {
-    "test": "tsx --test tests/catalog.test.ts",
+    "test": "tsx --test tests/catalog.test.ts tests/config-panel.test.ts tests/config-panel-wiring.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "build": "npm run typecheck",
     "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
@@ -54,14 +54,16 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.80.0",
-    "@earendil-works/pi-coding-agent": ">=0.80.0"
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@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",
     "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "24.12.4",
     "tsx": "4.23.1",
     "typescript": "5.9.3"

package/src/config-panel.ts

@@ -0,0 +1,553 @@
+/**
+ * 模型发现 provider 的 TUI 配置面板。
+ *
+ * 原来用 `ctx.ui.select` 摆一串「id — baseUrl（api）」文本，看不出哪行是状态、按下去会发生什么。
+ * 这里改用 Pi 自带 `SettingsList`：左边字段名、右边当前值、选中项下方一行说明。
+ * 面板分两层：第一层列出所有带 discoverModels 标记的 provider，回车进入某个 provider 的第二层，
+ * 第二层就是这个 provider 的字段（发现开关、baseUrl、api、apiKey、显示名）和动作（立即发现、删除）。
+ *
+ * 枚举项回车开二级列表，自由文本回车开预填当前值的 Input 子菜单；改一项先写回内存配置，
+ * 由调用方负责落盘与运行期生效，不需要 /reload。
+ */
+
+import {
+	getSelectListTheme,
+	getSettingsListTheme,
+	type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type Component,
+	Input,
+	SelectList,
+	SettingsList,
+	type SelectItem,
+	type SettingItem,
+	Text,
+} from "@earendil-works/pi-tui";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
+
+/** `models.json` 里 api 类型的候选值。 */
+export const API_CHOICES = [
+	"openai-completions",
+	"anthropic-messages",
+	"openai-responses",
+	"google-generative-ai",
+] as const;
+
+/** 某个 provider 在面板上的可编辑字段名。 */
+export const PROVIDER_FIELD = {
+	/** 是否参与模型发现；关闭时只去掉 discoverModels 标记，provider 本身保留。 */
+	enabled: "enabled",
+	/** 显示名。 */
+	name: "name",
+	/** API 地址。 */
+	baseUrl: "baseUrl",
+	/** api 类型。 */
+	api: "api",
+	/** API Key；支持 $ENV_VAR 插值。 */
+	apiKey: "apiKey",
+	/** 动作：立刻请求 {baseUrl}/models 刷新模型。 */
+	rediscover: "rediscover",
+	/** 动作：从 models.json 删除该 provider。 */
+	remove: "remove",
+} as const;
+
+/** provider 面板字段名联合类型。 */
+export type ProviderFieldId = (typeof PROVIDER_FIELD)[keyof typeof PROVIDER_FIELD];
+
+/** 面板顶层：新增 provider 的入口字段名。 */
+export const ROOT_FIELD = {
+	/** 添加 provider。 */
+	add: "add",
+} as const;
+
+/**
+ * 面板覆盖的全部字段名（顶层 + provider 层），测试用它核对没有漏掉可编辑字段。
+ * provider 层字段名带 `provider.` 前缀，与顶层区分开。
+ */
+export const PANEL_FIELD_IDS: readonly string[] = [
+	ROOT_FIELD.add,
+	...Object.values(PROVIDER_FIELD).map((field) => `provider.${field}`),
+];
+
+/** 面板里一个 provider 的读形态。 */
+export interface PanelProvider {
+	/** provider id，也是 models.json 里的键。 */
+	id: string;
+	/** baseUrl。 */
+	baseUrl: string;
+	/** api 类型。 */
+	api: string;
+	/** apiKey；空串表示未设置。 */
+	apiKey: string;
+	/** 显示名；空串表示未设置（回落为 id）。 */
+	name: string;
+	/** 是否带 discoverModels 标记。 */
+	enabled: boolean;
+}
+
+/** 开关在面板上显示的两个文案。 */
+function toggleLabels(): { on: string; off: string } {
+	return { on: i18n.t("panelOn"), off: i18n.t("panelOff") };
+}
+
+/** 下拉列表的一项：label 是展示文本，value 是写回配置的值。 */
+interface PanelOption {
+	/** 展示文本。 */
+	label: string;
+	/** 写回配置的值。 */
+	value: string;
+}
+
+/** 二级列表最多同时显示几行；超出的部分由 SelectList 滚动。 */
+const CHOICE_MENU_MAX_VISIBLE = 10;
+
+/** provider 面板的行顺序：开关在最前，动作用特殊后缀区分。 */
+const PROVIDER_ROWS: readonly {
+	/** 字段名。 */
+	id: ProviderFieldId;
+	/** 取值方式：开关原地切换，枚举开列表，文本开输入框，动作直接执行。 */
+	kind: "toggle" | "choice" | "text" | "action";
+	/** 标题文案 key。 */
+	labelKey: string;
+	/** 说明文案 key。 */
+	descriptionKey: string;
+}[] = [
+	{ id: PROVIDER_FIELD.enabled, kind: "toggle", labelKey: "panelLabelEnabled", descriptionKey: "panelDescEnabled" },
+	{ id: PROVIDER_FIELD.name, kind: "text", labelKey: "panelLabelName", descriptionKey: "panelDescName" },
+	{ id: PROVIDER_FIELD.baseUrl, kind: "text", labelKey: "panelLabelBaseUrl", descriptionKey: "panelDescBaseUrl" },
+	{ id: PROVIDER_FIELD.api, kind: "choice", labelKey: "panelLabelApi", descriptionKey: "panelDescApi" },
+	{ id: PROVIDER_FIELD.apiKey, kind: "text", labelKey: "panelLabelApiKey", descriptionKey: "panelDescApiKey" },
+	{ id: PROVIDER_FIELD.rediscover, kind: "action", labelKey: "panelLabelRediscover", descriptionKey: "panelDescRediscover" },
+	{ id: PROVIDER_FIELD.remove, kind: "action", labelKey: "panelLabelRemove", descriptionKey: "panelDescRemove" },
+];
+
+/** 按配置值取展示文本；不在候选表里就直接显示原值。 */
+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;
+}
+
+/** 开关候选项。 */
+function toggleOptions(): PanelOption[] {
+	const labels = toggleLabels();
+	return [
+		{ label: labels.on, value: "on" },
+		{ label: labels.off, value: "off" },
+	];
+}
+
+/** api 类型候选项。 */
+function apiOptions(): PanelOption[] {
+	return API_CHOICES.map((value) => ({ label: value, value }));
+}
+
+/** 某个字段的候选表；文本和动作字段没有候选项。 */
+function fieldOptions(id: ProviderFieldId): PanelOption[] {
+	if (id === PROVIDER_FIELD.enabled) return toggleOptions();
+	if (id === PROVIDER_FIELD.api) return apiOptions();
+	return [];
+}
+
+/** 读取一个字段当前值的机器形态。 */
+function readProviderField(provider: PanelProvider, id: ProviderFieldId): string {
+	switch (id) {
+		case PROVIDER_FIELD.enabled:
+			return provider.enabled ? "on" : "off";
+		case PROVIDER_FIELD.name:
+			return provider.name;
+		case PROVIDER_FIELD.baseUrl:
+			return provider.baseUrl;
+		case PROVIDER_FIELD.api:
+			return provider.api;
+		case PROVIDER_FIELD.apiKey:
+			return provider.apiKey;
+		default:
+			return "";
+	}
+}
+
+/** 面板上显示的当前值；文本字段留空时显示「未设置」。 */
+function displayProviderValue(provider: PanelProvider, id: ProviderFieldId): string {
+	const stored = readProviderField(provider, id);
+	if (id === PROVIDER_FIELD.enabled) {
+		const labels = toggleLabels();
+		return stored === "on" ? labels.on : labels.off;
+	}
+	if (id === PROVIDER_FIELD.api) return optionLabelForValue(apiOptions(), stored);
+	if (id === PROVIDER_FIELD.apiKey || id === PROVIDER_FIELD.name) {
+		return stored || i18n.t("panelValueUnset");
+	}
+	return stored;
+}
+
+/**
+ * 把面板回传的展示文本写回 provider。
+ *
+ * 返回 undefined 表示这一项不该由面板改（未知字段，或候选表里没有这个标签），
+ * 调用方保持原值。动作字段（rediscover/remove）不走这里，由面板单独处理。
+ */
+export function applyProviderChange(
+	provider: PanelProvider,
+	id: string,
+	value: string,
+): PanelProvider | undefined {
+	const labels = toggleLabels();
+	switch (id) {
+		case PROVIDER_FIELD.enabled: {
+			if (value !== labels.on && value !== labels.off) return undefined;
+			return { ...provider, enabled: value === labels.on };
+		}
+		case PROVIDER_FIELD.name:
+			return { ...provider, name: value.trim() };
+		case PROVIDER_FIELD.baseUrl:
+			return { ...provider, baseUrl: value.trim() };
+		case PROVIDER_FIELD.api: {
+			const api = optionValueFromLabel(apiOptions(), value);
+			return api === undefined ? undefined : { ...provider, api };
+		}
+		case PROVIDER_FIELD.apiKey:
+			return { ...provider, apiKey: value.trim() };
+		default:
+			return undefined;
+	}
+}
+
+/** 自由文本子菜单：一个预填当前值的输入框。 */
+function createTextSubmenu(
+	value: string,
+	placeholder: string,
+	done: (value?: string) => void,
+): Component {
+	const input = new Input({ prompt: `${i18n.t("panelInputPrompt")} `, placeholder });
+	input.setValue(value);
+	input.focused = true;
+	input.onSubmit = (submitted) => done(submitted);
+	input.onEscape = () => done(undefined);
+	return {
+		/** 一行可编辑文本。 */
+		render: (width) => input.render(width),
+		/** 无本地缓存。 */
+		invalidate: () => input.invalidate(),
+		/** 按键全部交给输入框。 */
+		handleInput: (data) => input.handleInput(data),
+	};
+}
+
+/** 二级选择列表：Enter 选定并回传展示文本，Esc 不改动直接返回。 */
+function createChoiceSubmenu(
+	options: readonly PanelOption[],
+	currentLabel: string,
+	done: (selectedLabel?: string) => void,
+): Component {
+	const items: SelectItem[] = options.map((option) => ({ value: option.label, label: option.label }));
+	const list = new SelectList(
+		items,
+		Math.max(1, Math.min(items.length, CHOICE_MENU_MAX_VISIBLE)),
+		getSelectListTheme(),
+	);
+	const currentIndex = options.findIndex((option) => option.label === currentLabel);
+	if (currentIndex >= 0) list.setSelectedIndex(currentIndex);
+	list.onSelect = (item) => done(item.value);
+	list.onCancel = () => done(undefined);
+	return {
+		/** 直接渲染候选列表。 */
+		render: (width) => list.render(width),
+		/** 无本地缓存。 */
+		invalidate: () => list.invalidate(),
+		/** 按键全部交给列表。 */
+		handleInput: (data) => list.handleInput(data),
+	};
+}
+
+/** provider 面板行的动作钩子：由入口注入，负责真正执行发现或删除。 */
+export interface ProviderRowActions {
+	/** 立刻重新发现该 provider 的模型。 */
+	rediscover(provider: PanelProvider): Promise<void>;
+	/** 删除该 provider；返回 true 表示已删除，面板回到顶层。 */
+	remove(provider: PanelProvider): Promise<boolean>;
+}
+
+/**
+ * 把一行变成「Enter 就触发」的动作行。
+ *
+ * SettingsList 只在有 submenu 或 values 时才会触发 onChange，所以动作行给一个只有单值的
+ * values：Enter/空格 会把同一个值再报一次，等于「按下执行」，而不会改变任何配置。
+ */
+function actionRow(item: SettingItem): SettingItem {
+	return { ...item, values: [item.currentValue] };
+}
+
+/** 构造 provider 层的设置行。 */
+export function buildProviderItems(provider: PanelProvider): SettingItem[] {
+	return PROVIDER_ROWS.map((row) => {
+		const label = i18n.t(row.labelKey);
+		const description = i18n.t(row.descriptionKey);
+		const currentValue = displayProviderValue(provider, row.id);
+		if (row.kind === "toggle") {
+			return {
+				id: row.id,
+				label,
+				description,
+				currentValue,
+				values: toggleOptions().map((option) => option.label),
+			};
+		}
+		if (row.kind === "choice") {
+			return {
+				id: row.id,
+				label,
+				description,
+				currentValue,
+				// 二级列表接管 Enter，避免在少量候选之间反复循环。
+				submenu: (current, done) =>
+					createChoiceSubmenu(apiOptions(), current, done),
+			};
+		}
+		if (row.kind === "text") {
+			return {
+				id: row.id,
+				label,
+				description,
+				currentValue,
+				submenu: (_current, done) =>
+					createTextSubmenu(readProviderField(provider, row.id), description, done),
+			};
+		}
+		return actionRow({ id: row.id, label, description, currentValue: i18n.t("panelActionHint") });
+	});
+}
+
+/** 构造顶层的设置行：一个 provider 一行，外加「添加 provider」。 */
+export function buildRootItems(providers: readonly PanelProvider[]): SettingItem[] {
+	const items: SettingItem[] = providers.map((provider) => actionRow({
+		id: `provider:${provider.id}`,
+		label: `${provider.enabled ? "●" : "○"} ${provider.id}`,
+		description: `${provider.baseUrl || "?"} · ${provider.api || "?"}`,
+		currentValue: provider.name || provider.id,
+	}));
+	items.push(actionRow({
+		id: ROOT_FIELD.add,
+		label: i18n.t("panelLabelAdd"),
+		description: i18n.t("panelDescAdd"),
+		currentValue: i18n.t("panelActionHint"),
+	}));
+	return items;
+}
+
+/** 面板与宿主之间的接口；provider 列表、写回动作都由入口提供。 */
+export interface PanelState {
+	/** 当前所有带发现标记的 provider；每次现读，因为增删会改变列表。 */
+	getProviders(): PanelProvider[];
+	/** provider 配置被改动后调用；由调用方负责落盘与注册。 */
+	onProviderChange(provider: PanelProvider): void;
+	/** provider 被删除后调用。 */
+	onProviderRemoved(id: string): void;
+	/** 新增 provider；由调用方负责落盘与首次发现。 */
+	onProviderAdd(provider: PanelProvider): void;
+	/** 行动作。 */
+	actions: ProviderRowActions;
+}
+
+/** 顶层列表：选中 provider 进第二层，选中「添加」走新增流程。 */
+async function openProviderPanel(
+	ctx: ExtensionCommandContext,
+	state: PanelState,
+	provider: PanelProvider,
+): Promise<"back" | "removed"> {
+	/** 当前这一层的 provider 副本；改动即时写回内存。 */
+	let current: PanelProvider = { ...provider };
+	/** 用户在子菜单里选择的动作结果。 */
+	let pending: { kind: "rediscover" } | { kind: "remove" } | undefined;
+
+	const settingsList = await ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold(i18n.t("panelProviderTitle", { id: current.id }))), 1, 1),
+		);
+		const list = new SettingsList(
+			buildProviderItems(current),
+			PROVIDER_ROWS.length,
+			getSettingsListTheme(),
+			(id, newValue) => {
+				if (id === PROVIDER_FIELD.rediscover) {
+					pending = { kind: "rediscover" };
+					done(undefined);
+					return;
+				}
+				if (id === PROVIDER_FIELD.remove) {
+					pending = { kind: "remove" };
+					done(undefined);
+					return;
+				}
+				const next = applyProviderChange(current, id, newValue);
+				if (!next) return;
+				current = next;
+				state.onProviderChange(current);
+				list.updateValue(id, displayProviderValue(current, id as ProviderFieldId));
+			},
+			() => done(undefined),
+		);
+		container.addChild(list);
+		return {
+			/** 布局交给 Container。 */
+			render: (width) => container.render(width),
+			/** 无本地缓存。 */
+			invalidate: () => container.invalidate(),
+			/** 按键交给列表，并触发一次重绘。 */
+			handleInput: (data) => {
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+
+	if (pending?.kind === "rediscover") {
+		await state.actions.rediscover(current);
+		return openProviderPanel(ctx, state, current);
+	}
+	if (pending?.kind === "remove") {
+		const confirmed = await ctx.ui.confirm(
+			i18n.t("panelConfirmRemove", { id: current.id }),
+			i18n.t("panelRemoveMessage"),
+		);
+		if (confirmed && (await state.actions.remove(current))) {
+			state.onProviderRemoved(current.id);
+			return "removed";
+		}
+		return openProviderPanel(ctx, state, current);
+	}
+	return "back";
+}
+
+/** 新增 provider 的表单结果。 */
+interface NewProviderInput {
+	/** provider id。 */
+	id: string;
+	/** baseUrl。 */
+	baseUrl: string;
+	/** api 类型。 */
+	api: string;
+	/** apiKey。 */
+	apiKey: string;
+	/** 显示名。 */
+	name: string;
+}
+
+/** 提示并校验一个值；返回 undefined 表示用户取消或校验失败（失败已提示）。 */
+async function askValidated(
+	ctx: ExtensionCommandContext,
+	options: {
+		/** 输入框标题。 */
+		title: string;
+		/** 预填值。 */
+		initial?: string;
+		/** 校验函数；通过返回 undefined，失败返回错误文案 key 的参数。 */
+		validate(value: string): { key: string; params?: Record<string, string> } | undefined;
+	},
+): Promise<string | undefined> {
+	const value = (await ctx.ui.input(options.title, options.initial))?.trim();
+	if (value === undefined) return undefined;
+	if (!value) return undefined;
+	const failure = options.validate(value);
+	if (failure) {
+		ctx.ui.notify(i18n.t(failure.key, failure.params), "error");
+		return undefined;
+	}
+	return value;
+}
+
+/** 逐项问出新增 provider 需要的字段；任一项取消就整体放弃。 */
+async function collectNewProvider(
+	ctx: ExtensionCommandContext,
+	existingIds: ReadonlySet<string>,
+): Promise<NewProviderInput | undefined> {
+	const id = await askValidated(ctx, {
+		title: i18n.t("providerId"),
+		validate: (value) => {
+			if (!/^[a-z0-9][a-z0-9-]*$/i.test(value)) return { key: "invalidId" };
+			if (existingIds.has(value)) return { key: "exists", params: { id: value } };
+			return undefined;
+		},
+	});
+	if (!id) return undefined;
+	const baseUrl = await askValidated(ctx, {
+		title: i18n.t("baseUrl"),
+		validate: (value) => (/^https?:\/\//.test(value) ? undefined : { key: "invalidUrl" }),
+	});
+	if (!baseUrl) return undefined;
+	const api = await ctx.ui.select(i18n.t("api"), [...API_CHOICES]);
+	if (!api) return undefined;
+	const apiKey = (await ctx.ui.input(i18n.t("apiKey")))?.trim() ?? "";
+	const name = (await ctx.ui.input(i18n.t("displayName", { id })))?.trim() ?? "";
+	return { id, baseUrl, api, apiKey, name };
+}
+
+/** 打开 /config:model-discovery 面板；Esc 关闭，改动已经即时写回。 */
+export async function openDiscoveryPanel(
+	ctx: ExtensionCommandContext,
+	state: PanelState,
+): Promise<void> {
+	while (true) {
+		const providers = state.getProviders();
+		const selection = await ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold(i18n.t("panelTitle", { count: providers.length }))), 1, 1),
+			);
+			const items = buildRootItems(providers);
+			const list = new SettingsList(
+				items,
+				Math.max(1, items.length),
+				getSettingsListTheme(),
+				(id) => done(id),
+				() => done(undefined),
+			);
+			container.addChild(list);
+			return {
+				/** 布局交给 Container。 */
+				render: (width) => container.render(width),
+				/** 无本地缓存。 */
+				invalidate: () => container.invalidate(),
+				/** 按键交给列表，并触发一次重绘。 */
+				handleInput: (data) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+
+		if (!selection) return;
+		if (selection === ROOT_FIELD.add) {
+			const existingIds = new Set(state.getProviders().map((provider) => provider.id));
+			const input = await collectNewProvider(ctx, existingIds);
+			if (!input) continue;
+			const provider: PanelProvider = {
+				id: input.id,
+				baseUrl: input.baseUrl,
+				api: input.api,
+				apiKey: input.apiKey,
+				name: input.name,
+				enabled: true,
+			};
+			state.onProviderAdd(provider);
+			continue;
+		}
+		if (!selection.startsWith("provider:")) continue;
+		const id = selection.slice("provider:".length);
+		const provider = state.getProviders().find((candidate) => candidate.id === id);
+		if (!provider) continue;
+		const result = await openProviderPanel(ctx, state, provider);
+		if (result === "removed") continue;
+	}
+}

package/src/index.ts

@@ -2,7 +2,7 @@
  * 通用模型发现插件
  *
  * 读取 models.json 中带 "discoverModels": true 的 provider，请求
- * GET {baseUrl}/models 自动发现模型并注册，无需手写 models 数组。
+ * GET modelsUrl（缺省为 {baseUrl}/models）自动发现模型并注册，无需手写 models 数组。
  *
  * 配置方式（二选一）：
  * 1. pi 终端内执行 /config:model-discovery，交互式添加/删除/重新发现 provider（推荐）；
@@ -22,14 +22,14 @@
  * 行为约定：
  * - 首次发现成功后，模型列表持久化到 ~/.pi/agent/extensions/pi-models-discovery/cache.json；
  *   之后每次启动直接读缓存注册，不请求网络。配置指纹
- *   （baseUrl+api+apiKey+headers+compat）变化时缓存自动失效，重新走网络发现。
+ *   （baseUrl+api+apiKey+headers+compat+modelsUrl）变化时缓存自动失效，重新走网络发现。
  * - /config:model-discovery-refresh 强制重新拉取所有发现 provider 并更新缓存；
  *   /model 打开时触发的在线 refreshModels 同样走网络并同步更新缓存。
  * - baseUrl / api 由扩展显式转发（pi 的 extension 组合层要求），
  *   apiKey / name / headers / compat 不写回注册配置，由 pi 的 models.json 层回落生效。
  * - provider 级 compat 会被合并进每个发现的模型（pi 的 models.json provider 级 compat
  *   不作用于 extension 注册的模型，故在此转发）。
- * - 同一 baseUrl+apiKey+headers 的多个 provider 共享一次 /models 请求。
+ * - 同一模型列表 URL+apiKey+headers+compat 的多个 provider 共享一次发现请求。
  * - 发现失败：该 provider 保留 models.json 手写 models（如有，作为离线回退），
  *   并通过 notify 显式警告，不静默降级；单个 provider 失败不影响其他 provider 注册。
  * - 注册 refreshModels：打开 /model 触发在线刷新时重新发现；
@@ -52,6 +52,7 @@ import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-codin
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { NOTICE_TAG_COLOR, createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
+import { openDiscoveryPanel, type PanelProvider } from "./config-panel.ts";
 
 const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
 
@@ -64,7 +65,7 @@ const NOTICE_TAG = "models";
 const NOTICE_COLOR: NoticeColor = NOTICE_TAG_COLOR;
 /** 本扩展的提示来源。 */
 const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
-const API_CHOICES = ["openai-completions", "anthropic-messages", "openai-responses", "google-generative-ai"] as const;
+
 
 /** 用户可见消息（级别与 ctx.ui.notify 的 type 对齐）；供通知中继与无 ctx 的收集队列共用 */
 interface Notice {
@@ -80,10 +81,13 @@ interface DiscoveryProviderEntry {
 	id: string;
 	name?: string;
 	baseUrl?: string;
+	modelsUrl?: string;
 	apiKey?: string;
 	api?: string;
 	headers?: Record<string, string>;
 	compat?: Record<string, unknown>;
+	/** 发现标记；面板关闭发现时写 false（实际会删掉这个键）。 */
+	discoverModels?: boolean;
 }
 
 interface ModelsResponse {
@@ -132,6 +136,8 @@ function providerFingerprint(entry: DiscoveryProviderEntry): string {
 		entry.apiKey ?? "",
 		entry.headers ?? {},
 		entry.compat ?? {},
+		// 未配置 modelsUrl 时保留已有指纹，避免让旧缓存失效。
+		...(entry.modelsUrl ? [entry.modelsUrl] : []),
 	]);
 }
 
@@ -247,6 +253,7 @@ function pickDiscoveryProviders(data: Record<string, unknown>): DiscoveryProvide
 			id,
 			name: typeof value.name === "string" ? value.name : undefined,
 			baseUrl: typeof value.baseUrl === "string" ? value.baseUrl : undefined,
+			modelsUrl: typeof value.modelsUrl === "string" ? value.modelsUrl : undefined,
 			apiKey: typeof value.apiKey === "string" ? value.apiKey : undefined,
 			api: typeof value.api === "string" ? value.api : undefined,
 			headers:
@@ -316,7 +323,12 @@ export function buildModel(
 	};
 }
 
-/** 请求 {baseUrl}/models 并解析为模型配置；失败抛错（错误信息带原因） */
+/** 模型列表的完整 URL；未配置时沿用 {baseUrl}/models。 */
+function getModelsUrl(entry: DiscoveryProviderEntry): string {
+	return entry.modelsUrl || `${(entry.baseUrl ?? "").replace(/\/+$/, "")}/models`;
+}
+
+/** 请求模型列表并解析为模型配置；失败抛错（错误信息带原因） */
 async function fetchModels(
 	entry: DiscoveryProviderEntry,
 	notices: Notice[],
@@ -345,7 +357,7 @@ async function fetchModels(
 			headers.Authorization = `Bearer ${resolved.value}`;
 		}
 	}
-	const url = `${entry.baseUrl.replace(/\/+$/, "")}/models`;
+	const url = getModelsUrl(entry);
 	let response: Response;
 	try {
 		response = await fetch(url, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
@@ -374,11 +386,11 @@ async function fetchModels(
 	return models;
 }
 
-/** 共享 /models 请求的缓存：同一 baseUrl+apiKey+headers 只拉一次 */
+/** 缓存的是含 compat 的模型配置，只有 URL+apiKey+headers+compat 相同才可复用。 */
 type FetchCache = Map<string, Promise<ProviderModelConfig[]>>;
 
 function fetchWithCache(cache: FetchCache, entry: DiscoveryProviderEntry, notices: Notice[]): Promise<ProviderModelConfig[]> {
-	const cacheKey = `${entry.baseUrl}\n${entry.apiKey ?? ""}\n${JSON.stringify(entry.headers ?? {})}`;
+	const cacheKey = JSON.stringify([getModelsUrl(entry), entry.apiKey ?? "", entry.headers ?? {}, entry.compat ?? {}]);
 	let pending = cache.get(cacheKey);
 	if (!pending) {
 		pending = fetchModels(entry, notices);
@@ -484,41 +496,220 @@ function registerFromCache(
 	});
 }
 
+/**
+ * 把带 discoverModels 标记的 provider 转成面板读的形态。
+ * 面板不直接碰磁盘，改完由 persistProvider 写回 models.json。
+ */
+function toPanelProvider(entry: DiscoveryProviderEntry): PanelProvider {
+	return {
+		id: entry.id,
+		baseUrl: entry.baseUrl ?? "",
+		api: entry.api ?? "",
+		apiKey: entry.apiKey ?? "",
+		name: entry.name ?? "",
+		enabled: true,
+	};
+}
+
+/** 读取当前 models.json 里所有带发现标记的 provider，供面板渲染。 */
+async function readPanelProviders(): Promise<{ providers: PanelProvider[]; error: string | null }> {
+	const { data, error } = await readModelsFile();
+	if (error) return { providers: [], error };
+	return { providers: pickDiscoveryProviders(data).map(toPanelProvider), error: null };
+}
+
+/**
+ * 面板改一个 provider 的字段后写回 models.json。
+ * 沿用原条目的其余字段（headers/compat 等面板不管的键），只覆盖面板能改的四项。
+ */
+async function persistProvider(provider: PanelProvider): Promise<{ backup: string }> {
+	const { data, error } = await readModelsFile();
+	if (error) throw new Error(error);
+	const providers = (data.providers ?? {}) as Record<string, Record<string, unknown>>;
+	const existing = providers[provider.id];
+	if (!existing) throw new Error(i18n.t("panelProviderMissing", { id: provider.id }));
+	const entry: Record<string, unknown> = { ...existing, baseUrl: provider.baseUrl, api: provider.api };
+	if (provider.enabled) entry[DISCOVERY_MARKER] = true;
+	else delete entry[DISCOVERY_MARKER];
+	if (provider.apiKey) entry.apiKey = provider.apiKey;
+	else delete entry.apiKey;
+	if (provider.name) entry.name = provider.name;
+	else delete entry.name;
+	providers[provider.id] = entry;
+	data.providers = providers;
+	return writeModelsFile(data);
+}
+
+/** 新增 provider 时写入 models.json 的条目。 */
+async function persistNewProvider(provider: PanelProvider): Promise<{ backup: string }> {
+	const { data, error } = await readModelsFile();
+	if (error) throw new Error(error);
+	const providers = (data.providers ?? {}) as Record<string, Record<string, unknown>>;
+	const entry: Record<string, unknown> = {
+		baseUrl: provider.baseUrl,
+		api: provider.api,
+		[DISCOVERY_MARKER]: true,
+	};
+	if (provider.apiKey) entry.apiKey = provider.apiKey;
+	if (provider.name) entry.name = provider.name;
+	providers[provider.id] = entry;
+	data.providers = providers;
+	return writeModelsFile(data);
+}
+
+/** 从 models.json 删掉一个 provider 条目。 */
+async function deleteProvider(id: string): Promise<{ backup: string }> {
+	const { data, error } = await readModelsFile();
+	if (error) throw new Error(error);
+	const providers = (data.providers ?? {}) as Record<string, Record<string, unknown>>;
+	delete providers[id];
+	data.providers = providers;
+	return writeModelsFile(data);
+}
+
+/**
+ * 用 models.json 当前内容重新注册一个 provider，行为与启动期一致：
+ * 指纹命中缓存就直接注册缓存里的模型，不请求网络；否则走在线发现。
+ */
+async function reloadProvider(options: {
+	/** 扩展 API，用来注册或注销 provider。 */
+	pi: ExtensionAPI;
+	/** models.json 中读到的 provider 条目。 */
+	entry: DiscoveryProviderEntry;
+	/** 本次会话共享的 /models 请求缓存。 */
+	fetchCache: FetchCache;
+	/** 收集过程中产生的提示，由调用方决定发给谁。 */
+	notices: Notice[];
+}): Promise<void> {
+	const { pi, entry, fetchCache, notices } = options;
+	if (entry.discoverModels === false) {
+		pi.unregisterProvider(entry.id);
+		return;
+	}
+	const cache = await readCache(notices);
+	const cached = cache.providers[entry.id];
+	if (
+		cached &&
+		cached.fingerprint === providerFingerprint(entry) &&
+		Array.isArray(cached.models) &&
+		cached.models.length > 0
+	) {
+		registerFromCache(pi, entry, cached.models, notices);
+		return;
+	}
+	await discoverAndRegister(pi, entry, fetchCache, notices);
+}
+
+/** 按 id 从 models.json 现读一个 provider 条目；没有发现标记时返回 undefined。 */
+async function readProviderEntry(id: string): Promise<DiscoveryProviderEntry | undefined> {
+	const { data } = await readModelsFile();
+	return pickDiscoveryProviders(data).find((entry) => entry.id === id);
+}
+
 /** /config:model-discovery 交互式配置命令；旧名称保留为兼容别名。 */
 function registerDiscoveryCommand(pi: ExtensionAPI, fetchCache: FetchCache, sink: NoticeSink) {
+	/** 面板读 provider 列表、写回 models.json，并把改动即时注册到运行期。 */
+	const openPanel = async (ctx: CommandCtx): Promise<void> => {
+		const first = await readPanelProviders();
+		if (first.error) {
+			sink({ level: "error", message: `${LOG_PREFIX} ${first.error}` }, ctx);
+			return;
+		}
+		let providers = first.providers;
+		/**
+		 * 变更队列。
+		 *
+		 * SettingsList 的 onChange 是同步回调，无法 await，所以写盘+重新注册按顺序排成一条链；
+		 * 面板关闭后等这条链清空，保证最后一次改动已落盘并已注册（不静默丢改动）。
+		 */
+		let pendingChange: Promise<void> = Promise.resolve();
+		/** 把一个变更追加到队尾，保证先后顺序与面板操作一致。 */
+		const enqueue = (change: () => Promise<void>): void => {
+			pendingChange = pendingChange.then(change);
+		};
+		await openDiscoveryPanel(ctx, {
+			getProviders: () => providers,
+			onProviderChange: (provider) => {
+				// 面板下一次读到的必须是刚改过的值，所以内存副本同步更新，落盘排队跟上。
+				providers = providers.map((current) => (current.id === provider.id ? provider : current));
+				enqueue(async () => {
+					const notices: Notice[] = [];
+					try {
+						await persistProvider(provider);
+					} catch (err) {
+						flushNotices(ctx, [{
+							level: "error",
+							message: `${LOG_PREFIX} ${err instanceof Error ? err.message : String(err)}`,
+						}]);
+						return;
+					}
+					const entry = await readProviderEntry(provider.id);
+					if (!entry) {
+						pi.unregisterProvider(provider.id);
+					} else {
+						await reloadProvider({ pi, entry, fetchCache, notices });
+					}
+					// 面板行上的当前值来自本地副本，网络提示照常发出来，不静默降级。
+					flushNotices(ctx, notices);
+				});
+			},
+			onProviderRemoved: (id) => {
+				providers = providers.filter((provider) => provider.id !== id);
+			},
+			onProviderAdd: (provider) => {
+				providers = [...providers, provider];
+				enqueue(() => addProviderFromPanel({ pi, ctx, provider, fetchCache, sink }));
+			},
+			actions: {
+				rediscover: (provider) => {
+					// 也走同一条队列：保证“改字段”与“立即重新发现”不会交叠写盘。
+					enqueue(async () => {
+						const entry = await readProviderEntry(provider.id) ?? {
+							id: provider.id,
+							baseUrl: provider.baseUrl,
+							api: provider.api,
+							apiKey: provider.apiKey || undefined,
+							name: provider.name || undefined,
+						};
+						const notices: Notice[] = [];
+						const result = await discoverAndRegister(pi, entry, fetchCache, notices);
+						flushNotices(ctx, notices);
+						if (result) {
+							sink({ level: "info", message: i18n.t("rediscovered", { id: provider.id, count: result.count }) }, ctx);
+						}
+					});
+					return pendingChange;
+				},
+				remove: async (provider) => {
+					/** 删除结果；由队列里的那段代码写入。 */
+					let removed = false;
+					enqueue(async () => {
+						try {
+							const { backup } = await deleteProvider(provider.id);
+							pi.unregisterProvider(provider.id);
+							const notices: Notice[] = [];
+							await removeCachedModels(provider.id, notices);
+							flushNotices(ctx, notices);
+							sink({ level: "info", message: i18n.t("removed", { id: provider.id, backup }) }, ctx);
+							removed = true;
+						} catch (err) {
+							sink({ level: "error", message: `${LOG_PREFIX} ${err instanceof Error ? err.message : String(err)}` }, ctx);
+						}
+					});
+					await pendingChange;
+					return removed;
+				},
+			},
+		});
+		// 面板已关，但队列里可能还有写盘与重新注册；等它们完成再返回。
+		await pendingChange;
+	};
+
 	const command = {
 		description: i18n.t("commandDescription"),
 		handler: async (_args, ctx) => {
 			if (!ctx.hasUI) return;
-			while (true) {
-				const { data, error } = await readModelsFile();
-				if (error) {
-					sink({ level: "error", message: `${LOG_PREFIX} ${error}` }, ctx);
-					return;
-				}
-				const providers = pickDiscoveryProviders(data);
-				const ADD = i18n.t("add");
-				const EXIT = i18n.t("exit");
-				const choices = [
-					...providers.map((p) => `${p.id} — ${p.baseUrl ?? "?"}（${p.api ?? "?"}）`),
-					ADD,
-					EXIT,
-				];
-				const choice = await ctx.ui.select(
-					providers.length > 0 ? i18n.t("title", { count: providers.length }) : i18n.t("emptyTitle"),
-					choices,
-				);
-				if (choice === undefined || choice === EXIT) return;
-
-				if (choice === ADD) {
-					await addProviderFlow(pi, ctx, data, fetchCache, sink);
-					continue;
-				}
-				const selected = providers[choices.indexOf(choice)];
-				if (selected) {
-					await manageProviderFlow(pi, ctx, data, selected, fetchCache, sink);
-				}
-			}
+			await openPanel(ctx);
 		},
 	};
 	for (const name of ["config:model-discovery", "model-discovery", "pi-model-discovery"] as const) {
@@ -542,7 +733,7 @@ function registerRefreshCommand(pi: ExtensionAPI, sink: NoticeSink) {
 				sink({ level: "info", message: i18n.t("refreshEmpty") }, ctx);
 				return;
 			}
-			// 每次刷新用新的请求级缓存：同 baseUrl 的 provider 仍共享一次请求，但不复用启动期结果
+			// 每次刷新用新的请求级缓存：同模型列表 URL 的 provider 仍共享请求，但不复用启动期结果
 			const fetchCache: FetchCache = new Map();
 			let ok = 0;
 			for (const entry of providers) {
@@ -581,104 +772,45 @@ function flushNotices(ctx: CommandCtx, notices: Notice[]): void {
 	for (const notice of notices) notifyWithSource({ ctx, source: NOTICE_SOURCE, level: notice.level, message: notice.message });
 }
 
-/** /config:model-discovery 添加 provider 交互流程 */
-async function addProviderFlow(pi: ExtensionAPI, ctx: CommandCtx, data: Record<string, unknown>, fetchCache: FetchCache, sink: NoticeSink) {
-	const existingIds = new Set(Object.keys((data.providers ?? {}) as Record<string, unknown>));
-	const id = (await ctx.ui.input(i18n.t("providerId")))?.trim();
-	if (!id) return;
-	if (!/^[a-z0-9][a-z0-9-]*$/i.test(id)) {
-		sink({ level: "error", message: i18n.t("invalidId") }, ctx);
-		return;
-	}
-	if (existingIds.has(id)) {
-		sink({ level: "error", message: i18n.t("exists", { id }) }, ctx);
-		return;
-	}
-	const baseUrl = (await ctx.ui.input(i18n.t("baseUrl")))?.trim();
-	if (!baseUrl) return;
-	if (!/^https?:\/\//.test(baseUrl)) {
-		sink({ level: "error", message: i18n.t("invalidUrl") }, ctx);
-		return;
-	}
-	const api = await ctx.ui.select(i18n.t("api"), [...API_CHOICES]);
-	if (!api) return;
-	const apiKey = (await ctx.ui.input(i18n.t("apiKey")))?.trim();
-	const name = (await ctx.ui.input(i18n.t("displayName", { id })))?.trim();
-
-	const entry: Record<string, unknown> = { baseUrl, api, [DISCOVERY_MARKER]: true };
-	if (name) entry.name = name;
-	if (apiKey) entry.apiKey = apiKey;
-	const summary = i18n.t("summary", { id, baseUrl, api, apiKey: apiKey || i18n.t("noKey"), name: name || id });
-	if (!(await ctx.ui.confirm(i18n.t("confirmAdd"), summary))) return;
-
-	const providers = (data.providers ?? {}) as Record<string, unknown>;
-	providers[id] = entry;
-	data.providers = providers;
+/** /config:model-discovery 新增 provider：写回 models.json 后立刻做首次发现。 */
+async function addProviderFromPanel(options: {
+	/** 扩展 API。 */
+	pi: ExtensionAPI;
+	/** 命令上下文，用来发提示。 */
+	ctx: CommandCtx;
+	/** 面板里填好的新 provider。 */
+	provider: PanelProvider;
+	/** 本次会话共享的 /models 请求缓存。 */
+	fetchCache: FetchCache;
+	/** 提示出口。 */
+	sink: NoticeSink;
+}): Promise<void> {
+	const { pi, ctx, provider, fetchCache, sink } = options;
 	try {
-		const { backup } = await writeModelsFile(data);
+		const { backup } = await persistNewProvider(provider);
 		sink({ level: "info", message: i18n.t("written", { backup }) }, ctx);
 	} catch (err) {
 		sink({ level: "error", message: `${LOG_PREFIX} ${err instanceof Error ? err.message : err}` }, ctx);
 		return;
 	}
-
 	const notices: Notice[] = [];
 	const result = await discoverAndRegister(
 		pi,
-		{ id, name: name || undefined, baseUrl, apiKey: apiKey || undefined, api },
+		{
+			id: provider.id,
+			name: provider.name || undefined,
+			baseUrl: provider.baseUrl,
+			apiKey: provider.apiKey || undefined,
+			api: provider.api,
+		},
 		fetchCache,
 		notices,
 	);
 	flushNotices(ctx, notices);
 	if (result) {
-		sink({ level: "info", message: i18n.t("discovered", { id, count: result.count }) }, ctx);
+		sink({ level: "info", message: i18n.t("discovered", { id: provider.id, count: result.count }) }, ctx);
 	} else {
-		sink({ level: "warning", message: i18n.t("firstFailed", { id }) }, ctx);
-	}
-}
-
-/** /config:model-discovery 管理 provider（重新发现/删除）交互流程 */
-async function manageProviderFlow(
-	pi: ExtensionAPI,
-	ctx: CommandCtx,
-	data: Record<string, unknown>,
-	entry: DiscoveryProviderEntry,
-	fetchCache: FetchCache,
-	sink: NoticeSink,
-) {
-	const REDISCOVER = i18n.t("rediscover");
-	const REMOVE = i18n.t("remove");
-	const BACK = i18n.t("back");
-	const action = await ctx.ui.select(
-		i18n.t("manageTitle", { id: entry.id, baseUrl: entry.baseUrl ?? "?", api: entry.api ?? "?" }),
-		[REDISCOVER, REMOVE, BACK],
-	);
-	if (action === undefined || action === BACK) return;
-
-	if (action === REDISCOVER) {
-		const notices: Notice[] = [];
-		const result = await discoverAndRegister(pi, entry, fetchCache, notices);
-		flushNotices(ctx, notices);
-		if (result) {
-			sink({ level: "info", message: i18n.t("rediscovered", { id: entry.id, count: result.count }) }, ctx);
-		}
-		return;
-	}
-
-	// REMOVE
-	if (!(await ctx.ui.confirm(i18n.t("confirmRemove", { id: entry.id }), i18n.t("removeMessage")))) return;
-	const providers = (data.providers ?? {}) as Record<string, unknown>;
-	delete providers[entry.id];
-	data.providers = providers;
-	try {
-		const { backup } = await writeModelsFile(data);
-		pi.unregisterProvider(entry.id);
-		const notices: Notice[] = [];
-		await removeCachedModels(entry.id, notices);
-		flushNotices(ctx, notices);
-		sink({ level: "info", message: i18n.t("removed", { id: entry.id, backup }) }, ctx);
-	} catch (err) {
-		sink({ level: "error", message: `${LOG_PREFIX} ${err instanceof Error ? err.message : err}` }, ctx);
+		sink({ level: "warning", message: i18n.t("firstFailed", { id: provider.id }) }, ctx);
 	}
 }