历史档案文档OceanWay 架构
历史 · OceanWay 平台架构总览
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
OceanWay 的目标不是把多个 AI 页面放在同一个导航里，而是建立一套可持续扩展的 AI 生产与技术服务生态：用户以同一个身份进入不同工作台，在明确的组织、业务空间与项目上下文中复用资产、Canvas、Agent、MCP、模型能力和钱包，同时保持企业数据、权限、计费与审计边界清晰。
本文档集是 OceanWay 后续产品设计、技术拆分、商业定价和交付治理的共同基线。它描述目标态，不代表其中每一项都已经实现。
当前结论
| 类型 | 结论 |
|---|---|
| 已确认 | oceanway.tech 是公共宣传站；canvas.oceanway.tech 是基于 oceanway-vozeb 演进的 OceanWay Studio；ai.oceanway.tech 是公开开发者中心 |
| 已确认 | api.oceanway.tech/v1 是面向程序调用的统一 Public API 入口，不承载客户网页会话 |
| 已确认 | console.oceanway.tech 是唯一登录后客户控制平台；Developer 作为 /ai 专业空间承载 Apps、Playground、Credential、API 用量与 Webhook |
| 已确认 | admin.oceanway.tech 是 OceanWay 内部管理员与运维控制面；首期复用现有 /admin 代码基座 |
| 已确认 | FDE 采用“oceanway.tech 公开展示 + Console 私有交付”双界面，私有项目默认永不公开 |
| 已确认 | 用户包括个人用户、企业用户与企业成员；一个自然人使用一个全局身份 |
| 已确认 | 业务层级为“组织 → 业务空间（Workspace）→ 项目（Project）” |
| 已确认 | 各平台共享资产、钱包、Canvas、Agent、MCP 与运行链路 |
| 已确认 | 网页可用模型、API 可用模型与内部模型必须使用显式发布范围隔离 |
| 已确认 | UUMI/new-api 收敛为 Text Gateway Pool；oceanway-media-gateway 独立承载 Media Gateway Pool |
| 已确认 | 私有模型基础设施采用互不级联的 Text Gateway Pool 与 Media Gateway Pool 同级拓扑 |
| 已确认 | Execution 以不可逆关闭事实冻结完整 Attempt 集；Metering 生成唯一规范事实与结算快照；Billing 只在本地事务原子终局，迟到变化走追加式 Transition |
| 已确认 | Media Gateway 是直连媒体 Provider 的单一服务边界；任务、Attempt、Poll/Reconcile 与结果处理均为内部模块 |
| 已确认 | 客户用户、客户组、Developer Key、公开模型目录、用户售价和钱包只属于 OceanWay，不在私有网关重复建设 |
| 已确认 | 开发者资源统一采用 Developer App → Environment → Service Account → DeveloperCredential，个人开发者自动获得默认资源链 |
| 已确认 | Console 的 Developer 空间展示 API 用量与调用日志；Console 总览与 Billing 空间汇总跨产品钱包、账单、预算与 Run |
| 已确认 | oceanway-vozeb 移除开发者内容和 Public API 入口；公开内容迁往 AI，登录后控制面迁往 Console，机器调用迁往 API Host |
| 已确认 | 内部管理员使用独立 Workforce 身份与 Host-only Session；企业客户管理员不进入内部控制面 |
| 已执行 | Oceanway-AI 已建立 14 个 Git 仓库；ADR-032 后以 13 个活跃仓库交付，oceanway-developer-center 仅作迁移来源并在门禁完成后归档 |
| 当前实现基线 | 三站点已经具备独立 Surface 与共享父域 Session 的实现候选；统一积分账本已有 V2 候选 |
| 目标态 | 以 Console 统一客户控制层，形成共享内核、稳定资源标识、企业权限、预算与跨产品任务中心 |
| 待决策 | 漫剧/电商正式域名、FDE 正式全称、企业受管账号首期范围、商业套餐最终口径 |
战略定位
OceanWay 对外应呈现为三种能力的组合，而不是单一“模型商城”或单一“创作工具”：
- 模型与开发能力：统一模型目录、API、协议适配、路由、计量与企业接入。
- AI 生产工作台：OceanWay Studio（统一创作与
/canvas无限画布工具）、AI 漫剧、电商等面向具体业务结果的工作流。 - FDE 技术服务：把模型、Agent、MCP 与客户系统组合成可交付、可运营的生产方案。
FDE 在本文档中暂按 Forward Deployed Engineering 理解，正式品牌释义仍需确认。
总体架构
十一条架构原则
- 一个身份，多种上下文：同一个人可以拥有个人空间，也可以加入多个企业组织；切换组织就是切换数据、付款与权限边界。
- 组织是所有权和计费边界：企业项目中的资产归企业组织或其 Workspace，创建者只保留署名与审计关系。
- 共享内核不等于共享业务表：工作台复用平台服务和稳定资源 ID，但不能直接读取彼此的私有数据库结构。
- 引用优先于复制：跨平台通过资源引用、版本与派生关系协作；需要改变归属时再执行明确复制或转让。
- 写回必须显式：OceanWay Studio 或 Agent 只产生候选版本；用户选择“设为商品主图”“写回分镜”等动作后，由源产品领域校验并写入自己的业务对象，禁止静默覆盖。
- 钱包统一，预算分层：一个个人空间或企业组织只有一个计费账户和追加式账本；项目、成员、Agent、Service Account 与 Credential 获得的是预算约束，不是独立钱包。
- 模型按 Surface 发布：网页、API、内部运行时分别维护显式可见范围，任何网关模型同步后默认不公开；Surface、Offering 与用户费率只属于 OceanWay，私有网关的 Channel、Supply 或内部模型不能直接发布。
- 权限随运行收敛：Agent、API 与 MCP 的有效权限是发起人、服务身份、项目授权、安全策略和预算的交集。
- 全链路可追溯：一次请求使用
requestId，一次分布式调用使用traceId，跨轮询、回调、重试和补偿的长期流程使用correlationId/operationId与稳定领域 ID 还原。 - 管理面独立且受控：内部管理员与企业客户管理员使用不同身份和权限边界；诊断读取只经过授权读模型，处置只通过幂等领域命令。
- 部署边界独立 Git，领域模块留在 Core：13 个活跃产品、Surface、运行、网关与运维边界分别建仓；
ai公开面与 Console 私有面共用oceanway-console，Identity、Wallet、Asset、Run、Agent、MCP 与 Model Control 不再逐域拆仓，跨仓只依赖版本化契约与不可变制品。
平台边界
| 层级 | 负责 | 不负责 |
|---|---|---|
| 公共体验层 | 品牌认知、能力说明、案例、合作转化、公开定价与文档 | 承载复杂生产工作流或企业管理 |
| 账户控制层 | Console 中的登录、组织、成员、Workspace、Project、Developer 专业空间、钱包、账单、订阅、安全、应用入口和 FDE 私有交付 | 保存各创作工作台的完整业务对象或成为第二事实源 |
| 产品工作台 | OceanWay Studio、漫剧与电商等垂直生产体验 | 自建第二套身份、钱包、模型目录或审计体系 |
| 共享运行层 | Agent、模型、MCP、任务、资产、计量、审批与事件 | 直接决定垂直产品的业务状态 |
| 内部管理层 | 运行诊断、错误、告警、Incident、对账、变更与审计 | 成为第二业务事实源、直接改表或读取客户 Secret |
| 私有网关层 | Provider 协议、凭据版本、Task/Attempt、健康容量，以及不可变 Provider Usage/Cost Evidence 与 source ref | 规范 MeterEvent/ProviderCostFact、客户身份、Developer Key、公开目录、用户售价、钱包、产品 Run 和正式 Asset |
| 数据与集成层 | PostgreSQL、对象存储、事件、供应商和客户系统适配 | 向浏览器暴露密钥或跨域数据库访问 |
统一术语
| 术语 | 含义 |
|---|---|
| OceanWay 账户 | 自然人的全局登录身份 |
| 个人空间 | 注册后自动拥有的个人业务与计费边界 |
| 企业组织 | 企业的合同、所有权、成员、安全和计费主体 |
| Workspace / 业务空间 | 品牌、客户、部门或长期业务单元 |
| Project / 项目 | 一次明确业务目标，例如一部漫剧、一次 Campaign 或一组商品 |
| Surface | 某类用户可见的产品发布面，例如 Web、API 或 Internal |
| Asset | 可版本化、可授权、可追溯的内容或业务素材 |
| Canvas | 对资产、上下文和生成步骤进行可视化编排的工作空间 |
| Agent | 带有版本、能力声明和运行策略的任务执行定义 |
| MCP Connection | OceanWay 对外部账户或工具的受托连接 |
| Run | 一次可追踪、可计量、可恢复的执行实例 |
| Request / Trace | 单次请求标识与单次分布式调用链；不能代替长期业务身份 |
| Correlation / Operation | 跨异步边界的业务关联与一次副作用操作的稳定身份 |
| Incident | 由明确负责人协调、处置并复盘的一次平台或客户影响事件 |
| Reconciliation Case | 当前仅指 `late_settlement_dimension |
| Billing Account | 个人空间或企业组织唯一的计费账户 |
| Entitlement | 订阅或活动授予的定向使用权，例如图片张数或视频秒数 |
| Developer App | 开发者集成的产品与权限容器 |
| Environment | App 下开发、测试或生产等隔离边界 |
| Service Account | 代表应用工作负载调用 OceanWay 的非自然人身份 |
| Developer Credential | 绑定 Service Account、只在 Public API Edge 终止的可轮换认证凭证，API Key 是其一种 |
当前实施边界
当前已验收的是固定 Contracts 0.2.0 下的受控 API Admission、Run 与 credits Reservation 原子基线。Outbox Dispatcher、Operations Read Model 与 Admin Operations 的设计已经冻结，但配对的 run.created@2.0 + wallet.reserved@2.0、core-operations-worker、Observation Intake、私有 Query 和 Admin Explorer 仍待实现；首个 v2 Producer 仅覆盖 Organization，既有两个 v1 保持原 Schema 不变。Gateway 执行、Output、Metering 与 Settlement 也尚未接入。PUBLIC_ADMISSION_MODE 继续保持 disabled，不能把文档完成解释为公共 API 已上线。
具体执行已经拆入多仓实施总控：架构页维护目标和不变量，实施页维护仓库工作包与跨仓门禁，进度页只记录已经通过证据的状态。
文档导航
- 站点与产品拓扑：品牌官网、账户控制层、各产品入口与域名边界。
- Polyrepo 仓库拓扑与迁移治理：仓库边界、依赖方向、本地目录、历史保留、切换与回滚规则。
- 平台与产品：逐个平台说明用户、业务结果、独有对象、共享能力和产品边界。
- 身份与多租户：个人、企业成员、受管账号及组织层级。
- 共享内核：资源目录、Asset Graph、Canvas、Run Center 与领域边界。
- API、数据与基础设施：接口分层、数据所有权、事件、队列、可观测与灾备。
- 运维事件与读模型：Outbox 可靠投递、版本化投影、低敏 Observation、内部查询与实施门禁。
- 管理员平台与运维控制面：内部后台、全链路诊断、错误、告警、Incident、对账与安全运维。
- 模型、Agent 与 MCP：模型发布、API 目录、Agent 运行与外部连接。
- 调度、执行与模型网关池：统一 Run/Attempt、Text/Media Pool 边界、重试、计费与迁移。
- 钱包与商业系统：统一账本、订阅、预算、商品与 FDE 结算。
- ADR-031：执行、计量与账务终局协议：Attempt 关闭、三组验证、Billing 本地事务与迟到结算边界。
- 权限与治理：角色、最小权限、Secret、审批和审计。
- 跨产品链路：漫剧、电商、Canvas、API 与 FDE 如何真正互通。
- 交付路线图：阶段、依赖、验收标准和待决策清单。
如何使用这套文档
任何新平台或新能力进入 OceanWay 前，都应回答以下问题：
- 它属于公共体验、账户控制、产品工作台还是共享内核？
- 它的资源归哪个 Organization、Workspace 与 Project？
- 它复用哪个稳定资源 ID，而不是复制哪张业务表？
- 它由谁付款、受哪个预算限制、如何计量和退款？
- 它需要哪些模型 Surface、Agent Capability 与 MCP Tool Grant？
- 它产生的外部副作用是否需要人工审批？
- 它如何被 Request、Trace、Correlation/Operation、稳定领域 ID、审计事件和账本分录完整还原？
无法清楚回答这些问题的能力，不应直接接入生产生态。