模型目录分类体系

模型目录的目标不是完整展示上游同步结果，而是帮助用户回答三个问题：我需要什么能力、哪个 OceanWay Offering 适合、怎样安全地开始调用。

当文本模型和媒体模型持续增加时，目录不能退化成供应商 ID、版本号和价格的超长列表。Kie.ai 证明了公开价格、模型状态和试用入口能够促进转化；它的模型文档大量平铺型号，也提醒 OceanWay 必须建立稳定分类与自动生成规则。Kie.ai 模型市场说明

正式分类决策

公开发现采用以下层级：

Capability 能力
└── Task 任务
    └── Family 模型家族
        └── Variant 变体
            └── Model Offering 已发布调用契约
                └── Offering Revision 不可变修订

其中 Capability 和 Task 是发现维度，不是新的执行或计费实体。Model Offering 仍是公开 Surface、协议、价格和生命周期的稳定产品契约。

内部模型体系保持不变：

Provider Model Observation
→ Model Deployment
→ Logical Model
→ Model Offering

公开目录不得从 Provider Observation 或 Gateway Deployment 直接生成客户页面。

各层定义

Family 和 Variant 是客户理解层；实际执行仍由 Logical Model 和已冻结 Execution Manifest 选择私有 Model Deployment。

Surface 门禁先于分类

目录构建顺序固定为：

已审核 Model Offering Revision
→ surface 包含 api
→ publicDiscoverable = true
→ 有有效公开协议和 Public Rate
→ 生命周期允许公开发现
→ 映射 Capability / Task / Family / Variant
→ 进入 Developer Center 搜索索引

• web Offering 只供 Canvas、漫剧、电商等工作台使用，不因存在就进入开发者目录；
• internal Offering 永不进入公开目录、Console Playground 或 /v1/models；
• 同一 Logical Model 可以发布到多个 Surface，但每个 Offering 明确自己的协议、费率和可见性；
• codex-auto-review 等平台审核模型只属于 internal，任何名称搜索都不能发现；
• 新同步的上游模型默认不可见，必须通过能力、协议、价格、安全和可用性审核。

一级能力

首期保持少量稳定一级分类：

一级能力用于导航、SEO、首页入口和目录筛选。不能因某个新模型的营销术语立即增加一级分类；新增一级能力需要产品与信息架构审核。

文本模型的专门组织

大量文本模型最容易形成型号噪声，因此默认按照用户任务组织：

文本与对话
├── 通用
├── 推理
├── 编程
├── 长上下文
├── 低延迟 / 低成本
├── 工具调用与 Agent
└── 结构化输出

一个 Offering 可以进入多个 Task，但只有一个主要 Task。目录默认提供“推荐模型”与少量可解释比较项，其余结果通过筛选和搜索访问。

文本目录不得：

• 用供应商同步顺序作为默认排序；
• 把上下文长度、推理等级或量化方式全部塞进模型名称；
• 把内部审核、路由、提示词优化或自动评测模型显示给客户；
• 根据网页工作台是否使用某模型推断它也支持公共 API；
• 以“最强”“最快”“最便宜”等不可证明标签替代具体指标与适用条件。

Family 与 Variant

Family 页负责建立共同心智，Variant 负责表达真实差异。

Variant 只在以下差异会改变选择或调用时建立：

• 输入/输出模态；
• 同步、流式或异步协议；
• 上下文、分辨率、时长或质量档；
• 延迟、吞吐或区域；
• 参数 Schema；
• 生命周期或兼容性；
• 计费单位和价格。

纯内部渠道、Provider 账号、容量池、路由权重和成本差异不能创建公开 Variant。

目录导航与 URL

/models
  全部公开 API Offering，按 Capability 聚合

/models/{familySlug}
  Family 总览、推荐 Variant、比较和公共能力

/models/{familySlug}/{variantSlug}
  具体 Offering 详情、参数、价格、限制、代码和试用入口

URL 使用可读 Slug，内部解析到稳定 offeringId。更名可以改变展示名称但不改变 publicModelId；Slug 变更需要 Canonical 与重定向。Console Playground 的交接使用稳定 Offering ID，不依赖标题或 Slug 猜测。

筛选和排序可以编码到 Query 参数，登录前不写入客户配置。分享到他人时应能恢复公开筛选，不携带组织授权或合同价。

搜索与筛选

默认搜索范围

搜索匹配：

• Family、Variant 和稳定 publicModelId；
• Capability、Task 和公开标签；
• 输入输出模态；
• 公开协议与已审核别名。

不索引 Provider Credential、内部 Route、Gateway Alias、Channel、Supply、Deployment ID 或未发布模型。

筛选层级

移动端先显示当前筛选摘要和结果数，再通过 Drawer 修改条件；桌面端可使用侧栏或顶部 Facet。筛选零结果时说明冲突条件，并允许逐项清除。

排序与策展

默认排序由公开策展规则决定，不直接使用利润、上游权重或最近同步时间。

允许的排序：

• 推荐：基于明确场景、产品审核和可解释适配性；
• 最新：按公开发布时间，不按 Provider Observation 时间；
• 价格：只在同计费单位且规格可比较的结果内排序；
• 延迟或吞吐：只显示有公开测试口径的数据；
• 生命周期：优先 GA，Preview 明确标识，Deprecated 降低优先级。

个性化“当前组织可用”只存在于 Console，不反向改变公开目录或搜索索引。

模型卡

目录卡片必须在不进入详情页的情况下支持初步判断：

