OceanWay Polyrepo 仓库拓扑与迁移治理

Oceanway-AI 已按“每个系统部分独立 Git”的原则建立 14 个仓库。仓库与产品 Surface、公共 API、共享运行时、私有网关、文档和基础设施边界对齐，使各部分可以独立授权、构建、发布、回滚和归档。

这不是“一领域一仓”。Identity、Tenant、Wallet、Billing、Asset、Run、Agent、MCP 与 Model Control 仍是 oceanway-core 内的模块；FDE 分别由公共站和 Console 承载，不创建独立仓库；Media Gateway 的 Registry、Dispatcher、Poller、Reconciler 与结果处理也继续位于同一仓库。

本文记录已经执行的仓库拓扑，并冻结跨仓依赖、历史保留、Cutover、Rollback 与禁止双写规则。

已执行决策

十四仓总览

实线表示运行时调用方向，虚线表示版本化契约、文档或部署制品依赖。任何箭头都不代表跨仓源码导入或跨库直写。

产品与 Surface 仓库

Surface 边界不随共享登录而合并

• oceanway-site 和 oceanway-developer-center 是匿名公开 Surface；它们只读取可公开数据。
• oceanway-console 使用 Customer User Session；Console /ai 管理 App、Environment、Service Account、Credential、Playground、API Usage、Logs 与 Webhook。
• oceanway-admin 使用独立 Workforce Principal 和 Host-only Session；企业客户管理员仍留在 Console。
• Studio、Drama 与 Commerce 可以共享 OceanWay 登录体验，但只持有自身产品聚合，公共事实通过 Core 契约访问。
• FDE 公开说明与案例位于 oceanway-site；私有交付位于 oceanway-console，不创建 oceanway-fde。

运行与平台仓库

Core 是模块化运行时，不是新的“大杂烩”

oceanway-core 中每个模块仍拥有明确 Command、Service、Repository、表和事件。模块只能直接写自己拥有的数据；跨模块行为通过领域 Service、事务内协调或版本化事件完成。

下列模块不再单独建仓：

• Identity / Tenant；
• Authorization / Developer Access；
• Wallet / Billing / Entitlement / Budget；
• Asset / Resource Directory；
• Run / Execution；
• Agent / MCP；
• Model Catalog / Offering / Surface / Control Plane；
• Audit / Operations Read Model。

仓库合并不等于事实源合并。一个 Billing Account 仍只有一份账本，一个 Run 仍只有一个 Command Owner，一个 AssetVersion 仍只有一个正式所有者。

网关仓库

两个网关同级、私有、互不级联。Core 使用短期 Workload Credential 和版本化 Gateway Execution Contract 调用它们；产品仓和 API Edge 不直接携带 Provider Credential，也不绕过 Core 调用网关。

运维仓库

Docs 可以引用带版本的 Contracts 和发布元数据；Infrastructure 只部署带版本、签名或摘要的不可变制品。两者不能通过相对路径读取其他仓库源码。

现有仓库处置状态

“已建立目标仓库”不等于“代码与流量已经全部迁移”。Legacy 归档必须满足：生产流量为零、部署引用为零、Secret 已撤销或迁移、未完成任务已结清、文档指向新事实源，并存在可验证的 Remote、Mirror 或 Bundle。

明确不创建的仓库

• 不创建 oceanway-identity、oceanway-tenant、oceanway-wallet、oceanway-billing、oceanway-assets、oceanway-execution、oceanway-agent、oceanway-mcp 或 oceanway-model-control；
• 不创建第二个登录后 Developer Portal；Developer 私有控制面属于 oceanway-console/ai；
• 不创建 oceanway-fde；公开 FDE 属于 Site，私有交付属于 Console；
• 不创建 oceanway-media-registry、oceanway-media-dispatcher、oceanway-media-poller 或 oceanway-reconciler；
• 不为单个 Queue Consumer、Cron、Alert、Incident 或 Trace 创建仓库。

新增第 15 个仓库必须先证明现有 14 仓无法满足产品、部署或安全边界，并通过新的 ADR；不能仅因目录较大或领域名称不同而拆仓。

依赖方向

允许的运行时依赖方向：

