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

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/cli.js

@@ -6,6 +6,7 @@ import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './co
 import { filterKeys, selectOperations } from './presets.js';
 import { DEFAULT_MAX_CHARS, DEFAULT_MAX_ROWS, toolName } from './tools.js';
 import { PACKAGE_VERSION, startStdio } from './server.js';
+import { checkForUpdate, describeReleaseChannel, formatUpdateNotice } from './version-check.js';
 const DEFAULT_BASE_URL = 'https://secure-api.uwa4d.com';
 const SANDBOX_BASE_URL = 'https://sandbox-api.uwa4d.com';
 function splitList(value) {
@@ -133,6 +134,16 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
+        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${describeReleaseChannel(PACKAGE_VERSION).releaseLabel}）`);
+        if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+            const update = await checkForUpdate(PACKAGE_VERSION);
+            if (update) {
+                console.log(formatUpdateNotice(update));
+            }
+            else {
+                console.log('已是最新同 release 线版本（或暂时无法连接 npm registry）。');
+            }
+        }
         console.log('\n可以按 README 配置 MCP 客户端了。');
     }
     catch (err) {

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/index.js

@@ -2,8 +2,10 @@ import { toolName } from '../tools.js';
 import { topResourcesTool } from './top-resources.js';
 import { topFunctionsTool } from './top-functions.js';
 import { reportDiagnosisTool } from './report-diagnosis.js';
+import { mcpVersionTool } from './mcp-version.js';
 /** 全部手写复合工具（不进 uwa-openapi.json）。 */
 export const COMPOSITE_TOOLS = [
+    mcpVersionTool,
     topResourcesTool,
     topFunctionsTool,
     reportDiagnosisTool,

package/dist/composite/mcp-version.d.ts

@@ -0,0 +1,2 @@
+import type { CompositeTool } from './types.js';
+export declare const mcpVersionTool: CompositeTool;

package/dist/composite/mcp-version.js

@@ -0,0 +1,48 @@
+import { PACKAGE_VERSION } from '../package-version.js';
+import { buildMcpVersionInfo, describeReleaseChannel } from '../version-check.js';
+import { errorResult, jsonToolResult } from './helpers.js';
+const release = describeReleaseChannel(PACKAGE_VERSION);
+const STABLE_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 正式版版本，并与 npm 最新稳定版对比（仅正式版↔正式版，不与内部测试版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告客户重启 MCP 升级；已是最新勿打扰。',
+    '不要臆测版本号。',
+].join('\n');
+const INTERNAL_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 内部测试版版本，并与 npm @beta 最新测试版对比（仅测试↔测试，不与正式版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey｜仅 UWA 内部 sandbox 联调',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告测试人员重启 MCP 升级；已是最新勿打扰。',
+    '不要臆测版本号。',
+].join('\n');
+export const mcpVersionTool = {
+    id: 'uwa_mcp_version',
+    title: release.releaseLine === 'stable' ? 'MCP 正式版与升级提示' : 'MCP 内部测试版与升级提示',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['uwa_mcp_version', 'composite', 'preset.default', 'common'],
+    description: release.releaseLine === 'stable' ? STABLE_DESCRIPTION : INTERNAL_DESCRIPTION,
+    inputSchema: {},
+    async handler(_args, ctx) {
+        try {
+            if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] === '1') {
+                return jsonToolResult({
+                    package: '@uwa4d/openapi-mcp',
+                    currentVersion: PACKAGE_VERSION,
+                    releaseLine: release.releaseLine,
+                    releaseLabel: release.releaseLabel,
+                    updateCheckSkipped: true,
+                    userNotice: `当前 MCP ${release.releaseLabel} ${PACKAGE_VERSION}（已设置 UWA_MCP_SKIP_UPDATE_CHECK，未核对 npm 最新版）。`,
+                }, ctx.maxChars);
+            }
+            const info = await buildMcpVersionInfo(PACKAGE_VERSION);
+            return jsonToolResult({
+                ...info,
+                suggestTellUser: info.updateAvailable,
+            }, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

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/composite/top-resources.js

@@ -1,3 +1,4 @@
+import { withRateLimitAnnotation } from '../error-hints.js';
 import { z } from './types.js';
 import { errorResult, isObj, jsonToolResult, requireReportKey, topNOf, } from './helpers.js';
 import { fetchOverviewStatistic, fetchReportIdentity, preferAtResourceTable, } from './route-overview.js';
@@ -193,26 +194,24 @@ export async function runTopResources(client, args) {
     apisUsed.push(...fetched.apisUsed);
     if (fetched.items.length === 0) {
         const fallbackItems = typeLevelFromOverview(view);
-        return packResult(fallbackItems, {
+        return packResult(fallbackItems, withRateLimitAnnotation({
             _sourceKind: fetched.sourceKind,
             _apisUsed: apisUsed,
-            ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
             _note: fallbackItems.length > 0
                 ? '逐资源列表为空，已回退为 Overview 类型级峰值。'
                 : '逐资源列表与类型级峰值均为空（报告可能未采集资源内存）。',
             _limitations: ['per_asset_empty'],
-        });
+        }, fetched.errors.length ? fetched.errors : undefined));
     }
     const note = groupBy === 'assetType'
         ? `已按类型各取 Top ${topN}（${fetched.sourceKind}，共 ${assetTypes.length} 种）。`
         : `已按内存峰值合并 ${assetTypes.length} 种资源类型（${fetched.sourceKind}），返回全局 Top ${topN}。`;
-    return packResult(fetched.items, {
+    return packResult(fetched.items, withRateLimitAnnotation({
         totalCandidates: fetched.items.length,
         _sourceKind: fetched.sourceKind,
         _apisUsed: apisUsed,
-        ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
         _note: note,
-    });
+    }, fetched.errors.length ? fetched.errors : undefined));
 }
 function normalizeAssetTypes(raw) {
     if (Array.isArray(raw) && raw.length)
@@ -236,6 +235,7 @@ export const topResourcesTool = {
         'Unity / UE 均优先走 AT 资源总览预签名（at/resource/overall/table/presign），按 assetType 并行下载后合并排序。',
         'groupBy=merged（默认）：跨类型合并后取全局 Top N；groupBy=assetType：每种类型各取 Top N，返回 byType。',
         'Unity 旧报告（解析日 < 2026-06-25）回退 memory/manage；拉不到逐资源时再回退 Overview 类型级峰值。',
+        '内部按 assetType 并行请求，易触发 OpenAPI 限流 31004（UWA 服务端保护，预期行为）。遇限流见 _rateLimitHint：可缩小 assetTypes、稍等重试；部分类型限流时已有 Top 仍可用。',
         '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
     ].join('\n'),
     inputSchema: {

package/dist/error-hints.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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";
+};
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export declare const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export declare const RATE_LIMIT_HINT: string;
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export declare function isRateLimitMessage(text: string): boolean;
+/** _partialErrors 中是否有限流项。 */
+export declare function hasRateLimitInPartialErrors(errors: string[]): boolean;
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export declare function withRateLimitAnnotation(extra: Record<string, unknown>, partialErrors?: string[]): Record<string, unknown>;
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;