agentsw 0.9.0 → 0.9.2

package/README.md

@@ -18,14 +18,14 @@ without touching the settings you hand-tuned.
 </div>
 
 ```console
-$ asw use vfing -m glm-5.3-flash
-switching to vfing (openai) · default model glm-5.3-flash
+$ asw use myproxy -m glm-5.3-flash
+switching to myproxy (openai) · default model glm-5.3-flash
 
 skip claude    Claude Code does not support openai-protocol providers
 ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
                backup: ~/.config/agentsw/backups/transaction-<unique>
 ok   omp       ~/.omp/agent/models.yml
-               select in omp with: omp --model vfing/glm-5.3-flash
+               select in omp with: omp --model myproxy/glm-5.3-flash
 skip pi        pi not detected (pass --apps pi to force)
 ok   opencode  ~/.config/opencode/opencode.json
 ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
@@ -73,35 +73,35 @@ when a portable home directory is desired.
 ## Quick start
 
 ```bash
-agentsw                   # no args: interactive menu (add, import, use, status, apps)
+npx agentsw               # no install needed — opens the interactive menu
+agentsw                   # once installed globally; the short alias `asw` is identical
 ```
 
-The first run on an empty store offers to import the providers already configured in your
-agents, and asks for English or 简体中文. Prefer flags? The same flow, unattended:
+**Run it with no arguments and you get a menu — that is the whole tool.** Every action lives
+there: add a provider (auto-detect or manual setup), import the providers already configured in
+your agents, switch provider and default model, re-sync, update a model list, configure model
+metadata, rename or delete, install/upgrade an agent, change language. On the first run it asks
+for English or 简体中文 and offers to adopt what your agents are already using.
 
-```bash
-# add a provider and let it discover its own model list
-asw add -y --id vfing --protocol openai --openai-api responses \
-  --base-url https://api.example.com/v1 --api-key sk-... --discover
+Each menu action has a command equivalent for scripts, CI and headless machines — see
+[Commands](#commands). Examples below are written as `asw`; without a global install, run them
+as `npx agentsw <command>`.
 
-asw use vfing             # point every detected agent at it
-asw use vfing --dry-run   # ...or just show the diffs
-asw status                # what each agent points at right now
-```
+One command that needs no menu — `asw status` prints what each agent currently points at:
 
 ```console
 $ asw status
 config: ~/.config/agentsw/config.json
-active provider: vfing
-
-APP        FOUND  PROTOCOLS         CURRENT                               CONFIG
----------  -----  ----------------  ------------------------------------  ---------------------------
-claude     yes    anthropic         -                                     ~/.claude/settings.json
-codex      yes    openai            vfing · glm-5.3-flash                 ~/.codex/config.toml
-omp        yes    openai+anthropic  providers: sub, sub-anthropic, vfing  ~/.omp/agent/models.yml
-pi         no     openai+anthropic  -                                     ~/.pi/agent/models.json
-opencode   yes    openai+anthropic  vfing/glm-5.3-flash                   ~/.config/opencode/opencode.json
-dsh        yes    openai+anthropic  vfing · glm-5.3-flash                 ~/.dsh/settings.yaml
+active provider: myproxy
+
+APP       FOUND  PROTOCOLS         CURRENT                                 CONFIG
+--------  -----  ----------------  --------------------------------------  --------------------------------
+claude    yes    anthropic         -                                       ~/.claude/settings.json
+codex     yes    openai            myproxy · glm-5.3-flash                 ~/.codex/config.toml
+omp       yes    openai+anthropic  providers: sub, sub-anthropic, myproxy  ~/.omp/agent/models.yml
+pi        no     openai+anthropic  -                                       ~/.pi/agent/models.json
+opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.config/opencode/opencode.json
+dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
 ## Supported apps
@@ -135,13 +135,14 @@ lists and source apps are unioned. Different protocols on the same host stay sep
 
 ```console
 $ asw import --all
+
 ID             PROTOCOL   BASE URL                                MODELS  FROM       KEY
 -------------  ---------  --------------------------------------  ------  ---------  ---
-any            anthropic  https://a-ocnfniawgw.cn-shanghai...     1       cc-switch  yes
-sub            openai     https://new.vfing.de/v1                 18      omp        yes
-sub-anthropic  anthropic  https://new.vfing.de                    18      omp        yes
+any            anthropic  https://a-long-reseller.example.com...  1       cc-switch  yes
+sub            openai     https://api.example.com/v1              18      omp        yes
+sub-anthropic  anthropic  https://api.example.com                 18      omp        yes
 zhipu-glm      anthropic  https://open.bigmodel.cn/api/anthropic  1       cc-switch  yes
-imported sub · openai · https://new.vfing.de/v1 · 18 models [from omp]
+imported sub · openai · https://api.example.com/v1 · 18 models [from omp]
 imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 models [from cc-switch]
 ```
 
@@ -251,7 +252,7 @@ Import still skips already configured accounts.
 | `use <id>` | switch every detected agent; `-a codex,omp`, `-m <model>`, `--dry-run` |
 | `sync` | re-apply the active provider (after an agent update, say) |
 | `discover <id> [--sync]` | refresh the model list + metadata from `/v1/models` |
-| `models [query]` | search the models.dev catalog |
+| `models [query]` | search the models.dev catalog (`-r` refresh the cache, `-l <n>` limit rows) |
 | `refresh [--provider <id>]` | refresh saved metadata and optionally configure Gateway; keep the model list |
 | `models --provider <id> --metadata` | inspect field sources, conflicts and reference pricing as JSON |
 | `prune <id>` / `remove <id> [--prune]` | remove from app configs / from the store |
@@ -259,7 +260,11 @@ Import still skips already configured accounts.
 | `apps` / `install <app>` / `upgrade` | agent version manager |
 
 ```bash
-asw use myproxy -a codex,omp -m glm-5.2
+# unattended add: discover the provider's model list, then write it everywhere
+asw add -y --id myproxy --protocol openai --openai-api responses \
+  --base-url https://api.example.com/v1 --api-key sk-... --discover
+asw use myproxy                           # every detected agent
+asw use myproxy -a codex,omp -m glm-5.2   # ...or only these, with another default model
 asw discover myproxy --sync
 asw remove myproxy --prune
 ```
@@ -268,6 +273,13 @@ New automatic IDs include the full hostname and protocol, e.g. `api-example-com-
 An explicit `--id` is retained, and syncing never renames an existing provider. Import
 deduplication compares endpoint, protocol, and credentials; different accounts remain separate.
 
+A bare IP works the same way — every dot and colon becomes a dash, and the **port is not part
+of the ID**, so `http://152.53.108.231:3456` becomes `152-53-108-231-openai`. Two ports on that
+host therefore share a base ID and the second provider gets `-2` appended
+(`152-53-108-231-openai-2`); pass `--id` to name them yourself. IPv6 hosts lose their brackets
+and dashes (`https://[2001:db8::1]:8080` → `2001-db8-1-openai`), an IDN host uses its punycode
+form, and a base URL that cannot be parsed falls back to `imported`.
+
 ```bash
 asw rename myproxy api-example-com-openai --dry-run
 asw rename myproxy api-example-com-openai

package/README.zh-CN.md

@@ -18,14 +18,14 @@
 </div>
 
 ```console
-$ asw use vfing -m glm-5.3-flash
-switching to vfing (openai) · default model glm-5.3-flash
+$ asw use myproxy -m glm-5.3-flash
+switching to myproxy (openai) · default model glm-5.3-flash
 
 skip claude    Claude Code does not support openai-protocol providers
 ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
                backup: ~/.config/agentsw/backups/transaction-<unique>
 ok   omp       ~/.omp/agent/models.yml
-               select in omp with: omp --model vfing/glm-5.3-flash
+               select in omp with: omp --model myproxy/glm-5.3-flash
 skip pi        pi not detected (pass --apps pi to force)
 ok   opencode  ~/.config/opencode/opencode.json
 ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
@@ -71,35 +71,32 @@ npm install -g agentsw    # 需要 Node >= 22.13，内置 SQLite 无需额外启
 ## 快速开始
 
 ```bash
-agentsw                   # 不带参数：交互菜单（添加、导入、切换、状态、应用管理）
+npx agentsw               # 免安装，直接打开交互菜单
+agentsw                   # 全局安装后可用；短名 `asw` 完全等价
 ```
 
-存储为空时，首次运行会询问是否导入各智能体里已配置的供应商，并让你选择
-English 或简体中文。想用参数跑？同样的流程，全自动：
+**不带参数运行就是一个菜单——整个工具都在里面。** 添加供应商（自动识别或手动设置）、导入各智能体
+已有的供应商、切换供应商和默认模型、重新同步、更新模型列表、设置模型参数补充源、重命名或删除、
+安装/升级智能体、切换语言。首次运行会先问你要 English 还是简体中文，并提议接管你各智能体已经在用的配置。
 
-```bash
-# 添加供应商，并让它自己发现模型列表
-asw add -y --id vfing --protocol openai --openai-api responses \
-  --base-url https://api.example.com/v1 --api-key sk-... --discover
+菜单里的每项操作都有对应的命令，方便脚本、CI 和无头机器——见 [命令](#命令)。
+下文示例统一写作 `asw`；没有全局安装时，请改成 `npx agentsw <命令>`。
 
-asw use vfing             # 把所有检测到的智能体指向它
-asw use vfing --dry-run   # ……或者只看 diff
-asw status                # 各智能体当前指向什么
-```
+不用菜单也能看一眼——`asw status` 打印各智能体当前指向哪个供应商：
 
 ```console
 $ asw status
 config: ~/.config/agentsw/config.json
-active provider: vfing
-
-APP        FOUND  PROTOCOLS         CURRENT                               CONFIG
----------  -----  ----------------  ------------------------------------  ---------------------------
-claude     yes    anthropic         -                                     ~/.claude/settings.json
-codex      yes    openai            vfing · glm-5.3-flash                 ~/.codex/config.toml
-omp        yes    openai+anthropic  providers: sub, sub-anthropic, vfing  ~/.omp/agent/models.yml
-pi         no     openai+anthropic  -                                     ~/.pi/agent/models.json
-opencode   yes    openai+anthropic  vfing/glm-5.3-flash                   ~/.config/opencode/opencode.json
-dsh        yes    openai+anthropic  vfing · glm-5.3-flash                 ~/.dsh/settings.yaml
+active provider: myproxy
+
+APP       FOUND  PROTOCOLS         CURRENT                                 CONFIG
+--------  -----  ----------------  --------------------------------------  --------------------------------
+claude    yes    anthropic         -                                       ~/.claude/settings.json
+codex     yes    openai            myproxy · glm-5.3-flash                 ~/.codex/config.toml
+omp       yes    openai+anthropic  providers: sub, sub-anthropic, myproxy  ~/.omp/agent/models.yml
+pi        no     openai+anthropic  -                                       ~/.pi/agent/models.json
+opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.config/opencode/opencode.json
+dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
 ## 支持的应用
@@ -119,6 +116,11 @@ dsh        yes    openai+anthropic  vfing · glm-5.3-flash                 ~/.ds
 未安装的应用会被跳过，而不是瞎猜。`--apps codex,omp` 只跑指定应用；
 对未检测到的应用显式传 `--apps` 可强制写入。
 
+交互菜单写配置前会问同一个问题：多选框第一行是**全部检测到的应用**，已检测到的排在前面，
+未检测到的会标注出来。上次的选择会被记住，所以菜单里的 `use`/`sync` 只会继续写你勾选的那几个。
+任何配置文件解析失败（JSON/YAML/TOML 非法）都会报出文件与位置，绝不回显出错那一行；
+`--dry-run` 同样保留这些细节，而不是含糊带过。
+
 ## 导入你已有的配置
 
 `import` 读取每个智能体的配置**以及 cc-switch 的 SQLite 存储**（只读），解析内联或环境变量
@@ -127,13 +129,14 @@ dsh        yes    openai+anthropic  vfing · glm-5.3-flash                 ~/.ds
 
 ```console
 $ asw import --all
+
 ID             PROTOCOL   BASE URL                                MODELS  FROM       KEY
 -------------  ---------  --------------------------------------  ------  ---------  ---
-any            anthropic  https://a-ocnfniawgw.cn-shanghai...     1       cc-switch  yes
-sub            openai     https://new.vfing.de/v1                 18      omp        yes
-sub-anthropic  anthropic  https://new.vfing.de                    18      omp        yes
+any            anthropic  https://a-long-reseller.example.com...  1       cc-switch  yes
+sub            openai     https://api.example.com/v1              18      omp        yes
+sub-anthropic  anthropic  https://api.example.com                 18      omp        yes
 zhipu-glm      anthropic  https://open.bigmodel.cn/api/anthropic  1       cc-switch  yes
-imported sub · openai · https://new.vfing.de/v1 · 18 models [from omp]
+imported sub · openai · https://api.example.com/v1 · 18 models [from omp]
 imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 models [from cc-switch]
 ```
 
@@ -234,7 +237,7 @@ asw sync --provider myproxy
 | `use <id>` | 切换所有检测到的智能体；`-a codex,omp`、`-m <model>`、`--dry-run` |
 | `sync` | 重新应用当前供应商（比如某个智能体升级之后） |
 | `discover <id> [--sync]` | 从 `/v1/models` 刷新模型列表与元数据 |
-| `models [query]` | 搜索 models.dev 目录 |
+| `models [query]` | 搜索 models.dev 目录（`-r` 强制刷新缓存，`-l <n>` 限制条数） |
 | `refresh [--provider <id>]` | 刷新已有模型参数，可设置 Gateway 补充源，不改变模型列表 |
 | `models --provider <id> --metadata` | 以 JSON 查看字段来源、冲突和参考价格 |
 | `prune <id>` / `remove <id> [--prune]` | 从各应用配置中清除 / 从存储中删除 |
@@ -242,7 +245,11 @@ asw sync --provider myproxy
 | `apps` / `install <app>` / `upgrade` | 智能体版本管理 |
 
 ```bash
-asw use myproxy -a codex,omp -m glm-5.2
+# 无人值守：添加供应商并自动发现模型列表，然后写入所有智能体
+asw add -y --id myproxy --protocol openai --openai-api responses \
+  --base-url https://api.example.com/v1 --api-key sk-... --discover
+asw use myproxy                           # 所有检测到的智能体
+asw use myproxy -a codex,omp -m glm-5.2   # ……或只写这几个，并换一个默认模型
 asw discover myproxy --sync
 asw remove myproxy --prune
 ```
@@ -251,6 +258,13 @@ asw remove myproxy --prune
 显式指定的 `--id` 会保留，同步不会自动重命名。导入去重会同时比较端点、协议和凭据，
 不同账号保持独立；同一账号的自定义名称优先于自动生成名称。
 
+纯 IP 的填写方式完全一样——域名里的每个点和冒号都变成短横线，**端口不属于 ID**：
+`http://152.53.108.231:3456` 生成的 ID 是 `152-53-108-231-openai`。因此同一 IP 上的两个端口
+共用一个基础 ID，第二个供应商会自动带上 `-2`（`152-53-108-231-openai-2`）；
+想区分请自己传 `--id`。IPv6 会去掉方括号并把冒号变短横线
+（`https://[2001:db8::1]:8080` → `2001-db8-1-openai`），国际化域名使用 punycode，
+无法解析的 base URL 退回 `imported`。
+
 ```bash
 asw rename myproxy api-example-com-openai --dry-run
 asw rename myproxy api-example-com-openai

package/dist/commands.js

@@ -8,7 +8,7 @@ import prompts from "prompts";
 import { loadStore, saveStore, getProvider, configFile } from "./store.js";
 import { scanCandidates, normalizeUrl, findMatchingProvider } from "./import.js";
 import { loadCatalog, searchCatalog } from "./modelsdev.js";
-import { enrichProviderModels, getMetadataMode, resolveMetadataOptions } from "./metadata.js";
+import { classifyUnresolved, enrichProviderModels, getMetadataMode, resolveMetadataOptions } from "./metadata.js";
 import { loadGatewayCatalog } from "./gateway.js";
 import { resolveTargets, supportsProtocol, targets } from "./targets/index.js";
 import { discoverProviderModels, probeProtocols } from "./discover.js";
@@ -70,11 +70,19 @@ function modelRows(models) {
     ]);
 }
 const MODEL_HEADER = ["MODEL", "CTX", "IN", "OUT", "REASONING", "$IN/$OUT per M"];
-/** Print a dim hint when some models have no catalog metadata. */
-function printUncatalogedHint(models) {
+/**
+ * Explain why some models stayed bare: only ambiguous ids are worth the user's
+ * attention, so those are named separately from ids nothing can resolve.
+ */
+function printUncatalogedHint(models, catalog, hint) {
     const bare = models.filter((m) => m.contextWindow === undefined && !m.cost);
-    if (bare.length > 0) {
-        console.log(pc.dim(`${bare.length} model(s) have no catalog metadata (shown as "-")`));
+    if (bare.length === 0)
+        return;
+    console.log(pc.dim(t("meta.gap", { count: bare.length })));
+    const { ambiguous, unknown, noCreatorRow } = classifyUnresolved(catalog, bare.map((m) => m.id), hint);
+    for (const [key, ids] of [["meta.ambiguous", ambiguous], ["meta.noCreatorRow", noCreatorRow], ["meta.unknown", unknown]]) {
+        if (ids.length)
+            console.log(pc.dim(`  ${t(key, { count: ids.length, ids: ids.join(", "), id: ids[0] })}`));
     }
 }
 /** Guess the models.dev provider whose API host matches the configured baseUrl. */
@@ -197,8 +205,15 @@ export async function cmdAdd(opts) {
         fail(t("add.openaiApiInvalid"));
     const baseUrl = normalizeUrl(answers.baseUrl);
     const explicitId = answers.id || undefined;
-    const existing = explicitId ? store.providers[explicitId] : findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey: answers.apiKey });
-    const id = explicitId ?? existing?.id ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
+    const byId = explicitId ? store.providers[explicitId] : undefined;
+    // Endpoint plus credential is the account identity, so an explicit id never
+    // licenses a second entry for an account that is already configured.
+    const sameAccount = byId ? undefined : findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey: answers.apiKey });
+    const existing = byId ?? sameAccount;
+    if (byId === undefined && explicitId && sameAccount) {
+        console.log(pc.yellow(t("add.alreadyConfigured", { id: pc.bold(sameAccount.id) })));
+    }
+    const id = byId?.id ?? sameAccount?.id ?? explicitId ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
     const openaiApi = protocol === "openai" ? wire ?? existing?.openaiApi : undefined;
     const metadataOptions = resolveMetadataOptions(opts, existing);
     const manualIds = (answers.models ?? "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -256,7 +271,7 @@ export async function cmdAdd(opts) {
     console.log(pc.green(t("add.saved", { status: savedStatus, id: pc.bold(provider.id), protocol })));
     console.log(t("add.metadata", { matched, total: models.length }) + (hint ? t("add.providerHint", { hint }) : ""));
     console.log(table(modelRows(models), MODEL_HEADER));
-    printUncatalogedHint(models);
+    printUncatalogedHint(models, catalog, hint);
     console.log(pc.dim(`\n${t("add.next", { id: provider.id })}`));
 }
 /** Shared logic to create and save a single provider from discovered models. */
@@ -297,7 +312,7 @@ async function createProvider(opts) {
     console.log(pc.green(t("add.saved", { status: savedStatus, id: pc.bold(provider.id), protocol })));
     console.log(t("add.metadata", { matched, total: models.length }) + (hint ? t("add.providerHint", { hint }) : ""));
     console.log(table(modelRows(models), MODEL_HEADER));
-    printUncatalogedHint(models);
+    printUncatalogedHint(models, catalog, hint);
     return provider;
 }
 /**
@@ -339,8 +354,13 @@ export async function cmdQuickAdd(opts) {
     const gatewayLoader = sharedGatewayLoader();
     for (const protocol of protocols) {
         const explicitId = opts.id === undefined ? undefined : `${opts.id}${multi ? `-${protocol}` : ""}`;
-        const existing = explicitId === undefined ? findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey }) : store.providers[explicitId];
-        const id = explicitId ?? existing?.id ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
+        const byId = explicitId ? store.providers[explicitId] : undefined;
+        const sameAccount = byId ? undefined : findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey });
+        const existing = byId ?? sameAccount;
+        if (byId === undefined && explicitId && sameAccount) {
+            console.log(pc.yellow(t("add.alreadyConfigured", { id: pc.bold(sameAccount.id) })));
+        }
+        const id = byId?.id ?? sameAccount?.id ?? explicitId ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
         const name = opts.name ?? existing?.name ?? (opts.id === undefined ? providerNameFromBaseUrl(baseUrl, protocol) : multi ? `${opts.id} (${protocol})` : opts.id);
         const modelFilter = parseFilterOpts(opts, existing?.modelFilter);
         process.stderr.write(pc.dim(`${t("add.discovering", { url: baseUrl })} [${protocol}]\n`));
@@ -641,7 +661,7 @@ export async function cmdModels(query, opts) {
         }
         console.log(`${pc.bold(provider.id)} (${provider.protocol}) · ${provider.baseUrl}`);
         console.log(table(modelRows(provider.models), MODEL_HEADER));
-        printUncatalogedHint(provider.models);
+        printUncatalogedHint(provider.models, await loadCatalog(), provider.modelsDevId);
         return;
     }
     const catalog = await loadCatalog({ refresh: opts.refresh });
@@ -680,9 +700,11 @@ export async function cmdRefreshMeta(opts = {}) {
             updated++;
     }
     saveStore(store);
-    console.log(pc.green(`checked model metadata (${updated} provider(s) changed)`));
+    console.log(pc.green(t("refresh.checked", { changed: updated })));
     if (updated > 0)
-        console.log(pc.dim("run `agentsw sync` to push updated metadata into app configs"));
+        console.log(pc.dim(t("refresh.next")));
+    for (const provider of providers)
+        printUncatalogedHint(provider.models, catalog, provider.modelsDevId);
 }
 export async function cmdDiscover(id, opts) {
     resolveTargets(opts.apps);
@@ -715,7 +737,7 @@ export async function cmdDiscover(id, opts) {
         (added.length ? `\n  new: ${added.join(", ")}` : "") +
         (gone.length ? `\n  removed upstream: ${gone.join(", ")}` : ""));
     console.log(table(modelRows(provider.models), MODEL_HEADER));
-    printUncatalogedHint(provider.models);
+    printUncatalogedHint(provider.models, catalog, provider.modelsDevId);
     if (opts.sync) {
         console.log("");
         await cmdSync({ provider: id, apps: opts.apps });

package/dist/i18n.js

@@ -190,6 +190,7 @@ const messages = {
     "add.defaultMissing": { en: "default model {model} is not in the model list", "zh-CN": "默认模型 {model} 不在模型列表中" },
     "add.smallMissing": { en: "small model {model} is not in the model list", "zh-CN": "小型模型 {model} 不在模型列表中" },
     "add.added": { en: "added", "zh-CN": "已添加" },
+    "add.alreadyConfigured": { en: "same endpoint and key are already configured as {id}; updating it instead of creating a duplicate", "zh-CN": "相同地址与密钥已配置为 {id};将更新该供应商,不会新建重复项" },
     "add.updated": { en: "updated", "zh-CN": "已更新" },
     "add.saved": { en: "{status} provider {id} ({protocol})", "zh-CN": "{status}供应商 {id} ({protocol})" },
     "add.metadata": { en: "model metadata: {matched}/{total} models have a context limit", "zh-CN": "模型参数：{matched}/{total} 个模型已有上下文上限" },
@@ -245,6 +246,18 @@ const messages = {
     "status.config": { en: "config: {file}", "zh-CN": "配置:{file}" },
     "status.active": { en: "active provider: {id}", "zh-CN": "当前供应商:{id}" },
     "status.none": { en: "(none)", "zh-CN": "(无)" },
+    "meta.gap": { en: "{count} model(s) have no catalog metadata (shown as \"-\")", "zh-CN": "{count} 个模型没有目录元数据(显示为 \"-\")" },
+    "meta.ambiguous": {
+        en: "ambiguous ({count}): {ids} — several creators list these; pin with --gateway-models '{\"{id}\":\"creator/model\"}'",
+        "zh-CN": "存在歧义({count}):{ids} —— 多个厂商都提供;用 --gateway-models '{\"{id}\":\"creator/model\"}' 指定",
+    },
+    "meta.unknown": { en: "not listed by any creator ({count}): {ids}", "zh-CN": "所有厂商均未收录({count}):{ids}" },
+    "meta.noCreatorRow": {
+        en: "no models.dev row for the creator ({count}): {ids} — filled from AI Gateway when available",
+        "zh-CN": "厂商在 models.dev 无对应条目({count}):{ids} —— 有 AI Gateway 数据时会自动补全",
+    },
+    "refresh.checked": { en: "checked model metadata ({changed} provider(s) changed)", "zh-CN": "已检查模型元数据({changed} 个供应商有变化)" },
+    "refresh.next": { en: "run `agentsw sync` to push updated metadata into app configs", "zh-CN": "运行 `agentsw sync` 将更新的元数据写入各智能体配置" },
 };
 let current = detectSystemLocale();
 export function normalizeLocale(value) {

package/dist/metadata.js

@@ -105,25 +105,42 @@ function equalValue(a, b) {
 function indexCatalog(catalog) {
     const exact = new Map();
     const canonical = new Map();
+    const identities = new Map();
+    const push = (map, key, entry) => {
+        const matches = map.get(key);
+        if (matches)
+            matches.push(entry);
+        else
+            map.set(key, [entry]);
+    };
     for (const provider of Object.values(catalog)) {
         for (const [key, model] of Object.entries(provider.models)) {
             const modelId = model.id.includes("/") ? model.id : `${provider.id}/${model.id}`;
-            const entry = { provider: provider.id, modelId, model };
-            for (const id of new Set([key, model.id])) {
-                const matches = exact.get(id);
-                if (matches)
-                    matches.push(entry);
-                else
-                    exact.set(id, [entry]);
-            }
-            const matches = canonical.get(modelId);
-            if (matches)
-                matches.push(entry);
-            else
-                canonical.set(modelId, [entry]);
+            const entry = { provider: provider.id, modelId, identity: model.canonical_model_id ?? modelId, model };
+            for (const id of new Set([key, model.id]))
+                push(exact, id, entry);
+            push(canonical, modelId, entry);
+            push(identities, entry.identity, entry);
         }
     }
-    return { exact, canonical };
+    return { exact, canonical, identities };
+}
+/** Creator identity of a catalog model id, or undefined when its rows disagree. */
+function catalogIdentity(index, modelId) {
+    const identities = new Set(index?.canonical.get(modelId)?.map((entry) => entry.identity));
+    return identities?.size === 1 ? [...identities][0] : undefined;
+}
+/**
+ * The creator's own listing for an identity, when models.dev carries one.
+ * Gateways also key their rows by the canonical id, and those rows carry the
+ * gateway's own limits and prices, so only a row from the creator's own
+ * namespace counts as authoritative.
+ */
+function creatorEntry(index, identity) {
+    const slash = identity.indexOf("/");
+    if (slash < 1)
+        return undefined;
+    return index?.identities.get(identity)?.find((entry) => entry.modelId === identity && entry.provider === identity.slice(0, slash));
 }
 function indexGatewayBareIds(gateway) {
     const result = new Map();
@@ -147,10 +164,15 @@ function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
             const candidate = gatewayBareIds?.get(id);
             const evidence = index?.exact.get(id);
             const hintedEvidence = hint ? evidence?.filter((entry) => entry.provider === hint) : undefined;
-            const identities = new Set((hintedEvidence?.length ? hintedEvidence : evidence)?.map((entry) => entry.modelId));
+            const identities = new Set((hintedEvidence?.length ? hintedEvidence : evidence)?.map((entry) => entry.identity));
+            // Gateway names the creator while models.dev names the listing provider, so
+            // the two agree only once both are reduced to a creator identity. A gateway
+            // id the catalog has no row for stands for itself.
+            const candidateIdentity = candidate ? catalogIdentity(index, candidate) ?? candidate : undefined;
             // A unique exact basename is safe only with absent or agreeing primary evidence.
             // Explicit provider hints can resolve primary ambiguity, but never Gateway ambiguity.
-            if (candidate && (identities.size === 0 || (identities.size === 1 && identities.has(candidate))))
+            if (candidate && candidateIdentity !== undefined
+                && (identities.size === 0 || (identities.size === 1 && identities.has(candidateIdentity))))
                 gatewayId = candidate;
         }
     }
@@ -159,10 +181,10 @@ function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
         : (bare && hint ? index?.canonical.get(`${hint}/${id}`) : undefined)
             ?? index?.canonical.get(id) ?? index?.exact.get(id);
     const hinted = candidates?.find((entry) => entry.provider === hint);
-    const identities = new Set(candidates?.map((entry) => entry.modelId));
-    const primary = hinted ?? (identities.size === 1
-        ? candidates?.find((entry) => entry.modelId.startsWith(`${entry.provider}/`)) ?? candidates?.[0]
-        : undefined);
+    const identities = new Set(candidates?.map((entry) => entry.identity));
+    // Reseller rows for one model share an identity but disagree on limits and
+    // prices, so only the creator's own row is authoritative.
+    const primary = hinted ?? (identities.size === 1 ? creatorEntry(index, [...identities][0]) : undefined);
     return { primary, gatewayId, alias };
 }
 function legacyPrimary(catalog, id, hint) {
@@ -398,3 +420,30 @@ export async function enrichProviderModels(catalog, ids, settings, options = {})
     // bounds must be resolved with the supplement against the original values.
     return gateway ? enrich(gateway) : primaryOnly ?? enrich();
 }
+/**
+ * Why a model id stayed bare after enrichment, so callers can tell the user
+ * what is worth acting on: "ambiguous" ids are listed under more than one
+ * creator and an explicit mapping resolves them; "unknown" ids no creator
+ * lists at all, so no mapping helps; "noCreatorRow" ids have one unambiguous
+ * creator but models.dev carries no authoritative row for it, so only Gateway
+ * can fill them.
+ */
+export function classifyUnresolved(catalog, ids, hint) {
+    const ambiguous = [];
+    const unknown = [];
+    const noCreatorRow = [];
+    if (!catalog)
+        return { ambiguous, unknown: [...ids], noCreatorRow };
+    const index = indexCatalog(catalog);
+    for (const id of ids) {
+        const hinted = hint ? index.canonical.get(`${hint}/${id}`) : undefined;
+        const candidates = hinted ?? index.canonical.get(id) ?? index.exact.get(id);
+        if (!candidates?.length)
+            unknown.push(id);
+        else if (new Set(candidates.map((entry) => entry.identity)).size > 1)
+            ambiguous.push(id);
+        else if (!creatorEntry(index, [...new Set(candidates.map((entry) => entry.identity))][0]))
+            noCreatorRow.push(id);
+    }
+    return { ambiguous, unknown, noCreatorRow };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsw",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "CLI provider switcher for coding agents: manage OpenAI/Anthropic-protocol providers in one place and sync them, with models.dev metadata, into Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy and DeepSeek Harness",
   "type": "module",
   "repository": {