pi-models-discovery 1.0.0 → 1.1.0

package/README.md

@@ -15,7 +15,7 @@ pi install npm:pi-models-discovery
 ### Option 1: interactive configuration inside pi (recommended)
 
 ```
-/model-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.
@@ -42,12 +42,12 @@ 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.
 
-Hand edits require `/reload` to take effect; changes made through `/model-discovery` apply immediately.
+Hand edits require `/reload` to take effect; changes made through `/config:model-discovery` apply immediately.
 
 ## Refreshing the cache
 
 ```
-/model-discovery-refresh
+/config:model-discovery-refresh
 ```
 
 Forces a rediscovery of every discovery provider and updates the local cache, notifying the result for each provider.
@@ -55,12 +55,14 @@ 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.
-- **Online refresh**: `/model-discovery-refresh`, or the `refreshModels` hook triggered when opening `/model`, rediscovers online and updates the cache.
+- **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.
 - 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.
+
 ## Uninstall
 
 ```bash

package/README.zh-CN.md

@@ -15,7 +15,7 @@ pi install npm:pi-models-discovery
 ### 方式一：pi 终端内交互配置（推荐）
 
 ```
-/model-discovery
+/config:model-discovery
 ```
 
 交互式添加 / 删除 / 重新发现 provider：输入 id、baseUrl、api 类型、apiKey（可留空）、显示名（可留空），确认后写入 models.json 并**立即生效**（无需 /reload）。写入前自动备份到 `models.json.discovery-bak`。
@@ -42,12 +42,12 @@ pi install npm:pi-models-discovery
 
 `baseUrl` 和 `api` 必填；`apiKey` 可选（无鉴权服务可省略）。同一 `baseUrl+apiKey` 的多个 provider 共享一次 `/models` 请求。
 
-手编方式修改配置后需 `/reload` 生效；`/model-discovery` 命令的修改立即生效。
+手编方式修改配置后需 `/reload` 生效；`/config:model-discovery` 命令的修改立即生效。
 
 ## 刷新缓存
 
 ```
-/model-discovery-refresh
+/config:model-discovery-refresh
 ```
 
 强制重新拉取所有发现 provider 的模型列表并更新本地缓存，逐个 notify 结果。
@@ -55,12 +55,14 @@ pi install npm:pi-models-discovery
 ## 行为
 
 - **启动（缓存优先）**：缓存命中时直接用持久化的模型列表注册，零网络请求；缓存文件位于 `~/.pi/agent/extensions/pi-models-discovery/cache.json`。provider 配置指纹（baseUrl+api+apiKey+headers+compat）变化时缓存自动失效，重新走网络发现。
-- **在线刷新**：`/model-discovery-refresh` 或 `/model` 打开时触发的 `refreshModels` 在线重新发现，并同步更新缓存。
+- **在线刷新**：`/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` 会合并进每个发现的模型。
 - 模型元数据可携带 `name` / `context_window`（或 `contextWindow`）/ `max_tokens`（或 `maxTokens`），缺失时用默认值。
 
