koishi-plugin-rocom 1.0.13 → 1.0.18

package/lib/atlas-service.d.ts

@@ -0,0 +1,33 @@
+import { Context } from 'koishi';
+export type AtlasProgressCallback = (percent: number, stage: string) => void | Promise<void>;
+export declare class AtlasService {
+    private dataDir;
+    private zipUrls;
+    private gitUrl;
+    constructor(dataDir: string, options?: {
+        zipUrls?: string[];
+        gitUrl?: string;
+    });
+    get atlasDir(): string;
+    private indexPath;
+    private petsDir;
+    private aliasPath;
+    isReady(): boolean;
+    loadIndex(): Record<string, string>;
+    private stripYamlValue;
+    loadPetAliases(): Record<string, string[]>;
+    private localImagePath;
+    private existingImagePath;
+    findMatch(query: string): {
+        name: string;
+        imagePath: string;
+        candidates: string[];
+    };
+    private prepareAtlasDir;
+    private replaceAtlasDir;
+    private downloadZipWithProgress;
+    download(ctx: Context, progressCb?: AtlasProgressCallback): Promise<{
+        imageCount: number;
+        totalBytes: number;
+    }>;
+}

package/lib/atlas-service.js

@@ -0,0 +1,439 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlasService = void 0;
+const koishi_1 = require("koishi");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_zlib_1 = __importDefault(require("node:zlib"));
+const wiki_service_1 = require("./wiki-service");
+const logger = new koishi_1.Logger('rocom-atlas');
+const DEFAULT_ATLAS_ZIP_URLS = [
+    'https://codeload.github.com/Entropy-Increase-Team/Rocom-Atlas/zip/refs/heads/main',
+    'https://github.com/Entropy-Increase-Team/Rocom-Atlas/archive/refs/heads/main.zip',
+];
+const DEFAULT_ATLAS_GIT_URL = 'https://github.com/Entropy-Increase-Team/Rocom-Atlas.git';
+// ===== 最小 ZIP 解包（stored + deflate），避免引入额外依赖 =====
+function extractZip(buffer, destDir) {
+    // 定位 End of Central Directory（自尾部反向搜索签名 0x06054b50）
+    let eocd = -1;
+    const minEocd = Math.max(0, buffer.length - 65557);
+    for (let i = buffer.length - 22; i >= minEocd; i--) {
+        if (buffer.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('ZIP 结构异常：找不到中央目录结尾');
+    const entryCount = buffer.readUInt16LE(eocd + 10);
+    let offset = buffer.readUInt32LE(eocd + 16);
+    for (let i = 0; i < entryCount; i++) {
+        if (buffer.readUInt32LE(offset) !== 0x02014b50)
+            throw new Error('ZIP 结构异常：中央目录签名错误');
+        const compressionMethod = buffer.readUInt16LE(offset + 10);
+        const compressedSize = buffer.readUInt32LE(offset + 20);
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        const localHeaderOffset = buffer.readUInt32LE(offset + 42);
+        const name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+        offset += 46 + nameLength + extraLength + commentLength;
+        // 拒绝路径穿越
+        const normalized = name.replace(/\\/g, '/');
+        if (normalized.includes('..'))
+            continue;
+        const target = node_path_1.default.join(destDir, ...normalized.split('/'));
+        if (!node_path_1.default.resolve(target).startsWith(node_path_1.default.resolve(destDir)))
+            continue;
+        if (normalized.endsWith('/')) {
+            node_fs_1.default.mkdirSync(target, { recursive: true });
+            continue;
+        }
+        // 读本地文件头拿数据真实偏移（本地头的 name/extra 长度可能与中央目录不同）
+        if (buffer.readUInt32LE(localHeaderOffset) !== 0x04034b50)
+            throw new Error('ZIP 结构异常：本地文件头签名错误');
+        const localNameLength = buffer.readUInt16LE(localHeaderOffset + 26);
+        const localExtraLength = buffer.readUInt16LE(localHeaderOffset + 28);
+        const dataStart = localHeaderOffset + 30 + localNameLength + localExtraLength;
+        const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+        let content;
+        if (compressionMethod === 0)
+            content = Buffer.from(compressed);
+        else if (compressionMethod === 8)
+            content = node_zlib_1.default.inflateRawSync(compressed);
+        else
+            throw new Error(`ZIP 不支持的压缩方式: ${compressionMethod}`);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(target), { recursive: true });
+        node_fs_1.default.writeFileSync(target, content);
+    }
+}
+function gitClone(dst, gitUrl) {
+    return new Promise((resolve, reject) => {
+        // --progress 让 git 在非 TTY 下也输出克隆进度（写到 stderr），逐行转发到日志。
+        const child = (0, node_child_process_1.spawn)('git', ['clone', '--depth', '1', '--single-branch', '--progress', gitUrl, dst], { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        const stderrLines = [];
+        let stderrTail = '';
+        child.stderr.on('data', (chunk) => {
+            stderrTail += chunk.toString('utf8');
+            // git 进度行用 \r 刷新，按 \r 和 \n 一起切
+            const lines = stderrTail.split(/[\r\n]+/);
+            stderrTail = lines.pop() || '';
+            for (const line of lines) {
+                const text = line.trim();
+                if (!text)
+                    continue;
+                stderrLines.push(text);
+                logger.info(`git clone: ${text}`);
+            }
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error('git clone Rocom-Atlas 超时（180 秒）'));
+        }, 180000);
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(new Error(`git clone Rocom-Atlas 失败：${error.message}`));
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`git clone Rocom-Atlas 失败（exit ${code}）：${stderrLines.slice(-3).join(' | ')}`));
+        });
+    });
+}
+class AtlasService {
+    dataDir;
+    zipUrls;
+    gitUrl;
+    constructor(dataDir, options = {}) {
+        this.dataDir = dataDir;
+        this.zipUrls = options.zipUrls?.length ? options.zipUrls : DEFAULT_ATLAS_ZIP_URLS;
+        this.gitUrl = options.gitUrl || DEFAULT_ATLAS_GIT_URL;
+    }
+    get atlasDir() {
+        return node_path_1.default.join(this.dataDir, 'rocom_atlas');
+    }
+    indexPath() {
+        return node_path_1.default.join(this.atlasDir, 'path.json');
+    }
+    petsDir() {
+        return node_path_1.default.join(this.atlasDir, 'pets');
+    }
+    aliasPath() {
+        return node_path_1.default.join(this.atlasDir, 'othername', 'pets.yaml');
+    }
+    isReady() {
+        return node_fs_1.default.existsSync(this.indexPath()) && node_fs_1.default.existsSync(this.petsDir());
+    }
+    loadIndex() {
+        try {
+            const payload = JSON.parse(node_fs_1.default.readFileSync(this.indexPath(), 'utf-8'));
+            const pets = payload?.pets;
+            return pets && typeof pets === 'object' ? pets : {};
+        }
+        catch (e) {
+            logger.warn(`读取本地图鉴索引失败: ${e}`);
+            return {};
+        }
+    }
+    stripYamlValue(value) {
+        const text = String(value || '').trim();
+        if (text.length >= 2 && text[0] === text[text.length - 1] && ["'", '"'].includes(text[0])) {
+            return text.slice(1, -1).trim();
+        }
+        return text;
+    }
+    // 解析上游简单结构的 pets.yaml：`正式名:` + 缩进 `- 别名` 列表。
+    loadPetAliases() {
+        const filePath = this.aliasPath();
+        if (!node_fs_1.default.existsSync(filePath))
+            return {};
+        const aliases = {};
+        let currentName = '';
+        try {
+            const lines = node_fs_1.default.readFileSync(filePath, 'utf-8').split(/\r?\n/);
+            for (const line of lines) {
+                const stripped = line.trim();
+                if (!stripped || stripped.startsWith('#'))
+                    continue;
+                if (!/^\s/.test(line) && stripped.endsWith(':')) {
+                    currentName = this.stripYamlValue(stripped.slice(0, -1));
+                    if (currentName) {
+                        const key = (0, wiki_service_1.normalizeQueryText)(currentName);
+                        aliases[key] = aliases[key] || [];
+                        if (!aliases[key].includes(currentName))
+                            aliases[key].push(currentName);
+                    }
+                    continue;
+                }
+                if (currentName && stripped.startsWith('-')) {
+                    const alias = this.stripYamlValue(stripped.slice(1));
+                    if (!alias)
+                        continue;
+                    const key = (0, wiki_service_1.normalizeQueryText)(alias);
+                    aliases[key] = aliases[key] || [];
+                    if (!aliases[key].includes(currentName))
+                        aliases[key].push(currentName);
+                }
+            }
+        }
+        catch (e) {
+            logger.warn(`读取本地图鉴别名失败: ${e}`);
+            return {};
+        }
+        return aliases;
+    }
+    localImagePath(atlasRelPath) {
+        const rel = String(atlasRelPath || '').replace(/\\/g, '/').replace(/^\/+/, '');
+        if (!rel)
+            return '';
+        const candidate = node_path_1.default.resolve(this.atlasDir, ...rel.split('/'));
+        const root = node_path_1.default.resolve(this.atlasDir);
+        if (!candidate.startsWith(root))
+            return '';
+        return candidate;
+    }
+    existingImagePath(index, name) {
+        const filePath = this.localImagePath(index[name] || '');
+        return filePath && node_fs_1.default.existsSync(filePath) ? filePath : '';
+    }
+    findMatch(query) {
+        const trimmed = String(query || '').trim();
+        if (!trimmed)
+            return { name: '', imagePath: '', candidates: [] };
+        if (/^\d+$/.test(trimmed)) {
+            const filePath = node_path_1.default.join(this.petsDir(), `${trimmed}.png`);
+            if (node_fs_1.default.existsSync(filePath))
+                return { name: `#${trimmed}`, imagePath: filePath, candidates: [] };
+        }
+        const index = this.loadIndex();
+        if (!Object.keys(index).length)
+            return { name: '', imagePath: '', candidates: [] };
+        const normalizedQuery = (0, wiki_service_1.normalizeQueryText)(trimmed);
+        let exactKey = '';
+        for (const name of Object.keys(index)) {
+            if ((0, wiki_service_1.normalizeQueryText)(name) === normalizedQuery) {
+                exactKey = name;
+                break;
+            }
+        }
+        if (exactKey) {
+            const filePath = this.existingImagePath(index, exactKey);
+            if (filePath)
+                return { name: exactKey, imagePath: filePath, candidates: [] };
+        }
+        const aliasMap = this.loadPetAliases();
+        const exactAliasCandidates = (aliasMap[normalizedQuery] || []).filter(name => this.existingImagePath(index, name));
+        if (exactAliasCandidates.length) {
+            const only = exactAliasCandidates[0];
+            return { name: only, imagePath: this.existingImagePath(index, only), candidates: [] };
+        }
+        const candidates = [];
+        const addCandidate = (name) => {
+            if (!candidates.includes(name) && this.existingImagePath(index, name))
+                candidates.push(name);
+        };
+        for (const name of Object.keys(index)) {
+            const normalizedName = (0, wiki_service_1.normalizeQueryText)(name);
+            if (normalizedQuery && (normalizedName.includes(normalizedQuery) || normalizedQuery.includes(normalizedName))) {
+                addCandidate(name);
+            }
+        }
+        for (const [alias, names] of Object.entries(aliasMap)) {
+            if (normalizedQuery && (alias.includes(normalizedQuery) || normalizedQuery.includes(alias))) {
+                for (const name of names)
+                    addCandidate(name);
+            }
+        }
+        if (candidates.length === 1) {
+            const only = candidates[0];
+            return { name: only, imagePath: this.existingImagePath(index, only), candidates: [] };
+        }
+        return { name: '', imagePath: '', candidates: candidates.slice(0, 10) };
+    }
+    prepareAtlasDir(sourceRoot, preparedDir) {
+        node_fs_1.default.mkdirSync(preparedDir, { recursive: true });
+        for (const name of ['path.json', 'index', 'othername', 'pets']) {
+            const src = node_path_1.default.join(sourceRoot, name);
+            const dst = node_path_1.default.join(preparedDir, name);
+            if (node_fs_1.default.existsSync(src)) {
+                node_fs_1.default.cpSync(src, dst, { recursive: true });
+            }
+        }
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(preparedDir, 'path.json')))
+            throw new Error('Atlas 缺少 path.json');
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(preparedDir, 'othername', 'pets.yaml')))
+            throw new Error('Atlas 缺少 othername/pets.yaml');
+        const petsDir = node_path_1.default.join(preparedDir, 'pets');
+        if (!node_fs_1.default.existsSync(petsDir))
+            throw new Error('Atlas 缺少 pets 图片目录');
+        const imageCount = node_fs_1.default.readdirSync(petsDir).filter(name => name.toLowerCase().endsWith('.png')).length;
+        let totalBytes = 0;
+        const walk = (dir) => {
+            for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                const entryPath = node_path_1.default.join(dir, entry.name);
+                if (entry.isDirectory())
+                    walk(entryPath);
+                else
+                    totalBytes += node_fs_1.default.statSync(entryPath).size;
+            }
+        };
+        walk(preparedDir);
+        return { imageCount, totalBytes };
+    }
+    replaceAtlasDir(preparedDir) {
+        const target = node_path_1.default.resolve(this.atlasDir);
+        const dataRoot = node_path_1.default.resolve(this.dataDir);
+        if (!target.startsWith(dataRoot))
+            throw new Error('图鉴目标目录不在插件数据目录内');
+        if (node_fs_1.default.existsSync(target))
+            node_fs_1.default.rmSync(target, { recursive: true, force: true });
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(target), { recursive: true });
+        try {
+            node_fs_1.default.renameSync(preparedDir, target);
+        }
+        catch (e) {
+            // Windows 跨盘符（如 C: 临时目录 → D: 数据目录）rename 会抛 EXDEV/EPERM，回退为复制。
+            if (['EXDEV', 'EPERM'].includes(e?.code)) {
+                logger.info(`rename 失败（${e.code}），回退为复制方式迁移图鉴目录`);
+                node_fs_1.default.cpSync(preparedDir, target, { recursive: true });
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    // 流式下载压缩包：每 2 秒输出一次已下载字节数/速度，避免大文件下载期间毫无动静。
+    async downloadZipWithProgress(ctx, url) {
+        const started = Date.now();
+        const res = await ctx.http(url, { responseType: 'stream', timeout: 180000 });
+        const totalHeader = Number(res.headers?.get?.('content-length'));
+        const totalBytes = Number.isFinite(totalHeader) && totalHeader > 0 ? totalHeader : 0;
+        const totalText = totalBytes ? `${(totalBytes / 1024 / 1024).toFixed(1)} MB` : '未知大小';
+        logger.info(`开始下载图鉴压缩包：${url}（${totalText}）`);
+        const chunks = [];
+        let received = 0;
+        let lastLogAt = Date.now();
+        const reader = res.data.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                chunks.push(Buffer.from(value));
+                received += value.byteLength;
+            }
+            const now = Date.now();
+            if (now - lastLogAt >= 2000) {
+                lastLogAt = now;
+                const mb = (received / 1024 / 1024).toFixed(1);
+                const speed = (received / 1024 / (now - started) * 1000 / 1024).toFixed(2);
+                const percentText = totalBytes ? `${Math.min(99, Math.round(received / totalBytes * 100))}%，` : '';
+                logger.info(`图鉴压缩包下载中：${percentText}已收到 ${mb} MB，平均 ${speed} MB/s`);
+            }
+        }
+        const elapsed = ((Date.now() - started) / 1000).toFixed(1);
+        logger.info(`图鉴压缩包下载完成：共 ${(received / 1024 / 1024).toFixed(1)} MB，耗时 ${elapsed} 秒`);
+        return Buffer.concat(chunks);
+    }
+    async download(ctx, progressCb) {
+        const emit = async (percent, stage) => {
+            if (progressCb)
+                await progressCb(Math.max(0, Math.min(100, Math.round(percent))), stage);
+        };
+        // 清理上次崩溃或中断留下的临时目录。
+        node_fs_1.default.mkdirSync(this.dataDir, { recursive: true });
+        for (const entry of node_fs_1.default.readdirSync(this.dataDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith('.atlas_tmp_')) {
+                cleanupTempDir(node_path_1.default.join(this.dataDir, entry.name));
+            }
+        }
+        // 临时目录放在数据目录同盘，确保 renameSync 原子操作不跨文件系统（避免 EXDEV）。
+        const tmpRoot = node_fs_1.default.mkdtempSync(node_path_1.default.join(this.dataDir, '.atlas_tmp_'));
+        const extractDir = node_path_1.default.join(tmpRoot, 'extract');
+        let preparedDir = node_path_1.default.join(tmpRoot, 'rocom_atlas');
+        const cloneDir = node_path_1.default.join(tmpRoot, 'clone');
+        try {
+            let zipBuffer = null;
+            const zipErrors = [];
+            for (const url of this.zipUrls) {
+                try {
+                    await emit(10, '正在下载图鉴压缩包');
+                    zipBuffer = await this.downloadZipWithProgress(ctx, url);
+                    await emit(80, '图鉴压缩包下载完成');
+                    break;
+                }
+                catch (e) {
+                    logger.warn(`图鉴压缩包下载失败：${url}: ${e}`);
+                    zipErrors.push(`${url}: ${e}`);
+                    zipBuffer = null;
+                }
+            }
+            let stats;
+            if (zipBuffer) {
+                await emit(80, '正在解压图鉴文件');
+                logger.info('正在解压图鉴压缩包…');
+                node_fs_1.default.mkdirSync(extractDir, { recursive: true });
+                extractZip(zipBuffer, extractDir);
+                logger.info('图鉴压缩包解压完成');
+                const roots = node_fs_1.default.readdirSync(extractDir, { withFileTypes: true })
+                    .filter(entry => entry.isDirectory())
+                    .map(entry => node_path_1.default.join(extractDir, entry.name));
+                if (!roots.length)
+                    throw new Error('Atlas 压缩包结构异常');
+                stats = this.prepareAtlasDir(roots[0], preparedDir);
+            }
+            else {
+                logger.warn(`GitHub zip 下载失败，尝试 git clone：${zipErrors.join(' | ')}`);
+                await emit(20, '正在 git clone 图鉴仓库');
+                await gitClone(cloneDir, this.gitUrl);
+                await emit(80, '正在整理图鉴文件');
+                stats = this.prepareAtlasDir(cloneDir, preparedDir);
+            }
+            this.replaceAtlasDir(preparedDir);
+            preparedDir = '';
+            logger.info(`本地图鉴缓存已更新：${stats.imageCount} 张图片，${(stats.totalBytes / 1024 / 1024).toFixed(1)} MB`);
+            await emit(100, '本地图鉴缓存已更新');
+            return stats;
+        }
+        finally {
+            cleanupTempDir(tmpRoot);
+        }
+    }
+}
+exports.AtlasService = AtlasService;
+// Windows 下 git clone 产生的 .git pack 文件是只读的，直接 rmSync 会抛 EPERM；
+// 先带重试删，失败则清掉只读属性再删。清理失败只告警，不影响下载结果。
+function cleanupTempDir(tmpRoot) {
+    try {
+        node_fs_1.default.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+    }
+    catch {
+        try {
+            const clearReadonly = (dir) => {
+                for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                    const entryPath = node_path_1.default.join(dir, entry.name);
+                    try {
+                        node_fs_1.default.chmodSync(entryPath, 0o666);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    if (entry.isDirectory())
+                        clearReadonly(entryPath);
+                }
+            };
+            clearReadonly(tmpRoot);
+            node_fs_1.default.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+        }
+        catch (e) {
+            logger.warn(`清理图鉴临时目录失败（不影响下载结果）：${tmpRoot}: ${e}`);
+        }
+    }
+}

