pi-models-discovery 1.3.1 → 1.5.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.
 
@@ -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,12 +72,25 @@ 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).
 - Default parameters for discovered models: `reasoning: true`, `input: ["text", "image"]`, zero cost, `contextWindow` 1M, `maxTokens` 64K, `compat.supportsDeveloperRole: false`. Provider-level `compat` is merged into every discovered model.
-- Discovered models do not declare `thinkingLevelMap`, so pi applies the provider's default thinking-level mapping (standard levels through `high`; the extended `xhigh` / `max` levels are not exposed). `/models` cannot report per-model thinking capability, and the extension does not guess it — declare `thinkingLevelMap` yourself in a handwritten `models` entry if a provider needs something different.
+- Discovered models declare `thinkingLevelMap: { xhigh: "xhigh", max: "max" }`, so `xhigh` and `max` appear in `/thinking`; the standard levels stay omitted and keep pi's provider default mapping. `/models` cannot report per-model thinking capability, so this is a blanket default for every discovered model: when a provider rejects those levels, override it per model through `modelOverrides` in models.json (set `xhigh` / `max` to `null` to hide them), or declare the model yourself in a handwritten `models` entry.
+
+```json
+{
+  "providers": {
+    "llm-proxy": {
+      "discoverModels": true,
+      "modelOverrides": {
+        "some-model": { "thinkingLevelMap": { "xhigh": null, "max": null } }
+      }
+    }
+  }
+}
+```
 - Model metadata may carry `name` / `context_window` (or `contextWindow`) / `max_tokens` (or `maxTokens`); defaults are used when absent.
 
 The old `/model-discovery`, `/model-discovery-refresh`, `/pi-model-discovery`, and `/pi-model-discovery-refresh` names remain available as compatibility aliases.

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 兼容服务。
 
@@ -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,12 +72,25 @@ 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 自身解析执行，不受影响）。
 - 发现的模型默认参数：`reasoning: true`、`input: ["text", "image"]`、cost 全 0、`contextWindow` 1M、`maxTokens` 64K、`compat.supportsDeveloperRole: false`；provider 级 `compat` 会合并进每个发现的模型。
