koishi-plugin-rocom 1.0.18 → 1.0.19

package/lib/client.js

@@ -1,12 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RocomClient = void 0;
+exports.RocomClient = exports.isObject = void 0;
+exports.inheritGoodsMapping = inheritGoodsMapping;
 const koishi_1 = require("koishi");
+const async_control_1 = require("./async-control");
 const logger = new koishi_1.Logger('rocom-client');
 // ingame 异步任务状态分类（来自服务端 /ingame/tasks/{task_id} 返回的 status 字段）
 const INGAME_PENDING_STATUSES = ['queued', 'pending', 'running', 'processing', 'accepted'];
 const INGAME_FAILED_STATUSES = ['failed', 'error', 'timeout', 'cancelled', 'canceled'];
 const INGAME_COMPLETED_STATUSES = ['done', 'success', 'succeeded', 'completed', 'finished'];
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+exports.isObject = isObject;
+// 每剥离一层 envelope 时继承 goods_mapping，避免只改商品渲染后拿不到名称/图标（上游 v4.1.0）。
+function inheritGoodsMapping(parent, child) {
+    const mapping = child._goods_mapping ?? child.goods_mapping
+        ?? parent._goods_mapping ?? parent.goods_mapping;
+    return mapping === undefined ? { ...child } : { ...child, _goods_mapping: mapping };
+}
 class RocomClient {
     baseUrl;
     apiKey;
@@ -23,6 +33,12 @@ class RocomClient {
             return '';
         return uid.trim().replace(/[^a-zA-Z0-9_\- \u4e00-\u9fa5]/g, '').trim();
     }
+    // HTTP/任务 envelope 的 goods_mapping 复制到业务对象，供商品名称与图标解析。
+    attachGoodsMapping(resp, data) {
+        if ((0, exports.isObject)(resp) && (0, exports.isObject)(data))
+            return inheritGoodsMapping(resp, data);
+        return data;
+    }
     wegameHeaders(fwToken = '', userIdentifier = '', clientType = '', clientId = '', includeApiKey = true) {
         const headers = {};
         if (includeApiKey && this.apiKey)
@@ -192,6 +208,7 @@ class RocomClient {
                 headers,
                 params,
                 timeout: this.timeout,
+                signal: options?.signal,
             });
             if (resp?.code !== 0) {
                 this.setLastError(resp?.message || '接口返回异常');
@@ -201,7 +218,7 @@ class RocomClient {
                 }
                 return null;
             }
-            return resp?.data ?? {};
+            return this.attachGoodsMapping(resp, resp?.data ?? {});
         }
         catch (e) {
             const message = this.formatHttpError(e);
@@ -219,12 +236,13 @@ class RocomClient {
             return null;
         }
     }