package/lib/client.d.ts

@@ -66,7 +66,7 @@ export declare class RocomClient {
     getLineupList(ctx: Context, fwToken: string, pageNo?: number, category?: string, userIdentifier?: string): Promise<any>;
     getExchangePosters(ctx: Context, fwToken: string, pageNo?: number, userIdentifier?: string): Promise<any>;
     getMerchantInfo(ctx: Context, refresh?: boolean): Promise<any>;
-    queryPetSize(ctx: Context, diameter: number, weight: number, sameRideEgg?: boolean, userIdentifier?: string): Promise<any>;
+    queryPetSize(ctx: Context, diameter: number, weight: number, pool?: string, pageNo?: number, pageSize?: number, userIdentifier?: string): Promise<any>;
     getActivitiesInfo(ctx: Context, refresh?: boolean, userIdentifier?: string): Promise<any>;
     syncConfig(ctx: Context, userIdentifier?: string): Promise<any>;
     getAnnouncementList(ctx: Context, params?: {
@@ -80,7 +80,6 @@ export declare class RocomClient {
         order?: string;
     }, userIdentifier?: string): Promise<any>;
     getAnnouncementDetail(ctx: Context, threadId: number | string, userIdentifier?: string): Promise<any>;
-    getEggSearch(ctx: Context, height: number, weight: number, pageNo?: number, pageSize?: number, userIdentifier?: string): Promise<any>;
     getEggGroups(ctx: Context, userIdentifier?: string): Promise<any>;
     getEggGroupPets(ctx: Context, groupIds: string | number[], matchMode?: 'any' | 'all', pageNo?: number, pageSize?: number, userIdentifier?: string): Promise<any>;
     getEggPetGroups(ctx: Context, query: string, limit?: number, userIdentifier?: string): Promise<any>;
@@ -95,6 +94,10 @@ export declare class RocomClient {
     getEggExchangeEvents(ctx: Context, subscriptionId: string | number, afterEventId?: string, limit?: number, userIdentifier?: string): Promise<any>;
     ingameHomeInfo(ctx: Context, uid: string, options?: IngameTaskPollOptions): Promise<any>;
     ingameMerchantInfo(ctx: Context, shopId: string | number): Promise<any>;
+    ingamePetData(ctx: Context, uid: string, extras?: {
+        petGid?: string | number;
+        npcId?: string | number;
+    }, options?: IngameTaskPollOptions): Promise<any>;
     getFriendship(ctx: Context, fwToken: string, userIds: string, userIdentifier?: string): Promise<any>;
     getStudentState(ctx: Context, fwToken: string, accountType?: number, userIdentifier?: string): Promise<any>;
     getStudentPerks(ctx: Context, fwToken: string, area?: number, accountType?: number, userIdentifier?: string): Promise<any>;
@@ -104,4 +107,19 @@ export declare class RocomClient {
         id?: number;
         name?: string;
     }): Promise<any>;
+    private wikiPagedParams;
+    listWikiPets(ctx: Context, q?: string, pageNo?: number, pageSize?: number, filters?: Record<string, any>): Promise<any>;
+    getWikiPet(ctx: Context, petId: string | number): Promise<any>;
+    getWikiPetProfile(ctx: Context, petId: string | number): Promise<any>;
+    getWikiPetSkills(ctx: Context, petId: string | number): Promise<any>;
+    getWikiPetFamily(ctx: Context, petId: string | number): Promise<any>;
+    getWikiPetHandbook(ctx: Context, petId: string | number): Promise<any>;
+    listWikiSkills(ctx: Context, q?: string, pageNo?: number, pageSize?: number, filters?: Record<string, any>): Promise<any>;
+    getWikiSkill(ctx: Context, skillId: string | number): Promise<any>;
+    getWikiSkillPets(ctx: Context, skillId: string | number): Promise<any>;
+    getWikiCatalogs(ctx: Context): Promise<any>;
+    getWikiOptions(ctx: Context): Promise<any>;
+    getWikiPath(ctx: Context, path: string, params?: Record<string, any>): Promise<any>;
+    listWikiCatalogItems(ctx: Context, path: string, q?: string, pageNo?: number, pageSize?: number, search?: boolean): Promise<any>;
+    get wikiAssetBaseUrl(): string;
 }

package/lib/client.js

@@ -360,7 +360,8 @@ class RocomClient {
         return String(payload?.task_id || payload?.taskId || payload?.taskID || '').trim();
     }
     // 判断一份 payload 是否为“已完成的业务结果”（而非排队占位）。
-    // 家园接口完成时返回 rows/home_info；玩家、商店完成时返回 source/title/rows。
+    // 家园接口完成时返回 rows/home_info；玩家、商店完成时返回 source/title/rows；
+    // 家园详情（pet/data）完成时返回 npc_pets/npc_pet。
     static isCompletedGatewayPayload(payload) {
         if (!payload || typeof payload !== 'object')
             return false;
@@ -370,6 +371,10 @@ class RocomClient {
             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())
             return true;
         return false;
@@ -611,11 +616,16 @@ class RocomClient {
             random_goods: 'all',
         });
     }
