Skip to content

models-provider-experience.md

Latest commit

 

History

History
67 lines (50 loc) · 3.41 KB

models-provider-experience.md

File metadata and controls

67 lines (50 loc) · 3.41 KB

Models / Providers 体验收敛交接

对应产品思考：insights/models-provider-experience.md

核心边界

Providers 页连接服务商，Models 页选择和补充模型。不要再把默认模型、模型刷新、模型启用隐藏、Runtime 兼容性和服务商连接状态混在同一张卡片里。

实现原则

  1. Provider record 分类先行

    • 用 record-aware helper 判断服务商类型，不要只看 provider_type。
    • 套餐型 / CodePlan：白名单或手动补 SKU。
    • OpenRouter：search-and-add，不全量物化。
    • 普通可发现服务商：只有新增或配置变更时尝试拉取。

  2. 模型拉取不常驻

    • 如果服务商不能可靠拉取模型，就不要显示“刷新模型”按钮。
    • 如果用户没有改 API Key / Base URL，不要主动重复拉取。
    • “刷新全部”属于高级操作，不是 Models 页主动作。

  3. 添加模型统一入口

    • UI 上只有一个“添加模型”入口。
    • 内部按 provider 类型切换：OpenRouter 搜索、套餐型补 SKU、普通服务商搜索或手动输入。
    • 手动添加行必须保持 manual_* / user_edited 保护，不被刷新覆盖。

  4. 状态必须有真实数据

    • “可用 / 不可用”只有在后端真实校验或 Runtime resolver 明确判断时才显示。
    • 不能用前端写死的绿色标签制造安全感。
    • 旧 SKU / 不在推荐目录提示只作用于权威 catalog provider，不要误伤普通自定义 provider。
    • 模型行默认不要展示来源型标签：api / manual_enabled / enable_source / catalog / upstream。这些属于详情信息，不属于主路径。

  5. 中文术语统一

    • 不直接暴露 Runtime。
    • 面向用户使用“执行引擎 / 服务商 / 模型 / 套餐模型 / 手动添加”。

  6. Auto 模式必须显示解析结果

    • Auto 状态下不能只显示“自动”。
    • 必须展示当前解析到的服务商和模型。
    • 如果解析结果不可用，再显示处理入口。

  7. 迁移工具不得伪装成日常功能

    • “按推荐整理”和 OpenRouter “整理早期导入目录”都是迁移/维护工具。
    • 默认不进入主路径。
    • 若保留，只能放高级维护区，并写清楚适用场景。

需要 ClaudeCode 先审计的事实

在继续改 UI 前，先跑一遍所有内置 preset 的 API Key / API 模型列表能力：

审计项 结论要写入
是否能用当前 API 拉到模型列表 能 / 不能 / 需要特殊参数
拉到的是套餐白名单还是大目录 白名单 / 大目录 / 不确定
是否适合自动刷新 是 / 否
如果不能自动刷新，主路径怎么添加模型 默认白名单 / 搜索添加 / 手动输入
文档来源 官方 URL + 最后核对日期

这个审计结果决定 UI 是否显示“刷新模型”，而不是反过来为了保留按钮去解释为什么刷新不了。

不要做

  • 不要为了兼容迁移期状态继续在主路径加 badge。
  • 不要把服务商页变成模型管理页。
  • 不要把 OpenRouter、套餐型服务商、普通 OpenAI-compatible 服务商塞进同一套“自动同步”逻辑。
  • 不要新增用户必须理解的技术术语。
  • 不要用折叠高级区来掩盖主路径仍然复杂的问题。真正要砍的是行级标签、伪日常操作和不透明 Auto 状态。