agentsw 0.7.1 → 0.8.0

package/dist/fsutil.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 // AGENTSW_HOME is an explicit portable/test override. Native Windows otherwise
 // uses USERPROFILE/os.homedir(), while Unix follows HOME as expected.
 export const home = process.env.AGENTSW_HOME?.trim() ||
@@ -24,14 +26,62 @@ export function expandHome(p) {
     return p.startsWith("~") ? path.join(home, p.slice(1)) : p;
 }
 export function ensureDir(dir) {
-    fs.mkdirSync(dir, { recursive: true });
+    if (isDryRun() || stagedFiles.getStore())
+        return;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/** Read exactly one regular file. A broken path or unreadable file is not an empty config. */
+export function readFileSnapshot(file) {
+    try {
+        const stat = fs.lstatSync(file, { bigint: true });
+        if (!stat.isFile())
+            throw new Error(`${file}: not a regular configuration file`);
+        return { text: fs.readFileSync(file, "utf8"), mode: Number(stat.mode & 511n), identity: `${stat.dev}:${stat.ino}` };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { text: undefined };
+        throw new Error(`${file}: cannot read a regular configuration file`);
+    }
+}
+const stagedFiles = new AsyncLocalStorage();
+function stagedSnapshot(scope, file) {
+    if (scope.closed)
+        throw new Error("configuration transaction already finished");
+    let snapshot = scope.reads.get(file);
+    if (!snapshot) {
+        snapshot = readFileSnapshot(file);
+        scope.reads.set(file, snapshot);
+    }
+    return snapshot;
+}
+/** Scope only this asynchronous adapter invocation, never unrelated filesystem calls. */
+export async function stageFileWrites(operation) {
+    if (stagedFiles.getStore())
+        throw new Error("nested configuration transaction is not supported");
+    const scope = { reads: new Map(), writes: new Map(), dryRun, closed: false };
+    try {
+        const result = await stagedFiles.run(scope, operation);
+        return { result, changes: [...scope.writes.values()], reads: scope.reads, dryRun: scope.dryRun };
+    }
+    finally {
+        scope.closed = true;
+    }
 }
 export function readTextIfExists(file) {
+    const scope = stagedFiles.getStore();
+    if (scope) {
+        file = path.resolve(file);
+        const snapshot = stagedSnapshot(scope, file);
+        return scope.writes.has(file) ? scope.writes.get(file).after : snapshot.text;
+    }
     try {
         return fs.readFileSync(file, "utf8");
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
     }
 }
 export function readJsonIfExists(file) {
@@ -40,9 +90,12 @@ export function readJsonIfExists(file) {
         return undefined;
     return JSON.parse(text);
 }
-/** dry-run mode: writeFileAtomic records intents instead of touching disk; backups are skipped */
+/** Compatibility preview switch. Each target captures its value when its scoped work starts. */
 let dryRun = false;
 const pendingWrites = [];
+export function isDryRun() {
+    return stagedFiles.getStore()?.dryRun ?? dryRun;
+}
 export function setDryRun(on) {
     dryRun = on;
     pendingWrites.length = 0;
@@ -50,25 +103,67 @@ export function setDryRun(on) {
 export function drainPendingWrites() {
     return pendingWrites.splice(0);
 }
-/** Atomic write: tmp file + rename. Creates parent dirs. In dry-run mode, records the intent instead. */
+/** Publish previews only after the adapter has validated all of its input files. */
+export function recordPendingWrites(changes) {
+    for (const change of changes) {
+        if (change.before !== change.after && change.after !== undefined) {
+            pendingWrites.push({ file: change.file, content: change.after });
+        }
+    }
+}
+/** Atomic replacement, preserving existing permissions and defaulting new secret files to 0600. */
 export function writeFileAtomic(file, content, mode) {
+    const scope = stagedFiles.getStore();
+    if (scope) {
+        file = path.resolve(file);
+        const expected = stagedSnapshot(scope, file);
+        scope.writes.set(file, { file, before: expected.text, after: content, mode, expected });
+        return;
+    }
     if (dryRun) {
         pendingWrites.push({ file, content });
         return;
     }
+    const existing = readFileSnapshot(file);
+    const permissions = mode ?? existing.mode ?? 0o600;
+    if (!Number.isInteger(permissions) || permissions < 0 || permissions > 0o777) {
+        throw new Error(`${file}: invalid file permissions`);
+    }
     ensureDir(path.dirname(file));
-    const tmp = `${file}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, content, mode !== undefined ? { mode } : undefined);
-    fs.renameSync(tmp, file);
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.agentsw-${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(tmp, content, { flag: "wx", mode: permissions });
+        fs.chmodSync(tmp, permissions);
+        fs.renameSync(tmp, file);
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
 }
 export const backupsDir = path.join(appDataDir("agentsw"), "backups");
-/** Copy `file` into the backups dir with a timestamp suffix. No-op if file missing. */
+/** Each original gets a private, unique directory even for equal basenames and timestamps. */
 export function backupFile(file) {
-    if (!fs.existsSync(file) || dryRun)
+    const scope = stagedFiles.getStore();
+    if (scope) {
+        stagedSnapshot(scope, path.resolve(file));
+        return undefined;
+    }
+    if (dryRun)
+        return undefined;
+    const snapshot = readFileSnapshot(file);
+    if (snapshot.text === undefined)
         return undefined;
-    ensureDir(backupsDir);
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const dest = path.join(backupsDir, `${path.basename(file)}.${stamp}`);
-    fs.copyFileSync(file, dest);
+    fs.mkdirSync(backupsDir, { recursive: true, mode: 0o700 });
+    const dir = fs.mkdtempSync(path.join(backupsDir, "file-"));
+    const dest = path.join(dir, path.basename(file));
+    try {
+        fs.chmodSync(dir, 0o700);
+        fs.copyFileSync(file, dest, fs.constants.COPYFILE_EXCL);
+        fs.chmodSync(dest, 0o600);
+    }
+    catch (error) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
     return dest;
 }

package/dist/gateway.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJsonIfExists, writeFileAtomic } from "./fsutil.js";
+import { configDir } from "./store.js";
+const API_URL = "https://ai-gateway.vercel.sh/v1/models";
+const CACHE_FILE = path.join(configDir, "ai-gateway.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const REASONING_EFFORTS = {
+    none: true, minimal: true, low: true, medium: true, high: true, xhigh: true, max: true,
+};
+const PRICE_FIELDS = [
+    ["input", "input"],
+    ["output", "output"],
+    ["cachedInputTokens", "cacheRead"],
+    ["cacheCreationInputTokens", "cacheWrite"],
+];
+function isStringList(value) {
+    return Array.isArray(value) && value.length > 0 &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0 && entry.trim() === entry);
+}
+function reasoningEfforts(options) {
+    if (!Array.isArray(options))
+        return undefined;
+    let effort;
+    for (const option of options) {
+        if (!option || typeof option !== "object" || Array.isArray(option) || !("type" in option) || option.type !== "effort")
+            continue;
+        if (effort)
+            return undefined; // Conflicting declarations are not an authoritative effort list.
+        effort = option;
+    }
+    const values = effort?.values;
+    if (!isStringList(values) || !values.every((value) => Object.hasOwn(REASONING_EFFORTS, value)))
+        return undefined;
+    return [...new Set(values)];
+}
+function perMillion(value) {
+    if (typeof value === "string") {
+        const text = value.trim();
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(text))
+            return undefined;
+        value = Number(text);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return undefined;
+    const converted = value * 1_000_000;
+    return Number.isFinite(converted) ? converted : undefined;
+}
+/** Normalize public REST metadata without interpreting SDK versions as provider routing. */
+export function parseGatewayCatalog(body, fetchedAt) {
+    if (!body || typeof body !== "object" || Array.isArray(body) || !("data" in body) || !Array.isArray(body.data)) {
+        throw new Error("Invalid AI Gateway catalog");
+    }
+    const models = Object.create(null);
+    const seen = new Set();
+    for (const entry of body.data) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const row = entry;
+        if (typeof row.id !== "string" || !/^[^/\s]+(?:\/[^/\s]+)+$/.test(row.id))
+            continue;
+        if (seen.has(row.id))
+            throw new Error("Duplicate AI Gateway model identity");
+        seen.add(row.id);
+        if (row.type !== "language")
+            continue;
+        const spec = { id: row.id };
+        if (typeof row.name === "string" && row.name.trim())
+            spec.name = row.name;
+        const context = typeof row.context_window === "number" && Number.isSafeInteger(row.context_window) && row.context_window > 0
+            ? row.context_window : undefined;
+        const output = typeof row.max_tokens === "number" && Number.isSafeInteger(row.max_tokens) && row.max_tokens > 0
+            ? row.max_tokens : undefined;
+        // Neither member of an inconsistent pair is safe to treat as authoritative.
+        if (context === undefined || output === undefined || output <= context) {
+            if (context !== undefined)
+                spec.contextWindow = context;
+            if (output !== undefined)
+                spec.maxOutput = output;
+        }
+        const efforts = reasoningEfforts(row.reasoning_options);
+        if (efforts)
+            spec.reasoningEfforts = efforts;
+        if ((isStringList(row.tags) && row.tags.includes("reasoning")) || efforts?.some((effort) => effort !== "none")) {
+            spec.reasoning = true;
+        }
+        if (row.modalities && typeof row.modalities === "object" && !Array.isArray(row.modalities) &&
+            "input" in row.modalities && isStringList(row.modalities.input)) {
+            spec.imageInput = row.modalities.input.includes("image");
+        }
+        const model = { id: row.id, spec };
+        if (row.pricing && typeof row.pricing === "object" && !Array.isArray(row.pricing)) {
+            const pricing = row.pricing;
+            const referenceCost = {};
+            for (const [source, target] of PRICE_FIELDS) {
+                const price = perMillion(pricing[source]);
+                if (price !== undefined)
+                    referenceCost[target] = price;
+            }
+            if (Object.keys(referenceCost).length)
+                model.referenceCost = referenceCost;
+            if ((Array.isArray(pricing.inputTiers) && pricing.inputTiers.length > 0) ||
+                (Array.isArray(pricing.outputTiers) && pricing.outputTiers.length > 0)) {
+                model.pricingIsVariable = true;
+            }
+            else if (typeof pricing.varies_by_provider === "boolean") {
+                model.pricingIsVariable = pricing.varies_by_provider;
+            }
+        }
+        models[row.id] = model;
+    }
+    return { fetchedAt, models };
+}
+function readCache() {
+    try {
+        // Bound local reads as well; the persisted envelope is only slightly larger than the response.
+        if (fs.statSync(CACHE_FILE).size > MAX_BODY_BYTES + 1024)
+            return undefined;
+        const cache = readJsonIfExists(CACHE_FILE);
+        if (!cache || typeof cache !== "object" || Array.isArray(cache) ||
+            !("version" in cache) || cache.version !== 1 ||
+            !("fetchedAt" in cache) || typeof cache.fetchedAt !== "string" || !("body" in cache))
+            return undefined;
+        const timestamp = Date.parse(cache.fetchedAt);
+        if (!Number.isFinite(timestamp) || timestamp > Date.now() || new Date(timestamp).toISOString() !== cache.fetchedAt) {
+            return undefined;
+        }
+        return parseGatewayCatalog(cache.body, cache.fetchedAt);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readResponseBody(response) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && Number(contentLength) > MAX_BODY_BYTES) {
+        await response.body?.cancel().catch(() => { });
+        throw new Error("AI Gateway catalog exceeds size limit");
+    }
+    if (!response.body)
+        throw new Error("Missing AI Gateway catalog body");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_BODY_BYTES)
+                throw new Error("AI Gateway catalog exceeds size limit");
+            chunks.push(decoder.decode(value, { stream: true }));
+        }
+        chunks.push(decoder.decode());
+        return chunks.join("");
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Optional supplement: offline never fetches, and every failure leaves discovery usable. */
+export async function loadGatewayCatalog(opts = {}) {
+    const cached = readCache();
+    if (opts.offline)
+        return cached;
+    if (!opts.refresh && cached && Date.now() - Date.parse(cached.fetchedAt) < CACHE_TTL_MS)
+        return cached;
+    try {
+        const response = await fetch(API_URL, {
+            signal: AbortSignal.timeout(15_000),
+            credentials: "omit",
+            redirect: "error",
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new Error("AI Gateway catalog request failed");
+        }
+        const body = JSON.parse(await readResponseBody(response));
+        const catalog = parseGatewayCatalog(body, new Date().toISOString());
+        try {
+            writeFileAtomic(CACHE_FILE, JSON.stringify({ version: 1, fetchedAt: catalog.fetchedAt, body }) + "\n", 0o600);
+        }
+        catch {
+            process.stderr.write("warning: could not cache AI Gateway metadata\n");
+        }
+        return catalog;
+    }
+    catch {
+        process.stderr.write(cached
+            ? "warning: could not refresh AI Gateway metadata; using cached metadata\n"
+            : "warning: could not load AI Gateway metadata\n");
+        return cached;
+    }
+}

package/dist/i18n.js

@@ -1,7 +1,7 @@
 const messages = {
     "root.description": {
-        en: "Manage OpenAI/Anthropic-protocol model providers and sync them into coding agents\n(Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy, DeepSeek Harness).\nModel metadata (context window, input/output limits, reasoning levels) is enriched from\nmodels.dev; existing providers can be imported from the agents and from cc-switch.\n\nRun without arguments (or via `npx agentsw`) for the interactive menu.",
-        "zh-CN": "管理 OpenAI / Anthropic 协议的模型供应商并同步到编码智能体\n(Claude Code、Codex、omp、pi、prime-agent、opencode、Hermes、WorkBuddy、DeepSeek Harness)。\n模型元数据(上下文、输入/输出上限、推理等级)由 models.dev 补全;\n也可从各智能体与 cc-switch 导入已有供应商。\n\n不带参数运行(或 `npx agentsw`)即可打开交互菜单。",
+        en: "Manage OpenAI/Anthropic-protocol model providers and sync them into coding agents\n(Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy, DeepSeek Harness).\nModel metadata (context window, input/output limits, reasoning levels) is enriched from\nmodels.dev first, with automatic AI Gateway supplementation when needed.\nExisting providers can be imported from the agents and from cc-switch.\n\nRun without arguments (or via `npx agentsw`) for the interactive menu.",
+        "zh-CN": "管理 OpenAI / Anthropic 协议的模型供应商并同步到编码智能体\n(Claude Code、Codex、omp、pi、prime-agent、opencode、Hermes、WorkBuddy、DeepSeek Harness)。\n模型元数据(上下文、输入/输出上限、推理等级)优先由 models.dev 补全，必要时自动查询 AI Gateway；\n也可从各智能体与 cc-switch 导入已有供应商。\n\n不带参数运行(或 `npx agentsw`)即可打开交互菜单。",
     },
     "help.language": { en: "UI language: en | zh-CN (also AGENTSW_LANG)", "zh-CN": "界面语言: en | zh-CN (也可用 AGENTSW_LANG)" },
     "error.language": { en: "unsupported language \"{value}\"; use en or zh-CN", "zh-CN": "不支持语言 \"{value}\";请使用 en 或 zh-CN" },
@@ -16,12 +16,12 @@ const messages = {
     "cmd.sync": { en: "re-apply the active provider (or --provider) to app configs", "zh-CN": "将当前供应商(或 --provider)重新应用到应用配置" },
     "cmd.status": { en: "show detected apps and what they currently point at", "zh-CN": "显示检测到的应用及当前供应商" },
     "cmd.models": { en: "search models.dev, or show a configured provider's models", "zh-CN": "搜索 models.dev 或显示已配置供应商的模型" },
-    "cmd.discover": { en: "refresh a provider's models via /v1/models and models.dev", "zh-CN": "通过 /v1/models 和 models.dev 刷新供应商模型" },
+    "cmd.discover": { en: "refresh a provider's model list and configured metadata sources", "zh-CN": "获取供应商模型列表，并通过已启用的目录补全参数" },
     "cmd.import": { en: "scan app configs, preview and dedupe existing custom providers, then import", "zh-CN": "扫描应用配置,预览并去重已有自定义供应商后导入" },
     "cmd.apps": { en: "check installed agents: current version vs latest", "zh-CN": "检查智能体已安装版本与最新版本" },
     "cmd.install": { en: "install an agent CLI", "zh-CN": "安装智能体 CLI" },
     "cmd.upgrade": { en: "upgrade agent CLIs (no args = everything outdated)", "zh-CN": "升级智能体 CLI(无参数时升级全部过期项)" },
-    "cmd.refresh": { en: "re-fetch models.dev metadata for all providers", "zh-CN": "重新拉取所有供应商的 models.dev 元数据" },
+    "cmd.refresh": { en: "refresh metadata for saved models; optionally configure Gateway supplementation", "zh-CN": "刷新已有模型参数，可设置 Gateway 补充源（不改变模型列表）" },
     "opt.id": { en: "custom provider id (default: full hostname + protocol)", "zh-CN": "自定义供应商 ID（默认：完整域名 + 协议）" },
     "opt.name": { en: "display name", "zh-CN": "显示名称" },
     "opt.protocol": { en: "wire protocol: openai | anthropic", "zh-CN": "接口协议: openai | anthropic" },
@@ -38,14 +38,21 @@ const messages = {
     "opt.discover": { en: "list model ids from the provider's /v1/models", "zh-CN": "从供应商 /v1/models 获取模型 id" },
     "opt.include": { en: "keep only models matching comma-separated globs", "zh-CN": "仅保留匹配逗号分隔 glob 的模型" },
     "opt.exclude": { en: "drop models matching comma-separated globs", "zh-CN": "排除匹配逗号分隔 glob 的模型" },
+    "opt.dedup": { en: "deduplicate model snapshot aliases", "zh-CN": "合并重复的模型快照别名" },
     "opt.noDedup": { en: "keep snapshot duplicates (-latest/date suffixes)", "zh-CN": "保留快照重复项(-latest/日期后缀)" },
     "opt.modelsDev": { en: "models.dev provider id for metadata matching", "zh-CN": "用于元数据匹配的 models.dev 供应商 id" },
+    "opt.metadataMode": { en: "save Gateway mode: auto (default, only when needed), on, or off; omission keeps saved mode", "zh-CN": "保存 Gateway 模式：auto（默认，按需补缺）、on 或 off；省略则沿用已保存模式" },
+    "opt.gatewayMetadata": { en: "always supplement from AI Gateway (same as --metadata-mode on)", "zh-CN": "始终使用 AI Gateway 补缺（等同 --metadata-mode on）" },
+    "opt.noGatewayMetadata": { en: "disable Gateway fetching; keep saved parameters (same as --metadata-mode off)", "zh-CN": "关闭 Gateway 获取，保留已保存参数（等同 --metadata-mode off）" },
+    "opt.gatewayModels": { en: 'replace exact aliases as JSON: {"local-id":"creator/model"}; {} clears them', "zh-CN": '用 JSON 替换精确映射：{"本地模型ID":"creator/model"}；{} 清空' },
+    "opt.metadataDetails": { en: "show field sources, conflicts and Gateway reference pricing as JSON (requires --provider)", "zh-CN": "以 JSON 查看字段来源、冲突和 Gateway 参考价格（需 --provider）" },
+    "opt.refreshProvider": { en: "refresh/configure only this saved provider (default: all)", "zh-CN": "仅刷新和设置该供应商（默认全部）" },
     "opt.yes": { en: "non-interactive; require all flags", "zh-CN": "非交互模式;要求提供全部参数" },
     "opt.prune": { en: "also remove entries from app configs", "zh-CN": "同时从应用配置中移除条目" },
     "opt.apps": { en: "comma-separated apps or 'all'", "zh-CN": "逗号分隔的应用或 'all'" },
     "opt.removeApps": { en: "delete only from these apps; keep the agentsw store and other apps unchanged", "zh-CN": "仅从这些智能体删除，保留 agentsw 中央配置和其他智能体配置" },
     "opt.manageDryRun": { en: "preview affected paths without changing files or creating backups", "zh-CN": "仅预览受影响路径，不修改文件或创建备份" },
-    "opt.appsDetailed": { en: "comma-separated apps (claude,codex,omp,pi,prime,opencode,hermes,workbuddy) or 'all'", "zh-CN": "逗号分隔的应用(claude,codex,omp,pi,prime,opencode,hermes,workbuddy)或 'all'" },
+    "opt.appsDetailed": { en: "comma-separated apps (claude,codex,omp,pi,prime,opencode,hermes,workbuddy,dsh) or 'all'", "zh-CN": "逗号分隔的应用(claude,codex,omp,pi,prime,opencode,hermes,workbuddy,dsh)或 'all'" },
     "opt.model": { en: "override default model while switching", "zh-CN": "切换时覆盖默认模型" },
     "opt.dryRun": { en: "preview config diff without writing", "zh-CN": "仅预览配置差异,不写入" },
     "opt.provider": { en: "sync this provider instead of the active one", "zh-CN": "同步指定供应商而非当前供应商" },
@@ -74,6 +81,16 @@ const messages = {
     "menu.list": { en: "View providers saved in agentsw", "zh-CN": "查看 agentsw 供应商列表" },
     "menu.sync": { en: "Re-sync the current provider to agents", "zh-CN": "重新同步当前供应商" },
     "menu.discover": { en: "Update a provider's model list", "zh-CN": "更新供应商模型列表" },
+    "menu.metadata": { en: "Configure and refresh model metadata", "zh-CN": "设置并刷新模型参数补充源" },
+    "menu.metadataHelp": { en: "Keep the model list; choose automatic, always-on or disabled AI Gateway lookup, then refresh saved parameters only.", "zh-CN": "保留模型列表，选择 AI Gateway 自动按需、始终补充或关闭，仅刷新保存的参数。" },
+    "menu.metadataProvider": { en: "which provider's metadata settings should be updated?", "zh-CN": "选择要设置模型参数补充源的供应商" },
+    "menu.metadataMode": { en: "AI Gateway lookup mode (no API key is sent)", "zh-CN": "AI Gateway 查询模式（请求不携带 API key）" },
+    "menu.metadataAuto": { en: "Automatic (recommended)", "zh-CN": "自动按需（推荐）" },
+    "menu.metadataAutoHelp": { en: "models.dev first; query Gateway for missing core specs, to refresh its saved fields or verify tracked identity conflicts.", "zh-CN": "优先 models.dev；仅在核心参数缺失、需刷新已有 Gateway 字段或核实旧自动值身份冲突时查询。" },
+    "menu.metadataOn": { en: "Always supplement", "zh-CN": "始终补充" },
+    "menu.metadataOnHelp": { en: "Check Gateway on every metadata lookup; models.dev still takes priority.", "zh-CN": "每次补全参数都查询 Gateway，仍以 models.dev 为优先。" },
+    "menu.metadataOff": { en: "Disabled", "zh-CN": "关闭" },
+    "menu.metadataOffHelp": { en: "Never query Gateway; keep previously saved model parameters.", "zh-CN": "不查询 Gateway，保留已保存的模型参数。" },
     "menu.remove": { en: "Delete provider configuration", "zh-CN": "删除供应商配置" },
     "menu.rename": { en: "Change a provider ID", "zh-CN": "修改供应商 ID" },
     "menu.renameProvider": { en: "which provider ID should be changed?", "zh-CN": "选择要修改 ID 的供应商" },
@@ -171,7 +188,7 @@ const messages = {
     "add.added": { en: "added", "zh-CN": "已添加" },
     "add.updated": { en: "updated", "zh-CN": "已更新" },
     "add.saved": { en: "{status} provider {id} ({protocol})", "zh-CN": "{status}供应商 {id} ({protocol})" },
-    "add.metadata": { en: "models.dev metadata: {matched}/{total} models matched", "zh-CN": "models.dev 元数据:匹配 {matched}/{total} 个模型" },
+    "add.metadata": { en: "model metadata: {matched}/{total} models have a context limit", "zh-CN": "模型参数：{matched}/{total} 个模型已有上下文上限" },
     "add.providerHint": { en: " (provider hint: {hint})", "zh-CN": " (供应商提示:{hint})" },
     "add.next": { en: "next: agentsw use {id}", "zh-CN": "下一步: agentsw use {id}" },
     "quick.probing": { en: "probing protocols at {url} ...", "zh-CN": "正在探测 {url} 支持的协议..." },
@@ -185,7 +202,7 @@ const messages = {
     "menu.useHelp": { en: "Select a provider and default model, then write them to compatible agent configs.", "zh-CN": "选择供应商和默认模型，然后写入支持该协议的智能体配置。" },
     "menu.statusHelp": { en: "Show detected agents, their current providers and config file locations.", "zh-CN": "查看检测到的智能体、所用供应商及配置文件位置。" },
     "menu.listHelp": { en: "Show only the providers, protocols and default models saved in agentsw.", "zh-CN": "只查看 agentsw 已保存的供应商、协议和默认模型。" },
-    "menu.syncHelp": { en: "Write the current agentsw provider to agent configs without fetching a new model list.", "zh-CN": "将 agentsw 当前供应商写入智能体配置，不重新获取模型列表。" },
+    "menu.syncHelp": { en: "Write the current agentsw provider to agent configs without fetching a model list or metadata catalogs.", "zh-CN": "将 agentsw 当前供应商写入智能体配置，不重新获取模型列表或元数据目录。" },
     "menu.discoverHelp": { en: "Fetch models from the provider, fill in model metadata, and optionally sync to agents.", "zh-CN": "从供应商接口重新获取模型并补全模型参数，可选择同步到智能体。" },
     "menu.renameHelp": { en: "Change the config ID and update references; keep custom display names.", "zh-CN": "修改配置中的标识并更新关联引用，保留自定义显示名称。" },
     "menu.removeHelp": { en: "Choose where to delete: agentsw only, one agent only, or both.", "zh-CN": "先选择删除范围：仅 agentsw、仅某个智能体，或两处一起。" },

package/dist/import.js

@@ -12,12 +12,12 @@ export function normalizeUrl(u) {
 }
 /** True when the path already names the API version, e.g. `.../v1`. */
 const hasApiVersion = (baseUrl) => /\/v\d+(?:beta\d*)?$/.test(baseUrl.split(/[?#]/, 1)[0]);
-/** Apps may append their own API version; all other URL components remain significant. */
+/** Apps may append /v1; other API versions and URL components remain significant. */
 export function endpointKey(baseUrl) {
     const normalized = normalizeUrl(baseUrl);
     const suffixAt = normalized.search(/[?#]/);
     const path = suffixAt < 0 ? normalized : normalized.slice(0, suffixAt);
-    return path.replace(/\/v\d+(?:beta\d*)?$/, "") + (suffixAt < 0 ? "" : normalized.slice(suffixAt));
+    return path.replace(/\/v1$/, "") + (suffixAt < 0 ? "" : normalized.slice(suffixAt));
 }
 /** An unresolved credential is not evidence that two configurations use the same account. */
 export function findMatchingProvider(existing, candidate) {

package/dist/index.js

@@ -6,8 +6,17 @@ import { detectSystemLocale, extractCliLocale, normalizeLocale, setLocale, t } f
 import { cmdMenu } from "./menu.js";
 import { loadStore } from "./store.js";
 import { cmdListLocalProviders, cmdRemoveProvider, cmdRename } from "./provider-actions.js";
+// Locale lookup is best effort: help/version and app-local commands do not need the store.
+function savedLocale() {
+    try {
+        return loadStore().language;
+    }
+    catch {
+        return undefined;
+    }
+}
 // Locale precedence: CLI flag > environment > saved preference > system locale.
-setLocale(extractCliLocale() ?? process.env.AGENTSW_LANG ?? loadStore().language ?? detectSystemLocale());
+setLocale(extractCliLocale() ?? process.env.AGENTSW_LANG ?? savedLocale() ?? detectSystemLocale());
 function parseLocale(value) {
     const locale = normalizeLocale(value);
     if (!locale)
@@ -51,14 +60,26 @@ program
     .option("-d, --discover", t("opt.discover"))
     .option("--include <globs>", t("opt.include"))
     .option("--exclude <globs>", t("opt.exclude"))
+    .option("--dedup", t("opt.dedup"))
     .option("--no-dedup", t("opt.noDedup"))
     .option("--models-dev <id>", t("opt.modelsDev"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .option("-y, --yes", t("opt.yes"))
     .action(cmdAdd);
 program
     .command("quick")
     .description(t("cmd.quick"))
     .option("--id <slug>", t("opt.id"))
+    .option("--name <name>", t("opt.name"))
+    .option("--openai-api <flavor>", t("opt.openaiApi"))
+    .option("--models-dev <id>", t("opt.modelsDev"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .option("--base-url <url>", t("opt.baseUrl"))
     .option("--api-key <key>", t("opt.apiKey"))
     .option("--default-model <id>", t("opt.defaultModel"))
@@ -66,6 +87,7 @@ program
     .option("--reasoning-effort <level>", t("opt.reasoning"))
     .option("--include <globs>", t("opt.include"))
     .option("--exclude <globs>", t("opt.exclude"))
+    .option("--dedup", t("opt.dedup"))
     .option("--no-dedup", t("opt.noDedup"))
     .option("-y, --yes", t("opt.yes"))
     .action(cmdQuickAdd);
@@ -112,6 +134,7 @@ program
     .command("models [query]")
     .description(t("cmd.models"))
     .option("-p, --provider <id>", t("opt.showProvider"))
+    .option("--metadata", t("opt.metadataDetails"))
     .option("-r, --refresh", t("opt.refresh"))
     .option("-l, --limit <n>", t("opt.limit"), "30")
     .action(cmdModels);
@@ -122,18 +145,35 @@ program
     .option("-a, --apps <apps>", t("opt.appsSync"))
     .option("--include <globs>", t("opt.setInclude"))
     .option("--exclude <globs>", t("opt.setExclude"))
+    .option("--dedup", t("opt.dedup"))
     .option("--no-dedup", t("opt.noDedup"))
     .option("--no-filter", t("opt.noFilter"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .action(cmdDiscover);
 program
     .command("import")
     .description(t("cmd.import"))
     .option("--all", t("opt.all"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .action(cmdImport);
 program.command("apps").description(t("cmd.apps")).action(cmdApps);
 program.command("install <app>").description(t("cmd.install")).action(cmdInstall);
 program.command("upgrade [apps...]").description(t("cmd.upgrade")).action(cmdUpgrade);
-program.command("refresh").description(t("cmd.refresh")).action(cmdRefreshMeta);
+program
+    .command("refresh")
+    .description(t("cmd.refresh"))
+    .option("-p, --provider <id>", t("opt.refreshProvider"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
+    .action(cmdRefreshMeta);
 program.parseAsync().catch((err) => {
     process.stderr.write(`error: ${err.message}\n`);
     process.exit(1);

package/dist/jsonc.js

@@ -1,4 +1,4 @@
-import fs from "node:fs";
+import { readTextIfExists } from "./fsutil.js";
 import { applyEdits, createScanner, getNodeValue, modify, parseTree, printParseErrorCode, } from "jsonc-parser";
 export function isJsonObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -34,15 +34,9 @@ function parseJsoncObject(file, text) {
 }
 /** Only missing files initialize to an empty object; unreadable or invalid files must not be replaced. */
 export function readJsoncObject(file) {
-    let text;
-    try {
-        text = fs.readFileSync(file, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return { file, text: "{}\n", value: {} };
-        throw error;
-    }
+    const text = readTextIfExists(file);
+    if (text === undefined)
+        return { file, text: "{}\n", value: {} };
     return { file, text, value: parseJsoncObject(file, text) };
 }
 function comments(text) {

package/dist/menu.js

@@ -1,7 +1,8 @@
 import pc from "picocolors";
 import prompts from "prompts";
-import { cmdAdd, cmdQuickAdd, cmdApps, cmdInstall, cmdDiscover, cmdImport, cmdList, cmdStatus, cmdSync, cmdUpgrade, cmdUse, } from "./commands.js";
+import { cmdAdd, cmdQuickAdd, cmdApps, cmdInstall, cmdDiscover, cmdImport, cmdRefreshMeta, cmdList, cmdStatus, cmdSync, cmdUpgrade, cmdUse, } from "./commands.js";
 import { getLocale, setLocale, t } from "./i18n.js";
+import { getMetadataMode } from "./metadata.js";
 import { loadStore, saveStore } from "./store.js";
 import { appPackages, appCommand, installedVersion } from "./apps.js";
 import { cmdRemoveProvider, cmdRename } from "./provider-actions.js";
@@ -166,6 +167,7 @@ export async function cmdMenu() {
                 { title: t("menu.list"), description: t("menu.listHelp"), value: "list" },
                 { title: t("menu.sync"), description: t("menu.syncHelp"), value: "sync" },
                 { title: t("menu.discover"), description: t("menu.discoverHelp"), value: "discover" },
+                { title: t("menu.metadata"), description: t("menu.metadataHelp"), value: "metadata" },
                 { title: t("menu.rename"), description: t("menu.renameHelp"), value: "rename" },
                 { title: t("menu.remove"), description: t("menu.removeHelp"), value: "remove" },
                 { title: t("menu.apps"), description: t("menu.appsHelp"), value: "apps" },
@@ -227,6 +229,25 @@ export async function cmdMenu() {
             const sync = await askToggle(t("menu.pushRefresh"));
             await cmdDiscover(picked.id, { sync });
         }
+        else if (action === "metadata") {
+            const picked = await pickProvider(t("menu.metadataProvider"));
+            if (!picked)
+                continue;
+            const current = loadStore().providers[picked.id];
+            const { metadataMode } = await prompts({
+                type: "select",
+                name: "metadataMode",
+                message: t("menu.metadataMode"),
+                hint: t("menu.selectInstructions"),
+                initial: ["auto", "on", "off"].indexOf(getMetadataMode(current)),
+                choices: [
+                    { title: t("menu.metadataAuto"), description: t("menu.metadataAutoHelp"), value: "auto" },
+                    { title: t("menu.metadataOn"), description: t("menu.metadataOnHelp"), value: "on" },
+                    { title: t("menu.metadataOff"), description: t("menu.metadataOffHelp"), value: "off" },
+                ],
+            }, cancel);
+            await cmdRefreshMeta({ provider: picked.id, metadataMode });
+        }
         else if (action === "rename" || action === "remove") {
             try {
                 if (action === "rename")