-    async queryPetSize(ctx, diameter, weight, sameRideEgg = false, userIdentifier = '') {
-        const params = this.scopedParams({ diameter, weight }, userIdentifier);
-        if (sameRideEgg)
-            params.sameRideEgg = 1;
-        return this.get(ctx, '/api/v1/games/rocom/pet/size-query', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), params);
+    async queryPetSize(ctx, diameter, weight, pool = 'magic', pageNo = 1, pageSize = 30, userIdentifier = '') {
+        const params = this.scopedParams({
+            diameter,
+            weight,
+            pool: pool || 'magic',
+            include_display_only: 'false',
+            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/wiki/pet-size/query', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), params);
     }
     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));
@@ -632,9 +642,6 @@ class RocomClient {
     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));
     }
-    async getEggSearch(ctx, height, weight, pageNo = 1, pageSize = 20, userIdentifier = '') {
-        return this.get(ctx, '/api/v1/games/rocom/egg/search', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams({ height, weight, page_no: pageNo, page_size: pageSize }, userIdentifier));
-    }
     async getEggGroups(ctx, userIdentifier = '') {
         return this.get(ctx, '/api/v1/games/rocom/egg/groups', this.wegameHeaders('', userIdentifier, 'bot', 'koishi'), this.scopedParams({}, userIdentifier));
     }
