2026-06-05 11:07:50 +08:00
|
|
|
|
# Portal Key Experience
|
|
|
|
|
|
|
2026-06-05 11:45:17 +08:00
|
|
|
|
日期：2026-06-05
|
|
|
|
|
|
状态：已审核通过
|
2026-06-05 11:07:50 +08:00
|
|
|
|
适用版本：vNext.2
|
|
|
|
|
|
|
|
|
|
|
|
## 目的
|
|
|
|
|
|
|
|
|
|
|
|
定义用户 portal 中 key 自助申请与首次调用体验的状态机、信息架构与边界，避免页面承诺超过宿主真实能力。
|
|
|
|
|
|
|
|
|
|
|
|
## 信息架构
|
|
|
|
|
|
|
|
|
|
|
|
用户页最少展示：
|
|
|
|
|
|
|
|
|
|
|
|
1. 我的 key
|
|
|
|
|
|
2. key 当前状态
|
|
|
|
|
|
3. 该 key 可用模型 / 逻辑分组
|
|
|
|
|
|
4. base URL
|
|
|
|
|
|
5. curl 示例
|
|
|
|
|
|
6. 首次调用指引
|
|
|
|
|
|
7. 最近一次失败原因（如有）
|
|
|
|
|
|
|
|
|
|
|
|
禁止向用户直接暴露：
|
|
|
|
|
|
|
|
|
|
|
|
- shadow_group_id
|
|
|
|
|
|
- route_id
|
|
|
|
|
|
- host_account_id
|
|
|
|
|
|
- 内部 capability inventory 明细
|
|
|
|
|
|
- 实验性/内部调试字段
|
|
|
|
|
|
|
|
|
|
|
|
## 用户状态机
|
|
|
|
|
|
|
|
|
|
|
|
### S0 未登录
|
|
|
|
|
|
|
|
|
|
|
|
- 只显示登录入口
|
|
|
|
|
|
- 不展示任何 key 信息
|
|
|
|
|
|
|
|
|
|
|
|
### S1 已登录但无 key
|
|
|
|
|
|
|
|
|
|
|
|
- 显示“创建 key”入口
|
|
|
|
|
|
- 展示说明：创建后明文只显示一次
|
|
|
|
|
|
- 展示可申请的逻辑模型组（用户可见范围内）
|
|
|
|
|
|
|
|
|
|
|
|
### S2 key 创建成功（首次显示明文）
|
|
|
|
|
|
|
|
|
|
|
|
- 返回一次明文 key
|
|
|
|
|
|
- 强提示：刷新/关闭后无法再次查看明文
|
|
|
|
|
|
- 同屏展示：
|
|
|
|
|
|
- base URL
|
|
|
|
|
|
- model 示例
|
|
|
|
|
|
- curl 示例
|
|
|
|
|
|
- 复制按钮
|
|
|
|
|
|
|
|
|
|
|
|
### S3 已有 key（明文不可再查看）
|
|
|
|
|
|
|
|
|
|
|
|
- 只显示 masked preview
|
|
|
|
|
|
- 显示状态、分组、模型、最近使用时间
|
|
|
|
|
|
- 支持重置/重新生成（如产品允许）
|
|
|
|
|
|
|
|
|
|
|
|
### S4 key paused
|
|
|
|
|
|
|
|
|
|
|
|
- 明确显示：已暂停
|
|
|
|
|
|
- 显示原因
|
|
|
|
|
|
- 若用户无恢复权限，只显示联系管理员
|
|
|
|
|
|
|
|
|
|
|
|
### S5 key quota exhausted / limited
|
|
|
|
|
|
|
|
|
|
|
|
- 明确显示：已超限/受限
|
|
|
|
|
|
- 给出用户下一步动作：等待恢复 / 联系管理员 / 升级配额
|
|
|
|
|
|
|
|
|
|
|
|
### S6 route degraded / model unavailable
|
|
|
|
|
|
|
|
|
|
|
|
- 明确显示：当前模型线路不可用
|
|
|
|
|
|
- 不伪装成“key 无效”
|
|
|
|
|
|
- 给出推荐动作：稍后重试 / 切换模型 / 联系管理员
|
|
|
|
|
|
|
|
|
|
|
|
### S7 示例调用失败
|
|
|
|
|
|
|
|
|
|
|
|
- 保留最近失败摘要
|
|
|
|
|
|
- 指明是：
|
|
|
|
|
|
- auth failed
|
|
|
|
|
|
- quota exhausted
|
|
|
|
|
|
- model unavailable
|
|
|
|
|
|
- route degraded
|
|
|
|
|
|
- upstream blocked
|
|
|
|
|
|
|
|
|
|
|
|
## 首次调用闭环
|
|
|
|
|
|
|
|
|
|
|
|
用户拿到 key 后，页面必须最短路径支持：
|
|
|
|
|
|
|
|
|
|
|
|
1. 复制 key
|
|
|
|
|
|
2. 复制 base URL
|
|
|
|
|
|
3. 复制 curl 示例
|
|
|
|
|
|
4. 选择一个已验证通过的 public model
|
|
|
|
|
|
5. 看到明确成功标准：`POST /v1/chat/completions = 200`
|
|
|
|
|
|
|
|
|
|
|
|
## 文案约束
|
|
|
|
|
|
|
|
|
|
|
|
必须避免：
|
|
|
|
|
|
|
|
|
|
|
|
- 承诺“所有模型都可用”
|
|
|
|
|
|
- 承诺“稳定负载均衡”
|
|
|
|
|
|
- 用 `/v1/models` 成功暗示真实可调
|
|
|
|
|
|
|
|
|
|
|
|
推荐文案：
|
|
|
|
|
|
|
|
|
|
|
|
- “以下模型基于当前已验证链路提供”
|
|
|
|
|
|
- “是否可进入默认链路以当前用户调用验证为准”
|
|
|
|
|
|
- “明文 key 仅首次显示一次”
|
|
|
|
|
|
|
|
|
|
|
|
## 页面块建议
|
|
|
|
|
|
|
|
|
|
|
|
1. 概览卡
|
|
|
|
|
|
2. key 列表卡
|
|
|
|
|
|
3. 创建 key / 重置 key 操作区
|
|
|
|
|
|
4. 使用示例区
|
|
|
|
|
|
5. 状态与故障说明区
|
|
|
|
|
|
6. 支持与说明区
|
|
|
|
|
|
|
|
|
|
|
|
## 验收要求
|
|
|
|
|
|
|
|
|
|
|
|
至少覆盖：
|
|
|
|
|
|
|
|
|
|
|
|
- 未登录
|
|
|
|
|
|
- 无 key
|
|
|
|
|
|
- 首次创建成功
|
|
|
|
|
|
- 已有 key 无明文
|
|
|
|
|
|
- paused
|
|
|
|
|
|
- quota exhausted
|
|
|
|
|
|
- model unavailable
|
|
|
|
|
|
- 示例调用成功
|
|
|
|
|
|
- 示例调用失败
|
|
|
|
|
|
|
|
|
|
|
|
## 与本轮范围关系
|
|
|
|
|
|
|
|
|
|
|
|
本文件属于 vNext.2 设计文档。
|
|
|
|
|
|
在当前 vNext.1 审核阶段，只作为后续设计真相源，不进入 UI 实现。
|
