历史 · 共享内核与资源图

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

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

共享能力目录

能力	负责内容	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	Agent Definition、Revision、Deployment、能力声明与运行策略	Agent 域
MCP Gateway	Connector、Connection、Tool、MCPConnectionSecret 与受控调用	MCP 域
Model Catalog / Registry	逻辑模型、发布面、Execution Route、Gateway Pool 和费率门禁	模型域
Run / Task Center	长任务状态、Step、Attempt、审批、输出与恢复	执行域
Private Gateway Execution	Task/Attempt、供应路由、Provider 凭据，以及不可变 `ProviderUsageEvidence` / `ProviderCostEvidence` 与 source ref	私有网关域
Metering / Billing	规范 `MeterEvent` / `ProviderCostFact`、Evidence 归一化与更正，以及预占、结算、权益、账本和预算	Metering / 商业域
Search / Notification	权限感知索引、通知与跨产品任务摘要	派生读模型
Operations Read Model	Run、Gateway、Asset、Billing、Error 与 Incident 的关联摘要	可重建运维投影
Audit / Policy / Secret	授权决策、审计、数据外发策略与密钥托管	治理域

这些共享领域集中在 oceanway-core 的模块化运行时中，并可以使用同一个 PostgreSQL；每个模块只能直接写自己拥有的数据。独立 Surface 与产品仓不能直接修改钱包余额、读取 MCP Secret 或改写 AssetVersion。

Gateway 与 Metering 之间只通过证据引用衔接：Gateway 只追加 Provider 返回/账单来源形成的 ProviderUsageEvidence / ProviderCostEvidence；对 Core 的每个响应及 Gateway Observation 都必须返回 Usage/Cost 两个严格 Availability 联合，只有 available 分支携带对应 Evidence Ref，其余状态禁止 Ref。Metering 是规范 MeterEvent 与 ProviderCostFact 的唯一 Writer，负责绑定 Execution Attempt、规范化、幂等、追加更正和差异对账。Operational Observation 对 Usage/Cost 只能按同一 Availability 契约引用 Gateway Evidence；Telemetry 与产品页面只能读取获得授权的派生或规范投影。它们都不能自行生成事实或驱动客户结算。

开发者三入口与资源链

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

