历史 · 架构变更记录

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

2026-09-09

• 在原 B1 控制页记录合并态与验收差异，补齐 Core 0003/0004 回归失败和独立评审输入；Admin P4、Infrastructure #17 已关闭，P5 与 B1 保持未验收。
• 更新普通包评审规则来源、13 仓定点治理同步待办及 Console 机器可读证据缺口；保留历史快照，不扩展运行时授权或派发重复 Writer。

本页只记录 OceanWay 当前平台架构和实施边界的变化，不记录旧产品的版本历史、页面功能或发布测试流水。

2026-09-08

B1 固定证据与下一批工作校准

• 正式 0.3.0 发布与双源校验已完成；Core P3/Admin P4 候选 CI 通过、独立评审与 P5 接收待完成。解除旧的“尚未发布 / Admin 403”状态，保留真实 Runtime 未验收限制。
• 原 B1 控制页增加固定 SHA、测试/CI、独立评审输入、Owned Paths 排队及真实事件链缺口；下一阶段每仓只保留一个当前包。
• Studio 隔离与 Console 只读目录按各自真实测试边界登记，不计作 B4 切流；更新现有验收/恢复入口。仅 Docs 协调记录，未批准评审、合并外仓、部署或生产切流。
• 本轮文档验证：冻结安装、types:check、生产构建（83 页）、依赖审计与 70 个内部链接检查通过；这是本地 Docs 验证，不是外仓独立评审或新的 B1 CI。

2026-09-05

B1 GitHub 执行结构建立

• Contracts、Core、Admin 与 Infrastructure 已分别建立 B1 Milestone，共形成 21 个稳定工作包：Contracts 4 个、Core 8 个、Admin 4 个、Infrastructure 5 个。
• 每个 Issue 固定目标、范围、非目标、上游门禁、仓内验收与跨仓证据，并通过真实 Issue URL 串联 Contracts Release → Core Outbox/Projection/Query → Admin Explorer → Infrastructure Evidence。
• 未设置未经确认的负责人、截止日期或生产切流日期。实施文档只登记 Milestone 入口，Issue/PR/CI 继续作为实时执行事实源。

十四仓实施计划正式分页

• 新增与“平台架构”“项目进度”并列的“仓库实施计划”一级目录，正式采用“一个仓库一个实施主页，跨仓依赖由总控页编排”的文档结构。
• 十四个仓库按产品与 Surface、平台与运行、模型网关、运维与治理四组分页；每页固定维护目标结果、当前基线、范围边界、依赖、里程碑、进入门禁、验收和回滚。
• 新增交付批次、跨仓依赖矩阵和统一 Evidence Manifest/Writer Cutover 规范。架构文档继续维护目标边界，Progress 只维护当前状态，GitHub 继续承载 Issue/PR/CI 的实时任务信息。
• 当前关键路径没有改变，仍为 Outbox/Ops Explorer → Metering/Settlement → Text Gateway canary → Asset → Console/Studio cutover；公开内容和无副作用设计可以并行，正式业务 Writer 不得越过门禁。

2026-09-04

Contracts 0.2.0 固定发布

• @oceanway-ai/contracts@0.2.0 已由 Commit ce323954 固定发布；CI Run 33756169615、Release Run 33756329273 与 Registry/Release Verify Run 33756418040 均已通过。
• Release tgz 的正式 SHA-256 为 731b9a54d846a7fb8714ba651d41d466abfa2b2b98a4f1466eedb0287e0a23c4；受控联调直接校验并使用该不可变制品，不使用本地源码链接或可变分支代替。

API Edge 受控准入正式验收

