agentsw 0.10.2 → 0.11.1

package/README.md

@@ -27,14 +27,17 @@ without touching the settings you hand-tuned.
   `npx agentsw use myproxy -a codex,omp` is one line in a provisioning script; nine GUI
   clicks are not.
 - **`--dry-run` prints redacted diffs.** Preview changes without writing files or creating
-  backups. Existing configuration files are backed up when actual changes are committed.
+  backups — the provider store included, so a previewed `sync` does not leave its refreshed
+  model list behind. Existing configuration files are backed up when changes are committed.
 - **Non-destructive by design.** Only the fields agentsw owns are rewritten. Provider-level
   keys it does not model — `authHeader`, `headers`, `compat`, `discovery` — per-model extras
   like `thinkingLevelMap`, and YAML comments all survive a re-sync.
 - **Model metadata, not just an id list.** Reseller `/v1/models` endpoints return bare ids.
   agentsw enriches them from [models.dev](https://models.dev), automatically fills meaningful gaps from AI Gateway when needed, and writes what each app
   actually reads: `thinkingLevelMap` for pi/prime, `limit`/`attachment` for opencode,
-  `contextWindow`/`maxTokens` for omp, `reasoningEfforts`/`input` for dsh.
+  `contextWindow`/`maxTokens` for omp, `reasoningEfforts`/`input` for dsh. Limits the endpoint declares for
+  its own models outrank the catalogs, so one model cannot end up with two different context windows
+  depending on which provider lists it.
 - **Adopts what you already have** — including [cc-switch](https://github.com/farion1231/cc-switch).
   `import` scans every installed agent *and* cc-switch's own store, merges duplicates
   (same protocol + normalized endpoint + credentials), and never writes back to either.
@@ -94,9 +97,10 @@ agentsw                   # once installed globally; the short alias `asw` is id
 
 **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.
+your agents, switch provider and default model, sync a provider (fetch its current model list,
+then write it to your agents), 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.
 
 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
@@ -202,8 +206,9 @@ use `--all` explicitly in scripts. Model discovery may update the local metadata
 
 ## Model discovery filters
 
-`--discover` lists model ids from the provider's `/v1/models`, then enriches each id from
-models.dev first, with automatic AI Gateway supplementation when needed. Reseller lists are noisy,
+`--discover` lists model ids from the provider's `/v1/models`, then enriches each id from models.dev first,
+with automatic AI Gateway supplementation when needed. Limits the provider declares for its own models in
+that same listing win over what a catalog claims for them; ids it lists bare are enriched as before. Reseller lists are noisy,
 so filters are persisted per provider and re-applied on every `discover`:
 
 ```bash
@@ -213,6 +218,10 @@ asw add -y --discover --exclude "*embedding*,*video*" --id myproxy ...
 asw add -y --discover --no-dedup ...            # keep duplicates
 asw discover myproxy --include "gpt-*,glm-*"    # update the persisted filter
 asw discover myproxy --no-filter                # clear it
+
+# Refresh several providers' model lists without writing any agent config.
+asw discover --all
+asw discover myproxy backup-proxy
 ```
 
 Explicit `--models` entries and the default model are never filtered out.
@@ -249,9 +258,16 @@ asw refresh --provider myproxy --metadata-mode off
 # Return an explicitly disabled provider to automatic mode
 asw refresh --provider myproxy --metadata-mode auto
 
-# Preview and apply separately; sync does not query catalogs
+# Preview and apply separately. Sync fetches the model list first;
+# --dry-run still fetches, so the preview matches a real sync, but saves nothing;
+# --no-refresh writes the saved list without touching the network.
 asw sync --provider myproxy --dry-run
 asw sync --provider myproxy
+asw sync --provider myproxy --no-refresh
+
+# Refresh and push several providers in one run.
+asw sync --all
+asw sync --provider myproxy,backup-proxy
 ```
 
 The menu's **Configure and refresh model metadata** action offers **Automatic (recommended)**,
@@ -264,9 +280,12 @@ Without `--provider`, `refresh` applies to all providers, including any supplied
 `--gateway-models` replaces the whole alias map (`{}` clears it); aliases do not change the saved mode or override `off`.
 Import still skips already configured accounts.
 
-- **Field-level priority:** manual values > models.dev > Gateway gap filling. Tracked automatic values may
-  refresh; subsequent manual edits are retained. Legacy values without provenance are conservatively treated
-  as manual overrides. Unmodeled extension fields survive enrichment too.
+- **Field-level priority:** manual values > the endpoint's own declaration > models.dev > Gateway gap filling.
+  An endpoint that advertises `context_window_tokens`/`maximum_output_tokens`
+  (or their `context_length`/`max_output_tokens` spellings) for its own list is authoritative for its own
+  route, so those limits are written instead of a catalog's estimate for the same model. Tracked automatic
+  values may refresh; subsequent manual edits are retained. Legacy values without provenance are conservatively
+  treated as manual overrides. Unmodeled extension fields survive enrichment too.
 - **Exact identities:** automatic lookup can map a bare, case-sensitive ID (no `/`) to a unique Gateway
   `creator/model` identity when models.dev evidence is absent or agrees. Ambiguous creator evidence in either
   catalog is rejected; custom or ambiguous names need explicit aliases. Qualified IDs never have their prefixes
@@ -286,9 +305,28 @@ Import still skips already configured accounts.
   Gateway has a separate 24-hour cache; a failed request is retried once before falling back to stale cached data
   (or skipping supplementation when there is none). `AGENTSW_DEBUG=1` reports why an attempt failed, and
   `AGENTSW_GATEWAY_TIMEOUT_MS` overrides the 15-second whole-request budget.
-- **Automatic lookup is not automatic sync:** enrichment updates saved metadata during add/quick/discover/import/refresh.
-  It does not add an automatic push to agents. Sync behavior is unchanged: ordinary `sync` only writes saved settings
-  and fetches neither model lists nor metadata catalogs.
+- **A model the endpoint dropped is reported, not hidden.** A refresh keeps the default and small
+  model even when the listing stops carrying them — one flaky listing must not delete the model you
+  chose — but being kept also keeps them out of the "removed upstream" line, so they are named in a
+  `warning:` after the apply and in `--json` as `refreshed.missing`. That is what a renamed model
+  looks like from the client side: the agents keep working with an id the endpoint now rejects.
+- **One selection everywhere:** `--all` and a comma-separated `-p a,b` mean the same thing on `sync`, `discover`
+  and `refresh`, and `discover` also takes its ids positionally (`discover alpha beta`). Every id is resolved before
+  the first request, so a typo fails before half the run is on disk. Omitting the selection keeps each command's own
+  default: the active provider for `sync` and `discover`, every provider for `refresh`.
+- **Syncing several providers:** `sync --all` takes every configured provider and `-p a,b` takes a list; each is
+  refreshed and written in turn, finishing with the active provider so whatever "current" pointer an app keeps ends
+  up where the store says it should. An app that names one provider instead of a map — Claude Code's env block — is
+  written once rather than once per provider: it gets the active provider when it can accept it, or the single
+  provider in the run that it can (Claude Code takes anthropic endpoints only, so an openai active provider does not
+  starve it). With several candidates and the active provider not among them the choice is yours, so the app keeps
+  pointing where it already does: syncing is not switching. A provider whose endpoint cannot be reached is reported
+  and skipped, the rest still sync, and the run exits non-zero.
+- **Automatic lookup is not an automatic push:** enrichment updates saved metadata during add/quick/discover/import/refresh
+  and never writes agent configs by itself. `sync` is the push, and it refreshes first: it fetches the provider's model
+  list, re-enriches it from the catalogs, saves the store, then applies it. `sync --dry-run` fetches the same list so
+  the preview is accurate but saves neither it nor the configs. `sync --no-refresh` writes the saved list without
+  fetching, and `discover` stops after the refresh without writing any agent.
 
 ## Commands
 
@@ -301,11 +339,11 @@ Import still skips already configured accounts.
 | `list` / `status` | configured providers / what each agent points at |
 | `list --apps omp,prime` | list agent-local provider IDs, including entries absent from agentsw |
 | `rename <id> <new-id>` | back up and migrate the ID and config references; supports `--dry-run` |
-| `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` |
+| `use <id>` | switch every detected agent; `-a codex,omp`, `-m <model>`, `--small-model <id>` / `--no-small-model`, `--dry-run` |
+| `sync` | refresh each provider's model list, then re-apply it to the agent configs; `--all` or `-p a,b` for several, `--no-refresh` writes the saved list |
+| `discover [ids...] [--sync]` | refresh the model list + metadata from `/v1/models`; `--all` or several ids for more than one, no id for the active provider; `--sync` pushes them to the agents |
 | `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 |
+| `refresh [--provider <ids>]` | refresh saved metadata and optionally configure Gateway; keep the model list; every provider unless `-p a,b` narrows it |
 | `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 |
 | `remove <id> --apps omp` | delete only the selected app's entry; supports `--dry-run` |

package/README.zh-CN.md

@@ -25,15 +25,15 @@
 
 - **它能去桌面应用去不了的地方。** 无头服务器、容器、devcontainer、CI。
   `npx agentsw use myproxy -a codex,omp` 在开机脚本里是一行；GUI 点九次不是。
-- **`--dry-run` 输出脱敏 diff。** 写盘前先预览；预览不写文件、不创建备份。
-  正式提交变更时，已有配置文件才会先备份。
+- **`--dry-run` 输出脱敏 diff。** 写盘前先预览；预览不写文件、不创建备份，供应商 store 也一样——
+  预览 `sync` 不会把刷新到的模型列表留在配置里。正式提交变更时，已有配置文件才会先备份。
 - **默认不破坏现有配置。** 只覆盖 agentsw 自己管理的字段：它不建模的供应商级键
   （`authHeader`、`headers`、`compat`、`discovery`）、`thinkingLevelMap` 之类的模型级字段、
   以及 YAML 注释，都会在重新同步后原样保留。
 - **写的是元数据，不只是模型 id。** 转售商 `/v1/models` 只返回裸 id；agentsw 从
   [models.dev](https://models.dev) 优先补全，并在有实际缺口时自动查询 AI Gateway，按各应用真正读取的字段下发：pi/prime 的
   `thinkingLevelMap`、opencode 的 `limit`/`attachment`、omp 的 `contextWindow`/`maxTokens`、
-  dsh 的 `reasoningEfforts`/`input`。
+  dsh 的 `reasoningEfforts`/`input`。端点自己声明的上下文/输出上限优先于目录，避免同一模型在不同供应商下被写成不同窗口。
 - **接管你已有的配置——包括 [cc-switch](https://github.com/farion1231/cc-switch)。**
   `import` 会扫描所有已安装的智能体**以及 cc-switch 自己的存储**，合并重复项
   （相同协议 + 归一化端点 + 凭据），并且对两者都只读不写。
@@ -87,7 +87,7 @@ agentsw                   # 全局安装后可用；短名 `asw` 完全等价
 ```
 
 **不带参数运行就是一个菜单——整个工具都在里面。** 添加供应商（自动识别或手动设置）、导入各智能体
-已有的供应商、切换供应商和默认模型、重新同步、更新模型列表、设置模型参数补充源、重命名或删除、
+已有的供应商、切换供应商和默认模型、同步供应商（重新获取模型列表再写入）、设置模型参数补充源、重命名或删除、
 安装/升级智能体、切换语言。首次运行会先问你要 English 还是简体中文，并提议接管你各智能体已经在用的配置。
 
 菜单里的每项操作都有对应的命令，方便脚本、CI 和无头机器——见 [命令](#命令)。
@@ -191,6 +191,7 @@ imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 m
 ## 模型发现过滤
 
 `--discover` 从供应商 `/v1/models` 拉取模型 id，优先从 models.dev 补全元数据，必要时自动查询 AI Gateway。
+同一份列表里供应商为自家模型声明的上下文/输出上限优先于目录的估算，只给出裸 id 的模型仍按原逻辑补全。
 转售商列表噪音大，过滤规则持久化在供应商上，每次 `discover` 自动复用：
 
 ```bash
@@ -200,6 +201,10 @@ asw add -y --discover --exclude "*embedding*,*video*" --id myproxy ...
 asw add -y --discover --no-dedup ...            # 保留重复项
 asw discover myproxy --include "gpt-*,glm-*"    # 更新持久化过滤规则
 asw discover myproxy --no-filter                # 清除规则
+
+# 只刷新模型列表、不写任何智能体配置，可一次多个。
+asw discover --all
+asw discover myproxy backup-proxy
 ```
 
 手动 `--models` 指定的 id 和默认模型永不被过滤。
@@ -234,9 +239,16 @@ asw refresh --provider myproxy --metadata-mode off
 # 将显式关闭的供应商恢复为自动模式
 asw refresh --provider myproxy --metadata-mode auto
 
-# 单独预览、同步；sync 不查询目录
+# 单独预览、应用。sync 会先重新获取模型列表；
+# --dry-run 同样会获取，预览因此与真实 sync 一致，但什么都不保存；
+# --no-refresh 则完全不联网，只写入已保存的列表。
 asw sync --provider myproxy --dry-run
 asw sync --provider myproxy
+asw sync --provider myproxy --no-refresh
+
+# 一次刷新并推送多个供应商。
+asw sync --all
+asw sync --provider myproxy,backup-proxy
 ```
 
 交互菜单的“设置并刷新模型参数补充源”提供“自动按需（推荐）”“始终补充”“关闭”，
@@ -249,7 +261,9 @@ asw sync --provider myproxy
 `--gateway-models` 替换整个映射，传 `{}` 清空；映射不会更改保存的模式，也不会覆盖 `off`。
 导入仍跳过已经配置的账号。
 
-- **按字段合并：** 用户手动值优先，其次 models.dev，最后 Gateway 补缺。已记录来源的自动值可以刷新，
+- **按字段合并：** 用户手动值优先，其次端点自己声明的值，然后 models.dev，最后 Gateway 补缺。
+  端点在 `/v1/models` 中为自家模型声明了 `context_window_tokens`/`maximum_output_tokens`（或
+  `context_length`/`max_output_tokens` 写法）时，以它为准而不是目录对同一模型的估算。已记录来源的自动值可以刷新，
   手动修改后会保留；旧版本中没有来源记录的已有值保守视为手动值，不强制覆盖。未知扩展字段也保留。
 - **精确匹配：** 不含 `/` 的裸 ID 可按大小写精确匹配唯一的 Gateway `creator/model` 身份，
   前提是 models.dev 没有身份线索或线索一致。任一目录中的创建者身份有歧义时拒绝自动匹配；
@@ -266,8 +280,25 @@ asw sync --provider myproxy
   审计信息仅保存在 agentsw，不写入智能体运行配置。Gateway 目录独立缓存 24 小时；请求失败会先重试一次，
   仍失败才使用旧缓存，无缓存时只跳过补充。`AGENTSW_DEBUG=1` 会说明该次尝试失败的原因，
   `AGENTSW_GATEWAY_TIMEOUT_MS` 可覆盖默认 15 秒的整体请求预算。
-- **自动查询不等于自动同步：** 添加、快速添加、发现、导入、刷新时补全保存的元数据，并不新增自动推送。
-  同步行为不变：普通 `sync` 仅写入已保存的设置，既不获取模型列表，也不请求元数据目录。
+- **端点下掉的模型会被明确报出,而不是悄悄保留。** 刷新时即使列表里不再有默认模型和小模型，也会保留它们——
+  一次抖动的列表不该删掉你选定的模型——但「removed upstream」里就不会出现它们了，所以改为在写入之后用
+  `warning:` 点名，`--json` 里对应 `refreshed.missing`。模型被改名时从客户端看到的就是这个现象：
+  配置照旧，而端点已经不认这个 id 了。
+- **选择供应商的方式统一：** `sync`、`discover`、`refresh` 都支持 `--all` 和逗号分隔的 `-p a,b`，
+  `discover` 还可以直接写位置参数（`discover alpha beta`）。所有 id 在第一次请求前就全部解析，
+  写错一个会在任何东西落盘之前失败。不指定时各命令保持自己的默认：`sync` 和 `discover` 取当前供应商，
+  `refresh` 取全部。
+- **一次同步多个供应商：** `sync --all` 取全部已配置的供应商，`-p a,b` 取指定列表；逐个刷新并写入，
+  并把当前供应商放在最后，这样各智能体记录的“当前指向”最终就停在 store 所说的那一个。
+  只记录单个供应商（而非供应商表）的应用——例如 Claude Code 的 env 块——只写一次而不是每个供应商写一遍：
+  能接受当前供应商时就写它，不能接受时（Claude Code 只收 anthropic 端点，当前供应商却可能是 openai 的）
+  就写本次同步里它唯一能接受的那个。若有多个候选且当前供应商不在其中，选择权在你，它保持原有指向：
+  同步不是切换。
+  某个供应商的端点不可达时会被报告并跳过，其余照常同步，整个运行以非零状态结束。
+- **自动查询不等于自动推送：** 添加、快速添加、发现、导入、刷新时补全保存的元数据，永远不会自行写入智能体配置。
+  推送是 `sync`，而且它先刷新：先获取供应商模型列表、按目录补全、保存到 store，再写入各智能体。
+  `sync --dry-run` 会获取同一份列表以保证预览准确，但既不保存列表也不写配置；
+  `sync --no-refresh` 不联网，只写入已保存的列表；`discover` 刷新完就停，不写任何智能体。
 
 ## 命令
 
@@ -280,11 +311,11 @@ asw sync --provider myproxy
 | `list` / `status` | 已配置的供应商 / 各智能体当前指向 |
 | `list --apps omp,prime` | 列出智能体本地供应商 ID，包括未导入 agentsw 的条目 |
 | `rename <id> <new-id>` | 备份并迁移 ID 和配置引用，支持 `--dry-run` |
-| `use <id>` | 切换所有检测到的智能体；`-a codex,omp`、`-m <model>`、`--dry-run` |
-| `sync` | 重新应用当前供应商（比如某个智能体升级之后） |
-| `discover <id> [--sync]` | 从 `/v1/models` 刷新模型列表与元数据 |
+| `use <id>` | 切换所有检测到的智能体；`-a codex,omp`、`-m <model>`、`--small-model <id>` / `--no-small-model`、`--dry-run` |
+| `sync` | 先刷新各供应商的模型列表，再写入各智能体配置；`--all` 或 `-p a,b` 可一次处理多个，`--no-refresh` 只写已保存的列表 |
+| `discover [ids...] [--sync]` | 从 `/v1/models` 刷新模型列表与元数据；`--all` 或多个 id 可一次处理多个，不给 id 则取当前供应商；`--sync` 再推送到各智能体 |
 | `models [query]` | 搜索 models.dev 目录（`-r` 强制刷新缓存，`-l <n>` 限制条数） |
-| `refresh [--provider <id>]` | 刷新已有模型参数，可设置 Gateway 补充源，不改变模型列表 |
+| `refresh [--provider <ids>]` | 刷新已有模型参数，可设置 Gateway 补充源，不改变模型列表；默认全部，`-p a,b` 可缩小范围 |
 | `models --provider <id> --metadata` | 以 JSON 查看字段来源、冲突和参考价格 |
 | `prune <id>` / `remove <id> [--prune]` | 从各应用配置中清除 / 从存储中删除 |
 | `remove <id> --apps omp` | 仅删除指定智能体内的条目，支持 `--dry-run` |