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

package/README.md

@@ -78,7 +78,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 +191,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 +198,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,34 @@
+/**
+ * 自定义面板 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;
+export declare function isIndicatorStatisticDashboard(opPath: string): boolean;
+export declare function isIndicatorCurveDashboard(opPath: string): boolean;
+/** 统计面板成功返回后的统一标注管线。 */
+export declare function annotateStatisticDashboard(data: unknown, accepted: string[], unknown: string[]): unknown;

package/dist/annotate-dashboard.js

@@ -0,0 +1,275 @@
+/**
+ * 自定义面板 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 侧过滤曲线点；完整曲线去掉这些参数即可。',
+    };
+}
+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');
+}
+/** 统计面板成功返回后的统一标注管线。 */
+export function annotateStatisticDashboard(data, accepted, unknown) {
+    let out = annotateSceneUnits(data);
+    out = annotateDuplicateFlatAliases(out);
+    out = annotateParamFieldMap(out);
+    if (!isObj(out))
+        return out;
+    return {
+        ...out,
+        _acceptedDashboards: accepted,
+        ...(unknown.length ? { _unknownDashboards: unknown } : {}),
+    };
+}

package/dist/composite/report-diagnosis.js

@@ -20,6 +20,25 @@ function summarizeScenes(data) {
     }
     return { keys: Object.keys(obj).slice(0, 30) };
 }