入口	身份与能力	明确不负责
`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
tenantKind
tenantId
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 重试必须分开。

Run Admission、Attempt 与 Route Binding

进入 reserved 后，RunAdmissionManifest@N 固定 Run 级不可变准入事实：

业务 Actor、执行 Principal、Tenant、Workspace、可选 Project 与付款方；
严格 Admission Authentication 联合：Developer Credential、Playground Execution Grant、Customer Authentication Assertion 或 Delegated Agent Grant；只有前两者携带 DeveloperApp、Environment、ServiceAccount，后两者分别携带 Product Surface 或 Agent Revision/Originating Surface；
Agent Revision、Canvas Revision、输入 Asset Version、MCP Tool Version 与 Connection Grant；MCPConnectionSecret 不进入 Manifest；
Logical Model、initial Model Deployment、Model Routing Policy Revision 与价格快照；
权限、数据外发策略、审批、输入输出契约、预算预占、correlationId、operationId 与创建时 Trace Context。

每次实际调用另建不可变 AttemptExecutionManifest@N，固定 executionAttemptId、实际 Model/Gateway Deployment、准入时的 Routing Policy Revision 和输出契约。Gateway 在 Provider Side Effect 前创建唯一 AttemptRouteBinding@N + GatewayRouteSnapshot@N 并返回 Binding Ref；Execution append-only 保存，不能回写 Run 或 Attempt Manifest。同一 Attempt 只能沿同一 Route Snapshot 做有证据的安全协议重试；任何需要改变 Deployment、Channel、Supply、Credential、Provider Model 或 Adapter 的故障切换都创建新 Attempt。

Run 开始后不能静默切换付款主体、扩大工具权限、追随资产最新版或追随最新路由策略。完整四层契约见调度、执行与模型网关池。

Public API 的执行 Principal 始终是 ServiceAccount：正式 API 的 Actor 同为该 ServiceAccount；Playground 的 Actor 是 Customer User，由短期 Grant 委托目标 ServiceAccount。交互式产品的 Customer Session 分支要求 Actor=Execution Principal，并只保存 Identity Authorization 的稳定 Assertion Ref；Delegated Agent 分支以授权发起者为 Actor、与 Agent Revision 绑定的 Agent Principal 为 Execution Principal，并冻结 Delegation Grant。分支外字段和伪造 Service Account 都拒绝。内部 Workload Principal 只记录在服务调用和 Gateway Invocation 审计中，不替换业务 Actor。

首批 Run/Wallet v2 Producer 只启用 Organization 的 Developer API 与 Playground 分支；Canvas、Studio、Drama、Commerce 与 Agent 虽复用同一 Run/Step/Attempt 领域模型，但只有完成各自 Assertion/Delegation、Billing 和端到端门禁后，才能启用对应 Authentication 分支。共享领域模型不等于所有产品已接入首批 Producer。

完成顺序

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

上游返回可验证结果；
媒体落盘并登记 AssetVersion；
RunOutput 与血缘关系提交；
产品领域显式绑定输出；
Metering 从 Execution/Output 与 Gateway Evidence 引用追加规范 MeterEvent，Billing 据此结算或释放；成本 Evidence 可用时 Metering 独立追加 ProviderCostFact，不得阻塞或改变客户结算；
发布完成事件和用户通知。

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

领域事件

跨模块同步采用稳定服务接口，异步传播采用 Transactional Outbox 与至少一次投递。消费者必须幂等。首期 Mandatory Delivery Set 必须与 Event Append 同事务冻结；Event/Observation Source 的不可变性由数据库约束和最小列权限强制执行。投影进度通过逐 Delivery/Receipt、未决集合和一致性快照边界证明，不使用可能受 PostgreSQL 提交乱序与回滚空洞影响的全局标量 Position。

事件信封：

eventId
eventType
schemaVersion
occurredAt
producer
actorPrincipalId
tenantKind
tenantId
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、provider_cost.recorded / corrected；
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 Execution Anchor（Text Invocation 或 Media Task）、Asset、Reservation、Error、Incident 与 Audit 的稳定 ID 关联为只读时间线。Outbox Dispatcher、Projector、投影存储与私有 Query API 由 oceanway-core Operations 模块唯一拥有；Admin 只通过 Workforce BFF 查询。投影只消费领域事件和私有网关发布的规范化 Observation，不读取其他领域或网关的私有数据库，也不能反向成为任务、资产或账本事实源。Gateway Observation 中的 Usage/Cost 必须使用两类必填 Availability 联合，且仅 available 分支携带对应 Evidence Ref/Schema Version/Digest Algorithm Version/Digest完整四元组，其他分支禁止全部 Evidence四元字段；它不能冒充 Metering Fact 或触发结算。

读模型必须展示自己的版本、投影进度、数据新鲜度、完整性，以及已接受 Observation 范围与健康窗口。Edge Observation 在 Intake 前是 best-effort，这些范围与窗口不能证明每次请求都已捕获；缺少关联时显示“未知/未观测”，请求级完整性标为 unknown | not_measurable。Core Authorization 是 Signed Workforce Grant 的唯一签发 Owner，特权或跨租户查询必须在返回数据前耐久写 Audit，失败时关闭查询。所有处置仍调用唯一拥有数据的领域命令；可靠投递与重建见运维事件与读模型，页面设计见管理员平台与运维控制面。

演进方式

oceanway-core 采用模块化运行时：

oceanway-core
├── 独立领域模块
├── 每模块明确 Repository
├── 稳定内部 Service Contract
├── Transactional Outbox
└── 禁止跨模块直接写表

容量或故障隔离可以推动 Core 内模块形成独立进程或部署单元，但 Identity、Asset、Execution、Billing、Agent、MCP 与 Model Control 不再逐域创建 Git 仓库。Text Gateway Pool 与 Media Gateway Pool 已是明确的同级仓库、部署和故障边界；Media Gateway 的 Task Registry、Provider Attempt、Poller/Reconciler 和可选 Callback 属于服务内部，不形成第三个 Gateway Registry 平台。任何部署演进都不应改变资源 ID、事件信封或产品契约。

历史 · 共享内核与资源图

On this page