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

package/dist/tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { UwaApiError } from './client.js';
 import { INDICATOR_DASHBOARD_PANEL_GUIDE, versionGuideFor } from './version-guide.js';
-import { findUnknownIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
+import { partitionIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
+import { annotateStatisticDashboard, annotateOverviewStatisticPss, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, isOverviewStatisticOp, stutterRootCauseGate, stripOuterXAxisWhenFramesOnly, } from './annotate-dashboard.js';
 const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
 /**
  * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
@@ -86,6 +87,13 @@ function describe(op) {
     }
     return lines.join('\n');
 }
+const SERVICE_META_TYPE_ENUM = 'PA（真人真机）、GOT_ONLINE（GOT Online）、LT（本地资源检测）、AB（AssetBundle 检测）、ATP（自动化功能测试）、BR（Build 分析）';
+/** 个别接口默认 apiVersion 与上游文档「推荐值」不一致时，在 MCP 侧纠偏。 */
+function defaultApiVersionFor(op) {
+    if (op.id === 'gotonline_overview_method_group_statistic')
+        return 'v1.0.2';
+    return op.defaultApiVersion;
+}
 export function buildInputSchema(op) {
     const shape = {};
     for (const p of [...op.query, ...op.body]) {
@@ -95,30 +103,58 @@ export function buildInputSchema(op) {
             desc = [
                 desc,
                 '传参名为面板标识符：后缀 _max/_avg 等为历史命名，不表示只能取峰值或均值。',
-                `合法取值共 ${INDICATOR_DASHBOARD_KEYS.length} 个；可先调 gotonline_overview_indicator_dashboard_keys 拉全量列表。`,
+                '每个面板一次返回全部统计量，勿按 mean/max/min 拆成多个面板名。',
+                `合法取值共 ${INDICATOR_DASHBOARD_KEYS.length} 个；可先调 gotonline_overview_indicator_dashboard_keys 拉全量列表（命名含 @ 等，不可从示例归纳）。`,
                 `常见误传（非面板名）：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}。`,
                 `示例面板名：${sampleKeys.join('、')}。`,
             ].join(' ');
         }
+        if (p.name === 'serviceMetaTypeList') {
+            desc = `${desc.replace(/见下方枚举值/, '枚举如下').replace(/，$/, '')}。合法值：${SERVICE_META_TYPE_ENUM}。`;
+        }
+        if (p.name === 'stackMethodName') {
+            desc = `${desc} 响应含 _resolvedMethod 时请核对实际命中的 stackMethodId（同名会自动取耗时最大者）。`;
+        }
         const base = zodFor(p).describe(p.example ? `${desc}（示例：${p.example}）` : desc);
         shape[p.name] = p.required ? base : base.optional();
     }
     if (op.apiVersions.length > 1) {
+        const def = defaultApiVersionFor(op);
         shape['apiVersion'] = z
             .enum(op.apiVersions)
             .optional()
-            .describe(`接口版本，默认 ${op.defaultApiVersion}。不同版本的返回字段有差异，详见文档`);
+            .describe(`接口版本，默认 ${def}。不同版本的返回字段有差异，详见文档`);
     }
     if (op.returnsPresignUrl) {
+        const isHeavyTree = op.id.includes('stack_overall_tree') ||
+            op.id.includes('stack_stutter') ||
+            op.id.includes('stack_tree');
         shape['download'] = z
             .boolean()
             .optional()
-            .describe('是否自动下载并解析预签名数据，默认 true。设为 false 时只返回 dataPresignUrl');
+            .describe(isHeavyTree
+            ? '是否自动下载并解析预签名数据，默认 true。大报告堆栈树建议 download=false，只取 dataPresignUrl 自行处理，避免撑爆上下文'
+            : '是否自动下载并解析预签名数据，默认 true。设为 false 时只返回 dataPresignUrl');
         shape['maxRows'] = z
             .number()
             .optional()
             .describe('可选的条目数上限。默认返回全部数据，只有在明确只需要前 N 条时才传这个参数');
     }
+    if (isIndicatorCurveDashboard(op.path)) {
+        shape['valueGt'] = z
+            .number()
+            .optional()
+            .describe('MCP 侧过滤：只保留数值 > 该阈值的曲线点（例：帧耗时慢帧传 40，单位与曲线一致多为 ms）');
+        shape['valueLt'] = z.number().optional().describe('MCP 侧过滤：只保留数值 < 该阈值的曲线点');
+        shape['topN'] = z
+            .number()
+            .optional()
+            .describe('MCP 侧过滤：在阈值过滤后按数值降序只保留最大的 N 个点');
+        shape['returnFramesOnly'] = z
+            .boolean()
+            .optional()
+            .describe('MCP 侧：为 true 时每条曲线只返回 frames[] + values[]，进一步压缩体积');
+    }
     return shape;
 }
 /** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
@@ -278,7 +314,7 @@ export function annotateDashboardEmptyResult(op, data, args) {
     const emptyColumns = !Array.isArray(columns) || columns.length === 0;
     if (!emptyStat && !emptyColumns)
         return data;
-    const unknown = findUnknownIndicatorDashboards(requested);
+    const { unknown } = partitionIndicatorDashboards(requested);
     const hintParts = [
         'indicatorDashboards 可能传错，导致 statistic/columns 为空。',
         '面板传参名≠统计维度后缀（如 fps_mean、frametime_min 是返回字段，不是面板名）。',
@@ -295,6 +331,41 @@ export function annotateDashboardEmptyResult(op, data, args) {
     };
 }
 const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
+function hasNonEmptyRecords(v) {
+    return Array.isArray(v) && v.length > 0;
+}
+/** 各 GOT Online 子模块是否有报告；供模型「无 GPU 停手」。 */
+export function buildModuleAvailable(group) {
+    return {
+        overview: hasNonEmptyRecords(group['gotOnlineOverviewRecords']),
+        gpu: hasNonEmptyRecords(group['gotOnlineGPURecords']),
+        mono: hasNonEmptyRecords(group['gotOnlineMonoRecords']),
+        lua: hasNonEmptyRecords(group['gotOnlineLuaRecords']),
+        resource: hasNonEmptyRecords(group['gotOnlineResourceRecords']),
+    };
+}
+export function annotateModuleAvailable(data) {
+    if (!isObj(data) || !Array.isArray(data['content']))
+        return data;
+    const content = data['content'].map((g) => {
+        if (!isObj(g))
+            return g;
+        const module_available = buildModuleAvailable(g);
+        const missing = Object.entries(module_available)
+            .filter(([, ok]) => !ok)
+            .map(([k]) => k);
+        return {
+            ...g,
+            module_available,
+            ...(missing.length
+                ? {
+                    _moduleHint: `本项目组缺少模块：${missing.join('、')}。module_available 为 false 的模块请停手，禁止用 Overview 数据冒充分析。`,
+                }
+                : {}),
+        };
+    });
+    return { ...data, content };
+}
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
  * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
@@ -304,10 +375,10 @@ const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
  */
 export function annotateProjectGroups(data) {
     if (!isObj(data) || !Array.isArray(data['content']))
-        return data;
+        return annotateModuleAvailable(data);
     const groups = data['content'].filter(isObj);
     if (groups.length < 2)
-        return data;
+        return annotateModuleAvailable(data);
     // dataKey → 出现过的项目组；以及「该报告在哪个数组字段里、原文是什么」
     const groupsOf = new Map();
     const firstSeen = new Map();
@@ -336,7 +407,7 @@ export function annotateProjectGroups(data) {
     }
     const duplicated = [...groupsOf.values()].some((gs) => gs.size > 1);
     if (!duplicated)
-        return data;
+        return annotateModuleAvailable(data);
     // 已知项目组壳子（保留名称、engine 等元信息），报告重新按真实归属灌入
     const shells = new Map();
     for (const g of groups) {
@@ -371,15 +442,15 @@ export function annotateProjectGroups(data) {
     }
     // 丢掉合并后一个报告都没有的空组（它们原先只有别人的副本）
     const content = [...shells.values()].filter((g) => Object.entries(g).some(([k, v]) => RECORD_ARRAY_KEYS.test(k) && Array.isArray(v) && v.length > 0));
-    return {
+    return annotateModuleAvailable({
         ...data,
         content,
         _deduplicated: true,
         _uniqueReportCount: placed,
-        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
-            '。可直接按项目组统计。',
-    };
+            '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
+    });
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
@@ -389,44 +460,128 @@ function asText(value) {
         return '(接口无返回内容)';
     return JSON.stringify(value, null, 2);
 }
+/** 空 Bound / 空日志列表等：补可教模型的语义，避免误判。 */
+export function annotateEmptyStateSemantics(op, data) {
+    if (op.id === 'gotonline_gpu_bound') {
+        const intervals = Array.isArray(data) ? data : isObj(data) && Array.isArray(data['data']) ? data['data'] : null;
+        if (intervals && intervals.length === 0) {
+            const base = isObj(data) ? data : { data: intervals };
+            return {
+                ...base,
+                gpuBound: [],
+                forbidden_claims: ['GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈'],
+                _hint: 'GPU Bound 为空数组：仅表示在当前 targetFps 下未检出 Bound 区间，不等于 GPU 完全无压力；禁止据此断言 GPU 是主要瓶颈。',
+            };
+        }
+    }
+    if (op.id === 'gotonline_overview_log_export') {
+        const empty = (Array.isArray(data) && data.length === 0) ||
+            (isObj(data) && Array.isArray(data['data']) && data['data'].length === 0);
+        if (empty) {
+            const base = isObj(data) ? data : { entries: data };
+            return {
+                ...base,
+                _hint: '运行日志 1.0 返回空列表：可能是真无条目，也可能是新报告应改用 gotonline_lg_runtime_log_entries_presign（日志 2.0）。禁止说成「一定没有日志」。',
+            };
+        }
+    }
+    if (op.id === 'gotonline_overview_event_lower_memory_frames') {
+        const empty = (Array.isArray(data) && data.length === 0) ||
+            (isObj(data) && Array.isArray(data['data']) && data['data'].length === 0);
+        if (empty) {
+            const base = isObj(data) ? data : { frames: data };
+            return {
+                ...base,
+                _hint: '未触发 Low Memory 事件（空数组）。不能推出内存完全没问题，请结合 PSS 峰值等综合判断。',
+            };
+        }
+    }
+    return data;
+}
 export function makeHandler(op, client, defaultMaxRows, maxChars) {
     return async (args) => {
         try {
-            const apiVersion = args['apiVersion'] ?? op.defaultApiVersion;
+            const apiVersion = args['apiVersion'] ?? defaultApiVersionFor(op);
             const wantDownload = args['download'] ?? true;
             const maxRows = args['maxRows'] ?? defaultMaxRows;
+            const { filter: curveFilter, cleaned: argsForApi } = isIndicatorCurveDashboard(op.path)
+                ? extractCurveFilterArgs(args)
+                : { filter: {}, cleaned: args };
+            let acceptedDashboards = [];
+            let unknownDashboards = [];
+            if (typeof argsForApi['indicatorDashboards'] === 'string') {
+                const part = partitionIndicatorDashboards(argsForApi['indicatorDashboards']);
+                acceptedDashboards = part.accepted;
+                unknownDashboards = part.unknown;
+                if (part.all.length && !acceptedDashboards.length) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: asText({
+                                    error: 'PARAMETERS_WRONG',
+                                    message: `indicatorDashboards 全部无法识别：${unknownDashboards.join('、')}`,
+                                    _unknownDashboards: unknownDashboards,
+                                    _acceptedDashboards: [],
+                                    _hint: `这些是面板标识符，不是统计维度后缀。` +
+                                        `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}；` +
+                                        `合法示例：fps_avg、frametime@gt_40_pct。` +
+                                        `请调 gotonline_overview_indicator_dashboard_keys 获取全量 ${INDICATOR_DASHBOARD_KEYS.length} 个合法值。`,
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (acceptedDashboards.length) {
+                    argsForApi['indicatorDashboards'] = acceptedDashboards.join(',');
+                }
+            }
             const query = {};
             for (const p of op.query)
-                if (args[p.name] !== undefined)
-                    query[p.name] = args[p.name];
+                if (argsForApi[p.name] !== undefined)
+                    query[p.name] = argsForApi[p.name];
             let body;
             if (op.body.length) {
                 body = {};
                 for (const p of op.body)
-                    if (args[p.name] !== undefined)
-                        body[p.name] = args[p.name];
+                    if (argsForApi[p.name] !== undefined)
+                        body[p.name] = argsForApi[p.name];
             }
             const raw = await client.call(op.method, op.path, apiVersion, query, body);
-            const unknownDashboards = findUnknownIndicatorDashboards(args['indicatorDashboards']);
-            if (unknownDashboards.length) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: asText({
-                                error: 'PARAMETERS_WRONG',
-                                message: `indicatorDashboards 含未知面板名：${unknownDashboards.join('、')}`,
-                                _hint: `这些是面板标识符，不是统计维度后缀。` +
-                                    `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}；` +
-                                    `合法示例：fps_avg、frametime@gt_40_pct。` +
-                                    `请调 gotonline_overview_indicator_dashboard_keys 获取全量 ${INDICATOR_DASHBOARD_KEYS.length} 个合法值。`,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
+            let processed = annotateProjectGroups(annotateCurveAxes(raw));
+            if (isIndicatorStatisticDashboard(op.path) && acceptedDashboards.length) {
+                processed = annotateStatisticDashboard(processed, acceptedDashboards, unknownDashboards);
+            }
+            else if (isOverviewStatisticOp(op.id, op.path)) {
+                processed = annotateOverviewStatisticPss(processed);
+            }
+            else if (isIndicatorCurveDashboard(op.path)) {
+                if (acceptedDashboards.length || unknownDashboards.length) {
+                    processed = isObj(processed)
+                        ? {
+                            ...processed,
+                            _acceptedDashboards: acceptedDashboards,
+                            ...(unknownDashboards.length ? { _unknownDashboards: unknownDashboards } : {}),
+                        }
+                        : processed;
+                }
+                if (hasCurveFilter(curveFilter)) {
+                    processed = filterCurveData(processed, curveFilter);
+                    if (curveFilter.returnFramesOnly) {
+                        processed = stripOuterXAxisWhenFramesOnly(processed, curveFilter);
+                    }
+                    else {
+                        processed = annotateCurveAxes(processed);
+                    }
+                }
+            }
+            let data = annotateDashboardEmptyResult(op, processed, args);
+            data = annotateEmptyStateSemantics(op, data);
+            const stutterGate = stutterRootCauseGate(op.id);
+            if (stutterGate && isObj(data)) {
+                data = { ...data, ...stutterGate };
             }
-            const data = annotateDashboardEmptyResult(op, annotateProjectGroups(annotateCurveAxes(raw)), args);
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
@@ -464,6 +619,7 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
             }
             const meta = {
                 ...data,
+                ...(stutterRootCauseGate(op.id) ?? {}),
                 _downloaded: true,
                 _format: payload.kind,
                 ...(total !== undefined ? { _totalItems: total } : {}),

package/dist/version-guide.d.ts

@@ -9,6 +9,11 @@
  * 挂到所有带 indicatorDashboards 的工具 description，避免模型见 _max 只读峰值。
  */
 export declare const INDICATOR_DASHBOARD_PANEL_GUIDE: string;
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >40ms 帧循环拉指定帧树再聚类」。
+ */
+export declare const STACK_ANALYSIS_GUIDE: string;
 /** 写入工具 description 的「选用规则」块，key 为 operation id。 */
 export declare const VERSION_GUIDE: Record<string, string>;
 export declare function versionGuideFor(opId: string): string | undefined;

package/dist/version-guide.js

@@ -11,14 +11,35 @@
 export const INDICATOR_DASHBOARD_PANEL_GUIDE = [
     '【indicatorDashboards 传参名称——勿按后缀猜统计维度】',
     '- 传参名（如 temperature_max、fps_avg、drawcall_cnt_max）是**面板标识符**，_max / _avg / @max 等为历史命名，**不限制**返回 mean / maximum / min 等统计类型。',
+    '- 【返回粒度】每个面板一次返回其下所有子指标的全部统计量（mean / min / maximum / maximum_frame / 专属指标，以及 scene_*），',
+    '  无需也无法按统计量拆成多个面板名（勿传 fps_mean、fps_max、fps_min）。面板→子指标展开见返回体 group；入参→出参映射见 _paramFieldMap。',
     '- 例：temperature_max 面板含子指标 temperature、android_temper_cpu、android_temper_gpu、android_temper_battery；',
     '  · 曲线接口（indicator_curve / custom_dashboard）→ 各子指标逐帧曲线；',
     '  · 统计 2.0（indicator_statistic_dashboard）→ statistic 下 *_mean / *_maximum / *_min 及 scene_* 等全量统计。',
     '- 查温度曲线/均值/峰值：Unity Overview 且 SDK ≥ 2.5.1 时传 indicatorDashboards=temperature_max，再读 y_axis 或 statistic；勿仅看 get_overview_statistic 的汇总段。',
-    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys；勿传 fps_mean、frametime_min 等统计字段名。',
-    '- 误传示例：fps_mean、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、frametime@gt_40_pct。',
+    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys（全量枚举）；勿传 fps_mean、frametime_min、android_pss_max 等统计字段名。',
+    '- 误传示例：fps_mean、android_pss_max、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、android_memory_pss@max、frametime@gt_40_pct。',
+    '- Android PSS 峰值：只认面板 android_memory_pss@max；优先读返回顶层 pss_peak_kb / pss_peak_mb / pss_peak_frame（单位 KB）。',
     '- UE Overview 当前 Open API 未开放 custom/indicator dashboard 路径（会 24052），UE 温度汇总见 get_ue_overview_statistic_v2 的 temperature 段。',
 ].join('\n');
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >40ms 帧循环拉指定帧树再聚类」。
+ */
+export const STACK_ANALYSIS_GUIDE = [
+    '【堆栈/卡顿选用——务必先看】',
+    '- 卡顿根因主路径：用**卡顿聚合树**（已合并全部/场景内卡顿帧），不要对每个慢帧循环拉指定帧树。',
+    '- 工具分工：',
+    '  · gotonline_overview_stack_stutter_full_presign → 卡顿帧列表（哪些帧卡、类型耗时拆分）',
+    '  · gotonline_overview_stack_stutter_full_tree_presign → **全部卡顿帧合并后的堆栈树**（全报告卡顿共性根因）',
+    '  · gotonline_overview_stack_stutter_scene_tree_presign → **指定场景内卡顿帧合并树**（主玩法段）',
+    '  · gotonline_overview_stack_tree_frame_presign → **单帧**完整树（仅尖峰深挖，如已知 frameId=8439）',
+    '  · gotonline_overview_stack_overall_tree_presign → 整线程全量堆栈（非卡顿专用；看持续税/全局热点）',
+    '  · gotonline_overview_stack_sample_frame_presign → 树结点逐帧曲线',
+    '- 慢帧占比/挑代表帧：indicator 面板 frametime@gt_40_pct（统计或 curve+valueGt）；根因归因仍走卡顿聚合树。',
+    '- 读任何堆栈树前必须配合 gotonline_overview_stack_id_map（树里是 methodId）。',
+    '- 错误假设：❌「没有批量帧树就无法做卡顿根因」——总体/场景卡顿树就是合并结果。',
+].join('\n');
 /** 写入工具 description 的「选用规则」块，key 为 operation id。 */
 export const VERSION_GUIDE = {
     get_overview_statistic_v1: [
@@ -61,7 +82,8 @@ export const VERSION_GUIDE = {
         '- 自定义面板统计 2.0。需 SDK ≥ 2.5.1，支持 GPU 指标，最多 15 个面板。',
         '- 旧接口（抽帧、无 GPU）见 gotonline_overview_custom_dashboard。',
         '- 只要逐帧曲线不要统计值时用 gotonline_overview_indicator_curve_dashboard。',
-        '- 返回 statistic 为空时优先怀疑 indicatorDashboards 传错；响应可能含 _hint。',
+        '- 返回 statistic 为空时优先怀疑 indicatorDashboards 传错；响应可能含 _hint / _unknownDashboards。',
+        '- 响应可能含 _paramFieldMap（入参面板→出参字段）、_duplicateFlatAliases、_sceneUnitNote（scene_* 补单位标注）。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_overview_indicator_curve_dashboard: [
@@ -71,6 +93,8 @@ export const VERSION_GUIDE = {
         '- 【横轴——勿混用】外层 x_axis 为逐帧共享横轴（1、2、3…）；y_axis.{指标名}.x_axis 为该曲线专属横轴（常见步长 30：0、30、60…）。',
         '- 读取某条曲线时：若存在专属 x_axis 必须用专属，否则才用外层共享 x_axis。把共享横轴套到 FPS 等专属曲线会错位。',
         '- 响应另含 _axisBinding / _axisHint，按其中 xAxisSource 取值即可。',
+        '- 【过滤——MCP 侧】可选 valueGt / valueLt / topN / returnFramesOnly：只返回超阈值或 TopN 点，适合慢帧列表（例：frametime@gt_40_pct + valueGt=40）。',
+        '- 慢帧列表 ≠ 卡顿根因：根因请用 stutter_full_tree / stutter_scene_tree（卡顿帧已合并），不要对 valueGt 结果逐帧拉 stack_tree_frame。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_gpu_curve: [
@@ -92,11 +116,19 @@ export const VERSION_GUIDE = {
         '【选用规则——务必先看】',
         '- 运行日志 1.0。Unity：解析日 < 2026-07-09；UE：提交日 ≤ 2026-03-25。',
         '- 新报告请用 gotonline_lg_runtime_log_entries_presign（运行日志 2.0）。',
+        '- 空列表 ≠「一定没有日志」：新报告误用本接口也可能返回空，应改调 2.0。',
     ].join('\n'),
     gotonline_lg_runtime_log_entries_presign: [
         '【选用规则——务必先看】',
         '- 运行日志 2.0（预签名）。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1。',
         '- 更早的报告请用 gotonline_overview_log_export。',
+        '- 若返回 80108 FILE_META_NOT_EXIST：Unity = 无 LG meta / 未解析 = 无可用日志数据；UE = 方案切换过，只能说「暂不支持获取当前报告的运行日志」，勿断定报告本身无日志。',
+    ].join('\n'),
+    gotonline_gpu_bound: [
+        '【选用规则——务必先看】',
+        '- 说「GPU Bound / GPU 主瓶颈」前必须先调本工具。',
+        '- 返回 [] 只能说「未检出 Bound」，禁止断言 GPU 是主要瓶颈。',
+        '- Overview 上的 WaitForVsync / RenderTexture 不能替代本接口。',
     ].join('\n'),
     gotonline_overview_group_export: [
         '【选用规则——务必先看】',
@@ -105,8 +137,10 @@ export const VERSION_GUIDE = {
     ].join('\n'),
     gotonline_overview_method_group_statistic: [
         '【选用规则——务必先看】',
-        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25，且 api 版本须 v1.0.2）。',
+        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25）。',
+        '- **MCP 默认 apiVersion=v1.0.2**（勿用 v1.0.1，会参数错误）。需要旧行为时显式传 apiVersion=v1.0.1。',
         '- UE 旧报告请用 gotonline_overview_group_export。',
+        '- 未配置自定义函数组时 data=[]；Overview 热点函数曲线优先用 method_idmap_statistic + method_curve_presign，不必依赖函数组。',
     ].join('\n'),
     gotonline_overview_method_idmap_statistic: [
         '【选用规则——务必先看】',
@@ -139,6 +173,50 @@ export const VERSION_GUIDE = {
         '- 合法示例：fps_avg、drawcall_cnt_max、frametime@gt_40_pct、temperature_max。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
+    gotonline_overview_stack_id_map: [
+        '【选用规则——务必先看】',
+        '- 函数 ID ↔ 名称映射。解析任何 stack_*_tree / stutter_*_tree 前先调本工具。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_overall_tree_presign: [
+        '【选用规则——务必先看】',
+        '- 指定线程的**全量**调用堆栈树（含非卡顿帧），适合持续税/全局热点。',
+        '- 只要卡顿根因：改用 stutter_full_tree / stutter_scene_tree，勿用本接口代替卡顿聚合。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_presign: [
+        '【选用规则——务必先看】',
+        '- 卡顿**帧列表**（帧号 + 卡顿类型耗时拆分），不是堆栈树。',
+        '- 要卡顿根因堆栈：接着调 stutter_full_tree_presign（或场景版 stutter_scene_tree）。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **全部卡顿帧已合并**的调用堆栈树 = 卡顿根因主入口（服务端聚合，无需客户端逐帧拉树再聚类）。',
+        '- 禁止把 WaitForVsync / Gfx.WaitForPresent 写成卡顿根因或 GPU Bound 证据。',
+        '- 说「GPU 主瓶颈」前必须先查 gotonline_gpu_bound；空数组只能说「未检出 Bound」。',
+        '- 只要某一场景：用 stutter_scene_tree；只要某一尖峰帧细节：再用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_scene_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **指定场景内卡顿帧已合并**的堆栈树；sceneIndex 来自 list_scenes 下标。',
+        '- 禁止把 WaitForVsync 当根因；GPU 主瓶颈结论须先查 gpu_bound。',
+        '- 全报告卡顿用 stutter_full_tree；单帧深挖用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_tree_frame_presign: [
+        '【选用规则——务必先看】',
+        '- **单帧**完整堆栈树（frameId 必填）。用于已知尖峰帧深挖，不是卡顿分析的第一步。',
+        '- 卡顿共性根因请先用 stutter_full_tree / stutter_scene_tree（已是多帧合并结果）。',
+        '- ❌ 不要对 frametime valueGt 筛出的每个慢帧循环调用本工具来「聚类」。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_sample_frame_presign: [
+        '【选用规则——务必先看】',
+        '- 堆栈树某个结点的逐帧曲线；结点 id 来自树文件。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
 };
 export function versionGuideFor(opId) {
     return VERSION_GUIDE[opId];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.9",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {

package/spec/uwa-openapi.json

@@ -3631,7 +3631,7 @@
         "v1.0.1",
         "v1.0.2"
       ],
-      "defaultApiVersion": "v1.0.1",
+      "defaultApiVersion": "v1.0.2",
       "query": [
         {
           "name": "recordId",