[Capability] [Lifecycle] [Availability]
Family / Variant
适用任务与一句摘要
Input → Output · 执行模式
公开价格 + 准确单位
[查看详情] [在 Playground 中试用]

必显字段

• Family、Variant 和稳定公共模型 ID；
• 主要 Capability 与 Task；
• 输入/输出模态；
• 同步、流式或异步；
• Preview、GA、Deprecated 等生命周期；
• 客户可理解的服务状态；
• 公开列表价、币种、单位和价格生效时间；
• 详情、文档与 Console Playground 入口。

禁止字段

• Provider Channel、Supply、账号、Region Credential；
• 内部路由权重、上游成本和毛利；
• 原始 Provider Task ID 或 Gateway URL；
• 未审核的模型能力和营销排名；
• 客户合同价、余额和专属容量；
• 内部错误率或未确认 Incident。

模型详情的信息层级

虽然详情页会在独立文档继续展开，但分类体系先固定以下结构：

1. 决策摘要：适用任务、输入输出、生命周期、服务状态和公开价格。
2. Variant 选择：速度、质量、上下文、规格、协议和价格的可比差异。
3. 试用与代码：进入 Console Playground、快速调用和 SDK 示例。
4. 参数契约：输入 Schema、输出、限制、错误和幂等要求。
5. 运行模式：文本同步/流式或媒体异步 Run、Webhook/查询。
6. 价格与计量：单位、规格、失败边界、生效时间和价格历史。
7. 数据与安全：保留、训练、区域、内容政策和企业控制。
8. 版本与迁移：更新日志、Deprecated 时间线、替代 Offering。

Family 页负责比较，Variant 页负责精确契约。不能为每一种输入方式复制整套互相漂移的文档。

Playground 交接

公开详情页的“试用”只发送稳定意图：

intent=playground
offeringId={stableOfferingId}
source=model-detail

Console 登录后执行以下步骤：

1. 恢复公开 Offering 提示；
2. 解析 Personal Space 或 Organization；
3. 选择或幂等创建 App、Environment 和受限 Service Account；
4. 重新校验授权、预算、区域和生命周期；
5. 由 Console BFF 申请短期 Playground Execution Grant；
6. 使用真实 API 契约创建 Request/Run，并生成等价代码。

浏览器不接收长期 Developer Key。公开可见不代表当前组织必然有权调用。

价格展示

每个 Offering 的价格最少包含：

币种
计费单位
输入/输出或规格维度
最低计费粒度
公开列表价
价格生效时间
失败、取消和结果不确定的处理说明

不同单位不能强行归一成一个无业务意义的“每次调用价格”。文本输入 Token、输出 Token、图片张数、分辨率、视频秒数、音频分钟和组合计量分别展示。

公开目录只读取 Public Rate Card。登录后合同价、赠送权益、订阅覆盖、预算和实际结算由 Console 与 Billing 权限感知投影提供。

可用状态与生命周期

客户可用状态

状态来自 OceanWay 客户状态投影，不等于某个 Provider Channel 的健康检查。详情可以链接已确认 Incident，但不能展示内部候选路由。

产品生命周期

可用状态描述现在能否服务，生命周期描述产品承诺阶段，两者不能合并成一个“Online”标签。

公共目录、Console 与 API 的一致性

这些表面使用同一模型事实，但按 Audience、Surface、权限和任务产生不同投影。

文档生成规则

模型文档采用 Schema 驱动：

• Family 和 Variant 的产品说明由审核内容管理；
• 参数、类型、必填、默认值和输出从 Offering Revision Schema 生成；
• 代码示例从公共协议模板和稳定 publicModelId 生成；
• 价格从 Public Rate Card 引用，不复制数值到多份 MDX；
• 生命周期和迁移信息来自发布流程；
• 文档构建失败不得继续发布一个参数或价格不一致的 Offering。

这一规则用于避免模型数量增长后形成超长手工目录和重复 Quickstart 页面，同时保留每个模型真实差异。

最小展示投影

前端目录至少需要以下只读投影，不直接读取网关或 Provider 数据：

offeringId
publicModelId
surface = api
capabilities[]
primaryTask
tasks[]
family
variant
inputModalities[]
outputModalities[]
executionModes[]
lifecycle
availability
publicRateSummary
effectiveAt
schemaRevision
docsRevision

availability 和 publicRateSummary 是有来源时间的投影；运行开始时仍由服务端固定实际 Offering Revision 与 Price Snapshot。

验收标准

1. 新同步模型在未审核和未发布到 api Surface 前，无法从 Center、Console Playground 或 /v1/models 发现。
2. web、api、internal 三种 Surface 不因共享目录而相互泄漏。
3. 用户可以从 Capability 或 Task 找到模型，也可以用稳定公共 ID 精确搜索。
4. 文本模型默认按通用、推理、编程、长上下文、低延迟等任务组织，不平铺全部型号。
5. 卡片同时显示准确价格单位、生命周期和客户可用状态，并且三者来自不同明确事实。
6. Family/Variant/Offering 更名不会改变已发布公共模型 ID 或历史 Run 的可解释性。
7. Center 的公开可见 Offering 进入 Console 后必须重新执行组织、权限、预算和环境校验。
8. 价格、参数、代码和生命周期在目录、详情、API Reference 与 Console 中可以追溯到同一 Revision。
9. 内部 Provider、Channel、Supply、Deployment 和成本信息不会出现在页面、接口或搜索索引。
10. 390px、430px 和桌面端均能完成搜索、筛选、比较和试用交接，无横向溢出或仅颜色状态。