• Core f9e55b6 的 CI Run 33777925718 与 API Edge f97cf5f 的 CI Run 33774539995 已通过。
• Infrastructure e72e5f3 收录由 Gate 9cc3c9c 生成的正式证据 controlled-admission-e2e-9cc3c9c49b16-f9e55b6e56e4-f97cf5f27027.json。该门禁使用真实 Contracts Release tgz、HTTPS JWKS、RS256 Workload JWT、Edge/Core Socket HTTP 和隔离 PostgreSQL，验证默认关闭、受控 202/reserved、并发同键收敛、冲突拒绝、等价认证失败、Host/租户字段拒绝、JWT/Scope 边界以及关联和持久化结果。
• API Edge 仍以 PUBLIC_ADMISSION_MODE=disabled 为默认值，公网流量没有开放。当前验收不包含 Gateway 执行与输出、Outbox 发布、Metering 或 Settlement，也不代表生产 API 已完成。
• 当前下一工程阶段正式进入 Outbox Publisher + Ops Explorer：先把事务 Outbox 可靠发布并建立 Operation/Run/Reservation 运维读模型，再进入 Metering/Settlement 与 Gateway canary。

Outbox 与 Operations 文档基线

• 正式采用 ADR-030：Outbox Dispatcher、Consumer/Projector、Operations Read Model、Observation Source 与私有 Query API 统一归 oceanway-core Operations 模块；oceanway-admin 只拥有 Workforce Query BFF/UI。
• 首期采用 PostgreSQL Outbox 与同一 Core 制品的独立 core-operations-worker，不引入 Kafka、NATS、Redis Streams、新 Git 仓库或新的业务微服务；外部 Broker 只在独立消费者、容量或故障域证据成立后另行决策。
• 事件与投递状态正式分离：Event Envelope/Payload 由数据库强制不可变，Mandatory Delivery Set 在 Event Append 同事务冻结，Delivery/Attempt/Quarantine 独立记录；Lease Token 防止旧 Worker 覆盖，Applied Receipt、Projection Mutation 与 Checkpoint 同事务。Checkpoint 不依赖会受提交乱序与回滚空洞影响的全局标量 Position。
• 下一 Contracts 版本将配对提供 Tenant-aware run.created@2.0 + wallet.reserved@2.0 的低敏、自包含准入事件；首个 Producer 只允许 Organization。已发布的两个 v1 保持原 Schema且只能形成 Legacy/Partial 投影，禁止收紧可选字段或用当前 Domain Query/日志水合历史。
• Edge Request Attempt/Error Observation 与领域事实分离：Edge 到 Intake 是 best-effort；Core 一旦接受就按 Observation ID 幂等、不可变保存。首期只显示 Accepted Observation 范围、健康窗口和已知投递失败，请求级完整性保持 Unknown/Not Measurable。
• Signed Workforce Grant 由 Core Authorization 统一签发；Admin BFF 只转交短期 Workload JWT 与 Grant。特权/跨租户查询必须先耐久写入 Audit，Audit 失败时不返回数据。
• 新增“运维事件与读模型”文档组，并把 Admin 平台拆出 Run Explorer、Error Center、Incident/Reconciliation 独立页面。当前只将 Run Explorer 作为准入纵切目标；后两者明确属于后续阶段。
• 以上是已采用的文档与实施契约，Publisher/Dispatcher、Contracts 扩展、投影、Query、Admin 页面和跨进程证据尚未实现或验收，公网与 Gateway/Metering/Settlement 继续关闭。

Operations 与执行证据链收口

• Operations 投影正式区分 operation_linked / observation_only / legacy_run_only，wallet-first 事件先进入 Pending Reservation 再按完整关联键原子链接；Snapshot 以严格 verified / unverified 判别联合表达完整性、时效与 Integrity，缺失可比较快照或 Guard 时必须是 Unknown。
• Shadow Rebuild 改为 Candidate-first：先只冻结精确 Source Member/Canonical Source Digest、定义版本和 Expected Receipt Coordinates，Shadow 追平该集合后，最终事务才生成新的不可变 Readiness Proof 并原子切换；最终事务不能扩大边界。
• Error Producer 不再提交服务身份或 Fingerprint；Core 从受信 Source 派生服务，并作为唯一 Writer 按固定七字段、NFC + RFC 8785 JCS 与 SHA-256 计算版本化 Error Fingerprint。
• Run 级准入、实际执行和私有路由分别由 RunAdmissionManifest、AttemptExecutionManifest、AttemptRouteBinding 与 GatewayRouteSnapshot 固定。同一 Attempt 只有一个 Binding/Route Snapshot；网关内部只能沿完全相同路由做经证明安全的协议重试，任何换路由都由 Execution 新建 Attempt。
• MeterEvent.gateway_provider 与 ProviderCostFact 必须同时绑定 Attempt Route Binding、Gateway Route Snapshot 与对应 Evidence；跨层确定性错配写 Owner-local Conflict/Blocked 事实，不伪造第三种 Operations Case。普通响应不暴露 Channel、Supply 或凭据版本。
• 目标架构统一使用 tenantKind = organization | personal_space 与 tenantId；已发布 Contracts 0.2.0、现有 Core/API Edge 准入和 wallet.reserved@1.0 仍是 Organization-backed 历史事实。Personal Space API Admission 等待 tenant-aware Manifest、Run/Wallet Event 与真实权限/账务门禁共同发布，当前保持禁用。

