@uwa4d/openapi-mcp 0.2.0-beta.5 → 0.2.0-beta.8

package/README.md

@@ -78,7 +78,6 @@ npx -y @uwa4d/openapi-mcp check -a <app_id> -s <app_secret>
 | `--app-id` | `-a` | AppId | `UWA_MCP_APP_ID` |
 | `--app-secret` | `-s` | AppSecret | `UWA_MCP_APP_SECRET` |
 | `--base-url` | `-b` | 接口地址，默认 `https://secure-api.uwa4d.com` | `UWA_MCP_API_BASE_URL` |
-| `--sandbox` | | 切到测试环境 `https://sandbox-api.uwa4d.com` | |
 | `--tool` | `-t` | 加载哪些工具，逗号分隔，默认 `preset.default` | `UWA_MCP_TOOL` |
 | `--engine` | `-e` | 只加载适用于 `unity` / `unreal` 的工具，默认 `all` | `UWA_MCP_ENGINE` |
 | `--tool-name-case` | `-c` | 工具命名风格 `snake` / `camel`，默认 `snake` | |
@@ -192,9 +191,6 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 | --- | --- | --- |
 | `@uwa4d/openapi-mcp` | 跟随最新稳定版，自动升级 | 默认，大多数用户 |
 | `@uwa4d/openapi-mcp@0.1.0` | 锁死某个版本 | 生产流水线，要求完全可复现 |
-| `@uwa4d/openapi-mcp@beta` | 跟随测试版 | 配合 UWA 验证新接口 |
-
-测试版只发布在 `beta` 标签下，默认写法不会拉到测试版。
 
 ## 常见问题
 
@@ -202,7 +198,7 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 检查 Node 版本是否 ≥ 18，以及配置文件 JSON 格式是否正确（多一个逗号就会整个失效）。改完配置需要重启客户端。
 
 **提示凭证错误**
-用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。注意测试环境和生产环境的凭证不通用。
+用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。确认 AppId / AppSecret 无误且未过期。
 
 **返回「数据服务错误」或不确定该用 v1 还是 v2**
 

package/dist/annotate-dashboard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 自定义面板 statistic / curve 返回体的 Agent 友好标注与过滤。
+ * 不改上游 Open API，只在 MCP wrapper 层消歧、降噪、提效。
+ */
+/**
+ * 上游嵌套 mean/maximum/min 与扁平别名已统一为同一单位（如 frametime=ms）。
+ * 这里只给仍无单位标注的 scene_* 裸数组补 unit/data，便于模型直接读，不改数值。
+ */
+export declare function annotateSceneUnits(data: unknown): unknown;
+/**
+ * 标明扁平别名与嵌套 scene_* 的重复关系，便于模型只读一份。
+ */
+export declare function annotateDuplicateFlatAliases(data: unknown): unknown;
+/** 从 columns / group 生成入参面板名 → 出参字段映射，便于模型自检。 */
+export declare function annotateParamFieldMap(data: unknown): unknown;
+export interface CurveFilterOptions {
+    valueGt?: number;
+    valueLt?: number;
+    topN?: number;
+    returnFramesOnly?: boolean;
+}
+export declare function extractCurveFilterArgs(args: Record<string, unknown>): {
+    filter: CurveFilterOptions;
+    cleaned: Record<string, unknown>;
+};
+export declare function hasCurveFilter(filter: CurveFilterOptions): boolean;
+/**
+ * 对 y_axis 曲线做客户端过滤，解决「慢帧列表必须全量进上下文」的问题。
+ */
+export declare function filterCurveData(data: unknown, filter: CurveFilterOptions): unknown;
+export declare function isIndicatorStatisticDashboard(opPath: string): boolean;
+export declare function isIndicatorCurveDashboard(opPath: string): boolean;
+/** 统计面板成功返回后的统一标注管线。 */
+export declare function annotateStatisticDashboard(data: unknown, accepted: string[], unknown: string[]): unknown;

package/dist/annotate-dashboard.js