1. Site 与 Developer Center 调用 Core 的公开只读接口，不读取客户私有数据。
2. Console、Studio、Drama、Commerce 与 Admin 通过各自 BFF 或受控服务契约调用 Core，不直连 Core 数据库。
3. API Edge 完成机器凭据认证、协议与限流后调用 Core；Core 创建正式 Run、预算预留和审计事实。
4. Core 根据 Offering Revision 和 Execution Manifest 调用 Text 或 Media Gateway。
5. 网关直连各自 Provider，并向 Core 返回标准状态、Usage、Cost 和不透明结果引用。
6. Docs 读取已发布的 Contracts 与版本元数据；Infrastructure 消费各仓库的不可变发布制品。

所有运行仓库都可以依赖 oceanway-contracts 的固定 Release，但 Contracts 不依赖任何运行仓库的源码。契约的业务语义仍由对应生产者负责，Contracts 仓负责版本化、校验、发布和弃用记录。

明确禁止：

• Surface 或产品仓导入 oceanway-core 源码，或直接读取 Core/Gateway 数据库；
• Core 导入 Studio、Drama、Commerce、Console 或 Admin 源码；
• API Edge 保存钱包、Run、Asset 或 Provider Supply 的第二事实源；
• 产品仓携带 Provider Credential 或绕过 Core 调用私有网关；
• 网关读取客户、钱包、Developer Access、产品 Run 或正式 Asset 表；
• 通过复制源码、相对路径、Git 分支 URL、Git submodule 或手工同步文件形成依赖；
• Infrastructure 持有明文 Secret 或成为绕过领域 Service 的数据修复工具。

版本化契约与事件

Canonical Source

oceanway-contracts 是跨仓契约的唯一 Canonical Source：

• Public API OpenAPI：路径、认证、错误、幂等、分页和异步任务；
• Core Service Contract：Surface/Product/Admin/API Edge 与 Core 的交互；
• Gateway Execution Contract：Manifest、Task、Attempt、状态、结果、Usage、Cost 和错误分类；
• Event Contract：统一 Envelope、业务载荷、版本和兼容规则；
• Generated Artifacts：带版本的类型、客户端或 Schema 包。

Provider 私有协议、Channel、Supply、Provider Credential Version 和原始上游 Payload 留在对应网关，不进入公共 Contracts。

兼容规则

• 所有 API、服务契约和事件都带显式版本；事件至少包含 eventId、eventType、schemaVersion、occurredAt、producer、subjectId、correlationId 和租户上下文。
• 同一主版本只允许兼容性新增；删除字段、改变语义、收紧必填或改变金额/状态含义必须发布新主版本。
• 演进顺序固定为“Contracts 先发布兼容版本 → 生产者兼容 → 消费者升级 → 切流 → 观察 → 下线旧版本”。
• 跨仓依赖固定到 Package Version、Release Tag 或 Image Digest；禁止依赖可变分支和本地路径。
• CI 必须验证 Schema、生产者实现、消费者契约与至少一个上一兼容版本。

事件规则

• 业务事实与 Outbox 在同一数据库事务写入，跨仓投递使用 at-least-once 语义。
• 消费者按 eventId 或业务幂等键去重，并允许重放、乱序和暂时重复。
• 事件不能绕过目标领域授权与不变量，也不能成为跨仓直接改表命令。
• 迁移期可以双读、Shadow Read、同时兼容新旧协议，但同一个业务命令不能向两个事实源双写。

本地非 Git 父目录

<workspace>/oceanway/
├── products/                          # 非 Git 父目录
│   ├── oceanway-site/                 # 独立 Git
│   ├── oceanway-developer-center/     # 独立 Git
│   ├── oceanway-console/              # 独立 Git
│   ├── oceanway-studio/               # 独立 Git
│   ├── oceanway-drama/                # 独立 Git
│   ├── oceanway-commerce/             # 独立 Git
│   └── oceanway-admin/                # 独立 Git
├── platform/                          # 非 Git 父目录
│   ├── oceanway-core/                 # 独立 Git
│   ├── oceanway-api-edge/             # 独立 Git
│   └── oceanway-contracts/            # 独立 Git
├── gateways/                          # 非 Git 父目录
│   ├── oceanway-text-gateway/         # 独立 Git
│   └── oceanway-media-gateway/        # 独立 Git
└── operations/                        # 非 Git 父目录
    ├── oceanway-docs/                 # 独立 Git
    └── oceanway-infrastructure/       # 独立 Git

硬性规则：

