niuniu/sub2api-cn-relay-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
82f3636521c49162ba19c9299de3917c452609c9
sub2api-cn-relay-manager/docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md
phamnazage-jpg 361a93270f docs(routing): capture phase1 foundation plan
2026-05-28 15:37:13 +08:00

11 KiB
Raw Blame History

插件整体需求梳理（2026-05-28）

日期：2026-05-28

背景

sub2api-cn-relay-manager 的最初定位，是一个不修改宿主源码的外部控制面：

  • 通过宿主 HTTP 管理 API 导入 provider / account / group / plan
  • 维护状态库
  • 做访问闭环验证
  • 提供最小管理页

随着新需求增加，当前插件目标已经从“导入控制面”扩展为一个更完整的模型供应管理 + 逻辑分组 + 前置路由 + 用户前端聚合层。

因此这里需要重新把插件职责收口，并明确区分：

  • 已完成：已经有真实代码与真实部署/验收支撑
  • 待优化：能力已存在，但还不够产品化或还不够顺手
  • 待完成：已经明确要做，但当前还没有真正落地
  • 未来规划：方向已确认，但不应假装已经进入当前交付范围

当前插件职责总图

按现在的产品边界，插件最终应覆盖 5 大功能域：

  1. 增加模型
  2. 维护逻辑分组
  3. 智能路由
  4. 供应商帐号导入与停启用
  5. 普通用户前端

这 5 个功能域里，当前真正成熟的是：

  • 模型与 provider 管理控制面
  • provider 草稿发布到 pack 仓库
  • 供应商帐号导入与 access closure
  • 最小管理员前端

而“逻辑分组 + 智能路由 + 面向普通用户的统一产品层”是本轮新增后的主线。

一、增加模型

这里的“增加模型”，当前真实语义不是直接往宿主里加一个模型开关，而是：

  • 在 pack/provider 体系里新增或更新 provider manifest
  • 定义其 provider_id / display_name / base_url / supported_models / smoke_test_model
  • 再由插件导入供应商 key，把这条 provider 变成真实可访问线路