+/** list_scenes 返回起止帧；归一成 sceneIdx + sceneName + frameStart/End。 */
+function normalizeSceneList(data) {
+    const arr = Array.isArray(data)
+        ? data
+        : data && typeof data === 'object' && Array.isArray(data['scenes'])
+            ? data['scenes']
+            : [];
+    return arr.slice(0, 50).map((item, idx) => {
+        if (!item || typeof item !== 'object')
+            return { sceneIdx: idx, raw: item };
+        const o = item;
+        return {
+            sceneIdx: idx,
+            sceneName: o['sceneName'] ?? o['name'] ?? null,
+            frameStart: o['frameStart'] ?? o['startFrame'] ?? null,
+            frameEnd: o['frameEnd'] ?? o['endFrame'] ?? null,
+        };
+    });
+}
 /** brief 全量可能很长，体检只保留常见关键指标（含 Unity key 与 UE 中文 label）。 */
 function pickImportantBrief(brief) {
     const preferExact = [
@@ -68,6 +87,8 @@ export const reportDiagnosisTool = {
         '调用方不必自己判断 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；勿对每个慢帧循环拉帧树。',
+        'scenes 含 list_scenes 起止帧（sceneIdx/sceneName/frameStart/frameEnd）。',
         '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
     ].join('\n'),
     inputSchema: {
@@ -121,12 +142,30 @@ export const reportDiagnosisTool = {
                     apisUsed.push(scene.target.id);
                 }
                 else {
-                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景摘要');
+                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景统计摘要');
                 }
             }
             catch (e) {
                 limitations.push(`场景统计失败：${e instanceof Error ? e.message : String(e)}`);
             }
+            // list_scenes 补起止帧（场景统计摘要经常只有名称/索引）
+            try {
+                const keyQuery = {};
+                if (identity.dataKey)
+                    keyQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    keyQuery['recordId'] = identity.recordId;
+                const sceneList = await ctx.client.call('GET', '/openapi/v1/data/gotonline/scene/info', 'v1.0.1', keyQuery);
+                const list = normalizeSceneList(sceneList);
+                if (list.length) {
+                    scenes = { ...(scenes ?? {}), sceneCount: list.length, scenes: list };
+                    if (!apisUsed.includes('list_scenes'))
+                        apisUsed.push('list_scenes');
+                }
+            }
+            catch (e) {
+                limitations.push(`场景列表(list_scenes)失败：${e instanceof Error ? e.message : String(e)}`);
+            }
             // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
             if (view.hasResource === false) {
                 limitations.push('未开启资源采集，逐资源 Top 可能为空');

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

@@ -4,3 +4,9 @@ export declare const INDICATOR_DASHBOARD_KEYS: readonly string[];
 export declare const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES: readonly ["fps_mean", "fps_maximum", "frametime_min", "frametime_gt_40_pct", "temperature_mean", "drawcall_maximum"];
 export declare function splitIndicatorDashboards(raw: unknown): string[];
 export declare function findUnknownIndicatorDashboards(raw: unknown): string[];
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export declare function partitionIndicatorDashboards(raw: unknown): {
+    accepted: string[];
+    unknown: string[];
+    all: string[];
+};

package/dist/indicator-dashboard-keys.js

@@ -28,3 +28,22 @@ export function findUnknownIndicatorDashboards(raw) {
     const valid = new Set(INDICATOR_DASHBOARD_KEYS);
     return parts.filter((k) => !valid.has(k));
 }
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export function partitionIndicatorDashboards(raw) {
+    const all = splitIndicatorDashboards(raw);
+    const valid = new Set(INDICATOR_DASHBOARD_KEYS);
+    const accepted = [];
+    const unknown = [];
+    const seen = new Set();
+    for (const k of all) {
+        if (!valid.has(k)) {
+            unknown.push(k);
+            continue;
+        }
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        accepted.push(k);
+    }
+    return { accepted, unknown, all };
+}

package/dist/presets.js

@@ -22,9 +22,14 @@ export const PRESET_DEFAULT = [
     'list_optimization_tasks',
     'gotonline_overview_indicator_statistic_dashboard',
     'gotonline_overview_indicator_curve_dashboard',
+    'gotonline_overview_indicator_dashboard_keys',
     'gotonline_overview_memory_manage_data_report',
     'gotonline_overview_method_group_statistic',
+    'gotonline_overview_stack_id_map',
     'gotonline_overview_stack_stutter_full_presign',
+    'gotonline_overview_stack_stutter_full_tree_presign',
+    'gotonline_overview_stack_stutter_scene_tree_presign',
+    'gotonline_overview_stack_tree_frame_presign',
     // 复合工具（手写，见 src/composite/）
     'top_resources',
     'top_functions',

package/dist/tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { UwaApiError } from './client.js';
 import { INDICATOR_DASHBOARD_PANEL_GUIDE, versionGuideFor } from './version-guide.js';
-import { findUnknownIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
+import { partitionIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
+import { annotateStatisticDashboard, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, } from './annotate-dashboard.js';
 const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
 /**
  * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
@@ -86,6 +87,13 @@ function describe(op) {
     }
     return lines.join('\n');
 }
+const SERVICE_META_TYPE_ENUM = 'PA（真人真机）、GOT_ONLINE（GOT Online）、LT（本地资源检测）、AB（AssetBundle 检测）、ATP（自动化功能测试）、BR（Build 分析）';
+/** 个别接口默认 apiVersion 与上游文档「推荐值」不一致时，在 MCP 侧纠偏。 */
+function defaultApiVersionFor(op) {
+    if (op.id === 'gotonline_overview_method_group_statistic')
+        return 'v1.0.2';
+    return op.defaultApiVersion;
+}
 export function buildInputSchema(op) {
     const shape = {};
     for (const p of [...op.query, ...op.body]) {
@@ -95,30 +103,58 @@ export function buildInputSchema(op) {
             desc = [
                 desc,
                 '传参名为面板标识符：后缀 _max/_avg 等为历史命名，不表示只能取峰值或均值。',
-                `合法取值共 ${INDICATOR_DASHBOARD_KEYS.length} 个；可先调 gotonline_overview_indicator_dashboard_keys 拉全量列表。`,
+                '每个面板一次返回全部统计量，勿按 mean/max/min 拆成多个面板名。',
+                `合法取值共 ${INDICATOR_DASHBOARD_KEYS.length} 个；可先调 gotonline_overview_indicator_dashboard_keys 拉全量列表（命名含 @ 等，不可从示例归纳）。`,
                 `常见误传（非面板名）：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}。`,
                 `示例面板名：${sampleKeys.join('、')}。`,
             ].join(' ');
         }
+        if (p.name === 'serviceMetaTypeList') {
+            desc = `${desc.replace(/见下方枚举值/, '枚举如下').replace(/，$/, '')}。合法值：${SERVICE_META_TYPE_ENUM}。`;
+        }
+        if (p.name === 'stackMethodName') {
+            desc = `${desc} 响应含 _resolvedMethod 时请核对实际命中的 stackMethodId（同名会自动取耗时最大者）。`;
+        }
         const base = zodFor(p).describe(p.example ? `${desc}（示例：${p.example}）` : desc);
         shape[p.name] = p.required ? base : base.optional();
     }
     if (op.apiVersions.length > 1) {
+        const def = defaultApiVersionFor(op);
         shape['apiVersion'] = z
             .enum(op.apiVersions)
             .optional()
-            .describe(`接口版本，默认 ${op.defaultApiVersion}。不同版本的返回字段有差异，详见文档`);
+            .describe(`接口版本，默认 ${def}。不同版本的返回字段有差异，详见文档`);
     }
     if (op.returnsPresignUrl) {
+        const isHeavyTree = op.id.includes('stack_overall_tree') ||
+            op.id.includes('stack_stutter') ||
+            op.id.includes('stack_tree');
         shape['download'] = z
             .boolean()
             .optional()
-            .describe('是否自动下载并解析预签名数据，默认 true。设为 false 时只返回 dataPresignUrl');
+            .describe(isHeavyTree
+            ? '是否自动下载并解析预签名数据，默认 true。大报告堆栈树建议 download=false，只取 dataPresignUrl 自行处理，避免撑爆上下文'
+            : '是否自动下载并解析预签名数据，默认 true。设为 false 时只返回 dataPresignUrl');
         shape['maxRows'] = z
             .number()
             .optional()
             .describe('可选的条目数上限。默认返回全部数据，只有在明确只需要前 N 条时才传这个参数');
     }
+    if (isIndicatorCurveDashboard(op.path)) {
+        shape['valueGt'] = z
+            .number()
+            .optional()
+            .describe('MCP 侧过滤：只保留数值 > 该阈值的曲线点（例：帧耗时慢帧传 40，单位与曲线一致多为 ms）');
+        shape['valueLt'] = z.number().optional().describe('MCP 侧过滤：只保留数值 < 该阈值的曲线点');
+        shape['topN'] = z
+            .number()
+            .optional()
+            .describe('MCP 侧过滤：在阈值过滤后按数值降序只保留最大的 N 个点');
+        shape['returnFramesOnly'] = z
+            .boolean()
+            .optional()
+            .describe('MCP 侧：为 true 时每条曲线只返回 frames[] + values[]，进一步压缩体积');
+    }
     return shape;
 }
 /** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
@@ -278,7 +314,7 @@ export function annotateDashboardEmptyResult(op, data, args) {
     const emptyColumns = !Array.isArray(columns) || columns.length === 0;
     if (!emptyStat && !emptyColumns)
         return data;
-    const unknown = findUnknownIndicatorDashboards(requested);
+    const { unknown } = partitionIndicatorDashboards(requested);
     const hintParts = [
         'indicatorDashboards 可能传错，导致 statistic/columns 为空。',
         '面板传参名≠统计维度后缀（如 fps_mean、frametime_min 是返回字段，不是面板名）。',
@@ -376,9 +412,9 @@ export function annotateProjectGroups(data) {
         content,
         _deduplicated: true,
         _uniqueReportCount: placed,
-        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
-            '。可直接按项目组统计。',
+            '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
     };
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
@@ -392,41 +428,74 @@ function asText(value) {
 export function makeHandler(op, client, defaultMaxRows, maxChars) {
     return async (args) => {
         try {
-            const apiVersion = args['apiVersion'] ?? op.defaultApiVersion;
+            const apiVersion = args['apiVersion'] ?? defaultApiVersionFor(op);
             const wantDownload = args['download'] ?? true;
             const maxRows = args['maxRows'] ?? defaultMaxRows;
+            const { filter: curveFilter, cleaned: argsForApi } = isIndicatorCurveDashboard(op.path)
+                ? extractCurveFilterArgs(args)
+                : { filter: {}, cleaned: args };
+            let acceptedDashboards = [];
+            let unknownDashboards = [];
+            if (typeof argsForApi['indicatorDashboards'] === 'string') {
+                const part = partitionIndicatorDashboards(argsForApi['indicatorDashboards']);
+                acceptedDashboards = part.accepted;
+                unknownDashboards = part.unknown;
+                if (part.all.length && !acceptedDashboards.length) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: asText({
+                                    error: 'PARAMETERS_WRONG',
+                                    message: `indicatorDashboards 全部无法识别：${unknownDashboards.join('、')}`,
+                                    _unknownDashboards: unknownDashboards,
+                                    _acceptedDashboards: [],
+                                    _hint: `这些是面板标识符，不是统计维度后缀。` +
+                                        `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}；` +
+                                        `合法示例：fps_avg、frametime@gt_40_pct。` +
+                                        `请调 gotonline_overview_indicator_dashboard_keys 获取全量 ${INDICATOR_DASHBOARD_KEYS.length} 个合法值。`,
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (acceptedDashboards.length) {
+                    argsForApi['indicatorDashboards'] = acceptedDashboards.join(',');
+                }
+            }
             const query = {};
             for (const p of op.query)
-                if (args[p.name] !== undefined)
-                    query[p.name] = args[p.name];
+                if (argsForApi[p.name] !== undefined)
+                    query[p.name] = argsForApi[p.name];
             let body;
             if (op.body.length) {
                 body = {};
                 for (const p of op.body)
-                    if (args[p.name] !== undefined)
-                        body[p.name] = args[p.name];
+                    if (argsForApi[p.name] !== undefined)
+                        body[p.name] = argsForApi[p.name];
             }
             const raw = await client.call(op.method, op.path, apiVersion, query, body);
-            const unknownDashboards = findUnknownIndicatorDashboards(args['indicatorDashboards']);
-            if (unknownDashboards.length) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: asText({
-                                error: 'PARAMETERS_WRONG',
-                                message: `indicatorDashboards 含未知面板名：${unknownDashboards.join('、')}`,
-                                _hint: `这些是面板标识符，不是统计维度后缀。` +
-                                    `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}；` +
-                                    `合法示例：fps_avg、frametime@gt_40_pct。` +
-                                    `请调 gotonline_overview_indicator_dashboard_keys 获取全量 ${INDICATOR_DASHBOARD_KEYS.length} 个合法值。`,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
+            let processed = annotateProjectGroups(annotateCurveAxes(raw));
+            if (isIndicatorStatisticDashboard(op.path) && acceptedDashboards.length) {
+                processed = annotateStatisticDashboard(processed, acceptedDashboards, unknownDashboards);
+            }
+            else if (isIndicatorCurveDashboard(op.path)) {
+                if (acceptedDashboards.length || unknownDashboards.length) {
+                    processed = isObj(processed)
+                        ? {
+                            ...processed,
+                            _acceptedDashboards: acceptedDashboards,
+                            ...(unknownDashboards.length ? { _unknownDashboards: unknownDashboards } : {}),
+                        }
+                        : processed;
+                }
+                if (hasCurveFilter(curveFilter)) {
+                    processed = filterCurveData(processed, curveFilter);
+                    processed = annotateCurveAxes(processed);
+                }
             }
-            const data = annotateDashboardEmptyResult(op, annotateProjectGroups(annotateCurveAxes(raw)), args);
+            const data = annotateDashboardEmptyResult(op, processed, args);
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;

package/dist/version-guide.d.ts

@@ -9,6 +9,11 @@
  * 挂到所有带 indicatorDashboards 的工具 description，避免模型见 _max 只读峰值。
  */
 export declare const INDICATOR_DASHBOARD_PANEL_GUIDE: string;
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >40ms 帧循环拉指定帧树再聚类」。
+ */
+export declare const STACK_ANALYSIS_GUIDE: string;
 /** 写入工具 description 的「选用规则」块，key 为 operation id。 */
 export declare const VERSION_GUIDE: Record<string, string>;
 export declare function versionGuideFor(opId: string): string | undefined;

package/dist/version-guide.js

@@ -11,14 +11,34 @@
 export const INDICATOR_DASHBOARD_PANEL_GUIDE = [
     '【indicatorDashboards 传参名称——勿按后缀猜统计维度】',
     '- 传参名（如 temperature_max、fps_avg、drawcall_cnt_max）是**面板标识符**，_max / _avg / @max 等为历史命名，**不限制**返回 mean / maximum / min 等统计类型。',
+    '- 【返回粒度】每个面板一次返回其下所有子指标的全部统计量（mean / min / maximum / maximum_frame / 专属指标，以及 scene_*），',
+    '  无需也无法按统计量拆成多个面板名（勿传 fps_mean、fps_max、fps_min）。面板→子指标展开见返回体 group；入参→出参映射见 _paramFieldMap。',
     '- 例：temperature_max 面板含子指标 temperature、android_temper_cpu、android_temper_gpu、android_temper_battery；',
     '  · 曲线接口（indicator_curve / custom_dashboard）→ 各子指标逐帧曲线；',
     '  · 统计 2.0（indicator_statistic_dashboard）→ statistic 下 *_mean / *_maximum / *_min 及 scene_* 等全量统计。',
     '- 查温度曲线/均值/峰值：Unity Overview 且 SDK ≥ 2.5.1 时传 indicatorDashboards=temperature_max，再读 y_axis 或 statistic；勿仅看 get_overview_statistic 的汇总段。',
-    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys；勿传 fps_mean、frametime_min 等统计字段名。',
-    '- 误传示例：fps_mean、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、frametime@gt_40_pct。',
+    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys（全量枚举）；勿传 fps_mean、frametime_min 等统计字段名。',
+    '- 误传示例：fps_mean、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、frametime@gt_40_pct（注意 @ 与阈值不可瞎猜）。',
     '- UE Overview 当前 Open API 未开放 custom/indicator dashboard 路径（会 24052），UE 温度汇总见 get_ue_overview_statistic_v2 的 temperature 段。',
 ].join('\n');
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >40ms 帧循环拉指定帧树再聚类」。
+ */
+export const STACK_ANALYSIS_GUIDE = [
+    '【堆栈/卡顿选用——务必先看】',
+    '- 卡顿根因主路径：用**卡顿聚合树**（已合并全部/场景内卡顿帧），不要对每个慢帧循环拉指定帧树。',
+    '- 工具分工：',
+    '  · gotonline_overview_stack_stutter_full_presign → 卡顿帧列表（哪些帧卡、类型耗时拆分）',
+    '  · gotonline_overview_stack_stutter_full_tree_presign → **全部卡顿帧合并后的堆栈树**（全报告卡顿共性根因）',
+    '  · gotonline_overview_stack_stutter_scene_tree_presign → **指定场景内卡顿帧合并树**（主玩法段）',
+    '  · gotonline_overview_stack_tree_frame_presign → **单帧**完整树（仅尖峰深挖，如已知 frameId=8439）',
+    '  · gotonline_overview_stack_overall_tree_presign → 整线程全量堆栈（非卡顿专用；看持续税/全局热点）',
+    '  · gotonline_overview_stack_sample_frame_presign → 树结点逐帧曲线',
+    '- 慢帧占比/挑代表帧：indicator 面板 frametime@gt_40_pct（统计或 curve+valueGt）；根因归因仍走卡顿聚合树。',
+    '- 读任何堆栈树前必须配合 gotonline_overview_stack_id_map（树里是 methodId）。',
+    '- 错误假设：❌「没有批量帧树就无法做卡顿根因」——总体/场景卡顿树就是合并结果。',
+].join('\n');
 /** 写入工具 description 的「选用规则」块，key 为 operation id。 */
 export const VERSION_GUIDE = {
     get_overview_statistic_v1: [
@@ -61,7 +81,8 @@ export const VERSION_GUIDE = {
         '- 自定义面板统计 2.0。需 SDK ≥ 2.5.1，支持 GPU 指标，最多 15 个面板。',
         '- 旧接口（抽帧、无 GPU）见 gotonline_overview_custom_dashboard。',
         '- 只要逐帧曲线不要统计值时用 gotonline_overview_indicator_curve_dashboard。',
-        '- 返回 statistic 为空时优先怀疑 indicatorDashboards 传错；响应可能含 _hint。',
+        '- 返回 statistic 为空时优先怀疑 indicatorDashboards 传错；响应可能含 _hint / _unknownDashboards。',
+        '- 响应可能含 _paramFieldMap（入参面板→出参字段）、_duplicateFlatAliases、_sceneUnitNote（scene_* 补单位标注）。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_overview_indicator_curve_dashboard: [
@@ -71,6 +92,8 @@ export const VERSION_GUIDE = {
         '- 【横轴——勿混用】外层 x_axis 为逐帧共享横轴（1、2、3…）；y_axis.{指标名}.x_axis 为该曲线专属横轴（常见步长 30：0、30、60…）。',
         '- 读取某条曲线时：若存在专属 x_axis 必须用专属，否则才用外层共享 x_axis。把共享横轴套到 FPS 等专属曲线会错位。',
         '- 响应另含 _axisBinding / _axisHint，按其中 xAxisSource 取值即可。',
+        '- 【过滤——MCP 侧】可选 valueGt / valueLt / topN / returnFramesOnly：只返回超阈值或 TopN 点，适合慢帧列表（例：frametime@gt_40_pct + valueGt=40）。',
+        '- 慢帧列表 ≠ 卡顿根因：根因请用 stutter_full_tree / stutter_scene_tree（卡顿帧已合并），不要对 valueGt 结果逐帧拉 stack_tree_frame。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_gpu_curve: [
@@ -105,8 +128,10 @@ export const VERSION_GUIDE = {
     ].join('\n'),
     gotonline_overview_method_group_statistic: [
         '【选用规则——务必先看】',
-        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25，且 api 版本须 v1.0.2）。',
+        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25）。',
+        '- **MCP 默认 apiVersion=v1.0.2**（勿用 v1.0.1，会参数错误）。需要旧行为时显式传 apiVersion=v1.0.1。',
         '- UE 旧报告请用 gotonline_overview_group_export。',
+        '- 未配置自定义函数组时 data=[]；Overview 热点函数曲线优先用 method_idmap_statistic + method_curve_presign，不必依赖函数组。',
     ].join('\n'),
     gotonline_overview_method_idmap_statistic: [
         '【选用规则——务必先看】',
@@ -139,6 +164,47 @@ export const VERSION_GUIDE = {
         '- 合法示例：fps_avg、drawcall_cnt_max、frametime@gt_40_pct、temperature_max。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
+    gotonline_overview_stack_id_map: [
+        '【选用规则——务必先看】',
+        '- 函数 ID ↔ 名称映射。解析任何 stack_*_tree / stutter_*_tree 前先调本工具。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_overall_tree_presign: [
+        '【选用规则——务必先看】',
+        '- 指定线程的**全量**调用堆栈树（含非卡顿帧），适合持续税/全局热点。',
+        '- 只要卡顿根因：改用 stutter_full_tree / stutter_scene_tree，勿用本接口代替卡顿聚合。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_presign: [
+        '【选用规则——务必先看】',
+        '- 卡顿**帧列表**（帧号 + 卡顿类型耗时拆分），不是堆栈树。',
+        '- 要卡顿根因堆栈：接着调 stutter_full_tree_presign（或场景版 stutter_scene_tree）。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **全部卡顿帧已合并**的调用堆栈树 = 卡顿根因主入口（服务端聚合，无需客户端逐帧拉树再聚类）。',
+        '- 只要某一场景：用 stutter_scene_tree；只要某一尖峰帧细节：再用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_scene_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **指定场景内卡顿帧已合并**的堆栈树；sceneIndex 来自 list_scenes 下标。',
+        '- 全报告卡顿用 stutter_full_tree；单帧深挖用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_tree_frame_presign: [
+        '【选用规则——务必先看】',
+        '- **单帧**完整堆栈树（frameId 必填）。用于已知尖峰帧深挖，不是卡顿分析的第一步。',
+        '- 卡顿共性根因请先用 stutter_full_tree / stutter_scene_tree（已是多帧合并结果）。',
+        '- ❌ 不要对 frametime valueGt 筛出的每个慢帧循环调用本工具来「聚类」。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_sample_frame_presign: [
+        '【选用规则——务必先看】',
+        '- 堆栈树某个结点的逐帧曲线；结点 id 来自树文件。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
 };
 export function versionGuideFor(opId) {
     return VERSION_GUIDE[opId];

package/package.json

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

package/spec/uwa-openapi.json

@@ -3631,7 +3631,7 @@
         "v1.0.1",
         "v1.0.2"
       ],
-      "defaultApiVersion": "v1.0.1",
+      "defaultApiVersion": "v1.0.2",
       "query": [
         {
           "name": "recordId",