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

package/README.md

@@ -40,7 +40,7 @@ UWA 开放平台 MCP Server。把 UWA Open API 暴露为 MCP 工具，让 Cursor
 | Claude Desktop | `claude_desktop_config.json` |
 | Trae | 设置面板中的 MCP 配置 |
 
-改完重启客户端即可。
+改完重启客户端即可。多数客户端（Claude Desktop、Trae，以及 PATH 正常的环境）按上面配置即可，**一般不用写 node / npx 绝对路径**。
 
 凭证也可以走命令行参数，适配不支持 `env` 字段的客户端：
 
@@ -57,6 +57,73 @@ UWA 开放平台 MCP Server。把 UWA Open API 暴露为 MCP 工具，让 Cursor
 
 > 配置文件里含有凭证，注意不要提交到公开代码仓库。
 
+### Cursor 连不上时（按系统）
+
+先在**本机终端**跑通 `npx -y @uwa4d/openapi-mcp check ...`。终端正常、仅 Cursor 失败时，多半是 Cursor 启动 MCP 的环境问题（**不是本包或凭证坏了**）。按日志选对应写法，仍用 `npx`，不必绑死本机 Node 安装路径。
+
+| 系统 | 常见日志 | 推荐改法 |
+| --- | --- | --- |
+| **macOS** | `ENOENT .../Cursor.app/.../resources/lib` | 用登录壳启动（见下「macOS」） |
+| **Windows** | `spawn npx ENOENT` | 用 `cmd /c` 包一层（见下「Windows」） |
+| **Linux** | 找不到 `npx` / 类似 PATH 问题 | 用 `bash -lc`（见下「Linux」） |
+
+**macOS（推荐）**
+
+```json
+{
+  "mcpServers": {
+    "uwa-openapi": {
+      "command": "/bin/zsh",
+      "args": ["-lic", "npx -y @uwa4d/openapi-mcp mcp"],
+      "env": {
+        "UWA_MCP_APP_ID": "<your_app_id>",
+        "UWA_MCP_APP_SECRET": "<your_app_secret>"
+      }
+    }
+  }
+}
+```
+
+说明：Cursor 可能把自带 Node 插进 `PATH`，导致 `npx` 找错运行时。`-lic` 走登录壳，加载你平时终端里的 Node（含 nvm 等），不写死版本路径。额外参数写进同一条命令字符串即可。
+
+**Windows**
+
+```json
+{
+  "mcpServers": {
+    "uwa-openapi": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@uwa4d/openapi-mcp", "mcp"],
+      "env": {
+        "UWA_MCP_APP_ID": "<your_app_id>",
+        "UWA_MCP_APP_SECRET": "<your_app_secret>"
+      }
+    }
+  }
+}
+```
+
+说明：Windows 上 `npx` 实际是 `npx.cmd`，Cursor 直接 `spawn('npx')` 常会 `ENOENT`。经 `cmd /c` 启动即可。请先确认系统已安装 Node 18+，且在 **CMD** 里执行 `npx -v` 成功（若只用 nvm-windows / fnm，需保证其 bin 已进系统 PATH，或改用该工具提供的 `exec` 方式）。
+
+**Linux**
+
+```json
+{
+  "mcpServers": {
+    "uwa-openapi": {
+      "command": "/bin/bash",
+      "args": ["-lc", "npx -y @uwa4d/openapi-mcp mcp"],
+      "env": {
+        "UWA_MCP_APP_ID": "<your_app_id>",
+        "UWA_MCP_APP_SECRET": "<your_app_secret>"
+      }
+    }
+  }
+}
+```
+
+改完后在 Cursor 中 **Restart MCP**（或重启客户端）。若仍失败，把 MCP 输出日志里的完整报错留给支持同学。
+
 ### 先验证一下
 
 配置前可以在终端确认凭证和网络是否通：

package/dist/annotate-dashboard.d.ts

@@ -28,7 +28,21 @@ export declare function hasCurveFilter(filter: CurveFilterOptions): boolean;
  * 对 y_axis 曲线做客户端过滤，解决「慢帧列表必须全量进上下文」的问题。
  */
 export declare function filterCurveData(data: unknown, filter: CurveFilterOptions): unknown;
