OceanWay 跨平台共享服务、Asset Graph、Canvas Runtime、Run 状态机和领域数据边界

共享内核与资源图

生态互通的关键不是让所有产品连接同一批表，而是建立一组稳定的共享能力。产品领域拥有自己的业务状态，通过资源注册、运行契约和领域事件协作。

共享能力目录

能力	负责内容	Source of Truth
Tenant Directory	Organization、Workspace、Project 与成员上下文	身份与租户域
Developer Access Domain	DeveloperApp、Environment、ServiceAccount、DeveloperCredential 与 Webhook Endpoint	开发者接入域
Resource Registry	稳定资源 ID、类型、所有权、Revision 与关系	资源注册域
Asset Service	Asset、AssetVersion、Rendition、版权与 Blob 引用	资产域
Canvas Runtime	CanvasDocument、Revision、Node、Edge、Binding 与执行快照	Canvas 域
Agent Registry / Runtime	Agent 定义、版本、部署、Run 与能力声明	Agent 域
MCP Gateway	Connector、Connection、Tool、MCPConnectionSecret 与受控调用	MCP 域
Model Catalog / Registry	逻辑模型、发布面、Execution Route、Gateway Pool 和费率门禁	模型域
Run / Task Center	长任务状态、Step、Attempt、审批、输出与恢复	执行域
Metering / Billing	用量事实、预占、结算、权益、账本与预算	商业域
Search / Notification	权限感知索引、通知与跨产品任务摘要	派生读模型
Operations Read Model	Run、Gateway、Asset、Billing、Error 与 Incident 的关联摘要	可重建运维投影
Audit / Policy / Secret	授权决策、审计、数据外发策略与密钥托管	治理域

首期可以继续使用模块化单体和同一个 PostgreSQL，但每个模块只能直接写自己拥有的数据。产品不能直接修改钱包余额、读取 MCP Secret 或改写 AssetVersion。

开发者三入口与资源链

开发者能力使用同一组领域事实，但三个入口承担不同职责：

入口	身份与能力	明确不负责
`ai.oceanway.tech`	无需登录的公开模型目录、文档、API 列表价和状态	App、密钥、用量、购买、账单或机器调用
`console.oceanway.tech/ai`	Customer Session 下的 Developer Control、API 用量与 Webhook 管理	成为 Developer Access 或账本的第二事实源
`api.oceanway.tech/v1`	DeveloperCredential 或 Playground Execution Grant 鉴权与唯一公共机器接口	Customer Session、HTML 门户与私有网关凭据

Developer Control 的用量仅指 API Surface；充值、购买、订阅、发票和跨产品消费总览由 Console 的统一 Commerce/Billing 能力拥有。/ai 可以引用账务摘要和提供受控跳转，但不能复制余额、订单或账本。

Developer Access Domain 统一拥有以下完整父子链，Console 只是其登录后控制面：

Organization / Personal Space
└── DeveloperApp
    └── Environment
        └── ServiceAccount
            └── DeveloperCredential

ServiceAccount 的直接父级只能是 Environment，DeveloperCredential 的直接父级只能是 ServiceAccount。Organization、Personal Space、Workspace、Project 和 Billing Account 通过 App 所有权或授权绑定解析，不能绕过层级直接挂 Key。

Secret 必须按信任边界分型：DeveloperCredential 只在 Public API Edge 校验；WebhookSigningSecretVersion 属于 Environment 的 Webhook Endpoint；MCPConnectionSecret 属于 MCP Connection；ProviderCredentialVersion 只存在于私有网关；Workload Credential 是内部 Workload Principal 使用的短期认证材料。它们不能互相复用或相互转换。

共享 Project 外壳

Project 定义为跨产品业务目标容器，保存：

标题、说明、状态和时间范围；
所属 Workspace；
业务上下文、标签和负责人；
预算、策略与默认资产集合；
关联的产品资源 ID。

它不保存完整剧本、SKU、Canvas 节点或 Developer App 配置。产品私有聚合通过 Binding 关联：

Project
├── DramaProject
├── CommerceCampaign
├── CanvasDocument[]
├── DeveloperApp[]
├── AssetCollection[]
└── AgentDeployment[]

这既允许一次 Campaign 横跨多个工作台，又避免同一个 projectId 在不同产品中拥有互相冲突的 JSON 语义。

