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

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

@@ -0,0 +1,77 @@
+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;
+    name: string;
+    /** 自身耗时合计（微秒）；CPU 类模式 */
+    selfTimeUs: number;
+    /** 总耗时合计（微秒）；仅供参考，同名合并时可能有父子重叠语义问题 */
+    totalTimeUs: number;
+    callCount: number;
+    callFrameCount: number;
+    /** 自身内存合计（KB）；Lua 内存类模式 */
+    selfMemoryKb: number;
+    totalMemoryKb: number;
+    /** 该函数在树中出现的节点数（合并前） */
+    nodeCount: number;
+}
+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;
+        selfTimeMean?: number | null;
+        totalTimeMean?: number | null;
+        callCountTotal?: number | null;
+        selfMemoryMean?: number | null;
+        selfMemoryTotal?: number | null;
+        selfMemoryUnit?: string | null;
+        selfMemoryKb?: number;
+        callCount: number;
+        callFrameCount: number;
+        nodeCount: number;
+        source: string;
+    }>;
+    totalNodes: number;
+    uniqueFunctions: number;
+    apisUsed: string[];
+}
+interface TreeNode {
+    depth: number;
+    sampleId: string;
+    methodId: string;
+    totalTimeUs: number;
+    selfTimeUs: number;
+    callCount: number;
+    callFrameCount: number;
+    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。
+ */
+export declare function aggregateOverviewStack(client: UwaClient, identity: ReportIdentity, topN: number, metric?: StackMetric): Promise<StackAggResult>;
+/**
+ * Mono：正向堆栈树 + Mono 函数 idmap。
+ * 文本格式与 Overview CSV 不同时走宽松解析；失败则抛错由上层处理。
+ */
+export declare function aggregateMonoStack(client: UwaClient, identity: ReportIdentity, topN: number, metric?: StackMetric): Promise<StackAggResult>;
+/**
+ * 解析无表头 CSV。列数随 testMode 变化；UE 固定 7 列（与 CPU_ONLY 同形）。
+ */
+export declare function parseStackCsv(csvText: string, testMode: string | null): TreeNode[];

package/dist/composite/stack-agg.js

@@ -0,0 +1,409 @@
+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。
+ */
+export async function aggregateOverviewStack(client, identity, topN, metric = 'selfTime') {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    const apisUsed = [];
+    const [treeMeta, idMap] = await Promise.all([
+        client.call('GET', '/openapi/v1/data/gotonline/overview/stack/overall/tree/presign', 'v1.0.1', keyQuery),
+        fetchFunctionIdMap(client, keyQuery),
+    ]);
+    apisUsed.push('gotonline_overview_stack_overall_tree_presign', 'gotonline_overview_stack_id_map');
+    const url = typeof treeMeta['dataPresignUrl'] === 'string' ? treeMeta['dataPresignUrl'] : null;
+    if (!url)
+        throw new Error('线程堆栈树未返回 dataPresignUrl（报告可能未开 CPU 堆栈或 SDK < 2.5.1）');
+    const testMode = treeMeta['testMode'] != null ? String(treeMeta['testMode']) : null;
+    const payload = await client.downloadPresign(url);
+    const csvText = payload.kind === 'text' ? (payload.text ?? '') : JSON.stringify(payload.json ?? '');
+    const nodes = parseStackCsv(csvText, testMode);
+    return finalizeAgg(nodes, idMap, topN, metric, testMode, apisUsed, 'overview.stack.overall');
+}
+/**
+ * Mono：正向堆栈树 + Mono 函数 idmap。
+ * 文本格式与 Overview CSV 不同时走宽松解析；失败则抛错由上层处理。
+ */
+export async function aggregateMonoStack(client, identity, topN, metric = 'selfMemory') {
+    const keyQuery = identity.dataKey
+        ? { dataKey: identity.dataKey }
+        : { recordId: identity.recordId };
+    const apisUsed = [];
+    const [treeMeta, idMapRaw] = await Promise.all([
+        client.call('GET', '/openapi/v1/data/gotonline/mono/stack/tree/overall/presign', 'v1.0.1', keyQuery),
+        client.call('GET', '/openapi/v1/data/gotonline/mono/stack/method/idmap/presign', 'v1.0.1', keyQuery),
+    ]);
+    apisUsed.push('gotonline_mono_stack_tree_overall_presign', 'gotonline_mono_stack_method_idmap_presign');
+    const treeUrl = typeof treeMeta['dataPresignUrl'] === 'string' ? treeMeta['dataPresignUrl'] : null;
+    const mapUrl = typeof idMapRaw['dataPresignUrl'] === 'string' ? idMapRaw['dataPresignUrl'] : null;
+    if (!treeUrl)
+        throw new Error('Mono 堆栈树未返回 dataPresignUrl');
+    if (!mapUrl)
+        throw new Error('Mono 函数 idmap 未返回 dataPresignUrl');
+    const [treePayload, mapPayload] = await Promise.all([
+        client.downloadPresign(treeUrl),
+        client.downloadPresign(mapUrl),
+    ]);
+    const idMap = parseIdMapPayload(mapPayload.json ?? mapPayload.text);
+    const csvText = treePayload.kind === 'text' ? (treePayload.text ?? '') : JSON.stringify(treePayload.json ?? '');
+    // Mono 正向树多为文本/CSV；按 CPU_ONLY/内存列尝试解析
+    const nodes = parseStackCsv(csvText, 'LUA_MEM_ONLY');
+    const useMetric = metric === 'selfTime' || metric === 'totalTime' ? 'selfMemory' : metric;
+    return finalizeAgg(nodes, idMap, topN, useMetric, 'LUA_MEM_ONLY', apisUsed, 'mono.stack.overall');
+}
+async function fetchFunctionIdMap(client, keyQuery) {
+    const raw = await client.call('GET', '/openapi/v1/data/gotonline/overview/stack/id/map', 'v1.0.1', keyQuery);
+    return parseIdMapPayload(raw);
+}
+function parseIdMapPayload(raw) {
+    const map = new Map();
+    let list = null;
+    if (isObj(raw)) {
+        list = raw['id_map'] ?? raw['stats_id_map'] ?? raw['idMap'];
+    }
+    if (!list && typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (isObj(parsed))
+                list = parsed['id_map'] ?? parsed['stats_id_map'];
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (!Array.isArray(list))
+        return map;
+    for (const item of list) {
+        if (!isObj(item))
+            continue;
+        const id = item['id'] != null ? String(item['id']) : '';
+        const name = item['name'] != null ? String(item['name']) : '';
+        if (id)
+            map.set(id, name || id);
+    }
+    return map;
+}
+/**
+ * 解析无表头 CSV。列数随 testMode 变化；UE 固定 7 列（与 CPU_ONLY 同形）。
+ */
+export function parseStackCsv(csvText, testMode) {
+    const lines = csvText
+        .replace(/^\uFEFF/, '')
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const nodes = [];
+    for (const line of lines) {
+        const cols = splitCsvLine(line);
+        if (cols.length < 6)
+            continue;
+        const depth = Number(cols[0]);
+        const sampleId = String(cols[1] ?? '');
+        const methodId = String(cols[2] ?? '');
+        if (!methodId || Number.isNaN(depth))
+            continue;
+        const mode = (testMode ?? inferMode(cols.length)).toUpperCase();
+        let totalTimeUs = 0;
+        let selfTimeUs = 0;
+        let callCount = 0;
+        let callFrameCount = 0;
+        let totalMemoryKb = 0;
+        let selfMemoryKb = 0;
+        if (mode === 'LUA_MEM_ONLY' || (cols.length === 7 && mode.includes('LUA') && !mode.includes('CPU'))) {
+            totalMemoryKb = num(cols[3]);
+            selfMemoryKb = num(cols[4]);
+            callCount = num(cols[5]);
+            callFrameCount = num(cols[6]);
+        }
+        else if (mode === 'CPU_AND_LUA_MEM' || cols.length >= 9) {
+            totalTimeUs = num(cols[3]);
+            selfTimeUs = num(cols[4]);
+            callCount = num(cols[5]);
+            totalMemoryKb = num(cols[6]);
+            selfMemoryKb = num(cols[7]);
+            callFrameCount = num(cols[8]);
+        }
+        else {
+            // CPU_ONLY / UE 7 列
+            totalTimeUs = num(cols[3]);
+            selfTimeUs = num(cols[4]);
+            callCount = num(cols[5]);
+            callFrameCount = num(cols[6]);
+        }
+        nodes.push({
+            depth,
+            sampleId,
+            methodId,
+            totalTimeUs,
+            selfTimeUs,
+            callCount,
+            callFrameCount,
+            totalMemoryKb,
+            selfMemoryKb,
+        });
+    }
+    return nodes;
+}
+function inferMode(colCount) {
+    if (colCount >= 9)
+        return 'CPU_AND_LUA_MEM';
+    return 'CPU_ONLY';
+}
+function num(v) {
+    if (v == null || v === '')
+        return 0;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+/** 简单 CSV 分割：堆栈树字段不含引号逗号，按逗号切即可；兼容制表符。 */
+function splitCsvLine(line) {
+    if (line.includes('\t') && !line.includes(','))
+        return line.split('\t');
+    return line.split(',');
+}
+function finalizeAgg(nodes, idMap, topN, metric, testMode, apisUsed, source) {
+    const byId = new Map();
+    for (const n of nodes) {
+        let row = byId.get(n.methodId);
+        if (!row) {
+            row = {
+                methodId: n.methodId,
+                name: idMap.get(n.methodId) ?? n.methodId,
+                selfTimeUs: 0,
+                totalTimeUs: 0,
+                callCount: 0,
+                callFrameCount: 0,
+                selfMemoryKb: 0,
+                totalMemoryKb: 0,
+                nodeCount: 0,
+            };
+            byId.set(n.methodId, row);
+        }
+        row.selfTimeUs += n.selfTimeUs;
+        row.totalTimeUs += n.totalTimeUs;
+        row.callCount += n.callCount;
+        row.callFrameCount += n.callFrameCount;
+        row.selfMemoryKb += n.selfMemoryKb;
+        row.totalMemoryKb += n.totalMemoryKb;
+        row.nodeCount += 1;
+    }
+    // 同名不同 methodId 再按 name 合并一次（文档要求「同一个函数的节点还需要合并」）
+    const byName = new Map();
+    for (const row of byId.values()) {
+        const key = row.name || row.methodId;
+        const exist = byName.get(key);
+        if (!exist) {
+            byName.set(key, { ...row });
+            continue;
+        }
+        exist.selfTimeUs += row.selfTimeUs;
+        exist.totalTimeUs += row.totalTimeUs;
+        exist.callCount += row.callCount;
+        exist.callFrameCount += row.callFrameCount;
+        exist.selfMemoryKb += row.selfMemoryKb;
+        exist.totalMemoryKb += row.totalMemoryKb;
+        exist.nodeCount += row.nodeCount;
+        // 保留首次 methodId
+    }
+    const metricOf = (r) => {
+        switch (metric) {
+            case 'totalTime':
+                return r.totalTimeUs;
+            case 'callCount':
+                return r.callCount;
+            case 'selfMemory':
+                return r.selfMemoryKb;
+            case 'selfTime':
+            default:
+                return r.selfTimeUs;
+        }
+    };
+    const unit = metric === 'selfMemory' ? 'KB' : metric === 'callCount' ? '次' : 'ms';
+    const sorted = [...byName.values()].sort((a, b) => metricOf(b) - metricOf(a));
+    const rows = sorted.slice(0, topN).map((r) => {
+        const value = metric === 'callCount'
+            ? r.callCount
+            : metric === 'selfMemory'
+                ? round2(r.selfMemoryKb)
+                : round2(metricOf(r) / 1000); // μs → ms
+        return {
+            name: r.name,
+            methodId: r.methodId,
+            stackMethodId: r.methodId,
+            selfTimeMean: round2(r.selfTimeUs / 1000),
+            totalTimeMean: round2(r.totalTimeUs / 1000),
+            value,
+            unit,
+            selfMemoryKb: round2(r.selfMemoryKb),
+            callCount: r.callCount,
+            callFrameCount: r.callFrameCount,
+            nodeCount: r.nodeCount,
+            source,
+        };
+    });
+    return {
+        testMode,
+        metric,
+        unit,
+        rows,
+        totalNodes: nodes.length,
+        uniqueFunctions: byName.size,
+        apisUsed,
+    };
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}

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

@@ -0,0 +1,21 @@
+import type { UwaClient } from '../client.js';
+import type { CompositeTool } from './types.js';
+export interface FunctionRow {
+    name: string;
+    value: number;
+    unit?: string;
+    source: string;
+    label?: string;
+    methodId?: string;
+    stackMethodId?: string;
+    selfTimeMean?: number | null;
+    totalTimeMean?: number | null;
+    callCountTotal?: number | null;
+    selfMemoryMean?: number | null;
+    selfMemoryTotal?: number | null;
+    selfMemoryUnit?: string | null;
+    callCount?: number;
+    nodeCount?: number;
+}
+export declare function runTopFunctions(client: UwaClient, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare const topFunctionsTool: CompositeTool;