@uwa4d/openapi-mcp 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/composite/stack-agg.js

@@ -0,0 +1,257 @@
+import { isObj } from './helpers.js';
+/**
+ * Overview：线程堆栈树（主线程）+ 函数 idmap → 按函数名合并节点。
+ * 同名（同一 methodId）节点的 selfTime / callCount 相加，再按指标排序取 Top N。
+ */
+export async function aggregateOverviewStack(client, identity, topN, metric = 'selfTime') {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    const apisUsed = [];
+    const [treeMeta, idMap] = await Promise.all([
+        client.call('GET', '/openapi/v1/data/gotonline/overview/stack/overall/tree/presign', 'v1.0.1', keyQuery),
+        fetchFunctionIdMap(client, keyQuery),
+    ]);
+    apisUsed.push('gotonline_overview_stack_overall_tree_presign', 'gotonline_overview_stack_id_map');
+    const url = typeof treeMeta['dataPresignUrl'] === 'string' ? treeMeta['dataPresignUrl'] : null;
+    if (!url)
+        throw new Error('线程堆栈树未返回 dataPresignUrl（报告可能未开 CPU 堆栈或 SDK < 2.5.1）');
+    const testMode = treeMeta['testMode'] != null ? String(treeMeta['testMode']) : null;
+    const payload = await client.downloadPresign(url);
+    const csvText = payload.kind === 'text' ? (payload.text ?? '') : JSON.stringify(payload.json ?? '');
+    const nodes = parseStackCsv(csvText, testMode);
+    return finalizeAgg(nodes, idMap, topN, metric, testMode, apisUsed, 'overview.stack.overall');
+}
+/**
+ * Mono：正向堆栈树 + Mono 函数 idmap。
+ * 文本格式与 Overview CSV 不同时走宽松解析；失败则抛错由上层处理。
+ */
+export async function aggregateMonoStack(client, identity, topN, metric = 'selfMemory') {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    const apisUsed = [];
+    const [treeMeta, idMapRaw] = await Promise.all([
+        client.call('GET', '/openapi/v1/data/gotonline/mono/stack/tree/overall/presign', 'v1.0.1', keyQuery),
+        client.call('GET', '/openapi/v1/data/gotonline/mono/stack/method/idmap/presign', 'v1.0.1', keyQuery),
+    ]);
+    apisUsed.push('gotonline_mono_stack_tree_overall_presign', 'gotonline_mono_stack_method_idmap_presign');
+    const treeUrl = typeof treeMeta['dataPresignUrl'] === 'string' ? treeMeta['dataPresignUrl'] : null;
+    const mapUrl = typeof idMapRaw['dataPresignUrl'] === 'string' ? idMapRaw['dataPresignUrl'] : null;
+    if (!treeUrl)
+        throw new Error('Mono 堆栈树未返回 dataPresignUrl');
+    if (!mapUrl)
+        throw new Error('Mono 函数 idmap 未返回 dataPresignUrl');
+    const [treePayload, mapPayload] = await Promise.all([
+        client.downloadPresign(treeUrl),
+        client.downloadPresign(mapUrl),
+    ]);
+    const idMap = parseIdMapPayload(mapPayload.json ?? mapPayload.text);
+    const csvText = treePayload.kind === 'text' ? (treePayload.text ?? '') : JSON.stringify(treePayload.json ?? '');
+    // Mono 正向树多为文本/CSV；按 CPU_ONLY/内存列尝试解析
+    const nodes = parseStackCsv(csvText, 'LUA_MEM_ONLY');
+    const useMetric = metric === 'selfTime' || metric === 'totalTime' ? 'selfMemory' : metric;
+    return finalizeAgg(nodes, idMap, topN, useMetric, 'LUA_MEM_ONLY', apisUsed, 'mono.stack.overall');
+}
+async function fetchFunctionIdMap(client, keyQuery) {
+    const raw = await client.call('GET', '/openapi/v1/data/gotonline/overview/stack/id/map', 'v1.0.1', keyQuery);
+    return parseIdMapPayload(raw);
+}
+function parseIdMapPayload(raw) {
+    const map = new Map();
+    let list = null;
+    if (isObj(raw)) {
+        list = raw['id_map'] ?? raw['stats_id_map'] ?? raw['idMap'];
+    }
+    if (!list && typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (isObj(parsed))
+                list = parsed['id_map'] ?? parsed['stats_id_map'];
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (!Array.isArray(list))
+        return map;
+    for (const item of list) {
+        if (!isObj(item))
+            continue;
+        const id = item['id'] != null ? String(item['id']) : '';
+        const name = item['name'] != null ? String(item['name']) : '';
+        if (id)
+            map.set(id, name || id);
+    }
+    return map;
+}
+/**
+ * 解析无表头 CSV。列数随 testMode 变化；UE 固定 7 列（与 CPU_ONLY 同形）。
+ */
+export function parseStackCsv(csvText, testMode) {
+    const lines = csvText
+        .replace(/^\uFEFF/, '')
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const nodes = [];
+    for (const line of lines) {
+        const cols = splitCsvLine(line);
+        if (cols.length < 6)
+            continue;
+        const depth = Number(cols[0]);
+        const sampleId = String(cols[1] ?? '');
+        const methodId = String(cols[2] ?? '');
+        if (!methodId || Number.isNaN(depth))
+            continue;
+        const mode = (testMode ?? inferMode(cols.length)).toUpperCase();
+        let totalTimeUs = 0;
+        let selfTimeUs = 0;
+        let callCount = 0;
+        let callFrameCount = 0;
+        let totalMemoryKb = 0;
+        let selfMemoryKb = 0;
+        if (mode === 'LUA_MEM_ONLY' || (cols.length === 7 && mode.includes('LUA') && !mode.includes('CPU'))) {
+            totalMemoryKb = num(cols[3]);
+            selfMemoryKb = num(cols[4]);
+            callCount = num(cols[5]);
+            callFrameCount = num(cols[6]);
+        }
+        else if (mode === 'CPU_AND_LUA_MEM' || cols.length >= 9) {
+            totalTimeUs = num(cols[3]);
+            selfTimeUs = num(cols[4]);
+            callCount = num(cols[5]);
+            totalMemoryKb = num(cols[6]);
+            selfMemoryKb = num(cols[7]);
+            callFrameCount = num(cols[8]);
+        }
+        else {
+            // CPU_ONLY / UE 7 列
+            totalTimeUs = num(cols[3]);
+            selfTimeUs = num(cols[4]);
+            callCount = num(cols[5]);
+            callFrameCount = num(cols[6]);
+        }
+        nodes.push({
+            depth,
+            sampleId,
+            methodId,
+            totalTimeUs,
+            selfTimeUs,
+            callCount,
+            callFrameCount,
+            totalMemoryKb,
+            selfMemoryKb,
+        });
+    }
+    return nodes;
+}
+function inferMode(colCount) {
+    if (colCount >= 9)
+        return 'CPU_AND_LUA_MEM';
+    return 'CPU_ONLY';
+}
+function num(v) {
+    if (v == null || v === '')
+        return 0;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+/** 简单 CSV 分割：堆栈树字段不含引号逗号，按逗号切即可；兼容制表符。 */
+function splitCsvLine(line) {
+    if (line.includes('\t') && !line.includes(','))
+        return line.split('\t');
+    return line.split(',');
+}
+function finalizeAgg(nodes, idMap, topN, metric, testMode, apisUsed, source) {
+    const byId = new Map();
+    for (const n of nodes) {
+        let row = byId.get(n.methodId);
+        if (!row) {
+            row = {
+                methodId: n.methodId,
+                name: idMap.get(n.methodId) ?? n.methodId,
+                selfTimeUs: 0,
+                totalTimeUs: 0,
+                callCount: 0,
+                callFrameCount: 0,
+                selfMemoryKb: 0,
+                totalMemoryKb: 0,
+                nodeCount: 0,
+            };
+            byId.set(n.methodId, row);
+        }
+        row.selfTimeUs += n.selfTimeUs;
+        row.totalTimeUs += n.totalTimeUs;
+        row.callCount += n.callCount;
+        row.callFrameCount += n.callFrameCount;
+        row.selfMemoryKb += n.selfMemoryKb;
+        row.totalMemoryKb += n.totalMemoryKb;
+        row.nodeCount += 1;
+    }
+    // 同名不同 methodId 再按 name 合并一次（文档要求「同一个函数的节点还需要合并」）
+    const byName = new Map();
+    for (const row of byId.values()) {
+        const key = row.name || row.methodId;
+        const exist = byName.get(key);
+        if (!exist) {
+            byName.set(key, { ...row });
+            continue;
+        }
+        exist.selfTimeUs += row.selfTimeUs;
+        exist.totalTimeUs += row.totalTimeUs;
+        exist.callCount += row.callCount;
+        exist.callFrameCount += row.callFrameCount;
+        exist.selfMemoryKb += row.selfMemoryKb;
+        exist.totalMemoryKb += row.totalMemoryKb;
+        exist.nodeCount += row.nodeCount;
+        // 保留首次 methodId
+    }
+    const metricOf = (r) => {
+        switch (metric) {
+            case 'totalTime':
+                return r.totalTimeUs;
+            case 'callCount':
+                return r.callCount;
+            case 'selfMemory':
+                return r.selfMemoryKb;
+            case 'selfTime':
+            default:
+                return r.selfTimeUs;
+        }
+    };
+    const unit = metric === 'selfMemory' ? 'KB' : metric === 'callCount' ? '次' : 'ms';
+    const sorted = [...byName.values()].sort((a, b) => metricOf(b) - metricOf(a));
+    const rows = sorted.slice(0, topN).map((r) => {
+        const value = metric === 'callCount'
+            ? r.callCount
+            : metric === 'selfMemory'
+                ? round2(r.selfMemoryKb)
+                : round2(metricOf(r) / 1000); // μs → ms
+        return {
+            name: r.name,
+            methodId: r.methodId,
+            value,
+            unit,
+            selfTimeMs: round2(r.selfTimeUs / 1000),
+            totalTimeMs: round2(r.totalTimeUs / 1000),
+            selfMemoryKb: round2(r.selfMemoryKb),
+            callCount: r.callCount,
+            callFrameCount: r.callFrameCount,
+            nodeCount: r.nodeCount,
+            source,
+        };
+    });
+    return {
+        testMode,
+        metric,
+        unit,
+        rows,
+        totalNodes: nodes.length,
+        uniqueFunctions: byName.size,
+        apisUsed,
+    };
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}

package/dist/composite/top-functions.d.ts

@@ -0,0 +1,16 @@
+import type { UwaClient } from '../client.js';
+import type { CompositeTool } from './types.js';
+export interface FunctionRow {
+    name: string;
+    value: number;
+    unit?: string;
+    source: string;
+    label?: string;
+    methodId?: string;
+    selfTimeMs?: number;
+    totalTimeMs?: number;
+    callCount?: number;
+    nodeCount?: number;
+}
+export declare function runTopFunctions(client: UwaClient, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare const topFunctionsTool: CompositeTool;

package/dist/composite/top-functions.js

@@ -0,0 +1,133 @@
+import { z } from './types.js';
+import { errorResult, jsonToolResult, requireReportKey, topNOf } from './helpers.js';
+import { fetchReportIdentity } from './route-overview.js';
+import { aggregateMonoStack, aggregateOverviewStack } from './stack-agg.js';
+function resolveMetric(raw, mode) {
+    if (raw === 'totalTime' || raw === 'callCount' || raw === 'selfMemory' || raw === 'selfTime') {
+        return raw;
+    }
+    return mode === 'mono' ? 'selfMemory' : 'selfTime';
+}
+export async function runTopFunctions(client, args) {
+    const key = requireReportKey(args);
+    const topN = topNOf(args, 20);
+    const subtype = typeof args['serviceSubtype'] === 'string' && args['serviceSubtype']
+        ? String(args['serviceSubtype']).toLowerCase()
+        : undefined;
+    const identity = await fetchReportIdentity(client, key);
+    const apisUsed = ['get_report_detail'];
+    const mode = subtype ?? identity.serviceSubtype ?? 'overview';
+    const metric = resolveMetric(args['metric'], mode);
+    if (mode === 'mono') {
+        if (identity.engine !== 'unity') {
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                items: [],
+                _apisUsed: apisUsed,
+                _note: 'Mono 模式仅支持 Unity 报告。',
+                _limitations: ['engine!=unity'],
+            };
+        }
+        try {
+            const agg = await aggregateMonoStack(client, identity, topN, metric);
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                serviceSubtype: 'mono',
+                topN,
+                metric: agg.metric,
+                testMode: agg.testMode,
+                items: agg.rows,
+                totalNodes: agg.totalNodes,
+                uniqueFunctions: agg.uniqueFunctions,
+                _apisUsed: [...apisUsed, ...agg.apisUsed],
+                _note: `已下载 Mono 正向堆栈树并按函数名合并同名节点（共 ${agg.totalNodes} 个节点 → ${agg.uniqueFunctions} 个函数），` +
+                    `按 ${agg.metric} 降序取 Top ${agg.rows.length}。`,
+            };
+        }
+        catch (e) {
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                serviceSubtype: 'mono',
+                items: [],
+                _apisUsed: apisUsed,
+                _note: `Mono 堆栈树聚合失败：${e instanceof Error ? e.message : String(e)}`,
+                _limitations: ['mono_stack_unavailable'],
+            };
+        }
+    }
+    // Overview：必须以堆栈树 + idmap 为准；统计接口里的「卡顿重点函数 / func / 自定义函数组」都不完整。
+    try {
+        const agg = await aggregateOverviewStack(client, identity, topN, metric);
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            createDate: identity.createDate,
+            sdkVersion: identity.sdkVersion,
+            serviceSubtype: identity.serviceSubtype,
+            topN,
+            metric: agg.metric,
+            testMode: agg.testMode,
+            items: agg.rows,
+            totalNodes: agg.totalNodes,
+            uniqueFunctions: agg.uniqueFunctions,
+            _apisUsed: [...apisUsed, ...agg.apisUsed],
+            _note: `已下载主线程堆栈树并按函数名合并同名节点（共 ${agg.totalNodes} 个节点 → ${agg.uniqueFunctions} 个函数），` +
+                `按 ${agg.metric}（${agg.unit}）降序取 Top ${agg.rows.length}。` +
+                `默认排序字段为 selfTime（自身耗时），不是统计接口里的抽样指标。`,
+        };
+    }
+    catch (e) {
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            createDate: identity.createDate,
+            sdkVersion: identity.sdkVersion,
+            serviceSubtype: identity.serviceSubtype,
+            items: [],
+            _apisUsed: apisUsed,
+            _note: `堆栈树聚合失败：${e instanceof Error ? e.message : String(e)}。` +
+                `Overview 函数 Top 依赖 stack/overall/tree + stack/id/map（通常需 SDK ≥ 2.5.1 且开启 CPU 堆栈）。`,
+            _limitations: ['overview_stack_unavailable'],
+        };
+    }
+}
+export const topFunctionsTool = {
+    id: 'top_functions',
+    title: '函数耗时 Top N',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['top_functions', 'composite', 'preset.default', 'overview', 'mono'],
+    description: [
+        '从堆栈树聚合指定报告的函数 Top N（按自身耗时合并同名节点）。',
+        '适用引擎：Unity / UE｜复合工具',
+        'Overview：下载主线程堆栈树（stack/overall/tree/presign）+ 函数 idmap（stack/id/map），',
+        '将 methodId 还原为函数名，并把树上同一函数的多个节点合并（selfTime/callCount 相加），再取 Top N。',
+        '不要用统计接口里的「卡顿重点函数」或自定义函数组——那不是全量函数耗时。',
+        'Mono（仅 Unity）：走 Mono 正向堆栈树 + Mono 函数 idmap，默认按自身内存排序。',
+        '需要原始树时请直接调对应的 stack/presign 原子工具。',
+    ].join('\n'),
+    inputSchema: {
+        dataKey: z.string().optional().describe('报告 dataKey，与 recordId 二选一'),
+        recordId: z.union([z.string(), z.number()]).optional().describe('报告 recordId，与 dataKey 二选一'),
+        topN: z.number().optional().describe('返回条数，默认 20，最大 200'),
+        metric: z
+            .enum(['selfTime', 'totalTime', 'callCount', 'selfMemory'])
+            .optional()
+            .describe('排序指标，默认 Overview 用 selfTime（自身耗时 ms），Mono 用 selfMemory（KB）'),
+        serviceSubtype: z
+            .enum(['overview', 'mono'])
+            .optional()
+            .describe('报告模式，默认跟随报告详情；mono 仅 Unity'),
+    },
+    async handler(args, ctx) {
+        try {
+            const result = await runTopFunctions(ctx.client, args);
+            return jsonToolResult(result, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

package/dist/composite/top-resources.d.ts

@@ -0,0 +1,12 @@
+import type { UwaClient } from '../client.js';
+import type { CompositeTool } from './types.js';
+export interface ResourceRow {
+    name: string;
+    assetType: string;
+    memoryBytes: number;
+    count?: number;
+    extras?: Record<string, unknown>;
+    _source: string;
+}
+export declare function runTopResources(client: UwaClient, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare const topResourcesTool: CompositeTool;

package/dist/composite/top-resources.js

@@ -0,0 +1,184 @@
+import { z } from './types.js';
+import { errorResult, isObj, jsonToolResult, requireReportKey, topNOf, } from './helpers.js';
+import { fetchOverviewStatistic, fetchReportIdentity, preferAtResourceTable, } from './route-overview.js';
+import { viewOverview } from './overview-view.js';
+const DEFAULT_ASSET_TYPES = ['Texture', 'Mesh', 'Shader', 'Material', 'AnimationClip'];
+async function fetchUnityAssetType(client, identity, assetType, useAtTable) {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    if (useAtTable) {
+        const meta = (await client.call('GET', '/openapi/v1/data/gotonline/overview/at/resource/overall/table/presign', 'v1.0.1', { ...keyQuery, assetType }));
+        const url = typeof meta['dataPresignUrl'] === 'string' ? meta['dataPresignUrl'] : null;
+        if (!url)
+            return [];
+        const payload = await client.downloadPresign(url);
+        const json = payload.json;
+        const resources = extractAtResources(json);
+        return resources.map((r) => ({
+            name: String(r['name'] ?? r['id'] ?? ''),
+            assetType,
+            memoryBytes: Number(r['memMaximum'] ?? 0) || 0,
+            count: r['countMaximum'] != null ? Number(r['countMaximum']) : undefined,
+            extras: pickExtras(r, ['id', 'typeName', 'tags', 'lifecycle', 'properties']),
+            _source: 'at/resource/overall/table/presign',
+        }));
+    }
+    const data = (await client.call('GET', '/openapi/v1/data/gotonline/overview/memory/manage/data/report', 'v1.0.1', { ...keyQuery, assetType }));
+    const dict = isObj(data['Asset_dict']) ? data['Asset_dict'] : {};
+    return Object.values(dict)
+        .filter(isObj)
+        .map((r) => ({
+        name: String(r['name'] ?? ''),
+        assetType,
+        memoryBytes: Number(r['max_memory'] ?? 0) || 0,
+        count: r['max_count'] != null ? Number(r['max_count']) : undefined,
+        extras: pickExtras(r, ['resident_frames', 'last_zero_frame', 'has_rw', 'width', 'height', 'format']),
+        _source: 'memory/manage/data/report',
+    }));
+}
+function extractAtResources(json) {
+    if (!json)
+        return [];
+    if (Array.isArray(json))
+        return json.filter(isObj);
+    if (!isObj(json))
+        return [];
+    if (Array.isArray(json['resources']))
+        return json['resources'].filter(isObj);
+    // 偶发整包就是一张表
+    for (const v of Object.values(json)) {
+        if (Array.isArray(v) && v.length && isObj(v[0]) && ('memMaximum' in v[0] || 'name' in v[0])) {
+            return v.filter(isObj);
+        }
+    }
+    return [];
+}
+function pickExtras(r, keys) {
+    const out = {};
+    for (const k of keys)
+        if (r[k] !== undefined)
+            out[k] = r[k];
+    return Object.keys(out).length ? out : undefined;
+}
+/** 从 Overview 统计抽出类型级内存峰值（UE / 无逐资源列表时用）。 */
+function typeLevelFromOverview(view) {
+    return view.memory.map((m) => ({
+        name: m.name,
+        assetType: m.assetType,
+        memoryBytes: m.memoryBytes,
+        _source: m._source,
+    }));
+}
+export async function runTopResources(client, args) {
+    const key = requireReportKey(args);
+    const topN = topNOf(args, 20);
+    const assetTypes = normalizeAssetTypes(args['assetTypes']);
+    const identity = await fetchReportIdentity(client, key);
+    const apisUsed = ['get_report_detail'];
+    if (identity.engine === 'unreal') {
+        const { target, data } = await fetchOverviewStatistic(client, identity);
+        apisUsed.push(target.id);
+        const view = viewOverview(data);
+        const items = typeLevelFromOverview(view).slice(0, topN);
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            topN,
+            items,
+            _note: 'UE 无逐资源内存列表接口，此处返回 Overview 统计中的类型级峰值（非单个资源）。Unity 报告可得到逐资源 Top N。',
+            _apisUsed: apisUsed,
+            _overviewShape: view.shape,
+        };
+    }
+    // Unity
+    const { target, data } = await fetchOverviewStatistic(client, identity);
+    apisUsed.push(target.id);
+    const view = viewOverview(data);
+    const hasRes = view.hasResource === true;
+    if (!hasRes) {
+        const items = typeLevelFromOverview(view).slice(0, topN);
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            topN,
+            items,
+            _note: view.hasResource === false
+                ? '报告未开启资源采集（OverviewHasResource=0），无法拉逐资源列表；已回退为 Overview 类型级峰值。'
+                : '无法从统计结果判定是否开启资源采集；已回退为 Overview 类型级峰值。',
+            _apisUsed: apisUsed,
+            _limitations: [view.hasResource === false ? '未开启资源采集' : '资源采集状态未知'],
+            _overviewShape: view.shape,
+        };
+    }
+    const useAt = preferAtResourceTable(identity);
+    const settled = await Promise.allSettled(assetTypes.map((t) => fetchUnityAssetType(client, identity, t, useAt)));
+    const items = [];
+    const errors = [];
+    for (let i = 0; i < settled.length; i++) {
+        const r = settled[i];
+        const t = assetTypes[i];
+        if (r.status === 'fulfilled') {
+            items.push(...r.value);
+            apisUsed.push(useAt ? `at_resource_overall:${t}` : `memory_manage:${t}`);
+        }
+        else {
+            errors.push(`${t}: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+        }
+    }
+    items.sort((a, b) => b.memoryBytes - a.memoryBytes);
+    const top = items.slice(0, topN);
+    return {
+        engine: identity.engine,
+        dataKey: identity.dataKey,
+        createDate: identity.createDate,
+        sdkVersion: identity.sdkVersion,
+        assetTypes,
+        topN,
+        totalCandidates: items.length,
+        items: top,
+        _sourceKind: useAt ? 'at_resource_overall_presign' : 'memory_manage',
+        _apisUsed: apisUsed,
+        ...(errors.length ? { _partialErrors: errors } : {}),
+        _note: `已按内存峰值合并 ${assetTypes.length} 种资源类型，返回 Top ${top.length}。`,
+    };
+}
+function normalizeAssetTypes(raw) {
+    if (Array.isArray(raw) && raw.length)
+        return raw.map(String);
+    if (typeof raw === 'string' && raw.trim()) {
+        return raw.split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+    }
+    return [...DEFAULT_ASSET_TYPES];
+}
+export const topResourcesTool = {
+    id: 'top_resources',
+    title: '资源内存 Top N',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['top_resources', 'composite', 'preset.default', 'overview'],
+    description: [
+        '聚合指定报告的资源内存占用 Top N。',
+        '适用引擎：Unity / UE｜复合工具（内部串多个接口，调用方不必自己选 v1/v2）',
+        'Unity：按 assetType 并行拉取资源列表（解析日 ≥ 2026-06-25 优先 AT 总览预签名；否则 memory/manage），合并后按内存峰值排序。',
+        'UE：无逐资源列表，返回 Overview 统计中的类型级峰值，并在 _note 中标明。',
+        '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
+    ].join('\n'),
+    inputSchema: {
+        dataKey: z.string().optional().describe('报告 dataKey，与 recordId 二选一'),
+        recordId: z.union([z.string(), z.number()]).optional().describe('报告 recordId，与 dataKey 二选一'),
+        assetTypes: z
+            .array(z.string())
+            .optional()
+            .describe(`资源类型列表，默认 ${DEFAULT_ASSET_TYPES.join(',')}。Unity 每次内部按类型各查一次再合并`),
+        topN: z.number().optional().describe('返回条数，默认 20，最大 200'),
+    },
+    async handler(args, ctx) {
+        try {
+            const result = await runTopResources(ctx.client, args);
+            return jsonToolResult(result, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

package/dist/composite/types.d.ts

@@ -0,0 +1,25 @@
+import { z, type ZodTypeAny } from 'zod';
+import type { Engine } from '../spec.js';
+import type { UwaClient } from '../client.js';
+import type { NameCase } from '../tools.js';
+import type { ToolResult } from '../tools.js';
+export interface CompositeContext {
+    client: UwaClient;
+    maxChars: number;
+    nameCase: NameCase;
+    namePrefix: string;
+    /** --engine 过滤，'all' 表示不过滤 */
+    engine: Engine | 'all';
+}
+export interface CompositeTool {
+    id: string;
+    title: string;
+    description: string;
+    /** 适用引擎；过滤 --engine 时用 */
+    engines: Engine[];
+    /** --tool 过滤键，除 id 外还可含 composite / preset.default 等 */
+    filterKeys: string[];
+    inputSchema: Record<string, ZodTypeAny>;
+    handler: (args: Record<string, unknown>, ctx: CompositeContext) => Promise<ToolResult>;
+}
+export { z };

package/dist/composite/types.js

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export { z };

package/dist/presets.js

@@ -25,6 +25,10 @@ export const PRESET_DEFAULT = [
     'gotonline_overview_memory_manage_data_report',
     'gotonline_overview_method_group_statistic',
     'gotonline_overview_stack_stutter_full_presign',
+    // 复合工具（手写，见 src/composite/）
+    'top_resources',
+    'top_functions',
+    'report_diagnosis',
 ];
 /**
  * 每个接口对应的一组过滤键，用户在 --tool 里写任意一个即可命中。

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { COMPOSITE_TOOLS, selectCompositeTools } from './composite/index.js';
 import { type Engine } from './spec.js';
 import { type NameCase } from './tools.js';
 export interface ServerOptions {
@@ -16,10 +17,13 @@ export interface ServerOptions {
     timeoutMs: number;
     specPath?: string;
 }
-export declare const PACKAGE_VERSION = "0.1.0";
+export declare const PACKAGE_VERSION = "0.2.0";
 export declare function createServer(opts: ServerOptions): {
     server: McpServer;
     toolCount: number;
     total: number;
+    atomicCount: number;
+    compositeCount: number;
 };
 export declare function startStdio(opts: ServerOptions): Promise<void>;
+export { selectCompositeTools, COMPOSITE_TOOLS };