@uwa4d/openapi-mcp 0.2.0-beta.1 → 0.2.0-beta.11

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 秒的预签名下载地址。
@@ -177,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` 标签下，默认写法不会拉到测试版。
 
 ## 常见问题
 
@@ -187,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 } : {}),
+    };
+}

package/dist/cli.js

@@ -2,9 +2,11 @@
 import { Command, Option } from 'commander';
 import { UwaClient } from './client.js';
 import { loadSpec } from './spec.js';
+import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './composite/index.js';
 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, formatUpdateNotice, resolveUpdateChannel } 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) {
@@ -70,10 +72,10 @@ program
     .option('--spec <path>', '自定义 spec 文件路径')
     .action((opts) => {
     const spec = loadSpec(opts.spec);
-    const selected = new Set(selectOperations(spec.operations, {
-        tools: opts.tool ?? ['all'],
-        engine: opts.engine,
-    }).map((o) => o.id));
+    const toolFilter = opts.tool ?? ['all'];
+    const engine = opts.engine;
+    const selected = new Set(selectOperations(spec.operations, { tools: toolFilter, engine }).map((o) => o.id));
+    const selectedComposite = new Set(selectCompositeTools({ tools: toolFilter, engine }).map((t) => t.id));
     const byModule = new Map();
     for (const op of spec.operations) {
         const key = op.modules.join(',');
@@ -89,8 +91,19 @@ program
             console.log(`${mark} ${toolName(op.id, 'snake', '').padEnd(52)} ${op.method.padEnd(4)} ${engines.padEnd(7)} ${op.name}`);
         }
     }
-    console.log(`\n共 ${spec.operations.length} 个工具，当前条件选中 ${selected.size} 个（* 标记）`);
-    console.log(`可用过滤键：${[...new Set(spec.operations.flatMap(filterKeys))].sort().join(', ')}`);
+    console.log('\n## composite（手写复合工具）');
+    for (const t of COMPOSITE_TOOLS) {
+        const mark = selectedComposite.has(t.id) ? '*' : ' ';
+        const engines = t.engines.map((e) => (e === 'unity' ? 'U3D' : 'UE')).join('+');
+        console.log(`${mark} ${toolName(t.id, 'snake', '').padEnd(52)} CMP  ${engines.padEnd(7)} ${t.title}`);
+    }
+    const total = spec.operations.length + COMPOSITE_TOOLS.length;
+    const selectedCount = selected.size + selectedComposite.size;
+    console.log(`\n共 ${total} 个工具（原子 ${spec.operations.length} + 复合 ${COMPOSITE_TOOLS.length}），当前条件选中 ${selectedCount} 个（* 标记）`);
+    const keys = [
+        ...new Set([...spec.operations.flatMap(filterKeys), ...compositeFilterKeys()]),
+    ].sort();
+    console.log(`可用过滤键：${keys.join(', ')}`);
 });
 program
     .command('check')
@@ -121,6 +134,16 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
+        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${resolveUpdateChannel(PACKAGE_VERSION)} 通道）`);
+        if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+            const update = await checkForUpdate(PACKAGE_VERSION);
+            if (update) {
+                console.log(formatUpdateNotice(update));
+            }
+            else {
+                console.log('已是最新同通道版本（或暂时无法连接 npm registry）。');
+            }
+        }
         console.log('\n可以按 README 配置 MCP 客户端了。');
     }
     catch (err) {