执行、计量与账务终局协议

• 正式采用 ADR-031，冻结 Admission → Attempt → Gateway → Metering → Execution Closure → Billing Finalization → Post-boundary Transition/Case 的单向事实链；该 ADR 是目标契约，尚未形成运行时完成证据。
• Gateway 为每个 Attempt/Deployment/Manifest 身份只允许一个 Dispatch Slot，并在同一事务互斥收敛到 Bound 或可证明无 Provider Side Effect 的 Terminal Rejection；未知提交必须保留 Attempt-bound 并查询或对账。
• Execution 用不可逆 CAS 和内容寻址 Attempt Set 关闭执行集合。Billing 尚未知关闭 Ref 时先读取严格前置结果；只有 Closed 才能构造 FinalizationInputManifest@1，再取得 Execution、Metering、Gateway 三组 Purpose-bound Receipt 和 FinalizationValidationBundle@1。
• 成功 Billing Finalization 只在 Billing 本地事务原子提交 Decision、Ledger、Reservation 终态与 Release，且成为吸收态；验证边界后的 Eligibility/Usage/Evidence 更正只追加 Transition、Refund 或 Late Settlement Exposure，不重开历史终局。
• 客户经济身份正式区分 Credits、Entitlement Bucket/Unit 与 Money Currency。人工正差额补结还必须绑定 Funding Policy、一次性 Funding/Command Grant、Metering Receipt 和严格 LateSettlementCommandResult@1；Operations 只消费 Applied Fact 并按 Exposure Source Revision 收敛 Case。
• 必达事件注册表收口为 13 个 Event Type/Schema 适用项与 14 个 Mandatory Destination Member；billing.finalization-reconciliation-resolution.applied@1 同时投递 Billing Coordinator 与 Core Operations。Delivery Set 在 Event Append 事务冻结，Consumer Receipt、Work/Fence/Watermark 与投影副作用必须分别在所属 Owner 的单一事务收敛。
• Finalization Fence 进入 reconciliation_required 后只允许当前代 FinalizationReconciliationResolutionApplied@1 重新打开评估；后到 Settlement 只推进 Watermark 并返回 Held Receipt，Execution Closure 重投只返回首次 Receipt，均不得自行退出 Case。任何 Producer 能进入该状态前，必须同批启用完整的 Finalization Resolution 命令出口。
• Finalization Case 使用不绑定易变 Work 的稳定 Identity Reservation；最终 Case Requested Event 才冻结获胜 Work/Generation 与 Finalization Operation。Admin/Operations 以 late_settlement_dimension | billing_finalization_run 严格联合展示，两种 Billing 来源都只能由各自 Billing-owned Applied Fact 驱动终态。
• Command Grant Exchange 新增 Operation-first 恢复：稳定 Operation 只由 Assertion Issuer/JTI 派生，Candidate/Workload 作为首次 Result 的 insert-or-compare 正文；Core 已提交 Grant/Audit 后响应丢失，完全相同输入即使跨过 Assertion 到期仍返回原 Grant，同 JTI 偷换 Candidate 则冲突。
• 正式 Operations Case 联合收敛为 late_settlement_dimension | billing_finalization_run。其他 Execution/Gateway/Metering/Provider Cost/Asset/Webhook 异常使用 Owner-local Conflict/Blocked、Signal 或 Incident；没有独立 Canonical Event、Mandatory Delivery、Owner Read、Identity 与终态 Authority 时不得扩展 Case。
• Metering 的确定性冲突不再伪装为 Work 完成或第三种 Case：Blocked Fact 保留 Active Work，暂态错误不写领域 Fact；新 Generation 通过 superseded Finish 明确关闭旧 Started Attempt，避免运维页面永久显示 Running。

