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

package/README.md

@@ -128,7 +128,7 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 | 工具 | 做什么 |
 | --- | --- |
 | `report_diagnosis` | 单份报告体检：自动选对统计 v1/v2，附带 Top 资源/函数与场景摘要 |
-| `top_resources` | 资源内存 Top N（Unity 逐资源合并多类型；UE 为类型级峰值） |
+| `top_resources` | 资源内存 Top N（默认 11 种类型；`groupBy=merged` 全局 Top / `assetType` 按类型各 Top） |
 | `top_functions` | 函数 Top N：下载堆栈树 + idmap，按函数名合并同名节点后再排序 |
 
 不确定该调统计 1.0 还是 2.0 时，优先用这三个，不必自己判断日期和 SDK。

package/dist/composite/overview-view.d.ts

@@ -1,7 +1,8 @@
 /**
- * Overview 统计 v1 / v2 返回结构差异很大：
- * - v1：flat brief / func / asset_stats / summary
- * - v2（Unity POST）：categories[] + basicInfo{}
+ * Overview 统计 v1 / v2 / UE 2.0 返回结构差异很大：
+ * - Unity v1：对象形 brief { fps_mean: [49] } + asset_stats
+ * - UE 2.0：数组形 brief [{ label, value }] + Resource 段
+ * - Unity v2（POST）：categories[] + basicInfo{}
  * 这里统一抽成复合工具能用的扁平视图。
  */
 export interface OverviewView {
@@ -26,7 +27,7 @@ export interface OverviewView {
     }[];
     /** 是否开启资源采集；无法判定时为 null */
     hasResource: boolean | null;
-    shape: 'v1' | 'v2' | 'unknown';
+    shape: 'v1' | 'v2' | 'ue-v2' | 'unknown';
 }
 /** 把 unwrap 后的报告或原始 data 统一成 OverviewView。 */
 export declare function viewOverview(data: unknown): OverviewView;

package/dist/composite/overview-view.js

@@ -23,6 +23,10 @@ function toBytes(value, unit) {
     // 无单位时：很大的数当字节，否则当 MB（兼容 v1 brief 的 _mem_max_mb）
     return value > 10_000 ? Math.round(value) : Math.round(value * 1024 * 1024);
 }
