docs: define invite-only client integration flow
This commit is contained in:
1 parent
a33d115776
commit
ae950e0b33
3 files changed
+96
-23
No files matched your search
@@ -46,7 +46,8 @@
|
||||
- 对 3D 生成等任务型模型,用户可以提交任务、查询进度、获取结果文件并处理失败或取消。
|
||||
- 平台根据实际用量扣减共享额度。
|
||||
- 用户可以查看调用量、费用和余额变化。
|
||||
- 具体支付方式未确定前,第一版可以先通过管理员发放额度或试用额度完成使用闭环。
|
||||
- 第一版通过邀请码控制准入,由管理员发放额度完成使用闭环。
|
||||
- 充值入口在页面中预留位置,具体规则和支付能力确认后再开放。
|
||||
|
||||
### 核心价值
|
||||
|
||||
@@ -70,6 +71,33 @@
|
||||
- 用户付费方式、免费试用、套餐、计价单位、扣费和退款规则暂未确定。
|
||||
- 平台负责模型调用、用量统计、余额扣减和基础服务支持;具体账务规则进入待决策清单。
|
||||
|
||||
### 准入、注册与额度规则(已确认)
|
||||
|
||||
| 事项 | 第一版规则 | 后续预留 |
|
||||
|---|---|---|
|
||||
| 平台准入 | 邀请码注册,未持有有效邀请码不能创建账户 | 可配置切换为公开注册、申请审核或混合模式 |
|
||||
| 账户注册 | 邀请码作为准入条件,注册时填写基础账号信息 | 预留手机号、邮箱、验证码、第三方登录和账号绑定能力 |
|
||||
| 邀请码管理 | 管理员创建、启用、停用并查看使用记录 | 预留有效期、使用次数、渠道、邀请人和活动规则 |
|
||||
| 初始额度 | 管理员向用户或内部项目发放额度 | 后续接入试用额度、充值、套餐、优惠券和自动续费 |
|
||||
| 额度记录 | 每次管理员发放必须记录额度、原因、操作人、时间和可选有效期 | 后续与支付订单、退款、发票和对账关联 |
|
||||
| 充值入口 | 控制台保留按钮和页面位置,第一版显示“暂未开放”或申请入口 | 商业规则确定后启用真实支付和订单流程 |
|
||||
|
||||
邀请机制是准入策略,不与具体登录凭证强绑定。账户和认证设计不能假设用户永远只能通过邀请码注册。
|
||||
|
||||
### 第三方客户端接入目标(已确认)
|
||||
|
||||
首批用户不仅要能在平台页面调用模型,还要能把模亦灵枢作为模型提供商配置到第三方客户端和开发工具中。
|
||||
|
||||
| 客户端类型 | 第一版目标 | 关键兼容项 |
|
||||
|---|---|---|
|
||||
| Cherry Studio | 作为明确验收客户端完成真实模型调用 | Base URL、API Key、模型列表/模型名、Chat Completions、SSE 流式响应和标准错误 |
|
||||
| Codex | 作为明确目标客户端完成自定义模型提供商联调 | 自定义 provider、Base URL、环境变量 API Key、Responses API、流式事件和工具调用 |
|
||||
| 通用 OpenAI SDK/客户端 | 提供可复制的配置和示例 | Bearer 鉴权、版本化 API、模型标识、Chat Completions/Responses 和错误语义 |
|
||||
|
||||
根据 [OpenAI Codex 配置参考](https://developers.openai.com/codex/config-reference),Codex 支持自定义 `model_providers`、`base_url` 和从环境变量读取 API Key;自定义提供商当前使用 `responses` 协议。因此,模亦灵枢若要成为 Codex 的模型提供商,第一版需要把 Responses API 兼容列为实际联调范围,而不能只实现 Chat Completions。
|
||||
|
||||
兼容层不强制所有模型使用对话协议:文本/代码模型优先提供 OpenAI 兼容接口,3D、视频、音频等模型继续使用类型化任务接口,并在模型详情中明确支持的协议。
|
||||
|
||||
### 并发、排队与任务规则
|
||||
|
||||
并发和排队是第一阶段的核心产品规则,不等到系统上线后再临时决定。第一阶段先定义用户可感知的行为和限制,具体队列、调度器、限流器和资源池在系统设计阶段确定。
|
||||
@@ -193,6 +221,9 @@
|
||||
| UR-008 | 运营人员希望管理供给、价格和风险 | 供应商、模型、定价、用户和风控后台 | P0 | 配置变更可审计并按权限生效 |
|
||||
| UR-009 | 用户希望在高峰期知道请求是排队、执行还是失败 | 并发限制、排队、任务状态、超时和容量提示 | P0 | 同步、流式和异步请求在容量不足时有明确且可预期的结果 |
|
||||
| UR-010 | 运营人员希望控制不同模型和供应商的资源 | 模型/供应商并发、速率、队列和资源配额 | P1 | 可按模型和供应商查看并调整容量策略 |
|
||||
| UR-011 | 内测用户需要通过受控方式进入平台 | 邀请码注册、邀请记录和账号状态 | P0 | 只有有效邀请码可以完成注册,管理员可追踪使用情况 |
|
||||
| UR-012 | 用户需要在没有支付系统时获得可用额度 | 管理员额度发放、额度流水和控制台额度展示 | P0 | 管理员发放后用户可调用,所有变更均有可追踪记录 |
|
||||
| UR-013 | 用户希望在常用客户端中直接使用平台 Key | 客户端兼容 API、接入指南和联调测试 | P0 | Cherry Studio 与 Codex 使用模亦灵枢 Base URL、Key 和模型完成目标调用 |
|
||||
|
||||
### 产品演进需求
|
||||
|
||||
@@ -213,19 +244,19 @@
|
||||
```text
|
||||
访问首页
|
||||
↓
|
||||
注册/登录
|
||||
输入邀请码并注册/登录
|
||||
↓
|
||||
查看模型目录和价格
|
||||
↓
|
||||
创建 API Key
|
||||
↓
|
||||
获得试用额度或完成充值
|
||||
管理员发放额度
|
||||
↓
|
||||
复制调用示例
|
||||
复制平台 Base URL、API Key、模型名和客户端配置
|
||||
↓
|
||||
完成第一次模型调用
|
||||
在 Cherry Studio、Codex 或代码中完成第一次模型调用
|
||||
↓
|
||||
查看用量与费用
|
||||
查看用量、额度和调用结果
|
||||
```
|
||||
|
||||
### 开发者日常调用流程
|
||||
@@ -246,6 +277,22 @@
|
||||
记录用量并完成额度结算
|
||||
```
|
||||
|
||||
### 第三方客户端接入流程
|
||||
|
||||
```text
|
||||
登录并获得邀请码额度
|
||||
↓
|
||||
创建或查看 API Key
|
||||
↓
|
||||
复制 Base URL、API Key 和模型名
|
||||
↓
|
||||
在客户端选择对应协议并保存配置
|
||||
↓
|
||||
发送测试请求
|
||||
↓
|
||||
查看响应、错误、延迟和用量记录
|
||||
```
|
||||
|
||||
### 3D 及其他异步模型调用流程
|
||||
|
||||
```text
|
||||
@@ -301,17 +348,18 @@
|
||||
- 计费与额度说明:规则未确定时保留入口并展示试用/内测说明,确定后再展示真实套餐和价格。
|
||||
- 文档中心:提供快速开始、API 参考和示例代码。
|
||||
- 服务状态:展示供应商和平台服务状态。
|
||||
- 登录/注册:进入用户控制台。
|
||||
- 登录/注册:邀请码校验后进入用户控制台;公开注册入口先不开放。
|
||||
|
||||
### 用户控制台
|
||||
|
||||
- 总览:额度、今日用量、请求/任务概况、快速开始和服务状态。
|
||||
- API Key:创建、查看、禁用和轮换 Key。
|
||||
- 客户端接入:展示 Base URL、API Key、模型名、协议选择和 Cherry Studio/Codex/SDK 配置说明。
|
||||
- 模型广场:登录后直接试用模型、查看调用示例或创建 Key。
|
||||
- Playground:在线测试模型,完成从体验到代码调用的过渡。
|
||||
- 调用日志与用量:按时间、模型和 Key 查看请求、资源消耗和错误。
|
||||
- 任务与结果:查看异步任务状态、失败原因、结果文件和下载/再次调用入口。
|
||||
- 额度与账务:额度余额、发放/充值记录、消费流水;真实支付和退款待规则确定后启用。
|
||||
- 额度与账务:额度余额、管理员发放记录、消费流水;充值按钮保留但第一版不启用真实支付。
|
||||
- 账户与安全:基础资料、登录方式和安全设置。
|
||||
- 文档:查看接入代码和常见问题。
|
||||
|
||||
@@ -340,9 +388,9 @@
|
||||
- 支持的模型类型和供应商入口。
|
||||
- 模型目录入口。
|
||||
- 快速开始入口。
|
||||
- 登录、注册和文档入口。
|
||||
- 邀请码申请/输入、登录、注册和文档入口。
|
||||
|
||||
**主要操作**:查看模型、注册、阅读文档。
|
||||
**主要操作**:查看模型、申请邀请码、输入邀请码注册、阅读文档。
|
||||
|
||||
### P02:模型广场与模型详情
|
||||
|
||||
@@ -368,13 +416,13 @@
|
||||
**页面内容**:
|
||||
|
||||
- 当前余额。
|
||||
- 今日/本月消费。
|
||||
- 今日/本月用量和消费(价格规则未开放时展示用量和额度变化)。
|
||||
- 请求次数和 Token 用量。
|
||||
- 最近调用记录。
|
||||
- 常用模型。
|
||||
- 服务状态和异常提醒。
|
||||
|
||||
**主要操作**:创建 Key、充值、查看用量、进入 Playground。
|
||||
**主要操作**:创建 Key、查看管理员发放额度、查看用量、进入 Playground、查看充值占位入口。
|
||||
|
||||
### P04:API Key 管理
|
||||
|
||||
@@ -385,9 +433,10 @@
|
||||
- Key 名称和所属项目。
|
||||
- 创建时间、最后使用时间和状态。
|
||||
- 调用权限、额度、速率、并发和队列限制。
|
||||
- 客户端配置:Base URL、模型名、协议和代码示例。
|
||||
- 创建、禁用和轮换操作。
|
||||
|
||||
**主要操作**:创建 Key、复制一次性密钥、禁用泄漏密钥。
|
||||
**主要操作**:创建 Key、复制一次性密钥、复制客户端配置、禁用泄漏密钥。
|
||||
|
||||
### P05:用量与账单
|
||||
|
||||
@@ -397,10 +446,10 @@
|
||||
|
||||
- 按日期、模型和项目筛选。
|
||||
- 请求次数、任务次数、输入/输出用量、处理时长、文件量和金额。
|
||||
- 成功、失败、限流和退款记录。
|
||||
- 余额流水和充值记录。
|
||||
- 成功、失败、限流和任务状态记录。
|
||||
- 管理员发放额度流水和充值占位记录。
|
||||
|
||||
**主要操作**:查看明细、导出账单、充值和申请退款。
|
||||
**主要操作**:查看明细、导出用量、申请管理员发放额度、查看充值占位入口。
|
||||
|
||||
### P06:Playground
|
||||
|
||||
@@ -450,14 +499,17 @@
|
||||
### P0:必须具备
|
||||
|
||||
- 用户注册、登录和基础账户。
|
||||
- 邀请码创建、校验、停用和使用记录。
|
||||
- 模型目录和模型详情。
|
||||
- API Key 创建和禁用。
|
||||
- Base URL、模型名和 API Key 的客户端接入说明。
|
||||
- 统一模型调用入口。
|
||||
- 面向 Chat Completions 和 Responses 的目标兼容接口,并完成 Cherry Studio 与 Codex 联调验证。
|
||||
- 支持同步、流式和异步任务三种调用模式。
|
||||
- 基础速率限制、并发限制、队列状态和超时处理。
|
||||
- 首批模型清单至少覆盖文本/多模态能力,并预留或接入 AI 生成 3D 模型能力。
|
||||
- 至少一个首批模型供应商的真实调用(供应商和模型清单待填写)。
|
||||
- 内部/平台额度账户和基础额度记账(具体扣费、试用和退款规则待定)。
|
||||
- 管理员额度发放、额度流水和基础额度记账(具体扣费、试用和退款规则待定)。
|
||||
- 支持 Token、请求、任务、文件或其他资源的基础用量和余额记录。
|
||||
- 用户调用文档和示例代码。
|
||||
- 运营后台的用户、模型和供应商管理。
|
||||
@@ -469,6 +521,7 @@
|
||||
- 模型收藏、对比和简单体验记录。
|
||||
- 3D 结果的增强预览、资产管理和更复杂的异步编排。
|
||||
- 充值、退款和套餐。
|
||||
- 手机号/邮箱公开注册和验证码流程。
|
||||
- 项目级 Key 和额度。
|
||||
- 更完整的账单和对账。
|
||||
- 调用状态、错误和服务状态页。
|
||||
@@ -497,6 +550,8 @@
|
||||
- 完整知识库和企业数据平台。
|
||||
- 多区域多活。
|
||||
- 面向所有行业的复杂企业解决方案。
|
||||
- 公开手机号/邮箱注册的完整运营闭环;第一版采用邀请码准入,但数据模型和页面位置预留公开注册。
|
||||
- 真实支付、自动充值、套餐和退款的完整闭环;第一版只保留入口和管理员额度发放。
|
||||
- 企业认证的完整业务闭环;第一版只预留用户类型、主体信息、认证状态和权限扩展字段。
|
||||
|
||||
### 后续 MaaS 的预留原则
|
||||
@@ -514,7 +569,9 @@
|
||||
|
||||
- 能清楚说明第一阶段服务的用户和核心价值。
|
||||
- 内部业务首次接入流程可以从配置凭证走到第一次调用。
|
||||
- 外部开发者首次使用流程可以从注册走到第一次调用。
|
||||
- 外部开发者首次使用流程可以从邀请码注册走到第一次调用。
|
||||
- 管理员可以发放额度,用户可以看到额度流水并使用额度完成调用。
|
||||
- 用户可以复制 Base URL、API Key 和模型名,在 Cherry Studio 和目标 Codex 配置中完成联调验收。
|
||||
- 模型目录、API Key、用量和账务记录之间的关系清楚,具体价格规则可暂时留空。
|
||||
- 同步、流式和异步任务型模型的核心流程可以分别说明。
|
||||
- 并发限制、排队、超时、取消、重试和容量不足时的行为可以说明。
|
||||
@@ -545,23 +602,34 @@
|
||||
| 待填写项 | 需要确认的内容 | 当前状态 |
|
||||
|---|---|---|
|
||||
| 额度来源 | 平台共享额度、内部额度、用户自有额度或混合模式 | 共享额度方向,细节待定 |
|
||||
| 第一版发放方式 | 管理员发放给用户或内部项目,记录原因和操作人 | 已确认 |
|
||||
| 免费试用 | 是否提供、对象、额度、有效期和防滥用规则 | 待填写 |
|
||||
| 计价单位 | Token、请求、图片张数、秒数、任务次数、文件量、GPU 时间等 | 待填写 |
|
||||
| 售价规则 | 成本价、销售价、倍率、套餐、最低消费和并发权益 | 待填写 |
|
||||
| 扣费时点 | 请求前预扣、成功后结算、异步任务分阶段扣费 | 待填写 |
|
||||
| 失败与退款 | 超时、取消、失败、上游故障和部分成功的处理 | 待填写 |
|
||||
| 支付与对账 | 支付渠道、退款、发票、账单周期和财务对账 | 待填写 |
|
||||
| 支付与对账 | 支付渠道、退款、发票、账单周期和财务对账 | 第一版暂不启用,保留入口 |
|
||||
|
||||
### C. 用户、认证与权限
|
||||
|
||||
| 待填写项 | 需要确认的内容 | 当前状态 |
|
||||
|---|---|---|
|
||||
| 内部接入 | 内部项目如何创建、分配额度和管理 API Key | 待填写 |
|
||||
| 外部注册 | 邮箱、手机号、邀请码或其他方式 | 待填写 |
|
||||
| 外部注册 | 邮箱、手机号、邀请码或其他方式 | 第一版必须使用邀请码;手机号/邮箱公开注册预留 |
|
||||
| 邀请码 | 生成、有效期、使用次数、停用和使用记录 | 第一版必须具备基础管理 |
|
||||
| 企业认证 | 是否第一版启用,认证材料、审核人和认证后权限 | 可后置;数据模型预留扩展 |
|
||||
| 项目与 Key | 是否支持项目级 Key、权限、预算、并发和模型白名单 | 待填写,建议预留 |
|
||||
| 管理员权限 | 用户、模型、供应商、账务、风控、审计的角色边界 | 待填写 |
|
||||
|
||||
### C.1 第三方客户端接入
|
||||
|
||||
| 待填写项 | 需要确认的内容 | 当前状态 |
|
||||
|---|---|---|
|
||||
| Cherry Studio | 支持的协议、Base URL 格式、模型名、流式和错误展示 | 第一版明确验收 |
|
||||
| Codex | `model_providers`、Base URL、环境变量 Key、Responses API、流式事件和工具调用 | 第一版目标,按目标版本实际联调 |
|
||||
| 通用 SDK | OpenAI 兼容 Chat Completions、Responses、模型列表、鉴权和错误码 | 第一版明确提供 |
|
||||
| 配置文档 | 各客户端的填写项、示例、常见错误和安全提示 | 第一版必须提供 |
|
||||
|
||||
### D. 地区、数据与合规评估
|
||||
|
||||
| 评估项 | 需要明确的问题 | 当前状态 |
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
- 把需求拆成 P0、P1、P2 优先级。
|
||||
- 明确功能需求和非功能需求。
|
||||
- 明确首版的并发、延迟、排队、超时、可用性和任务完成时间等关键质量目标;容量数字可以先记录为假设。
|
||||
- 明确首版准入方式、额度发放方式和目标第三方客户端兼容范围。
|
||||
- 建立“用户需求—产品功能—验收标准—测试用例”的追踪关系。
|
||||
- 评审正常流程、异常流程、业务闭环和跨系统影响。
|
||||
- 编写 MVP 范围与验收标准。
|
||||
@@ -107,6 +108,7 @@
|
||||
- 功能清单和优先级。
|
||||
- 业务规则说明。
|
||||
- 非功能需求和容量假设。
|
||||
- 第三方客户端兼容矩阵和接入验收标准。
|
||||
- MVP 验收标准。
|
||||
- 需求评审记录。
|
||||
|
||||
|
||||
Reference in new issue
Block a user