chore: initial public snapshot for github upload

docs/llm_gateway_subapi_evolution_plan_v2_2026-03-17.md

@@ -0,0 +1,305 @@
+# 商用 LLM 通用转发网关演进方案（Subapi First）
+
+- 版本：v2.0（续规划稿）
+- 日期：2026-03-17
+- 基线文档：
+  - `llm_gateway_prd_v0_2026-03-16.md`
+  - `llm_gateway_product_technical_blueprint_v1_2026-03-16.md`
+  - `sub2api_integration_readiness_checklist_2026-03-16.md`
+- 文档目标：在既有 PRD/技术蓝图基础上，明确“先集成 subapi，再逐步替代客户端 subapi，最终形成企业级控制面”的演进路径与边界。
+
+## 1. 本轮续规划目标
+
+围绕你提出的方向，形成四个连续目标：
+
+1. 第一阶段以 `subapi` 作为集成底座，快速形成可售卖能力。
+2. 逐步替代用户端 `subapi` 接入，统一到我方网关入口与控制面。
+3. 后续增强“机器人客户（Bot Customer）”能力，支持自动化运营与客户成功流程。
+4. 增加独立模块：
+   - LLM 供应商账号导入（BYOA/BYOK）
+   - 低成本 LLM 账号获取与治理（仅限合规来源）
+   - 合规与审计增强（ToS、隐私、风控）
+
+## 2. 三种演进路径对比（先决策）
+
+### 路径 A：`subapi` 外部服务模块化（推荐）
+
+1. 做法：
+   - `subapi` 作为独立服务部署在数据面旁路。
+   - 我方网关只通过内部 API 调用 `subapi` 的能力。
+   - 核心账务、租户、权限、审计在我方控制面自研。
+2. 优点：
+   - 集成最快，风险隔离最好，回滚简单。
+   - 可逐步替换，不会一次性重构核心链路。
+3. 缺点：
+   - 双系统运维复杂度增加。
+   - 部分路由决策需跨服务，调优链路更长。
+
+### 路径 B：反向代理链路串联（次选）
+
+1. 做法：我方网关前置，`subapi` 作为后置中转层。
+2. 优点：接入快，早期改造少。
+3. 缺点：链路故障定位复杂，长期可维护性差。
+
+### 路径 C：Fork 深度改造（谨慎）
+
+1. 做法：维护私有 `subapi` 分支并深改为主系统。
+2. 优点：短期控制力强。
+3. 缺点：长期升级成本高，版本漂移和维护负担重。
+
+结论：推荐路径 A，保持“快上线 + 可替换 + 可审计”的平衡。
+
+## 3. 目标架构（控制面优先，数据面渐进替换）
+
+## 3.1 架构原则
+
+1. 控制面主权：租户、计费、权限、审计、合规全部沉淀在我方。
+2. 数据面兼容：北向接口保持 OpenAI/Anthropic/Gemini 兼容，不强推客户改协议。
+3. 双轨演进：短期借力 `subapi`，中期逐步把关键能力迁入自研 Router Core。
+4. 风险前置：把合规和 ToS 校验纳入请求前置策略，而非事后补救。
+
+## 3.2 分层模块
+
+1. Ingress & Compatibility Layer
+   - 统一 `/v1/*` 入口
+   - 客户端兼容适配（历史 subapi 客户端参数映射）
+2. Routing Orchestration Layer
+   - Provider Registry
+   - Policy Engine（预算、白名单、限流、回退）
+   - `subapi connector`（阶段 1-2）
+3. Provider Adapter Layer
+   - OpenAI / Anthropic / Gemini / OpenRouter / 其他国产模型
+   - 统一 usage 与错误标准化
+4. Control Plane
+   - Tenant/RBAC
+   - Billing Ledger（pre-settle-refund）
+   - Audit & Compliance
+   - Provider Account Vault
+5. Bot Customer Layer（后续）
+   - 客户成功机器人
+   - 运维机器人
+   - 成本优化机器人
+
+## 4. 分阶段路线图（以 2026-03-17 为起点）
+
+## 阶段 S1：Subapi 集成上线（2026-03-17 至 2026-05-15）
+
+目标：在 8 周内构建“可售卖 MVP”，验证付费与稳定性。
+
+1. 产品能力
+   - 统一入口 + 基础路由 + fallback
+   - 租户/团队/Key 管理
+   - 预算阈值告警 + 成本归因
+   - 账单导出
+2. 技术动作
+   - 采用路径 A：`subapi` 外部服务模块化接入
+   - 建立 `subapi connector` 与 `adapter registry`
+   - 接入监控基线：错误率、P95、成本突增、熔断次数
+3. Go/No-Go
+   - 灰度 7 天可用性 >= 99.9%
+   - 成本差错率 <= 0.1%
+   - 回滚演练通过（30 分钟内）
+
+## 阶段 S2：替代用户端 subapi（2026-05-16 至 2026-08-15）
+
+目标：将客户“直接用 subapi”的模式迁到“统一用我方网关”。
+
+1. 客户迁移机制
+   - SDK/配置迁移向导（base URL、key、模型映射）
+   - 兼容层保留旧参数与错误码映射
+   - 按租户分批迁移（10%/30%/60%/100%）
+2. 技术动作
+   - 自研 Router Core 接管 >= 60% 主路径请求（全供应商口径）
+   - 国内 LLM 供应商主路径请求由自研 Router Core 接管率 = 100%
+   - `subapi` 仅保留长尾协议或备用回退
+   - 完成 Provider 扩容到至少 6 家可用供应商
+3. 商业目标
+   - 新签客户默认走我方入口，不再直接依赖客户侧 subapi
+   - 迁移客户 30 天留存与成功率不低于迁移前
+
+## 阶段 S3：机器人客户能力（2026-08-16 至 2026-10-31）
+
+目标：把“人肉运维与客户成功”升级为“机器人辅助闭环”。
+
+1. Bot Customer 能力包
+   - 成本优化机器人：给出模型替换建议与预算调优建议
+   - 运维机器人：异常解释、回滚建议、故障摘要
+   - 客户成功机器人：新客户接入引导、健康巡检、续费风险提示
+2. 边界
+   - 机器人只提供建议和自动化执行草案，关键动作仍需审批
+   - 保留审计轨迹（谁触发、依据什么策略、最终执行结果）
+3. 技术依赖
+   - 事件总线与规则引擎
+   - 对话上下文存储
+   - 可观测数据聚合与指标解释层
+
+## 阶段 S4：供应商账号导入 + 低成本账号模块 + 合规增强（2026-11-01 至 2027-03-31）
+
+目标：形成差异化护城河，但严格遵循合规边界。
+
+1. 供应商账号导入（BYOA/BYOK）
+   - 支持客户导入 OpenAI/Anthropic/Gemini/其他账号凭证
+   - Vault 加密存储、轮换、最小权限与可撤销
+   - 账号健康状态、额度状态与风险状态统一可视化
+2. 低成本账号模块（仅合规来源）
+   - 仅允许官方渠道或授权分销渠道
+   - 建立账号来源证明、合同/授权凭证、风控评分
+   - 禁止任何违反上游 ToS 的灰色接入方式
+3. 合规增强
+   - ToS Policy Engine：按供应商、区域、模型动态拦截
+   - 数据与隐私策略：PII 脱敏、日志保留策略、跨境策略
+   - 审计报表：面向法务/安全/财务的统一合规报表
+
+## 5. 核心模块设计补充（本轮新增）
+
+## 5.1 Provider Account Vault
+
+1. 凭证存储：KMS + 字段级加密 + 审计日志。
+2. 生命周期：导入、校验、轮换、停用、吊销。
+3. 访问控制：仅策略引擎短时解密，禁止控制台明文展示。
+
+## 5.2 ToS & Compliance Engine
+
+1. 规则维度：供应商条款、区域限制、模型限制、使用场景限制。
+2. 执行位置：请求前置硬拦截 + 请求后审计与告警。
+3. 输出：
+   - 合规判定结果
+   - 拦截原因码
+   - 审计证据链
+
+## 5.3 Bot Customer Orchestrator
+
+1. 事件输入：预算超阈值、错误率突增、客户健康分下降。
+2. 决策输出：建议动作（降级模型、加权切换、限流、回滚）。
+3. 安全机制：高风险动作必须人工审批。
+
+## 6. 指标与验收（续规划版）
+
+## 6.1 产品与商业指标
+
+1. 从“客户侧 subapi”迁移到“我方网关入口”的迁移完成率。
+2. 单客户月度受管成本（GMV）与毛利率。
+3. 预算超限前告警命中率与执行闭环率。
+
+## 6.2 技术与稳定性指标
+
+1. 网关附加时延 P95（不含上游推理） <= 60ms。
+2. 请求可追踪率（request_id 全链路覆盖） = 100%。
+3. 账务差错率 <= 0.1%，并可追溯到请求级。
+4. S2 结束时主路径接管率（全供应商） >= 60%。
+5. S2 结束时国内 LLM 供应商主路径接管率 = 100%。
+
+## 6.3 合规与风控指标
+
+1. 高风险策略误放行率接近 0（以红线规则为硬约束）。
+2. 供应商 ToS 规则覆盖率（已接入供应商） = 100%。
+3. 关键管理操作审计覆盖率 = 100%。
+
+## 7. 风险与应对（针对本轮新增能力）
+
+1. 低成本账号模块的法律风险
+   - 应对：只做合规来源，法务前置审批，建立可审计证据链。
+2. 机器人误触发导致运营事故
+   - 应对：高风险动作审批制 + 演练 + 回滚预案。
+3. 迁移期间双轨链路复杂度上升
+   - 应对：按租户灰度、双写观测、阶段性去耦目标明确。
+4. `subapi` 快速迭代导致兼容性回归
+   - 应对：版本锁定 + 契约测试 + 周级升级窗口 + 自动回滚。
+
+## 8. 本周可执行动作（2026-03-17 当周）
+
+1. 冻结 S1 范围和不做清单（避免范围膨胀）。
+2. 明确 `subapi connector` 契约：
+   - 请求标准化字段
+   - usage 对账字段
+   - 错误码映射表
+   - 契约文档：`subapi_connector_contract_v1_2026-03-17.md`
+3. 建立迁移基线文档：
+   - 客户侧 subapi -> 我方网关 的迁移手册 v0
+4. 和法务定义 S4 的“低成本账号模块”红线条款模板。
+
+## 9. 已拍板决策（2026-03-17）
+
+1. 采用路径 A：`subapi` 外部服务模块化。
+2. S2 结束时：自研 Router Core 主路径接管率（全供应商） >= 60%。
+3. S2 结束时：国内 LLM 供应商主路径接管率 = 100%。
+
+## 10. 待拍板的 4 个决策
+
+1. S3 机器人能力优先顺序（成本优化优先 or 运维优先）。
+2. S4 是否把“低成本账号模块”作为独立付费包。
+3. 合规策略默认是“严格拦截”还是“告警+人工复核”。
+4. 迁移节奏是“行业试点优先”还是“全客户统一批次”。
+
+## 11. `subapi` 快速迭代集成保障机制（新增）
+
+1. 版本治理
+   - 生产环境固定 `subapi` 次版本（例如 `vX.Y.*` 锁定为 `vX.Y.Z`）。
+   - 仅在周级升级窗口内升级，不做临时线上直升。
+2. 契约治理
+   - 建立 `subapi connector` 契约测试集（请求字段、错误码、usage、流式行为）。
+   - 每次升级必须通过“兼容矩阵”后才允许灰度。
+3. 发布治理
+   - 灰度比例：5% -> 20% -> 50% -> 100%。
+   - 每阶段观察至少 2 小时关键指标（5xx、P95、token 成本偏差、fallback 比例）。
+4. 回滚治理
+   - 保留上一稳定版本镜像和配置快照。
+   - 任一红线触发（错误率、延迟、成本偏差）立即自动回滚到上一稳定版本。
+5. 变更治理
+   - 每周固定一次上游变更扫描（Release/Commit/Breaking Change）。
+   - 对潜在破坏性变更创建“影响单”，先评估再排期升级。
+
+## 12. S2 执行基线文档（新增）
+
+为落实你已确认的 S2 目标（全供应商 `>=60%`、国内供应商 `100%`），新增执行层文档：
+
+- `router_core_takeover_execution_plan_v3_2026-03-17.md`
+
+该文档补齐了三类执行要素：
+
+1. 接管率统一口径与计算公式（避免统计歧义）
+2. 模块拆分 + 迁移优先级 + 批次节奏
+3. 可验收测试矩阵与阶段门槛（质量/账务/接管率）
+
+## 13. S2 执行附件（新增）
+
+在 S2 阶段，除执行基线文档外，补充两份落地附件：
+
+1. `router_core_takeover_metrics_sql_dashboard_v1_2026-03-17.md`
+   - 定义接管率统计 SQL 与看板口径（overall/cn）。
+2. `router_core_s2_acceptance_test_cases_v1_2026-03-17.md`
+   - 按模块展开验收测试清单与分波次门禁。
+
+## 14. 兼容性、安全与运维可靠性设计附件（新增）
+
+为回应“subapi 快速迭代 + 商用集成”的实施风险，补充设计文档：
+
+1. `subapi_integration_compat_security_reliability_design_v1_2026-03-17.md`
+   - 定义兼容闸门、风险分级、强制配置硬化基线与运维可靠性机制。
+
+## 15. 风险控制执行任务单（新增）
+
+为避免“设计有了但执行失焦”，补充两周执行任务单：
+
+1. `subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md`
+   - 以绝对日期管理实施节奏（2026-03-18 至 2026-03-31）
+   - 绑定责任角色、验收标准和证据产物
+   - 纳入 daily/weekly gate 与回滚演练要求
+
+## 16. 专家审核与博弈机制（新增）
+
+为避免实施过程出现“团队内共识偏差”，补充独立专家审核机制：
+
+1. `subapi_expert_review_wargame_plan_v1_2026-03-17.md`
+   - 明确专家构成与独立性约束（含安全/合规一票否决）
+   - 通过对抗式评审验证集成可行性、替换路径可行性与商用可靠性
+   - 输出 GO / CONDITIONAL GO / NO-GO 结论与整改闭环
+
+## 17. 三角色联合评审与优化（新增，2026-03-18）
+
+为进一步降低实施期“用户体验断层、质量门禁失效、网关替换不可逆”风险，新增：
+
+1. `subapi_role_based_review_wargame_optimization_v1_2026-03-18.md`
+   - 角色范围：用户代表、测试专家、网关专家
+   - 输出三角色 Red/Blue 博弈结论与条件放行门槛
+   - 绑定新增任务：`UXR-001/002`、`TST-001/002/003`、`GAT-001/002/003`、`EXP-007`