@jsonstudio/rcc 0.89.1803 → 0.89.1959

package/docs/v2-architecture/PROVIDER-V2-PHASED-MIGRATION-ROLLBACK-DRAFT.md

@@ -0,0 +1,164 @@
+# Provider V2 分阶段迁移与回滚方案（Draft）
+
+- Status: Draft
+- Date: 2026-02-09
+- Owner: routecodex-113.4
+- Strategy: 新实现主路径 + 旧实现影子路径；验证通过后移除旧实现
+
+## 1. 迁移总原则（已确认）
+
+本次 Provider 重构采用以下固定策略：
+
+1. 对每个替换点，**新实现先成为主路径**。
+2. 原实现保留为影子路径（shadow），并行执行只用于比对，不参与主响应。
+3. 当测试与 replay 指标达标后，移除原实现。
+
+> 该策略与“先实现、不连线”并不冲突：先完成可调用实现；进入连线阶段时采用“新主旧影子”的切换方式。
+
+## 2. 影子模式定义
+
+### 2.1 主路径（new-primary）
+
+- 用户请求只返回新实现结果。
+- 失败直接按 fail-fast 上报，不静默回落旧实现。
+
+### 2.2 影子路径（legacy-shadow）
+
+- 同 shape 输入驱动旧实现并记录输出。
+- 不影响主请求响应。
+- 仅记录：关键字段、错误类型、耗时、shape diff。
+
+### 2.3 比对维度
+
+- Request shape：endpoint、headers 关键字段、body 关键字段。
+- Response shape：status、error envelope、核心 data path。
+- Error classification：`statusCode / code / upstreamCode`。
+- 性能：P50/P95 latency 增量。
+
+## 3. 分阶段与 Gate
+
+## Phase 0（设计冻结）
+
+- 输入：`113.1/113.2/113.3` 草案已通过。
+- 产出：替换点清单 + 每点 shadow 观测字段。
+
+### Entry Gate
+
+- ADR 决策冻结。
+- 迁移矩阵完整（Mxx 对应关系清晰）。
+
+### Exit Gate
+
+- 每个 Mxx 指定 owner、wave、回滚键。
+
+## Phase 1（实现不连线）
+
+- 新增 kernel/protocol/profile 模块，但不接入主执行流。
+- 增加模块级单测与样本对比。
+
+### Entry Gate
+
+- 模块接口与 registry 契约稳定。
+
+### Exit Gate
+
+- 单测通过。
+- `npx tsc --noEmit` 通过。
+- 不影响现网路径（零行为变化）。
+
+## Phase 2（新主旧影子切换）
+
+- 按 wave 逐批连线（Wave-1 iflow -> Wave-2 antigravity/gemini-cli -> Wave-3 清理层）。
+- 连线后新实现主路径生效，旧实现影子并行观测。
+
+### Entry Gate
+
+- 该 wave 对应实现与测试准备完成。
+- shadow 观测点已接入日志/快照。
+
+### Exit Gate（每个 wave 必须全部满足）
+
+1. 构建验证通过：
+   - `npm run build:dev`
+   - `npm run install:global`
+2. 类型与单测通过：
+   - `npx tsc --noEmit`
+   - 该 wave 相关测试集全绿
+3. 回放验证通过：
+   - 至少一组 same-shape replay（目标 provider）
+   - 至少一组 control replay（不受影响 provider）
+4. shadow 比对达标：
+   - 无 P0/P1 shape diff
+   - 关键错误分类一致率达标（建议 >= 99%）
+
+## Phase 3（移除旧实现）
+
+- 在 wave exit gate 连续达标后，删除对应 legacy 代码路径。
+- 删除后执行全量回归与 replay。
+
+### Entry Gate
+
+- 连续 N 次（建议 3 次）回放稳定。
+- 无新增高优先级缺陷。
+
+### Exit Gate
+
+- 旧实现路径删除完成。
+- 文档与测试更新完成。
+- `bd` 任务附证据后关闭。
+
+## 4. 回滚策略
+
+## 4.1 回滚触发条件
+
+任一条件满足即回滚该 wave：
+
+- 新主路径出现 P0/P1 功能偏差。
+- 关键 provider 出现不可接受错误激增（例如 4xx/5xx 激增）。
+- same-shape 或 control replay 失败。
+
+## 4.2 回滚动作
+
+1. 停止该 wave 的继续连线。
+2. 切回旧实现主路径（保留新实现为影子，定位差异）。
+3. 保留失败证据（requestId/providerKey/route/model/before-after diff）。
+4. 修复后重新走该 wave gate，不跨级推进。
+
+## 4.3 回滚粒度
+
+- 以 wave 为最小回滚单位。
+- wave 内可按 provider family 子单元回滚（例如仅回滚 iflow）。
+
+## 5. Wave 拆分建议
+
+### Wave-1（iflow）
+
+- 包含 M01~M07 + M18(iflow)。
+- 核心目标：iflowWebSearch 去重、UA/signature、business envelope 归一。
+
+### Wave-2（antigravity/gemini-cli）
+
+- 包含 M09/M10/M12/M14/M17。
+- 核心目标：fallback/error wrapping/header policy 下沉。
+
+### Wave-3（协议/工厂/目录清理）
+
+- 包含 M11/M13/M15/M16。
+- 核心目标：protocol adapter 定型、factory 仅装配、目录映射单一事实源。
+
+## 6. 证据模板（任务关闭必填）
+
+每个 wave 的 BD 关闭 notes 至少包含：
+
+- 构建/类型/测试命令与结果。
+- same-shape replay 证据（requestId、providerKey、model、route）。
+- control replay 证据（不受影响 provider）。
+- shadow 比对摘要（diff 数、严重级别、结论）。
+- 回滚演练结果（如有）。
+
+## 7. 执行纪律
+
+- 不允许同时连线多个高风险 family。
+- 不允许在未达 gate 时删除旧实现。
+- 不允许把 compat 逻辑迁入 provider transport。
+

