docs(user): guide model discovery for third-party providers

docs/user/guide/providers.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
-providers.md: 105f9a0fcc635e17606d9b86df1a62af75e0c520
-providers.zh.md: fcebf9fe81bae54626ddb1c147513f9cb47dfea5
+providers.md: f84211a44d1be1ade67c52ef3669bbdbfd9fee6c
+providers.zh.md: 94ee37c21f9918f0793cbc3c07d5938f3323c167

docs/user/guide/providers.md

@@ -26,7 +26,13 @@ Choose **Add a custom provider** for a company gateway, self-hosted server, or p
 
 The Provider ID is permanent because requests, saved sessions, model defaults, and credential references use it. To rename a provider, add a new provider and delete the old one. The display name, base URL, protocol, credential, and models remain editable.
 
-Under **Model catalog**, choose **Fetch available models** to query the base URL and credential currently shown in the form. Selecting candidates updates the draft; the provider is not stored until you save. Catalog providers use their installed catalog without a network request.
+### Discover models
+
+Under **Model catalog**, choose **Fetch available models** to ask the endpoint what it serves. The request goes to the base URL and API protocol currently in the form, with the key typed there or, for a saved provider, the stored one: `openai-completions` and `openai-responses` call `GET /models` with bearer auth, and `anthropic-messages` calls Anthropic's native `GET /v1/models`, whether the base URL is written with or without a trailing `/v1`. The reply may be OpenAI's `data` array or the enriched `models` object some gateways return; either way each candidate arrives with its id and, when the endpoint reports them, a display name, context window, and max output tokens.
+
+The reply opens a searchable picker rather than writing anything. Search matches ids and display names, **Select all** adds the visible results, **Deselect all** clears every selection including hidden ones, and **Add selected** copies the chosen candidates into the model list. The provider is not stored until you save or create it, so a fetch is safe to repeat while drafting.
+
+A catalog provider is answered from the installed catalog without a network request, even when its base URL points at a gateway. To see what a gateway actually serves under a catalog protocol, fetch through a custom provider with the same base URL, or enter the gateway's ids by hand.
 
 ::: tip The form is deliberately small
 The Models page exposes only what a route needs to exist: the API key, display name, base URL, API protocol, and for each model its id, display name, context window, and max output tokens. Every other field — reasoning effort levels, image input, request-compatibility switches, headers, timeouts, retry policy — is set in `$DSH_HOME/settings.yaml`, the same document the page writes. Open it with **Open configuration file** in the Settings header; the adapters re-read it on the next request, so nothing needs a restart. The subsections below cover the fields most gateways need, and the [generated configuration reference](../../config-catalog.md#deepseek-aidsh-llm-pi-ai) lists them all.
@@ -172,6 +178,7 @@ If a saved default names a provider that was deleted, the composer displays **Se
 - **`MISSING_CREDENTIAL`** — Store the provider key through the Models page or supply the referenced environment variable.
 - **`UNKNOWN_MODEL`** — Select a configured model or add the missing model to the custom provider.
 - **Fetching available models returns 401** — Check the key. Model discovery calls the OpenAI-compatible `GET /models` endpoint; enter models manually for endpoints that do not provide it.
+- **Fetching available models reports neither a `data` array nor a `models` object** — The endpoint's listing is in a format discovery does not read. Enter the models by hand.
 - **The gateway refuses every request although the key and URL are right** — Its request shape differs from OpenAI's. Start with `compat.supportsDeveloperRole: false` and `compat.maxTokensField: max_tokens` on the route.
 - **Only reasoning models fail** — pi-ai sends their system prompt as the `developer` role, which the gateway rejects. Set `compat.supportsDeveloperRole: false`.
 - **The Effort menu is empty for a model you entered by hand** — It declares no levels. Add `reasoningEfforts` to the model in `settings.yaml`.

docs/user/guide/providers.zh.md

@@ -26,7 +26,13 @@
 
 Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。如需重命名提供方，请添加新提供方并删除旧提供方。显示名称、基础 URL、协议、凭据和模型仍可编辑。
 
-在**模型目录**中选择**获取可用模型**，可查询表单当前显示的基础 URL 和凭据。选择候选项只会更新草稿；保存前不会存储提供方。目录提供方使用已安装目录，不发起网络请求。
+### 探测模型
+
+在**模型目录**中选择**获取可用模型**，即可询问端点它提供哪些模型。请求发往表单当前显示的 API 地址和 API 协议，密钥用表单里输入的，已保存的提供方则用已存储的密钥：`openai-completions` 和 `openai-responses` 以 bearer 认证调用 `GET /models`，`anthropic-messages` 调用 Anthropic 原生的 `GET /v1/models`，API 地址末尾带不带 `/v1` 都可以。响应可以是 OpenAI 的 `data` 数组，也可以是部分网关返回的富信息 `models` 对象；无论哪种，每个候选都带有 ID，端点若报告了显示名称、上下文窗口和最大输出 token 数，也会一并带上。
+
+响应会打开一个可搜索的选择框，而不是直接写入任何内容。搜索同时匹配 ID 和显示名称，**全选**只加入可见结果，**取消全选**清空包括隐藏项在内的全部勾选，**添加所选**把选中的候选复制进模型列表。保存或创建之前提供方不会被存储，因此起草时可以放心重复探测。
+
+目录提供方一律由已安装目录作答，不发起网络请求，即使其 API 地址指向网关也是如此。要查看网关在目录协议下实际提供的模型，请用同一 API 地址通过自定义提供方探测，或手动录入网关的模型 ID。
 
 ::: tip 表单刻意保持精简
 模型页只开放让一条路由得以存在的字段：API 密钥、显示名称、API 地址、API 协议，以及每个模型的 ID、显示名称、上下文窗口和最大输出 token 数。其余所有字段——推理等级、图片输入、请求兼容性开关、请求头、超时、重试策略——都在 `$DSH_HOME/settings.yaml` 中设置，也就是模型页写入的同一份文档。点击设置页顶部的**打开配置文件**即可打开它；适配器会在下一次请求时重新读取，无需重启任何东西。下面各小节介绍多数网关会用到的字段，[生成的配置参考](../../config-catalog.zh.md#deepseek-aidsh-llm-pi-ai)则列出全部字段。
@@ -172,6 +178,7 @@ llm-pi-ai:
 - **`MISSING_CREDENTIAL`**：通过模型页存储提供方密钥，或提供被引用的环境变量。
 - **`UNKNOWN_MODEL`**：选择已配置的模型，或向自定义提供方添加缺失的模型。
 - **获取可用模型返回 401**：检查密钥。模型发现会调用 OpenAI 兼容的 `GET /models` 端点；对于不提供该端点的服务，请手动输入模型。
+- **获取可用模型提示既没有 `data` 数组也没有 `models` 对象**：端点返回的列表格式不在探测的读取范围内。请手动输入模型。
 - **密钥与地址都正确，网关却拒绝每一个请求**：它的请求形状与 OpenAI 不同。先在路由上设 `compat.supportsDeveloperRole: false` 与 `compat.maxTokensField: max_tokens`。
 - **只有推理模型失败**：pi-ai 把它们的系统提示词以 `developer` 角色发出，而网关拒绝该角色。设 `compat.supportsDeveloperRole: false`。
 - **手动录入的模型的推理等级菜单为空**：该模型没有声明任何等级。在 `settings.yaml` 中给该模型加上 `reasoningEfforts`。