已完成

  • 已有 providers.html 管理页，可浏览 pack/provider 目录
  • 已有 provider manifest 草稿能力：
    • POST /api/provider-drafts
    • GET /api/provider-drafts
    • GET /api/provider-drafts/{draft_id}
    • PUT /api/provider-drafts/{draft_id}
    • DELETE /api/provider-drafts/{draft_id}
  • 已有 provider 草稿发布能力：
    • POST /api/provider-drafts/{draft_id}/publish
  • 发布时已可自动：
    • 写 packs/<pack>/providers/*.json
    • bump pack.json patch version
    • 更新 checksums.txt
    • 重跑 pack 校验
    • git add + git commit
  • Provider Manifest 草稿 已做过一轮可用性优化：
    • 最近成功模板回填
    • Provider ID 自动生成与避重
    • 前端同模型冲突提示
    • 服务端 save draft / publish 模型冲突校验

待优化

  • 草稿表单虽然能用，但仍偏“manifest 视角”，不是“运营录入视角”
  • providers.html 还缺更强的“已有模板复用 / 最近一次导入参考 / 同类线路推荐”
  • “新增模型”与“导入供应商帐号”虽然已经在同页，但产品语义仍然容易混淆
  • route-lab / 逻辑分组引入后，新增模型页需要补一层：
    • 这是新增 provider
    • 还是把模型纳入某个 logical_group

待完成

  • 增加模型时直接选择或创建 logical_group
  • 增加模型时直接配置 route 归属，而不只是落一个 provider 文件
  • 新增模型后自动生成 shadow group 规划建议

未来规划

  • 模型家族级模板库
  • 官方 / 中转 / 专线 的线路类型模板
  • 按历史成功接入记录生成默认字段与 smoke 策略

二、维护逻辑分组

这是本轮新增后最核心的新能力。

逻辑分组的目标是：

  • 前端只显示一个业务分组
  • 后面可以挂多个真实 route
  • 每个 route 再映射到宿主里的一个 shadow group

已完成

  • 已经完成概念澄清：当前宿主不支持“同一个真实 group 多 channel”
  • 已完成两份关键设计文档：
  • 已完成真实实验验证：
    • route-lab asxs
    • route-lab codex2api
    • 证明当前宿主真实约束是 GROUP_ALREADY_IN_CHANNEL
  • 已明确 fallback 方向：
    • 不改宿主源码
    • 由插件层维护 logical_group -> route -> shadow_group

待优化

  • 当前还没有一个统一文档把“逻辑分组”放回整体产品需求里，这份文档正是补这个缺口
  • 当前 portal 与 admin 页面里还没有逻辑分组这个产品层
  • 逻辑分组和 pack/provider 的关系还没有被操作界面正式表达出来

待完成

  • logical_groups 持久化模型
  • logical_group_routes 持久化模型
  • 逻辑分组 CRUD API
  • route 绑定与 shadow group 绑定 API
  • 管理页上的逻辑分组维护入口

未来规划

  • 逻辑分组级别的运营标签、描述、默认模型集合
  • 逻辑分组级别的 SLA/成本/优先级策略
  • 逻辑分组级别的用户权限与套餐映射

三、智能路由

这里的智能路由，不是宿主内部调度，而是插件层的前置路由：

  • 用户请求进入插件
  • 插件先决定 route
  • 再把请求稳定转发到对应 shadow group
  • 宿主继续在 shadow group 内做账号调度

已完成

  • 已完成路线方向选择：
    • 放弃“宿主内多 channel”
    • 采用“插件前置路由 + 宿主 shadow group”路线
  • 已完成第一版设计：
    • route sticky
    • route failover
    • Redis key 设计
    • conversation/session/user-model sticky 设计
    • cooldown / retryable / non-retryable 分类

待优化

  • 设计已成型，但还没有拆成实现任务单
  • 当前普通用户 portal 还没有接入这层前置路由
  • 对 route 健康状态、错误分类、熔断观测还没有产品级可视化

待完成

  • 前置路由器服务实现
  • Redis sticky 实现
  • route cooldown / failover 实现
  • logical group -> route -> shadow group 实时解析
  • 用户请求转发到 shadow group 的数据面链路

未来规划

  • 同公开模型名双线路主备
  • route priority + cost-aware routing
  • latency-aware routing
  • A/B route policy
  • 自动摘除劣化线路与自动恢复

四、供应商帐号导入与停启用

这是当前插件最接近成熟生产能力的一块，但需求已经不止“导入”。

当前要覆盖的完整语义

  • 导入供应商帐号 / key
  • 预检导入
  • 批量导入
  • 复用已有帐号
  • 重新启用 disabled / deprecated 帐号
  • 停用帐号
  • 查看帐号状态与导入结果

已完成

  • 已有 preview-import / import 主链路
  • 已有最小与结构化 batch-import API
  • 已有 batch-import 管理页与运行结果查询
  • 已支持 key 去重、复用、导入结果投影
  • 已在文档与实现中支持：
    • 命中 disabled / deprecated 账号时走 reactivated
  • 已有 access closure 与 provider status 聚合
  • 已完成多条真实 provider 验收

待优化

  • 当前“供应商帐号导入”仍偏导入任务视角，不是帐号资产视角
  • 没有真正的“帐号库存页 / 帐号状态列表 / route 归属页”
  • “reactivated” 虽然已支持，但前端没有被清晰表达成一个显式运维动作
  • 缺少一眼可见的：
    • active
    • warning
    • disabled
    • deprecated
    • broken 状态面板

待完成

  • 供应商帐号清单页
  • 帐号启用 / 停用 / 下线 API
  • 把帐号与 route / shadow group / logical group 的关系展示出来
  • 明确“导入新 key”和“启用已有 key”的不同操作入口

未来规划

  • 批量失效检测
  • 自动停用持续失败帐号
  • 多 key 池健康分层
  • 帐号级配额/余额/延迟监控

五、普通用户前端

这是当前最容易被误判“已经有了”的部分。

严格说，当前已经有用户 Portal，但它还是宿主分组视角，不是插件逻辑分组视角。

已完成

  • 已有公网用户 portal：
    • /portal/
  • 已有登录态、用户信息、订阅、key 列表等最小页面
  • 已有管理员 portal：
    • /portal/admin/
    • /portal/admin/providers.html
    • /portal/admin/batch-import.html

待优化

  • 当前普通用户最终看到的仍是宿主真实 group / subscription 结构
  • 这和未来“逻辑分组 + 多 route”产品层不一致
  • 用户仍可能看到过于底层的分组信息，而不是统一产品视图

待完成

  • 逻辑分组视角的普通用户前端
  • 把多个 shadow group 聚合成一个用户可见产品分组
  • 用户侧模型展示改成逻辑分组模型集合，而不是宿主原始 group 集合
  • 用户创建 key / 查看权限时走逻辑分组视图

未来规划

  • 用户侧逻辑分组购买 / 订阅 / 升级
  • 逻辑分组可见性与分层套餐
  • 用户侧展示当前线路状态、可用模型集合、使用建议

六、当前真实状态总表

已完成

  • 外部控制面主链路成立：host 注册、探测、导入、access closure、reconcile、rollback
  • 管理员前端已上线：provider 管理、batch-import、管理员 session 登录
  • provider 草稿与发布主链路已打通
  • provider 模型冲突校验已落到服务端
  • 供应商帐号导入主链路已具备真实宿主验收基础
  • 宿主不支持同 group 多 channel 的事实已经被真实验证
  • 插件前置路由 + logical group 方案已经完成设计收口

待优化

  • 管理页仍偏工程/manifest 视角，不够产品化
  • provider、新增模型、导入帐号三者的产品语义需要重新整理
  • batch-import 已有结构化入口，但普通运营视角还不够强
  • 当前 portal 仍是宿主分组视角，不是逻辑分组视角

待完成

  • logical_group 数据模型、API、管理页
  • 前置智能路由器实现
  • Redis sticky / failover / cooldown
  • route 与 shadow group 管理
  • 供应商帐号启用/停用与库存视图
  • 普通用户逻辑分组前端

未来规划

  • 同公开模型名双线路主备
  • 成本/延迟/成功率驱动的智能路由
  • 用户侧订阅、购买、升级与逻辑分组统一产品化
  • 运营指标、审计面板、健康监控

七、当前推荐主线

如果要按价值排序，当前插件后续实现主线建议是：

  1. 先做 logical_group 数据模型与管理 API
  2. 再做前置路由器最小闭环：
    • priority
    • sticky
    • failover
    • shadow group 转发
  3. 再补供应商帐号的启用/停用与 route 归属视图
  4. 最后重做普通用户 portal，把宿主真实分组隐藏到逻辑分组之后

一句话结论

插件已经从“导入控制面”演进为一个四层产品：

  • 模型与 provider 管理层
  • 逻辑分组与 route 管理层
  • 前置智能路由层
  • 面向普通用户的聚合前端层

当前第一层基本成立，第二层已完成设计但未落地，第三层和第四层是后续真正的产品化主线。

Reference in New Issue View Git Blame Copy Permalink