package/docs/v2-architecture/PROVIDER-V2-PROFILE-API-REGISTRY-DRAFT.md

@@ -0,0 +1,201 @@
+# Provider V2 Profile API 与 Registry 机制（Draft）
+
+- Status: Draft
+- Date: 2026-02-09
+- Owner: routecodex-113.3
+- Strategy: 先实现各层模块，不连线；按 Wave 批次接线
+
+## 1. 目标与输入约束
+
+本草案定义 Provider 分层中 `Profile` 的抽象契约与注册解析机制，遵循已确认决策：
+
+- 配置显式字段 `providerProtocol + providerId + compatibilityProfile` 决定协议、品牌分支与 compat。
+- `providerId / providerFamily` 单一事实来源来自“配置文件 + provider 目录映射”。
+- Gemini CLI 长期作为 Gemini 协议变体。
+
+## 2. 当前代码的结构约束（作为设计边界）
+
+- 已存在声明式 profile 输入：`src/providers/profile/provider-profile.ts`。
+- 已存在配置装载器：`src/providers/profile/provider-profile-loader.ts`。
+- 已存在 runtime metadata 承载 `providerProtocol/providerFamily/compatibilityProfile`：`src/providers/core/runtime/provider-runtime-metadata.ts`。
+- 当前 transport 内仍有大量品牌分支（iflow/antigravity 等），需要迁移到 family profile：`src/providers/core/runtime/http-transport-provider.ts`、`src/providers/core/runtime/http-request-executor.ts`。
+
+## 3. 抽象契约（API 草案）
+
+> 下列接口为目标 API；本阶段只定义，不替换现网调用。
+
+### 3.1 标识与解析结果
+
+```ts
+type ProtocolId =
+  | 'openai-chat'
+  | 'openai-responses'
+  | 'anthropic-messages'
+  | 'gemini-chat';
+
+interface ProviderDirectoryEntry {
+  providerId: string;
+  providerFamily: string;
+  allowedProtocols: ProtocolId[];
+  defaultModuleType?: string;
+  defaultProfileId: string;
+}
+
+interface ResolvedProviderBinding {
+  providerId: string;
+  providerFamily: string;
+  providerProtocol: ProtocolId;
+  profileId: string;
+  compatibilityProfile: string;
+  moduleType?: string;
+}
+```
+
+### 3.2 Profile 能力接口
+
+```ts
+interface RequestPolicyInput {
+  endpoint: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+  runtime: ProviderRuntimeMetadata;
+}
+
+interface ResponsePolicyInput {
+  response: unknown;
+  runtime: ProviderRuntimeMetadata;
+}
+
+interface ErrorPolicyInput {
+  error: unknown;
+  runtime: ProviderRuntimeMetadata;
+}
+
+interface ProviderFamilyProfile {
+  id: string;            // e.g. 'iflow/default'
+  providerFamily: string;
+
+  applyRequestPolicy?(input: RequestPolicyInput): RequestPolicyInput;
+  applyResponsePolicy?(input: ResponsePolicyInput): ResponsePolicyInput;
+  mapError?(input: ErrorPolicyInput): ProviderErrorAugmented;
+}
+```
+
+### 3.3 Registry 契约
+
+```ts
+interface ProviderProfileRegistry {
+  register(entry: ProviderDirectoryEntry, profile: ProviderFamilyProfile): void;
+  resolve(binding: {
+    providerProtocol: string;
+    providerId: string;
+    compatibilityProfile: string;
+    moduleType?: string;
+  }): ResolvedProviderBinding;
+  getProfile(profileId: string): ProviderFamilyProfile;
+}
+```
+
+## 4. 解析顺序（已定稿）
+
+解析顺序必须固定并可审计：
+
+1. 读取配置中的 `providerProtocol`，映射到唯一 `ProtocolId`。
+2. 读取配置中的 `providerId`，通过 provider-directory 映射得到 `providerFamily` 与 `defaultProfileId`。
+3. 读取配置中的 `compatibilityProfile`，写入 `ResolvedProviderBinding`（供 llmswitch-core compat 阶段使用）。
+4. 若任一字段缺失/非法/冲突，直接 fail-fast。
+
+### 4.1 重要边界
+
+- Provider 层只“解析并透传” `compatibilityProfile`，不在 transport 内执行 compat 语义。
+- compat 的实际转换仍由 llmswitch-core 负责（保持 AGENTS 既有边界）。
+- Factory 仅负责组装 runtime 依赖，不负责 profile 解析与实例化。
+- Registry resolver 仅做 binding 解析；profile 实例由预注册集合提供，禁止在 resolver/factory 内临时 `new` profile。
+
+## 5. Protocol 与 Profile 的交互边界
+
+### 5.1 Protocol 层负责
+
+- wire shape（endpoint/body/stream）
+- 协议级 response parse
+- 协议字段合法性
+
+### 5.2 Family Profile 层负责
+
+- 品牌级 header 策略（UA、签名、清理）
+- 品牌级 request 微调（字段注入/裁剪）
+- 品牌级 error envelope 映射
+
+### 5.3 明确禁止
+
+- Profile 禁止发 HTTP、禁止路由决策、禁止工具语义改写。
+- Protocol 禁止品牌识别分支。
+
+## 6. 向后兼容策略（迁移期间）
+
+### 6.1 Legacy 兼容输入
+
+现有配置仍可能仅给 `providerType/type`（无显式 `providerProtocol`）。迁移期策略：
+
+1. 在配置加载阶段做一次性 legacy 归一（alias -> protocol/providerId）。
+2. 归一后输出“显式三元组”：`providerProtocol + providerId + compatibilityProfile`。
+3. 运行时仅消费归一结果，不再做二次猜测。
+
+### 6.2 兼容期约束
+
+- 兼容归一逻辑只存在于配置加载层（single source of truth）。
+- Provider runtime / transport 中不得新增 legacy 推断。
+
+## 7. 最小可行目录结构（MVP）
+
+```text
+src/providers/
+  profile/
+    provider-directory.ts            # providerId -> providerFamily/protocol constraints
+    profile-contracts.ts             # ProviderFamilyProfile interfaces
+    profile-registry.ts              # register/resolve/getProfile
+    families/
+      iflow/default-profile.ts
+      antigravity/default-profile.ts
+      qwen/default-profile.ts
+      gemini/default-profile.ts
+  core/
+    protocols/
+      openai-chat/adapter.ts
+      openai-responses/adapter.ts
+      anthropic-messages/adapter.ts
+      gemini-chat/adapter.ts
+```
+
+## 8. 先实现不连线：可执行落地清单
+
+### Step A（仅实现）
+
+- 新增 `provider-directory.ts` + `profile-registry.ts`。
+- 新增 `profile-contracts.ts`。
+- 为 iflow/antigravity 提供最小 default profile（空实现 + 单测）。
+
+### Step B（仅验证）
+
+- 增加 registry 解析测试：字段缺失/冲突/非法协议 fail-fast。
+- 增加 profile policy 单测：请求头策略和错误映射逻辑纯函数测试。
+
+### Step C（仍不连线）
+
+- 在 factory/transport 增加“旁路可调用”探针（仅日志/快照，不接入主执行流）。
+
+## 9. 风险与防护
+
+1. **风险：Registry 成为第二个 factory**
+   - 防护：registry 只做解析，不做实例化。
+2. **风险：compat 再次下沉到 provider**
+   - 防护：compatibilityProfile 仅透传，不在 profile 中执行。
+3. **风险：legacy 兼容逻辑散落**
+   - 防护：只允许配置加载层存在 alias 归一。
+
+## 10. 113.3 验收对应关系
+
+- Profile 接口：见第 3 节。
+- Protocol/Profile 边界：见第 5 节。
+- 向后兼容：见第 6 节。
+- 最小目录结构：见第 7 节。

