OceanWay 开发者平台

OceanWay Developer 是一个逻辑产品与领域，不是第二套客户后台。它由三个明确分离的入口组成：

ai.oceanway.tech
  公开 Developer Center：发现、理解、评估

console.oceanway.tech/ai
  登录后 AI 专业空间：配置、调试、治理、观察

api.oceanway.tech/v1
  机器入口：鉴权、执行、查询、结果交付

三个入口由同一套 Organization、Workspace、Billing、Model Offering、Run、Asset 和 Audit 等核心能力支撑，但不复制这些事实。Console 的 Customer User 与 API 的 Service Account 是不同 Principal，但都解析到同一个 Personal Space 或 Organization 所有权及 Billing Account 上下文；公开 Center 本身不读取客户身份。Developer Access Domain 是 Developer App → Environment → Service Account → DeveloperCredential 四层资源的唯一 Command Owner。

正式决策

UUMI/new-api 和 oceanway-media-gateway 不进入客户登录、应用切换器、公开模型目录、购买流程或 Credential 体系。

产品旅程

典型路径：

1. 开发者在公开 Center 查看模型、协议、价格和服务状态。
2. “开始使用”跳转到 console.oceanway.tech/ai；未登录时先通过 Customer Identity 登录并安全返回。
3. Console 解析 Personal Space 或 Organization，为用户展示或创建 App/Environment/Service Account。
4. 用户在 Console 创建只显示一次的 Credential，供自己的服务端调用正式 API。
5. Playground 不读取或生成长期 Key；Console BFF 取得短期、受限的执行授权后服务端调用 API Edge。
6. API Edge 创建统一 Run，按 Offering Revision 分发到 Text 或 Media Gateway。
7. API 专业空间展示请求、Run、API 用量、日志和 Webhook；Console 顶层继续汇总全平台任务、资产和账务。

各入口的信息架构

公开 Developer Center

ai.oceanway.tech
├── 首页与快速开始
├── 模型目录
├── API 文档 / SDK
├── API 价格
├── 服务状态
└── 更新、弃用与迁移公告

Center 只读取公开发布物，不读取客户 Organization、App、Credential、Usage 或合同价。登录按钮本质是前往 Console 的可信链接；Center 本身不建立客户管理 Session，也不提供个性化控制面。

Console AI 专业空间

console.oceanway.tech/ai
├── 总览
├── Developer Apps
│   └── Environments
│       ├── Service Accounts
│       ├── Credentials
│       ├── Webhooks
│       └── Limits / Budgets
├── Playground
├── API Usage
├── API Runs / Request Logs
└── Developer Security / Audit

这是 Console 中的专业工作区，而不是独立客户后台。它复用当前 Organization、Workspace、Project、付款方、成员、策略和 Host-only Customer Session。完整钱包、购买、订阅、账单、发票和跨产品总览仍由 Console 顶层页面负责。

Public API

api.oceanway.tech/v1 当前只接受 DeveloperCredential，或 Console Playground BFF 服务端持有的短期 Playground Execution Grant。它不接受浏览器 Cookie 或 Customer Session，不返回 HTML 登录跳转。未来 OAuth 只能在独立 ADR 批准后作为 DeveloperCredential 的新类型进入，不能自然演变成第三类 Edge Principal。

Developer Access Domain

Developer Access Domain 唯一拥有以下命令和状态变更：

• 创建、修改、停用和删除 Developer App；
• 创建、隔离、停用 Environment；
• 创建、授权、停用 Service Account；
• 签发、轮换、到期和撤销 Credential；
• 维护四层资源之间的父子关系、状态传播和审计事件。

调用边界：

Developer Access Domain 可以先作为模块化单体中的独立模块实现，不要求立即拆微服务；“唯一 Command Owner”描述的是数据与行为所有权，不是部署数量。

四层资源模型

Organization / Personal Space
└── Developer App
    └── Environment
        └── Service Account
            └── Credential

Developer App 是 API 产品的业务容器；Environment 隔离开发、测试和生产策略；Service Account 是非交互式 Principal；Credential 只负责证明该 Principal 身份，不拥有权限或钱包。

个人开发者首次进入 Console AI 专业空间时，系统幂等创建 Personal Space 下的默认 App、默认 Environment 和受限 Service Account。底层仍使用完整四层模型，不能保留一套直接归属 User 的“个人自由 Key”。

