niuniu/sub2api-cn-relay-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13b88ba2e7ede1e6ff2acb65b2966ea6d7dae40c
sub2api-cn-relay-manager/docs/2026-06-04-plugin-host-enhancement-SPEC.md
phamnazage-jpg 492f33a129
Some checks failed
CI / Build & Test (push) Has been cancelled
Details
CI / Lint (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / Docker Build (push) Has been cancelled
Details
CI / Release (push) Has been cancelled
Details
feat(vnext): complete vNext.1 release gate — default chain admission, idempotent init, user key skeleton 
- DEFAULT_CHAIN_ADMISSION.md: reviewed and approved, real artifact refs added
- DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md: reviewed and approved
- scripts/setup_default_data.sh: idempotent init with --dry-run/--apply/artifact
- scripts/test/test_default_data.sh: 4 test cases all pass
- scripts/acceptance/verify_user_key_self_service.sh: Phase 0 skeleton
- .gitignore: add generated artifact directories
2026-06-05 11:07:50 +08:00

12 KiB
Raw Blame History

Spec: 插件增强与宿主深度适配 vNext

Objective

为 sub2api-cn-relay-manager 的下一版本建立明确规格：在“不修改宿主后端源码、不直接写宿主数据库”的前提下，先完成 vNext.1 的能力真相与模型池基础，再把用户 key 自助、治理、SLO 拆到后续版本。

当前版本目标不是一次性把“宿主适配、池化、前端、自助 key、治理、SLO”全部做完，而是先把最小可发布范围说清楚，避免再次在 Kimi / 多供应商聚合 / 用户端能力上反复试错，或在未审核设计上直接进入实现。

背景与问题陈述

当前已知问题来自真实线上使用：

  1. 宿主协议转换能力不透明
    • Kimi 接入时多次遇到协议转换偏差
    • 需确认宿主是否只稳定支持 OpenAI Chat Completions，还是也支持 Responses / Anthropic / Gemini 兼容转换
  2. 同模型多中转聚合能力不足
    • 需要确认同一个逻辑模型（如 gpt-5.4、kimi-k2.6）是否能通过一个分组聚合多个供应商账号/线路，形成池化与故障切换
  3. 用户前端能力弱
    • 现有插件前端更偏管理与目录展示，用户要拿 key、看用法、理解分组限制仍较弱
    • 希望尽量在插件/portal 前端内完成，不修改宿主后端代码
  4. 用户自助取 key 能力不足
    • 需要插件帮助生成 key，并把 key 的分组、模型、调用地址、状态、剩余额度/限制等信息交给最终用户
  5. key / 账号治理能力不足
    • 需要暂停 key、暂停账号、设置限额、设置默认分组或默认上限等能力

Host Hard Constraints

  1. 不修改 sub2api 宿主后端源码
  2. 不向宿主数据库做常态化直写作为产品能力
  3. 只允许通过：
    • 宿主公开 HTTP API
    • 宿主管理 API / 管理页面可达契约
    • 插件自身控制面、SQLite、portal 前端
  4. 如发现宿主现有 API 无法支撑某项需求，必须：
    • 先记录为协议能力缺口
    • 再决定是否由插件侧前端/控制面补偿
    • 不能把“未来也许能改宿主”当作当前方案前提

Access Closure

对本版本所有功能，完成判定不能停在“资源创建成功”。至少要同时满足：

  1. 管理面闭环：控制面/前端能看到配置结果
  2. 用户面闭环：真实用户拿到 key 后，按文档发起一次最小 POST /v1/chat/completions 成功
  3. 证据闭环：保留当前运行日志、API 回包、页面回读或脚本输出

Tech Stack

  • Go 1.22 控制面
  • internal/host/sub2api 宿主适配器
  • internal/provision 导入编排
  • internal/access 访问闭环
  • deploy/tksea-portal/ 静态前端
  • SQLite 本地状态存储

Commands

规格与后续实现的标准命令：

  • 文档真相核对：
    • git status --short
    • git log --oneline -n 5
  • Go 质量门禁：
    • gofmt -l .
    • go vet ./...
    • go test -cover ./internal/...
    • go test ./tests/integration/... -count=1
  • 前端门禁（若触及 portal）：
    • bash ./scripts/test/test_tksea_portal_assets.sh
    • bash ./scripts/test/verify_frontend_smoke.sh
    • bash ./scripts/acceptance/verify_provider_admin_actions.sh
  • 宿主协议探测（需新增脚本后执行）：
    • bash ./scripts/acceptance/verify_host_protocol_matrix.sh
    • bash ./scripts/acceptance/verify_host_pool_routing.sh
    • bash ./scripts/acceptance/verify_user_key_self_service.sh

Project Structure

本次规划预计涉及的目录：

  • docs/ — SPEC、TDD 计划、执行板
  • internal/host/sub2api/ — 宿主能力探测、协议/契约抽象
  • internal/provision/ — 导入、聚合池配置、账号/key 治理编排
  • internal/access/ — 用户访问闭环、key 可用性验证
  • internal/app/ — 控制面 API（若新增插件自有 API）
  • deploy/tksea-portal/ — 用户 portal / admin 页面增强
  • tests/integration/ — 集成测试
  • scripts/acceptance/ — 宿主真实验收脚本

Code Style

遵循仓库既有约束：

  • Go 包按 host/app/provision/access/store 分层
  • 错误统一 fmt.Errorf("context: %w", err)
  • 新能力优先通过 adapter/service/repo 组合扩展，不把宿主特例硬编码到 handler
  • 与宿主的“协议差异”必须放在 adapter / capability 层，不把协议分支散到 portal 页面

Testing Strategy

本版本的测试要分五层：

  1. 单元测试
    • 宿主 capability 解析
    • 模型池聚合策略
    • key/账号状态机（active / paused / quota exceeded）
  2. 集成测试
    • SQLite repo + app handler + provision service
  3. 前端 smoke
    • key 发放页、key 状态页、限额/暂停页渲染与动作契约
  4. 宿主真实验收
    • 协议矩阵
    • 池化分发
    • 用户取 key 到调用成功
  5. 生产准入验证
    • 仅将“真实用户 chat=200”的模型/池写入默认链路

Boundaries

Always:

  • 先写 spec，再写 TDD 计划，再开始实现
  • 所有“宿主支持某协议/某模型/某聚合方式”的结论都必须来自真实验收
  • 触及 portal 时必须跑前端门禁
  • 每个能力都要有用户面闭环，不只看 admin 成功

Ask first:

  • 需要新增外部依赖
  • 需要改变 key 发放产品策略（如收费、默认余额、默认分组）
  • 需要把某个模型池写入 OpenClaw 默认链路

Never:

  • 直接修改宿主后端源码
  • 直接把宿主数据库写入当成长期产品方案
  • 用 models=200 代替真实 chat=200
  • 把“协议猜测”当成功能完成

Release Scope

当前发布范围以 docs/2026-06-04-vnext-release-scope.md 为真相源。

  • vNext.1（当前要审核并准备实施的版本）:
    • 宿主协议能力矩阵
    • 模型池抽象
    • pool 到现有 priority failover 运行面的映射
    • 默认链路准入规则
    • 幂等默认数据/初始化脚本前置
  • vNext.2（本轮只设计，不进入当前实现）:
    • KEY_SECURITY_MODEL
    • 用户 key 自助申请
    • portal 首次调用闭环
  • vNext.3（本轮只设计，不进入当前实现）:
    • key/account 治理
    • quota/limit
    • SLO/指标/告警

Scope

A. 宿主协议能力矩阵

要回答：

  • 宿主当前稳定支持哪些协议入口/返回格式？
  • 哪些模型需要额外转换层？
  • Kimi 失败到底是上游问题、宿主协议问题，还是导入配置问题？

本版本输出：

  • 一份宿主协议能力矩阵文档
  • 一组可重复执行的协议探测脚本
  • 明确“受支持 / 需插件适配 / 当前不支持”的分类

B. 同模型多供应商池化分发

要回答：

  • 同一逻辑分组下是否能挂多个账号/多个 channel
  • 是否能对同一个公共模型名映射到多个供应商线路
  • 现有宿主选路是否已有健康分发/优先级/冷却能力

本版本输出：

  • 池化模型设计：logical model -> route set -> provider accounts
  • 插件侧“模型池”抽象，而不是单 provider 绑定
  • 验证脚本证明：同组多供应商可轮转 / 故障切换 / 人工禁用后可收敛

C. 前端承接用户能力

要回答：

  • 哪些宿主原生用户能力不足，需要 portal 前端承接
  • 在不改宿主后端时，哪些能力可由插件自有 API + portal 完成

本版本输出：

  • 用户产品面信息架构：
    • 可申请的模型组
    • 已有 key
    • key 状态/限额/暂停
    • 推荐 base URL / model / curl 示例
  • admin 侧操作页：
    • 发放 key
    • 暂停/恢复 key
    • 设置额度/限额
    • 查看池健康

D. 插件辅助生成 key

要回答：

  • key 是由宿主生成还是插件包装生成
  • 用户拿到 key 后需要看到哪些元数据
  • 是否支持一键复制 SDK/curl 示例

本版本输出：

  • 自助 key 发放流程
  • key 元信息展示规范
  • 用户端“从登录到首次 200 调用”的最短路径

E. key / 账号治理

要回答：

  • key 暂停、账号暂停、限额是否已有宿主 API 可控点
  • 如果宿主无足够字段，插件侧是否能通过控制面侧策略先拦截

本版本输出：

  • key 状态模型
  • account 状态模型
  • quota / budget / request limit 的最小可落地方案
  • 与真实验收一致的治理 runbook

Functional Requirements

FR-1 协议能力探测

系统必须能输出一份按模型/协议/供应商分类的能力矩阵，至少覆盖：

  • OpenAI Chat Completions
  • OpenAI Responses（若宿主不支持，要明确标红）
  • Kimi 兼容接口
  • DeepSeek
  • MiniMax
  • GLM
  • GPT 中转常见供应商

FR-2 宿主兼容性标签

系统必须把模型线路分类为：

  • supported-direct
  • supported-with-plugin-adapter
  • unsupported-by-host
  • upstream-unhealthy

FR-3 模型池抽象

系统必须允许一个逻辑模型对应多个候选线路，并记录：

  • provider name
  • base_url
  • supported models
  • priority
  • schedulable
  • last health state
  • cooldown / disable reason

FR-4 池化验收

必须证明在同组内：

  • 至少两个候选线路可共同服务一个模型名
  • 一个线路失败后能切到另一条
  • 被人工暂停的线路不会继续被分发

FR-5 模型池 active 准入

vNext.1 的 active model pool 必须默认排除：

  • Schedulable=false 的候选
  • HostReady=false 的候选
  • unsupported-by-host
  • upstream-unhealthy

如需展示不可进入 active pool 的候选，应输出 rejected/reason 视图，而不是混入 active routes。

FR-6 默认链路准入

只有通过真实用户链路 POST /v1/chat/completions=200 的模型池，才允许进入默认链路。

每条准入记录必须至少包含：

  • model pool ID
  • route/provider/account 证据
  • upstream / host / user-key 三层 probe 路径
  • artifact 路径
  • 最近 N 次 chat=200 结果
  • owner approval

FR-7 后续版本保留项

以下需求仍保留，但不属于 vNext.1 实现范围：

  • 用户 portal 承接
  • key 自助发放
  • key/account 暂停恢复
  • quota/limit
  • SLO/告警

这些内容必须在后续文档中单独落地：

  • KEY_SECURITY_MODEL.md
  • PORTAL_KEY_EXPERIENCE.md
  • KEY_ACCOUNT_GOVERNANCE.md
  • SLO_AND_OBSERVABILITY.md

Non-Goals

本版本不做：

  • 修改宿主后端源码
  • 自研完整计费系统
  • 自研多租户 IAM
  • 直接替换宿主所有 UI
  • 在没有真实上游证据前承诺“所有主流模型都支持”

Success Criteria

vNext.1 当前审核通过标准：

  1. 范围层面
    • 已冻结 vNext.1 / vNext.2 / vNext.3 边界
    • 未经审核通过，不继续实现后续版本主链功能
  2. 设计层面
    • 完成协议矩阵设计 + 模型池设计 + 默认链路准入设计
    • 明确当前只承诺 priority failover，不承诺完整负载均衡池化
  3. 证据层面
    • 每个“支持”结论都绑定真实探测脚本与输出
    • probe 必须区分 upstream / host / user-key 三层证据
  4. 发布层面
    • active pool 默认排除 HostReady=false 与 Schedulable=false
    • 只有通过真实用户链路的模型池才能进入默认链路
  5. 规划层面
    • vNext.2/vNext.3 的 key 安全模型、治理状态模型、SLO 文档已列为必备后续设计产物

Open Questions

  1. 宿主当前对 key 暂停/禁用/限额是否已有稳定 API？需要先做 capability inventory。
  2. 如果宿主无法直接生成明文 key，插件是否应改为“调用宿主生成 + 自身只投影展示”，而不是自造 key。
  3. 限额优先做哪一种：余额、请求次数、模型级预算、日限额？
  4. 用户登录态是否继续沿用 portal 当前机制，还是需要更明确的“申请 key / 管理 key”入口分离。
  5. Kimi 与 GLM 是否都坚持走宿主统一协议，还是先接受“部分模型在插件侧标记为实验支持”。
Reference in New Issue View Git Blame Copy Permalink