@uwa4d/openapi-mcp 0.2.0-beta.1 → 0.2.0-beta.3

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,263 @@
+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';
+/** 与 OpenAPI memory/manage、AT overall 文档枚举对齐（11 种）。 */
+const DEFAULT_ASSET_TYPES = [
+    'Texture',
+    'Mesh',
+    'AnimationClip',
+    'AudioClip',
+    'Material',
+    'Shader',
+    'Font',
+    'RenderTexture',
+    'ParticleSystem',
+    'AssetBundle',
+    'TextAsset',
+];
+/** AT 资源总览（Unity / UE 实测均可用）。 */
+async function fetchAtAssetType(client, identity, assetType) {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    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 resources = extractAtResources(payload.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',
+    }));
+}
+/** Unity 旧路径：memory/manage（仅 Unity，且 AT 不可用时回退）。 */
+async function fetchMemoryManageAssetType(client, identity, assetType) {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    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;
+}
+function typeLevelFromOverview(view) {
+    return view.memory.map((m) => ({
+        name: m.name,
+        assetType: m.assetType,
+        memoryBytes: m.memoryBytes,
+        _source: m._source,
+    }));
+}
+async function fetchPerAssetRows(client, identity, assetTypes, useAt) {
+    const apisUsed = [];
+    const errors = [];
+    const items = [];
+    const settled = await Promise.allSettled(assetTypes.map((t) => useAt ? fetchAtAssetType(client, identity, t) : fetchMemoryManageAssetType(client, identity, t)));
+    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)}`);
+        }
+    }
+    return {
+        items,
+        apisUsed,
+        errors,
+        sourceKind: useAt ? 'at_resource_overall_presign' : 'memory_manage',
+    };
+}
+function groupByAssetType(items, assetTypes, topN) {
+    const byType = {};
+    for (const t of assetTypes) {
+        byType[t] = items
+            .filter((r) => r.assetType === t)
+            .sort((a, b) => b.memoryBytes - a.memoryBytes)
+            .slice(0, topN);
+    }
+    return byType;
+}
+function normalizeGroupBy(raw) {
+    return raw === 'assetType' ? 'assetType' : 'merged';
+}
+export async function runTopResources(client, args) {
+    const key = requireReportKey(args);
+    const topN = topNOf(args, 20);
+    const assetTypes = normalizeAssetTypes(args['assetTypes']);
+    const groupBy = normalizeGroupBy(args['groupBy']);
+    const identity = await fetchReportIdentity(client, key);
+    const apisUsed = ['get_report_detail'];
+    // 先拉 Overview，用于资源开关判定与最终回退
+    const { target, data } = await fetchOverviewStatistic(client, identity);
+    apisUsed.push(target.id);
+    const view = viewOverview(data);
+    const canAt = preferAtResourceTable(identity);
+    // Unity 旧报告可回退 memory/manage；UE 没有这条，只能 AT 或类型级峰值
+    const useAt = canAt || identity.engine === 'unreal';
+    const useMemoryManage = !useAt && identity.engine === 'unity';
+    const packResult = (items, extra) => {
+        const sorted = [...items].sort((a, b) => b.memoryBytes - a.memoryBytes);
+        if (groupBy === 'assetType') {
+            const byType = groupByAssetType(sorted, assetTypes, topN);
+            const flat = Object.values(byType).flat();
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                createDate: identity.createDate,
+                sdkVersion: identity.sdkVersion,
+                assetTypes,
+                topN,
+                groupBy,
+                byType,
+                items: flat,
+                _overviewShape: view.shape,
+                ...extra,
+            };
+        }
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            createDate: identity.createDate,
+            sdkVersion: identity.sdkVersion,
+            assetTypes,
+            topN,
+            groupBy,
+            items: sorted.slice(0, topN),
+            _overviewShape: view.shape,
+            ...extra,
+        };
+    };
+    if (!useAt && !useMemoryManage) {
+        return packResult(typeLevelFromOverview(view), {
+            _note: '无法使用 AT 资源列表，已回退为 Overview 类型级峰值。',
+            _apisUsed: apisUsed,
+            _limitations: ['at_resource_unavailable'],
+        });
+    }
+    // Unity：明确未开资源采集时不必打 AT；UE 的 AT 实测可直接用，不依赖 OverviewHasResource 字段
+    if (identity.engine === 'unity' && view.hasResource === false && !canAt) {
+        return packResult(typeLevelFromOverview(view), {
+            _note: '报告未开启资源采集，无法拉逐资源列表；已回退为 Overview 类型级峰值。',
+            _apisUsed: apisUsed,
+            _limitations: ['未开启资源采集'],
+        });
+    }
+    let fetched = await fetchPerAssetRows(client, identity, assetTypes, useAt);
+    // AT 全部失败时，Unity 还可回退 memory/manage
+    if (useAt && fetched.items.length === 0 && identity.engine === 'unity') {
+        const fallback = await fetchPerAssetRows(client, identity, assetTypes, false);
+        if (fallback.items.length > 0 || fallback.errors.length === 0)
+            fetched = fallback;
+    }
+    apisUsed.push(...fetched.apisUsed);
+    if (fetched.items.length === 0) {
+        const fallbackItems = typeLevelFromOverview(view);
+        return packResult(fallbackItems, {
+            _sourceKind: fetched.sourceKind,
+            _apisUsed: apisUsed,
+            ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
+            _note: fallbackItems.length > 0
+                ? '逐资源列表为空，已回退为 Overview 类型级峰值。'
+                : '逐资源列表与类型级峰值均为空（报告可能未采集资源内存）。',
+            _limitations: ['per_asset_empty'],
+        });
+    }
+    const note = groupBy === 'assetType'
+        ? `已按类型各取 Top ${topN}（${fetched.sourceKind}，共 ${assetTypes.length} 种）。`
+        : `已按内存峰值合并 ${assetTypes.length} 种资源类型（${fetched.sourceKind}），返回全局 Top ${topN}。`;
+    return packResult(fetched.items, {
+        totalCandidates: fetched.items.length,
+        _sourceKind: fetched.sourceKind,
+        _apisUsed: apisUsed,
+        ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
+        _note: note,
+    });
+}
+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｜复合工具',
+        'Unity / UE 均优先走 AT 资源总览预签名（at/resource/overall/table/presign），按 assetType 并行下载后合并排序。',
+        'groupBy=merged（默认）：跨类型合并后取全局 Top N；groupBy=assetType：每种类型各取 Top N，返回 byType。',
+        'Unity 旧报告（解析日 < 2026-06-25）回退 memory/manage；拉不到逐资源时再回退 Overview 类型级峰值。',
+        '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
+    ].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(`资源类型列表，默认全部 11 种：${DEFAULT_ASSET_TYPES.join(',')}。每次内部按类型各查一次`),
+        groupBy: z
+            .enum(['merged', 'assetType'])
+            .optional()
+            .describe("分组模式：merged=跨类型全局 Top N（默认）；assetType=每种类型各 Top N，返回 byType"),
+        topN: z.number().optional().describe('返回条数，默认 20，最大 200；groupBy=assetType 时为每类型条数'),
+    },
+    async handler(args, ctx) {
+        try {
+            const result = await runTopResources(ctx.client, args);
+            return jsonToolResult(result, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};