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

package/dist/composite/top-functions.js

@@ -0,0 +1,178 @@
+import { z } from './types.js';
+import { errorResult, jsonToolResult, requireReportKey, topNOf } from './helpers.js';
+import { fetchReportIdentity } from './route-overview.js';
+import { aggregateMonoStack, aggregateOverviewStackFromStatistic } from './stack-agg.js';
+import { filterRowsByNamePattern } from './name-pattern.js';
+function resolveOverviewMetricInput(raw) {
+    if (raw === 'totalTime' || raw === 'callCount' || raw === 'selfMemory' || raw === 'selfTime') {
+        return raw;
+    }
+    return undefined;
+}
+function resolveMonoMetric(raw) {
+    if (raw === 'totalTime' || raw === 'callCount' || raw === 'selfMemory' || raw === 'selfTime') {
+        return raw;
+    }
+    return 'selfMemory';
+}
+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';
+    if (mode === 'mono') {
+        const metric = resolveMonoMetric(args['metric']);
+        if (identity.engine !== 'unity') {
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                serviceSubtype: 'mono',
+                items: [],
+                _apisUsed: apisUsed,
+                _note: 'Mono 模式仅支持 Unity 报告（与 Overview stackTestMode 无关）。',
+                _limitations: ['engine!=unity'],
+            };
+        }
+        try {
+            const namePattern = typeof args['namePattern'] === 'string' && args['namePattern'].trim()
+                ? String(args['namePattern']).trim()
+                : undefined;
+            const fetchN = namePattern ? Math.max(topN, 200) : topN;
+            const agg = await aggregateMonoStack(client, identity, fetchN, metric);
+            const filtered = filterRowsByNamePattern(agg.rows, namePattern);
+            const items = filtered.rows.slice(0, topN);
+            return {
+                engine: identity.engine,
+                dataKey: identity.dataKey,
+                serviceSubtype: 'mono',
+                topN,
+                metric: agg.metric,
+                namePattern: namePattern ?? null,
+                matchedFunctions: namePattern ? filtered.matchedTotal : agg.uniqueFunctions,
+                items,
+                totalNodes: agg.totalNodes,
+                uniqueFunctions: agg.uniqueFunctions,
+                _apisUsed: [...apisUsed, ...agg.apisUsed],
+                _note: `Mono 模式：已下载正向堆栈树合并取 Top ${items.length}（共 ${agg.totalNodes} 节点）。` +
+                    `Mono 不使用 Overview stackTestMode；默认按 selfMemory 排序。` +
+                    (namePattern ? ` namePattern「${String(namePattern)}」命中 ${filtered.matchedTotal} 个。` : ''),
+            };
+        }
+        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'],
+            };
+        }
+    }
+    const threadName = typeof args['threadName'] === 'string' && args['threadName'].trim()
+        ? String(args['threadName']).trim()
+        : undefined;
+    const metricInput = resolveOverviewMetricInput(args['metric']);
+    const namePattern = typeof args['namePattern'] === 'string' && args['namePattern'].trim()
+        ? String(args['namePattern']).trim()
+        : undefined;
+    try {
+        const agg = await aggregateOverviewStackFromStatistic(client, identity, topN, metricInput, threadName, namePattern);
+        const nameFilterNote = namePattern
+            ? agg.rows.length === 0
+                ? ` namePattern「${namePattern}」无匹配函数。`
+                : ` namePattern「${namePattern}」已过滤后取 Top ${agg.rows.length}。`
+            : '';
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            createDate: identity.createDate,
+            sdkVersion: identity.sdkVersion,
+            serviceSubtype: 'overview',
+            stackTestMode: agg.stackTestMode,
+            availableMetrics: agg.availableMetrics,
+            availableFields: agg.availableFields,
+            topN,
+            metric: agg.metric,
+            namePattern: namePattern ?? null,
+            items: agg.rows,
+            totalNodes: agg.totalNodes,
+            uniqueFunctions: agg.uniqueFunctions,
+            _apisUsed: [...apisUsed, ...agg.apisUsed],
+            _note: `Overview 模式 stackTestMode=${agg.stackTestMode}。${agg.metricGuide ?? ''} ` +
+                `本次按 ${agg.metric} 排序，Top ${agg.rows.length} / 共 ${agg.totalNodes} 函数。` +
+                `数据来自 method/idmap/statistic v1.0.2（非堆栈树解析）。` +
+                `逐帧曲线：method/curve/presign v1.0.2 + stackMethodId。` +
+                (identity.engine === 'unreal'
+                    ? ` UE 默认 threadName=GameThread${threadName ? `（本次 ${threadName}）` : ''}；UE 固定 CPU_ONLY。`
+                    : '') +
+                nameFilterNote,
+        };
+    }
+    catch (e) {
+        return {
+            engine: identity.engine,
+            dataKey: identity.dataKey,
+            createDate: identity.createDate,
+            sdkVersion: identity.sdkVersion,
+            serviceSubtype: 'overview',
+            items: [],
+            _apisUsed: apisUsed,
+            _note: `Overview 函数 Top 失败：${e instanceof Error ? e.message : String(e)}。` +
+                `通常需 SDK ≥ 2.5.1 且报告开启堆栈。`,
+            _limitations: ['overview_idmap_statistic_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：method/idmap/statistic v1.0.2；stackTestMode 决定可用字段（仅 Overview）：',
+        '  CPU_ONLY → selfTimeMean/totalTimeMean/callCountTotal；',
+        '  LUA_MEM_ONLY → callCountTotal/selfMemoryMean/selfMemoryTotal；',
+        '  CPU_AND_LUA_MEM → 全部；UE 固定 CPU_ONLY。',
+        'Mono（仅 Unity）：独立堆栈树，不使用 stackTestMode，默认 selfMemory。',
+        '逐帧曲线：method/curve/presign v1.0.2 + stackMethodId。',
+        'namePattern：可选，按函数名子串或 /正则/ 过滤（Overview 在 idmap 结果上过滤；Mono 在合并后的函数列表上过滤）。',
+    ].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'),
+        namePattern: z
+            .string()
+            .optional()
+            .describe('函数名过滤：默认子串匹配（忽略大小写）；正则写 /pattern/i，如 /Canvas\\./ 或 Update'),
+        metric: z
+            .enum(['selfTime', 'totalTime', 'callCount', 'selfMemory'])
+            .optional()
+            .describe('排序指标。Overview 须与 stackTestMode 匹配（CPU_ONLY 无 selfMemory；LUA_MEM_ONLY 无 selfTime/totalTime）；未传时 Overview 按模式默认 selfTime 或 selfMemory'),
+        threadName: z
+            .string()
+            .optional()
+            .describe('UE Overview 线程名，默认 GameThread；Unity 忽略'),
+        serviceSubtype: z
+            .enum(['overview', 'mono'])
+            .optional()
+            .describe('overview（默认）或 mono；stackTestMode 仅 overview 有效'),
+    },
+    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 { withRateLimitAnnotation } from '../error-hints.js';
+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, withRateLimitAnnotation({
+            _sourceKind: fetched.sourceKind,
+            _apisUsed: apisUsed,
+            _note: fallbackItems.length > 0
+                ? '逐资源列表为空，已回退为 Overview 类型级峰值。'
+                : '逐资源列表与类型级峰值均为空（报告可能未采集资源内存）。',
+            _limitations: ['per_asset_empty'],
+        }, fetched.errors.length ? fetched.errors : undefined));
+    }
+    const note = groupBy === 'assetType'
+        ? `已按类型各取 Top ${topN}（${fetched.sourceKind}，共 ${assetTypes.length} 种）。`
+        : `已按内存峰值合并 ${assetTypes.length} 种资源类型（${fetched.sourceKind}），返回全局 Top ${topN}。`;
+    return packResult(fetched.items, withRateLimitAnnotation({
+        totalCandidates: fetched.items.length,
+        _sourceKind: fetched.sourceKind,
+        _apisUsed: apisUsed,
+        _note: note,
+    }, fetched.errors.length ? fetched.errors : undefined));
+}
+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 类型级峰值。',
+        '内部按 assetType 并行请求，易触发 OpenAPI 限流 31004（UWA 服务端保护，预期行为）。遇限流见 _rateLimitHint：可缩小 assetTypes、稍等重试；部分类型限流时已有 Top 仍可用。',
+        '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
+    ].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);
+        }
+    },
+};

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/error-hints.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export declare const FILE_META_REASONS: {
+    readonly LG_META_ABSENT: "LG_META_ABSENT";
+    readonly LG_RUNTIME_PATH_MISSING: "LG_RUNTIME_PATH_MISSING";
+    readonly AT_META_ABSENT: "AT_META_ABSENT";
+    readonly AT_META_TYPE_INVALID: "AT_META_TYPE_INVALID";
+    readonly AT_META_PATH_MISSING: "AT_META_PATH_MISSING";
+};
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export declare const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export declare const RATE_LIMIT_HINT: string;
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export declare function isRateLimitMessage(text: string): boolean;
+/** _partialErrors 中是否有限流项。 */
+export declare function hasRateLimitInPartialErrors(errors: string[]): boolean;
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export declare function withRateLimitAnnotation(extra: Record<string, unknown>, partialErrors?: string[]): Record<string, unknown>;
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;

