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

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

@@ -66,7 +66,8 @@ 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 等统计字段当面板名）。',
         '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
     ].join('\n'),
     inputSchema: {

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,

package/dist/composite/stack-test-mode.d.ts

@@ -0,0 +1,33 @@
+import type { StackMetric } from './stack-agg.js';
+/**
+ * Overview 堆栈采集模式（来自 overview/stack/overall/tree/presign 的 testMode）。
+ * 仅适用于 Overview 报告；Mono 报告走独立堆栈，不使用本枚举。
+ */
+export type OverviewStackTestMode = 'CPU_ONLY' | 'LUA_MEM_ONLY' | 'CPU_AND_LUA_MEM';
+/** @deprecated 使用 OverviewStackTestMode */
+export type StackTestMode = OverviewStackTestMode;
+export interface OverviewStackTestModeProfile {
+    stackTestMode: OverviewStackTestMode;
+    availableMetrics: StackMetric[];
+    availableFields: readonly string[];
+    description: string;
+}
+/** @deprecated 使用 OverviewStackTestModeProfile */
+export type StackTestModeProfile = OverviewStackTestModeProfile;
+export declare const OVERVIEW_STACK_TEST_MODE_PROFILES: Record<OverviewStackTestMode, OverviewStackTestModeProfile>;
+export declare const STACK_TEST_MODE_PROFILES: Record<OverviewStackTestMode, OverviewStackTestModeProfile>;
+export declare function normalizeOverviewStackTestMode(raw: unknown): OverviewStackTestMode | null;
+/** @deprecated 使用 normalizeOverviewStackTestMode */
+export declare const normalizeStackTestMode: typeof normalizeOverviewStackTestMode;
+export declare function inferOverviewStackTestMode(flags: {
+    hasTime: boolean;
+    hasMem: boolean;
+}): OverviewStackTestMode | null;
+/** @deprecated 使用 inferOverviewStackTestMode */
+export declare const inferStackTestMode: typeof inferOverviewStackTestMode;
+export declare function resolveOverviewDefaultMetric(stackTestMode: OverviewStackTestMode): StackMetric;
+/** @deprecated 使用 resolveOverviewDefaultMetric */
+export declare const resolveDefaultMetric: typeof resolveOverviewDefaultMetric;
+export declare function assertOverviewMetricSupported(metric: StackMetric, profile: OverviewStackTestModeProfile): void;
+/** @deprecated 使用 assertOverviewMetricSupported */
+export declare const assertMetricSupported: typeof assertOverviewMetricSupported;

package/dist/composite/stack-test-mode.js

@@ -0,0 +1,60 @@
+export const OVERVIEW_STACK_TEST_MODE_PROFILES = {
+    CPU_ONLY: {
+        stackTestMode: 'CPU_ONLY',
+        availableMetrics: ['selfTime', 'totalTime', 'callCount'],
+        availableFields: ['selfTimeMean', 'totalTimeMean', 'callCountTotal'],
+        description: 'CPU_ONLY：仅有耗时（selfTimeMean/totalTimeMean，ms）与调用次数（callCountTotal）；内存字段恒为 null。',
+    },
+    LUA_MEM_ONLY: {
+        stackTestMode: 'LUA_MEM_ONLY',
+        availableMetrics: ['callCount', 'selfMemory'],
+        availableFields: ['callCountTotal', 'selfMemoryMean', 'selfMemoryTotal'],
+        description: 'LUA_MEM_ONLY：仅有调用次数（callCountTotal）与内存（selfMemoryMean/selfMemoryTotal）；耗时字段恒为 null。',
+    },
+    CPU_AND_LUA_MEM: {
+        stackTestMode: 'CPU_AND_LUA_MEM',
+        availableMetrics: ['selfTime', 'totalTime', 'callCount', 'selfMemory'],
+        availableFields: [
+            'selfTimeMean',
+            'totalTimeMean',
+            'callCountTotal',
+            'selfMemoryMean',
+            'selfMemoryTotal',
+        ],
+        description: 'CPU_AND_LUA_MEM：耗时、调用次数、内存均可用。',
+    },
+};
+export const STACK_TEST_MODE_PROFILES = OVERVIEW_STACK_TEST_MODE_PROFILES;
+export function normalizeOverviewStackTestMode(raw) {
+    const tm = String(raw ?? '').toUpperCase();
+    if (tm === 'CPU_ONLY' || tm === 'LUA_MEM_ONLY' || tm === 'CPU_AND_LUA_MEM') {
+        return tm;
+    }
+    return null;
+}
+/** @deprecated 使用 normalizeOverviewStackTestMode */
+export const normalizeStackTestMode = normalizeOverviewStackTestMode;
+export function inferOverviewStackTestMode(flags) {
+    if (flags.hasTime && flags.hasMem)
+        return 'CPU_AND_LUA_MEM';
+    if (flags.hasMem && !flags.hasTime)
+        return 'LUA_MEM_ONLY';
+    if (flags.hasTime)
+        return 'CPU_ONLY';
+    return null;
+}
+/** @deprecated 使用 inferOverviewStackTestMode */
+export const inferStackTestMode = inferOverviewStackTestMode;
+export function resolveOverviewDefaultMetric(stackTestMode) {
+    return stackTestMode === 'LUA_MEM_ONLY' ? 'selfMemory' : 'selfTime';
+}
+/** @deprecated 使用 resolveOverviewDefaultMetric */
+export const resolveDefaultMetric = resolveOverviewDefaultMetric;
+export function assertOverviewMetricSupported(metric, profile) {
+    if (!profile.availableMetrics.includes(metric)) {
+        throw new Error(`当前 Overview stackTestMode=${profile.stackTestMode} 不支持 metric=${metric}。` +
+            `可用：${profile.availableMetrics.join('、')}。${profile.description}`);
+    }
+}
+/** @deprecated 使用 assertOverviewMetricSupported */
+export const assertMetricSupported = assertOverviewMetricSupported;

package/dist/composite/top-functions.d.ts

@@ -7,8 +7,13 @@ export interface FunctionRow {
     source: string;
     label?: string;
     methodId?: string;
-    selfTimeMs?: number;
-    totalTimeMs?: number;
+    stackMethodId?: string;
+    selfTimeMean?: number | null;
+    totalTimeMean?: number | null;
+    callCountTotal?: number | null;
+    selfMemoryMean?: number | null;
+    selfMemoryTotal?: number | null;
+    selfMemoryUnit?: string | null;
     callCount?: number;
     nodeCount?: number;
 }

package/dist/composite/top-functions.js

@@ -1,12 +1,19 @@
 import { z } from './types.js';
 import { errorResult, jsonToolResult, requireReportKey, topNOf } from './helpers.js';
 import { fetchReportIdentity } from './route-overview.js';
-import { aggregateMonoStack, aggregateOverviewStack } from './stack-agg.js';
-function resolveMetric(raw, mode) {
+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 mode === 'mono' ? 'selfMemory' : 'selfTime';
+    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);
@@ -17,33 +24,42 @@ export async function runTopFunctions(client, args) {
     const identity = await fetchReportIdentity(client, key);
     const apisUsed = ['get_report_detail'];
     const mode = subtype ?? identity.serviceSubtype ?? 'overview';
-    const metric = resolveMetric(args['metric'], mode);
     if (mode === 'mono') {
+        const metric = resolveMonoMetric(args['metric']);
         if (identity.engine !== 'unity') {
             return {
                 engine: identity.engine,
                 dataKey: identity.dataKey,
+                serviceSubtype: 'mono',
                 items: [],
                 _apisUsed: apisUsed,
-                _note: 'Mono 模式仅支持 Unity 报告。',
+                _note: 'Mono 模式仅支持 Unity 报告（与 Overview stackTestMode 无关）。',
                 _limitations: ['engine!=unity'],
             };
         }
         try {
-            const agg = await aggregateMonoStack(client, identity, topN, metric);
+            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,
-                testMode: agg.testMode,
-                items: agg.rows,
+                namePattern: namePattern ?? null,
+                matchedFunctions: namePattern ? filtered.matchedTotal : agg.uniqueFunctions,
+                items,
                 totalNodes: agg.totalNodes,
                 uniqueFunctions: agg.uniqueFunctions,
                 _apisUsed: [...apisUsed, ...agg.apisUsed],
-                _note: `已下载 Mono 正向堆栈树并按函数名合并同名节点（共 ${agg.totalNodes} 个节点 → ${agg.uniqueFunctions} 个函数），` +
-                    `按 ${agg.metric} 降序取 Top ${agg.rows.length}。`,
+                _note: `Mono 模式：已下载正向堆栈树合并取 Top ${items.length}（共 ${agg.totalNodes} 节点）。` +
+                    `Mono 不使用 Overview stackTestMode；默认按 selfMemory 排序。` +
+                    (namePattern ? ` namePattern「${String(namePattern)}」命中 ${filtered.matchedTotal} 个。` : ''),
             };
         }
         catch (e) {
@@ -58,25 +74,44 @@ export async function runTopFunctions(client, args) {
             };
         }
     }
-    // Overview：必须以堆栈树 + idmap 为准；统计接口里的「卡顿重点函数 / func / 自定义函数组」都不完整。
+    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 aggregateOverviewStack(client, identity, topN, metric);
+        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: identity.serviceSubtype,
+            serviceSubtype: 'overview',
+            stackTestMode: agg.stackTestMode,
+            availableMetrics: agg.availableMetrics,
+            availableFields: agg.availableFields,
             topN,
             metric: agg.metric,
-            testMode: agg.testMode,
+            namePattern: namePattern ?? null,
             items: agg.rows,
             totalNodes: agg.totalNodes,
             uniqueFunctions: agg.uniqueFunctions,
             _apisUsed: [...apisUsed, ...agg.apisUsed],
-            _note: `已下载主线程堆栈树并按函数名合并同名节点（共 ${agg.totalNodes} 个节点 → ${agg.uniqueFunctions} 个函数），` +
-                `按 ${agg.metric}（${agg.unit}）降序取 Top ${agg.rows.length}。` +
-                `默认排序字段为 selfTime（自身耗时），不是统计接口里的抽样指标。`,
+            _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) {
@@ -85,12 +120,12 @@ export async function runTopFunctions(client, args) {
             dataKey: identity.dataKey,
             createDate: identity.createDate,
             sdkVersion: identity.sdkVersion,
-            serviceSubtype: identity.serviceSubtype,
+            serviceSubtype: 'overview',
             items: [],
             _apisUsed: apisUsed,
-            _note: `堆栈树聚合失败：${e instanceof Error ? e.message : String(e)}。` +
-                `Overview 函数 Top 依赖 stack/overall/tree + stack/id/map（通常需 SDK ≥ 2.5.1 且开启 CPU 堆栈）。`,
-            _limitations: ['overview_stack_unavailable'],
+            _note: `Overview 函数 Top 失败：${e instanceof Error ? e.message : String(e)}。` +
+                `通常需 SDK ≥ 2.5.1 且报告开启堆栈。`,
+            _limitations: ['overview_idmap_statistic_unavailable'],
         };
     }
 }