package/docs/v2-architecture/PROVIDER-V2-PROFILE-GEMINI-DRAFT.md

@@ -0,0 +1,56 @@
+---
+# Provider V2 Profile: Gemini Protocol + Family
+
+> 目标：将 `gemini-http-provider` 与 `gemini-cli-http-provider` 中的品牌特判迁移到 Kernel → Protocol → Profile 三层架构。
+
+## 现状盘点
+
+| 当前特判 | 位置 | 应属层级 | 备注 |
+|---------|------|----------|------|
+| OpenAI Chat → Gemini contents 形状转换 | `gemini-http-provider.ts:preprocessRequest` | Protocol (gemini-chat) | 协议层字段映射 |
+| systemInstruction 提取与合并 | `gemini-http-provider.ts:preprocessRequest` | Protocol (gemini-chat) | 同上 |
+| x-goog-api-key 认证头处理 | `gemini-http-provider.ts:finalizeRequestHeaders` | Protocol (gemini-chat) | 协议层认证规范 |
+| Authorization: Bearer → x-goog-api-key 转换 | `gemini-http-provider.ts` | Protocol (gemini-chat) | 同上 |
+| generationConfig 构建 | `gemini-http-provider.ts:buildGenerationConfig` | Protocol (gemini-chat) | 字段映射 |
+| Antigravity runtime 检测 | `gemini-http-provider.ts` | Family Profile (antigravity) | 品牌特有运行时 |
+| Antigravity session/signature 头注入 | `gemini-http-provider.ts:applyAntigravityRequestCompat` | Family Profile (antigravity) | 同上 |
+| Antigravity 错误包装 (wrapAntigravityHttpErrorAsResponse) | `gemini-http-provider.ts:sendRequestInternal` | Family Profile (antigravity) | 错误处理策略 |
+| Gemini CLI user-agent 处理 | `gemini-cli-http-provider.ts` | Family Profile (gemini-cli) | CLI 特有头策略 |
+| Gemini empty-reply-continue servertool | `gemini-empty-reply-continue.ts` | Protocol (gemini-chat) | 协议层空回复处理 |
+
+## 迁移策略
+
+### Phase 1: Protocol 层 `gemini-chat`
+
+新建 `src/providers/profile/protocols/gemini-chat-protocol.ts`：
+- 实现 `ProtocolAdapter` 接口
+- 提供 `toProtocolPayload(openaiChat)` → `geminiContents`
+- 提供 `fromProtocolResponse(geminiResponse)` → `openaiChat`
+- 认证头标准化：`x-goog-api-key`
+
+### Phase 2: Family Profile `antigravity`
+
+新建 `src/providers/profile/families/antigravity-profile.ts`：
+- 继承 `gemini-chat` protocol
+- 注入 antigravity 特有头：`x-antigravity-session`, `x-antigravity-signature`
+- 错误处理：识别 antigravity 特有错误码并包装
+
+### Phase 3: 影子实现验证
+
+1. 保留现有 `gemini-http-provider` 作为影子
+2. 新实现走 `http-transport-provider` + profile 路径
+3. 对比测试通过后再移除旧实现
+
+## BD 任务拆分
+
+- routecodex-113.10: Gemini Protocol Adapter 设计与实现
+- routecodex-113.11: Antigravity Family Profile 迁移
+- routecodex-113.12: Gemini CLI Profile 对齐
+- routecodex-113.13: 影子实现与对比验证
+
+## 验收标准
+
+- [ ] same-shape replay: Gemini 原生请求前后一致
+- [ ] control replay: OpenAI Chat 请求不受影响
+- [ ] antigravity 特有功能（session/signature）正常
+- [ ] 无回归：现有 Gemini 相关测试通过

