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

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,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"];
+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,49 @@
+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));
+}
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+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 };
+}