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

package/dist/tools.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import { UwaApiError } from './client.js';
+import { INDICATOR_DASHBOARD_PANEL_GUIDE, versionGuideFor } from './version-guide.js';
+import { partitionIndicatorDashboards, INDICATOR_DASHBOARD_KEYS, INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES, } from './indicator-dashboard-keys.js';
+import { annotateStatisticDashboard, annotateOverviewStatisticPss, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, isOverviewStatisticOp, stutterRootCauseGate, stripOuterXAxisWhenFramesOnly, } from './annotate-dashboard.js';
 const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
 /**
  * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
@@ -36,6 +39,14 @@ function zodFor(param) {
  */
 function describe(op) {
     const lines = [op.summary || op.name];
+    // v1/v2 选用规则放在最前，避免模型淹没在长 notes 里选错接口
+    const guide = versionGuideFor(op.id);
+    if (guide)
+        lines.push(guide);
+    else if (op.query.some((p) => p.name === 'indicatorDashboards')) {
+        // 带 indicatorDashboards 但未单独写 VERSION_GUIDE 的原子工具（兜底）
+        lines.push(INDICATOR_DASHBOARD_PANEL_GUIDE);
+    }
     const engines = op.engines.map((e) => ENGINE_LABEL[e]).join(' / ');
     lines.push(`适用引擎：${engines}｜模块：${op.modules.join(',')}｜${op.method} ${op.path}`);
     const sdk = op.variants.find((v) => v.sdkRequirement)?.sdkRequirement;
@@ -76,28 +87,74 @@ 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]) {
-        const base = zodFor(p).describe(p.example ? `${p.description}（示例：${p.example}）` : p.description);
+        let desc = p.description;
+        if (p.name === 'indicatorDashboards') {
+            const sampleKeys = ['fps_avg', 'drawcall_cnt_max', 'frametime@gt_40_pct', 'temperature_max'];
+            desc = [
+                desc,
+                '传参名为面板标识符：后缀 _max/_avg 等为历史命名，不表示只能取峰值或均值。',
+                '每个面板一次返回全部统计量，勿按 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;
 }
 /** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
@@ -241,7 +298,74 @@ export function annotateCurveAxes(data) {
         _axisHint: '每条曲线按 _axisBinding[曲线名].xAxisSource 指定的横轴取值，不要统一使用外层 x_axis',
     };
 }
+/**
+ * 自定义面板 statistic/curve 返回空 `{}` 时，优先提示面板名传错（静默失败高发）。
+ */
+export function annotateDashboardEmptyResult(op, data, args) {
+    const isDashboard = op.path.includes('/indicator/statistic/dashboard') ||
+        op.path.includes('/indicator/curve/dashboard') ||
+        op.path.includes('/custom/dashboard');
+    if (!isDashboard || !isObj(data))
+        return data;
+    const requested = args['indicatorDashboards'];
+    const stat = data['statistic'];
+    const columns = data['columns'];
+    const emptyStat = stat == null || (isObj(stat) && Object.keys(stat).length === 0);
+    const emptyColumns = !Array.isArray(columns) || columns.length === 0;
+    if (!emptyStat && !emptyColumns)
+        return data;
+    const { unknown } = partitionIndicatorDashboards(requested);
+    const hintParts = [
+        'indicatorDashboards 可能传错，导致 statistic/columns 为空。',
+        '面板传参名≠统计维度后缀（如 fps_mean、frametime_min 是返回字段，不是面板名）。',
+        '合法示例：fps_avg、drawcall_cnt_max、frametime@gt_40_pct（含 @ 等特殊字符）。',
+        `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}。`,
+        '请先调 gotonline_overview_indicator_dashboard_keys 核对全量合法面板名。',
+    ];
+    if (unknown.length) {
+        hintParts.unshift(`未识别的面板名：${unknown.join('、')}。`);
+    }
+    return {
+        ...data,
+        _hint: hintParts.join(' '),
+    };
+}
 const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
+function hasNonEmptyRecords(v) {
+    return Array.isArray(v) && v.length > 0;
+}
+/** 各 GOT Online 子模块是否有报告；供模型「无 GPU 停手」。 */
+export function buildModuleAvailable(group) {
+    return {
+        overview: hasNonEmptyRecords(group['gotOnlineOverviewRecords']),
+        gpu: hasNonEmptyRecords(group['gotOnlineGPURecords']),
+        mono: hasNonEmptyRecords(group['gotOnlineMonoRecords']),
+        lua: hasNonEmptyRecords(group['gotOnlineLuaRecords']),
+        resource: hasNonEmptyRecords(group['gotOnlineResourceRecords']),
+    };
+}
+export function annotateModuleAvailable(data) {
+    if (!isObj(data) || !Array.isArray(data['content']))
+        return data;
+    const content = data['content'].map((g) => {
+        if (!isObj(g))
+            return g;
+        const module_available = buildModuleAvailable(g);
+        const missing = Object.entries(module_available)
+            .filter(([, ok]) => !ok)
+            .map(([k]) => k);
+        return {
+            ...g,
+            module_available,
+            ...(missing.length
+                ? {
+                    _moduleHint: `本项目组缺少模块：${missing.join('、')}。module_available 为 false 的模块请停手，禁止用 Overview 数据冒充分析。`,
+                }
+                : {}),
+        };
+    });
+    return { ...data, content };
+}
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
  * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
@@ -251,10 +375,10 @@ const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
  */
 export function annotateProjectGroups(data) {
     if (!isObj(data) || !Array.isArray(data['content']))
-        return data;
+        return annotateModuleAvailable(data);
     const groups = data['content'].filter(isObj);
     if (groups.length < 2)
-        return data;
+        return annotateModuleAvailable(data);
     // dataKey → 出现过的项目组；以及「该报告在哪个数组字段里、原文是什么」
     const groupsOf = new Map();
     const firstSeen = new Map();
@@ -283,7 +407,7 @@ export function annotateProjectGroups(data) {
     }
     const duplicated = [...groupsOf.values()].some((gs) => gs.size > 1);
     if (!duplicated)
-        return data;
+        return annotateModuleAvailable(data);
     // 已知项目组壳子（保留名称、engine 等元信息），报告重新按真实归属灌入
     const shells = new Map();
     for (const g of groups) {
@@ -318,15 +442,15 @@ export function annotateProjectGroups(data) {
     }
     // 丢掉合并后一个报告都没有的空组（它们原先只有别人的副本）
     const content = [...shells.values()].filter((g) => Object.entries(g).some(([k, v]) => RECORD_ARRAY_KEYS.test(k) && Array.isArray(v) && v.length > 0));
-    return {
+    return annotateModuleAvailable({
         ...data,
         content,
         _deduplicated: true,
         _uniqueReportCount: placed,
-        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
-            '。可直接按项目组统计。',
-    };
+            '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
+    });
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
@@ -336,25 +460,128 @@ function asText(value) {
         return '(接口无返回内容)';
     return JSON.stringify(value, null, 2);
 }
+/** 空 Bound / 空日志列表等：补可教模型的语义，避免误判。 */
+export function annotateEmptyStateSemantics(op, data) {
+    if (op.id === 'gotonline_gpu_bound') {
+        const intervals = Array.isArray(data) ? data : isObj(data) && Array.isArray(data['data']) ? data['data'] : null;
+        if (intervals && intervals.length === 0) {
+            const base = isObj(data) ? data : { data: intervals };
+            return {
+                ...base,
+                gpuBound: [],
+                forbidden_claims: ['GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈'],
+                _hint: 'GPU Bound 为空数组：仅表示在当前 targetFps 下未检出 Bound 区间，不等于 GPU 完全无压力；禁止据此断言 GPU 是主要瓶颈。',
+            };
+        }
+    }
+    if (op.id === 'gotonline_overview_log_export') {
+        const empty = (Array.isArray(data) && data.length === 0) ||
+            (isObj(data) && Array.isArray(data['data']) && data['data'].length === 0);
+        if (empty) {
+            const base = isObj(data) ? data : { entries: data };
+            return {
+                ...base,
+                _hint: '运行日志 1.0 返回空列表：可能是真无条目，也可能是新报告应改用 gotonline_lg_runtime_log_entries_presign（日志 2.0）。禁止说成「一定没有日志」。',
+            };
+        }
+    }
+    if (op.id === 'gotonline_overview_event_lower_memory_frames') {
+        const empty = (Array.isArray(data) && data.length === 0) ||
+            (isObj(data) && Array.isArray(data['data']) && data['data'].length === 0);
+        if (empty) {
+            const base = isObj(data) ? data : { frames: data };
+            return {
+                ...base,
+                _hint: '未触发 Low Memory 事件（空数组）。不能推出内存完全没问题，请结合 PSS 峰值等综合判断。',
+            };
+        }
+    }
+    return data;
+}
 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 data = annotateProjectGroups(annotateCurveAxes(raw));
+            let processed = annotateProjectGroups(annotateCurveAxes(raw));
+            if (isIndicatorStatisticDashboard(op.path) && acceptedDashboards.length) {
+                processed = annotateStatisticDashboard(processed, acceptedDashboards, unknownDashboards);
+            }
+            else if (isOverviewStatisticOp(op.id, op.path)) {
+                processed = annotateOverviewStatisticPss(processed);
+            }
+            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);
+                    if (curveFilter.returnFramesOnly) {
+                        processed = stripOuterXAxisWhenFramesOnly(processed, curveFilter);
+                    }
+                    else {
+                        processed = annotateCurveAxes(processed);
+                    }
+                }
+            }
+            let data = annotateDashboardEmptyResult(op, processed, args);
+            data = annotateEmptyStateSemantics(op, data);
+            const stutterGate = stutterRootCauseGate(op.id);
+            if (stutterGate && isObj(data)) {
+                data = { ...data, ...stutterGate };
+            }
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
@@ -392,6 +619,7 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
             }
             const meta = {
                 ...data,
+                ...(stutterRootCauseGate(op.id) ?? {}),
                 _downloaded: true,
                 _format: payload.kind,
                 ...(total !== undefined ? { _totalItems: total } : {}),

package/dist/version-check.d.ts

@@ -0,0 +1,14 @@
+/** npm 包名（与 package.json 同步）。 */
+export declare const PACKAGE_NAME = "@uwa4d/openapi-mcp";
+export interface UpdateCheckResult {
+    current: string;
+    latest: string;
+    channel: 'beta' | 'latest';
+}
+/** 当前运行版本应跟哪个 dist-tag 比对新版。 */
+export declare function resolveUpdateChannel(version: string): 'beta' | 'latest';
+/** 查询 registry 是否有比 current 更新的同通道版本；失败时返回 null。 */
+export declare function checkForUpdate(current: string): Promise<UpdateCheckResult | null>;
+export declare function formatUpdateNotice(result: UpdateCheckResult): string;
+/** 启动时异步检查；仅写 stderr，不阻塞 MCP 握手。 */
+export declare function scheduleUpdateNotice(current: string): void;

package/dist/version-check.js

@@ -0,0 +1,94 @@
+/** npm 包名（与 package.json 同步）。 */
+export const PACKAGE_NAME = '@uwa4d/openapi-mcp';
+const REGISTRY_URL = 'https://registry.npmjs.org/@uwa4d%2Fopenapi-mcp';
+const CHECK_TIMEOUT_MS = 8_000;
+/** 当前运行版本应跟哪个 dist-tag 比对新版。 */
+export function resolveUpdateChannel(version) {
+    return version.includes('-') ? 'beta' : 'latest';
+}
+/** 简易 semver 比较：a > b 返回 1，相等 0，a < b 返回 -1。 */
+function compareVersions(a, b) {
+    if (a === b)
+        return 0;
+    const parseCore = (v) => v.split('-')[0].split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const parsePre = (v) => {
+        const idx = v.indexOf('-');
+        if (idx < 0)
+            return [];
+        return v
+            .slice(idx + 1)
+            .split('.')
+            .map((part, i) => (i === 0 ? part : Number.parseInt(part, 10) || part));
+    };
+    const aCore = parseCore(a);
+    const bCore = parseCore(b);
+    for (let i = 0; i < Math.max(aCore.length, bCore.length); i++) {
+        const av = aCore[i] ?? 0;
+        const bv = bCore[i] ?? 0;
+        if (av !== bv)
+            return av > bv ? 1 : -1;
+    }
+    const aPre = parsePre(a);
+    const bPre = parsePre(b);
+    const aHasPre = aPre.length > 0;
+    const bHasPre = bPre.length > 0;
+    if (!aHasPre && bHasPre)
+        return 1;
+    if (aHasPre && !bHasPre)
+        return -1;
+    if (!aHasPre && !bHasPre)
+        return 0;
+    for (let i = 0; i < Math.max(aPre.length, bPre.length); i++) {
+        const av = aPre[i];
+        const bv = bPre[i];
+        if (av === bv)
+            continue;
+        if (av === undefined)
+            return -1;
+        if (bv === undefined)
+            return 1;
+        if (typeof av === 'number' && typeof bv === 'number')
+            return av > bv ? 1 : -1;
+        return String(av) > String(bv) ? 1 : -1;
+    }
+    return 0;
+}
+async function fetchDistTagVersion(channel) {
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+            headers: { Accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const tag = data['dist-tags']?.[channel];
+        return typeof tag === 'string' && tag.trim() ? tag.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 查询 registry 是否有比 current 更新的同通道版本；失败时返回 null。 */
+export async function checkForUpdate(current) {
+    const channel = resolveUpdateChannel(current);
+    const latest = await fetchDistTagVersion(channel);
+    if (!latest || compareVersions(latest, current) <= 0)
+        return null;
+    return { current, latest, channel };
+}
+export function formatUpdateNotice(result) {
+    const pkgRef = result.channel === 'beta' ? `${PACKAGE_NAME}@beta` : PACKAGE_NAME;
+    return (`[uwa-openapi-mcp] 有新版本 ${result.latest}（当前 ${result.current}，通道 ${result.channel}）。` +
+        `若 MCP 配置未锁定具体版本号，请在您使用的 AI 客户端中重启 MCP 服务以升级（重载 MCP 配置或重启客户端均可）；` +
+        `也可在终端核对：npx --yes --prefer-online ${pkgRef} --version`);
+}
+/** 启动时异步检查；仅写 stderr，不阻塞 MCP 握手。 */
+export function scheduleUpdateNotice(current) {
+    if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] === '1')
+        return;
+    void checkForUpdate(current).then((result) => {
+        if (result)
+            console.error(formatUpdateNotice(result));
+    });
+}

package/dist/version-guide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 版本成对工具的选用规则。
+ *
+ * 集中手写、挂到 describe() 首段，避免散落在 notes 里被模型漏读。
+ * 不塞进 docs/ 生成链路——刷新官方文档镜像不会冲掉这里。
+ */
+/**
+ * indicatorDashboards 传参名称说明（面板标识符，非统计维度后缀）。
+ * 挂到所有带 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;