package/docs/v2-architecture/PROVIDER-V2-REFACTOR-OVERVIEW-DRAFT.md

@@ -0,0 +1,102 @@
+# Provider V2 重构总览（Draft）
+
+- Status: Draft
+- Date: 2026-02-09
+- Epic: routecodex-113
+- Working Mode: 先实现、不连线；连线时采用“新主旧影子”，通过 gate 后移除旧实现
+
+## 1) 已冻结决策
+
+1. 分层固定为：`Kernel -> 4 Protocol -> Family Profile`
+2. 四协议固定为：
+   - openai-chat
+   - openai-responses
+   - anthropic-messages
+   - gemini-chat（Gemini CLI 作为 Gemini 协议变体长期保留）
+3. 配置显式字段 `providerProtocol + providerId + compatibilityProfile` 决定：
+   - Protocol Adapter
+   - Family Profile
+   - Compat Profile
+4. `providerId/providerFamily` 的单一事实来源：配置文件 + provider 目录映射。
+
+## 2) 子任务产出总览
+
+- `routecodex-113.1`：分层 ADR 草案
+  - `docs/v2-architecture/PROVIDER-V2-LAYERING-ADR-DRAFT.md`
+- `routecodex-113.2`：特判盘点与迁移矩阵
+  - `docs/v2-architecture/PROVIDER-V2-MIGRATION-MATRIX-DRAFT.md`
+- `routecodex-113.3`：Profile API 与 Registry 机制
+  - `docs/v2-architecture/PROVIDER-V2-PROFILE-API-REGISTRY-DRAFT.md`
+- `routecodex-113.4`：分阶段迁移与回滚
+  - `docs/v2-architecture/PROVIDER-V2-PHASED-MIGRATION-ROLLBACK-DRAFT.md`
+- `routecodex-113.5`：验证矩阵与 Replay 模板
+  - `docs/v2-architecture/PROVIDER-V2-VERIFICATION-MATRIX-DRAFT.md`
+
+## 3) 执行顺序（建议）
+
+## Phase A：实现不连线
+
+- 新建 profile contracts / registry / provider-directory
+- 新建 family profiles（iflow、antigravity、qwen、gemini）
+- 新建 protocol adapters（4 协议）
+- 只加单测，不改主路径
+
+## Phase B：分 wave 连线（新主旧影子）
+
+- Wave-1：iflow
+- Wave-2：antigravity / gemini-cli
+- Wave-3：protocol/factory/service-profile/provider-type 清理
+
+## Phase C：旧实现移除
+
+- 每个 wave 连续达标后删除对应 legacy 路径
+- 删除后重新跑 build/install/tsc/replay
+
+## 4) Gate（摘要）
+
+每个 wave 的退出 gate 必须包含：
+
+- `npm run build:dev`
+- `npm run install:global`
+- `npx tsc --noEmit`
+- wave 目标测试集
+- same-shape replay（目标 provider）
+- control replay（未受影响 provider）
+- shadow diff 指标达标（P0/P1 diff=0）
+
+## 5) 回滚规则（摘要）
+
+触发条件（任一）：
+
+- P0/P1 功能偏差
+- 错误率异常升高
+- same-shape/control replay 失败
+
+回滚动作：
+
+- 回切到旧主路径
+- 新实现保留影子继续对比
+- 修复后重走该 wave gate
+
+## 6) 当前建议提交范围（仅架构草案）
+
+可提交：
+
+- `.beads/issues.jsonl`
+- `docs/v2-architecture/PROVIDER-V2-REFACTOR-OVERVIEW-DRAFT.md`
+- `docs/v2-architecture/PROVIDER-V2-LAYERING-ADR-DRAFT.md`
+- `docs/v2-architecture/PROVIDER-V2-MIGRATION-MATRIX-DRAFT.md`
+- `docs/v2-architecture/PROVIDER-V2-PROFILE-API-REGISTRY-DRAFT.md`
+- `docs/v2-architecture/PROVIDER-V2-PHASED-MIGRATION-ROLLBACK-DRAFT.md`
+- `docs/v2-architecture/PROVIDER-V2-VERIFICATION-MATRIX-DRAFT.md`
+
+建议暂不纳入本次（与架构草案无关/另案处理）：
+
+- `AGENTS.md`
+- `package.json`
+- `package-lock.json`
+- `src/build-info.ts`
+- `src/commands/validate.ts`
+- `src/providers/core/runtime/http-transport-provider.ts`
+- `tests/providers/core/runtime/http-transport-provider.headers.test.ts`
+