Gateway Evidence 与 Metering 事实所有权

• Text/Media Gateway 对用量和成本只拥有不可变 ProviderUsageEvidence / ProviderCostEvidence 及 source ref；Gateway Response 与 Gateway Operational Observation 必须同时携带 usageEvidenceAvailability 与 costEvidenceAvailability 严格联合，每个分支都携带Availability Snapshot的Ref/Schema Version/Digest Algorithm Version/Digest/State Version，只有各自 available 分支再携带对应Evidence完整四元组，其余状态禁止全部Evidence字段；不得把任何 Gateway Usage/Cost 字段冒充 OceanWay 规范事实。
• Metering 是规范 MeterEvent / ProviderCostFact 的唯一 Writer，负责绑定 Execution Attempt、规范单位/币种、幂等去重、追加更正和差异对账；Billing 只基于规范 MeterEvent、可信输出状态与冻结 Price Snapshot 处理客户结算。
• Provider Cost Evidence/Fact 只进入供应核对、成本归集和毛利链，迟到、缺失或更正不能阻塞或改变客户费用；Operational Observation、Poll、Callback、Telemetry 与 Admin Case 均不能直接驱动结算。
• 该规则是已采用的目标契约，现有 UUMI/new-api 或 Media Gateway 中名称相似的 Usage/Cost 字段只作为迁移输入。Gateway Evidence、Metering Writer 与结算闭环尚未实现或验收。

跨服务契约深度审计与路线图收口

• 跨域不可变对象统一使用 Ref + Schema Version + Digest Algorithm Version + Digest 完整内容身份；有 Current 链的 Snapshot 另外携带 State Version 与完整直接前驱身份。Owner Read 必须按精确 Audience、Tenant/Reservation/Run/Attempt/Operation Scope 定向读取并重算摘要，禁止裸 Ref、“最新记录”、相邻 Event 补值或跨用途 Receipt 复用。
• Billing Transition 把稳定逻辑 Operation 与按 From State/Basis 确定性派生的 Validation Operation 分离。并发前驱推进后必须丢弃旧 Receipt、按新 Revision 重建 Basis 与 Validation Operation；Settlement 可以通过经过逐项 Owner Read 的非空有序 Snapshot Lineage 一次追平多个更正，但不能跳过、分叉或只验证末项。
• ExecutionFailureFact@1 已冻结为 Execution-owned 封闭低敏事实，readExecutionEligibilityFact 同构返回 Failure/Not-dispatched Evidence。Operations 错误记录、Provider 自由错误正文和暂态状态不能代替执行终态或驱动结算。
• Late Settlement Case 的业务终态只由 Billing-owned BillingCaseResolutionApplied@1 驱动；Operations/Admin 只拥有调查、指派、评论与命令编排，不能用本地“已解决、驳回、无需处理”或供应损失标签直接关闭账务 Case。平台承担、核销等处置必须等待新的 Billing-owned Disposition 契约。
• Gateway Diagnostic 只返回封闭的低敏结果摘要；Operations 验证 Binding 时必须绑定当前 Submission 或 Accepted Observation 的完整摘要，不能借此读取私有 Route、Availability/Evidence 正文或签发计费 Receipt。Adapter 的 ProviderEvidenceSourceDTO@N 必须在 Release Manifest 中解析为具体封闭 Schema，未注册占位符或自由 JSON 不能通过 Deployment Admission。
• Operations Explorer、Projection Status、Completeness Snapshot/Proof 与 Current Guard 已补齐严格请求/响应和证据边界：历史 Proof 冻结 Mandatory Delivery Definition、精确坐标/终态集合与全部摘要输入，当前查询只在定义可比且现场输入全等时声明 verified_current。
• 交付路线图正式区分“当前核心固定门禁”和“长期并行产品工作流”。当前顺序保持 API Edge → Outbox/Ops Explorer → Metering/Settlement → Text Gateway canary → Asset → Console/Studio cutover；Media 正式执行只能在最小文本链通过后复用同一骨架扩展。模型发布目标只有 web/api/internal 三类 Surface，unpublished 是独立发布状态。
• 上述均为文档与目标契约收口，不表示 Contracts 新版本、Outbox/Ops、Gateway、Metering、Billing Transition 或 Admin 运行时已经实现。

