sub2api-cn-relay-manager/docs/PLUGIN_REQUIREMENTS_OVERVIEW_2026-05-28.md

# 插件整体需求梳理（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”
- 已完成两份关键设计文档：
  - [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 管理层
- 前置智能路由层
- 面向普通用户的聚合前端层

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