模型提供商与模型发现开发说明

1. 本次目标

本次完善设置页的模型提供商配置，不改变 Agent、Chat 和 Skill 对统一 Model Core 接口的依赖：

提供 OpenAI、DeepSeek 和 Ollama 配置预设；
保存 Provider 后自动获取该账号或服务当前可用的模型列表；
支持手动刷新模型列表和选择默认模型；
保留自定义 OpenAI-Compatible 服务入口；
不在 Vue、FastAPI 配置或仓库文件中保存、回显 API Key 明文。

2. 接口与实现

2.1 Provider 预设

新增接口：

GET /api/providers/presets

预设由后端 ProviderFactory 提供，前端只消费名称、协议类型、Base URL 和是否需要凭据等配置元数据，不直接实现厂商协议。

当前预设：

提供商	Provider Type	Base URL	默认 Credential ID
OpenAI	`openai_chat`	`https://api.openai.com/v1`	`openai`
DeepSeek	`openai_compatible`	`https://api.deepseek.com`	`deepseek`
Ollama	`ollama`	`http://127.0.0.1:11434`	无

OpenAI 和 DeepSeek 都通过项目已有的 OpenAICompatibleProvider 访问。模型发现分别请求 Base URL 下的 /models，不引入厂商 SDK。

2.2 自动获取模型

模型列表继续使用既有接口：

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、日志或本文档。

当前尚未实现 Tauri Host 的开发环境中，openai 和 deepseek Credential ID 分别兼容标准的 OPENAI_API_KEY 和 DEEPSEEK_API_KEY 进程环境变量。Host 注入的 AINOTE_CREDENTIAL_OPENAI、AINOTE_CREDENTIAL_DEEPSEEK 优先级更高。环境变量必须在启动 AI Core 前设置；Provider 明确指定了 Credential ID 但进程内无法解析时，Adapter 会在网络请求前返回 PROVIDER_CREDENTIAL_MISSING，避免把本地配置缺失误报为厂商 401。

本次没有创建或使用本机 OpenAI API Key，也没有对 OpenAI、DeepSeek 发起真实请求。外部模型列表的联调需要在桌面 Host 完成 Stronghold 注入后进行。

4. 验证

后端：

cd backend
uv run pytest -q -p no:cacheprovider

前端：

cd frontend
pnpm test
pnpm build

自动化验证覆盖 Provider 预设、OpenAI-Compatible /models 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。

3.8 KiB Raw Blame History Unescape Escape