@uwa4d/openapi-mcp 0.2.0-beta.7 → 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 输出日志里的完整报错留给支持同学。
+
 ### 先验证一下
 
 配置前可以在终端确认凭证和网络是否通：
@@ -78,7 +145,6 @@ npx -y @uwa4d/openapi-mcp check -a <app_id> -s <app_secret>
 | `--app-id` | `-a` | AppId | `UWA_MCP_APP_ID` |
 | `--app-secret` | `-s` | AppSecret | `UWA_MCP_APP_SECRET` |
 | `--base-url` | `-b` | 接口地址，默认 `https://secure-api.uwa4d.com` | `UWA_MCP_API_BASE_URL` |
-| `--sandbox` | | 切到测试环境 `https://sandbox-api.uwa4d.com` | |
 | `--tool` | `-t` | 加载哪些工具，逗号分隔，默认 `preset.default` | `UWA_MCP_TOOL` |
 | `--engine` | `-e` | 只加载适用于 `unity` / `unreal` 的工具，默认 `all` | `UWA_MCP_ENGINE` |
 | `--tool-name-case` | `-c` | 工具命名风格 `snake` / `camel`，默认 `snake` | |
@@ -192,9 +258,6 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 | --- | --- | --- |
 | `@uwa4d/openapi-mcp` | 跟随最新稳定版，自动升级 | 默认，大多数用户 |
 | `@uwa4d/openapi-mcp@0.1.0` | 锁死某个版本 | 生产流水线，要求完全可复现 |
-| `@uwa4d/openapi-mcp@beta` | 跟随测试版 | 配合 UWA 验证新接口 |
-
-测试版只发布在 `beta` 标签下，默认写法不会拉到测试版。
 
 ## 常见问题
 
@@ -202,7 +265,7 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 检查 Node 版本是否 ≥ 18，以及配置文件 JSON 格式是否正确（多一个逗号就会整个失效）。改完配置需要重启客户端。
 
 **提示凭证错误**
-用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。注意测试环境和生产环境的凭证不通用。
+用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。确认 AppId / AppSecret 无误且未过期。
 
 **返回「数据服务错误」或不确定该用 v1 还是 v2**
 

package/dist/annotate-dashboard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 自定义面板 statistic / curve 返回体的 Agent 友好标注与过滤。
+ * 不改上游 Open API，只在 MCP wrapper 层消歧、降噪、提效。
+ */
+/**
+ * 上游嵌套 mean/maximum/min 与扁平别名已统一为同一单位（如 frametime=ms）。
+ * 这里只给仍无单位标注的 scene_* 裸数组补 unit/data，便于模型直接读，不改数值。
+ */
+export declare function annotateSceneUnits(data: unknown): unknown;
+/**
+ * 标明扁平别名与嵌套 scene_* 的重复关系，便于模型只读一份。
+ */
+export declare function annotateDuplicateFlatAliases(data: unknown): unknown;
+/** 从 columns / group 生成入参面板名 → 出参字段映射，便于模型自检。 */
+export declare function annotateParamFieldMap(data: unknown): unknown;
+export interface CurveFilterOptions {
+    valueGt?: number;
+    valueLt?: number;
+    topN?: number;
+    returnFramesOnly?: boolean;
+}
+export declare function extractCurveFilterArgs(args: Record<string, unknown>): {
+    filter: CurveFilterOptions;
+    cleaned: Record<string, unknown>;
+};
+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