+旧的 `/model-discovery`、`/model-discovery-refresh`、`/pi-model-discovery` 和 `/pi-model-discovery-refresh` 名称仍作为兼容别名保留。
+
 ## 卸载
 
 ```bash

package/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: configure-pi-models-discovery
+description: "配置与排查 models.json 的动态模型发现、缓存刷新、鉴权和离线回退。Use when adding discoverModels providers or refreshing model catalogs."
+---
+
+# 配置 pi-models-discovery
+
+## 诊断
+
+读取实际 Pi agent 目录中的：
+
+- `models.json`：provider 配置；
+- `extensions/pi-models-discovery/cache.json`：启动缓存；
+- `models.json.discovery-bak`：交互配置写回前的备份。
+
+只处理带 `discoverModels: true` 的 provider。确认 `baseUrl`、`api`、可选 `apiKey`、headers/compat 以及服务的 `GET {baseUrl}/models` 响应。
+
+## 修改
+
+优先使用 `/config:model-discovery` 添加、删除或重新发现 provider；命令会备份并格式化重写 `models.json`，注释与原排版不会保留。手工修改时，provider 至少提供 `baseUrl`、`api`、`discoverModels: true`；修改后需要 `/reload`。
+
+`apiKey` 可用字面量、`$ENV_VAR` 或 `${ENV_VAR}`；`!command` 不用于发现请求，会被跳过并警告。不要把密钥写入 Skill、仓库或回复。
+
+## 验证
+
+- `/config:model-discovery-refresh` 强制联网刷新并更新缓存；旧命令名仅为兼容别名。
+- 打开 `/model` 也会触发在线刷新。
+- 逐个 provider 报告成功或失败。失败时可保留 `models.json` 中手写的 `models` 作为显式离线回退，但不能把缓存或静态模型冒充本次发现成功。

package/locales/index.json

@@ -8,8 +8,8 @@
     "en-US": "Force rediscovery of all model-discovery providers and update the local cache (startup uses the cache and performs no network requests by default)"
   },
   "refreshEmpty": {
-    "zh-CN": "models.json 中没有标记 discoverModels 的 provider，可用 /model-discovery 添加",
-    "en-US": "No provider in models.json is marked with discoverModels; add one with /model-discovery"
+    "zh-CN": "models.json 中没有标记 discoverModels 的 provider，可用 /config:model-discovery 添加",
+    "en-US": "No provider in models.json is marked with discoverModels; add one with /config:model-discovery"
   },
   "refreshDone": {
     "zh-CN": "模型刷新完成：{ok}/{total} 个 provider 成功",
@@ -148,8 +148,8 @@
     "en-US": "{id}: discovered and registered {count} models; they are available in /model"
   },
   "firstFailed": {
-    "zh-CN": "{id}: 配置已保存，但首次发现失败；服务恢复后可在 /model-discovery 中重新发现",
-    "en-US": "{id}: configuration saved, but initial discovery failed; rediscover with /model-discovery after the service recovers"
+    "zh-CN": "{id}: 配置已保存，但首次发现失败；服务恢复后可在 /config:model-discovery 中重新发现",
+    "en-US": "{id}: configuration saved, but initial discovery failed; rediscover with /config:model-discovery after the service recovers"
   },
   "rediscover": {
     "zh-CN": "🔄 重新发现模型",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-models-discovery",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pi extension: discover models from {baseUrl}/models for providers marked with discoverModels in models.json",
   "type": "module",
   "main": "./index.ts",
@@ -12,7 +12,8 @@
     "src",
     "locales",
     "README.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "SKILL.md"
   ],
   "scripts": {
     "test": "tsx --test tests/catalog.test.ts",
@@ -22,7 +23,11 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
     ]
   },
   "engines": {
@@ -49,14 +54,15 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.80.0 <0.81.0",
-    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
-    "pi-extensions-i18n": "^0.3.0"
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0"
+  },
+  "dependencies": {
+    "pi-extensions-i18n": "^0.4.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.80.10",
     "@earendil-works/pi-coding-agent": "0.80.10",
     "@types/node": "24.12.4",
-    "pi-extensions-i18n": "^0.3.0",
     "tsx": "4.23.1",
     "typescript": "5.9.3"
   }

package/src/index.ts

@@ -5,7 +5,7 @@
  * GET {baseUrl}/models 自动发现模型并注册，无需手写 models 数组。
  *
  * 配置方式（二选一）：
- * 1. pi 终端内执行 /model-discovery，交互式添加/删除/重新发现 provider（推荐）；
+ * 1. pi 终端内执行 /config:model-discovery，交互式添加/删除/重新发现 provider（推荐）；
  * 2. 直接编辑 ~/.pi/agent/models.json：
  * {
  *   "providers": {
@@ -23,7 +23,7 @@
  * - 首次发现成功后，模型列表持久化到 ~/.pi/agent/extensions/pi-models-discovery/cache.json；
  *   之后每次启动直接读缓存注册，不请求网络。配置指纹
  *   （baseUrl+api+apiKey+headers+compat）变化时缓存自动失效，重新走网络发现。
- * - /model-discovery-refresh 强制重新拉取所有发现 provider 并更新缓存；
+ * - /config:model-discovery-refresh 强制重新拉取所有发现 provider 并更新缓存；
  *   /model 打开时触发的在线 refreshModels 同样走网络并同步更新缓存。
  * - baseUrl / api 由扩展显式转发（pi 的 extension 组合层要求），
  *   apiKey / name / headers / compat 不写回注册配置，由 pi 的 models.json 层回落生效。
@@ -37,7 +37,7 @@
  *   以免空列表清掉 models.json 手写 models。
  * - 发现请求的 apiKey 解析仅支持字面量与 $ENV_VAR/${ENV_VAR} 插值；
  *   "!command" 形式的 apiKey 跳过发现（显式警告），pi 发起聊天请求时仍由 pi 自身解析。
- * - /model-discovery 命令对 models.json 的修改立即生效（registerProvider 运行时可直接调用）；
+ * - /config:model-discovery 命令对 models.json 的修改立即生效（registerProvider 运行时可直接调用）；
  *   直接手编 models.json 后需 /reload 扩展生效。
  * - 本插件不使用 console.*：所有用户可见消息走 ctx.ui.notify；
  *   加载期（无 ctx）产生的消息收集到 pendingNotices，session_start 时统一 flush。
@@ -417,7 +417,7 @@ function validateEntry(entry: DiscoveryProviderEntry, notices: Notice[]): entry
 
 /**
  * 对单个 provider 执行模型发现并注册（成功带 models，失败保留手写回退）。
- * 启动期缓存未命中时与 /model-discovery、/model-discovery-refresh 命令共用；
+ * 启动期缓存未命中时与 /config:model-discovery、/config:model-discovery-refresh 命令共用；
  * 运行期调用立即生效，无需 /reload。
  * 成功时持久化模型缓存；返回发现的模型列表（失败为 null），消息写入 notices。
  * 注意：本函数不再主动输出“发现成功”信息；调用方按需自行 notify，
@@ -476,9 +476,9 @@ function registerFromCache(
 	});
 }
 
-/** /model-discovery 交互式配置命令 */
+/** /config:model-discovery 交互式配置命令；旧名称保留为兼容别名。 */
 function registerDiscoveryCommand(pi: ExtensionAPI, fetchCache: FetchCache) {
-	pi.registerCommand("model-discovery", {
+	const command = {
 		description: i18n.t("commandDescription"),
 		handler: async (_args, ctx) => {
 			if (!ctx.hasUI) return;
@@ -512,12 +512,15 @@ function registerDiscoveryCommand(pi: ExtensionAPI, fetchCache: FetchCache) {
 				}
 			}
 		},
-	});
+	};
+	for (const name of ["config:model-discovery", "model-discovery", "pi-model-discovery"] as const) {
+		pi.registerCommand(name, command);
+	}
 }
 
-/** /model-discovery-refresh 强制刷新命令：绕过启动缓存，重拉所有发现 provider 并更新持久化缓存 */
+/** /config:model-discovery-refresh 强制刷新命令；旧名称保留为兼容别名。 */
 function registerRefreshCommand(pi: ExtensionAPI) {
-	pi.registerCommand("model-discovery-refresh", {
+	const command = {
 		description: i18n.t("refreshDescription"),
 		handler: async (_args, ctx) => {
 			if (!ctx.hasUI) return;
@@ -551,7 +554,10 @@ function registerRefreshCommand(pi: ExtensionAPI) {
 				ok === providers.length ? "info" : "warning",
 			);
 		},
-	});
+	};
+	for (const name of ["config:model-discovery-refresh", "model-discovery-refresh", "pi-model-discovery-refresh"] as const) {
+		pi.registerCommand(name, command);
+	}
 }
 
 type CommandCtx = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>[1];
@@ -561,7 +567,7 @@ function flushNotices(ctx: CommandCtx, notices: Notice[]): void {
 	for (const notice of notices) ctx.ui.notify(notice.message, notice.level);
 }
 
-/** /model-discovery 添加 provider 交互流程 */
+/** /config:model-discovery 添加 provider 交互流程 */
 async function addProviderFlow(pi: ExtensionAPI, ctx: CommandCtx, data: Record<string, unknown>, fetchCache: FetchCache) {
 	const existingIds = new Set(Object.keys((data.providers ?? {}) as Record<string, unknown>));
 	const id = (await ctx.ui.input(i18n.t("providerId")))?.trim();
@@ -617,7 +623,7 @@ async function addProviderFlow(pi: ExtensionAPI, ctx: CommandCtx, data: Record<s
 	}
 }
 
-/** /model-discovery 管理 provider（重新发现/删除）交互流程 */
+/** /config:model-discovery 管理 provider（重新发现/删除）交互流程 */
 async function manageProviderFlow(
 	pi: ExtensionAPI,
 	ctx: CommandCtx,