Resource Envelope

所有可跨产品引用的对象使用统一外壳：

resourceId
resourceType
organizationId
workspaceId
projectId?
currentRevisionId
status
createdBy
createdAt
updatedAt
classification

领域 Payload 仍由对应服务保存。Resource Registry 只管理统一身份、所有权、版本指针、关系和索引，不能成为装载所有产品 JSON 的万能数据库。

资源身份规则

URL、文件名、标题、提示词和展示名称都不是资源身份。
正式执行固定不可变 Revision，不在运行中追随“最新版”。
编辑产生新 Revision，不能原地篡改已被 Run 或发布版本引用的内容。
跨 Workspace 引用必须经过授权；改变所有权需要复制或转让。
删除前执行引用影响分析，底层 Blob 只有在无任何有效引用时才可回收。

Asset Graph

Asset Graph 将素材、生成结果、业务对象和运行历史连接起来：

推荐关系类型：

derived_from：派生自某个源版本；
used_in：作为 Run 或 Canvas 输入；
generated_by：由某个 Run 生成；
bound_to：绑定到产品业务槽位；
forked_from：跨 Workspace 复制或分叉；
published_as：发布成公开或渠道对象；
replaced_by：显式替换，但保留历史。

Asset 至少包含类型、版本、Rendition、内容哈希、MIME、尺寸/时长、来源、版权/许可、数据分类和可公开状态。对象存储只保存 Blob；数据库保存稳定 storageKey 与引用，浏览器和外部上游使用短期签名 URL。

Canvas Engine 与 OceanWay Studio

Canvas 是生态的编排能力，不只是当前创作产品的一张页面：

Canvas Runtime / Engine：文档、Revision、通用节点、连接、Binding、执行快照与事件。
OceanWay Studio 无限画布工具：canvas.oceanway.tech/canvas 提供完整可视化编辑体验。
Embedded Canvas：漫剧、电商等产品中的受限局部编排视图。
Product Node Namespace：产品专属节点保留自己的领域语义，不污染通用节点。

跨产品“在 Canvas 中打开”默认创建对源资源固定版本的 Binding。Canvas 编辑产生派生版本；只有用户执行“写回镜头”“设为商品主图”等动作时，产品领域才更新自己的引用。

Canvas 共享时只共享文档和被授权资源，不自动共享 Agent 的内部定义、MCPConnectionSecret 或底层受限资产。

统一 Run 模型

Run 是所有 Agent、模型、Canvas 执行和 MCP 调用的统一运行外壳。

每个 Run 包含 Step 和 Attempt。重试创建新的 Attempt，不把第二次上游调用伪装成原调用；整 Run 重试与单 Step 重试必须分开。

Execution Manifest

进入 reserved 后固定不可变执行清单：

业务 Actor、执行 Principal、组织、Workspace、Project 与付款方；
API 调用对应的 DeveloperApp、Environment、ServiceAccount，以及严格二选一的 DeveloperCredential ID 或 Playground Execution Grant ID 和鉴权决策；
Agent Revision 与 Canvas Revision；
输入 Asset Version；
逻辑模型、真实 Model Deployment 与价格快照；
MCP Tool Version 与 Connection Grant；MCPConnectionSecret 不进入 Manifest；
权限、数据外发策略和审批结果；
输入输出契约、预算预占、correlationId、operationId 与创建时 Trace Context。

Run 开始后不能静默切换付款主体、扩大工具权限或追随资产最新版。Provider 故障切换必须符合已固定的逻辑模型策略，并记录实际 Deployment。

Public API 的执行 Principal 始终是 ServiceAccount：正式 API 的 Actor 同为该 ServiceAccount；Playground 的 Actor 是 Customer User，由短期 Grant 委托目标 ServiceAccount。内部 Workload Principal 只记录在服务调用和 Gateway Invocation 审计中，不替换业务 Actor。

完成顺序

一个生成步骤只有按以下顺序完成，产品才可显示成功：

上游返回可验证结果；
媒体落盘并登记 AssetVersion；
RunOutput 与血缘关系提交；
产品领域显式绑定输出；
用量结算或释放；
发布完成事件和用户通知。

对外发布、支付、调价等不可逆副作用需要独立 Step、幂等键、审批与补偿策略。

