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

package/dist/composite/report-diagnosis.js

@@ -0,0 +1,157 @@
+import { z } from './types.js';
+import { errorResult, jsonToolResult, requireReportKey } from './helpers.js';
+import { fetchOverviewStatistic, fetchReportIdentity, fetchSceneStatistic, } from './route-overview.js';
+import { viewOverview } from './overview-view.js';
+import { runTopFunctions } from './top-functions.js';
+import { runTopResources } from './top-resources.js';
+function summarizeScenes(data) {
+    if (!data)
+        return { sceneCount: 0 };
+    if (Array.isArray(data))
+        return { sceneCount: data.length, scenes: data.slice(0, 20) };
+    if (typeof data !== 'object' || data === null)
+        return { rawType: typeof data };
+    const obj = data;
+    for (const k of ['scenes', 'list', 'content', 'records']) {
+        if (Array.isArray(obj[k])) {
+            const arr = obj[k];
+            return { sceneCount: arr.length, scenes: arr.slice(0, 20) };
+        }
+    }
+    return { keys: Object.keys(obj).slice(0, 30) };
+}
+/** brief 全量可能很长，体检只保留常见关键指标。 */
+function pickImportantBrief(brief) {
+    const prefer = [
+        'fps_mean',
+        'fps',
+        'FPS均值',
+        'jank_rate',
+        'cpu_freq_mean',
+        'Total_Reserved_Memory_Bytes_maximum',
+        'Reserved Total峰值',
+        'lua_total_memory_maximum',
+    ];
+    const out = {};
+    for (const k of prefer)
+        if (brief[k] !== undefined)
+            out[k] = brief[k];
+    let n = 0;
+    for (const [k, v] of Object.entries(brief)) {
+        if (k in out)
+            continue;
+        out[k] = v;
+        if (++n >= 12)
+            break;
+    }
+    return out;
+}
+export const reportDiagnosisTool = {
+    id: 'report_diagnosis',
+    title: '报告体检',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['report_diagnosis', 'composite', 'preset.default', 'overview'],
+    description: [
+        '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数与场景摘要。',
+        '适用引擎：Unity / UE｜复合工具',
+        '调用方不必自己判断 2026-07-09 / 2026-03-25 分界或 SDK 版本——内部按 get_report_detail 路由。',
+        'Top 函数来自堆栈树解析合并，不是统计接口里的抽样指标。',
+        '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
+    ].join('\n'),
+    inputSchema: {
+        dataKey: z.string().optional().describe('报告 dataKey，与 recordId 二选一'),
+        recordId: z.union([z.string(), z.number()]).optional().describe('报告 recordId，与 dataKey 二选一'),
+    },
+    async handler(args, ctx) {
+        try {
+            const key = requireReportKey(args);
+            const apisUsed = [];
+            const limitations = [];
+            const identity = await fetchReportIdentity(ctx.client, key);
+            apisUsed.push('get_report_detail');
+            const { target, data } = await fetchOverviewStatistic(ctx.client, identity);
+            apisUsed.push(target.id);
+            const view = viewOverview(data);
+            const hasRes = view.hasResource === true;
+            let topResources = null;
+            try {
+                topResources = await runTopResources(ctx.client, { ...key, topN: 10 });
+                const used = topResources['_apisUsed'];
+                if (Array.isArray(used))
+                    for (const u of used)
+                        if (!apisUsed.includes(String(u)))
+                            apisUsed.push(String(u));
+            }
+            catch (e) {
+                limitations.push(`top_resources 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let topFunctions = null;
+            try {
+                const subtype = identity.serviceSubtype === 'mono' ? 'mono' : 'overview';
+                topFunctions = await runTopFunctions(ctx.client, { ...key, topN: 10, serviceSubtype: subtype });
+                const used = topFunctions['_apisUsed'];
+                if (Array.isArray(used))
+                    for (const u of used)
+                        if (!apisUsed.includes(String(u)))
+                            apisUsed.push(String(u));
+                if (Array.isArray(topFunctions['_limitations'])) {
+                    for (const lim of topFunctions['_limitations'])
+                        limitations.push(String(lim));
+                }
+            }
+            catch (e) {
+                limitations.push(`top_functions 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let scenes = null;
+            try {
+                const scene = await fetchSceneStatistic(ctx.client, identity);
+                if (scene) {
+                    scenes = summarizeScenes(scene.data);
+                    apisUsed.push(scene.target.id);
+                }
+                else {
+                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景摘要');
+                }
+            }
+            catch (e) {
+                limitations.push(`场景统计失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            if (!hasRes)
+                limitations.push('未开启资源采集或无法从 brief 判定，逐资源 Top 可能为空');
+            const result = {
+                report: {
+                    dataKey: identity.dataKey,
+                    recordId: identity.recordId,
+                    recordName: identity.recordName,
+                    engine: identity.engine,
+                    createDate: identity.createDate,
+                    sdkVersion: identity.sdkVersion,
+                    serviceSubtype: identity.serviceSubtype,
+                },
+                routedOverview: target.id,
+                overviewShape: view.shape,
+                summary: view.summary,
+                brief: pickImportantBrief(view.brief),
+                topResources: topResources
+                    ? { items: topResources['items'], note: topResources['_note'] }
+                    : null,
+                topFunctions: topFunctions
+                    ? {
+                        items: topFunctions['items'],
+                        metric: topFunctions['metric'],
+                        uniqueFunctions: topFunctions['uniqueFunctions'],
+                        note: topFunctions['_note'],
+                    }
+                    : null,
+                scenes,
+                _apisUsed: apisUsed,
+                _limitations: limitations,
+                _note: '结构化体检摘要。细节请按 _apisUsed 调用对应原子工具。',
+            };
+            return jsonToolResult(result, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

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

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

package/dist/composite/route-overview.js

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

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

@@ -0,0 +1,65 @@
+import type { UwaClient } from '../client.js';
+import type { ReportIdentity } from './route-overview.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;
+    metric: StackMetric;
+    unit: string;
+    rows: Array<{
+        name: string;
+        methodId: string;
+        value: number;
+        unit: string;
+        selfTimeMs?: number;
+        totalTimeMs?: number;
+        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;
+}
+/**
+ * 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[];
+export {};