当前阶段

• 平台目标架构已完成首轮文档化。
• Phase 0 的 Contracts 0.1 与 Core Run Admission 历史基线已经验收；Contracts 0.2.0、Core f9e55b6、API Edge f97cf5f 和 Infrastructure 受控跨服务门禁也已完成正式验收。
• Outbox Publisher/Dispatcher 与 Ops Explorer 的架构文档已完成，当前下一动作是依照固定顺序实施 Contracts → Core → Admin → Infrastructure Evidence；生产部署、Public API 公网切流、Gateway 执行与输出、Outbox 发布、Metering 和 Settlement 均不记录为完成。
• 实施状态与下一门禁分别维护在当前状态和下一阶段。

2026-09-03

Contracts 与 Core 首个实施基线

• 发布 @oceanway-ai/contracts@0.1.0，固定公共安全根导出、公开模型目录与内部 Execution、Model Control、Gateway 子路径；发布流程改为同一 tgz 同时进入 GitHub Packages 与 Release，并新增 Registry/Release 制品比对 Workflow。
• Event Envelope 固定使用 aggregateId / aggregateRevision；Request Context 显式包含 Caller Workload Principal 与认证上下文。
• Core Commit 77f336a 已形成 PostgreSQL Run Admission 功能基线，将租户、Developer Access、授权、API Offering、credits Reservation、Run、不可变 Execution Manifest、幂等结果与 Outbox 放入同一事务；本地类型检查、构建、依赖审计、5 项单元测试、14 项专用 PostgreSQL 集成测试和 Health 启动验证均已通过。
• GitHub Packages 为 oceanway-core Actions 授予 Contracts Read；Core 在 4d66b6c 使用 pnpm gh: registry-qualified 精确依赖，并只为 @oceanway-ai/contracts@0.1.0 配置 minimumReleaseAge 例外，避免 Registry 异常时被同名公共包替换。
• Core 独立 CI Run 33745852471 已通过，Contracts-first/Core Run Admission 实现基线转为已验收；生产部署、Public API、Outbox 发布、Gateway 执行、完整结算与 Asset 登记仍不记为完成。
• 下一阶段固定按 API Edge → Outbox/Ops Explorer → Metering/Settlement → Text Gateway canary → Asset → Console/Studio cutover 推进。

API Edge 受控准入与信任边界

• 采用 ADR-029，首个公共契约固定为 POST /v1/responses，只接收稳定 publicModelId 与非空文本，并强制要求 Idempotency-Key；Chat Completions、流式与其他能力后置。
• V1 DeveloperCredential Grammar 固定为 ow_sk_<keyId>.<secret>，其中 keyId 是 22 字符、secret 是 43 字符无填充 base64url。调用时 Raw Secret 只到 API Edge；Edge 按 keyId 从 Core 读取请求级验证快照，在本地执行 SHA-256 constant-time 比较，不建立 Credential、Digest 或 Snapshot 业务持久化。
• 不引入独立 credentialRevision：developerCredentialId 本身是不可变 Credential Version 身份，轮换创建新 ID/Key/Secret 并撤销旧 ID。Core 在 Snapshot 与 Admission 分别检查确切 Credential、App、Environment、Service Account、租户和 Billing Account；Workspace 与可选 Project 由 Environment Execution Binding 唯一解析，Admission 再解析当前 api Model Offering。
• Edge 到 Core 使用短期 Workload JWT；内部 Admission 强制 apiVersion="v1"。Edge 的 Operation/Correlation 绑定 V1、Organization、Environment、Service Account、操作与 Idempotency-Key；Core 幂等记录按 Organization、Execution Principal 与 Idempotency-Key 分区，冲突 Fingerprint 只包含 apiVersion、操作、Environment、Service Account 与公共请求 Fingerprint，明确排除 Credential Version、Trace 和可变执行绑定。
• Trace 基线只校验 W3C Version 00 traceparent 并沿用合法 Trace ID 写入 Run/Manifest；远端 Parent Span、Sampling State、跨服务 Span 与 OpenTelemetry Exporter 未写成已完成能力。
• 成功响应冻结为 flat {requestId, runId, status: "reserved", createdAt}；错误冻结为 OpenAI-style nested error、顶层 requestId 与 underscore 稳定错误码。202/reserved 不表示模型执行或结算完成。
• Contracts、API Edge 与 Core 在当日已按上述契约完成设计和实现收敛，但尚未形成固定 Release、独立 CI 与隔离联调的完整证据；这些证据已在 2026-09-04 补齐。该变化仍不代表生产上线，生产公网、Gateway、Outbox Publisher、完整结算与输出均未完成。
• 公网继续默认关闭：API Edge 默认 PUBLIC_ADMISSION_MODE=disabled 且监听回环地址，只有隔离联调显式使用 controlled。多实例分布式限流、客户 IP/细粒度 Scope 策略、完整 W3C/OpenTelemetry 链路和公网压力测试是未来公开切流前置，不写成当前完成能力。下一工程阶段仍是 Outbox Publisher 与 Ops Explorer。

