历史 · Polyrepo 仓库拓扑与迁移治理

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

Oceanway-AI 当前对应 15 个独立仓库。根据 ADR-032，oceanway-developer-center 停止独立开发并迁入 Console，作为待归档历史来源；Design 已独立承接设计系统，当前为 14 个目标活跃仓库和 1 个历史来源仓库。仓库与产品 Surface、公共 API、共享运行时、私有网关、文档和基础设施边界对齐，使各部分可以独立授权、构建、发布、回滚和归档。

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

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

每个仓库的具体工作包、当前基线、进入门禁和验收证据不在本页展开，统一维护在多仓实施总控。本页仍是“有哪些仓库、为什么这样分、允许怎样依赖”的唯一架构事实源。

2026-09-09 Design 迁移见 Design #2 与 Infrastructure #21。Design 默认分支仍为 baseten-ui，共享包发布与产品接入另行实施。本轮任务采用本机协调，不改变运行时事实边界。

已执行决策

目标活跃仓与历史仓总览

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

产品与 Surface 仓库

代码仓合并不取消 Surface 安全边界

• oceanway-site 与 Console 的 ai.oceanway.tech 匿名路由只读取可公开数据。
• 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；其中 Dispatcher、投影存储与私有 Query API 固定由 Core Operations 拥有，Admin 只通过 BFF 查询。

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

网关仓库

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

运维仓库

Docs 可以引用带版本的 Contracts 和发布元数据；Infrastructure 只部署带版本、签名或摘要的不可变制品。两者不能通过相对路径读取其他仓库源码。 Infrastructure 可以拥有自身的工程工具与共享 UI/token 源码，不能因此导入产品业务实现。 /components 从 Studio 迁为 Infrastructure 独立实验室；产品使用其发布的固定版本包， 不是运行时调用实验室或导入 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 Surface 都由 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 创建仓库。

新增任何活跃仓库必须先证明当前 13 个目标活跃仓无法满足产品、部署或安全边界，并通过新的 ADR；不能仅因目录较大或领域名称不同而拆仓。

依赖方向

允许的运行时依赖方向：

1. Site 与 Console 匿名路由调用 Core 的公开只读接口，不读取客户私有数据。
2. Console 认证路由、Studio、Drama、Commerce 与 Admin 通过各自 BFF 或受控服务契约调用 Core，不直连 Core 数据库。
3. API Edge 严格解析 22 字符 keyId 与 43 字符 secret 的 ow_sk_<keyId>.<secret>，只把 keyId 与短期 Workload JWT 用于读取 Core 验证快照，在请求生命周期内本地比较 SHA-256 Digest；再提交 apiVersion="v1"、受信上下文和规范请求 Fingerprint。Credential ID 是不可变版本身份，轮换创建新 ID 并撤销旧 ID；Core 按确切 ID 重检父链，解析 publicModelId、持久化 Run Input，并创建授权决策、Run、预算预留等准入事实。完整 Request Attempt、Error Occurrence 与运维关联由后续 Ops Explorer 建立。
4. Core 根据 Offering Revision 与 RunAdmissionManifest 创建每次 AttemptExecutionManifest，再调用 Text 或 Media Gateway；同一 Attempt 不得换路。
5. 网关在 Provider Side Effect前原子创建唯一 AttemptRouteBinding + GatewayRouteSnapshot，直连各自 Provider，保存不可变 ProviderUsageEvidence / ProviderCostEvidence，并向 Core返回标准状态、Binding/Route完整四元组、必填的 usageEvidenceAvailability + costEvidenceAvailability与不透明结果引用；只有 available分支携带相应 Evidence完整四元组。Metering再逐层校验并唯一生成规范 MeterEvent / ProviderCostFact。
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 的第二事实源；
• API Edge 持久化 Credential、Digest、验证快照、Run Input，或把 Raw Developer Secret 转发给 Core、Gateway 和 Provider；
• 产品仓携带 Provider Credential 或绕过 Core 调用私有网关；
• 网关读取客户、钱包、Developer Access、产品 Run 或正式 Asset 表；
• 网关或 Operational Observation 创建规范 MeterEvent / ProviderCostFact，或绕过 Metering/Billing 驱动客户结算；
• 通过复制源码、相对路径、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、状态、结果、Binding/Route/Provider Evidence完整四元组和错误分类；规范 MeterEvent / ProviderCostFact属于 Metering Contract，不由 Gateway生产；
• Event Contract：统一 Envelope、业务载荷、版本和兼容规则；
• Generated Artifacts：带版本的类型、客户端或 Schema 包。

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

兼容规则