@@ -695,6 +702,27 @@ class RocomClient {
         const { status, data } = await this.requestIngameWithFallback(ctx, '/api/v1/games/rocom/ingame/merchant/info', params);
         return status === null ? null : data;
     }
+    // 家园详情：批量或单只查询家园摆放精灵的完整 ingame 数据（上游 v3.6.1）。
+    // UID 参数名为 target_uin；单只查询需同时提供 pet_gid 和 npc_id。
+    async ingamePetData(ctx, uid, extras = {}, options = {}) {
+        const sanitizedUid = this.sanitizeUid(uid);
+        if (!sanitizedUid) {
+            this.setLastError('UID 不能为空');
+            return null;
+        }
+        const waitMs = Number(options.waitMs) || 20000;
+        const payload = { target_uin: sanitizedUid, wait_ms: waitMs };
+        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, {
+            queuedNoTaskId: '家园详情任务已入队，但未返回 task_id',
+            stillQueued: (taskId) => `家园详情任务仍在排队，请稍后重试（task_id: ${taskId}）`,
+        });
+    }
     async getFriendship(ctx, fwToken, userIds, userIdentifier = '') {
         return this.get(ctx, '/api/v1/games/rocom/social/friendship', this.rocomHeaders(fwToken, userIdentifier), { user_ids: userIds });
     }