1. products/、platform/、gateways/、operations/ 和共同父目录都不执行 git init，不放 .git 或 .gitmodules。
2. 每个叶子仓库拥有自己的 .git、Remote、默认分支、CODEOWNERS、CI 和发布权限。
3. 禁止 Git submodule；跨仓只使用版本化协议与制品。
4. IDE Workspace 或本机仓库清单可以同时打开多个仓库，但不能成为父级 Git 仓库。
5. Linked Worktree 只能通过 Git 命令创建、移动和修复；移动前验证 common Git directory 与全部关联 Worktree，禁止手工搬运 .git 指针。
6. Oceanway-Web 和 Oceanway-design 维持既定处置，不为适配目录示意强行移动。

历史保留与迁移清单

每次内容或历史迁移必须生成 Migration Manifest，至少记录：

• 源仓库、Remote、Commit、Branch、Tag、Stash、Worktree 和 Dirty/Untracked 状态；
• 目标仓库、目标 Commit、Remote、默认分支、Owner 和 CODEOWNERS；
• 过滤工具版本、命令、路径映射、作者映射和输出 Commit；
• WIP Checkpoint、Mirror/Bundle、未跟踪文件白名单和 Secret Scan 结果；
• 契约版本、数据水位、Writer of Record、切换时间、验证项和回滚窗口；
• 旧部署、DNS、Webhook、Queue、Cron、Secret 与 Provider Callback 的关闭结果。

历史保留原则：

1. 保留可用的 Commit、Tag、作者和时间，不把当前快照复制到空仓后丢弃来源历史。
2. 路径抽取只在新鲜 Mirror/Clone 上使用可复现的 git filter-repo，不得破坏性重写唯一工作副本。
3. git subtree split 只允许一次性、单方向迁移；正式切断所有权后不维持双向同步。
4. Dirty 与 Untracked 内容不受 Git 历史保护，必须先建立具名 Checkpoint 或白名单快照并做 Secret Scan。
5. 在目标历史、Remote/Bundle、Worktree 和部署来源均可验证前，不删除或覆盖来源目录。
6. 仓库重命名必须保留重定向、部署引用和审计记录；oceanway-drama、oceanway-commerce 的来源映射永久写入 Manifest。

分阶段迁移

M0：十四仓拓扑建立（已执行）

• 14 个目标仓库已经建立并具有唯一名称；
• Drama 与 Commerce 已分别完成仓库重命名；
• 后续工作是内容、历史、部署和流量迁移，不再回退到已废弃的合仓方案。

M1：冻结、盘点与历史抢救

• 盘点所有来源仓库的 Remote、Branch、Tag、Dirty/Untracked、Stash、Linked Worktree、部署来源、许可证和 Secret 风险；
• 为未完成工作建立具名 WIP Checkpoint，生成 Mirror 或 Bundle；
• 优先处理无 Remote、失联 Worktree、多 Canonical 来源和仍被生产引用的目录；
• 此阶段禁止凭目录名删除“重复”仓库或重写唯一历史。

M2：Contracts 与 Core 成为事实 Owner

• 先在 oceanway-contracts 发布跨仓 API、事件和 Gateway Execution Contract；
• 将 Identity/Tenant、Developer Access、Wallet/Billing、Asset、Run、Agent/MCP、Model Control 与 Audit/Ops 收敛到 oceanway-core 的模块边界；
• 为每类 Command、表、事件、Outbox 与幂等键登记唯一 Owner；
• 旧实现只能代理到新 Core，不能继续写第二份事实。

M3：Surface 与产品仓迁移

• 公共品牌/FDE/案例迁往 Site；公开模型/文档/价格/状态迁往 Developer Center；
• 登录后客户控制、Console /ai 与 FDE 私有交付迁往 Console；
• Workforce 管理面迁往 Admin；机器入口迁往 API Edge；
• Studio、Drama、Commerce 只保留各自私有产品聚合，并通过 Contracts 调用 Core；
• 每个 Surface 独立构建、发布、回滚和撤销旧路由。

M4：双网关 Canonical 化

• Text Gateway 收敛 UUMI/new-api 的分支、Worktree、部署和供应配置；
• Media Gateway 保持单服务边界并移除客户域能力，不拆内部模块；
• 已受理 Task/Attempt 继续由原路径完成，新请求才切换到新部署；
• 对账供应 Usage/Cost、状态、结果和回调后关闭旧 Writer。

M5：Docs 与 Infrastructure 接管

• 架构、公开指南、ADR 和运行手册迁往 Docs；契约参考从固定 Contracts Release 生成；
• IaC、DNS、网络、部署与可观测声明迁往 Infrastructure；
• 应用仓只输出不可变制品，不复制环境 Secret 或部署脚本私有分叉。

