qqmusic-api-enhanced 1.0.4 → 1.0.6

package/interface.d.ts

@@ -39,6 +39,8 @@ export interface LoginQrCreateResult {
   qrurl?: string;
   qrimg?: string;
   url?: string;
+  /** 本次登录的设备标识；登录成功后会写入 Cookie，后续续期沿用。 */
+  guid?: string;
 }
 
 export interface LoginQrCheckQuery extends RequestBaseConfig {
@@ -54,6 +56,8 @@ export interface LoginQrCheckQuery extends RequestBaseConfig {
   qrcodeID?: string;
   /** 兼容通用 key 参数 */
   key?: string;
+  /** 设备标识；缺省由二维码会话派生，登录成功后写入 Cookie。 */
+  guid?: string;
 }
 
 export interface LoginQrCheckResult {
@@ -61,6 +65,9 @@ export interface LoginQrCheckResult {
   message: string;
   uin?: string;
   musickey?: string;
+  guid?: string;
+  /** 新凭证过期时刻（毫秒），上游给出时才有。 */
+  expiresAt?: number;
   cookie?: Record<string, string>;
   cookieStr?: string;
   data?: Record<string, any>;
@@ -95,6 +102,10 @@ export interface LoginStatusResult {
   avatarUrl?: string;
   vip: NormalizedVipInfo;
   account: NormalizedLoginAccount;
+  /** 校验过程中轮换后的完整 Cookie；调用方应回写。 */
+  cookieStr?: string;
+  /** 新凭证过期时刻（毫秒），上游给出时才有。 */
+  expiresAt?: number;
   data?: Record<string, any>;
   userInfo?: Record<string, any>;
 }
@@ -103,12 +114,17 @@ export interface LoginRefreshQuery extends RequestBaseConfig {
   openid?: string;
   refresh_token?: string;
   refresh_key?: string;
+  /** 设备标识；缺省从 Cookie/账号派生。 */
+  guid?: string;
 }
 
 export interface LoginRefreshResult {
   code: number;
   musickey?: string;
   cookieStr?: string;
+  /** 新凭证过期时刻（毫秒），上游给出时才有。 */
+  expiresAt?: number;
+  message?: string;
   data?: Record<string, any>;
   raw?: Record<string, any>;
 }
@@ -341,9 +357,16 @@ export function qrcDecrypt(hexData: string): string | null;
 export function hash33(str: string): number;
 export function getGtk(skey: string): number;
 export function getGuid(): string;
+/** 由稳定种子派生 32 位设备 guid；同一账号/登录会话内保持不变。 */
+export function getStableGuid(seed: string): string;
 export function getSearchId(): string;
 export function cookieToJson(cookie: string | Record<string, string> | undefined | null): Record<string, string>;
 export function cookieToString(cookieObj: Record<string, string> | undefined | null): string;
+/** 把登录/续期响应里的凭证字段（含 refresh_token/refresh_key/openid）并入 Cookie。 */
+export function mergeLoginPayloadCookies(
+  cookieObj: Record<string, string>,
+  payload: unknown
+): { obtainedMusickey: boolean; expiresAt?: number };
 export function parseSetCookie(setCookieHeaders?: string[]): Record<string, string>;
 
 declare const api: {
@@ -372,9 +395,11 @@ declare const api: {
   hash33: typeof hash33;
   getGtk: typeof getGtk;
   getGuid: typeof getGuid;
+  getStableGuid: typeof getStableGuid;
   getSearchId: typeof getSearchId;
   cookieToJson: typeof cookieToJson;
   cookieToString: typeof cookieToString;
+  mergeLoginPayloadCookies: typeof mergeLoginPayloadCookies;
   parseSetCookie: typeof parseSetCookie;
 };
 

package/main.js

@@ -14,8 +14,8 @@ import song_url_fn from "./module/song_url.js";
 import user_detail_fn from "./module/user_detail.js";
 import user_playlist_fn from "./module/user_playlist.js";
 import user_vip_info_fn, { deriveVipInfo, parseVipFromIcons, } from "./module/user_vip_info.js";
-import { cookieToJson, cookieToString, parseSetCookie } from "./util/cookie.js";
-import { getGtk, getGuid, getSearchId, hash33, qrcDecrypt } from "./util/crypto.js";
+import { cookieToJson, cookieToString, mergeLoginPayloadCookies, parseSetCookie, } from "./util/cookie.js";
+import { getGtk, getGuid, getSearchId, getStableGuid, hash33, qrcDecrypt, } from "./util/crypto.js";
 import { request, requestCgi, requestRaw } from "./util/request.js";
 import { zzcSign } from "./util/sign.js";
 export const artist_detail = (query = {}) => artist_detail_fn(query, request);
@@ -34,7 +34,7 @@ export const song_url = (query = {}) => song_url_fn(query, request);
 export const user_detail = (query = {}) => user_detail_fn(query, request);
 export const user_playlist = (query = {}) => user_playlist_fn(query, request);
 export const user_vip_info = (query = {}) => user_vip_info_fn(query, request);
-export { request, requestCgi, requestRaw, zzcSign, qrcDecrypt, hash33, getGtk, getGuid, getSearchId, cookieToJson, cookieToString, parseSetCookie, deriveVipInfo, parseVipFromIcons, };
+export { request, requestCgi, requestRaw, zzcSign, qrcDecrypt, hash33, getGtk, getGuid, getStableGuid, getSearchId, cookieToJson, cookieToString, mergeLoginPayloadCookies, parseSetCookie, deriveVipInfo, parseVipFromIcons, };
 const api = {
     artist_detail,
     artist_songs,
@@ -62,9 +62,11 @@ const api = {
     hash33,
     getGtk,
     getGuid,
+    getStableGuid,
     getSearchId,
     cookieToJson,
     cookieToString,
+    mergeLoginPayloadCookies,
     parseSetCookie,
 };
 export default api;

package/main.ts

@@ -22,8 +22,20 @@ import user_vip_info_fn, {
   type NormalizedVipInfo,
 } from "./module/user_vip_info.js";
 
-import { cookieToJson, cookieToString, parseSetCookie } from "./util/cookie.js";
-import { getGtk, getGuid, getSearchId, hash33, qrcDecrypt } from "./util/crypto.js";
+import {
+  cookieToJson,
+  cookieToString,
+  mergeLoginPayloadCookies,
+  parseSetCookie,
+} from "./util/cookie.js";
+import {
+  getGtk,
+  getGuid,
+  getSearchId,
+  getStableGuid,
+  hash33,
+  qrcDecrypt,
+} from "./util/crypto.js";
 import { request, requestCgi, requestRaw, type ApiResponse } from "./util/request.js";
 import { zzcSign } from "./util/sign.js";
 
@@ -84,9 +96,11 @@ export {
   hash33,
   getGtk,
   getGuid,
+  getStableGuid,
   getSearchId,
   cookieToJson,
   cookieToString,
+  mergeLoginPayloadCookies,
   parseSetCookie,
   deriveVipInfo,
   parseVipFromIcons,
@@ -123,9 +137,11 @@ const api = {
   hash33,
   getGtk,
   getGuid,
+  getStableGuid,
   getSearchId,
   cookieToJson,
   cookieToString,
+  mergeLoginPayloadCookies,
   parseSetCookie,
 };
 

package/module/login_qr_check.d.ts

@@ -15,4 +15,5 @@ export default function login_qr_check(query?: {
     uuid?: string;
     qrcodeID?: string;
     key?: string;
+    guid?: string;
 }, req?: typeof request): Promise<ApiResponse>;

package/module/login_qr_check.js

@@ -1,6 +1,6 @@
 import { request, requestCgi } from "../util/request.js";
-import { getGtk, getGuid } from "../util/crypto.js";
-import { cookieToString, parseSetCookie } from "../util/cookie.js";
+import { getGtk, getStableGuid } from "../util/crypto.js";
+import { cookieToJson, cookieToString, mergeLoginPayloadCookies, parseSetCookie, } from "../util/cookie.js";
 import { getMobileSession, registerMobileSession } from "../util/mobile_qr_session.js";
 /**
  * 轮询检查二维码登录状态.
@@ -25,6 +25,7 @@ export default async function login_qr_check(query = {}, req = request) {
             `&ptqrtoken=${ptqrtoken}&ptredirect=0&h=1&t=1&g=1&from_ui=1&ptlang=2052` +
             `&action=0-0-${Date.now()}&js_ver=20102616&js_type=1&pt_uistyle=40` +
             `&aid=716027609&daid=383&pt_3rd_aid=100497308&has_onekey=1`;
+        const guid = query.guid || getStableGuid(qrsig);
         const checkRes = await fetch(checkUrl, {
             headers: {
                 Referer: "https://xui.ptlogin2.qq.com/",
@@ -97,7 +98,7 @@ export default async function login_qr_check(query = {}, req = request) {
         authorizeFormData.append("openapi", "1010_1030");
         authorizeFormData.append("g_tk", String(gtk));
         authorizeFormData.append("auth_time", String(Date.now()));
-        authorizeFormData.append("ui", getGuid());
+        authorizeFormData.append("ui", guid);
         const authRes = await fetch("https://graph.qq.com/oauth2.0/authorize", {
             method: "POST",
             headers: {
@@ -125,6 +126,10 @@ export default async function login_qr_check(query = {}, req = request) {
         });
         const resultCookie = loginCgiRes.cookie || [];
         const finalCookies = { ...allCookies, ...parseSetCookie(resultCookie) };
+        // 登录响应里的 refresh_token / refresh_key / openid 是后续续期的关键，
+        // 旧实现只取 musickey，导致 key 过期后无法恢复。
+        const merged = mergeLoginPayloadCookies(finalCookies, loginCgiRes.body);
+        finalCookies.guid = guid;
         const uin = finalCookies.uin || finalCookies.qqmusic_uin || "";
         const musickey = finalCookies.qm_keyst || finalCookies.qqmusic_key || "";
         return {
@@ -134,6 +139,8 @@ export default async function login_qr_check(query = {}, req = request) {
                 message: "登录成功",
                 uin,
                 musickey,
+                guid,
+                expiresAt: merged.expiresAt,
                 data: loginCgiRes.body,
                 cookieStr: cookieToString(finalCookies),
             },
@@ -148,6 +155,7 @@ export default async function login_qr_check(query = {}, req = request) {
                 body: { code: 400, message: "缺少必要参数 qrcodeID" },
             };
         }
+        const guid = query.guid || getStableGuid(qrcodeID);
         // 1. 确保后台 MQTT 会话已启动
         let session = getMobileSession(qrcodeID);
         if (!session) {
@@ -159,6 +167,8 @@ export default async function login_qr_check(query = {}, req = request) {
         }
         // 2. 优先检查实时会话事件
         if (session && session.code === 200) {
+            const cookieObj = cookieToJson(session.cookieStr);
+            cookieObj.guid = cookieObj.guid || guid;
             return {
                 status: 200,
                 body: {
@@ -168,7 +178,8 @@ export default async function login_qr_check(query = {}, req = request) {
                     musickey: session.musickey || "",
                     nickname: session.nickname || "",
                     avatarUrl: session.avatarUrl || "",
-                    cookieStr: session.cookieStr || "",
+                    guid,
+                    cookieStr: cookieToString(cookieObj),
                 },
             };
         }
@@ -215,16 +226,9 @@ export default async function login_qr_check(query = {}, req = request) {
             if (code === 0) {
                 const cookies = cgiRes.cookie || [];
                 const cookieObj = parseSetCookie(cookies);
-                if (cgiBody.musicid && !cookieObj.uin)
-                    cookieObj.uin = String(cgiBody.musicid);
-                if (cgiBody.musickey && !cookieObj.qm_keyst)
-                    cookieObj.qm_keyst = String(cgiBody.musickey);
-                if (cgiBody.musickey && !cookieObj.qqmusic_key)
-                    cookieObj.qqmusic_key = String(cgiBody.musickey);
-                if (cgiBody.openid && !cookieObj.openid)
-                    cookieObj.openid = String(cgiBody.openid);
-                if (cgiBody.refresh_token && !cookieObj.refresh_token)
-                    cookieObj.refresh_token = String(cgiBody.refresh_token);
+                // 与 QQ 网页扫码同一套合并逻辑：refresh_key/openid/access_token/过期时间都要留下。
+                const merged = mergeLoginPayloadCookies(cookieObj, cgiBody);
+                cookieObj.guid = guid;
                 const cookieStr = cookieToString(cookieObj);
                 return {
                     status: 200,
@@ -233,6 +237,8 @@ export default async function login_qr_check(query = {}, req = request) {
                         message: "登录成功",
                         uin: cookieObj.uin || String(cgiBody.musicid || ""),
                         musickey: cookieObj.qm_keyst || String(cgiBody.musickey || ""),
+                        guid,
+                        expiresAt: merged.expiresAt,
                         cookieStr,
                         data: cgiBody,
                     },
@@ -257,6 +263,7 @@ export default async function login_qr_check(query = {}, req = request) {
             body: { code: 400, message: "缺少必要参数 uuid" },
         };
     }
+    const guid = query.guid || getStableGuid(uuid);
     const pollUrl = `https://lp.open.weixin.qq.com/connect/l/qrconnect?uuid=${uuid}&_=${Date.now()}`;
     const wxRes = await fetch(pollUrl, {
         headers: {
@@ -295,6 +302,8 @@ export default async function login_qr_check(query = {}, req = request) {
         });
         const cookies = wxLoginRes.cookie || [];
         const cookieObj = parseSetCookie(cookies);
+        const merged = mergeLoginPayloadCookies(cookieObj, wxLoginRes.body);
+        cookieObj.guid = guid;
         return {
             status: 200,
             body: {
@@ -302,6 +311,8 @@ export default async function login_qr_check(query = {}, req = request) {
                 message: "微信登录成功",
                 uin: cookieObj.wxuin || cookieObj.uin || "",
                 musickey: cookieObj.qm_keyst || cookieObj.musickey || "",
+                guid,
+                expiresAt: merged.expiresAt,
                 data: wxLoginRes.body,
                 cookieStr: cookieToString(cookieObj),
             },

package/module/login_qr_check.ts

@@ -1,6 +1,11 @@
 import { request, requestCgi, type ApiResponse } from "../util/request.js";
-import { getGtk, getGuid } from "../util/crypto.js";
-import { cookieToString, parseSetCookie } from "../util/cookie.js";
+import { getGtk, getStableGuid } from "../util/crypto.js";
+import {
+  cookieToJson,
+  cookieToString,
+  mergeLoginPayloadCookies,
+  parseSetCookie,
+} from "../util/cookie.js";
 import { getMobileSession, registerMobileSession } from "../util/mobile_qr_session.js";
 
 /**
@@ -20,6 +25,7 @@ export default async function login_qr_check(
     uuid?: string;
     qrcodeID?: string;
     key?: string;
+    guid?: string;
   } = {},
   req = request
 ): Promise<ApiResponse> {
@@ -40,6 +46,7 @@ export default async function login_qr_check(
       `&action=0-0-${Date.now()}&js_ver=20102616&js_type=1&pt_uistyle=40` +
       `&aid=716027609&daid=383&pt_3rd_aid=100497308&has_onekey=1`;
 
+    const guid = query.guid || getStableGuid(qrsig);
     const checkRes = await fetch(checkUrl, {
       headers: {
         Referer: "https://xui.ptlogin2.qq.com/",
@@ -127,7 +134,7 @@ export default async function login_qr_check(
     authorizeFormData.append("openapi", "1010_1030");
     authorizeFormData.append("g_tk", String(gtk));
     authorizeFormData.append("auth_time", String(Date.now()));
-    authorizeFormData.append("ui", getGuid());
+    authorizeFormData.append("ui", guid);
 
     const authRes = await fetch("https://graph.qq.com/oauth2.0/authorize", {
       method: "POST",
@@ -165,6 +172,10 @@ export default async function login_qr_check(
 
     const resultCookie = loginCgiRes.cookie || [];
     const finalCookies = { ...allCookies, ...parseSetCookie(resultCookie) };
+    // 登录响应里的 refresh_token / refresh_key / openid 是后续续期的关键，
+    // 旧实现只取 musickey，导致 key 过期后无法恢复。
+    const merged = mergeLoginPayloadCookies(finalCookies, loginCgiRes.body);
+    finalCookies.guid = guid;
 
     const uin = finalCookies.uin || finalCookies.qqmusic_uin || "";
     const musickey = finalCookies.qm_keyst || finalCookies.qqmusic_key || "";
@@ -176,6 +187,8 @@ export default async function login_qr_check(
         message: "登录成功",
         uin,
         musickey,
+        guid,
+        expiresAt: merged.expiresAt,
         data: loginCgiRes.body,
         cookieStr: cookieToString(finalCookies),
       },
@@ -191,6 +204,7 @@ export default async function login_qr_check(
         body: { code: 400, message: "缺少必要参数 qrcodeID" },
       };
     }
+    const guid = query.guid || getStableGuid(qrcodeID);
 
     // 1. 确保后台 MQTT 会话已启动
     let session = getMobileSession(qrcodeID);
@@ -203,6 +217,8 @@ export default async function login_qr_check(
 
     // 2. 优先检查实时会话事件
     if (session && session.code === 200) {
+      const cookieObj = cookieToJson(session.cookieStr);
+      cookieObj.guid = cookieObj.guid || guid;
       return {
         status: 200,
         body: {
@@ -212,7 +228,8 @@ export default async function login_qr_check(
           musickey: session.musickey || "",
           nickname: session.nickname || "",
           avatarUrl: session.avatarUrl || "",
-          cookieStr: session.cookieStr || "",
+          guid,
+          cookieStr: cookieToString(cookieObj),
         },
       };
     }
@@ -270,11 +287,9 @@ export default async function login_qr_check(
       if (code === 0) {
         const cookies = cgiRes.cookie || [];
         const cookieObj = parseSetCookie(cookies);
-        if (cgiBody.musicid && !cookieObj.uin) cookieObj.uin = String(cgiBody.musicid);
-        if (cgiBody.musickey && !cookieObj.qm_keyst) cookieObj.qm_keyst = String(cgiBody.musickey);
-        if (cgiBody.musickey && !cookieObj.qqmusic_key) cookieObj.qqmusic_key = String(cgiBody.musickey);
-        if (cgiBody.openid && !cookieObj.openid) cookieObj.openid = String(cgiBody.openid);
-        if (cgiBody.refresh_token && !cookieObj.refresh_token) cookieObj.refresh_token = String(cgiBody.refresh_token);
+        // 与 QQ 网页扫码同一套合并逻辑：refresh_key/openid/access_token/过期时间都要留下。
+        const merged = mergeLoginPayloadCookies(cookieObj, cgiBody);
+        cookieObj.guid = guid;
 
         const cookieStr = cookieToString(cookieObj);
         return {
@@ -284,6 +299,8 @@ export default async function login_qr_check(
             message: "登录成功",
             uin: cookieObj.uin || String(cgiBody.musicid || ""),
             musickey: cookieObj.qm_keyst || String(cgiBody.musickey || ""),
+            guid,
+            expiresAt: merged.expiresAt,
             cookieStr,
             data: cgiBody,
           },
@@ -309,6 +326,7 @@ export default async function login_qr_check(
       body: { code: 400, message: "缺少必要参数 uuid" },
     };
   }
+  const guid = query.guid || getStableGuid(uuid);
 
   const pollUrl = `https://lp.open.weixin.qq.com/connect/l/qrconnect?uuid=${uuid}&_=${Date.now()}`;
   const wxRes = await fetch(pollUrl, {
@@ -359,6 +377,8 @@ export default async function login_qr_check(
 
     const cookies = wxLoginRes.cookie || [];
     const cookieObj = parseSetCookie(cookies);
+    const merged = mergeLoginPayloadCookies(cookieObj, wxLoginRes.body);
+    cookieObj.guid = guid;
 
     return {
       status: 200,
@@ -367,6 +387,8 @@ export default async function login_qr_check(
         message: "微信登录成功",
         uin: cookieObj.wxuin || cookieObj.uin || "",
         musickey: cookieObj.qm_keyst || cookieObj.musickey || "",
+        guid,
+        expiresAt: merged.expiresAt,
         data: wxLoginRes.body,
         cookieStr: cookieToString(cookieObj),
       },

package/module/login_qr_create.d.ts

@@ -7,4 +7,5 @@ import { request, type ApiResponse } from "../util/request.js";
 export default function login_qr_create(query?: {
     type?: "qq" | "wx" | "mobile";
     cookie?: any;
+    guid?: string;
 }, req?: typeof request): Promise<ApiResponse>;

package/module/login_qr_create.js

@@ -1,5 +1,5 @@
 import { request } from "../util/request.js";
-import { hash33 } from "../util/crypto.js";
+import { getStableGuid, hash33 } from "../util/crypto.js";
 import { parseSetCookie } from "../util/cookie.js";
 import { registerMobileSession } from "../util/mobile_qr_session.js";
 /**
@@ -23,6 +23,8 @@ export default async function login_qr_create(query = {}, req = request) {
         const cookieObj = parseSetCookie(res.cookie);
         const qrsig = cookieObj.qrsig || "";
         const ptqrtoken = hash33(qrsig);
+        // 与 login_qr_check 用同一个种子派生，登录成功时写入 Cookie，保证设备标识稳定。
+        const guid = query.guid || getStableGuid(qrsig);
         // 二维码图片转 base64
         let qrimg = "";
         if (Buffer.isBuffer(res.body)) {
@@ -46,6 +48,7 @@ export default async function login_qr_create(query = {}, req = request) {
                 ptqrtoken,
                 qrimg,
                 url,
+                guid,
             },
             cookie: res.cookie,
         };
@@ -64,6 +67,7 @@ export default async function login_qr_create(query = {}, req = request) {
         const qrcodeUrl = uuid
             ? `https://open.weixin.qq.com/connect/qrcode/${uuid}`
             : "";
+        const guid = query.guid || (uuid ? getStableGuid(uuid) : "");
         return {
             status: 200,
             body: {
@@ -71,6 +75,7 @@ export default async function login_qr_create(query = {}, req = request) {
                 type: "wx",
                 uuid,
                 qrurl: qrcodeUrl,
+                guid,
             },
             cookie: res.cookie,
         };
@@ -86,6 +91,7 @@ export default async function login_qr_create(query = {}, req = request) {
         }
         catch { }
     }
+    const guid = query.guid || (qrcodeID ? getStableGuid(qrcodeID) : "");
     return {
         status: cgiRes.status,
         body: {
@@ -93,6 +99,7 @@ export default async function login_qr_create(query = {}, req = request) {
             type: "mobile",
             qrcode: cgiRes.body?.qrcode,
             qrcodeID,
+            guid,
         },
         cookie: cgiRes.cookie,
     };

package/module/login_qr_create.ts

@@ -1,5 +1,5 @@
 import { request, type ApiResponse } from "../util/request.js";
-import { hash33 } from "../util/crypto.js";
+import { getStableGuid, hash33 } from "../util/crypto.js";
 import { parseSetCookie } from "../util/cookie.js";
 import { registerMobileSession } from "../util/mobile_qr_session.js";
 
@@ -9,7 +9,7 @@ import { registerMobileSession } from "../util/mobile_qr_session.js";
  * @param query.type 登录类型: 'qq' (默认), 'wx' (微信), 'mobile' (QQ音乐App)
  */
 export default async function login_qr_create(
-  query: { type?: "qq" | "wx" | "mobile"; cookie?: any } = {},
+  query: { type?: "qq" | "wx" | "mobile"; cookie?: any; guid?: string } = {},
   req = request
 ): Promise<ApiResponse> {
   const type = query.type || "qq";
@@ -32,6 +32,8 @@ export default async function login_qr_create(
     const cookieObj = parseSetCookie(res.cookie);
     const qrsig = cookieObj.qrsig || "";
     const ptqrtoken = hash33(qrsig);
+    // 与 login_qr_check 用同一个种子派生，登录成功时写入 Cookie，保证设备标识稳定。
+    const guid = query.guid || getStableGuid(qrsig);
 
     // 二维码图片转 base64
     let qrimg = "";
@@ -54,6 +56,7 @@ export default async function login_qr_create(
         ptqrtoken,
         qrimg,
         url,
+        guid,
       },
       cookie: res.cookie,
     };
@@ -77,6 +80,7 @@ export default async function login_qr_create(
     const qrcodeUrl = uuid
       ? `https://open.weixin.qq.com/connect/qrcode/${uuid}`
       : "";
+    const guid = query.guid || (uuid ? getStableGuid(uuid) : "");
 
     return {
       status: 200,
@@ -85,6 +89,7 @@ export default async function login_qr_create(
         type: "wx",
         uuid,
         qrurl: qrcodeUrl,
+        guid,
       },
       cookie: res.cookie,
     };
@@ -106,6 +111,7 @@ export default async function login_qr_create(
       registerMobileSession(qrcodeID);
     } catch {}
   }
+  const guid = query.guid || (qrcodeID ? getStableGuid(qrcodeID) : "");
 
   return {
     status: cgiRes.status,
@@ -114,6 +120,7 @@ export default async function login_qr_create(
       type: "mobile",
       qrcode: cgiRes.body?.qrcode,
       qrcodeID,
+      guid,
     },
     cookie: cgiRes.cookie,
   };

package/module/login_refresh.d.ts

@@ -1,18 +1,36 @@
 import { request, type ApiResponse } from "../util/request.js";
-/**
- * 刷新登录凭证.
- *
- * @param query.cookie 登录 Cookie
- * @param query.openid 微信/QQ openid (可选)
- * @param query.refresh_token 刷新令牌 (可选)
- */
-export default function login_refresh(query?: {
+export interface LoginRefreshQuery {
     cookie?: any;
     openid?: string;
     refresh_token?: string;
     refresh_key?: string;
-}, req?: typeof request): Promise<ApiResponse<{
+    guid?: string;
+}
+export interface LoginRefreshBody {
     code: number;
-    data: any;
+    musickey?: string;
     cookieStr: string;
-}>>;
+    expiresAt?: number;
+    data?: any;
+    message?: string;
+}
+/**
+ * 刷新登录凭证。
+ *
+ * QQ 音乐不同登录入口的续期接口并不一样：
+ * - 手机 QQ / QQ 互联网页扫码拿到的是 `uin + qm_keyst`，续期走
+ *   `QQConnectLogin.LoginServer/QQLogin`（带 `expired_in` 与旧 `musickey`），
+ *   这是上游长期使用的稳定路径；
+ * - QQ 音乐 App / 微信等移动端登录会额外拿到 `refresh_token` / `refresh_key`，
+ *   续期走 `music.login.LoginServer/Login` 的 refresh-token 流程。
+ *
+ * 旧实现无条件走后者，网页扫码的 Cookie 没有 refresh_token，续期会失败，
+ * 账号随后被判失效。这里先走 QQLogin，再回退到 refresh-token 流程。
+ *
+ * @param query.cookie 登录 Cookie
+ * @param query.openid 微信/QQ openid (可选)
+ * @param query.refresh_token 刷新令牌 (可选)
+ * @param query.refresh_key 刷新密钥 (可选)
+ * @param query.guid 设备标识；缺省从 Cookie/账号派生，保持稳定
+ */
+export default function login_refresh(query?: LoginRefreshQuery, req?: typeof request): Promise<ApiResponse<LoginRefreshBody>>;