@@ -726,5 +754,67 @@ class RocomClient {
             params.name = options.name;
         return this.get(ctx, '/api/v1/games/rocom/pet/detail', this.wegameHeaders(), params);
     }
+    // ===== 新版 RoCom Wiki API（上游 v3.6.0）=====
+    wikiPagedParams(q = '', pageNo = 1, pageSize = 10, filters = {}) {
+        const params = {
+            page_no: Math.max(Number(pageNo) || 1, 1),
+            page_size: Math.min(Math.max(Number(pageSize) || 10, 1), 100),
+        };
+        if (q)
+            params.q = q;
+        for (const [key, value] of Object.entries(filters)) {
+            if (value !== undefined && value !== null && value !== '')
+                params[key] = value;
+        }
+        return params;
+    }
+    async listWikiPets(ctx, q = '', pageNo = 1, pageSize = 10, filters = {}) {
+        return this.get(ctx, '/api/v1/games/rocom/wiki/pets', this.wegameHeaders(), this.wikiPagedParams(q, pageNo, pageSize, filters));
+    }
+    async getWikiPet(ctx, petId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/pets/${petId}`, this.wegameHeaders());
+    }
+    async getWikiPetProfile(ctx, petId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/pets/${petId}/profile`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiPetSkills(ctx, petId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/pets/${petId}/skills`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiPetFamily(ctx, petId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/pets/${petId}/family`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiPetHandbook(ctx, petId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/pets/${petId}/handbook`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async listWikiSkills(ctx, q = '', pageNo = 1, pageSize = 10, filters = {}) {
+        return this.get(ctx, '/api/v1/games/rocom/wiki/skills', this.wegameHeaders(), this.wikiPagedParams(q, pageNo, pageSize, filters));
+    }
+    async getWikiSkill(ctx, skillId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/skills/${skillId}`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiSkillPets(ctx, skillId) {
+        return this.get(ctx, `/api/v1/games/rocom/wiki/skills/${skillId}/pets`, this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiCatalogs(ctx) {
+        return this.get(ctx, '/api/v1/games/rocom/wiki/catalogs', this.wegameHeaders());
+    }
+    async getWikiOptions(ctx) {
+        return this.get(ctx, '/api/v1/games/rocom/wiki/options', this.wegameHeaders(), undefined, { silentFailureDetails: true });
+    }
+    async getWikiPath(ctx, path, params = {}) {
+        const trimmed = String(path || '').trim();
+        if (!trimmed.startsWith('/api/v1/games/rocom/wiki/')) {
+            this.setLastError('非法 Wiki 路径');
+            return null;
+        }
+        return this.get(ctx, trimmed, this.wegameHeaders(), params);
+    }
+    async listWikiCatalogItems(ctx, path, q = '', pageNo = 1, pageSize = 10, search = true) {
+        const params = this.wikiPagedParams(search ? q : '', pageNo, pageSize);
+        return this.getWikiPath(ctx, path, params);
+    }
+    get wikiAssetBaseUrl() {
+        return this.baseUrl;
+    }
 }
 exports.RocomClient = RocomClient;