领域事件

跨模块同步采用稳定服务接口，异步传播采用 Transactional Outbox 与至少一次投递。消费者必须幂等。

事件信封：

eventId
eventType
schemaVersion
occurredAt
actorPrincipalId
organizationId
workspaceId
projectId?
aggregateId
aggregateRevision
correlationId
operationId?
causationId
traceId?

核心事件包括：

resource.created / revised / shared / deleted；
asset.derivative_created；
canvas.published；
agent.deployed / deprecated；
connection.authorized / revoked；
developer_app.created / disabled、developer_environment.disabled；
service_account.created / disabled、developer_credential.created / revoked；
run.created / approved / started / completed / failed / cancelled；
meter.recorded；
wallet.reserved / settled / released / refunded；
product.resource_bound / unbound；
case.approved / published / withdrawn。

事件中禁止包含 Secret、长效签名 URL、大段媒体数据或不必要的个人信息。

产品数据边界

产品或控制面	私有聚合	共享引用
Canvas	Document、Node、Edge、Viewport、Revision	Asset、Agent、Run、Project
漫剧	Episode、Scene、Shot、Review、Composition	Asset、Canvas、Agent、Run
电商	Product、SKU、Campaign、ChannelPublication	Asset、Agent、MCP、Run
公开开发者中心 `ai.oceanway.tech`	公开内容发布，不保存客户接入聚合	Model Offering、公开 Rate、服务状态
Developer Control `console.oceanway.tech/ai`	页面偏好与受控命令，不复制接入事实	Developer Access、Model、Run、Billing、Asset
Developer Access Domain	DeveloperApp、Environment、ServiceAccount、DeveloperCredential、Webhook Endpoint 与 WebhookSigningSecretVersion 元数据	Tenant、Model、Run、Billing、Asset
FDE	Engagement、Milestone、Deliverable、Acceptance	Project、Asset、Canvas、Agent、Audit

任何产品只能更新自己的聚合。console.oceanway.tech/ai 的写操作必须调用 Developer Access Domain 命令，ai.oceanway.tech 不提供客户资源写入口。跨产品操作由“命令 → 共享 Run/Binding → 产品确认写回”完成，禁止跨库直接改状态。

一致性与读模型

所有权、权限、账本、资源 Revision 和任务状态转换需要强一致。
DeveloperApp、Environment、ServiceAccount 与 DeveloperCredential 的父子关系、停用传播和唯一归属需要强一致。
全局搜索、任务摘要、用量报表和通知可以最终一致。
搜索结果必须在查询时再次执行权限过滤，不能把索引命中视为授权。
缓存只保存派生结果；Organization、Membership、预算和 Secret 状态不得依赖长时间缓存。
requestId 标识单次请求，traceId 标识一次分布式调用链，correlationId/operationId 与领域 ID 连接异步恢复、重试、资产和账务；长期任务不能依赖一个永不结束的 Trace。

运维读模型

管理员 Run Explorer 使用可重建的 Operations Read Model，将 Run、Gateway Task、Asset、Reservation、Error、Incident 与 Audit 的稳定 ID 关联为只读时间线。它只消费领域事件和私有网关发布的规范化 Observation，不读取其他领域或网关的私有数据库，也不能反向成为任务、资产或账本事实源。

读模型必须展示自己的事件水位和数据新鲜度。缺少关联时显示“未知/未观测”，不能按相同 Prompt、模型名或发生时间猜测。所有处置仍调用唯一拥有数据的领域命令；完整设计见管理员平台与运维控制面。

演进方式

初期采用模块化单体：

同一代码库
├── 独立领域模块
├── 每模块明确 Repository
├── 稳定内部 Service Contract
├── Transactional Outbox
└── 禁止跨模块直接写表

只有当团队边界、容量、故障隔离或发布节奏出现真实需求时，才继续拆分 Asset、Execution、Billing 等服务。Text Gateway Pool 与 Media Gateway Pool 是明确的同级部署和故障边界；Media Gateway 的 Task Registry、Provider Attempt、Poller/Reconciler 和可选 Callback 属于服务内部，不形成第三个 Gateway Registry 平台。任何物理拆分都不应改变资源 ID、事件信封或产品契约。

共享内核与资源图

On this page