# 插件整体需求梳理（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//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” - 已完成两份关键设计文档： - [HOST_MULTI_CHANNEL_MINIMAL_RETROFIT.md](/home/long/project/sub2api-cn-relay-manager/docs/HOST_MULTI_CHANNEL_MINIMAL_RETROFIT.md:1) - [PLUGIN_ROUTE_STICKY_DESIGN.md](/home/long/project/sub2api-cn-relay-manager/docs/PLUGIN_ROUTE_STICKY_DESIGN.md:1) - 已完成真实实验验证： - 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 管理层 - 前置智能路由层 - 面向普通用户的聚合前端层 当前第一层基本成立，第二层已完成设计但未落地，第三层和第四层是后续真正的产品化主线。