Playground 安全边界

Playground 是 Console 中的 API 契约测试工具，不是正式 Credential 的浏览器客户端。

执行授权必须绑定 Customer User Actor、目标 Service Account、App、Environment、允许的 Offering/操作、请求边界、到期时间和审计身份。Developer Access Domain 只提供 Access Snapshot，Authorization/Policy Token Issuer 负责签发，Console BFF 只申请和持有。它不等同于 API Key，不可用于管理资源，也不能作为 Bearer 暴露给浏览器 JavaScript、URL、日志或本地存储。

模型目录与 Surface

大量 API 模型按“能力 → Family → Variant”组织。每个公开 Offering 至少说明稳定 ID、输入输出模态、协议与参数、流式/异步能力、生命周期、费率单位、限制、区域、数据政策和迁移建议。

Provider、Channel、Supply、Credential Version、候选权重和内部错误不进入公开目录。codex-auto-review 等 internal-only 模型不会出现在 Center、Console AI 模型选择或 /v1/models 中。

双私有网关

两池同级、互不级联。OceanWay Product/Execution Control 负责客户、Offering、Run、零售价、钱包和正式 Asset；网关只负责私有供应执行。Developer Center、Console、浏览器和客户程序都不能直接访问网关。

用量、日志和 Console 总览

• console.oceanway.tech/ai/usage：只展示 API 与 Playground Meter/Billing 事实；
• console.oceanway.tech/ai/logs：展示权限范围内的请求、Run、状态、延迟、标准错误和关联 ID；
• Console 顶层：汇总 Canvas、API、漫剧、电商等全平台 Run、Asset、钱包和账务；
• ai.oceanway.tech/pricing：只展示公开列表价；
• admin.oceanway.tech：展示 Workforce 授权下的内部 Gateway、Provider Cost 和运维诊断。

这些视图读取同一事实源，不各自计算余额、状态或账单。API 日志不得包含 Secret、完整内部 Prompt、Provider Payload 或跨租户信息。

当前实现基线

当前项目已经具备 Developer Host、首页、模型目录、个人 API Key、用量页面、web/api/internal Surface 和 /v1 代理。但模型、Key 和用量目前位于 Developer Portal，且依赖网页登录；用量混合 Web/API；Key 直接归 User 并可再次解密显示；/v1 在多个 Host 放行；浏览器 Session 仍可能得到内部路由映射。

这些能力是迁移输入，不是目标产品边界。

目标状态

• ai.oceanway.tech 是完全公开、无客户私有状态的 Developer Center；
• console.oceanway.tech/ai 是唯一登录后开发者专业空间；
• Developer Access Domain 是四层资源唯一 Command Owner；
• Playground 通过 Console BFF 使用短期受限执行授权，浏览器永不接触长期 Key；
• api.oceanway.tech/v1 是独立机器入口，不接受 Customer Session；
• Text/Media Gateway 保持私有、同级和供应事实自治。

待决策

• Developer Access Domain 是模块化单体模块还是后续独立服务；
• 首期 SDK 语言与发布节奏；
• OAuth 客户授权能力范围；
• Playground 首期协议与媒体能力；
• 客户 Webhook 事件清单、保留期和重放策略；
• Preview、GA、弃用窗口与企业 SLA；
• API 套餐、资源包和合同定价口径。

不可妥协的规则

1. Developer Center 不承载登录后管理页面，也不读取客户私有数据。
2. Console AI 专业空间不创建第二套 Identity、Billing、Run 或 Credential 存储。
3. 四层资源只能由 Developer Access Domain Command 修改。
4. Public API 不接受 Customer Session；Developer Key 不下沉到网关。
5. Playground 不向浏览器暴露或复用长期 Developer Credential。
6. 网页、API 与内部模型通过显式 Surface 隔离。
7. API 消费进入统一 Billing Account，Credential 与钱包不是同一对象。
8. Canvas 构建产物不承载 Developer Center、Console AI 空间或 Public API Edge。

延伸阅读

• 开发者中心与 Console AI 信息架构
• 应用、环境与服务身份
• 公共 API 运行链路
• 开发者平台迁移计划
• 统一客户控制台
• 调度与网关池