From 340bfbbd0736efaca5af9bcab2af654f59282d02 Mon Sep 17 00:00:00 2001
From: KiriAky 107 <KiriAky107@qq.com>
Date: Sun, 30 Aug 2026 10:44:13 +0800
Subject: [PATCH] =?UTF-8?q?docs(provider):=20=E8=A1=A5=E5=85=85=E6=A8=A1?=
 =?UTF-8?q?=E5=9E=8B=E5=8F=91=E7=8E=B0=E4=B8=8E=E5=87=AD=E6=8D=AE=E8=BE=B9?=
 =?UTF-8?q?=E7=95=8C=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/模型提供商与模型发现开发说明.md | 91 ++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/模型提供商与模型发现开发说明.md

diff --git a/docs/模型提供商与模型发现开发说明.md b/docs/模型提供商与模型发现开发说明.md
new file mode 100644
index 0000000..247cbb2
--- /dev/null
+++ b/docs/模型提供商与模型发现开发说明.md
@@ -0,0 +1,91 @@
+# 模型提供商与模型发现开发说明
+
+## 1. 本次目标
+
+本次完善设置页的模型提供商配置，不改变 Agent、Chat 和 Skill 对统一 Model Core 接口的依赖：
+
+- 提供 OpenAI、DeepSeek 和 Ollama 配置预设；
+- 保存 Provider 后自动获取该账号或服务当前可用的模型列表；
+- 支持手动刷新模型列表和选择默认模型；
+- 保留自定义 OpenAI-Compatible 服务入口；
+- 不在 Vue、FastAPI 配置或仓库文件中保存、回显 API Key 明文。
+
+## 2. 接口与实现
+
+### 2.1 Provider 预设
+
+新增接口：
+
+```http
+GET /api/providers/presets
+```
+
+预设由后端 `ProviderFactory` 提供，前端只消费名称、协议类型、Base URL 和是否需要凭据等配置元数据，不直接实现厂商协议。
+
+当前预设：
+
+| 提供商 | Provider Type | Base URL |
+| --- | --- | --- |
+| OpenAI | `openai_chat` | `https://api.openai.com/v1` |
+| DeepSeek | `openai_compatible` | `https://api.deepseek.com` |
+| Ollama | `ollama` | `http://127.0.0.1:11434` |
+
+OpenAI 和 DeepSeek 都通过项目已有的 `OpenAICompatibleProvider` 访问。模型发现分别请求 Base URL 下的 `/models`，不引入厂商 SDK。
+
+### 2.2 自动获取模型
+
+模型列表继续使用既有接口：
+
+```http
+GET /api/providers/{provider_id}/models
+```
+
+设置页在以下时机调用该接口：
+
+- Provider 列表加载完成后，为所有已启用 Provider 自动刷新；
+- 新增或编辑 Provider 保存成功后自动刷新；
+- 用户点击“刷新模型”时手动刷新；
+- 打开已有 Provider 的编辑窗口时刷新可选模型。
+
+前端按模型名称排序并按 `model_id` 去重。获取结果保存在 `providerStore.modelsByProvider`，加载状态和错误按 Provider 隔离，单个外部服务失败不会阻止其他服务展示。
+
+获取成功后，Provider 卡片展示模型数量和默认模型下拉框。更换默认模型会调用 Provider PATCH 接口写回配置；编辑窗口仍允许手动输入模型 ID，以兼容未出现在列表中的代理模型或部署别名。
+
+### 2.3 错误处理
+
+Provider Adapter 的错误在 FastAPI 路由转换为统一 API Error：
+
+| Provider Error | HTTP 状态 |
+| --- | --- |
+| `PROVIDER_AUTH_FAILED` | 401 |
+| `MODEL_NOT_FOUND` | 404 |
+| `PROVIDER_RATE_LIMITED` | 429 |
+| `PROVIDER_TIMEOUT` | 504 |
+| 其他 Provider 可用性错误 | 502 |
+
+前端在对应 Provider 卡片内展示失败原因，并允许用户修正 Credential ID、Base URL 后重新获取。
+
+## 3. 凭据边界
+
+设置页只保存 `credential_id`。桌面 Host 负责将 Stronghold 中的密钥以临时凭据上下文注入 AI Core，`EnvironmentCredentialResolver` 根据 Credential ID 解析。API Key 明文不会进入 Provider Contract、Pinia、localStorage、日志或本文档。
+
+本次没有创建或使用本机 OpenAI API Key，也没有对 OpenAI、DeepSeek 发起真实请求。外部模型列表的联调需要在桌面 Host 完成 Stronghold 注入后进行。
+
+## 4. 验证
+
+后端：
+
+```bash
+cd backend
+uv run pytest -q -p no:cacheprovider
+```
+
+前端：
+
+```bash
+cd frontend
+pnpm test
+pnpm build
+```
+
+自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。