package/dist/error-hints.js

@@ -0,0 +1,80 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export const FILE_META_REASONS = {
+    LG_META_ABSENT: 'LG_META_ABSENT',
+    LG_RUNTIME_PATH_MISSING: 'LG_RUNTIME_PATH_MISSING',
+    AT_META_ABSENT: 'AT_META_ABSENT',
+    AT_META_TYPE_INVALID: 'AT_META_TYPE_INVALID',
+    AT_META_PATH_MISSING: 'AT_META_PATH_MISSING',
+};
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export const RATE_LIMIT_HINT = 'OpenAPI 限流（31004）是 UWA 服务端保护，不是报告无数据或接口故障。可稍等重试、减少并发或缩小 assetTypes；' +
+    '若 _partialErrors 仅部分类型限流，已有 Top 仍可用，需说明可能不完整。';
+const ERROR_HINTS_BY_CODE = {
+    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
+    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
+    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
+    24052: '请求参数有误，请对照接口文档检查',
+    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
+    24056: '签名错误，检查 appSecret 是否正确',
+    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
+    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）；勿把瞬时失败说成「一定没有数据」',
+    31004: 'OpenAPI 接口限流（UWA 服务端保护，预期行为）。稍等重试，或减少并行请求/缩小查询范围（如 top_resources 的 assetTypes）；' +
+        '勿当成报告无数据或接口永久故障。',
+};
+/** OpenAPI 已按引擎写好的稳定文案（优先沿用，再补 AI 纪律）。 */
+function hintForOpenApiRuntimeLogMessage(apiMessage) {
+    if (/暂不支持获取当前报告的运行日志/.test(apiMessage)) {
+        return 'UE 运行日志方案有过切换：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。旧报告可试 gotonline_overview_log_export。';
+    }
+    if (/运行日志未解析|运行日志解析未完成/.test(apiMessage)) {
+        return 'Unity：该报告无可用运行日志数据（未解析或解析未完成）。旧报告可试 gotonline_overview_log_export。';
+    }
+    return null;
+}
+function hintForFileMetaReason(rawMessage, apiMessage) {
+    const fromApi = hintForOpenApiRuntimeLogMessage(apiMessage);
+    if (fromApi)
+        return fromApi;
+    if (rawMessage.includes(FILE_META_REASONS.LG_META_ABSENT) || rawMessage.includes(FILE_META_REASONS.LG_RUNTIME_PATH_MISSING)) {
+        return ('运行日志 file_meta 不可用（原因码见 rawMessage）。' +
+            'Unity：通常表示未解析/无可用日志数据；UE：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。' +
+            '旧报告可试 gotonline_overview_log_export。');
+    }
+    if (rawMessage.includes(FILE_META_REASONS.AT_META_ABSENT) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_TYPE_INVALID) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_PATH_MISSING)) {
+        return 'AT 资源 meta 不可用：可能未开启资源采集或未解析完成，勿把失败说成「一定没有资源」。';
+    }
+    return null;
+}
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export function isRateLimitMessage(text) {
+    return text.includes(`[${RATE_LIMIT_ERROR_CODE}]`) || text.includes('API_RATE_LIMIT') || text.includes('接口限流');
+}
+/** _partialErrors 中是否有限流项。 */
+export function hasRateLimitInPartialErrors(errors) {
+    return errors.some(isRateLimitMessage);
+}
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export function withRateLimitAnnotation(extra, partialErrors) {
+    if (!partialErrors?.length)
+        return extra;
+    const out = { ...extra, _partialErrors: partialErrors };
+    if (hasRateLimitInPartialErrors(partialErrors)) {
+        out._rateLimitHint = RATE_LIMIT_HINT;
+    }
+    return out;
+}
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export function resolveErrorHint(code, rawMessage, apiMessage) {
+    if (code === 80108) {
+        return (hintForFileMetaReason(rawMessage, apiMessage) ??
+            '文件 meta 不存在（FILE_META_NOT_EXIST）。运行日志/AT 等场景请结合接口 message 与报告引擎解释；勿臆造数据。');
+    }
+    return ERROR_HINTS_BY_CODE[code];
+}

