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

package/dist/composite/report-diagnosis.js

@@ -0,0 +1,347 @@
+import { z } from './types.js';
+import { errorResult, isObj, jsonToolResult, requireReportKey } from './helpers.js';
+import { fetchOverviewStatistic, fetchReportIdentity, fetchSceneStatistic, } from './route-overview.js';
+import { viewOverview } from './overview-view.js';
+import { runTopFunctions } from './top-functions.js';
+import { runTopResources } from './top-resources.js';
+import { extractPssPeakCard } from '../annotate-dashboard.js';
+function summarizeScenes(data) {
+    if (!data)
+        return { sceneCount: 0 };
+    if (Array.isArray(data))
+        return { sceneCount: data.length, scenes: data.slice(0, 20) };
+    if (typeof data !== 'object' || data === null)
+        return { rawType: typeof data };
+    const obj = data;
+    for (const k of ['scenes', 'list', 'content', 'records']) {
+        if (Array.isArray(obj[k])) {
+            const arr = obj[k];
+            return { sceneCount: arr.length, scenes: arr.slice(0, 20) };
+        }
+    }
+    return { keys: Object.keys(obj).slice(0, 30) };
+}
+/** list_scenes 返回起止帧；归一成 sceneIdx + sceneName + frameStart/End。 */
+function normalizeSceneList(data) {
+    const arr = Array.isArray(data)
+        ? data
+        : data && typeof data === 'object' && Array.isArray(data['scenes'])
+            ? data['scenes']
+            : [];
+    return arr.slice(0, 50).map((item, idx) => {
+        if (!item || typeof item !== 'object')
+            return { sceneIdx: idx, raw: item };
+        const o = item;
+        return {
+            sceneIdx: idx,
+            sceneName: o['sceneName'] ?? o['name'] ?? null,
+            frameStart: o['frameStart'] ?? o['startFrame'] ?? null,
+            frameEnd: o['frameEnd'] ?? o['endFrame'] ?? null,
+        };
+    });
+}
+/** brief 全量可能很长，体检只保留常见关键指标（含 Unity key 与 UE 中文 label）。 */
+function pickImportantBrief(brief) {
+    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 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)
+            continue;
+        out[k] = v;
+        if (++n >= 12)
+            break;
+    }
+    return out;
+}
+function numOf(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (Array.isArray(v) && typeof v[0] === 'number')
+        return v[0];
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/** 从 overview brief/summary 尽量抽出 PSS 峰值答题卡。 */
+function extractPssFromView(brief, summary) {
+    const sources = [brief, summary];
+    for (const src of sources) {
+        const peak = numOf(src['android_memory_pss_maximum']) ??
+            numOf(src['android_memory_pss@max']) ??
+            numOf(src['PSS峰值']) ??
+            numOf(src['设备内存峰值（MB）']);
+        const frame = numOf(src['android_memory_pss_maximum_frame']) ??
+            numOf(src['android_memory_pss@max_frame']) ??
+            null;
+        if (peak == null)
+            continue;
+        // brief 里设备内存峰值多为 MB；android_memory_pss 多为 KB
+        const looksMb = peak < 50_000 && (src['设备内存峰值（MB）'] !== undefined || peak < 2048);
+        const peakKb = looksMb ? Math.round(peak * 1024) : peak;
+        return {
+            pss_peak_kb: peakKb,
+            pss_peak_mb: Math.round((peakKb / 1024) * 100) / 100,
+            pss_peak_frame: frame,
+            pss_unit: 'KB',
+            _pssHint: 'Android PSS 峰值请优先读 pss_peak_kb/mb/frame；合法面板名 android_memory_pss@max（不是 android_pss_max）。',
+        };
+    }
+    return null;
+}
+/** 优先走 indicator statistic 拿完整 PSS 峰值+帧；失败再回退 overview brief。 */
+async function resolvePssPeakCard(client, identity, brief, summary, apisUsed, limitations) {
+    const keyQuery = {
+        indicatorDashboards: 'android_memory_pss@max',
+    };
+    if (identity.dataKey)
+        keyQuery['dataKey'] = identity.dataKey;
+    else if (identity.recordId != null)
+        keyQuery['recordId'] = identity.recordId;
+    else
+        return extractPssFromView(brief, summary);
+    try {
+        const raw = await client.call('GET', '/openapi/v1/data/gotonline/overview/indicator/statistic/dashboard', 'v1.0.1', keyQuery);
+        apisUsed.push('gotonline_overview_indicator_statistic_dashboard');
+        const card = extractPssPeakCard(raw);
+        if (card)
+            return card;
+        limitations.push('indicator PSS 面板无峰值字段，已回退 overview 摘要');
+    }
+    catch (e) {
+        limitations.push(`PSS 面板查询失败，已回退 overview 摘要：${e instanceof Error ? e.message : String(e)}`);
+    }
+    return extractPssFromView(brief, summary);
+}
+function isWaitForVsyncName(name) {
+    return /wait\s*for\s*vsync|WaitForVsync|Gfx\.WaitForPresent/i.test(String(name ?? ''));
+}
+function buildBottleneckCandidates(topFunctions, gpuBoundEmpty) {
+    const items = topFunctions && Array.isArray(topFunctions['items']) ? topFunctions['items'] : [];
+    const out = [];
+    for (const raw of items.slice(0, 8)) {
+        if (!isObj(raw))
+            continue;
+        const name = raw['name'] ?? raw['methodName'] ?? raw['stackMethodName'];
+        const wait = isWaitForVsyncName(name);
+        out.push({
+            name,
+            selfTimeMean: raw['selfTimeMean'] ?? raw['value'] ?? null,
+            source: 'top_functions',
+            role: wait ? 'frame_sync_wait' : 'cpu_candidate',
+            note: wait
+                ? 'WaitForVsync/Present 等待是帧同步表现，不能直接当卡顿根因或 GPU Bound 证据'
+                : '需结合 stutter 合并树确认是否为卡顿根因',
+        });
+    }
+    if (gpuBoundEmpty === true) {
+        out.push({
+            name: 'GPU Bound',
+            source: 'gotonline_gpu_bound',
+            role: 'not_detected',
+            note: 'targetFps=30 下未检出 GPU Bound 区间',
+        });
+    }
+    return out;
+}
+export const reportDiagnosisTool = {
+    id: 'report_diagnosis',
+    title: '报告体检',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['report_diagnosis', 'composite', 'preset.default', 'overview'],
+    description: [
+        '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数、场景摘要与 GPU Bound@30。',
+        '适用引擎：Unity / UE｜复合工具',
+        '调用方不必自己判断 2026-07-09 / 2026-03-25 分界或 SDK 版本——内部按 get_report_detail 路由。',
+        '返回答题卡：forbidden_claims、bottleneck_candidates（与 topFunctions 分栏）、gpuBound、pss_peak_*、comparability_note。',
+        '卡顿根因：优先 stutter_full_tree / stutter_scene_tree；禁止把 WaitForVsync 写成根因或 GPU 主瓶颈。',
+        'gpuBound 为空时只能说「未检出 Bound」，禁止断言 GPU 是主要瓶颈。',
+        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys（勿把 fps_mean 等统计字段当面板名）。',
+        'scenes 含 list_scenes 起止帧（sceneIdx/sceneName/frameStart/frameEnd）。',
+        '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
+    ].join('\n'),
+    inputSchema: {
+        dataKey: z.string().optional().describe('报告 dataKey，与 recordId 二选一'),
+        recordId: z.union([z.string(), z.number()]).optional().describe('报告 recordId，与 dataKey 二选一'),
+    },
+    async handler(args, ctx) {
+        try {
+            const key = requireReportKey(args);
+            const apisUsed = [];
+            const limitations = [];
+            const identity = await fetchReportIdentity(ctx.client, key);
+            apisUsed.push('get_report_detail');
+            const { target, data } = await fetchOverviewStatistic(ctx.client, identity);
+            apisUsed.push(target.id);
+            const view = viewOverview(data);
+            let topResources = null;
+            try {
+                topResources = await runTopResources(ctx.client, { ...key, topN: 10 });
+                const used = topResources['_apisUsed'];
+                if (Array.isArray(used))
+                    for (const u of used)
+                        if (!apisUsed.includes(String(u)))
+                            apisUsed.push(String(u));
+            }
+            catch (e) {
+                limitations.push(`top_resources 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let topFunctions = null;
+            try {
+                const subtype = identity.serviceSubtype === 'mono' ? 'mono' : 'overview';
+                topFunctions = await runTopFunctions(ctx.client, { ...key, topN: 10, serviceSubtype: subtype });
+                const used = topFunctions['_apisUsed'];
+                if (Array.isArray(used))
+                    for (const u of used)
+                        if (!apisUsed.includes(String(u)))
+                            apisUsed.push(String(u));
+                if (Array.isArray(topFunctions['_limitations'])) {
+                    for (const lim of topFunctions['_limitations'])
+                        limitations.push(String(lim));
+                }
+            }
+            catch (e) {
+                limitations.push(`top_functions 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let scenes = null;
+            try {
+                const scene = await fetchSceneStatistic(ctx.client, identity);
+                if (scene) {
+                    scenes = summarizeScenes(scene.data);
+                    apisUsed.push(scene.target.id);
+                }
+                else {
+                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景统计摘要');
+                }
+            }
+            catch (e) {
+                limitations.push(`场景统计失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            // list_scenes 补起止帧（场景统计摘要经常只有名称/索引）
+            try {
+                const keyQuery = {};
+                if (identity.dataKey)
+                    keyQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    keyQuery['recordId'] = identity.recordId;
+                const sceneList = await ctx.client.call('GET', '/openapi/v1/data/gotonline/scene/info', 'v1.0.1', keyQuery);
+                const list = normalizeSceneList(sceneList);
+                if (list.length) {
+                    scenes = { ...(scenes ?? {}), sceneCount: list.length, scenes: list };
+                    if (!apisUsed.includes('list_scenes'))
+                        apisUsed.push('list_scenes');
+                }
+            }
+            catch (e) {
+                limitations.push(`场景列表(list_scenes)失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let gpuBound = null;
+            let gpuBoundEmpty = null;
+            try {
+                const boundQuery = { targetFps: 30 };
+                if (identity.dataKey)
+                    boundQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    boundQuery['recordId'] = identity.recordId;
+                gpuBound = await ctx.client.call('GET', '/openapi/v1/data/gotonline/gpu/bound', 'v1.0.1', boundQuery);
+                apisUsed.push('gotonline_gpu_bound');
+                const intervals = Array.isArray(gpuBound)
+                    ? gpuBound
+                    : isObj(gpuBound) && Array.isArray(gpuBound['data'])
+                        ? gpuBound['data']
+                        : null;
+                gpuBoundEmpty = Array.isArray(intervals) ? intervals.length === 0 : null;
+            }
+            catch (e) {
+                limitations.push(`gpu_bound 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
+            if (view.hasResource === false) {
+                limitations.push('未开启资源采集，逐资源 Top 可能为空');
+            }
+            const forbidden_claims = [];
+            if (gpuBoundEmpty === true) {
+                forbidden_claims.push('GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈');
+            }
+            forbidden_claims.push('WaitForVsync是卡顿根因');
+            const pssCard = await resolvePssPeakCard(ctx.client, identity, view.brief, view.summary, apisUsed, limitations);
+            const sceneCount = isObj(scenes) ? Number(scenes['sceneCount'] ?? 0) : 0;
+            const comparability_note = [
+                '与其它报告对比时：请核对场景名/数量、测试时长、目标帧率、SDK/引擎版本是否一致。',
+                sceneCount > 0 ? `本报告场景数=${sceneCount}。` : '',
+                '仅比较 FPS 均值不能视为严格同场景对比。',
+            ]
+                .filter(Boolean)
+                .join(' ');
+            const result = {
+                report: {
+                    dataKey: identity.dataKey,
+                    recordId: identity.recordId,
+                    recordName: identity.recordName,
+                    engine: identity.engine,
+                    createDate: identity.createDate,
+                    sdkVersion: identity.sdkVersion,
+                    serviceSubtype: identity.serviceSubtype,
+                },
+                routedOverview: target.id,
+                overviewShape: view.shape,
+                hasResource: view.hasResource,
+                summary: view.summary,
+                brief: pickImportantBrief(view.brief),
+                ...(pssCard ?? {}),
+                gpuBound: Array.isArray(gpuBound) ? gpuBound : isObj(gpuBound) ? gpuBound['data'] ?? gpuBound : gpuBound,
+                gpuBoundEmpty,
+                forbidden_claims,
+                bottleneck_candidates: buildBottleneckCandidates(topFunctions, gpuBoundEmpty),
+                topResources: topResources
+                    ? {
+                        items: topResources['items'],
+                        byType: topResources['byType'],
+                        note: topResources['_note'],
+                    }
+                    : null,
+                topFunctions: topFunctions
+                    ? {
+                        items: topFunctions['items'],
+                        metric: topFunctions['metric'],
+                        uniqueFunctions: topFunctions['uniqueFunctions'],
+                        note: topFunctions['_note'],
+                        _columnNote: 'topFunctions 是耗时排行，不等于卡顿根因；根因看 stutter 合并树与 bottleneck_candidates。',
+                    }
+                    : null,
+                scenes,
+                comparability_note,
+                _apisUsed: apisUsed,
+                _limitations: limitations,
+                _note: '结构化体检摘要（含答题卡）。GPU Bound 空时禁止 GPU 主瓶颈结论；卡顿根因优先 stutter 树。细节请按 _apisUsed 调用对应原子工具。',
+            };
+            return jsonToolResult(result, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

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

@@ -0,0 +1,72 @@
+import type { UwaClient } from '../client.js';
+import type { Engine } from '../spec.js';
+/** Unity Overview / 场景统计 2.0 分界 */
+export declare const UNITY_V2_DAY = "2026-07-09";
+/** UE Overview 2.0 分界（v1 含当日及以前，v2 为严格之后） */
+export declare const UE_V2_DAY = "2026-03-25";
+/** AT 资源总览列表可用分界 */
+export declare const AT_RESOURCE_DAY = "2026-06-25";
+export declare const UNITY_V2_SDK = "2.5.1";
+export interface ReportIdentity {
+    dataKey?: string;
+    recordId?: string;
+    engine: Engine;
+    createDate: string | null;
+    sdkVersion: string | null;
+    serviceSubtype: string | null;
+    recordName: string | null;
+    raw: Record<string, unknown>;
+}
+export type OverviewTarget = {
+    id: 'get_overview_statistic_v1';
+    method: 'GET';
+    path: '/openapi/v1/data/gotonline/overview/report';
+    apiVersion: 'v1.0.1';
+} | {
+    id: 'get_overview_statistic_v2';
+    method: 'POST';
+    path: '/openapi/v1/data/gotonline/overview/statistic/batch';
+    apiVersion: 'v1.0.1';
+} | {
+    id: 'get_ue_overview_statistic_v2';
+    method: 'GET';
+    path: '/openapi/v1/data/gotonline/ue/overview/report';
+    apiVersion: 'v1.0.1';
+};
+export type SceneTarget = {
+    id: 'get_scene_statistic_v1';
+    method: 'GET';
+    path: '/openapi/v1/data/gotonline/overview/scene';
+    apiVersion: 'v1.0.1';
+} | {
+    id: 'get_scene_statistic_v2';
+    method: 'POST';
+    path: '/openapi/v1/data/gotonline/overview/report/scene/statistic/batch';
+    apiVersion: 'v1.0.1';
+};
+/**
+ * 拉取单份报告详情并规范化身份字段。
+ * get_report_detail 的 dataKeys 为逗号分隔；返回可能是数组或带 records 的对象。
+ */
+export declare function fetchReportIdentity(client: UwaClient, key: {
+    dataKey?: string;
+    recordId?: string;
+}): Promise<ReportIdentity>;
+/** 按引擎 + 日期 + SDK 选出 Overview 统计接口。 */
+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<{
+    target: OverviewTarget;
+    data: unknown;
+}>;
+export declare function fetchSceneStatistic(client: UwaClient, identity: ReportIdentity): Promise<{
+    target: SceneTarget;
+    data: unknown;
+} | null>;
+/** 从 Overview 统计结果里取出「第一份报告」的业务对象（v1/v2 结构略有差异）。 */
+export declare function unwrapOverviewReport(data: unknown): Record<string, unknown> | null;
+export declare function overviewHasResource(report: Record<string, unknown> | null): boolean;

package/dist/composite/route-overview.js

@@ -0,0 +1,233 @@
+import { dayGte, dayLt, dayLte, dayOf, isObj, sdkAtLeast } from './helpers.js';
+/** Unity Overview / 场景统计 2.0 分界 */
+export const UNITY_V2_DAY = '2026-07-09';
+/** UE Overview 2.0 分界（v1 含当日及以前，v2 为严格之后） */
+export const UE_V2_DAY = '2026-03-25';
+/** AT 资源总览列表可用分界 */
+export const AT_RESOURCE_DAY = '2026-06-25';
+export const UNITY_V2_SDK = '2.5.1';
+function normalizeEngine(v) {
+    const s = String(v ?? '').toLowerCase();
+    if (s === 'unity' || s === '1')
+        return 'unity';
+    if (s === 'unreal' || s === 'ue' || s === '2' || s === '3')
+        return 'unreal';
+    return null;
+}
+/**
+ * 拉取单份报告详情并规范化身份字段。
+ * get_report_detail 的 dataKeys 为逗号分隔；返回可能是数组或带 records 的对象。
+ */
+export async function fetchReportIdentity(client, key) {
+    if (!key.dataKey && !key.recordId)
+        throw new Error('必须提供 dataKey 或 recordId');
+    // 详情接口以 dataKeys 为主；只有 recordId 时先用 recordId 拼进查询（部分环境也认）
+    const query = {};
+    if (key.dataKey)
+        query['dataKeys'] = key.dataKey;
+    else
+        query['dataKeys'] = key.recordId;
+    const data = await client.call('GET', '/openapi/v1/data/gotonline/records/detail', 'v1.0.1', query);
+    const record = pickFirstRecord(data);
+    if (!record)
+        throw new Error('get_report_detail 未返回报告详情，请确认 dataKey/recordId 是否正确');
+    const engine = normalizeEngine(record['engine']) ??
+        normalizeEngine(isObj(data) ? data['engine'] : null) ??
+        inferEngineFromLink(String(record['link'] ?? ''));
+    if (!engine)
+        throw new Error('无法从报告详情判断引擎（unity / unreal），请检查返回字段');
+    return {
+        dataKey: typeof record['dataKey'] === 'string' ? record['dataKey'] : key.dataKey,
+        recordId: record['recordId'] !== undefined && record['recordId'] !== null
+            ? String(record['recordId'])
+            : key.recordId,
+        engine,
+        createDate: dayOf(String(record['createDate'] ?? record['date'] ?? '')),
+        sdkVersion: record['sdkVersion'] != null ? String(record['sdkVersion']) : null,
+        serviceSubtype: record['serviceSubtype'] != null ? String(record['serviceSubtype']) : null,
+        recordName: record['recordName'] != null ? String(record['recordName']) : null,
+        raw: record,
+    };
+}
+function pickFirstRecord(data) {
+    if (Array.isArray(data) && data.length && isObj(data[0]))
+        return data[0];
+    if (!isObj(data))
+        return null;
+    for (const k of ['records', 'list', 'content', 'data']) {
+        const v = data[k];
+        if (Array.isArray(v) && v.length && isObj(v[0]))
+            return v[0];
+    }
+    // 单条对象直接返回
+    if ('dataKey' in data || 'recordId' in data || 'serviceSubtype' in data)
+        return data;
+    return null;
+}
+function inferEngineFromLink(link) {
+    const m = /[?&]engine=(\d+)/.exec(link);
+    if (!m)
+        return null;
+    return normalizeEngine(m[1]);
+}
+/** 按引擎 + 日期 + SDK 选出 Overview 统计接口。 */
+export function resolveOverviewTarget(identity) {
+    const day = identity.createDate;
+    if (identity.engine === 'unreal') {
+        if (day && dayLte(day, UE_V2_DAY)) {
+            return {
+                id: 'get_overview_statistic_v1',
+                method: 'GET',
+                path: '/openapi/v1/data/gotonline/overview/report',
+                apiVersion: 'v1.0.1',
+            };
+        }
+        return {
+            id: 'get_ue_overview_statistic_v2',
+            method: 'GET',
+            path: '/openapi/v1/data/gotonline/ue/overview/report',
+            apiVersion: 'v1.0.1',
+        };
+    }
+    // Unity
+    const canV2 = day != null && dayGte(day, UNITY_V2_DAY) && sdkAtLeast(identity.sdkVersion, UNITY_V2_SDK);
+    if (canV2) {
+        return {
+            id: 'get_overview_statistic_v2',
+            method: 'POST',
+            path: '/openapi/v1/data/gotonline/overview/statistic/batch',
+            apiVersion: 'v1.0.1',
+        };
+    }
+    return {
+        id: 'get_overview_statistic_v1',
+        method: 'GET',
+        path: '/openapi/v1/data/gotonline/overview/report',
+        apiVersion: 'v1.0.1',
+    };
+}
+/** Unity 场景统计路由；UE 无独立 scene v1/v2 对，返回 null。 */
+export function resolveSceneTarget(identity) {
+    if (identity.engine !== 'unity')
+        return null;
+    const day = identity.createDate;
+    const canV2 = day != null && dayGte(day, UNITY_V2_DAY) && sdkAtLeast(identity.sdkVersion, UNITY_V2_SDK);
+    if (canV2) {
+        return {
+            id: 'get_scene_statistic_v2',
+            method: 'POST',
+            path: '/openapi/v1/data/gotonline/overview/report/scene/statistic/batch',
+            apiVersion: 'v1.0.1',
+        };
+    }
+    if (day != null && dayLt(day, UNITY_V2_DAY)) {
+        return {
+            id: 'get_scene_statistic_v1',
+            method: 'GET',
+            path: '/openapi/v1/data/gotonline/overview/scene',
+            apiVersion: 'v1.0.1',
+        };
+    }
+    // 日期未知时偏保守走 v1
+    return {
+        id: 'get_scene_statistic_v1',
+        method: 'GET',
+        path: '/openapi/v1/data/gotonline/overview/scene',
+        apiVersion: 'v1.0.1',
+    };
+}
+/** Unity / UE 共用 AT 资源总览列表；解析日 ≥ 2026-06-25 时优先走这条。 */
+export function preferAtResourceTable(identity) {
+    return identity.createDate != null && dayGte(identity.createDate, AT_RESOURCE_DAY);
+}
+/** 调用已路由的 Overview 统计，返回原始 data + 路由元信息。 */
+export async function fetchOverviewStatistic(client, identity) {
+    const target = resolveOverviewTarget(identity);
+    const key = identity.dataKey ?? identity.recordId;
+    if (!key)
+        throw new Error('报告缺少 dataKey/recordId，无法拉统计');
+    let data;
+    if (target.method === 'POST') {
+        data = await client.call(target.method, target.path, target.apiVersion, {}, { dataKeys: [key] });
+    }
+    else if (identity.dataKey) {
+        data = await client.call(target.method, target.path, target.apiVersion, { dataKeys: identity.dataKey });
+    }
+    else {
+        data = await client.call(target.method, target.path, target.apiVersion, {
+            recordIds: identity.recordId,
+        });
+    }
+    return { target, data };
+}
+export async function fetchSceneStatistic(client, identity) {
+    const target = resolveSceneTarget(identity);
+    if (!target)
+        return null;
+    const key = identity.dataKey ?? identity.recordId;
+    if (!key)
+        return null;
+    let data;
+    if (target.method === 'POST') {
+        data = await client.call(target.method, target.path, target.apiVersion, {}, { dataKey: key });
+    }
+    else if (identity.dataKey) {
+        data = await client.call(target.method, target.path, target.apiVersion, { dataKey: identity.dataKey });
+    }
+    else {
+        data = await client.call(target.method, target.path, target.apiVersion, {
+            recordId: identity.recordId,
+        });
+    }
+    return { target, data };
+}
+/** 从 Overview 统计结果里取出「第一份报告」的业务对象（v1/v2 结构略有差异）。 */
+export function unwrapOverviewReport(data) {
+    if (!data)
+        return null;
+    if (Array.isArray(data) && data.length && isObj(data[0]))
+        return data[0];
+    if (!isObj(data))
+        return null;
+    for (const k of ['reports', 'list', 'content', 'data', 'records']) {
+        const v = data[k];
+        if (Array.isArray(v) && v.length && isObj(v[0]))
+            return v[0];
+    }
+    // v2 batch 有时直接是 { [dataKey]: {...} }
+    const values = Object.values(data);
+    if (values.length === 1 && isObj(values[0]))
+        return values[0];
+    if ('brief' in data || 'func' in data || 'summary' in data || 'asset_stats' in data)
+        return data;
+    return data;
+}
+export function overviewHasResource(report) {
+    if (!report)
+        return false;
+    const brief = report['brief'];
+    if (isObj(brief) && brief['OverviewHasResource'] != null) {
+        const v = brief['OverviewHasResource'];
+        const n = Array.isArray(v) ? Number(v[0]) : Number(v);
+        return Number.isFinite(n) && n !== 0;
+    }
+    // summary 里可能是 label/value 数组
+    const summary = report['summary'];
+    if (Array.isArray(summary)) {
+        for (const row of summary) {
+            if (!isObj(row))
+                continue;
+            const label = String(row['label'] ?? row['key'] ?? '');
+            if (/OverviewHasResource/i.test(label) || label === 'Resource') {
+                const val = row['value'] ?? row['data'];
+                const first = Array.isArray(val) ? val[0] : val;
+                const n = Number(first);
+                if (Number.isFinite(n))
+                    return n !== 0;
+                if (String(first) === '1' || String(first) === '2')
+                    return true;
+            }
+        }
+    }
+    return false;
+}