M6：Cutover、观察与 Legacy 归档

• 按命令类别和流量批次切换 Writer、Route、Queue、Webhook、Cron 和部署；
• 校验身份、权限、执行、Asset、Usage、账务、审计、告警和在途任务；
• 回滚窗口结束后撤销旧 Secret 与写权限；满足归零条件后只读归档 Oceanway-Web 等 Legacy 来源。

Cutover、Rollback 与禁止双写

Writer of Record

在任意时刻，每一种业务命令、聚合根或幂等键只能有一个 Writer of Record。切换顺序固定为：

1. 冻结旧入口对新命令的接收；
2. 排空或记录在途 Request、Run、Attempt、Reservation、Gateway Task 和 Outbox；
3. 固定契约版本、幂等水位和数据校验点；
4. 切换路由与唯一 Writer；
5. 验证读取、权限、执行、Asset、Usage、结算和审计；
6. 关闭旧写权限并观察；
7. 回滚窗口结束后撤销旧 Secret、Consumer 和部署。

允许 Shadow Read、投影重建、结果比较和隔离环境重放，但这些流程不能生成第二份业务事实、账务分录或客户副作用。

明确禁止

• 同一命令同时写旧、新数据库或两个 Core 实现；
• 同一 Execution Attempt 同时提交到两个 Gateway 或 Provider；
• 重复生成 Meter Event、Reservation、Settlement、Asset、Webhook 或外部写操作；
• 使用双向 CDC 维持两个主事实源；
• 回滚时把已受理的在途任务搬给另一 Owner 重做；
• 以“最终余额相同”替代逐笔可追溯账本与 Usage 对账。

回滚语义

回滚只改变后续新命令的路由。已经由某个 Owner 接收的 Run、Attempt、Reservation、Gateway Task 和 Outbox 必须由原 Owner 完成、失败或进入 Reconciliation Case，不得因回滚再次执行。

无法确定请求是否产生外部副作用时，必须保留原幂等键和原 Owner，进入对账与人工处置；不能向另一仓库或网关盲目重试。协议双读和双版本兼容可以存在，业务双写不能存在。

CI、发布与所有权门禁

每个叶子仓库必须具备：

• 明确 Owner、CODEOWNERS、受保护默认分支和最小权限发布身份；
• 独立 Lint、Typecheck、Test、Build、Secret Scan、Dependency Scan 与制品摘要；
• 可追溯 Release Tag、Changelog、部署环境和回滚制品；
• 固定 Contracts 版本、消费者/生产者兼容测试和弃用窗口；
• 不含明文 Secret 的配置与 Runbook；
• 生产发布、数据迁移与 DNS/Queue/Callback 变更审计。

跨仓发布不以“同时合并 14 个主分支”为一致性方案。固定顺序为：Contracts 发布兼容版本，提供方实现兼容，消费者升级，流量切换，观察完成后再移除旧版本。

验收标准

• 14 个仓库都有唯一 Remote、默认分支、Owner、CODEOWNERS、CI 和发布制品；
• Site、Developer Center、Console、Studio、Drama、Commerce、Admin 与 API Edge 可以独立发布和回滚；
• Developer Center 不保存客户私有状态，Console /ai 是唯一登录后 Developer 控制面；
• API Edge 不接受 Customer Session，Service Account 仍是 API 唯一执行 Principal；
• Core 的 Identity/Tenant/Wallet/Billing/Asset/Run/Agent/MCP/Model Control 保持模块化且不重复拆仓；
• FDE 没有独立仓库，Media Registry/Dispatcher/Poller/Reconciler 没有独立子仓；
• Studio、Drama、Commerce、Console 与 Admin 不直接访问 Core/Gateway 数据库或源码；
• Text/Media Gateway 不出现 Customer User、DeveloperCredential、公开模型、用户售价、钱包或产品 Run；
• 所有跨仓依赖可由 Contracts Release、API、Event、Package 或 Image Digest 还原；
• 本地四个分类父目录不是 Git 仓库，不存在 Submodule 或跨仓相对路径依赖；
• 每次迁移都有可恢复历史、Manifest、唯一 Writer、Cutover 验证和 Rollback 记录；
• 任何业务双写、重复执行或无法归属的在途任务都会阻止切换。

延伸阅读

• 站点与产品拓扑
• 共享内核
• API、数据与基础设施
• 调度、执行与模型网关池
• OceanWay Studio 迁移计划
• 开发者平台迁移计划
• 交付路线图