From f7cd0b1e67690fa66fc47efdb584a7a9b8a6a4e4 Mon Sep 17 00:00:00 2001 From: Jacobinwwey Date: Wed, 27 May 2026 08:25:19 -0500 Subject: [PATCH] docs(provider-settings): sync bounded discovery and token-guidance truth --- README.md | 17 ++++++++++++----- README_zh.md | 17 ++++++++++++----- change.md | 3 +++ ...s-simplification-and-model-discovery-plan.md | 11 +++++++++++ ...lification-and-model-discovery-plan.zh-CN.md | 11 +++++++++++ 5 files changed, 49 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a0331889..e6abe4cf 100644 --- a/README.md +++ b/README.md @@ -247,15 +247,15 @@ Access plugin settings via: ### LLM Provider Configuration 1. **Active Provider**: Select the LLM provider you want to use from the dropdown menu. 2. **Provider Settings**: Configure the specific settings for the selected provider: - * **API Key**: Required for most cloud providers (e.g., OpenAI, Anthropic, DeepSeek, Qwen, Qwen Code, Doubao, Moonshot, Xiaomi MiMo, GLM, Z AI, MiniMax, Huawei Cloud MaaS, Baidu Qianfan, SiliconFlow, Google, Mistral, Azure OpenAI, OpenRouter, xAI, Groq, Together, Fireworks, Requesty). Not needed for Ollama. Optional for LM Studio and the generic `OpenAI Compatible` preset when your endpoint accepts anonymous or placeholder access. + * **API Key**: Required for most cloud providers (e.g., OpenAI, Anthropic, DeepSeek, Qwen, Qwen Code, Doubao, Moonshot, Xiaomi MiMo, GLM, Z AI, MiniMax, Huawei Cloud MaaS, Baidu Qianfan, SiliconFlow, Google, Mistral, Azure OpenAI, OpenRouter, xAI, Groq, Together, Fireworks, Nebius, Cerebras, Hugging Face, Vercel AI Gateway, Requesty). Not needed for Ollama. Optional for LM Studio, LiteLLM, and the generic `OpenAI Compatible` preset when your endpoint accepts anonymous or placeholder access. * **Base URL / Endpoint**: The API endpoint for the service. Defaults are provided, but you may need to change this for local models (LMStudio, Ollama), gateways (OpenRouter, Requesty, OpenAI Compatible), or specific Azure deployments. **Required for Azure OpenAI.** * **Model**: The specific model name/ID to use (e.g., `gpt-4o`, `claude-3-5-sonnet-20240620`, `google/gemini-flash-1.5`, `grok-4`, `moonshotai/kimi-k2-instruct-0905`, `accounts/fireworks/models/kimi-k2p5`, `anthropic/claude-3-7-sonnet-latest`). Ensure the model is available at your endpoint/provider. * **API Version (Azure Only)**: Required for Azure OpenAI deployments (e.g., `2024-02-15-preview`). * **Advanced Settings**: Secondary tuning controls such as `Temperature`, `Top-p`, reasoning hints, DeepSeek thinking mode, and the provider-specific output-token override now live behind **Show advanced settings**. If a provider already has saved advanced overrides, this section auto-expands so existing behavior stays visible instead of being silently hidden. - * **Fetch Model List**: Supported providers can query the endpoint for available model IDs without replacing manual model entry. In the first batch this covers OpenAI-compatible `/models`, Ollama tags, and Google Gemini model listing. The fetched list is transient suggestions only; your saved `Model` string remains the source of truth. + * **Fetch Model List**: Supported providers can query the endpoint for available model IDs without replacing manual model entry. The current bounded support covers OpenAI-compatible `/models`, the dedicated Vercel AI Gateway registry endpoint, Ollama tags, and Google Gemini model listing. Presets such as LiteLLM and Hugging Face still stay manual-first for model entry until their discovery semantics are implemented explicitly. The fetched list is transient suggestions only; your saved `Model` string remains the source of truth. 3. **Test Connection**: Use the "Test Connection" button for the active provider to verify your settings. OpenAI-compatible providers now use provider-aware checks: endpoints such as `Qwen`, `Qwen Code`, `Doubao`, `Moonshot`, `Xiaomi MiMo`, `GLM`, `Z AI`, `MiniMax`, `Huawei Cloud MaaS`, `Baidu Qianfan`, `SiliconFlow`, `Groq`, `Together`, `Fireworks`, `LMStudio`, and `OpenAI Compatible` probe `chat/completions` directly, while providers with a reliable `/models` endpoint can still use model listing first. If the first probe fails with a transient network disconnect such as `ERR_CONNECTION_CLOSED`, Notemd automatically falls back to the stable retry sequence instead of failing immediately. 4. **Manage Provider Configurations**: Use the "Export Providers" and "Import Providers" buttons to save/load your LLM provider settings to/from a `notemd-providers.json` file within the plugin's configuration directory. This allows for easy backup and sharing. -5. **Preset Coverage**: In addition to the original providers, Notemd now includes preset entries for `Qwen`, `Qwen Code`, `Doubao`, `Moonshot`, `Xiaomi MiMo`, `GLM`, `Z AI`, `MiniMax`, `Huawei Cloud MaaS`, `Baidu Qianfan`, `SiliconFlow`, `xAI`, `Groq`, `Together`, `Fireworks`, `Requesty`, and a generic `OpenAI Compatible` target for LiteLLM, vLLM, Perplexity, Vercel AI Gateway, or custom proxies. +5. **Preset Coverage**: In addition to the original providers, Notemd now includes preset entries for `Qwen`, `Qwen Code`, `Doubao`, `Moonshot`, `Xiaomi MiMo`, `GLM`, `Z AI`, `MiniMax`, `Huawei Cloud MaaS`, `Baidu Qianfan`, `SiliconFlow`, `xAI`, `Groq`, `Together`, `Fireworks`, `LiteLLM`, `Nebius`, `Cerebras`, `Hugging Face`, `Vercel AI Gateway`, `Requesty`, and a generic `OpenAI Compatible` target for custom proxies. LLM ### Multi-Model Configuration @@ -389,8 +389,8 @@ Access plugin settings via: - **Batch Size**: (Visible only when parallelism is enabled) The number of files to group into a single batch. (Default: 50, Range: 10-200) - **Delay Between Batches (ms)**: (Visible only when parallelism is enabled) An optional delay in milliseconds between processing each batch, which can help manage API rate limits. (Default: 1000ms) - **API Call Interval (ms)**: Minimum delay in milliseconds *before and after* each individual LLM API call. Crucial for low-rate APIs or to prevent 429 errors. Set to 0 for no artificial delay. (Default: 500ms) -- **Max Tokens**: Maximum tokens the LLM should generate per response chunk. Affects cost and detail. (Default: 8192) -- **Chunk Word Count**: Maximum words per chunk sent to the LLM. Affects the number of API calls for large files. Recommended: about one third of **Max Tokens**. If you have not customized it yet, changing **Max Tokens** auto-fills the recommended chunk size for you. (Default: 3000) +- **Max Tokens**: Global maximum tokens the LLM should generate per response chunk. Affects cost and detail. If the active provider has a **Provider output token override** set in advanced settings, that provider-specific cap takes precedence. (Default: 8192) +- **Chunk Word Count**: Maximum words per chunk sent to the LLM. Affects the number of API calls for large files. Recommended default: one third of **Max Tokens**, rounded up. If you have not customized it yet, changing **Max Tokens** auto-fills the recommended chunk size for you. (Default: 3000) - **Enable Duplicate Detection**: Toggles the basic check for duplicate words within processed content (results in console). (Default: Enabled) Processing Parameters Language settings @@ -652,6 +652,11 @@ This is the core functionality focused on identifying concepts and adding `[[wik | Groq | Cloud | Yes | Fast OpenAI-compatible inference for hosted OSS models | | Together | Cloud | Yes | OpenAI-compatible endpoint for hosted OSS models | | Fireworks | Cloud | Yes | OpenAI-compatible inference endpoint | +| LiteLLM | Gateway | Optional | Self-hosted OpenAI-compatible proxy preset; default local endpoint is `http://localhost:4000/v1` | +| Nebius | Cloud | Yes | Nebius AI Studio OpenAI-compatible endpoint | +| Cerebras | Cloud | Yes | Cerebras Cloud OpenAI-compatible endpoint for fast hosted inference | +| Hugging Face | Gateway | Yes | Hugging Face hosted inference router preset | +| Vercel AI Gateway | Gateway | Yes | Vercel multi-provider gateway preset with dedicated model discovery | | Requesty | Gateway | Yes | Multi-provider router behind one API key | | OpenAI Compatible | Gateway | Optional | Generic preset for LiteLLM, vLLM, Perplexity, Vercel AI Gateway, etc. | | LMStudio | Local | Optional (`EMPTY`) | Runs models locally via LM Studio server | @@ -662,6 +667,8 @@ This is the core functionality focused on identifying concepts and adding `[[wik *Note: `Doubao` usually expects an Ark endpoint/deployment ID in the model field rather than a raw model family name. The settings screen now warns when the placeholder value is still present and blocks connection tests until you replace it with a real endpoint ID.* *Note: `Z AI` targets the international `api.z.ai` line, while `GLM` keeps the mainland China BigModel endpoint. Choose the preset that matches your account region.* *Note: China-focused presets use chat-first connection checks so the test validates the actual configured model/deployment, not only API-key reachability.* +*Note: `Vercel AI Gateway` uses a dedicated model-registry discovery path instead of the generic OpenAI-compatible `/models` endpoint.* +*Note: `LiteLLM` and `Hugging Face` presets are supported for runtime calls, but the settings UI currently keeps model entry manual-first rather than claiming remote discovery support.* *Note: `OpenAI Compatible` is intended for custom gateways and proxies. Set the Base URL, API key policy, and model ID according to your provider's documentation.* ## Network Usage & Data Handling diff --git a/README_zh.md b/README_zh.md index 886f6864..8a271539 100644 --- a/README_zh.md +++ b/README_zh.md @@ -229,18 +229,18 @@ Notemd 通过与各种大型语言模型 (LLM) 集成来增强您的 Obsidian : 配置所选提供商的具体设置： - - **API 密钥**: 大多数云提供商（例如 OpenAI、Anthropic、DeepSeek、Qwen、Qwen Code、Doubao、Moonshot、Xiaomi MiMo、GLM、Z AI、MiniMax、Huawei Cloud MaaS、Baidu Qianfan、SiliconFlow、Google、Mistral、Azure OpenAI、OpenRouter、xAI、Groq、Together、Fireworks、Requesty）需要。Ollama 不需要。LMStudio 和通用的 `OpenAI Compatible` 预设在某些允许匿名或占位密钥的端点上可留空。 + - **API 密钥**: 大多数云提供商（例如 OpenAI、Anthropic、DeepSeek、Qwen、Qwen Code、Doubao、Moonshot、Xiaomi MiMo、GLM、Z AI、MiniMax、Huawei Cloud MaaS、Baidu Qianfan、SiliconFlow、Google、Mistral、Azure OpenAI、OpenRouter、xAI、Groq、Together、Fireworks、Nebius、Cerebras、Hugging Face、Vercel AI Gateway、Requesty）需要。Ollama 不需要。LMStudio、LiteLLM 和通用的 `OpenAI Compatible` 预设在某些允许匿名或占位密钥的端点上可留空。 - **基础 URL / 端点**: 服务的 API 端点。提供了默认值，但您可能需要为本地模型（LMStudio、Ollama）、网关（OpenRouter、Requesty、OpenAI Compatible）或特定 Azure 部署修改此项。**Azure OpenAI 必填。** - **模型**: 要使用的具体模型名称/ID（例如 `gpt-4o`, `claude-3-5-sonnet-20240620`, `google/gemini-flash-1.5`, `grok-4`, `moonshotai/kimi-k2-instruct-0905`, `accounts/fireworks/models/kimi-k2p5`, `anthropic/claude-3-7-sonnet-latest`）。请确保该模型在您的端点/提供商处可用。 - **API 版本（仅 Azure）**: Azure OpenAI 部署需要（例如 `2024-02-15-preview`）。 - **高级设置**: `Temperature`、`Top-p`、reasoning hint、DeepSeek thinking mode、provider 级 output-token override 等次级调优项现在统一收入 **显示高级设置**。如果某个 provider 已经保存了 advanced override，该区域会默认展开，避免现有行为被静默藏起来。 - - **获取模型列表**: 已支持的 provider 可以直接向端点查询可用 model ID，但不会替代手动 `Model` 输入。首批仅覆盖 OpenAI-compatible `/models`、Ollama tags 与 Google Gemini model listing。获取到的列表只是瞬时建议，持久化真值仍然是用户保存的 `Model` 字符串。 + - **获取模型列表**: 已支持的 provider 可以直接向端点查询可用 model ID，但不会替代手动 `Model` 输入。当前有界支持覆盖 OpenAI-compatible `/models`、Vercel AI Gateway 的专用模型注册表接口、Ollama tags 与 Google Gemini model listing。LiteLLM、Hugging Face 等预设目前仍保持手动填写 model 为主，不会误报成已支持远端发现。获取到的列表只是瞬时建议，持久化真值仍然是用户保存的 `Model` 字符串。 3. **测试连接**: 使用活动提供商的“测试连接”按钮来验证您的设置。OpenAI-compatible 提供商现在会按 provider 特性自动选择测试策略：`Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow`、`Groq`、`Together`、`Fireworks`、`LMStudio` 与 `OpenAI Compatible` 会直接探测 `chat/completions`，而具备稳定 `/models` 端点的服务仍会优先走模型列表探测。如果首次探测遇到 `ERR_CONNECTION_CLOSED` 这类瞬时网络断连，Notemd 会自动切入稳定重试序列，而不是立刻报错。 4. **管理提供商配置**: 使用“导出提供商”和“导入提供商”按钮将您的 LLM 提供商设置保存到插件配置目录中的 `notemd-providers.json` 文件或从中加载。这便于备份和共享。 -5. **预设覆盖范围**: 除了原有提供商外，Notemd 现在还内置了 `Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow`、`xAI`、`Groq`、`Together`、`Fireworks`、`Requesty` 以及通用的 `OpenAI Compatible` 预设，可用于 LiteLLM、vLLM、Perplexity、Vercel AI Gateway 或自定义代理。 +5. **预设覆盖范围**: 除了原有提供商外，Notemd 现在还内置了 `Qwen`、`Qwen Code`、`Doubao`、`Moonshot`、`Xiaomi MiMo`、`GLM`、`Z AI`、`MiniMax`、`Huawei Cloud MaaS`、`Baidu Qianfan`、`SiliconFlow`、`xAI`、`Groq`、`Together`、`Fireworks`、`LiteLLM`、`Nebius`、`Cerebras`、`Hugging Face`、`Vercel AI Gateway`、`Requesty` 以及通用的 `OpenAI Compatible` 预设，可用于自定义代理。 LLM @@ -419,8 +419,8 @@ Notemd 通过与各种大型语言模型 (LLM) 集成来增强您的 Obsidian - **批处理大小**: (仅在启用并行化时可见) 分组到单个批次中的文件数。（默认值：50，范围：10-200） - **批处理间隔延迟（毫秒）**: (仅在启用并行化时可见) 处理每个批次之间的可选延迟（以毫秒为单位），这有助于管理API速率限制。（默认值：1000毫秒） - **API 调用间隔（毫秒）**: 每个单独的 LLM API 调用之前和之后的最小延迟（以毫秒为单位）。对于低速率 API 或防止 429 错误至关重要。设置为 0 表示没有人为延迟。（默认值：500毫秒） -- **最大令牌数**: LLM 每个响应块应生成的最大令牌数。影响成本和细节。（默认值：8192） -- **分块字数**: 发送给 LLM 的每个块的最大字数。影响大型文件的 API 调用次数。推荐约为 **最大令牌数** 的三分之一；如果您尚未自定义该值，修改最大令牌数时插件会自动填入推荐分块值。（默认值：3000） +- **最大令牌数**: LLM 每个响应块应生成的全局最大令牌数。影响成本和细节。如果当前 provider 在高级设置中填写了“提供商输出 Token 覆盖上限”，则会优先使用该 provider 级上限。（默认值：8192） +- **分块字数**: 发送给 LLM 的每个块的最大字数。影响大型文件的 API 调用次数。默认推荐值为 **最大令牌数** 的三分之一并向上取整；如果您尚未自定义该值，修改最大令牌数时插件会自动填入推荐分块值。（默认值：3000） - **启用重复检测**: 切换对处理内容中重复单词的基本检查（结果在控制台中）。（默认值：启用） Processing Parameters Language settings @@ -704,6 +704,11 @@ Notemd 通过与各种大型语言模型 (LLM) 集成来增强您的 Obsidian | Groq | 云 | 是 | 面向托管开源模型的高速 OpenAI-compatible 推理端点 | | Together | 云 | 是 | 面向托管开源模型的 OpenAI-compatible 端点 | | Fireworks | 云 | 是 | OpenAI-compatible 推理端点 | +| LiteLLM | 网关 | 可选 | 自托管 OpenAI-compatible 代理预设；默认本地端点为 `http://localhost:4000/v1` | +| Nebius | 云 | 是 | Nebius AI Studio 的 OpenAI-compatible 端点 | +| Cerebras | 云 | 是 | Cerebras Cloud 的 OpenAI-compatible 高速推理端点 | +| Hugging Face | 网关 | 是 | Hugging Face 托管推理路由预设 | +| Vercel AI Gateway | 网关 | 是 | Vercel 多提供商网关预设，并带专用模型发现实现 | | Requesty | 网关 | 是 | 单一 API Key 对接多提供商路由 | | OpenAI Compatible | 网关 | 可选 | 通用预设，可接 LiteLLM、vLLM、Perplexity、Vercel AI Gateway 等 | | LMStudio | 本地 | 可选（`EMPTY`） | LM Studio 本地 OpenAI-compatible 服务 | @@ -714,6 +719,8 @@ Notemd 通过与各种大型语言模型 (LLM) 集成来增强您的 Obsidian *`Doubao` 预设通常要求在模型字段中填写 Ark Endpoint/Deployment ID，而不是直接填写模型家族名。设置页现在会在仍使用默认占位值时发出警告，并阻止连接测试，直到你替换为真实 Endpoint ID。* *`Z AI` 面向国际 `api.z.ai` 线路，而 `GLM` 继续保留中国大陆 BigModel 入口。请根据账户区域选择对应预设。* *中国区兼容协议预设默认使用 chat-first 测试，这样可以同时验证 API Key、模型名或部署 ID 是否真正可用。* +*`Vercel AI Gateway` 的模型发现走专用模型注册表接口，而不是 generic OpenAI-compatible `/models`。* +*`LiteLLM` 与 `Hugging Face` 预设已经支持运行时调用，但设置页目前仍将模型填写视为 manual-first，不会误导为已支持远端模型发现。* *`OpenAI Compatible` 预设用于自定义网关与代理，请按对应服务文档填写 Base URL、鉴权方式和模型 ID。* ## 网络使用与数据处理 diff --git a/change.md b/change.md index cc8d1daa..9d4984c4 100644 --- a/change.md +++ b/change.md @@ -17,6 +17,7 @@ This document summarizes the major functional and architectural changes implemen - Added provider-field taxonomy metadata (`core`, `contextual`, `advanced`, `developer`) so the provider settings panel can render required/default-visible controls separately from secondary tuning controls. - Added lightweight in-settings model discovery for OpenAI-compatible `/models`, Ollama tags, and Google Gemini model listing. Discovery results are transient suggestions only; persisted provider state still uses the existing manual `model` string. +- Expanded the bounded OpenAI-compatible preset set with `LiteLLM`, `Nebius`, `Cerebras`, `Hugging Face`, and `Vercel AI Gateway`, while keeping discovery support honest per endpoint family rather than over-claiming generic `/models` parity. - Added the `Relax input file restrictions` developer setting plus the shared supported-input reader layer. - Extended advanced folder-task selection with profile-aware folder locking, temporary overrides, preview panels, and example/preset chips. @@ -24,6 +25,8 @@ This document summarizes the major functional and architectural changes implemen - Provider advanced settings now auto-expand when a provider already has saved advanced overrides, preserving visibility for existing `data.json` behavior instead of silently collapsing non-default live config. - Added discovery prerequisite validation and endpoint normalization so `/chat/completions`, `/models`, and `/tags` style base URLs do not cause malformed model-list requests. +- Added canonical provider-name normalization for legacy persisted/imported aliases such as `Xiaomi` -> `Xiaomi MiMo`, preventing duplicate provider rows across settings load and profile import. +- Added model-aware token guidance in provider settings so the current model's known output-token cap is surfaced beside `Model`, provider override, and global `Max tokens`, with immediate re-render after edits. - Unified task-aware input validation across sidebar actions, command entrypoints, batch adapters, and path-based diagram generation. - Corrected relaxed-mode batch empty-folder notices so they describe supported inputs rather than hard-coded `.md` / `.txt` assumptions. - Kept source-mutating and verbatim-sensitive flows intentionally restricted while widening only the safe allowlist. diff --git a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md index a27272c2..37a8a2ba 100644 --- a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md +++ b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md @@ -129,12 +129,18 @@ What is now present on current main: - derived auto-expand when persisted advanced values exist - optional fetch-models UI wiring 4. matching locale keys, README/update-surface sync, and focused tests cover the new control-plane behavior. +5. current main also now carries bounded provider-breadth follow-through for this lane: + - canonical provider alias normalization for legacy persisted names such as `Xiaomi` -> `Xiaomi MiMo` + - additional OpenAI-compatible presets aligned to the shared runtime (`LiteLLM`, `Nebius`, `Cerebras`, `Hugging Face`, `Vercel AI Gateway`) + - provider-family-specific discovery handling for Vercel AI Gateway's `v3/ai/config` registry endpoint + - model-aware token guidance in settings, so the active model's known max output-token cap is surfaced beside `Model`, provider override, and global `Max tokens` What remains intentionally out of scope: 1. persisted remote provider model catalogs; 2. model CRUD / health-check management UI; 3. broad all-provider model discovery claims beyond the verified first batch. +4. pretending that every OpenAI-compatible gateway should expose the same `/models` semantics. ## 4. Cherry Studio Comparison @@ -225,6 +231,7 @@ Current checkpoint: 1. landed on current main; 2. the metadata shape remains declarative and field-scoped. +3. backward compatibility now also includes canonicalization of legacy provider names during settings load and provider-profile import/export flows. ### Phase 2: settings renderer refactor @@ -253,6 +260,7 @@ Current checkpoint: 1. landed on current main; 2. default/core, contextual, and advanced sections are wired through shared metadata; 3. CSS/layout support and focused style tests are now part of the shipped surface. +4. provider settings now surface model-aware token guidance and refresh immediately after `model`, global `Max tokens`, or chunk-size edits commit. ### Phase 3: lightweight discovery service @@ -284,6 +292,7 @@ Current checkpoint: 1. landed on current main for the planned first batch; 2. it keeps manual `model` entry as the persisted source of truth; 3. unsupported providers still degrade to manual entry rather than a heavy catalog subsystem. +4. the bounded gateway split is now explicit: Vercel AI Gateway uses its dedicated registry endpoint, while presets such as LiteLLM and Hugging Face remain manual-first rather than over-claiming discovery support. ### Phase 4: UI integration @@ -298,6 +307,7 @@ Current checkpoint: 1. fetch-models UI wiring and transient suggestion state are now on current main; 2. styling support for the new provider-panel surfaces is landed; 3. README/update surfaces now describe the same bounded behavior. +4. apply-success feedback and collapse-state persistence are now covered by focused behavior tests. ### Phase 5: tests and documentation @@ -320,6 +330,7 @@ Current checkpoint: 1. focused i18n/test updates are landed on current main; 2. canonical docs now describe the lane as landed current-main truth rather than isolated implementation progress; 3. verification evidence now includes targeted provider-settings/model-discovery tests plus full repository gates. +4. the current settings surface also documents the relationship between global `Max tokens` and provider-specific output-token overrides, to reduce confusion around the two token caps. ## 7. Explicit Non-Goals diff --git a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md index 02252858..46a4e33e 100644 --- a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md +++ b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md @@ -129,12 +129,18 @@ canonical: true - 基于持久化 advanced 值的派生 auto-expand - 可选的 fetch-models UI wiring 4. 对应 locale keys、README/update surface 与聚焦测试也已经补入。 +5. 当前 main 还继续补齐了这条 lane 的有界 provider 宽度收口： + - 对旧持久化 provider 名称做 canonical alias 归一化，例如 `Xiaomi` -> `Xiaomi MiMo` + - 补入并对齐共享 runtime 的额外 OpenAI-compatible 预设（`LiteLLM`、`Nebius`、`Cerebras`、`Hugging Face`、`Vercel AI Gateway`） + - 对 Vercel AI Gateway 单独走 `v3/ai/config` registry endpoint，而不是假装它和 generic `/models` 完全等价 + - 在设置页中加入 model-aware token guidance，使当前模型的已知最大输出 Token 上限能在 `Model`、provider override 与全局 `Max tokens` 旁被明确展示 仍然刻意不做的内容： 1. 持久化远程 provider model catalog； 2. model CRUD / health-check management UI； 3. 对首批之外 provider 的泛化 discovery 覆盖宣称。 +4. 假装所有 OpenAI-compatible gateway 都共享完全相同的 `/models` 语义。 ## 4. Cherry Studio 对照结论 @@ -225,6 +231,7 @@ Cherry Studio 值得复用的点： 1. 已落地到 current main； 2. 当前 metadata 形态仍保持 declarative、field-scoped。 +3. backward compatibility 现在还覆盖了 legacy provider name 的 canonicalization，包括 settings load 与 provider-profile import/export。 ### Phase 2：settings renderer 重构 @@ -253,6 +260,7 @@ Cherry Studio 值得复用的点： 1. 已落地到 current main； 2. default/core、contextual 与 advanced 分区现已通过共享 metadata 接线； 3. 对应 CSS/layout 支撑与样式测试也已进入发货面。 +4. provider settings 现在还会展示 model-aware token guidance，并在 `model`、全局 `Max tokens`、chunk-size 提交后立即刷新。 ### Phase 3：lightweight discovery service @@ -284,6 +292,7 @@ Cherry Studio 值得复用的点： 1. 已按计划首批 family 落地到 current main； 2. 它仍保持手动 `model` 输入为持久化 source of truth； 3. 不支持的 provider 仍然降级回手动输入，而不是引入重型 catalog 子系统。 +4. gateway 的有界分流现在已经显式化：Vercel AI Gateway 走专用 registry endpoint；LiteLLM、Hugging Face 等预设则继续保持 manual-first，而不是过度宣称 discovery 支持。 ### Phase 4：UI 接入 @@ -298,6 +307,7 @@ Cherry Studio 值得复用的点： 1. fetch-models UI wiring 与瞬时 suggestion state 已进入 current main； 2. 新 provider-panel surface 的 styling 支撑已经落地； 3. README / update surface 现在也已描述同样的有界行为。 +4. “应用成功提示”与 discovered-models collapse-state/persistence 行为现在也有聚焦行为测试覆盖。 ### Phase 5：测试与文档 @@ -320,6 +330,7 @@ Cherry Studio 值得复用的点： 1. 聚焦的 i18n/test 更新已经落地到 current main； 2. canonical 文档现在把这条线描述为 current-main 已落地真值，而不是隔离实现进展； 3. 验证证据现已包含 targeted provider-settings/model-discovery tests 与完整仓库门禁。 +4. 当前 settings surface 还额外写清了全局 `Max tokens` 与 provider-specific output-token override 的关系，以降低“两处 max tokens”造成的理解成本。 ## 7. 显式非目标