历史 · oceanway-text-gateway 实施计划

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

仓库：Oceanway-AI/oceanway-text-gateway。现有运行基础：pic-vps 上的 UUMI/new-api 文本服务。

目标结果与当前基线

Text Gateway 把现有 UUMI/new-api 收敛为 OceanWay 私有文本模型基础设施，承载文本、Embedding、Rerank 等 Provider 协议适配、Channel/Supply、Provider Credential Version、健康容量、路由冻结、执行和不可变 Usage/Cost Evidence。

它与 Media Gateway 同级、互不级联。现有服务可继续作为迁移来源，但正式接入 Core 前必须完成私有边界、契约适配和唯一生产来源核对。

明确移除或禁止

• OceanWay 客户用户、Customer Group 和 Customer Session；
• DeveloperCredential、客户 API Key 与公开 API 认证；
• 公开模型广场、Surface Offering 和用户售价；
• Wallet、订阅、预算、产品 Run、规范 MeterEvent/ProviderCostFact 与正式 Asset；
• 产品仓或 API Edge 直接调用网关；
• Text Gateway 级联到 Media Gateway，或反向级联。

new-api 中与这些能力相关的现存功能只能作为上游运维实现细节关闭、隔离或删除，不能成为 OceanWay 客户事实源。

本轮全流程：先统一消费者需求、私有化设计与原型

Owner：本人，负责盘点、需求、服务设计、原型、后台 API、文档和验收；使用本机工作台协调，按实施工作流记录每个决策和证据。既有运行服务保持其当前职责，补计划不直接触发迁移或下线。

消费者需求与首轮待决策项

本人先确定首个 Provider/文本能力的最小范围与验收场景；Embedding/Rerank、多供应商及运维 UI 是独立待选范围，不因源项目具备就全部纳入。现有部署文档中的路径/分支与新本地布局可能不同，真实来源在接入前只读核对并记录。

服务、数据、错误与权限设计

按 Dispatch Slot→Route Binding→Provider Side Effect→查询/对账→Evidence 画时序，列 Channel/Supply/Credential Version/Provider Task 私有事实与 Core Attempt 的引用边界。每个状态标明是否可能已产生上游副作用、谁可推进以及是否允许重试；Provider 确定性错误、提交未知、临时失败和内部冲突分别定义。

数据设计列不可变路由、任务版本/CAS、证据追加与保存期限，禁止客户钱包/售价作为 OceanWay 事实进入网关。权限设计分 Core 调用身份、Evidence 读取和受控运维，待定 Scope/配置值不猜测；Provider Secret 只由网关管理，不进入跨仓返回或日志。

非 UI 原型与首轮验收

使用 Provider stub 和合成材料，演示一次固定路由提交、同 Attempt 重放、响应丢失后查询、凭据轮换不改变已绑定版本和 Evidence 缺失。产物包括调用时序/状态机、请求与安全错误示例、可运行 fixture 及预期结果；不发起付费调用。

首轮要求每个状态都能解释下一步、迁移来源/Owner 明确、Core 与网关没有第二 Writer。原型验证提交未知处理，不用返回 200 的 stub 冒称 Provider 真实幂等保证。若存在运维页面需求，先确认归 Admin 还是私有运维工具，再另做 UI 原型。

接口清单与 API 文档

本人维护网关仓的 HTTP OpenAPI、adapter 能力表和错误目录；方法/路径在实际设计或代码确认后填写。Schema 消费 Contracts 生成制品；非 TypeScript 实现使用其固定 JSON Schema，不手写第二套 wire model。每条文档列版本、Owner、身份/Scope、错误、分页/幂等（不适用也标注）、成功/未知/冲突示例及弃用策略。Docs 链接固定接口来源，Provider 私有内容不进入公开 API 文档。

后台实现切片与接入边界

1. 先完成来源/需求/原型及旧客户功能迁移决定；逐文件复用稳定 adapter，不重建已验证的 Provider 基础。
2. 在明确范围内收口 Workload-only 服务边界，完成配置和权限负测；存量生产客户迁移单独安排。
3. 固定 B2 契约并取得消费资格后，实现 Dispatch Slot/Binding、Task 状态与安全错误，再补查询/对账恢复。
4. 追加 Usage/Cost Evidence、授权读取/验证和摘要；Provider stub 覆盖响应丢失、重复提交与在途凭据轮换。
5. 用真实数据库和独立进程补并发/崩溃/旧租约测试，验证不会创建第二上游任务；真实 Provider canary 使用后续明确范围与环境。
6. 固定镜像/契约/来源、清点在途任务、验证唯一 Writer 与回滚后才切入 Core。Text canary 成功不自动推广其他 Provider 或媒体能力。

需求和本机原型可先行；固定契约生产消费、付费调用与部署不是本轮原型完成的隐含动作。

仓库里程碑

1. TEXT-1 来源盘点：核对 UUMI/new-api Remote、分支、Worktree、部署来源、数据库、Secret、Channel 和在途任务。
2. TEXT-2 私有化收口：关闭客户注册、用户分组、公开 Key、商城、用户价格和外部管理入口；建立 Workload-only Audience。
3. TEXT-3 Gateway Contract：实现 Attempt、唯一 Dispatch Slot、Route Binding/Snapshot、Task 状态和安全错误映射。
4. TEXT-4 Evidence：追加 ProviderUsageEvidence/ProviderCostEvidence、Availability、Current Read/Validate Receipt 和内容摘要。
5. TEXT-5 Canary：只接一个 Organization、credits、Offering、Execution Target 与固定 Provider 路径。
6. TEXT-6 扩展：在 canary 通过后按 Provider/能力逐项开放文本、Embedding、Rerank 和容量路由。

执行不变量

• Provider Side Effect 前原子创建唯一 Dispatch Slot 与 Route Binding；同一 Attempt 不换 Channel、Supply、Credential、Provider Model 或 Adapter。
• 需要换路时由 Core 创建新 Attempt；网关内部重试只允许完全相同路由且有供应商幂等/查询证据。
• 提交结果未知时保留 Attempt-bound 状态并查询/对账，不伪装失败或盲目重投。
• Gateway 只保存不可变 Provider Evidence 与 source ref；Metering 才能创建规范 MeterEvent/ProviderCostFact。
• 返回 Core 的对象使用固定 Contracts 四元组和摘要，不返回 Provider Secret 或完整私有 Payload。

验收与切换

• Workload JWT 的 Issuer、Audience、Subject、Purpose、Scope 与 Operation 全部逐项验证。
• 同一 Attempt/Dispatch 身份重放返回首次 Task/Receipt；同身份异摘要被隔离。
• 故障注入覆盖 Provider 已提交但响应丢失、Poll/Reconcile 竞态、凭据轮换、旧 Lease 和 Callback 乱序。
• 生产切换前冻结旧/新唯一 Writer、在途任务、渠道映射和回滚路径；旧部署不能继续接受同一范围的新任务。
• 网关数据库与 API 中不能出现 OceanWay 客户余额、用户售价、DeveloperCredential 或产品对象。

完整契约见调度、执行与模型网关池，计量边界见ADR-031。