@@ -0,0 +1,413 @@
+/**
+ * 自定义面板 statistic / curve 返回体的 Agent 友好标注与过滤。
+ * 不改上游 Open API，只在 MCP wrapper 层消歧、降噪、提效。
+ */
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isUnitObj(v) {
+    return isObj(v) && ('unit' in v || 'value' in v || 'data' in v);
+}
+/**
+ * 上游嵌套 mean/maximum/min 与扁平别名已统一为同一单位（如 frametime=ms）。
+ * 这里只给仍无单位标注的 scene_* 裸数组补 unit/data，便于模型直接读，不改数值。
+ */
+export function annotateSceneUnits(data) {
+    if (!isObj(data) || !isObj(data['statistic']))
+        return data;
+    const statistic = { ...data['statistic'] };
+    const notes = [];
+    for (const [key, raw] of Object.entries(statistic)) {
+        if (!isObj(raw))
+            continue;
+        // 扁平别名 { unit, data } 跳过；只处理嵌套子指标对象
+        if (Array.isArray(raw['data']) && isObj(raw['unit']) && raw['mean'] === undefined)
+            continue;
+        const metric = { ...raw };
+        let changed = false;
+        const sceneUnit = isUnitObj(metric['mean']) && isObj(metric['mean'].unit) ? metric['mean'].unit : null;
+        for (const [sk, sv] of Object.entries(metric)) {
+            if (!sk.startsWith('scene_') || !Array.isArray(sv))
+                continue;
+            if (isObj(sv[0]) && 'unit' in sv[0])
+                continue;
+            if (sk.endsWith('_frame') || sk.includes('max_frame')) {
+                metric[sk] = { unit: { description: '帧', value: 'frame' }, data: sv };
+            }
+            else if (sk.includes('pct') || sk.includes('rate')) {
+                metric[sk] = { unit: { description: '百分比', value: 'percentage' }, data: sv };
+            }
+            else if (sk.includes('per_min')) {
+                metric[sk] = { unit: { description: '次/分钟', value: 'times/min' }, data: sv };
+            }
+            else if (sceneUnit) {
+                metric[sk] = { unit: sceneUnit, data: sv };
+            }
+            else {
+                continue;
+            }
+            changed = true;
+        }
+        if (changed) {
+            statistic[key] = metric;
+            notes.push(key);
+        }
+    }
+    if (!notes.length)
+        return data;
+    return {
+        ...data,
+        statistic,
+        _sceneUnitNote: `已为子指标 [${notes.join(', ')}] 的 scene_* 裸数组补上 unit（与嵌套 mean.unit 对齐）；数值未改动。`,
+    };
+}
+/**
+ * 标明扁平别名与嵌套 scene_* 的重复关系，便于模型只读一份。
+ */
+export function annotateDuplicateFlatAliases(data) {
+    if (!isObj(data) || !isObj(data['statistic']))
+        return data;
+    const statistic = data['statistic'];
+    const dups = [];
+    for (const [flatKey, flatVal] of Object.entries(statistic)) {
+        if (!isObj(flatVal) || !Array.isArray(flatVal['data']))
+            continue;
+        const m = /^(.+)_(mean|min|maximum|maximum_frame|gt_40_ms_frame_pct|jank_time_pct|jank_frames_per_min|bigjank_frames_per_min)$/.exec(flatKey);
+        if (!m)
+            continue;
+        const indicator = m[1];
+        const kind = m[2];
+        const nested = statistic[indicator];
+        if (!isObj(nested))
+            continue;
+        const sceneKey = kind === 'mean'
+            ? 'scene_mean'
+            : kind === 'min'
+                ? 'scene_min'
+                : kind === 'maximum'
+                    ? 'scene_max'
+                    : kind === 'maximum_frame'
+                        ? 'scene_max_frame'
+                        : `scene_${kind}`;
+        const sceneVal = nested[sceneKey];
+        const sceneArr = Array.isArray(sceneVal)
+            ? sceneVal
+            : isObj(sceneVal) && Array.isArray(sceneVal['data'])
+                ? sceneVal['data']
+                : null;
+        if (!sceneArr)
+            continue;
+        const flatArr = flatVal['data'];
+        if (flatArr.length === sceneArr.length && flatArr.every((v, i) => v === sceneArr[i])) {
+            dups.push(`${flatKey} ≡ ${indicator}.${sceneKey}`);
+        }
+    }
+    if (!dups.length)
+        return data;
+    return {
+        ...data,
+        _duplicateFlatAliases: dups,
+        _duplicateNote: '扁平别名与嵌套 scene_* 数值相同，读嵌套结构即可，扁平 key 为兼容别名。',
+    };
+}
+/** 从 columns / group 生成入参面板名 → 出参字段映射，便于模型自检。 */
+export function annotateParamFieldMap(data) {
+    if (!isObj(data))
+        return data;
+    const columns = data['columns'];
+    const group = data['group'];
+    if (!Array.isArray(columns) && !Array.isArray(group))
+        return data;
+    const map = {};
+    if (Array.isArray(group)) {
+        for (const row of group) {
+            if (!Array.isArray(row) || row.length < 2)
+                continue;
+            const panel = String(row[0]);
+            const inds = Array.isArray(row[1]) ? row[1].map(String) : [];
+            if (!map[panel])
+                map[panel] = { indicators: [], flatKeys: [], nestedHint: [] };
+            map[panel].indicators = [...new Set([...map[panel].indicators, ...inds])];
+            for (const ind of inds) {
+                map[panel].nestedHint.push(`statistic.${ind}`);
+            }
+        }
+    }
+    if (Array.isArray(columns)) {
+        for (const col of columns) {
+            if (!isObj(col))
+                continue;
+            const panel = String(col['firstLevel'] ?? '');
+            const seconds = Array.isArray(col['secondLevel']) ? col['secondLevel'].map(String) : [];
+            if (!panel)
+                continue;
+            if (!map[panel])
+                map[panel] = { indicators: [], flatKeys: [], nestedHint: [] };
+            map[panel].flatKeys = [...new Set([...map[panel].flatKeys, ...seconds])];
+            for (const k of seconds) {
+                map[panel].nestedHint.push(`statistic.${k}`);
+            }
+        }
+    }
+    // frametime 专属：入参与出参字段名不一致
+    for (const [panel, info] of Object.entries(map)) {
+        if (info.indicators.includes('frametime') || panel.includes('frametime') || /jank/i.test(panel)) {
+            info.nestedHint.push('statistic.frametime.gt_40_ms_frame_pct', 'statistic.frametime.jank_time_pct', 'statistic.frametime.jank_frames_per_min', 'statistic.frametime.bigjank_frames_per_min');
+        }
+        info.nestedHint = [...new Set(info.nestedHint)];
+    }
+    if (!Object.keys(map).length)
+        return data;
+    return { ...data, _paramFieldMap: map };
+}
+function parseNum(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v)))
+        return Number(v);
+    return undefined;
+}
+export function extractCurveFilterArgs(args) {
+    const filter = {
+        valueGt: parseNum(args['valueGt']),
+        valueLt: parseNum(args['valueLt']),
+        topN: parseNum(args['topN']),
+        returnFramesOnly: args['returnFramesOnly'] === true,
+    };
+    const cleaned = { ...args };
+    delete cleaned['valueGt'];
+    delete cleaned['valueLt'];
+    delete cleaned['topN'];
+    delete cleaned['returnFramesOnly'];
+    return { filter, cleaned };
+}
+export function hasCurveFilter(filter) {
+    return (filter.valueGt !== undefined ||
+        filter.valueLt !== undefined ||
+        filter.topN !== undefined ||
+        filter.returnFramesOnly === true);
+}
+/**
+ * 对 y_axis 曲线做客户端过滤，解决「慢帧列表必须全量进上下文」的问题。
+ */
+export function filterCurveData(data, filter) {
+    if (!hasCurveFilter(filter) || !isObj(data) || !isObj(data['y_axis']))
+        return data;
+    const yAxis = data['y_axis'];
+    const sharedX = isObj(data['x_axis']) && Array.isArray(data['x_axis']['data']) ? data['x_axis']['data'] : null;
+    const nextY = {};
+    const filterMeta = {};
+    for (const [name, curve] of Object.entries(yAxis)) {
+        if (!isObj(curve) || !Array.isArray(curve['data'])) {
+            nextY[name] = curve;
+            continue;
+        }
+        const values = curve['data'];
+        const ownX = isObj(curve['x_axis']) && Array.isArray(curve['x_axis']['data'])
+            ? curve['x_axis']['data']
+            : sharedX;
+        const pairs = [];
+        for (let i = 0; i < values.length; i++) {
+            const v = values[i];
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                continue;
+            if (filter.valueGt !== undefined && !(v > filter.valueGt))
+                continue;
+            if (filter.valueLt !== undefined && !(v < filter.valueLt))
+                continue;
+            pairs.push({ frame: ownX?.[i] ?? i + 1, value: v, idx: i });
+        }
+        let kept = pairs;
+        if (filter.topN !== undefined && filter.topN > 0 && kept.length > filter.topN) {
+            kept = [...kept].sort((a, b) => b.value - a.value).slice(0, filter.topN);
+            kept.sort((a, b) => Number(a.frame) - Number(b.frame));
+        }
+        filterMeta[name] = {
+            originalPoints: values.length,
+            keptPoints: kept.length,
+            valueGt: filter.valueGt ?? null,
+            valueLt: filter.valueLt ?? null,
+            topN: filter.topN ?? null,
+        };
+        if (filter.returnFramesOnly) {
+            nextY[name] = {
+                unit: { description: '帧', value: 'frame' },
+                frames: kept.map((p) => p.frame),
+                values: kept.map((p) => p.value),
+            };
+        }
+        else {
+            nextY[name] = {
+                ...curve,
+                data: kept.map((p) => p.value),
+                x_axis: {
+                    unit: isObj(curve['x_axis']) ? curve['x_axis']['unit'] : { description: '帧', value: 'frame' },
+                    data: kept.map((p) => p.frame),
+                },
+            };
+        }
+    }
+    return {
+        ...data,
+        y_axis: nextY,
+        _curveFilter: filterMeta,
+        _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);
+    out = annotateDuplicateFlatAliases(out);
+    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 ?? {};
     }