@@ -0,0 +1,275 @@
+/**
+ * 自定义面板 statistic / curve 返回体的 Agent 友好标注与过滤。
+ * 不改上游 Open API，只在 MCP wrapper 层消歧、降噪、提效。
+ */
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isUnitObj(v) {
+    return isObj(v) && ('unit' in v || 'value' in v || 'data' in v);
+}
+/**
+ * 上游嵌套 mean/maximum/min 与扁平别名已统一为同一单位（如 frametime=ms）。
+ * 这里只给仍无单位标注的 scene_* 裸数组补 unit/data，便于模型直接读，不改数值。
+ */
+export function annotateSceneUnits(data) {
+    if (!isObj(data) || !isObj(data['statistic']))
+        return data;
+    const statistic = { ...data['statistic'] };
+    const notes = [];
+    for (const [key, raw] of Object.entries(statistic)) {
+        if (!isObj(raw))
+            continue;
+        // 扁平别名 { unit, data } 跳过；只处理嵌套子指标对象
+        if (Array.isArray(raw['data']) && isObj(raw['unit']) && raw['mean'] === undefined)
+            continue;
+        const metric = { ...raw };
+        let changed = false;
+        const sceneUnit = isUnitObj(metric['mean']) && isObj(metric['mean'].unit) ? metric['mean'].unit : null;
+        for (const [sk, sv] of Object.entries(metric)) {
+            if (!sk.startsWith('scene_') || !Array.isArray(sv))
+                continue;
+            if (isObj(sv[0]) && 'unit' in sv[0])
+                continue;
+            if (sk.endsWith('_frame') || sk.includes('max_frame')) {
+                metric[sk] = { unit: { description: '帧', value: 'frame' }, data: sv };
+            }
+            else if (sk.includes('pct') || sk.includes('rate')) {
+                metric[sk] = { unit: { description: '百分比', value: 'percentage' }, data: sv };
+            }
+            else if (sk.includes('per_min')) {
+                metric[sk] = { unit: { description: '次/分钟', value: 'times/min' }, data: sv };
+            }
+            else if (sceneUnit) {
+                metric[sk] = { unit: sceneUnit, data: sv };
+            }
+            else {
+                continue;
+            }
+            changed = true;
+        }
+        if (changed) {
+            statistic[key] = metric;
+            notes.push(key);
+        }
+    }
+    if (!notes.length)
+        return data;
+    return {
+        ...data,
+        statistic,
+        _sceneUnitNote: `已为子指标 [${notes.join(', ')}] 的 scene_* 裸数组补上 unit（与嵌套 mean.unit 对齐）；数值未改动。`,
+    };
+}
+/**
+ * 标明扁平别名与嵌套 scene_* 的重复关系，便于模型只读一份。
+ */
+export function annotateDuplicateFlatAliases(data) {
+    if (!isObj(data) || !isObj(data['statistic']))
+        return data;
+    const statistic = data['statistic'];
+    const dups = [];
+    for (const [flatKey, flatVal] of Object.entries(statistic)) {
+        if (!isObj(flatVal) || !Array.isArray(flatVal['data']))
+            continue;
+        const m = /^(.+)_(mean|min|maximum|maximum_frame|gt_40_ms_frame_pct|jank_time_pct|jank_frames_per_min|bigjank_frames_per_min)$/.exec(flatKey);
+        if (!m)
+            continue;
+        const indicator = m[1];
+        const kind = m[2];
+        const nested = statistic[indicator];
+        if (!isObj(nested))
+            continue;
+        const sceneKey = kind === 'mean'
+            ? 'scene_mean'
+            : kind === 'min'
+                ? 'scene_min'
+                : kind === 'maximum'
+                    ? 'scene_max'
+                    : kind === 'maximum_frame'
+                        ? 'scene_max_frame'
+                        : `scene_${kind}`;
+        const sceneVal = nested[sceneKey];
+        const sceneArr = Array.isArray(sceneVal)
+            ? sceneVal
+            : isObj(sceneVal) && Array.isArray(sceneVal['data'])
+                ? sceneVal['data']
+                : null;
+        if (!sceneArr)
+            continue;
+        const flatArr = flatVal['data'];
+        if (flatArr.length === sceneArr.length && flatArr.every((v, i) => v === sceneArr[i])) {
+            dups.push(`${flatKey} ≡ ${indicator}.${sceneKey}`);
+        }
+    }
+    if (!dups.length)
+        return data;
+    return {
+        ...data,
+        _duplicateFlatAliases: dups,
+        _duplicateNote: '扁平别名与嵌套 scene_* 数值相同，读嵌套结构即可，扁平 key 为兼容别名。',
+    };
+}
+/** 从 columns / group 生成入参面板名 → 出参字段映射，便于模型自检。 */
+export function annotateParamFieldMap(data) {
+    if (!isObj(data))
+        return data;
+    const columns = data['columns'];
+    const group = data['group'];
+    if (!Array.isArray(columns) && !Array.isArray(group))
+        return data;
+    const map = {};
+    if (Array.isArray(group)) {
+        for (const row of group) {
+            if (!Array.isArray(row) || row.length < 2)
+                continue;
+            const panel = String(row[0]);
+            const inds = Array.isArray(row[1]) ? row[1].map(String) : [];
+            if (!map[panel])
+                map[panel] = { indicators: [], flatKeys: [], nestedHint: [] };
+            map[panel].indicators = [...new Set([...map[panel].indicators, ...inds])];
+            for (const ind of inds) {
+                map[panel].nestedHint.push(`statistic.${ind}`);
+            }
+        }
+    }
+    if (Array.isArray(columns)) {
+        for (const col of columns) {
+            if (!isObj(col))
+                continue;
+            const panel = String(col['firstLevel'] ?? '');
+            const seconds = Array.isArray(col['secondLevel']) ? col['secondLevel'].map(String) : [];
+            if (!panel)
+                continue;
+            if (!map[panel])
+                map[panel] = { indicators: [], flatKeys: [], nestedHint: [] };
+            map[panel].flatKeys = [...new Set([...map[panel].flatKeys, ...seconds])];
+            for (const k of seconds) {
+                map[panel].nestedHint.push(`statistic.${k}`);
+            }
+        }
+    }
+    // frametime 专属：入参与出参字段名不一致
+    for (const [panel, info] of Object.entries(map)) {
+        if (info.indicators.includes('frametime') || panel.includes('frametime') || /jank/i.test(panel)) {
+            info.nestedHint.push('statistic.frametime.gt_40_ms_frame_pct', 'statistic.frametime.jank_time_pct', 'statistic.frametime.jank_frames_per_min', 'statistic.frametime.bigjank_frames_per_min');
+        }
+        info.nestedHint = [...new Set(info.nestedHint)];
+    }
+    if (!Object.keys(map).length)
+        return data;
+    return { ...data, _paramFieldMap: map };
+}
+function parseNum(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v)))
+        return Number(v);
+    return undefined;
+}
+export function extractCurveFilterArgs(args) {
+    const filter = {
+        valueGt: parseNum(args['valueGt']),
+        valueLt: parseNum(args['valueLt']),
+        topN: parseNum(args['topN']),
+        returnFramesOnly: args['returnFramesOnly'] === true,
+    };
+    const cleaned = { ...args };
+    delete cleaned['valueGt'];
+    delete cleaned['valueLt'];
+    delete cleaned['topN'];
+    delete cleaned['returnFramesOnly'];
+    return { filter, cleaned };
+}
+export function hasCurveFilter(filter) {
+    return (filter.valueGt !== undefined ||
+        filter.valueLt !== undefined ||
+        filter.topN !== undefined ||
+        filter.returnFramesOnly === true);
+}
+/**
+ * 对 y_axis 曲线做客户端过滤，解决「慢帧列表必须全量进上下文」的问题。
+ */
+export function filterCurveData(data, filter) {
+    if (!hasCurveFilter(filter) || !isObj(data) || !isObj(data['y_axis']))
+        return data;
+    const yAxis = data['y_axis'];
+    const sharedX = isObj(data['x_axis']) && Array.isArray(data['x_axis']['data']) ? data['x_axis']['data'] : null;
+    const nextY = {};
+    const filterMeta = {};
+    for (const [name, curve] of Object.entries(yAxis)) {
+        if (!isObj(curve) || !Array.isArray(curve['data'])) {
+            nextY[name] = curve;
+            continue;
+        }
+        const values = curve['data'];
+        const ownX = isObj(curve['x_axis']) && Array.isArray(curve['x_axis']['data'])
+            ? curve['x_axis']['data']
+            : sharedX;
+        const pairs = [];
+        for (let i = 0; i < values.length; i++) {
+            const v = values[i];
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                continue;
+            if (filter.valueGt !== undefined && !(v > filter.valueGt))
+                continue;
+            if (filter.valueLt !== undefined && !(v < filter.valueLt))
+                continue;
+            pairs.push({ frame: ownX?.[i] ?? i + 1, value: v, idx: i });
+        }
+        let kept = pairs;
+        if (filter.topN !== undefined && filter.topN > 0 && kept.length > filter.topN) {
+            kept = [...kept].sort((a, b) => b.value - a.value).slice(0, filter.topN);
+            kept.sort((a, b) => Number(a.frame) - Number(b.frame));
+        }
+        filterMeta[name] = {
+            originalPoints: values.length,
+            keptPoints: kept.length,
+            valueGt: filter.valueGt ?? null,
+            valueLt: filter.valueLt ?? null,
+            topN: filter.topN ?? null,
+        };
+        if (filter.returnFramesOnly) {
+            nextY[name] = {
+                unit: { description: '帧', value: 'frame' },
+                frames: kept.map((p) => p.frame),
+                values: kept.map((p) => p.value),
+            };
+        }
+        else {
+            nextY[name] = {
+                ...curve,
+                data: kept.map((p) => p.value),
+                x_axis: {
+                    unit: isObj(curve['x_axis']) ? curve['x_axis']['unit'] : { description: '帧', value: 'frame' },
+                    data: kept.map((p) => p.frame),
+                },
+            };
+        }
+    }
+    return {
+        ...data,
+        y_axis: nextY,
+        _curveFilter: filterMeta,
+        _curveFilterHint: '已按 valueGt/valueLt/topN/returnFramesOnly 在 MCP 侧过滤曲线点；完整曲线去掉这些参数即可。',
+    };
+}
+export function isIndicatorStatisticDashboard(opPath) {
+    return opPath.includes('/indicator/statistic/dashboard') || opPath.includes('/custom/dashboard');
+}
+export function isIndicatorCurveDashboard(opPath) {
+    return opPath.includes('/indicator/curve/dashboard') || opPath.includes('/gpu/curve');
+}
+/** 统计面板成功返回后的统一标注管线。 */
+export function annotateStatisticDashboard(data, accepted, unknown) {
+    let out = annotateSceneUnits(data);
+    out = annotateDuplicateFlatAliases(out);
+    out = annotateParamFieldMap(out);
+    if (!isObj(out))
+        return out;
+    return {
+        ...out,
+        _acceptedDashboards: accepted,
+        ...(unknown.length ? { _unknownDashboards: unknown } : {}),
+    };
+}

