koishi-plugin-rocom 1.0.13 → 1.0.17

package/lib/commands/merchant.js

@@ -549,6 +549,7 @@ async function checkMerchantSubscriptions(deps) {
 function register(deps) {
     const { ctx, config, client, merchantSubMgr } = deps;
     ctx.command(TEXT.merchant, '\u67e5\u770b\u8fdc\u884c\u5546\u4eba\u5546\u54c1')
+        .alias('yxsr')
         .action(async ({ session }) => {
         const res = await client.getMerchantInfo(ctx, true);
         if (!res)
@@ -619,6 +620,14 @@ function register(deps) {
         return `远行商人订阅检查完成：订阅 ${result.subscriptions} 条，命中 ${result.matched} 条，推送 ${result.pushed} 条。`;
     });
     if (config.merchantSubscriptionEnabled) {
+        // 上游 v3.1.0：检查前加入 ±30s 随机延迟，降低刷新窗口和并发请求冲突。
+        const MERCHANT_JITTER_MS = 30000;
+        const runCheckWithJitter = () => {
+            const jitter = Math.floor(Math.random() * MERCHANT_JITTER_MS);
+            setTimeout(() => {
+                checkMerchantSubscriptions(deps).catch(err => logger.warn(`远行商人订阅检查失败: ${err}`));
+            }, jitter);
+        };
         if (config.merchantCheckMode === 'times' && config.merchantCheckTimes.length > 0) {
             let lastMerchantCheckKey = '';
             ctx.setInterval(async () => {
@@ -630,12 +639,12 @@ function register(deps) {
                 if (checkKey === lastMerchantCheckKey)
                     return;
                 lastMerchantCheckKey = checkKey;
-                await checkMerchantSubscriptions(deps);
+                runCheckWithJitter();
             }, 60000);
         }
         else {
             ctx.setInterval(async () => {
-                await checkMerchantSubscriptions(deps);
+                runCheckWithJitter();
             }, config.merchantCheckInterval);
         }
     }

package/lib/commands/query.js

@@ -8,6 +8,7 @@ const koishi_1 = require("koishi");
 const account_1 = require("./account");
 const send_image_1 = require("../send-image");
 const subscription_send_1 = require("../subscription-send");
+const pet_data_service_1 = require("../pet-data-service");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const logger = new koishi_1.Logger('rocom-query');
@@ -874,7 +875,24 @@ function extractHomePet(deps, raw, index, guard = false) {
     const eggReady = hasEgg || (predictedEggTime > 0 && nowTs >= predictedEggTime);
     const feedRound = Number(homePet.feed_round || raw.feed_round || 0) || 0;
     const gender = Number(display.gender || raw.gender || 0) || 0;
-    const mutationType = Number(display.mutation_type || raw.mutation_type || homePet.mutation_type || 0) || 0;
+    let mutationType = Number(display.mutation_type || raw.mutation_type || homePet.mutation_type || 0) || 0;
+    // 上游 v3.4.0：mutation_type 缺失时按 real_speciality_ids 识别变体（103=异色、502=炫彩、两者兼有=异色炫彩）。
+    if (!mutationType) {
+        const specialityValues = [];
+        for (const value of [homePet.real_speciality_ids, raw.real_speciality_ids, homePet.speciality_id, raw.speciality_id]) {
+            if (Array.isArray(value))
+                specialityValues.push(...value);
+            else if (value !== undefined && value !== null && value !== '')
+                specialityValues.push(value);
+        }
+        const specialityIds = new Set(specialityValues.map(value => String(value).trim()).filter(Boolean));
+        if (specialityIds.has('103') && specialityIds.has('502'))
+            mutationType = 9;
+        else if (specialityIds.has('103'))
+            mutationType = 1;
+        else if (specialityIds.has('502'))
+            mutationType = 8;
+    }
     const isMale = gender === 1;
     const status = homePet.status ?? raw.status;
     const isGuard = guard || Boolean(raw.is_guard || raw.guard) || ['2', 'guard', '守卫'].includes(String(status).toLowerCase());
@@ -923,6 +941,9 @@ function extractHomePet(deps, raw, index, guard = false) {
         statusText,
         statusClass,
         note,
+        hasEgg,
+        eggReady,
+        eggTime: predictedEggTime || 0,
         inspireReady: eggReady,
         readyAt: predictedEggTime || 0,
         gender,
@@ -1269,13 +1290,33 @@ async function resolveHomeUid(deps, session, uid = '') {
         return targetUid;
     return String(deps.userMgr.getPrimaryBinding(session?.userId || '')?.role_id || '');
 }
+const HOME_SUB_TEXT = {
+    garden: {
+        kindText: '菜园作物',
+        actionText: '成熟',
+        subscribedHint: '的家园菜园提醒：首个成熟和全部成熟时各推送一次。',
+        needUidHint: '请提供玩家 UID，或先完成绑定后再订阅家园菜园。',
+    },
+    inspiration: {
+        kindText: '精灵灵感',
+        actionText: '完成',
+        subscribedHint: '的家园精灵灵感提醒：首个完成和全部完成时各推送一次。',
+        needUidHint: '请提供玩家 UID，或先完成绑定后再订阅家园灵感。',
+    },
+    egg: {
+        kindText: '精灵生蛋',
+        actionText: '可领取',
+        subscribedHint: '的家园精灵生蛋提醒：首个可领取和全部可领取时各推送一次。',
+        needUidHint: '请提供玩家 UID，或先完成绑定后再订阅家园生蛋。',
+    },
+};
 async function subscribeHome(deps, session, uid, kind) {
     const target = sessionTarget(session);
     if (!target.userId && !isBotAdmin(session, deps.config.adminUserIds))
         return '此指令仅限管理员使用。';
     const targetUid = await resolveHomeUid(deps, session, uid);
     if (!targetUid)
-        return kind === 'garden' ? '请提供玩家 UID，或先完成绑定后再订阅家园菜园。' : '请提供玩家 UID，或先完成绑定后再订阅家园灵感。';
+        return HOME_SUB_TEXT[kind].needUidHint;
     const key = homeSubscriptionKey(session, targetUid, kind);
     deps.homeSubMgr.upsert(key, {
         key,
@@ -1289,9 +1330,7 @@ async function subscribeHome(deps, session, uid, kind) {
         notify_state: {},
         updated_at: Math.floor(Date.now() / 1000),
     });
-    return kind === 'garden'
-        ? `已订阅 UID ${targetUid} 的家园菜园提醒：首个成熟和全部成熟时各推送一次。`
-        : `已订阅 UID ${targetUid} 的家园精灵灵感提醒：首个完成和全部完成时各推送一次。`;
+    return `已订阅 UID ${targetUid} ${HOME_SUB_TEXT[kind].subscribedHint}`;
 }
 function homeSubscriptionState(data, kind) {
     if (kind === 'garden') {
@@ -1300,14 +1339,19 @@ function homeSubscriptionState(data, kind) {
         const names = readyItems.map((item) => `田地${item.landIndex} ${item.plantName}`);
         return { items, readyItems, names };
     }
+    if (kind === 'egg') {
+        const items = [...(data.indoorPets || []), ...(data.guardPets || [])].filter((item) => item.eggTime || item.hasEgg);
+        const readyItems = items.filter((item) => item.eggReady);
+        const names = readyItems.map((item) => item.name || '未知精灵');
+        return { items, readyItems, names };
+    }
     const items = [...(data.indoorPets || []), ...(data.guardPets || [])].filter((item) => item.readyAt);
     const readyItems = items.filter((item) => item.inspireReady);
     const names = readyItems.map((item) => item.name || '未知精灵');
     return { items, readyItems, names };
 }
 function homeSubscriptionMessage(uid, kind, level, totalCount, readyItems, names) {
-    const kindText = kind === 'garden' ? '菜园作物' : '精灵灵感';
-    const actionText = kind === 'garden' ? '成熟' : '完成';
+    const { kindText, actionText } = HOME_SUB_TEXT[kind];
     const levelText = level === 'first' ? '首个' : '全部';
     return [
         `家园${kindText}${levelText}${actionText}提醒：${uid}`,
@@ -1321,7 +1365,7 @@ async function checkHomeSubscriptions(deps) {
     let checkedCount = 0;
     let pushedCount = 0;
     for (const [key, sub] of Object.entries(subs)) {
-        if (!sub.uid || !['garden', 'inspiration'].includes(sub.kind))
+        if (!sub.uid || !['garden', 'inspiration', 'egg'].includes(sub.kind))
             continue;
         checkedCount++;
         if (!cache.has(sub.uid)) {
@@ -1830,6 +1874,92 @@ function register(deps) {
             return `家园查询失败：${client.getLastErrorBrief()}`;
         await sendImage(deps, session, 'home', buildHomeRenderData(deps, res, targetUid), `【洛克家园】UID ${targetUid}`);
     });
+    ctx.command('洛克').subcommand('.家园详情 [uid:string] [petGid:string] [npcId:string]', '查询家园摆放精灵的完整 ingame 数据')
+        .alias('洛克家园详情')
+        .alias('家园详情')
+        .alias('洛克精灵数据')
+        .alias('精灵数据')
+        .action(async ({ session }, uid = '', petGid = '', npcId = '') => {
+        const petGidText = String(petGid || '').trim();
+        const npcIdText = String(npcId || '').trim();
+        if ((petGidText && !npcIdText) || (npcIdText && !petGidText)) {
+            return [
+                '请同时提供 pet_gid 和 npc_id。用法：洛克.家园详情 <UID> 或 洛克.家园详情 <UID> <pet_gid> <npc_id>',
+                '提示：该接口依赖目标玩家在线，npc_id 也可以使用 furniture_guid。',
+            ].join('\n');
+        }
+        let targetUid = String(uid || '').trim();
+        if (!targetUid) {
+            const binding = deps.userMgr.getPrimaryBinding(session.userId);
+            targetUid = String(binding?.role_id || '');
+        }
+        if (!targetUid)
+            return '请提供玩家 UID，或先完成绑定后使用 洛克.家园详情。目标玩家需要在线。';
+        let queuedNotified = false;
+        const res = await client.ingamePetData(ctx, targetUid, { petGid: petGidText, npcId: npcIdText }, {
+            waitMs: 20000,
+            intervalMs: deps.config.homeQueryPollIntervalMs,
+            timeoutMs: deps.config.homeQueryTimeoutMs,
+            onQueued: async () => {
+                if (queuedNotified)
+                    return;
+                queuedNotified = true;
+                await session?.send?.(`UID ${targetUid} 的家园详情查询已进入队列，正在等待游戏侧返回，请稍候…`);
+            },
+        });
+        if (!res) {
+            return [
+                `家园详情查询失败：${client.getLastErrorBrief()}`,
+                '提示：该接口需要目标玩家在线，且目标家园可访问；离线时通常无法获取完整数据。',
+            ].join('\n');
+        }
+        const lowBandwidth = Boolean(deps.config.lowBandwidthMode);
+        // Wiki 补全（技能详情/精灵体重范围）；低带宽模式跳过技能图标但仍取技能名。
+        const [optionsPayload, skillLookup, sizeLookup] = await Promise.all([
+            deps.wikiService.getOptionsPayload().catch(() => ({})),
+            (async () => {
+                const lookup = {};
+                const ids = (0, pet_data_service_1.petDataSkillIdsFromPayload)(res);
+                await Promise.all(ids.map(async (id) => {
+                    const detail = await deps.wikiService.getSkillDetailCached(id).catch(() => null);
+                    if (detail)
+                        lookup[id] = detail;
+                }));
+                return lookup;
+            })(),
+            (async () => {
+                const lookup = {};
+                const ids = (0, pet_data_service_1.petDataPetIdsFromPayload)(res);
+                await Promise.all(ids.map(async (id) => {
+                    const detail = await deps.wikiService.getPetDetailCached(id).catch(() => null);
+                    if (detail)
+                        lookup[id] = detail;
+                }));
+                return lookup;
+            })(),
+        ]);
+        const data = (0, pet_data_service_1.buildPetDataRenderData)(res, targetUid || '当前绑定', {
+            optionsPayload,
+            skillLookup,
+            sizeLookup,
+            singleQuery: Boolean(petGidText && npcIdText),
+            lowBandwidthMode: lowBandwidth,
+            baseUrl: deps.config.apiBaseUrl.replace(/\/$/, ''),
+        });
+        const fallbackLines = [
+            `家园详情 - UID ${data.uid}（${data.onlineText}）`,
+            data.notice,
+        ];
+        for (const pet of (data.pets || []).slice(0, 8)) {
+            fallbackLines.push(`${pet.index}. ${pet.name} Lv.${pet.level} #${pet.baseId} ${pet.variantText} 分贝 ${pet.voiceText || '--'}`);
+        }
+        if (!data.pets?.length)
+            fallbackLines.push(data.emptyText);
+        fallbackLines.push('');
+        fallbackLines.push('若服务器带宽过小导致生成超时，请在配置项打开低带宽模式。');
+        fallbackLines.push('低带宽模式开启后，家园详情将不再加载技能图标。');
+        await sendImage(deps, session, 'pet-data', data, fallbackLines.join('\n'));
+    });
     ctx.command('洛克').subcommand('.刷新面板 [uid:string]', '刷新指定 UID 的精灵面板缓存')
         .alias('洛克刷新面板')
         .alias('刷新面板')
@@ -1938,12 +2068,14 @@ function register(deps) {
         .action(async ({ session }, uid = '') => subscribeHome(deps, session, uid, 'garden'));
     ctx.command('订阅家园灵感 [uid:string]', '订阅指定 UID 的家园精灵灵感完成提醒')
         .action(async ({ session }, uid = '') => subscribeHome(deps, session, uid, 'inspiration'));
+    ctx.command('订阅家园生蛋 [uid:string]', '订阅指定 UID 的家园精灵生蛋提醒')
+        .action(async ({ session }, uid = '') => subscribeHome(deps, session, uid, 'egg'));
     ctx.command('取消订阅家园 [kind:string] [uid:string]', '取消当前会话的家园订阅')
         .action(async ({ session }, kind = '全部', uid = '') => {
         const target = sessionTarget(session);
         if (!target.userId && !isBotAdmin(session, deps.config.adminUserIds))
             return '此指令仅限管理员使用。';
-        const kindMap = { '菜园': 'garden', '灵感': 'inspiration', '全部': '', all: '', garden: 'garden', inspiration: 'inspiration' };
+        const kindMap = { '菜园': 'garden', '灵感': 'inspiration', '生蛋': 'egg', '全部': '', all: '', garden: 'garden', inspiration: 'inspiration', egg: 'egg' };
         const deleted = deps.homeSubMgr.deleteMatching(target, kindMap[String(kind || '全部')] ?? '', String(uid || '').trim());
         return deleted ? `已取消 ${deleted} 条家园订阅。` : '当前会话没有匹配的家园订阅。';
     });

package/lib/commands/tools.js

@@ -4,6 +4,7 @@ exports.register = register;
 const koishi_1 = require("koishi");
 const activities_service_1 = require("../activities-service");
 const send_image_1 = require("../send-image");
+const subscription_send_1 = require("../subscription-send");
 const logger = new koishi_1.Logger('rocom-tools');
 const activitiesService = new activities_service_1.ActivitiesService();
 function trimText(value) {
@@ -54,6 +55,70 @@ function firstArray(payload, keys) {
 function announcementId(item) {
     return trimText(item?.thread_id || item?.id);
 }
+function announcementTimestamp(item) {
+    for (const key of ['published_at_ts', 'publish_at_ts', 'created_at_ts']) {
+        const value = Number(item?.[key]);
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    for (const key of ['publishAt', 'published_at', 'createdAt']) {
+        const text = trimText(item?.[key]);
+        if (!text)
+            continue;
+        const date = new Date(text);
+        if (!Number.isNaN(date.getTime()))
+            return Math.floor(date.getTime() / 1000);
+    }
+    return 0;
+}
+function announcementSubscriptionKey(session) {
+    const privateChat = !session?.guildId;
+    return [session?.platform || '', session?.channelId || 'private', privateChat ? (session?.userId || '') : '', 'announcement'].join(':');
+}
+// 上游 v3.2.0：轮询最新公告，向订阅会话推送新公告提醒。
+async function checkAnnouncementSubscriptions(deps) {
+    const { ctx, client, announcementSubMgr } = deps;
+    const subs = announcementSubMgr.getAll();
+    const subEntries = Object.entries(subs);
+    if (!subEntries.length)
+        return { subscriptions: 0, pushed: 0 };
+    const latest = await client.getLatestAnnouncement(ctx, { category_id: 99 });
+    const item = latest?.detail || latest?.announcement || latest;
+    const latestId = announcementId(item);
+    if (!latestId)
+        return { subscriptions: subEntries.length, pushed: 0 };
+    const latestTs = announcementTimestamp(item);
+    let pushed = 0;
+    for (const [key, sub] of subEntries) {
+        if (latestId === String(sub.last_id || ''))
+            continue;
+        if (latestTs && sub.since_ts && latestTs <= sub.since_ts)
+            continue;
+        const message = [`【洛克王国新公告】`, buildAnnouncementDetailText(latest)].join('\n');
+        try {
+            const sent = await (0, subscription_send_1.sendScheduledMessage)(ctx, {
+                platform: sub.platform,
+                channelId: sub.channel_id || sub.guild_id || sub.user_id || '',
+                guildId: sub.guild_id || '',
+                userId: sub.user_id || '',
+            }, message);
+            if (!sent)
+                continue;
+        }
+        catch (e) {
+            logger.warn(`公告订阅推送失败: ${e}`);
+            continue;
+        }
+        pushed++;
+        announcementSubMgr.upsert(key, {
+            ...sub,
+            last_id: latestId,
+            since_ts: latestTs || Math.floor(Date.now() / 1000),
+            updated_at: Math.floor(Date.now() / 1000),
+        });
+    }
+    return { subscriptions: subEntries.length, pushed };
+}
 function buildAnnouncementListText(data, page) {
     const list = firstArray(data, ['list', 'items']);
     if (!list.length)
@@ -147,6 +212,45 @@ function register(deps) {
             return `公告详情查询失败：${client.getLastErrorBrief()}`;
         return buildAnnouncementDetailText(data);
     });
+    ctx.command('订阅洛克公告', '订阅洛克王国新公告推送')
+        .action(async ({ session }) => {
+        const privateChat = !session?.guildId;
+        if (!privateChat && !config.adminUserIds.includes(session?.userId || ''))
+            return '此指令仅限管理员使用。';
+        const key = announcementSubscriptionKey(session);
+        // 以当前最新公告为基线，只推送之后的新公告。
+        const latest = await client.getLatestAnnouncement(ctx, { category_id: 99 }, session?.userId || '');
+        const item = latest?.detail || latest?.announcement || latest;
+        deps.announcementSubMgr.upsert(key, {
+            key,
+            platform: session?.platform || '',
+            channel_id: session?.channelId || '',
+            guild_id: session?.guildId || '',
+            user_id: privateChat ? (session?.userId || '') : '',
+            updated_by: session?.userId || '',
+            last_id: announcementId(item),
+            since_ts: announcementTimestamp(item) || Math.floor(Date.now() / 1000),
+            updated_at: Math.floor(Date.now() / 1000),
+        });
+        return '已订阅洛克王国新公告推送，检测到新公告时会在当前会话提醒。';
+    });
+    ctx.command('取消订阅洛克公告', '取消洛克王国新公告推送')
+        .action(async ({ session }) => {
+        const privateChat = !session?.guildId;
+        if (!privateChat && !config.adminUserIds.includes(session?.userId || ''))
+            return '此指令仅限管理员使用。';
+        const deleted = deps.announcementSubMgr.deleteMatching({
+            platform: session?.platform || '',
+            channelId: session?.channelId || '',
+            userId: privateChat ? (session?.userId || '') : '',
+        });
+        return deleted ? '已取消洛克公告订阅。' : '当前会话没有洛克公告订阅。';
+    });
+    if (config.announcementSubscriptionEnabled) {
+        ctx.setInterval(() => {
+            checkAnnouncementSubscriptions(deps).catch(err => logger.warn(`公告订阅检查失败: ${err}`));
+        }, Math.max(1, config.announcementPollIntervalMinutes || 10) * 60000);
+    }
     ctx.command('洛克').subcommand('.同步配置', '手动同步 RoCom 远端配置')
         .alias('洛克同步配置')
         .action(async ({ session }) => {

package/lib/commands/wiki.js

@@ -1,13 +1,174 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.register = register;
-const WIKI_CLOSED_MESSAGE = '该功能暂时关闭';
+const koishi_1 = require("koishi");
+const node_fs_1 = __importDefault(require("node:fs"));
+const send_image_1 = require("../send-image");
+const wiki_service_1 = require("../wiki-service");
+const logger = new koishi_1.Logger('rocom-wiki-cmd');
+async function sendImage(deps, session, templateName, data, fallback) {
+    const png = await deps.renderer.renderHtml(deps.ctx, templateName, data);
+    await (0, send_image_1.sendImageWithFallback)(session, png, fallback, `wiki:${templateName}`, deps.config);
+}
+// 统一 Wiki 入口：目录菜单 / 分类查询 / 全局搜索 / 精灵与技能专属渲染。
+async function handleWikiQuery(deps, session, rawText) {
+    const { ctx, wikiService } = deps;
+    const trimmed = String(rawText || '').trim();
+    const rawKey = trimmed.toLowerCase();
+    const catalogsMeta = await wikiService.getCatalogsPayload();
+    if (!trimmed || ['帮助', 'help', '类型', '目录', '专题'].includes(rawKey)) {
+        const optionsMeta = await wikiService.getOptionsPayload();
+        const data = wikiService.buildCatalogRenderData(catalogsMeta, optionsMeta);
+        await sendImage(deps, session, 'wiki/menu', data, wikiService.catalogUsageText());
+        return;
+    }
+    let { catalog, query, pageNo } = wikiService.parseWikiCommand(trimmed);
+    if (catalog) {
+        catalog = wikiService.catalogForKeyFromPayload(String(catalog.key || ''), catalogsMeta) || catalog;
+    }
+    if (!catalog) {
+        const { parts, pageNo: parsedPageNo } = (0, wiki_service_1.splitWikiCommandParts)(trimmed);
+        if (parts.length) {
+            const dynamicCatalog = wikiService.dynamicCatalogByToken(parts[0], catalogsMeta);
+            if (dynamicCatalog) {
+                catalog = dynamicCatalog;
+                query = parts.slice(1).join(' ').trim();
+                pageNo = parsedPageNo;
+            }
+        }
+    }
+    if (!catalog) {
+        const { payload, mode, error } = await wikiService.fetchGlobalSearch(query, pageNo);
+        if (error)
+            return error;
+        if (mode === 'global-detail') {
+            const sourceCatalog = payload?._catalog || {};
+            const detail = payload?.item && typeof payload.item === 'object' ? payload.item : {};
+            const sourceKey = String(sourceCatalog?.key || '');
+            if (sourceKey === 'pets') {
+                const sections = await wikiService.fetchWikiPetSections(detail.pet_id);
+                const data = (0, wiki_service_1.buildWikiPetRenderData)(detail, sections.profile, sections.skills, sections.family, sections.handbook, query);
+                await sendImage(deps, session, 'wiki/pet', data, [
+                    `${data.name} #${data.number}`,
+                    `属性：${data.type_names.join(' / ') || '暂无'}`,
+                    `蛋组：${data.egg_groups.join(' / ') || '暂无'}`,
+                    data.description,
+                ].join('\n'));
+                return;
+            }
+            if (sourceKey === 'skills') {
+                const pets = await deps.client.getWikiSkillPets(ctx, detail.skill_id);
+                const data = (0, wiki_service_1.buildWikiSkillRenderData)(detail, pets && typeof pets === 'object' ? pets : {}, query);
+                await sendImage(deps, session, 'wiki/skill', data, `${data.name} #${data.skill_id}\n${data.description}`);
+                return;
+            }
+            const data = wikiService.buildGenericRenderData(sourceCatalog?.key ? sourceCatalog : { title: '全局搜索', key: 'global' }, detail, query, 'detail', pageNo);
+            await sendImage(deps, session, 'wiki/detail', data, `${data.title}\n${data.summary || ''}`);
+            return;
+        }
+        const data = wikiService.buildGenericRenderData({ title: '全局搜索', key: 'global' }, payload, query, 'global-search', pageNo);
+        await sendImage(deps, session, 'wiki/list', data, `${data.title}\n${data.summary || ''}`);
+        return;
+    }
+    if (['pets', 'pet'].includes(catalog.key) && query) {
+        const { detail: overview, candidates, error } = await wikiService.resolveWikiPet(query);
+        if (error)
+            return error;
+        if (candidates.length)
+            return (0, wiki_service_1.wikiCandidateText)(query, candidates, '精灵');
+        if (!overview)
+            return '获取 Wiki 精灵详情失败：接口未返回有效数据。';
+        const sections = await wikiService.fetchWikiPetSections(overview.pet_id);
+        const data = (0, wiki_service_1.buildWikiPetRenderData)(overview, sections.profile, sections.skills, sections.family, sections.handbook, query);
+        await sendImage(deps, session, 'wiki/pet', data, `${data.name} #${data.number}\n${data.description}`);
+        return;
+    }
+    if (['skills', 'skill'].includes(catalog.key) && query) {
+        const { detail, candidates, error } = await wikiService.resolveWikiSkill(query);
+        if (error)
+            return error;
+        if (candidates.length)
+            return (0, wiki_service_1.wikiCandidateText)(query, candidates, '技能');
+        if (!detail)
+            return '获取技能详情失败：接口未返回有效数据。';
+        const pets = await deps.client.getWikiSkillPets(ctx, detail.skill_id);
+        const data = (0, wiki_service_1.buildWikiSkillRenderData)(detail, pets && typeof pets === 'object' ? pets : {}, query);
+        await sendImage(deps, session, 'wiki/skill', data, `${data.name} #${data.skill_id}\n${data.description}`);
+        return;
+    }
+    const { payload, mode, error } = await wikiService.fetchGenericCatalog(catalog, query, pageNo);
+    if (error)
+        return error;
+    const data = wikiService.buildGenericRenderData(catalog, payload, query, mode, pageNo);
+    let templateName = 'wiki/detail';
+    if (mode === 'list')
+        templateName = 'wiki/list';
+    else if (mode === 'suggestions')
+        templateName = 'wiki/suggestions';
+    await sendImage(deps, session, templateName, data, `${data.title}\n${data.summary || ''}`);
+}
 function register(deps) {
-    const { ctx } = deps;
-    ctx.command('洛克').subcommand('.wiki <name:text>', '查询精灵 wiki')
+    const { ctx, atlasService } = deps;
+    ctx.command('洛克').subcommand('.wiki [name:text]', '查询洛克 Wiki（精灵/技能/物品等，支持全局搜索）')
         .alias('洛克wiki')
-        .action(() => WIKI_CLOSED_MESSAGE);
-    ctx.command('洛克').subcommand('.技能 <name:text>', '查询技能 wiki')
+        .alias('洛克百科')
+        .action(async ({ session }, name = '') => handleWikiQuery(deps, session, name));
+    ctx.command('洛克').subcommand('.技能 <name:text>', '查询技能 Wiki')
         .alias('洛克技能')
-        .action(() => WIKI_CLOSED_MESSAGE);
+        .action(async ({ session }, name = '') => handleWikiQuery(deps, session, `技能 ${String(name || '').trim()}`));
+    ctx.command('图鉴下载', '下载 Rocom-Atlas 精灵图鉴到本地缓存')
+        .alias('洛克图鉴下载')
+        .action(async ({ session }) => {
+        if (!deps.config.adminUserIds.includes(session?.userId || ''))
+            return '此指令仅限管理员使用。';
+        await session?.send?.('开始下载 Rocom-Atlas 图鉴，请稍候…');
+        let lastPercent = -20;
+        try {
+            const { imageCount, totalBytes } = await atlasService.download(ctx, async (percent, stage) => {
+                // 20% 粒度进度提醒（对应上游行为）
+                if (percent - lastPercent >= 20 || percent >= 100) {
+                    lastPercent = percent;
+                    await session?.send?.(`图鉴下载进度 ${percent}%：${stage}`);
+                }
+            });
+            const sizeMb = (totalBytes / 1024 / 1024).toFixed(1);
+            return `图鉴下载完成：共 ${imageCount} 张精灵图片，占用约 ${sizeMb} MB。\n使用：精灵图鉴 <精灵名>`;
+        }
+        catch (e) {
+            logger.warn(`图鉴下载失败: ${e}`);
+            return `图鉴下载失败：${e instanceof Error ? e.message : e}`;
+        }
+    });
+    ctx.command('精灵图鉴 <name:text>', '使用本地 Rocom-Atlas 查询精灵图鉴图片')
+        .alias('洛克精灵图鉴')
+        .action(async ({ session }, name = '') => {
+        const query = String(name || '').trim();
+        if (!query)
+            return '请输入精灵名称。用法：精灵图鉴 <精灵名>';
+        if (!atlasService.isReady()) {
+            return '本地图鉴尚未下载。请管理员先执行：图鉴下载';
+        }
+        const { name: matchedName, imagePath, candidates } = atlasService.findMatch(query);
+        if (imagePath) {
+            try {
+                const image = node_fs_1.default.readFileSync(imagePath);
+                await session?.send?.((0, koishi_1.h)('message', {}, koishi_1.h.text(`【精灵图鉴】${matchedName}\n`), koishi_1.h.image(image, 'image/png')));
+                return;
+            }
+            catch (e) {
+                logger.warn(`读取图鉴图片失败: ${e}`);
+                return `读取图鉴图片失败：${e instanceof Error ? e.message : e}`;
+            }
+        }
+        if (candidates.length) {
+            const lines = [`未精确匹配「${query}」，可能是：`];
+            candidates.forEach((item, idx) => lines.push(`${idx + 1}. ${item}`));
+            lines.push('请使用更精确名称重新查询。');
+            return lines.join('\n');
+        }
+        return `未在本地图鉴中找到「${query}」。可尝试其他名称，或联系管理员更新图鉴（图鉴下载）。`;
+    });
 }

package/lib/egg-service.d.ts

@@ -27,6 +27,8 @@ export declare class EggService {
     private rangeMatchScore;
     private formatPetCard;
     private formatSizeApiCard;
+    private splitNewSizeApiItems;
+    private sizeApiResultGroups;
     private formatEggSearchCard;
     private formatEggSearchTextLine;
     private mergeCardsByName;