文档站范围收敛

• 文档站正式收敛为“平台架构”和“项目进度”两个分区。
• 删除旧项目的安装、操作手册、后端实现、开源治理、社区支持与历史版本记录。
• 首页、导航、站内搜索、LLM 文档输出和 Sitemap 只暴露 OceanWay 当前架构与进度内容。
• 正式 Host 确认为 docs.oceanway.site；文档变更合入 main 后自动构建、签名并部署不可变镜像到 la-vps2，容器健康失败时恢复上一 Digest。

平台与域名

• oceanway.tech 定位为公共宣传与商业信息入口。
• canvas.oceanway.tech 定位为基于现有项目演进的 OceanWay Studio。
• ai.oceanway.tech 定位为无需登录的公开 Developer Center，只提供模型、文档、公开价格、状态与更新信息。
• console.oceanway.tech 正式作为唯一登录后客户控制平台，Developer Control 合并为 /ai 专业空间。
• api.oceanway.tech/v1 定位为独立机器入口，不接受 Customer Session。
• admin.oceanway.tech 作为 OceanWay 内部管理员与运维控制面。

统一生态

• 个人用户、企业组织和企业成员使用同一身份体系。
• 所有专业平台共享钱包、Project、资产、Canvas、Agent、MCP 与统一 Run 链路。
• 产品数据保持领域归属，共享能力通过稳定资源身份、权限和事件连接，不复制权威数据。

模型与调度

• 网页模型、开发者 API 模型和内部模型采用显式发布面，内部审核、规划或自动评测模型不得自动进入网页调度。
• 正式采用“文本网关池 + 媒体网关池”的同级架构。
• 私有文本基础设施承接文本模型执行；独立媒体网关承接图像与视频模型接入。
• 媒体网关不维护本地用户、客户组、DeveloperCredential、模型广场或用户售价，避免与 OceanWay 客户控制面和商业域冲突。

管理员与运维

• 管理员平台独立承担用户与经营管理、全链路检索、错误定位、日志与 Trace、告警、Incident、对账、审计和受控运维命令。
• 首期复用现有 OceanWay 管理后台代码基座，但逐步迁移为独立 Host Surface 与权限域。
• 任何执行请求必须能够关联业务 Run、计费事件、网关 Attempt、上游错误和最终资产。

当日阶段

• 平台目标架构已完成首轮文档化。
• Phase 0 的 Contracts 0.1 固定版本和 Core Run Admission 基线已经验收；V1 Contracts/API Edge/Core 在当日完成设计与实现收敛，正式制品和跨服务验收证据于 2026-09-04 补齐。
• 当日已固定 API Edge → Outbox/Ops Explorer → Metering/Settlement → Text Gateway canary → Asset → Console/Studio cutover 的工程顺序，且未记录生产部署、Public API 公网切流、Gateway 执行或完整结算完成。