package/docs/v2-architecture/PROVIDER-V2-VERIFICATION-MATRIX-DRAFT.md

@@ -0,0 +1,163 @@
+# Provider V2 验证矩阵与 Replay 验收模板（Draft）
+
+- Status: Draft
+- Date: 2026-02-09
+- Owner: routecodex-113.5
+- Scope: 用于 Wave 连线与旧实现移除前的统一验证标准
+
+## 1. Mandatory 验证项（每次 Wave 必跑）
+
+1. 构建与安装
+   - `npm run build:dev`
+   - `npm run install:global`
+2. 类型检查
+   - `npx tsc --noEmit`
+3. 目标改动测试
+   - 运行该 Wave 关联的 provider / routing / pipeline 测试集
+4. Replay 验证
+   - same-shape replay（受影响 provider）至少 1 组
+   - control replay（未受影响 provider）至少 1 组
+5. Shadow 对比
+   - 新主路径 vs 旧影子输出差异比对
+
+## 2. Four-Protocol × Family 验证矩阵
+
+> 说明：矩阵是“至少覆盖”；某 Wave 可聚焦子集，但必须包含对应 control 列。
+
+| Protocol | 受影响 Family（示例） | Same-shape 必测 | Control 必测 | Mandatory 指标 |
+|---|---|---|---|---|
+| openai-chat | iflow / qwen / glm / lmstudio | 1+ 样本（目标 family） | 1+ 样本（openai 或未改 family） | shape 一致、错误分类一致、无新增 P0/P1 |
+| openai-responses | iflow / openai / 其他 responses 路由 | 1+ 样本（目标 family） | 1+ 样本（responses 其他 family） | SSE/JSON 结构一致、工具回合一致 |
+| anthropic-messages | anthropic / 兼容代理 | 1+ 样本（目标 family） | 1+ 样本（anthropic control） | tool alias / message shape 一致 |
+| gemini-chat | gemini / gemini-cli / antigravity | 1+ 样本（目标 family） | 1+ 样本（gemini family control） | header policy 与错误映射一致 |
+
+## 3. Same-shape Replay 模板
+
+### 3.1 目标
+
+验证“同一输入 shape 下，新主路径结果与旧影子可比”，并确保主链路正确。
+
+### 3.2 命令模板
+
+```bash
+npm run replay:codex-sample -- \
+  --sample <path-to-client-request.json> \
+  --label wave-<n>-same-shape
+```
+
+脚本就绪状态（2026-02-09）：`package.json` 已存在 `replay:codex-sample -> node scripts/replay-codex-sample.mjs`。
+若后续脚本不可用，需在 `routecodex-113.5` 新增“replay script readiness”子任务后再推进 wave gate。
+
+### 3.3 证据最小字段
+
+- requestId
+- providerKey / runtimeKey
+- providerProtocol
+- routeName
+- model（clientModelId / assignedModelId）
+- 结果类型（JSON / SSE）
+- 关键字段对比结论（pass/fail）
+
+## 4. Control Replay 模板
+
+### 4.1 目标
+
+验证“未受影响 provider 不回归”。
+
+### 4.2 选择原则
+
+- 与目标 Wave 不同 family。
+- 同协议优先（若有），跨协议可作为补充。
+
+### 4.3 命令模板
+
+```bash
+npm run replay:codex-sample -- \
+  --sample <path-to-control-client-request.json> \
+  --label wave-<n>-control
+```
+
+### 4.4 证据最小字段
+
+- requestId
+- providerKey
+- providerProtocol
+- 关键响应 shape 结论
+- 错误分类是否与基线一致
+
+## 5. Shadow Diff 验证模板
+
+### 5.1 必比字段
+
+- endpoint
+- header 关键键（UA、签名、protocol 相关头）
+- body 关键键（messages/tools/stream/metadata）
+- response.status / error.code / upstreamCode
+
+### 5.2 通过阈值（建议默认）
+
+- P0/P1 差异：0
+- 关键错误分类一致率：>= 99%
+- 性能增量：P95 不超过基线 +10%（或明确备案）
+
+## 6. Wave 退出 Gate Checklist（可复制）
+
+```markdown
+## Wave-<n> Exit Gate
+- [ ] npm run build:dev
+- [ ] npm run install:global
+- [ ] npx tsc --noEmit
+- [ ] Targeted tests passed
+- [ ] Same-shape replay evidence attached
+- [ ] Control replay evidence attached
+- [ ] Shadow diff metrics attached
+- [ ] No P0/P1 regression
+```
+
+## 7. BD 关闭任务证据模板（可复制）
+
+```markdown
+## Verification Summary
+- Wave: <wave-id>
+- Scope: <families/protocols>
+- Date: <YYYY-MM-DD>
+
+## Build / Type / Test
+- build:dev: <pass/fail>
+- install:global: <pass/fail>
+- tsc --noEmit: <pass/fail>
+- targeted tests: <list>
+
+## Same-shape Replay
+- requestId: <id>
+- providerKey: <key>
+- providerProtocol: <protocol>
+- model/route: <model>/<route>
+- result: <pass/fail>
+- evidence path: <runs/...>
+
+## Control Replay
+- requestId: <id>
+- providerKey: <key>
+- providerProtocol: <protocol>
+- result: <pass/fail>
+- evidence path: <runs/...>
+
+## Shadow Diff
+- compared fields: <list>
+- P0/P1 diffs: <count>
+- error-classification match: <percent>
+- performance delta (P95): <value>
+
+## Decision
+- gate: <pass/fail>
+- rollback required: <yes/no>
+- notes: <details>
+```
+
+## 8. 与前序文档对齐关系
+
+- 分层与决策来源：`docs/v2-architecture/PROVIDER-V2-LAYERING-ADR-DRAFT.md`
+- 特判迁移清单：`docs/v2-architecture/PROVIDER-V2-MIGRATION-MATRIX-DRAFT.md`
+- 分阶段与回滚：`docs/v2-architecture/PROVIDER-V2-PHASED-MIGRATION-ROLLBACK-DRAFT.md`
+