+/** returnFramesOnly 时去掉顶层无用 x_axis，避免慢帧列表撑爆上下文。 */
+export declare function stripOuterXAxisWhenFramesOnly(data: unknown, filter: CurveFilterOptions): unknown;
 export declare function isIndicatorStatisticDashboard(opPath: string): boolean;
 export declare function isIndicatorCurveDashboard(opPath: string): boolean;
+/** 从 android_memory_pss 统计抽出弱模型友好的峰值字段（单位 KB）。 */
+export declare function extractPssPeakCard(data: unknown): Record<string, unknown> | null;
+/**
+ * 从 Overview 统计 v2（categories[]）抽出 PSS 峰值答题卡。
+ * v2 通常只有 maximum、没有 peak frame —— frame 为 null 时提示改用 indicator 面板。
+ */
+export declare function extractPssPeakFromOverviewStatistic(data: unknown): Record<string, unknown> | null;
+/** Overview 统计（v1/v2）成功返回后附加 PSS 答题卡。 */
+export declare function annotateOverviewStatisticPss(data: unknown): unknown;
+export declare function isOverviewStatisticOp(opId: string, _opPath?: string): boolean;
+/** 卡顿合并树：返回层硬门禁，防止 WaitForVsync→根因 / 空 Bound 仍说 GPU 主瓶颈。 */
+export declare function stutterRootCauseGate(opId: string): Record<string, unknown> | null;
 /** 统计面板成功返回后的统一标注管线。 */
 export declare function annotateStatisticDashboard(data: unknown, accepted: string[], unknown: string[]): unknown;

package/dist/annotate-dashboard.js

@@ -254,12 +254,148 @@ export function filterCurveData(data, filter) {
         _curveFilterHint: '已按 valueGt/valueLt/topN/returnFramesOnly 在 MCP 侧过滤曲线点；完整曲线去掉这些参数即可。',
     };
 }
+/** returnFramesOnly 时去掉顶层无用 x_axis，避免慢帧列表撑爆上下文。 */
+export function stripOuterXAxisWhenFramesOnly(data, filter) {
+    if (!filter.returnFramesOnly || !isObj(data))
+        return data;
+    const { x_axis: _drop, ...rest } = data;
+    return {
+        ...rest,
+        _framesOnlyNote: 'returnFramesOnly=true 已省略顶层 x_axis；帧号在各曲线 frames 字段。',
+    };
+}
 export function isIndicatorStatisticDashboard(opPath) {
     return opPath.includes('/indicator/statistic/dashboard') || opPath.includes('/custom/dashboard');
 }
 export function isIndicatorCurveDashboard(opPath) {
     return opPath.includes('/indicator/curve/dashboard') || opPath.includes('/gpu/curve');
 }