package/dist/composite/name-pattern.d.ts

@@ -0,0 +1,8 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export declare function matchesNamePattern(name: string, pattern?: unknown): boolean;
+export declare function filterRowsByNamePattern<T extends {
+    name: string;
+}>(rows: T[], pattern: unknown): {
+    rows: T[];
+    matchedTotal: number;
+};

package/dist/composite/name-pattern.js

@@ -0,0 +1,25 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export function matchesNamePattern(name, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim()))
+        return true;
+    const p = String(pattern).trim();
+    if (p.length >= 2 && p.startsWith('/') && p.lastIndexOf('/') > 0) {
+        const last = p.lastIndexOf('/');
+        const body = p.slice(1, last);
+        const flags = p.slice(last + 1);
+        try {
+            return new RegExp(body, flags).test(name);
+        }
+        catch {
+            return name.toLowerCase().includes(p.toLowerCase());
+        }
+    }
+    return name.toLowerCase().includes(p.toLowerCase());
+}
+export function filterRowsByNamePattern(rows, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim())) {
+        return { rows, matchedTotal: rows.length };
+    }
+    const matched = rows.filter((r) => matchesNamePattern(r.name, pattern));
+    return { rows: matched, matchedTotal: matched.length };
+}

package/dist/composite/report-diagnosis.js