@@ -100,26 +135,36 @@ export const topFunctionsTool = {
     engines: ['unity', 'unreal'],
     filterKeys: ['top_functions', 'composite', 'preset.default', 'overview', 'mono'],
     description: [
-        '从堆栈树聚合指定报告的函数 Top N（按自身耗时合并同名节点）。',
+        '从函数统计聚合指定报告的函数 Top N。',
         '适用引擎：Unity / UE｜复合工具',
-        'Overview：下载主线程堆栈树（stack/overall/tree/presign）+ 函数 idmap（stack/id/map），',
-        '将 methodId 还原为函数名，并把树上同一函数的多个节点合并（selfTime/callCount 相加），再取 Top N。',
-        '不要用统计接口里的「卡顿重点函数」或自定义函数组——那不是全量函数耗时。',
-        'Mono（仅 Unity）：走 Mono 正向堆栈树 + Mono 函数 idmap，默认按自身内存排序。',
-        '需要原始树时请直接调对应的 stack/presign 原子工具。',
+        '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 用 selfTime（自身耗时 ms），Mono 用 selfMemory（KB）'),
+            .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('报告模式，默认跟随报告详情；mono 仅 Unity'),
+            .describe('overview（默认）或 mono；stackTestMode 仅 overview 有效'),
     },
     async handler(args, ctx) {
         try {

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

@@ -0,0 +1,6 @@
+/** 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"];
+export declare function splitIndicatorDashboards(raw: unknown): string[];
+export declare function findUnknownIndicatorDashboards(raw: unknown): string[];

package/dist/indicator-dashboard-keys.js

@@ -0,0 +1,30 @@
+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',
+];
+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));
+}