+function numFromUnitOrData(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (Array.isArray(v) && typeof v[0] === 'number' && Number.isFinite(v[0]))
+        return v[0];
+    if (typeof v === 'object' && v !== null) {
+        const o = v;
+        if (typeof o.value === 'number' && Number.isFinite(o.value))
+            return o.value;
+        if (Array.isArray(o.data) && typeof o.data[0] === 'number')
+            return o.data[0];
+    }
+    return null;
+}
+function buildPssPeakCard(peakKb, frame) {
+    return {
+        pss_peak_kb: peakKb,
+        pss_peak_mb: Math.round((peakKb / 1024) * 100) / 100,
+        pss_peak_frame: frame,
+        pss_unit: 'KB',
+        _pssHint: 'Android PSS 峰值请优先读本对象顶层 pss_peak_kb / pss_peak_mb / pss_peak_frame；' +
+            '合法面板名是 android_memory_pss@max（不是 android_pss_max）。单位默认 KB。',
+    };
+}
+/** 从 android_memory_pss 统计抽出弱模型友好的峰值字段（单位 KB）。 */
+export function extractPssPeakCard(data) {
+    if (!isObj(data))
+        return null;
+    const statistic = isObj(data['statistic']) ? data['statistic'] : null;
+    const nested = statistic && isObj(statistic['android_memory_pss'])
+        ? statistic['android_memory_pss']
+        : null;
+    const peakKb = (nested ? numFromUnitOrData(nested['maximum']) : null) ??
+        (statistic ? numFromUnitOrData(statistic['android_memory_pss_maximum']) : null) ??
+        numFromUnitOrData(data['android_memory_pss_maximum']);
+    const frame = (nested ? numFromUnitOrData(nested['maximum_frame']) : null) ??
+        (statistic ? numFromUnitOrData(statistic['android_memory_pss_maximum_frame']) : null) ??
+        numFromUnitOrData(data['android_memory_pss_maximum_frame']);
+    if (peakKb == null)
+        return null;
+    return buildPssPeakCard(peakKb, frame);
+}
+/**
+ * 从 Overview 统计 v2（categories[]）抽出 PSS 峰值答题卡。
+ * v2 通常只有 maximum、没有 peak frame —— frame 为 null 时提示改用 indicator 面板。
+ */
+export function extractPssPeakFromOverviewStatistic(data) {
+    if (!isObj(data))
+        return null;
+    const categories = Array.isArray(data['categories'])
+        ? data['categories']
+        : isObj(data['data']) && Array.isArray(data['data']['categories'])
+            ? data['data']['categories']
+            : null;
+    if (!categories)
+        return null;
+    let peakKb = null;
+    let frame = null;
+    for (const cat of categories) {
+        if (!isObj(cat) || !Array.isArray(cat['indicators']))
+            continue;
+        for (const ind of cat['indicators']) {
+            if (!isObj(ind))
+                continue;
+            const key = String(ind['key'] ?? ind['indicatorKey'] ?? '');
+            const n = numFromUnitOrData(ind['data'] ?? ind['value']);
+            if (n == null)
+                continue;
+            if (key === 'android_memory_pss_maximum' || key === 'android_memory_pss@max')
+                peakKb = n;
+            if (key === 'android_memory_pss_maximum_frame' || key === 'android_memory_pss@max_frame')
+                frame = n;
+        }
+    }
+    if (peakKb == null)
+        return null;
+    const card = buildPssPeakCard(peakKb, frame);
+    if (frame == null) {
+        card['_pssFrameNote'] =
+            '本接口未返回峰值帧；需要 pss_peak_frame 时请再调 gotonline_overview_indicator_statistic_dashboard，面板名 android_memory_pss@max。';
+    }
+    return card;
+}
+/** Overview 统计（v1/v2）成功返回后附加 PSS 答题卡。 */
+export function annotateOverviewStatisticPss(data) {
+    if (Array.isArray(data)) {
+        return data.map((item) => annotateOverviewStatisticPss(item));
+    }
+    if (!isObj(data))
+        return data;
+    // batch map: { [dataKey]: { categories... } }
+    const keys = Object.keys(data);
+    if (!data['categories'] &&
+        !data['statistic'] &&
+        !data['brief'] &&
+        keys.length > 0 &&
+        keys.every((k) => isObj(data[k]))) {
+        const next = { ...data };
+        for (const k of keys)
+            next[k] = annotateOverviewStatisticPss(data[k]);
+        return next;
+    }
+    if (data['pss_peak_kb'] != null)
+        return data;
+    const fromDash = extractPssPeakCard(data);
+    const fromV2 = fromDash ?? extractPssPeakFromOverviewStatistic(data);
+    if (!fromV2)
+        return data;
+    return { ...data, ...fromV2 };
+}
+export function isOverviewStatisticOp(opId, _opPath) {
+    return (opId === 'get_overview_statistic_v1' ||
+        opId === 'get_overview_statistic_v2' ||
+        opId === 'get_ue_overview_statistic_v2');
+}
+/** 卡顿合并树：返回层硬门禁，防止 WaitForVsync→根因 / 空 Bound 仍说 GPU 主瓶颈。 */
+export function stutterRootCauseGate(opId) {
+    if (!/stack_stutter_(full|scene)_tree/.test(opId))
+        return null;
+    return {
+        forbidden_claims: ['WaitForVsync是卡顿根因', 'GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈'],
+        _stutterRootCauseHint: '本树是卡顿根因主入口。请按耗时归因到具体业务/引擎节点；' +
+            '禁止把 WaitForVsync / Gfx.WaitForPresent 写成根因或 GPU Bound 证据。' +
+            '若要说 GPU 主瓶颈，必须另查 gotonline_gpu_bound；空数组只能说「未检出 Bound」。',
+    };
+}
 /** 统计面板成功返回后的统一标注管线。 */
 export function annotateStatisticDashboard(data, accepted, unknown) {
     let out = annotateSceneUnits(data);
@@ -267,8 +403,10 @@ export function annotateStatisticDashboard(data, accepted, unknown) {
     out = annotateParamFieldMap(out);
     if (!isObj(out))
         return out;
+    const pssCard = extractPssPeakCard(out);
     return {
         ...out,
+        ...(pssCard ?? {}),
         _acceptedDashboards: accepted,
         ...(unknown.length ? { _unknownDashboards: unknown } : {}),
     };

package/dist/client.js

@@ -1,22 +1,12 @@
 import { gunzipSync } from 'node:zlib';
 import { authHeaders } from './auth.js';
+import { resolveErrorHint } from './error-hints.js';
 function isEnvelope(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;
     const o = v;
     return o['status'] === 'success' || o['status'] === 'failed';
 }
-/** 常见错误码的排查提示，直接给到模型，省掉一轮试错。 */
-const ERROR_HINTS = {
-    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
-    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
-    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
-    24052: '请求参数有误，请对照接口文档检查',
-    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
-    24056: '签名错误，检查 appSecret 是否正确',
-    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
-    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）',
-};
 export class UwaApiError extends Error {
     code;
     rawMessage;
@@ -68,8 +58,9 @@ export class UwaClient {
         if (parsed.status === 'failed' || parsed.error) {
             const code = parsed.error?.code ?? -1;
             const raw = parsed.error?.data?.rawMessage ?? '';
-            const hint = ERROR_HINTS[code];
-            throw new UwaApiError(code, raw, `[${code}] ${parsed.error?.message ?? '请求失败'}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
+            const apiMessage = parsed.error?.message ?? '请求失败';
+            const hint = resolveErrorHint(code, raw, apiMessage);
+            throw new UwaApiError(code, raw, `[${code}] ${apiMessage}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
         }
         return parsed.data ?? {};
     }

package/dist/composite/report-diagnosis.js

@@ -1,9 +1,10 @@
 import { z } from './types.js';
-import { errorResult, jsonToolResult, requireReportKey } from './helpers.js';
+import { errorResult, isObj, 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';
+import { extractPssPeakCard } from '../annotate-dashboard.js';
 function summarizeScenes(data) {
     if (!data)
         return { sceneCount: 0 };
@@ -76,18 +77,109 @@ function pickImportantBrief(brief) {
     }
     return out;
 }
+function numOf(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (Array.isArray(v) && typeof v[0] === 'number')
+        return v[0];
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/** 从 overview brief/summary 尽量抽出 PSS 峰值答题卡。 */
+function extractPssFromView(brief, summary) {
+    const sources = [brief, summary];
+    for (const src of sources) {
+        const peak = numOf(src['android_memory_pss_maximum']) ??
+            numOf(src['android_memory_pss@max']) ??
+            numOf(src['PSS峰值']) ??
+            numOf(src['设备内存峰值（MB）']);
+        const frame = numOf(src['android_memory_pss_maximum_frame']) ??
+            numOf(src['android_memory_pss@max_frame']) ??
+            null;
+        if (peak == null)
+            continue;
+        // brief 里设备内存峰值多为 MB；android_memory_pss 多为 KB
+        const looksMb = peak < 50_000 && (src['设备内存峰值（MB）'] !== undefined || peak < 2048);
+        const peakKb = looksMb ? Math.round(peak * 1024) : peak;
+        return {
+            pss_peak_kb: peakKb,
+            pss_peak_mb: Math.round((peakKb / 1024) * 100) / 100,
+            pss_peak_frame: frame,
+            pss_unit: 'KB',
+            _pssHint: 'Android PSS 峰值请优先读 pss_peak_kb/mb/frame；合法面板名 android_memory_pss@max（不是 android_pss_max）。',
+        };
+    }
+    return null;
+}
+/** 优先走 indicator statistic 拿完整 PSS 峰值+帧；失败再回退 overview brief。 */
+async function resolvePssPeakCard(client, identity, brief, summary, apisUsed, limitations) {
+    const keyQuery = {
+        indicatorDashboards: 'android_memory_pss@max',
+    };
+    if (identity.dataKey)
+        keyQuery['dataKey'] = identity.dataKey;
+    else if (identity.recordId != null)
+        keyQuery['recordId'] = identity.recordId;
+    else
+        return extractPssFromView(brief, summary);
+    try {
+        const raw = await client.call('GET', '/openapi/v1/data/gotonline/overview/indicator/statistic/dashboard', 'v1.0.1', keyQuery);
+        apisUsed.push('gotonline_overview_indicator_statistic_dashboard');
+        const card = extractPssPeakCard(raw);
+        if (card)
+            return card;
+        limitations.push('indicator PSS 面板无峰值字段，已回退 overview 摘要');
+    }
+    catch (e) {
+        limitations.push(`PSS 面板查询失败，已回退 overview 摘要：${e instanceof Error ? e.message : String(e)}`);
+    }
+    return extractPssFromView(brief, summary);
+}
+function isWaitForVsyncName(name) {
+    return /wait\s*for\s*vsync|WaitForVsync|Gfx\.WaitForPresent/i.test(String(name ?? ''));
+}
+function buildBottleneckCandidates(topFunctions, gpuBoundEmpty) {
+    const items = topFunctions && Array.isArray(topFunctions['items']) ? topFunctions['items'] : [];
+    const out = [];
+    for (const raw of items.slice(0, 8)) {
+        if (!isObj(raw))
+            continue;
+        const name = raw['name'] ?? raw['methodName'] ?? raw['stackMethodName'];
+        const wait = isWaitForVsyncName(name);
+        out.push({
+            name,
+            selfTimeMean: raw['selfTimeMean'] ?? raw['value'] ?? null,
+            source: 'top_functions',
+            role: wait ? 'frame_sync_wait' : 'cpu_candidate',
+            note: wait
+                ? 'WaitForVsync/Present 等待是帧同步表现，不能直接当卡顿根因或 GPU Bound 证据'
+                : '需结合 stutter 合并树确认是否为卡顿根因',
+        });
+    }
+    if (gpuBoundEmpty === true) {
+        out.push({
+            name: 'GPU Bound',
+            source: 'gotonline_gpu_bound',
+            role: 'not_detected',
+            note: 'targetFps=30 下未检出 GPU Bound 区间',
+        });
+    }
+    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 函数与场景摘要。',
+        '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数、场景摘要与 GPU Bound@30。',
         '适用引擎：Unity / UE｜复合工具',
         '调用方不必自己判断 2026-07-09 / 2026-03-25 分界或 SDK 版本——内部按 get_report_detail 路由。',
-        'Top 函数：Overview 走 method/idmap/statistic v1.0.2 + stackTestMode；Mono 走堆栈树；逐帧曲线用 method/curve/presign v1.0.2。',
-        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys 核对 indicatorDashboards（勿把 fps_mean 等统计字段当面板名）。',
-        '卡顿根因：stutter_full_tree / stutter_scene_tree（卡顿帧已合并的树）；尖峰再 stack_tree_frame；勿对每个慢帧循环拉帧树。',
+        '返回答题卡：forbidden_claims、bottleneck_candidates（与 topFunctions 分栏）、gpuBound、pss_peak_*、comparability_note。',
+        '卡顿根因：优先 stutter_full_tree / stutter_scene_tree；禁止把 WaitForVsync 写成根因或 GPU 主瓶颈。',
+        'gpuBound 为空时只能说「未检出 Bound」，禁止断言 GPU 是主要瓶颈。',
+        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys（勿把 fps_mean 等统计字段当面板名）。',
         'scenes 含 list_scenes 起止帧（sceneIdx/sceneName/frameStart/frameEnd）。',
         '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
     ].join('\n'),
@@ -166,10 +258,44 @@ export const reportDiagnosisTool = {
             catch (e) {
                 limitations.push(`场景列表(list_scenes)失败：${e instanceof Error ? e.message : String(e)}`);
             }
+            let gpuBound = null;
+            let gpuBoundEmpty = null;
+            try {
+                const boundQuery = { targetFps: 30 };
+                if (identity.dataKey)
+                    boundQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    boundQuery['recordId'] = identity.recordId;
+                gpuBound = await ctx.client.call('GET', '/openapi/v1/data/gotonline/gpu/bound', 'v1.0.1', boundQuery);
+                apisUsed.push('gotonline_gpu_bound');
+                const intervals = Array.isArray(gpuBound)
+                    ? gpuBound
+                    : isObj(gpuBound) && Array.isArray(gpuBound['data'])
+                        ? gpuBound['data']
+                        : null;
+                gpuBoundEmpty = Array.isArray(intervals) ? intervals.length === 0 : null;
+            }
+            catch (e) {
+                limitations.push(`gpu_bound 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
             // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
             if (view.hasResource === false) {
                 limitations.push('未开启资源采集，逐资源 Top 可能为空');
             }
+            const forbidden_claims = [];
+            if (gpuBoundEmpty === true) {
+                forbidden_claims.push('GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈');
+            }
+            forbidden_claims.push('WaitForVsync是卡顿根因');
+            const pssCard = await resolvePssPeakCard(ctx.client, identity, view.brief, view.summary, apisUsed, limitations);
+            const sceneCount = isObj(scenes) ? Number(scenes['sceneCount'] ?? 0) : 0;
+            const comparability_note = [
+                '与其它报告对比时：请核对场景名/数量、测试时长、目标帧率、SDK/引擎版本是否一致。',
+                sceneCount > 0 ? `本报告场景数=${sceneCount}。` : '',
+                '仅比较 FPS 均值不能视为严格同场景对比。',
+            ]
+                .filter(Boolean)
+                .join(' ');
             const result = {
                 report: {
                     dataKey: identity.dataKey,
@@ -185,6 +311,11 @@ export const reportDiagnosisTool = {
                 hasResource: view.hasResource,
                 summary: view.summary,
                 brief: pickImportantBrief(view.brief),
+                ...(pssCard ?? {}),
+                gpuBound: Array.isArray(gpuBound) ? gpuBound : isObj(gpuBound) ? gpuBound['data'] ?? gpuBound : gpuBound,
+                gpuBoundEmpty,
+                forbidden_claims,
+                bottleneck_candidates: buildBottleneckCandidates(topFunctions, gpuBoundEmpty),
                 topResources: topResources
                     ? {
                         items: topResources['items'],
@@ -198,12 +329,14 @@ export const reportDiagnosisTool = {
                         metric: topFunctions['metric'],
                         uniqueFunctions: topFunctions['uniqueFunctions'],
                         note: topFunctions['_note'],
+                        _columnNote: 'topFunctions 是耗时排行，不等于卡顿根因；根因看 stutter 合并树与 bottleneck_candidates。',
                     }
                     : null,
                 scenes,
+                comparability_note,
                 _apisUsed: apisUsed,
                 _limitations: limitations,
-                _note: '结构化体检摘要。细节请按 _apisUsed 调用对应原子工具。',
+                _note: '结构化体检摘要（含答题卡）。GPU Bound 空时禁止 GPU 主瓶颈结论；卡顿根因优先 stutter 树。细节请按 _apisUsed 调用对应原子工具。',
             };
             return jsonToolResult(result, ctx.maxChars);
         }

package/dist/error-hints.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export declare const FILE_META_REASONS: {
+    readonly LG_META_ABSENT: "LG_META_ABSENT";
+    readonly LG_RUNTIME_PATH_MISSING: "LG_RUNTIME_PATH_MISSING";
+    readonly AT_META_ABSENT: "AT_META_ABSENT";
+    readonly AT_META_TYPE_INVALID: "AT_META_TYPE_INVALID";
+    readonly AT_META_PATH_MISSING: "AT_META_PATH_MISSING";
+};
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;

package/dist/error-hints.js

@@ -0,0 +1,55 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export const FILE_META_REASONS = {
+    LG_META_ABSENT: 'LG_META_ABSENT',
+    LG_RUNTIME_PATH_MISSING: 'LG_RUNTIME_PATH_MISSING',
+    AT_META_ABSENT: 'AT_META_ABSENT',
+    AT_META_TYPE_INVALID: 'AT_META_TYPE_INVALID',
+    AT_META_PATH_MISSING: 'AT_META_PATH_MISSING',
+};
+const ERROR_HINTS_BY_CODE = {
+    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
+    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
+    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
+    24052: '请求参数有误，请对照接口文档检查',
+    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
+    24056: '签名错误，检查 appSecret 是否正确',
+    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
+    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）；勿把瞬时失败说成「一定没有数据」',
+};
+/** OpenAPI 已按引擎写好的稳定文案（优先沿用，再补 AI 纪律）。 */
+function hintForOpenApiRuntimeLogMessage(apiMessage) {
+    if (/暂不支持获取当前报告的运行日志/.test(apiMessage)) {
+        return 'UE 运行日志方案有过切换：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。旧报告可试 gotonline_overview_log_export。';
+    }
+    if (/运行日志未解析|运行日志解析未完成/.test(apiMessage)) {
+        return 'Unity：该报告无可用运行日志数据（未解析或解析未完成）。旧报告可试 gotonline_overview_log_export。';
+    }
+    return null;
+}
+function hintForFileMetaReason(rawMessage, apiMessage) {
+    const fromApi = hintForOpenApiRuntimeLogMessage(apiMessage);
+    if (fromApi)
+        return fromApi;
+    if (rawMessage.includes(FILE_META_REASONS.LG_META_ABSENT) || rawMessage.includes(FILE_META_REASONS.LG_RUNTIME_PATH_MISSING)) {
+        return ('运行日志 file_meta 不可用（原因码见 rawMessage）。' +
+            'Unity：通常表示未解析/无可用日志数据；UE：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。' +
+            '旧报告可试 gotonline_overview_log_export。');
+    }
+    if (rawMessage.includes(FILE_META_REASONS.AT_META_ABSENT) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_TYPE_INVALID) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_PATH_MISSING)) {
+        return 'AT 资源 meta 不可用：可能未开启资源采集或未解析完成，勿把失败说成「一定没有资源」。';
+    }
+    return null;
+}
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export function resolveErrorHint(code, rawMessage, apiMessage) {
+    if (code === 80108) {
+        return (hintForFileMetaReason(rawMessage, apiMessage) ??
+            '文件 meta 不存在（FILE_META_NOT_EXIST）。运行日志/AT 等场景请结合接口 message 与报告引擎解释；勿臆造数据。');
+    }
+    return ERROR_HINTS_BY_CODE[code];
+}

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

@@ -1,7 +1,7 @@
 /** 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 const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES: readonly ["fps_mean", "fps_maximum", "frametime_min", "frametime_gt_40_pct", "temperature_mean", "drawcall_maximum", "android_pss_max"];
 export declare function splitIndicatorDashboards(raw: unknown): string[];
 export declare function findUnknownIndicatorDashboards(raw: unknown): string[];
 /** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */

package/dist/indicator-dashboard-keys.js

@@ -12,6 +12,7 @@ export const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES = [
     'frametime_gt_40_pct',
     'temperature_mean',
     'drawcall_maximum',
+    'android_pss_max',
 ];
 export function splitIndicatorDashboards(raw) {
     if (typeof raw !== 'string' || !raw.trim())

package/dist/server-instructions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP server instructions：客户裸问时的全局纪律（勿依赖用户粘贴规则）。
+ * 与 docs/EMPTY_STATE_CONTRACT.md 对齐。
+ */
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/server-instructions.js

@@ -0,0 +1,16 @@
+/**
+ * MCP server instructions：客户裸问时的全局纪律（勿依赖用户粘贴规则）。
+ * 与 docs/EMPTY_STATE_CONTRACT.md 对齐。
+ */
+export const SERVER_INSTRUCTIONS = [
+    '你是 UWA GOT Online OpenAPI MCP 助手。用人话查报告时遵守以下纪律：',
+    '',
+    '1. 多份候选报告：先列出备注/设备/时间，再选或先问用户；禁止静默默认却假装只有一份。',
+    '2. 没有某类报告（如 GPU/Mono）：看 list 返回的 module_available；为 false 时明确说没有并停手。禁止用 Overview 的 RenderTexture / WaitForVsync 冒充 GPU 分析。',
+    '3. 说「GPU Bound / GPU 是主要瓶颈」之前：必须先查 gotonline_gpu_bound（或看 report_diagnosis.gpuBound）。空数组 [] 只能说「未检出 Bound」，不能说主要瓶颈是 GPU。',
+    '4. 卡顿根因：优先 gotonline_overview_stack_stutter_full_tree_presign / stutter_scene_tree；禁止把 WaitForVsync 直接当根因。尖峰再查单帧树。',
+    '5. 非法面板名要纠正（fps_mean→fps_avg；android_pss_max→android_memory_pss@max）；数值带单位。PSS 优先读 pss_peak_kb/mb/frame。',
+    '6. 接口失败时说明原因：运行日志 80108 — Unity 无 LG file_meta 表示未解析、无可用日志；UE 无 meta 只能说「暂不支持获取当前报告的运行日志」（方案切换过），勿断定报告本身无日志。其它失败勿把瞬时错误说成「一定没有数据」。',
+    '',
+    '体检优先调用 report_diagnosis；细节再按 _apisUsed 深挖。对比多份报告时说明场景/时长/目标帧是否可比（见 comparability_note）。',
+].join('\n');

package/dist/server.js

@@ -8,6 +8,7 @@ import { registerCompositeTools, COMPOSITE_TOOLS, selectCompositeTools } from '.
 import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
+import { SERVER_INSTRUCTIONS } from './server-instructions.js';
 function readPackageVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -28,7 +29,7 @@ export function createServer(opts) {
         credentials: { appId: opts.appId, appSecret: opts.appSecret },
         timeoutMs: opts.timeoutMs,
     });
-    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION });
+    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION }, { instructions: SERVER_INSTRUCTIONS });
     for (const op of operations) {
         server.registerTool(toolName(op.id, opts.nameCase, opts.namePrefix), toolConfig(op), makeHandler(op, client, opts.maxRows, opts.maxChars));
     }

package/dist/tools.d.ts

@@ -32,6 +32,9 @@ export declare function annotateCurveAxes(data: unknown): unknown;
  * 自定义面板 statistic/curve 返回空 `{}` 时，优先提示面板名传错（静默失败高发）。
  */
 export declare function annotateDashboardEmptyResult(op: Operation, data: unknown, args: Record<string, unknown>): unknown;
+/** 各 GOT Online 子模块是否有报告；供模型「无 GPU 停手」。 */
+export declare function buildModuleAvailable(group: Record<string, unknown>): Record<string, boolean>;
+export declare function annotateModuleAvailable(data: unknown): unknown;
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
  * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
@@ -40,6 +43,8 @@ export declare function annotateDashboardEmptyResult(op: Operation, data: unknow
  * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
  */
 export declare function annotateProjectGroups(data: unknown): unknown;
+/** 空 Bound / 空日志列表等：补可教模型的语义，避免误判。 */
+export declare function annotateEmptyStateSemantics(op: Operation, data: unknown): unknown;
 export declare function makeHandler(op: Operation, client: UwaClient, defaultMaxRows: number, maxChars: number): (args: Record<string, unknown>) => Promise<ToolResult>;
 export declare function toolConfig(op: Operation): {
     title: string;

package/dist/tools.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { UwaApiError } from './client.js';
 import { INDICATOR_DASHBOARD_PANEL_GUIDE, versionGuideFor } from './version-guide.js';
 import { partitionIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
-import { annotateStatisticDashboard, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, } from './annotate-dashboard.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 之间，
@@ -331,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%），直接按组统计会成倍放大。
@@ -340,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();
@@ -372,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) {
@@ -407,7 +442,7 @@ 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,
@@ -415,7 +450,7 @@ export function annotateProjectGroups(data) {
         _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
             '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
-    };
+    });
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
@@ -425,6 +460,44 @@ 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 {
@@ -480,6 +553,9 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
             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)
@@ -492,10 +568,20 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
                 }
                 if (hasCurveFilter(curveFilter)) {
                     processed = filterCurveData(processed, curveFilter);
-                    processed = annotateCurveAxes(processed);
+                    if (curveFilter.returnFramesOnly) {
+                        processed = stripOuterXAxisWhenFramesOnly(processed, curveFilter);
+                    }
+                    else {
+                        processed = annotateCurveAxes(processed);
+                    }
                 }
             }
-            const data = annotateDashboardEmptyResult(op, processed, args);
+            let data = annotateDashboardEmptyResult(op, processed, args);
+            data = annotateEmptyStateSemantics(op, data);
+            const stutterGate = stutterRootCauseGate(op.id);
+            if (stutterGate && isObj(data)) {
+                data = { ...data, ...stutterGate };
+            }
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
@@ -533,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.js

@@ -17,8 +17,9 @@ export const INDICATOR_DASHBOARD_PANEL_GUIDE = [
     '  · 曲线接口（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');
 /**
@@ -115,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: [
         '【选用规则——务必先看】',
@@ -184,12 +193,15 @@ export const VERSION_GUIDE = {
     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'),

package/package.json

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