pi-models-discovery 1.4.0 → 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,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 兼容服务。
 
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-models-discovery",
-  "version": "1.4.0",
+  "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",

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 触发在线刷新时重新发现；
@@ -80,6 +80,7 @@ interface DiscoveryProviderEntry {
 	id: string;
 	name?: string;
 	baseUrl?: string;
+	modelsUrl?: string;
 	apiKey?: string;
 	api?: string;
 	headers?: Record<string, string>;
@@ -132,6 +133,8 @@ function providerFingerprint(entry: DiscoveryProviderEntry): string {
 		entry.apiKey ?? "",
 		entry.headers ?? {},
 		entry.compat ?? {},
+		// 未配置 modelsUrl 时保留已有指纹，避免让旧缓存失效。
+		...(entry.modelsUrl ? [entry.modelsUrl] : []),
 	]);
 }
 
@@ -247,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:
@@ -316,7 +320,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 +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) });
@@ -374,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);
@@ -542,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) {