-- 发现的模型不声明 `thinkingLevelMap`，由 pi 按 provider 默认映射决定可选思考等级（标准等级直至 `high`，不提供扩展的 `xhigh` / `max`）。`/models` 无法逐个模型返回思考能力，扩展也不替它猜；个别 provider 需要不同映射时，请在 models.json 里手写该模型的 `models` 条目自行声明。
+- 发现的模型声明 `thinkingLevelMap: { xhigh: "xhigh", max: "max" }`，让 `xhigh` / `max` 出现在 `/thinking`；标准档位保持缺省，仍由 pi 的 provider 默认映射决定。`/models` 无法逐个模型返回思考能力，所以这是对所有发现模型一刀切的默认值：某个 provider 拒绝这些档位时，在 models.json 的 `modelOverrides` 里按 model.id 覆盖（把 `xhigh` / `max` 置 `null` 可隐藏），或改用手写 `models` 条目自行声明。
+
+```json
+{
+  "providers": {
+    "llm-proxy": {
+      "discoverModels": true,
+      "modelOverrides": {
+        "some-model": { "thinkingLevelMap": { "xhigh": null, "max": null } }
+      }
+    }
+  }
+}
+```
 - 模型元数据可携带 `name` / `context_window`（或 `contextWindow`）/ `max_tokens`（或 `maxTokens`），缺失时用默认值。
 
 旧的 `/model-discovery`、`/model-discovery-refresh`、`/pi-model-discovery` 和 `/pi-model-discovery-refresh` 名称仍作为兼容别名保留。

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`；它会接收现有鉴权信息，须使用可信端点。
 
 ## 修改
 
@@ -21,6 +21,10 @@ description: "配置与排查 models.json 的动态模型发现、缓存刷新
 
 `apiKey` 可用字面量、`$ENV_VAR` 或 `${ENV_VAR}`；`!command` 不用于发现请求，会被跳过并警告。不要把密钥写入 Skill、仓库或回复。
 
+## 思考等级
+
+发现的模型默认声明 `thinkingLevelMap: { xhigh: "xhigh", max: "max" }`（对所有模型一刀切）。若某个模型不认 `xhigh` / `max`，用 models.json 的 `modelOverrides` 按 model.id 把它们置 `null`。
+
 ## 验证
 
 - `/config:model-discovery-refresh` 强制联网刷新并更新缓存；旧命令名仅为兼容别名。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-models-discovery",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Pi extension: discover models from {baseUrl}/models for providers marked with discoverModels in models.json",
   "type": "module",
   "main": "./index.ts",
@@ -57,7 +57,7 @@
     "@earendil-works/pi-coding-agent": ">=0.80.0"
   },
   "dependencies": {
-    "pi-extensions-i18n": "^0.7.0"
+    "pi-extensions-i18n": "^0.8.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.85.1",

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,19 +22,22 @@
  * 行为约定：
  * - 首次发现成功后，模型列表持久化到 ~/.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 触发在线刷新时重新发现；
  *   离线初始化（allowNetwork=false）返回上次成功列表（含缓存），尚无成功记录时抛错，
  *   以免空列表清掉 models.json 手写 models。
+ * - 发现模型默认声明 thinkingLevelMap { xhigh: "xhigh", max: "max" }，让 xhigh/max 出现在
+ *   /thinking；标准档位缺省沿用 pi 的 provider 默认映射。这是对所有发现模型一刀切的默认值，
+ *   上游不认这些值时用 models.json 的 provider.modelOverrides 按 model.id 覆盖。
  * - 发现请求的 apiKey 解析仅支持字面量与 $ENV_VAR/${ENV_VAR} 插值；
  *   "!command" 形式的 apiKey 跳过发现（显式警告），pi 发起聊天请求时仍由 pi 自身解析。
  * - /config:model-discovery 命令对 models.json 的修改立即生效（registerProvider 运行时可直接调用）；
@@ -48,7 +51,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
+import { NOTICE_TAG_COLOR, createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
 
 const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
 
@@ -57,8 +60,8 @@ const DISCOVERY_MARKER = "discoverModels";
 const LOG_PREFIX = "[model-discovery]";
 /** 本扩展的提示标签；短且唯一，便于在会话里定位来源。 */
 const NOTICE_TAG = "models";
-/** 提示标签颜色；与其它扩展错开，避免看起来像同一条消息。 */
-const NOTICE_COLOR: NoticeColor = "accent";
+/** 提示标签颜色：所有扩展统一用弱化色，来源靠 tag 文本区分，不靠颜色。 */
+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;
@@ -77,6 +80,7 @@ interface DiscoveryProviderEntry {
 	id: string;
 	name?: string;
 	baseUrl?: string;
+	modelsUrl?: string;
 	apiKey?: string;
 	api?: string;
 	headers?: Record<string, string>;
@@ -129,6 +133,8 @@ function providerFingerprint(entry: DiscoveryProviderEntry): string {
 		entry.apiKey ?? "",
 		entry.headers ?? {},
 		entry.compat ?? {},
+		// 未配置 modelsUrl 时保留已有指纹，避免让旧缓存失效。
+		...(entry.modelsUrl ? [entry.modelsUrl] : []),
 	]);
 }
 
@@ -244,6 +250,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:
@@ -288,7 +295,7 @@ function resolveEnvValue(raw: string): { value: string | null; error: string | n
 	return { value, error: null };
 }
 
-function buildModel(
+export function buildModel(
 	id: string,
 	name: string | undefined,
 	contextWindow: number | undefined,
@@ -299,6 +306,9 @@ function buildModel(
 		id,
 		name: name ?? id,
 		reasoning: true,
+		// xhigh/max 必须给非 null 值才会出现在 /thinking（缺省键等同不支持）；
+		// 标准档位保持缺省，仍走 pi 的 provider 默认映射，语义不变。
+		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
 		input: ["text", "image"],
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 		contextWindow: contextWindow ?? 1_000_000,
@@ -310,7 +320,12 @@ 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[],
@@ -339,7 +354,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) });
@@ -368,11 +383,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);
@@ -536,7 +551,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) {