-    async post(ctx, path, headers, json, params) {
+    async post(ctx, path, headers, json, params, signal) {
         try {
             const resp = await ctx.http.post(`${this.baseUrl}${path}`, json, {
                 headers,
                 params,
                 timeout: this.timeout,
+                signal,
             });
             if (resp?.code !== 0) {
                 this.setLastError(resp?.message || '接口返回异常');
@@ -232,7 +250,7 @@ class RocomClient {
                 this.logRequestFailureDetails('POST', path, headers, params, json, resp);
                 return null;
             }
-            return resp?.data ?? {};
+            return this.attachGoodsMapping(resp, resp?.data ?? {});
         }
         catch (e) {
             const message = this.formatHttpError(e);
@@ -263,7 +281,7 @@ class RocomClient {
                 this.logRequestFailureDetails('DELETE', path, headers, params, undefined, resp);
                 return null;
             }
-            return resp?.data ?? {};
+            return this.attachGoodsMapping(resp, resp?.data ?? {});
         }
         catch (e) {
             const message = this.formatHttpError(e);
@@ -287,14 +305,16 @@ class RocomClient {
                 headers,
                 params: options.params,
                 data: options.json,
-                timeout: this.timeout,
+                timeout: Math.max(this.timeout, Number(options.json?.wait_ms ?? options.params?.wait_ms ?? 0) + 2000),
+                signal: options.signal,
                 validateStatus: () => true,
             });
-            const status = Number(response?.status ?? response?.statusCode ?? 200);
+            const rawStatus = Number(response?.status);
+            const status = Number.isFinite(rawStatus) ? rawStatus : null;
             const body = response?.data !== undefined ? response.data : response;
             if (body?.code !== undefined && body.code !== 0) {
                 const rawMessage = body.message || body.msg || '接口返回异常';
-                const message = !acceptedStatuses.includes(status)
+                const message = status !== null && !acceptedStatuses.includes(status)
                     ? `HTTP ${status}: ${rawMessage}`
                     : rawMessage;
                 this.setLastError(message);
@@ -303,9 +323,9 @@ class RocomClient {
                 }
                 return { status: null, data: null };
             }
-            const data = body?.code !== undefined ? (body.data ?? {}) : (body ?? {});
-            if (!acceptedStatuses.includes(status)) {
-                this.setLastError(`HTTP ${status}`);
+            const data = body?.code !== undefined ? this.attachGoodsMapping(body, body.data ?? {}) : (body ?? {});
+            if (status === null || !acceptedStatuses.includes(status)) {
+                this.setLastError(status === null ? 'HTTP 响应缺少状态码' : `HTTP ${status}`);
                 if (!options.silentFailureDetails) {
                     this.logRequestFailureDetails(method, path, headers, options.params, options.json, response);
                 }
@@ -324,18 +344,21 @@ class RocomClient {
     }
     async requestIngameWithFallback(ctx, path, payload, options = {}) {
         const acceptedStatuses = options.acceptedStatuses || [200, 202];
+        const auth = options.auth || {};
         const requestOnce = async (includeApiKey, silentFailureDetails) => {
-            const headers = this.wegameHeaders('', '', '', '', includeApiKey);
+            const headers = this.wegameHeaders(auth.fwToken || '', auth.userIdentifier || '', '', '', includeApiKey);
             let result = await this.requestWithStatus(ctx, 'POST', path, headers, {
                 json: payload,
                 acceptedStatuses,
                 silentFailureDetails,
+                signal: options.signal,
             });
-            if (result.status === null) {
+            if (result.status === null && !options.signal?.aborted) {
                 result = await this.requestWithStatus(ctx, 'GET', path, headers, {
                     params: payload,
                     acceptedStatuses,
                     silentFailureDetails,
+                    signal: options.signal,
                 });
             }
             return result;
@@ -343,15 +366,15 @@ class RocomClient {
         let result = await requestOnce(false, Boolean(this.apiKey));
         if (result.status !== null)
             return { ...result, usedApiKey: false };
-        if (this.shouldRetryIngameWithApiKey(this.getLastError())) {
+        if (!options.signal?.aborted && this.shouldRetryIngameWithApiKey(this.getLastError())) {
             result = await requestOnce(true, false);
             if (result.status !== null)
                 return { ...result, usedApiKey: true };
         }
         return { status: null, data: null, usedApiKey: false };
     }
-    async getIngameTask(ctx, taskId, includeApiKey = true) {
-        return this.requestWithStatus(ctx, 'GET', `/api/v1/games/rocom/ingame/tasks/${taskId}`, this.wegameHeaders('', '', '', '', includeApiKey), { acceptedStatuses: [200, 202] });
+    async getIngameTask(ctx, taskId, includeApiKey = true, auth = {}, signal) {
+        return this.requestWithStatus(ctx, 'GET', `/api/v1/games/rocom/ingame/tasks/${taskId}`, this.wegameHeaders(auth.fwToken || '', auth.userIdentifier || '', '', '', includeApiKey), { acceptedStatuses: [200, 202], signal });
     }
     static normalizeTaskStatus(value) {
         return String(value ?? '').trim().toLowerCase();
@@ -361,7 +384,8 @@ class RocomClient {
     }
     // 判断一份 payload 是否为“已完成的业务结果”（而非排队占位）。
     // 家园接口完成时返回 rows/home_info；玩家、商店完成时返回 source/title/rows；
-    // 家园详情（pet/data）完成时返回 npc_pets/npc_pet。
+    // 家园详情（pet/data）完成时返回 npc_pets/npc_pet；
+    // v4.1 玩家嵌套结构返回 player_info/player_card_brief_info，实时商人返回 goods/shop/meta。
     static isCompletedGatewayPayload(payload) {
         if (!payload || typeof payload !== 'object')
             return false;
@@ -369,26 +393,46 @@ class RocomClient {
             return true;
         if (payload.home_info !== undefined)
             return true;
-        if (payload.source !== undefined)
-            return true;
         if (Array.isArray(payload.npc_pets))
             return true;
         if (payload.npc_pet && typeof payload.npc_pet === 'object')
             return true;
-        if (String(payload.title || '').trim())
+        if (payload.player_info && typeof payload.player_info === 'object')
+            return true;
+        if (payload.player_card_brief_info && typeof payload.player_card_brief_info === 'object')
+            return true;
+        if (Array.isArray(payload.goods))
+            return true;
+        if (payload.shop && typeof payload.shop === 'object')
+            return true;
+        if (payload.meta && typeof payload.meta === 'object' && Array.isArray(payload.goods))
             return true;
         return false;
     }
-    static extractCompletedIngamePayload(payload) {
-        if (!payload || typeof payload !== 'object')
-            return null;
+    static inspectIngamePayload(payload, depth = 0, completed = false) {
+        if (!(0, exports.isObject)(payload) || depth > 6)
+            return { error: '任务返回结构无法解析' };
+        const state = RocomClient.normalizeTaskStatus(payload.status);
+        if (INGAME_FAILED_STATUSES.includes(state))
+            return { error: RocomClient.taskErrorMessage(payload, state) };
+        if (INGAME_PENDING_STATUSES.includes(state))
+            return { pending: true };
+        if (state && !INGAME_COMPLETED_STATUSES.includes(state))
+            return { error: 'Ingame 任务状态异常：' + state };
+        completed ||= INGAME_COMPLETED_STATUSES.includes(state);
         if (RocomClient.isCompletedGatewayPayload(payload))
-            return payload;
-        if (RocomClient.isCompletedGatewayPayload(payload.result))
-            return payload.result;
-        if (RocomClient.isCompletedGatewayPayload(payload.data))
-            return payload.data;
-        return null;
+            return { value: payload };
+        for (const key of ['result', 'data']) {
+            if ((0, exports.isObject)(payload[key]))
+                return RocomClient.inspectIngamePayload(inheritGoodsMapping(payload, payload[key]), depth + 1, completed);
+        }
+        if (completed)
+            return { error: '任务已完成但未返回可解析结果' };
+        if (state)
+            return { error: 'Ingame 任务状态异常：' + state };
+        if (RocomClient.extractTaskId(payload))
+            return { pending: true };
+        return { value: payload };
     }
     static taskErrorMessage(payload, fallbackStatus = '') {
         const candidates = [
@@ -405,64 +449,65 @@ class RocomClient {
     }
     // 排队等候轮询：把 ingame 接口提交后返回的 202（task_id/status=queued）轮询到出结果或超时。
     // 入参 first 是首请求拿到的 { status, data, usedApiKey }。
-    async pollIngameTask(ctx, first, options, labels) {
-        const { status, data, usedApiKey } = first;
-        // 服务端在 wait_ms 内已直接返回业务结果，或任务壳里已经带了完成结果。
-        const initialCompletedPayload = RocomClient.extractCompletedIngamePayload(data);
-        if (status !== null && initialCompletedPayload)
-            return initialCompletedPayload;
-        const taskId = RocomClient.extractTaskId(data);
+    async pollIngameTask(ctx, first, options, labels, auth = {}) {
+        if (first.status === null || options.signal?.aborted)
+            return null;
+        const initial = RocomClient.inspectIngamePayload(first.data);
+        if (initial.error) {
+            this.setLastError(initial.error);
+            return null;
+        }
+        const taskId = RocomClient.extractTaskId(first.data);
+        if (!initial.pending && initial.value !== undefined && first.status !== 202)
+            return initial.value;
         if (!taskId) {
-            if (status === 202)
-                this.setLastError(labels.queuedNoTaskId);
-            // 既不是任务也不是已知完成结构：把原始 data 透传给上层兼容旧逻辑。
-            return status === null ? null : data;
-        }
-        // 已进入队列，回调通知“排队中”。
-        if (typeof options.onQueued === 'function') {
-            try {
-                await options.onQueued(taskId);
-            }
-            catch (e) {
-                logger.warn(`ingame 排队提示回调失败: ${e}`);
-            }
+            this.setLastError(labels.queuedNoTaskId);
+            return null;
         }
-        const intervalMs = Math.max(300, Number(options.intervalMs) || 3000);
-        const timeoutMs = Math.max(intervalMs, Number(options.timeoutMs) || 180000);
-        const startedAt = Date.now();
-        let lastStatus = RocomClient.normalizeTaskStatus(data?.status);
-        while (Date.now() - startedAt < timeoutMs) {
-            if (lastStatus && INGAME_FAILED_STATUSES.includes(lastStatus)) {
-                this.setLastError(RocomClient.taskErrorMessage(data, lastStatus));
-                return null;
-            }
-            await new Promise(resolve => setTimeout(resolve, intervalMs));
-            const task = await this.getIngameTask(ctx, taskId, usedApiKey);
-            if (task.status === null)
-                return null;
-            const completedPayload = RocomClient.extractCompletedIngamePayload(task.data);
-            if (completedPayload)
-                return completedPayload;
-            lastStatus = RocomClient.normalizeTaskStatus(task.data?.status);
-            if (INGAME_FAILED_STATUSES.includes(lastStatus)) {
-                this.setLastError(RocomClient.taskErrorMessage(task.data, lastStatus));
-                return null;
-            }
-            // 状态标记完成，但结果可能嵌套在 result/data 中。
-            if (INGAME_COMPLETED_STATUSES.includes(lastStatus)) {
-                this.setLastError(`Ingame 任务已完成但未返回可解析结果：${taskId}`);
-                return null;
-            }
-            if (lastStatus && !INGAME_PENDING_STATUSES.includes(lastStatus)) {
-                this.setLastError(`Ingame 任务状态异常：${lastStatus}`);
+        try {
+            return await (0, async_control_1.withDeadline)(Math.max(1, Number(options.timeoutMs) || 180000), options.signal, async (signal) => {
+                if (options.onQueued) {
+                    try {
+                        await options.onQueued(taskId);
+                    }
+                    catch (error) {
+                        logger.warn('排队提示失败: ' + error);
+                    }
+                }
+                while (!signal.aborted) {
+                    await (0, async_control_1.delay)(Math.max(300, Number(options.intervalMs) || 3000), signal);
+                    const task = await this.getIngameTask(ctx, taskId, first.usedApiKey, auth, signal);
+                    signal.throwIfAborted();
+                    if (task.status === null)
+                        return null;
+                    const result = RocomClient.inspectIngamePayload(task.data);
+                    if (result.error) {
+                        this.setLastError(result.error);
+                        return null;
+                    }
+                    if (!result.pending && result.value !== undefined && task.status !== 202)
+                        return result.value;
+                }
                 return null;
-            }
-            // 既无 task_id 也无状态，说明拿到的就是裸结果。
-            if (!RocomClient.extractTaskId(task.data) && !lastStatus)
-                return task.data;
+            });
+        }
+        catch {
+            this.setLastError(options.signal?.aborted ? '查询已取消' : labels.stillQueued(taskId));
+            return null;
+        }
+    }
+    async queuedQuery(ctx, path, payload, options, labels) {
+        try {
+            return await (0, async_control_1.withDeadline)(Number(options.timeoutMs) || 180000, options.signal, async (signal) => {
+                const first = await this.requestIngameWithFallback(ctx, path, payload, { auth: options.auth, signal });
+                signal.throwIfAborted();
+                return this.pollIngameTask(ctx, first, { ...options, signal }, labels, options.auth);
+            });
+        }
+        catch {
+            this.setLastError(options.signal?.aborted ? '查询已取消' : '查询等待超时，请稍后重试');
+            return null;
         }
-        this.setLastError(labels.stillQueued(taskId));
-        return null;
     }
     async qqQrLogin(ctx, userIdentifier) {
         const params = { client_type: 'bot', client_id: 'koishi', provider: 'rocom' };
@@ -562,39 +607,40 @@ class RocomClient {
             || Array.isArray(data.notes)
             || data.title
             || data.nickname
-            || data.uid);
+            || data.uid
+            || (data.player_info && typeof data.player_info === 'object')
+            || (data.player_card_brief_info && typeof data.player_card_brief_info === 'object'));
     }
-    async ingamePlayerSearch(ctx, uid) {
+    async ingamePlayerSearch(ctx, uid, options = {}) {
         const sanitizedUid = this.sanitizeUid(uid);
-        if (!sanitizedUid) {
+        if (!sanitizedUid && !options.auth?.fwToken) {
             this.setLastError('UID 不能为空');
             return null;
         }
         const path = '/api/v1/games/rocom/ingame/player/search';
-        const payload = { uid: sanitizedUid, wait_ms: 5000 };
-        const { status, data, usedApiKey } = await this.requestIngameWithFallback(ctx, path, payload);
-        if (status === 200 && data && this.isIngamePlayerPayload(data))
-            return data;
-        if (!data)
+        const payload = { ...(sanitizedUid ? { uid: sanitizedUid } : {}), wait_ms: Number(options.waitMs) || 5000 };
+        return this.queuedQuery(ctx, path, payload, options, {
+            queuedNoTaskId: '玩家搜索任务已入队，但未返回 task_id',
+            stillQueued: (taskId) => `玩家搜索任务仍在排队，请稍后重试（task_id: ${taskId}）`,
+        });
+    }
+    // 玩家名片（上游 v4.1.0）：需要补充收集数/名片图时按需查询。
+    async ingamePlayerCard(ctx, uid, options = {}) {
+        const sanitizedUid = this.sanitizeUid(uid);
+        if (!sanitizedUid && !options.auth?.fwToken) {
+            this.setLastError('UID 不能为空');
             return null;
-        if (this.isIngamePlayerPayload(data))
-            return data;
-        const taskId = data.task_id || data.taskId || data.taskID;
-        if (!taskId) {
-            if (status === 202)
-                this.setLastError('玩家搜索任务已入队，但未返回 task_id');
-            return data;
-        }
-        for (let i = 0; i < 8; i++) {
-            await new Promise(resolve => setTimeout(resolve, 1000));
-            const task = await this.getIngameTask(ctx, taskId, usedApiKey);
-            if (task.status === 200)
-                return task.data;
-            if (task.status === null)
-                return null;
         }
-        this.setLastError('Player search task is still queued, please retry later (task_id: ' + taskId + ')');
-        return null;
+        const path = '/api/v1/games/rocom/ingame/player/card';
+        const payload = {
+            ...(sanitizedUid ? { uid: sanitizedUid } : {}),
+            wait_ms: Number(options.waitMs) || 5000,
+            source: options.source || 'friend',
+        };
+        return this.queuedQuery(ctx, path, payload, options, {
+            queuedNoTaskId: '玩家名片任务已入队，但未返回 task_id',
+            stillQueued: (taskId) => `玩家名片任务仍在排队，请稍后重试（task_id: ${taskId}）`,
+        });
     }
     async getPets(ctx, fwToken, petSubset = 0, pageNo = 1, pageSize = 10, userIdentifier = '') {
         const params = { pet_subset: petSubset, page_no: pageNo, page_size: pageSize };
@@ -610,11 +656,26 @@ class RocomClient {
         const params = { page_no: Math.max(pageNo, 1), refresh: 'false' };
         return this.get(ctx, '/api/v1/games/rocom/exchange/posters', this.wegameHeaders(fwToken, userIdentifier), params);
     }
-    async getMerchantInfo(ctx, refresh = false) {
-        return this.get(ctx, '/api/v1/games/rocom/merchant/info', this.wegameHeaders(), {
+    // 远行商人：优先实时 ingame 接口，失败/协议无法识别时回退旧 merchant/info。
+    // 成功的空商品列表（goods: []）视为有效结果，不触发回退。
+    async getMerchantInfo(ctx, refresh = false, options = {}) {
+        const live = await this.ingameMerchantInfo(ctx, null, options);
+        if (live && typeof live === 'object' && (Array.isArray(live.goods)
+            || Array.isArray(live.merchantActivities)
+            || Array.isArray(live.merchant_activities))) {
+            return { ...live, _source: 'live' };
+        }
+        if (options.signal?.aborted)
+            return null;
+        const legacy = await this.get(ctx, '/api/v1/games/rocom/merchant/info', this.wegameHeaders(options.auth?.fwToken, options.auth?.userIdentifier), {
             refresh: refresh ? 'true' : 'false',
             random_goods: 'all',
-        });
+        }, { signal: options.signal });
+        if (legacy && typeof legacy === 'object') {
+            logger.warn('[Rocom] ingame/merchant/info 不可用，已回退 merchant/info');
+            return { ...legacy, _source: 'legacy' };
+        }
+        return null;
     }
     async queryPetSize(ctx, diameter, weight, pool = 'magic', pageNo = 1, pageSize = 30, userIdentifier = '') {
         const params = this.scopedParams({
@@ -627,6 +688,55 @@ class RocomClient {
         }, userIdentifier);
         return this.get(ctx, '/api/v1/games/rocom/wiki/pet-size/query', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), params);
     }
+    // 后端查蛋（上游 v3.8.0）：按展示身高/体重查询，参数名是 height/weight。
+    async searchEggBySize(ctx, heightMeters, weightKg, pageNo = 1, pageSize = 30, userIdentifier = '') {
+        const params = this.scopedParams({
+            height: heightMeters,
+            weight: weightKg,
+            page_no: Math.max(Number(pageNo) || 1, 1),
+            page_size: Math.min(Math.max(Number(pageSize) || 30, 1), 100),
+        }, userIdentifier);
+        return this.get(ctx, '/api/v1/games/rocom/egg/search', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), params);
+    }
+    // 异色/炫彩收集排行榜（上游 v3.9.0）。
+    async getPetCollectionRanking(ctx, rankType, limit = 10, uid = '', options = {}) {
+        if (!['shining', 'glass'].includes(rankType)) {
+            this.setLastError('无效榜单类型');
+            return null;
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+            this.setLastError('无效数量');
+            return null;
+        }
+        const params = { limit, resolve_names: '1' };
+        if (uid)
+            params.uid = this.sanitizeUid(uid);
+        return this.get(ctx, `/api/v1/games/rocom/ingame/player/card/pet-stats/rankings/${rankType}`, this.wegameHeaders('', options.userIdentifier || '', 'bot', 'koishi'), this.scopedParams(params, options.userIdentifier || ''));
+    }
+    // 阵容分享码解析与历史查询（上游 v3.9.0）。
+    async parseShareCode(ctx, shareCode, userIdentifier = '') {
+        const code = String(shareCode || '').trim();
+        if (!code) {
+            this.setLastError('分享码不能为空');
+            return null;
+        }
+        return this.post(ctx, '/api/v1/games/rocom/tools/share-code/parse', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), { share_code: code }, this.scopedParams({}, userIdentifier));
+    }
+    async getShareCodeRecords(ctx, options = {}, userIdentifier = '') {
+        const params = {
+            page_no: Math.max(Number(options.pageNo) || 1, 1),
+            page_size: Math.min(Math.max(Number(options.pageSize) || 20, 1), 100),
+        };
+        if (options.shareCode)
+            params.share_code = String(options.shareCode).trim();
+        if (options.hash)
+            params.hash = String(options.hash).trim();
+        if (options.modeId !== undefined)
+            params.mode_id = options.modeId;
+        if (options.magicId !== undefined)
+            params.magic_id = options.magicId;
+        return this.get(ctx, '/api/v1/games/rocom/tools/share-code/records', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams(params, userIdentifier));
+    }
     async getActivitiesInfo(ctx, refresh = false, userIdentifier = '') {
         return this.get(ctx, '/api/v1/games/rocom/activities/info', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams({ refresh: refresh ? 'true' : 'false' }, userIdentifier));
     }
@@ -636,8 +746,8 @@ class RocomClient {
     async getAnnouncementList(ctx, params = {}, userIdentifier = '') {
         return this.get(ctx, '/api/v1/games/rocom/announcement/list', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams(params, userIdentifier));
     }
-    async getLatestAnnouncement(ctx, params = {}, userIdentifier = '') {
-        return this.get(ctx, '/api/v1/games/rocom/announcement/latest', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams(params, userIdentifier));
+    async getLatestAnnouncement(ctx, params = {}, userIdentifier = '', signal) {
+        return this.get(ctx, '/api/v1/games/rocom/announcement/latest', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams(params, userIdentifier), { signal });
     }
     async getAnnouncementDetail(ctx, threadId, userIdentifier = '') {
         return this.get(ctx, '/api/v1/games/rocom/announcement/detail', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams({ thread_id: threadId }, userIdentifier));
@@ -684,41 +794,50 @@ class RocomClient {
     }
     async ingameHomeInfo(ctx, uid, options = {}) {
         const sanitizedUid = this.sanitizeUid(uid);
-        if (!sanitizedUid) {
+        if (!sanitizedUid && !options.auth?.fwToken) {
             this.setLastError('UID 不能为空');
             return null;
         }
         const waitMs = Number(options.waitMs) || 5000;
         const path = '/api/v1/games/rocom/ingame/home/info';
-        const payload = { uid: sanitizedUid, wait_ms: waitMs };
-        const first = await this.requestIngameWithFallback(ctx, path, payload);
-        return this.pollIngameTask(ctx, first, options, {
+        const payload = { wait_ms: waitMs };
+        if (sanitizedUid)
+            payload.uid = sanitizedUid;
+        return this.queuedQuery(ctx, path, payload, options, {
             queuedNoTaskId: '家园查询任务已入队，但未返回 task_id',
             stillQueued: (taskId) => `家园查询任务仍在排队，请稍后重试（task_id: ${taskId}）`,
         });
     }
-    async ingameMerchantInfo(ctx, shopId) {
-        const params = { shop_id: shopId };
-        const { status, data } = await this.requestIngameWithFallback(ctx, '/api/v1/games/rocom/ingame/merchant/info', params);
-        return status === null ? null : data;
+    // 远行商人实时接口（上游 v4.1.0）：优先 ingame live，返回 goods/shop/meta 或任务轮询结果。
+    // 未指定商店时不传 shop_id；调用方负责在新接口不可用时回退旧 merchant/info。
+    async ingameMerchantInfo(ctx, shopId, options = {}) {
+        const waitMs = Number(options.waitMs) || 5000;
+        const payload = { wait_ms: waitMs };
+        if (shopId !== undefined && shopId !== null && String(shopId) !== '')
+            payload.shop_id = shopId;
+        return this.queuedQuery(ctx, '/api/v1/games/rocom/ingame/merchant/info', payload, options, {
+            queuedNoTaskId: '远行商人任务已入队，但未返回 task_id',
+            stillQueued: (taskId) => `远行商人任务仍在排队，请稍后重试（task_id: ${taskId}）`,
+        });
     }
     // 家园详情：批量或单只查询家园摆放精灵的完整 ingame 数据（上游 v3.6.1）。
     // UID 参数名为 target_uin；单只查询需同时提供 pet_gid 和 npc_id。
     async ingamePetData(ctx, uid, extras = {}, options = {}) {
         const sanitizedUid = this.sanitizeUid(uid);
-        if (!sanitizedUid) {
+        if (!sanitizedUid && !options.auth?.fwToken) {
             this.setLastError('UID 不能为空');
             return null;
         }
         const waitMs = Number(options.waitMs) || 20000;
-        const payload = { target_uin: sanitizedUid, wait_ms: waitMs };
+        const payload = { wait_ms: waitMs };
+        if (sanitizedUid)
+            payload.target_uin = sanitizedUid;
         if (extras.petGid !== undefined && extras.petGid !== null && String(extras.petGid) !== '')
             payload.pet_gid = extras.petGid;
         if (extras.npcId !== undefined && extras.npcId !== null && String(extras.npcId) !== '')
             payload.npc_id = extras.npcId;
         const path = '/api/v1/games/rocom/ingame/pet/data';
-        const first = await this.requestIngameWithFallback(ctx, path, payload);
-        return this.pollIngameTask(ctx, first, options, {
+        return this.queuedQuery(ctx, path, payload, options, {
             queuedNoTaskId: '家园详情任务已入队，但未返回 task_id',
             stillQueued: (taskId) => `家园详情任务仍在排队，请稍后重试（task_id: ${taskId}）`,
         });