package/dist/indicator-dashboard-keys.d.ts

@@ -0,0 +1,12 @@
+/** indicatorDashboards 合法面板传参名称（与 got-query OverviewIndicatorDashboardCatalogService 同源）。 */
+export declare const INDICATOR_DASHBOARD_KEYS: readonly string[];
+/** 常见误传：统计维度后缀 / 子指标名，不是面板标识符。 */
+export declare const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES: readonly ["fps_mean", "fps_maximum", "frametime_min", "frametime_gt_40_pct", "temperature_mean", "drawcall_maximum", "android_pss_max"];
+export declare function splitIndicatorDashboards(raw: unknown): string[];
+export declare function findUnknownIndicatorDashboards(raw: unknown): string[];
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export declare function partitionIndicatorDashboards(raw: unknown): {
+    accepted: string[];
+    unknown: string[];
+    all: string[];
+};

package/dist/indicator-dashboard-keys.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const keysJson = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'indicator-dashboard-keys.json'), 'utf8'));
+/** indicatorDashboards 合法面板传参名称（与 got-query OverviewIndicatorDashboardCatalogService 同源）。 */
+export const INDICATOR_DASHBOARD_KEYS = keysJson.keys;
+/** 常见误传：统计维度后缀 / 子指标名，不是面板标识符。 */
+export const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES = [
+    'fps_mean',
+    'fps_maximum',
+    'frametime_min',
+    'frametime_gt_40_pct',
+    'temperature_mean',
+    'drawcall_maximum',
+    'android_pss_max',
+];
+export function splitIndicatorDashboards(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function findUnknownIndicatorDashboards(raw) {
+    const parts = splitIndicatorDashboards(raw);
+    if (!parts.length)
+        return [];
+    const valid = new Set(INDICATOR_DASHBOARD_KEYS);
+    return parts.filter((k) => !valid.has(k));
+}
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export function partitionIndicatorDashboards(raw) {
+    const all = splitIndicatorDashboards(raw);
+    const valid = new Set(INDICATOR_DASHBOARD_KEYS);
+    const accepted = [];
+    const unknown = [];
+    const seen = new Set();
+    for (const k of all) {
+        if (!valid.has(k)) {
+            unknown.push(k);
+            continue;
+        }
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        accepted.push(k);
+    }
+    return { accepted, unknown, all };
+}