@uwa4d/openapi-mcp 0.2.0-beta.0 → 0.2.0-beta.10

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` | |
@@ -107,6 +173,9 @@ npx -y @uwa4d/openapi-mcp check -a <app_id> -s <app_secret>
 # 组合：默认集 + 所有预签名类接口 + 单个指定工具
 -t preset.default,presign,gotonline_overview_stack_id_map
 
+# 只要复合工具（报告体检 / Top 资源 / Top 函数）
+-t composite
+
 # 只做 Unity 项目，砍掉 UE 专用工具
 -t preset.default -e unity
 ```
@@ -118,6 +187,18 @@ npx -y @uwa4d/openapi-mcp list-tools
 npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 ```
 
+## 复合工具
+
+默认 preset 里除了原子接口，还有三个**复合工具**——内部会串多个接口并聚合，适合对话式提问：
+
+| 工具 | 做什么 |
+| --- | --- |
+| `report_diagnosis` | 单份报告体检：自动选对统计 v1/v2，附带 Top 资源/函数与场景摘要 |
+| `top_resources` | 资源内存 Top N（默认 11 种类型；`groupBy=merged` 全局 Top / `assetType` 按类型各 Top） |
+| `top_functions` | 函数 Top N：下载堆栈树 + idmap，按函数名合并同名节点后再排序 |
+
+不确定该调统计 1.0 还是 2.0 时，优先用这三个，不必自己判断日期和 SDK。
+
 ## 大数据接口的返回方式
 
 堆栈树、资源列表、卡顿帧等接口不直接返回数据，而是返回一个有效期 600 秒的预签名下载地址。
@@ -128,7 +209,15 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 - `_totalItems` — 主数据列表的条目总数
 - `_returnedChars` — 实际返回的字符数
 
-只在明确只要前 N 条时才传 `maxRows`。另有一道字符数兜底闸门（`--max-chars`，默认 50 万字符），正常报告不会触发；一旦触发会在 `_truncated` 里说清楚，此时可以用 `download: false` 取回 `dataPresignUrl` 自行下载完整文件。
+只在明确只要前 N 条时才传 `maxRows`。
+
+## 返回体积控制
+
+`--max-chars`（默认 50 万字符）对**所有**工具生效，不只是上面这类下载型接口。批量统计、报告列表这类接口一次查十几份报告就可能产生二十万字符以上的返回，容易撑爆模型上下文。
+
+超限时不会粗暴截断字符串——那样会切出无法解析的 JSON——而是按条目缩减，保证返回始终是完整合法的结构，并在 `_truncated` 里说明缩减到了多少条、该怎么拿到剩下的（分页或缩小批量）。
+
+如果你的客户端对单次工具输出有更严格的限制，把 `--max-chars` 调小即可。
 
 ## 曲线接口的双横轴
 
@@ -169,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` 标签下，默认写法不会拉到测试版。
 
 ## 常见问题
 
@@ -179,10 +265,20 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 检查 Node 版本是否 ≥ 18，以及配置文件 JSON 格式是否正确（多一个逗号就会整个失效）。改完配置需要重启客户端。
 
 **提示凭证错误**
-用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。注意测试环境和生产环境的凭证不通用。
+用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。确认 AppId / AppSecret 无误且未过期。
+
+**返回「数据服务错误」或不确定该用 v1 还是 v2**
+
+部分接口按报告解析/提交日期和引擎区分版本：
+
+| 场景 | 用哪个 |
+| --- | --- |
+| Unity Overview，解析日 **&lt; 2026-07-09** | `get_overview_statistic_v1` |
+| Unity Overview，解析日 **≥ 2026-07-09** 且 SDK ≥ 2.5.1 | `get_overview_statistic_v2` |
+| UE Overview，提交日 **≤ 2026-03-25** | `get_overview_statistic_v1` |
+| UE Overview，提交日 **&gt; 2026-03-25** | `get_ue_overview_statistic_v2` |
 
-**返回「数据服务错误」**
-部分接口区分报告生成时间和引擎类型，例如 Unity 2026-07-09 之前的报告用 `get_overview_statistic_v1`，之后的用 `get_overview_statistic_v2`。工具描述里注明了适用范围。
+场景统计、运行日志、快照帧等也有类似 1.0/2.0 成对工具，描述开头有「选用规则」。不确定时直接用复合工具 `report_diagnosis` / `top_functions`，内部会按报告详情自动路由。
 
 ## 许可
 

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 } : {}),
+    };
+}