@@ -20,6 +20,25 @@ function summarizeScenes(data) {
     }
     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 = [
@@ -66,7 +85,10 @@ export const reportDiagnosisTool = {
         '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数与场景摘要。',
         '适用引擎：Unity / UE｜复合工具',
         '调用方不必自己判断 2026-07-09 / 2026-03-25 分界或 SDK 版本——内部按 get_report_detail 路由。',
-        'Top 函数来自堆栈树解析合并，不是统计接口里的抽样指标。',
+        'Top 函数：Overview 走 method/idmap/statistic v1.0.2 + stackTestMode；Mono 走堆栈树；逐帧曲线用 method/curve/presign v1.0.2。',
+        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys 核对 indicatorDashboards（勿把 fps_mean 等统计字段当面板名）。',
+        '卡顿根因：stutter_full_tree / stutter_scene_tree（卡顿帧已合并的树）；尖峰再 stack_tree_frame；勿对每个慢帧循环拉帧树。',
+        'scenes 含 list_scenes 起止帧（sceneIdx/sceneName/frameStart/frameEnd）。',
         '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
     ].join('\n'),
     inputSchema: {
@@ -120,12 +142,30 @@ export const reportDiagnosisTool = {
                     apisUsed.push(scene.target.id);
                 }
                 else {
-                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景摘要');
+                    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)}`);
+            }
             // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
             if (view.hasResource === false) {
                 limitations.push('未开启资源采集，逐资源 Top 可能为空');

package/dist/composite/stack-agg.d.ts

@@ -1,5 +1,7 @@
 import type { UwaClient } from '../client.js';
 import type { ReportIdentity } from './route-overview.js';
+import { type OverviewStackTestMode } from './stack-test-mode.js';
+export type { OverviewStackTestMode, OverviewStackTestModeProfile } from './stack-test-mode.js';
 export type StackMetric = 'selfTime' | 'totalTime' | 'callCount' | 'selfMemory';
 export interface StackAggRow {
     methodId: string;
@@ -18,15 +20,25 @@ export interface StackAggRow {
 }
 export interface StackAggResult {
     testMode: string | null;
+    /** 仅 Overview：堆栈采集模式 CPU_ONLY / LUA_MEM_ONLY / CPU_AND_LUA_MEM */
+    stackTestMode?: OverviewStackTestMode | null;
+    availableMetrics?: StackMetric[];
+    availableFields?: string[];
+    metricGuide?: string;
     metric: StackMetric;
     unit: string;
     rows: Array<{
         name: string;
         methodId: string;
+        stackMethodId?: string;
         value: number;
         unit: string;
-        selfTimeMs?: number;
-        totalTimeMs?: number;
+        selfTimeMean?: number | null;
+        totalTimeMean?: number | null;
+        callCountTotal?: number | null;
+        selfMemoryMean?: number | null;
+        selfMemoryTotal?: number | null;
+        selfMemoryUnit?: string | null;
         selfMemoryKb?: number;
         callCount: number;
         callFrameCount: number;
@@ -48,6 +60,7 @@ interface TreeNode {
     totalMemoryKb: number;
     selfMemoryKb: number;
 }
+export declare function aggregateOverviewStackFromStatistic(client: UwaClient, identity: ReportIdentity, topN: number, metricInput?: StackMetric, threadName?: string, namePattern?: string): Promise<StackAggResult>;
 /**
  * Overview：线程堆栈树（主线程）+ 函数 idmap → 按函数名合并节点。
  * 同名（同一 methodId）节点的 selfTime / callCount 相加，再按指标排序取 Top N。
@@ -62,4 +75,3 @@ export declare function aggregateMonoStack(client: UwaClient, identity: ReportId
  * 解析无表头 CSV。列数随 testMode 变化；UE 固定 7 列（与 CPU_ONLY 同形）。
  */
 export declare function parseStackCsv(csvText: string, testMode: string | null): TreeNode[];
-export {};

package/dist/composite/stack-agg.js

@@ -1,4 +1,155 @@
 import { isObj } from './helpers.js';
+import { assertOverviewMetricSupported, inferOverviewStackTestMode, normalizeOverviewStackTestMode, OVERVIEW_STACK_TEST_MODE_PROFILES, resolveOverviewDefaultMetric, } from './stack-test-mode.js';
+import { matchesNamePattern } from './name-pattern.js';
+/**
+ * Overview：函数 idmap 统计（v1.0.2）+ Overview stackTestMode → Top N。
+ * stackTestMode 仅 Overview 有效；决定哪些统计字段/metric 可用。
+ */
+function parseStatNumber(obj) {
+    if (!isObj(obj) || obj['value'] == null)
+        return null;
+    const n = Number(obj['value']);
+    return Number.isFinite(n) ? n : null;
+}
+function parseStatUnit(obj) {
+    if (!isObj(obj))
+        return null;
+    const unit = obj['unit'];
+    if (!isObj(unit) || unit['value'] == null)
+        return null;
+    return String(unit['value']);
+}
+async function fetchOverviewStackTestMode(client, identity) {
+    if (identity.engine === 'unreal') {
+        return { stackTestMode: 'CPU_ONLY', apisUsed: [] };
+    }
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    try {
+        const meta = (await client.call('GET', '/openapi/v1/data/gotonline/overview/stack/overall/tree/presign', 'v1.0.1', keyQuery));
+        return {
+            stackTestMode: normalizeOverviewStackTestMode(meta['testMode']),
+            apisUsed: ['gotonline_overview_stack_overall_tree_presign'],
+        };
+    }
+    catch {
+        return { stackTestMode: null, apisUsed: [] };
+    }
+}
+export async function aggregateOverviewStackFromStatistic(client, identity, topN, metricInput, threadName, namePattern) {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    if (identity.engine === 'unreal') {
+        keyQuery['threadName'] = threadName?.trim() || 'GameThread';
+    }
+    const apisUsed = [];
+    const [{ stackTestMode: presignMode, apisUsed: presignApis }, raw] = await Promise.all([
+        fetchOverviewStackTestMode(client, identity),
+        client.call('GET', '/openapi/v1/data/gotonline/overview/method/idmap/statistic', 'v1.0.2', keyQuery),
+    ]);
+    apisUsed.push(...presignApis, 'gotonline_overview_method_idmap_statistic');
+    const list = Array.isArray(raw) ? raw : [];
+    if (!list.length) {
+        throw new Error('函数 idmap 统计返回空列表（报告可能未开堆栈或 SDK < 2.5.1）');
+    }
+    const rows = [];
+    for (const item of list) {
+        if (!isObj(item))
+            continue;
+        const methodId = item['stackMethodId'] != null ? String(item['stackMethodId']) : '';
+        const name = item['stackMethodName'] != null ? String(item['stackMethodName']) : methodId;
+        if (!methodId)
+            continue;
+        const memMeanObj = item['selfMemoryMean'];
+        const memTotalObj = item['selfMemoryTotal'];
+        const selfTimeMean = parseStatNumber(item['selfTimeMean']);
+        const totalTimeMean = parseStatNumber(item['totalTimeMean']);
+        const callCountTotal = parseStatNumber(item['callCountTotal']);
+        const selfMemoryMean = parseStatNumber(memMeanObj);
+        const selfMemoryTotal = parseStatNumber(memTotalObj);
+        const selfMemoryUnit = parseStatUnit(memMeanObj) ?? parseStatUnit(memTotalObj);
+        if (selfTimeMean == null &&
+            totalTimeMean == null &&
+            callCountTotal == null &&
+            selfMemoryMean == null &&
+            selfMemoryTotal == null) {
+            continue;
+        }
+        rows.push({
+            stackMethodId: methodId,
+            name,
+            selfTimeMean,
+            totalTimeMean,
+            callCountTotal,
+            selfMemoryMean,
+            selfMemoryTotal,
+            selfMemoryUnit,
+        });
+    }
+    if (!rows.length) {
+        throw new Error('函数 idmap 统计无有效数据');
+    }
+    const hasTime = rows.some((r) => r.selfTimeMean != null || r.totalTimeMean != null);
+    const hasMem = rows.some((r) => r.selfMemoryMean != null || r.selfMemoryTotal != null);
+    const stackTestMode = presignMode ?? inferOverviewStackTestMode({ hasTime, hasMem });
+    if (!stackTestMode) {
+        throw new Error('无法判断 Overview stackTestMode');
+    }
+    const profile = OVERVIEW_STACK_TEST_MODE_PROFILES[stackTestMode];
+    const metric = metricInput ?? resolveOverviewDefaultMetric(stackTestMode);
+    assertOverviewMetricSupported(metric, profile);
+    const metricValue = (r) => {
+        if (metric === 'totalTime')
+            return r.totalTimeMean != null ? r.totalTimeMean : -1;
+        if (metric === 'callCount')
+            return r.callCountTotal != null ? r.callCountTotal : -1;
+        if (metric === 'selfMemory') {
+            if (r.selfMemoryMean != null)
+                return r.selfMemoryMean;
+            if (r.selfMemoryTotal != null)
+                return r.selfMemoryTotal;
+            return -1;
+        }
+        return r.selfTimeMean != null ? r.selfTimeMean : -1;
+    };
+    const sorted = rows.sort((a, b) => metricValue(b) - metricValue(a));
+    const pattern = namePattern?.trim();
+    const matched = pattern ? sorted.filter((r) => matchesNamePattern(r.name, pattern)) : sorted;
+    const unit = metric === 'callCount' ? '次' : metric === 'selfMemory' ? rows.find((r) => r.selfMemoryUnit)?.selfMemoryUnit ?? 'KB' : 'ms';
+    return {
+        testMode: stackTestMode,
+        stackTestMode,
+        availableMetrics: [...profile.availableMetrics],
+        availableFields: [...profile.availableFields],
+        metricGuide: profile.description,
+        metric,
+        unit,
+        rows: matched.slice(0, topN).map((r) => ({
+            name: r.name,
+            methodId: r.stackMethodId,
+            stackMethodId: r.stackMethodId,
+            selfTimeMean: r.selfTimeMean != null ? round2(r.selfTimeMean) : null,
+            totalTimeMean: r.totalTimeMean != null ? round2(r.totalTimeMean) : null,
+            callCountTotal: r.callCountTotal != null ? Math.round(r.callCountTotal) : null,
+            selfMemoryMean: r.selfMemoryMean != null ? round2(r.selfMemoryMean) : null,
+            selfMemoryTotal: r.selfMemoryTotal != null ? round2(r.selfMemoryTotal) : null,
+            selfMemoryUnit: r.selfMemoryUnit,
+            value: metric === 'callCount'
+                ? Math.round(metricValue(r) >= 0 ? metricValue(r) : 0)
+                : round2(metricValue(r) >= 0 ? metricValue(r) : 0),
+            unit,
+            callCount: r.callCountTotal != null ? Math.round(r.callCountTotal) : 0,
+            callFrameCount: 0,
+            nodeCount: 1,
+            source: 'overview.method.idmap.statistic',
+        })),
+        totalNodes: rows.length,
+        uniqueFunctions: rows.length,
+        apisUsed,
+    };
+}
 /**
  * Overview：线程堆栈树（主线程）+ 函数 idmap → 按函数名合并节点。
  * 同名（同一 methodId）节点的 selfTime / callCount 相加，再按指标排序取 Top N。
@@ -231,10 +382,11 @@ function finalizeAgg(nodes, idMap, topN, metric, testMode, apisUsed, source) {
         return {
             name: r.name,
             methodId: r.methodId,
+            stackMethodId: r.methodId,
+            selfTimeMean: round2(r.selfTimeUs / 1000),
+            totalTimeMean: round2(r.totalTimeUs / 1000),
             value,
             unit,
-            selfTimeMs: round2(r.selfTimeUs / 1000),
-            totalTimeMs: round2(r.totalTimeUs / 1000),
             selfMemoryKb: round2(r.selfMemoryKb),
             callCount: r.callCount,
             callFrameCount: r.callFrameCount,