启动器 API（Launcher API v1）

面向桌面启动器的账号/角色管理接口，由官方插件 launcher-api 提供。 规范正文与 OpenAPI 在插件仓库：

• <https://github.com/YimingZhanshen/skin-nexus-plugins/blob/main/plugins/launcher-api/LAUNCHER-API.md&gt;
• <https://github.com/YimingZhanshen/skin-nexus-plugins/blob/main/plugins/launcher-api/openapi.yaml&gt;

基址 = https://<站点>/api/plugins/launcher-api/v1。GET <基址>/meta 公开，其余端点 Authorization: Bearer <token>。

启动器登录流程

1. 启动器用现有的 Yggdrasil Connect OIDC 设备码流程（client 2，scope 含 openid offline_access Yggdrasil.PlayerProfiles.Select Yggdrasil.Server.Join） 取得 access_token；或复用密码登录拿到的 Yggdrasil accessToken。
2. 调 GET <基址>/meta 探测站点是否安装/启用该插件； 404 时回退到浏览器。
3. 之后所有请求带 Authorization: Bearer <access_token>，不使用 cookie/CSRF。
4. 401 时刷新或重新认证；改名/删角后旧游戏 token 可能失效，需刷新。

能力

• 账号：昵称、头像 URL、角色上限/数量、存储用量
• 角色：列表 / 详情 / 创建 / 改名 / 删除（UUID 零漂移）
• 外观：上传 PNG（skin/cape；model 只是建议值，手臂模型最终由服务端按像素判定）或应用已有纹理、清除槽位
• 纹理：个人纹理库、独立上传（按 uid+type+hash 幂等）
• 皮肤库：公开纹理搜索/详情、导入为私有副本后应用到角色

错误为 {"error":"stable.code","message":"..."}；限流返回 429 + Retry-After。 独立上传遇到公共库相同 (type,hash) 时返回 409 texture.duplicate_public 并附 textureId/url；同用户重复上传仍是 200（该门需宿主 >=0.5.0，见下方服务端要求）。 完整端点、字段、错误码与重试语义见上面的规范。

服务端要求

• 宿主 >=0.4.0（bearer-auth.v1、binary-body.v1、account.v1）；公共纹理去重错误码需 >=0.5.0。
• 安装并启用签名插件 launcher-api；它需要 http:routes、 http:routes:bearer、account:read、players:read、players:write、 textures:read、textures:write。
• 角色的所有权、名称规则、数量上限、guard、事件与审计全部由宿主账号服务执行； 插件只做请求/响应映射。
• 下游复刻站可安装自己的 launcher API 插件；启动器只需按本规范调用固定路径。