• 所有 API、服务契约和事件都带显式版本；事件至少包含 eventId、eventType、schemaVersion、occurredAt、producer、aggregateId、正整数 aggregateRevision、actorPrincipalId、correlationId 和 Organization/Workspace 租户上下文，可按事实携带 Project、Operation、Causation 与 Trace。
• 严格对象 Schema 的既有字段集合发生变化时发布新主版本；兼容扩展优先新增独立 Schema 或新的事件版本。删除字段、改变语义、收紧校验或改变金额/状态含义同样属于不兼容变更。
• 演进顺序固定为“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，不能继续写第二份事实。

M2 的首个实施基线采用“Contracts First + PostgreSQL Run Admission 纵切”。@oceanway-ai/contracts@0.1.0 是 2026-09-03 验收的初始固定版本；Core 当时只覆盖 API Edge 已认证上下文、租户/开发者访问/授权、API Offering、credits 预占、Run、不可变 Manifest 和事务 Outbox。该历史基线不代表生产部署或完整 Identity、Billing、Execution、Outbox Publisher、Gateway 已完成。详细决策和后续顺序见 ADR-028。

API Edge 的受控准入采用 ADR-029：固定 POST /v1/responses、22/43 字符 Key Grammar、强制 Idempotency-Key 与 apiVersion="v1"、请求级验证快照、本地 constant-time Digest 校验、短期 Workload JWT、flat 成功/nested 错误 Envelope、Core publicModelId 解析和不可变 Run Input。该基线现已完成固定制品、独立 CI 与真实跨服务隔离验收：Contracts 0.2.0（Commit ce323954；CI 33756169615；Release 33756329273；Verify 33756418040；tgz SHA-256 731b9a54d846a7fb8714ba651d41d466abfa2b2b98a4f1466eedb0287e0a23c4）、Core f9e55b6（CI 33777925718）、API Edge f97cf5f（CI 33774539995），以及 Infrastructure e72e5f3 中由 Gate 9cc3c9c 生成的 controlled-admission-e2e-9cc3c9c49b16-f9e55b6e56e4-f97cf5f27027.json。验收只证明默认关闭与受控模式下的 Credential/JWT/幂等/事务准入链路；/v1/responses 公网流量、Gateway 执行与输出、Outbox 发布、Metering 和 Settlement 均未完成。当前下一工程阶段是 Outbox Publisher 与 Ops Explorer；分布式限流、完整链路追踪和公网压测仍是公开切流前置门禁。

下一阶段采用 ADR-030：同一 oceanway-core 制品增加独立 core-operations-worker Role，使用 PostgreSQL Outbox、Append-time Delivery Set、Lease Fencing、Applied Receipt 与版本化投影，不创建新的仓库或预先引入 Kafka/NATS，也不使用全局标量 Position 假装连续水位。oceanway-contracts 先配对发布 run.created@2.0 + wallet.reserved@2.0，并发布 Operational Observation 与私有 Query 契约；首个 Producer 只允许 Organization 准入且必须在同一事务中原子切换这对 v2 事件，两个 v1 保持原 Schema 不变。Core Authorization 统一签发 Workforce Grant，特权/跨租户查询 Audit fail-closed；oceanway-admin 只实现 Workforce BFF/UI。Event 与已接受 Observation Source 由数据库强制不可变，Edge Observation 仍是 best-effort。该内容目前是已采用的文档基线，尚未形成代码或验收证据。

M3：Surface 与产品仓迁移

• 公共品牌/FDE/案例迁往 Site；公开模型/文档/价格/状态迁往 Console 的 ai.oceanway.tech 匿名 Surface；
• 登录后客户控制、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 输出按来源映射为不可变 Gateway Evidence，经 Metering 生成规范 Fact；对账 Evidence、状态、结果和回调后关闭旧 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 完成、失败、保持可恢复阻塞或进入已注册的正式终态流程，不得因回滚再次执行；只有满足 late_settlement_dimension | billing_finalization_run 来源契约的 Billing 状态才能创建当前 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、Console、Studio、Drama、Commerce、Admin 与 API Edge 可以独立发布和回滚；Console 的同一制品可按 Host 独立切流和回滚；
• Developer Center 匿名路由不保存客户私有状态，Console /ai 是唯一登录后 Developer 控制面；
• API Edge 不接受 Customer Session，Service Account 仍是 API 唯一执行 Principal；V1 Admission 强制 apiVersion="v1"，客户不能声明租户、付款方或可选 Project；
• API Edge 不持久化 Credential/Snapshot/Run Input，Raw Developer Secret 不越过 Edge；Credential ID 是不可变版本身份，Edge 到 Core 使用短期 Workload JWT，Core 保持父链复核、模型解析与准入事实唯一 Owner；
• 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 迁移计划
• 开发者平台迁移计划
• 交付路线图