+function unitFromLabel(label) {
+    const m = /[（(]\s*(MB|KB|GB|B|字节)\s*[）)]/i.exec(label);
+    return m?.[1]?.toLowerCase() === '字节' ? 'b' : m?.[1]?.toLowerCase();
+}
 /** 排除「数量峰值」这类非内存指标。 */
 function looksLikeMemoryMetric(label, key, unit) {
     if (/数量|count|cnt/i.test(label) || /count|cnt/i.test(key))
@@ -32,8 +36,42 @@ function looksLikeMemoryMetric(label, key, unit) {
     return /内存|memory|mem|reserved|used|heap|gfx|mono|lua/i.test(label + key);
 }
 function guessAssetType(label, fallback) {
-    const m = /(Texture|Mesh|Shader|Material|Animation|Audio|Font|RenderTexture|AssetBundle|TextAsset|Lua|Mono|Gfx|GC)/i.exec(label);
-    return m?.[1] ?? fallback;
+    const rules = [
+        [/RenderTexture/i, 'RenderTexture'],
+        [/纹理|Texture/i, 'Texture'],
+        [/网格|Mesh/i, 'Mesh'],
+        [/Shader/i, 'Shader'],
+        [/材质|Material/i, 'Material'],
+        [/动画|Animation/i, 'AnimationClip'],
+        [/音频|Audio/i, 'AudioClip'],
+        [/字体|Font/i, 'Font'],
+        [/AssetBundle/i, 'AssetBundle'],
+        [/TextAsset|文本资源/i, 'TextAsset'],
+        [/粒子|Particle/i, 'ParticleSystem'],
+        [/Lua/i, 'Lua'],
+        [/Mono/i, 'Mono'],
+        [/Gfx/i, 'Gfx'],
+    ];
+    for (const [re, t] of rules)
+        if (re.test(label))
+            return t;
+    return fallback;
+}
+/** 把 summary / UE brief 一类 [{label,value}] 展开成 map。 */
+function expandLabelValueRows(rows) {
+    const out = {};
+    for (const row of rows) {
+        if (!isObj(row))
+            continue;
+        const label = String(row['label'] ?? row['key'] ?? '');
+        if (!label)
+            continue;
+        out[label] = firstVal(row['value'] ?? row['data']);
+        const key = row['key'];
+        if (typeof key === 'string' && key && !(key in out))
+            out[key] = out[label];
+    }
+    return out;
 }
 function basicInfoMap(basicInfo) {
     const out = {};
@@ -75,6 +113,61 @@ function parseHasResource(summary, brief) {
     }
     return null;
 }
+/**
+ * UE 2.0：从 Resource / resource 段判定资源采集。
+ * 「资源内存占用峰值」> 0 → true；段存在但无法确认时返回 null（不误报关闭）。
+ */
+function parseHasResourceFromResourceSection(report) {
+    const section = report['Resource'] ?? report['resource'];
+    if (!Array.isArray(section) || section.length === 0)
+        return null;
+    let peak = null;
+    let anyMemPositive = false;
+    for (const item of section) {
+        if (!isObj(item))
+            continue;
+        const label = String(item['label'] ?? item['key'] ?? '');
+        const n = numOf(item['value'] ?? item['data']);
+        if (n == null)
+            continue;
+        if (/^资源内存占用峰值/.test(label) || /资源内存占用峰值（MB）/.test(label))
+            peak = n;
+        const unit = unitFromLabel(label) ?? '';
+        if (looksLikeMemoryMetric(label, '', unit) && n > 0)
+            anyMemPositive = true;
+    }
+    if (peak != null && peak > 0)
+        return true;
+    if (anyMemPositive)
+        return true;
+    return null;
+}
+/** 解析 Resource / resource 数组 → memory[]（排除数量峰值）。 */
+function memoryFromResourceSection(report) {
+    const section = report['Resource'] ?? report['resource'];
+    if (!Array.isArray(section))
+        return [];
+    const memory = [];
+    for (const item of section) {
+        if (!isObj(item))
+            continue;
+        const label = String(item['label'] ?? item['key'] ?? '');
+        const num = numOf(item['value'] ?? item['data']);
+        if (!label || num == null)
+            continue;
+        const unit = unitFromLabel(label) ?? 'mb';
+        if (!looksLikeMemoryMetric(label, '', unit))
+            continue;
+        // 总「资源内存占用峰值」不绑具体类型，仍保留便于看总量
+        memory.push({
+            name: label,
+            assetType: guessAssetType(label, 'Resource'),
+            memoryBytes: toBytes(num, unit),
+            _source: 'overview.Resource',
+        });
+    }
+    return memory;
+}
 function extractV2(data) {
     const summary = basicInfoMap(data['basicInfo']);
     const brief = {};
@@ -130,24 +223,21 @@ function extractV2(data) {
         shape: 'v2',
     };
 }
-function extractV1(report) {
+function extractV1OrUe(report) {
     const brief = {};
     const summary = {};
     const functions = [];
     const memory = [];
-    if (isObj(report['brief'])) {
+    const briefIsArray = Array.isArray(report['brief']);
+    if (briefIsArray) {
+        Object.assign(brief, expandLabelValueRows(report['brief']));
+    }
+    else if (isObj(report['brief'])) {
         for (const [k, v] of Object.entries(report['brief']))
             brief[k] = firstVal(v);
     }
     if (Array.isArray(report['summary'])) {
-        for (const row of report['summary']) {
-            if (!isObj(row))
-                continue;
-            const label = String(row['label'] ?? row['key'] ?? '');
-            if (!label)
-                continue;
-            summary[label] = firstVal(row['value'] ?? row['data']);
-        }
+        Object.assign(summary, expandLabelValueRows(report['summary']));
     }
     else if (isObj(report['reportInfo'])) {
         Object.assign(summary, report['reportInfo']);
@@ -178,6 +268,29 @@ function extractV1(report) {
             });
         }
     }
+    // UE 数组 brief 里也可能夹带内存类指标（类型级）
+    if (briefIsArray) {
+        for (const [label, v] of Object.entries(brief)) {
+            if (!looksLikeMemoryMetric(label, '', unitFromLabel(label) ?? ''))
+                continue;
+            const num = numOf(v);
+            if (num == null)
+                continue;
+            if (memory.some((m) => m.name === label))
+                continue;
+            memory.push({
+                name: label,
+                assetType: guessAssetType(label, 'brief'),
+                memoryBytes: toBytes(num, unitFromLabel(label) ?? 'mb'),
+                _source: 'overview.brief',
+            });
+        }
+    }
+    for (const row of memoryFromResourceSection(report)) {
+        if (memory.some((m) => m.name === row.name))
+            continue;
+        memory.push(row);
+    }
     if (Array.isArray(report['asset_stats'])) {
         for (const item of report['asset_stats']) {
             if (!isObj(item))
@@ -191,7 +304,7 @@ function extractV1(report) {
             const looksMb = /mb|内存/i.test(label);
             memory.push({
                 name: label,
-                assetType: label,
+                assetType: guessAssetType(label, label),
                 memoryBytes: looksMb ? toBytes(num, 'mb') : toBytes(num, 'b'),
                 _source: 'overview.asset_stats',
             });
@@ -210,13 +323,15 @@ function extractV1(report) {
     }
     functions.sort((a, b) => b.value - a.value);
     memory.sort((a, b) => b.memoryBytes - a.memoryBytes);
+    const fromSection = parseHasResourceFromResourceSection(report);
+    const fromFields = parseHasResource(summary, brief);
     return {
         brief,
         summary,
         functions,
         memory,
-        hasResource: parseHasResource(summary, brief),
-        shape: 'v1',
+        hasResource: fromSection ?? fromFields,
+        shape: briefIsArray ? 'ue-v2' : 'v1',
     };
 }
 /** 把 unwrap 后的报告或原始 data 统一成 OverviewView。 */
@@ -243,10 +358,16 @@ export function viewOverview(data) {
         if (Array.isArray(v) && v.length && isObj(v[0]))
             return viewOverview(v[0]);
     }
-    if ('brief' in root || 'func' in root || 'summary' in root || 'asset_stats' in root)
-        return extractV1(root);
+    if ('brief' in root ||
+        'func' in root ||
+        'summary' in root ||
+        'asset_stats' in root ||
+        'Resource' in root ||
+        'resource' in root) {
+        return extractV1OrUe(root);
+    }
     // 可能整包就是 v2 包在更深一层
     if (values.length && isObj(values[0]) && Array.isArray(values[0]['categories']))
         return extractV2(values[0]);
-    return extractV1(root);
+    return extractV1OrUe(root);
 }

package/dist/composite/report-diagnosis.js

@@ -20,22 +20,33 @@ function summarizeScenes(data) {
     }
     return { keys: Object.keys(obj).slice(0, 30) };
 }
-/** brief 全量可能很长，体检只保留常见关键指标。 */
+/** brief 全量可能很长，体检只保留常见关键指标（含 Unity key 与 UE 中文 label）。 */
 function pickImportantBrief(brief) {
-    const prefer = [
+    const preferExact = [
         'fps_mean',
         'fps',
         'FPS均值',
+        'FPS均值（帧/秒）',
         'jank_rate',
+        'Jank均值',
+        'Jank均值（次/分钟）',
         'cpu_freq_mean',
         'Total_Reserved_Memory_Bytes_maximum',
         'Reserved Total峰值',
+        '设备内存峰值（MB）',
         'lua_total_memory_maximum',
     ];
+    const preferLoose = [/fps/i, /jank/i, /设备内存/, /reserved.*memory/i, /卡顿/];
     const out = {};
-    for (const k of prefer)
+    for (const k of preferExact)
         if (brief[k] !== undefined)
             out[k] = brief[k];
+    for (const [k, v] of Object.entries(brief)) {
+        if (k in out)
+            continue;
+        if (preferLoose.some((re) => re.test(k)))
+            out[k] = v;
+    }
     let n = 0;
     for (const [k, v] of Object.entries(brief)) {
         if (k in out)
@@ -72,7 +83,6 @@ export const reportDiagnosisTool = {
             const { target, data } = await fetchOverviewStatistic(ctx.client, identity);
             apisUsed.push(target.id);
             const view = viewOverview(data);
-            const hasRes = view.hasResource === true;
             let topResources = null;
             try {
                 topResources = await runTopResources(ctx.client, { ...key, topN: 10 });
@@ -116,8 +126,10 @@ export const reportDiagnosisTool = {
             catch (e) {
                 limitations.push(`场景统计失败：${e instanceof Error ? e.message : String(e)}`);
             }
-            if (!hasRes)
-                limitations.push('未开启资源采集或无法从 brief 判定，逐资源 Top 可能为空');
+            // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
+            if (view.hasResource === false) {
+                limitations.push('未开启资源采集，逐资源 Top 可能为空');
+            }
             const result = {
                 report: {
                     dataKey: identity.dataKey,
@@ -130,10 +142,15 @@ export const reportDiagnosisTool = {
                 },
                 routedOverview: target.id,
                 overviewShape: view.shape,
+                hasResource: view.hasResource,
                 summary: view.summary,
                 brief: pickImportantBrief(view.brief),
                 topResources: topResources
-                    ? { items: topResources['items'], note: topResources['_note'] }
+                    ? {
+                        items: topResources['items'],
+                        byType: topResources['byType'],
+                        note: topResources['_note'],
+                    }
                     : null,
                 topFunctions: topFunctions
                     ? {

package/dist/composite/route-overview.d.ts

@@ -56,6 +56,7 @@ export declare function fetchReportIdentity(client: UwaClient, key: {
 export declare function resolveOverviewTarget(identity: ReportIdentity): OverviewTarget;
 /** Unity 场景统计路由；UE 无独立 scene v1/v2 对，返回 null。 */
 export declare function resolveSceneTarget(identity: ReportIdentity): SceneTarget | null;
+/** Unity / UE 共用 AT 资源总览列表；解析日 ≥ 2026-06-25 时优先走这条。 */
 export declare function preferAtResourceTable(identity: ReportIdentity): boolean;
 /** 调用已路由的 Overview 统计，返回原始 data + 路由元信息。 */
 export declare function fetchOverviewStatistic(client: UwaClient, identity: ReportIdentity): Promise<{

package/dist/composite/route-overview.js

@@ -136,8 +136,9 @@ export function resolveSceneTarget(identity) {
         apiVersion: 'v1.0.1',
     };
 }
+/** Unity / UE 共用 AT 资源总览列表；解析日 ≥ 2026-06-25 时优先走这条。 */
 export function preferAtResourceTable(identity) {
-    return identity.engine === 'unity' && identity.createDate != null && dayGte(identity.createDate, AT_RESOURCE_DAY);
+    return identity.createDate != null && dayGte(identity.createDate, AT_RESOURCE_DAY);
 }
 /** 调用已路由的 Overview 统计，返回原始 data + 路由元信息。 */
 export async function fetchOverviewStatistic(client, identity) {

package/dist/composite/top-resources.js

@@ -2,28 +2,45 @@ 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) {
+/** 与 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 };
-    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)
@@ -46,7 +63,6 @@ function extractAtResources(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);
@@ -61,7 +77,6 @@ function pickExtras(r, keys) {
             out[k] = r[k];
     return Object.keys(out).length ? out : undefined;
 }
-/** 从 Overview 统计抽出类型级内存峰值（UE / 无逐资源列表时用）。 */
 function typeLevelFromOverview(view) {
     return view.memory.map((m) => ({
         name: m.name,
@@ -70,84 +85,143 @@ function typeLevelFromOverview(view) {
         _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'];
-    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
+    // 先拉 Overview，用于资源开关判定与最终回退
     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);
+    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,
-            items,
-            _note: view.hasResource === false
-                ? '报告未开启资源采集（OverviewHasResource=0），无法拉逐资源列表；已回退为 Overview 类型级峰值。'
-                : '无法从统计结果判定是否开启资源采集；已回退为 Overview 类型级峰值。',
-            _apisUsed: apisUsed,
-            _limitations: [view.hasResource === false ? '未开启资源采集' : '资源采集状态未知'],
+            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'],
+        });
     }
-    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)}`);
-        }
+    // Unity：明确未开资源采集时不必打 AT；UE 的 AT 实测可直接用，不依赖 OverviewHasResource 字段
+    if (identity.engine === 'unity' && view.hasResource === false && !canAt) {
+        return packResult(typeLevelFromOverview(view), {
+            _note: '报告未开启资源采集，无法拉逐资源列表；已回退为 Overview 类型级峰值。',
+            _apisUsed: apisUsed,
+            _limitations: ['未开启资源采集'],
+        });
     }
-    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',
+    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,
-        ...(errors.length ? { _partialErrors: errors } : {}),
-        _note: `已按内存峰值合并 ${assetTypes.length} 种资源类型，返回 Top ${top.length}。`,
-    };
+        ...(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 raw
+            .split(/[,，]/)
+            .map((s) => s.trim())
+            .filter(Boolean);
     }
     return [...DEFAULT_ASSET_TYPES];
 }
@@ -157,10 +231,11 @@ export const topResourcesTool = {
     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 中标明。',
+        '聚合指定报告的资源内存占用 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: {
@@ -169,8 +244,12 @@ export const topResourcesTool = {
         assetTypes: z
             .array(z.string())
             .optional()
-            .describe(`资源类型列表，默认 ${DEFAULT_ASSET_TYPES.join(',')}。Unity 每次内部按类型各查一次再合并`),
-        topN: z.number().optional().describe('返回条数，默认 20，最大 200'),
+            .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 {

package/dist/server.d.ts

@@ -17,7 +17,8 @@ export interface ServerOptions {
     timeoutMs: number;
     specPath?: string;
 }
-export declare const PACKAGE_VERSION = "0.2.0";
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export declare const PACKAGE_VERSION: string;
 export declare function createServer(opts: ServerOptions): {
     server: McpServer;
     toolCount: number;

package/dist/server.js

@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { UwaClient } from './client.js';
@@ -5,7 +8,18 @@ import { registerCompositeTools, COMPOSITE_TOOLS, selectCompositeTools } from '.
 import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
-export const PACKAGE_VERSION = '0.2.0';
+function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export const PACKAGE_VERSION = readPackageVersion();
 export function createServer(opts) {
     const spec = loadSpec(opts.specPath);
     const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });

package/dist/version-guide.js

@@ -50,6 +50,9 @@ export const VERSION_GUIDE = {
         '【选用规则——务必先看】',
         '- 自定义面板帧数据 2.0。需 SDK ≥ 2.5.1，最多 3 个面板；不支持内存类面板。',
         '- 要统计值（含场景维度）用 gotonline_overview_indicator_statistic_dashboard。',
+        '- 【横轴——勿混用】外层 x_axis 为逐帧共享横轴（1、2、3…）；y_axis.{指标名}.x_axis 为该曲线专属横轴（常见步长 30：0、30、60…）。',
+        '- 读取某条曲线时：若存在专属 x_axis 必须用专属，否则才用外层共享 x_axis。把共享横轴套到 FPS 等专属曲线会错位。',
+        '- 响应另含 _axisBinding / _axisHint，按其中 xAxisSource 取值即可。',
     ].join('\n'),
     gotonline_overview_memory_usage_snapshot: [
         '【选用规则——务必先看】',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.3",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {