agentsw 0.10.1 → 0.11.0

package/README.md

@@ -17,20 +17,7 @@ without touching the settings you hand-tuned.
 
 </div>
 
-```console
-$ 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 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
-               select in dsh with the model picker, or run: dsh web
-```
+![asw use myproxy writes one provider into nine coding agents](https://raw.githubusercontent.com/tchivs/agentsw/main/docs/demo.gif)
 
 `agentsw` and the short `asw` are the same binary.
 
@@ -40,7 +27,8 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
   `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.
@@ -54,9 +42,37 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 - **Wire-aware.** `/v1/chat/completions` and `/v1/responses` are different endpoints;
   agentsw tracks which one a provider speaks and never downgrades a working one.
 
-Want a GUI, MCP/Skills sync, a usage dashboard or a local failover proxy? Use
-[cc-switch](https://github.com/farion1231/cc-switch) — it is excellent at that, and agentsw
-imports from it rather than competing with it.
+## How it compares
+
+Two projects do most of this better than agentsw does, and both are worth your time:
+
+- **[cc-switch](https://github.com/farion1231/cc-switch)** — a desktop app (Tauri) for ten tools:
+  one-click switching, 90+ provider presets, MCP/Skills/Prompts management, local routing and
+  failover with API-format conversion, a usage and cost dashboard, a session manager, and
+  WebDAV/S3 sync.
+- **[cc-switch-cli](https://github.com/SaladDay/cc-switch-cli)** — the community CLI fork of the
+  same idea: TUI plus scriptable subcommands, seven tools, MCP and skills, a daemon proxy with
+  token accounting, SQLite-backed state.
+
+Between them they cover Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, Hermes,
+OpenClaw, Pi, Grok Build and MiniMax Code. agentsw covers a different nine — Claude Code, Codex,
+omp, pi, prime-agent, opencode, Hermes, WorkBuddy and DeepSeek Harness — **four of which neither
+other tool writes at all.**
+
+| | agentsw | cc-switch | cc-switch-cli |
+|---|---|---|---|
+| Interface | CLI, `--json` for scripts | desktop GUI | TUI + CLI |
+| Model metadata (models.dev + AI Gateway) written into each app's own fields | **yes** | no | no |
+| MCP / Skills / Prompts management | — | yes | yes |
+| Routing, API-format conversion, failover | — | yes | yes |
+| Usage and cost dashboard | — | yes | yes |
+| Presets, sessions, cloud sync, deep links | — | yes | partial |
+| Reads the other tool's provider store | yes — read-only `import` | — | — |
+
+The honest summary: **if you want a GUI, MCP management, or a failover proxy, use cc-switch.** If
+you use omp, prime-agent, WorkBuddy or DeepSeek Harness, or you want each agent to receive real
+model metadata instead of a bare id, that is what agentsw is for. It reads cc-switch's store
+rather than competing with it.
 
 ## Install
 
@@ -79,9 +95,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
@@ -104,6 +121,32 @@ opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.co
 dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
+And the point of the whole thing — one command writes every detected agent (this is the run in
+the animation at the top of this page, as text):
+
+```console
+$ asw use myproxy
+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
+ok   omp       ~/.omp/agent/models.yml
+               select in omp with: omp --model myproxy/glm-5.3-flash
+ok   pi        ~/.pi/agent/models.json, ~/.pi/agent/settings.json
+ok   prime     ~/.prime/agent/models.json, ~/.prime/agent/settings.json
+ok   opencode  ~/.config/opencode/opencode.json
+ok   hermes    ~/.hermes/config.yaml, ~/.hermes/.env
+ok   workbuddy ~/.workbuddy/models.json, ~/.workbuddy/settings.json
+               WorkBuddy watches models.json; models appear in the selector's custom section without restart
+ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
+               select in dsh with the model picker, or run: dsh web
+```
+
+`claude` is the only skip: Claude Code speaks the Anthropic protocol, and `myproxy` is an
+OpenAI-protocol provider. On a machine where an agent's config already exists, committing to it
+also prints a `backup: ~/.config/agentsw/backups/transaction-<unique>` line; this sandbox starts
+with empty configs, so there is nothing to back up and none appear.
+
 ## Supported apps
 
 | App | Config written | Protocols |
@@ -172,6 +215,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.
@@ -208,9 +255,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)**,
@@ -245,9 +299,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
 
@@ -260,11 +333,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

@@ -17,20 +17,7 @@
 
 </div>
 
-```console
-$ 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 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
-               select in dsh with the model picker, or run: dsh web
-```
+![asw use myproxy 把一个供应商写进九个编码智能体](https://raw.githubusercontent.com/tchivs/agentsw/main/docs/demo.gif)
 
 `agentsw` 和短名 `asw` 是同一个可执行文件。
 
@@ -38,8 +25,8 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 
 - **它能去桌面应用去不了的地方。** 无头服务器、容器、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 注释，都会在重新同步后原样保留。
@@ -53,9 +40,33 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 - **区分接口形态。** `/v1/chat/completions` 与 `/v1/responses` 是两个不同端点；
   agentsw 记录供应商说的是哪一种，并且绝不把可用的 responses 降级。
 
-想要 GUI、MCP/Skills 同步、用量仪表盘或本地故障转移代理？用
-[cc-switch](https://github.com/farion1231/cc-switch)——那些它做得很好；agentsw 从它导入，
-而不是跟它抢。
+## 它和同类工具的关系
+
+有两件事别人做得比 agentsw 好，而且都值得你去看：
+
+- **[cc-switch](https://github.com/farion1231/cc-switch)**——桌面应用（Tauri），支持十个工具：一键切换、
+  90+ 供应商预设、MCP/Skills/Prompts 管理、本地路由与故障转移（含 API 格式转换）、用量与成本仪表盘、
+  会话管理、WebDAV/S3 同步。
+- **[cc-switch-cli](https://github.com/SaladDay/cc-switch-cli)**——同一思路的社区 CLI 分支：TUI + 可脚本化子命令、
+  七个工具、MCP 与 Skills、带 token 统计的守护进程代理、SQLite 存储。
+
+两者合起来覆盖 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw、Pi、
+Grok Build、MiniMax Code。agentsw 覆盖的是另外九个——Claude Code、Codex、omp、pi、prime-agent、
+opencode、Hermes、WorkBuddy、DeepSeek Harness——**其中四个另外两个工具根本不写。**
+
+| | agentsw | cc-switch | cc-switch-cli |
+|---|---|---|---|
+| 形态 | CLI，`--json` 可脚本化 | 桌面 GUI | TUI + CLI |
+| 从 models.dev + AI Gateway 取元数据，写入各应用自己的字段 | **是** | 无 | 无 |
+| MCP / Skills / Prompts 管理 | — | 有 | 有 |
+| 路由、API 格式转换、故障转移 | — | 有 | 有 |
+| 用量与成本仪表盘 | — | 有 | 有 |
+| 预设、会话、云同步、deep link | — | 有 | 部分 |
+| 读取对方的供应商库 | 有——只读 `import` | — | — |
+
+说实话的结论：**想要 GUI、MCP 管理或故障转移代理，用 cc-switch。** 如果你在用 omp、prime-agent、
+WorkBuddy 或 DeepSeek Harness，或者你希望每个智能体拿到的是真实模型参数而不是一个裸 id，
+那才是 agentsw 的用处。它读 cc-switch 的库，而不是跟它抢。
 
 ## 安装
 
@@ -76,7 +87,7 @@ agentsw                   # 全局安装后可用；短名 `asw` 完全等价
 ```
 
 **不带参数运行就是一个菜单——整个工具都在里面。** 添加供应商（自动识别或手动设置）、导入各智能体
-已有的供应商、切换供应商和默认模型、重新同步、更新模型列表、设置模型参数补充源、重命名或删除、
+已有的供应商、切换供应商和默认模型、同步供应商（重新获取模型列表再写入）、设置模型参数补充源、重命名或删除、
 安装/升级智能体、切换语言。首次运行会先问你要 English 还是简体中文，并提议接管你各智能体已经在用的配置。
 
 菜单里的每项操作都有对应的命令，方便脚本、CI 和无头机器——见 [命令](#命令)。
@@ -99,6 +110,31 @@ opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.co
 dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
+而这个工具真正的用处是另一条——一条命令写进所有检测到的智能体
+（也就是本页顶部那段动画里跑的东西，文字版）：
+
+```console
+$ asw use myproxy
+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
+ok   omp       ~/.omp/agent/models.yml
+               select in omp with: omp --model myproxy/glm-5.3-flash
+ok   pi        ~/.pi/agent/models.json, ~/.pi/agent/settings.json
+ok   prime     ~/.prime/agent/models.json, ~/.prime/agent/settings.json
+ok   opencode  ~/.config/opencode/opencode.json
+ok   hermes    ~/.hermes/config.yaml, ~/.hermes/.env
+ok   workbuddy ~/.workbuddy/models.json, ~/.workbuddy/settings.json
+               WorkBuddy watches models.json; models appear in the selector's custom section without restart
+ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
+               select in dsh with the model picker, or run: dsh web
+```
+
+唯一被跳过的是 `claude`：Claude Code 说的是 Anthropic 协议，而 `myproxy` 是 OpenAI 协议的供应商。
+在智能体的配置已经存在的机器上，提交它时还会打印一行 `backup: ~/.config/agentsw/backups/transaction-<unique>`；
+本沙箱从空配置开始，无物可备，因此没有这行。
+
 ## 支持的应用
 
 | 应用 | 写入的配置 | 协议 |
@@ -164,6 +200,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 和默认模型永不被过滤。
@@ -198,9 +238,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
 ```
 
 交互菜单的“设置并刷新模型参数补充源”提供“自动按需（推荐）”“始终补充”“关闭”，
@@ -230,8 +277,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` 刷新完就停，不写任何智能体。
 
 ## 命令
 
@@ -244,11 +308,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` |