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

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;
 }
 /** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
@@ -145,13 +202,58 @@ function summarize(payload, maxRows, maxChars) {
         rowTruncated = maxRows > 0 && lines.length > maxRows;
         body = rowTruncated ? lines.slice(0, maxRows).join('\n') : (payload.text ?? '');
     }
-    let text = typeof body === 'string' ? body : JSON.stringify(body, null, 2);
-    let charTruncated = false;
-    if (maxChars > 0 && text.length > maxChars) {
-        charTruncated = true;
-        text = text.slice(0, maxChars);
+    const fitted = fitToChars(body, maxChars);
+    return { rowTruncated, total, ...fitted };
+}
+const serialize = (v) => (typeof v === 'string' ? v : JSON.stringify(v, null, 2));
+/**
+ * 把返回内容压到字符上限以内。
+ *
+ * 直接按字符裁剪 JSON 会切出非法结构，模型没法解析。因此优先按条目缩减
+ * 主数据数组——二分找出能放下的最大条数，保留完整的 JSON 结构，
+ * 并在元信息里说明丢了多少。只有在没有数组可缩减时才退化为字符串截断。
+ */
+function fitToChars(body, maxChars) {
+    const full = serialize(body);
+    if (maxChars <= 0 || full.length <= maxChars) {
+        return { charTruncated: false, chars: full.length, body: full };
+    }
+    const rebuild = (n) => {
+        if (Array.isArray(body))
+            return serialize(body.slice(0, n));
+        if (body && typeof body === 'object') {
+            const obj = body;
+            const key = mainArrayKey(obj);
+            if (!key)
+                return null;
+            return serialize({ ...obj, [key]: obj[key].slice(0, n) });
+        }
+        return null;
+    };
+    const count = Array.isArray(body)
+        ? body.length
+        : body && typeof body === 'object'
+            ? (() => {
+                const key = mainArrayKey(body);
+                return key ? body[key].length : 0;
+            })()
+            : 0;
+    if (count > 0 && rebuild(0) !== null) {
+        // 二分出能放进上限的最大条数
+        let lo = 0;
+        let hi = count;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            const text = rebuild(mid);
+            if (text.length <= maxChars)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        const text = rebuild(lo);
+        return { charTruncated: true, kept: lo, chars: text.length, body: text };
     }
-    return { rowTruncated, charTruncated, total, chars: text.length, body: text };
+    return { charTruncated: true, chars: maxChars, body: full.slice(0, maxChars) };
 }
 function isObj(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -196,6 +298,160 @@ 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%），直接按组统计会成倍放大。
+ *
+ * 这里就地合并：按 link 里的 project= 判定真实归属，每份报告只保留在正确的组里。
+ * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
+ */
+export function annotateProjectGroups(data) {
+    if (!isObj(data) || !Array.isArray(data['content']))
+        return annotateModuleAvailable(data);
+    const groups = data['content'].filter(isObj);
+    if (groups.length < 2)
+        return annotateModuleAvailable(data);
+    // dataKey → 出现过的项目组；以及「该报告在哪个数组字段里、原文是什么」
+    const groupsOf = new Map();
+    const firstSeen = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid)
+            continue;
+        for (const [k, v] of Object.entries(g)) {
+            if (!RECORD_ARRAY_KEYS.test(k) || !Array.isArray(v))
+                continue;
+            for (const r of v) {
+                if (!isObj(r))
+                    continue;
+                const key = typeof r['dataKey'] === 'string' ? r['dataKey'] : null;
+                if (!key)
+                    continue;
+                if (!groupsOf.has(key))
+                    groupsOf.set(key, new Set());
+                groupsOf.get(key).add(gid);
+                if (!firstSeen.has(key)) {
+                    const fromLink = /[?&]project=(\d+)/.exec(String(r['link'] ?? ''))?.[1];
+                    firstSeen.set(key, { arrayKey: k, record: r, realGid: fromLink ?? gid });
+                }
+            }
+        }
+    }
+    const duplicated = [...groupsOf.values()].some((gs) => gs.size > 1);
+    if (!duplicated)
+        return annotateModuleAvailable(data);
+    // 已知项目组壳子（保留名称、engine 等元信息），报告重新按真实归属灌入
+    const shells = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid || shells.has(gid))
+            continue;
+        const shell = { ...g };
+        for (const k of Object.keys(shell)) {
+            if (RECORD_ARRAY_KEYS.test(k))
+                shell[k] = [];
+        }
+        shells.set(gid, shell);
+    }
+    let placed = 0;
+    let orphaned = 0;
+    for (const { arrayKey, record, realGid } of firstSeen.values()) {
+        let shell = shells.get(realGid);
+        if (!shell) {
+            // link 指向的组不在本页 content 里——仍给出一份壳，避免报告丢失
+            shell = {
+                projectGroupId: Number.isFinite(Number(realGid)) ? Number(realGid) : realGid,
+                projectGroupName: `(id=${realGid})`,
+                engine: null,
+            };
+            shells.set(realGid, shell);
+            orphaned++;
+        }
+        if (!Array.isArray(shell[arrayKey]))
+            shell[arrayKey] = [];
+        shell[arrayKey].push(record);
+        placed++;
+    }
+    // 丢掉合并后一个报告都没有的空组（它们原先只有别人的副本）
+    const content = [...shells.values()].filter((g) => Object.entries(g).some(([k, v]) => RECORD_ARRAY_KEYS.test(k) && Array.isArray(v) && v.length > 0));
+    return annotateModuleAvailable({
+        ...data,
+        content,
+        _deduplicated: true,
+        _uniqueReportCount: placed,
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
+            (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
+            '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
+    });
+}
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
     if (typeof value === 'string')
@@ -204,41 +460,166 @@ 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);
+            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 data = annotateCurveAxes(await client.call(op.method, op.path, apiVersion, query, body));
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
             if (!presignUrl || !wantDownload) {
-                return { content: [{ type: 'text', text: asText(data) }] };
+                // 非预签名接口同样可能很大（如报告列表 50 条约 56K 字符、
+                // 统计接口批量查十几份报告可达 20 万字符），这里必须同样设闸门，
+                // 否则会直接撑爆模型上下文。
+                const fitted = fitToChars(data, maxChars);
+                if (!fitted.charTruncated) {
+                    return { content: [{ type: 'text', text: asText(fitted.body) }] };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: asText({
+                                _truncated: `返回内容超过 ${maxChars} 字符上限，已缩减为 ${fitted.kept ?? 0} 条。` +
+                                    `请缩小查询范围后重试${op.query.some((p) => p.name === 'pageSize') ? '（如调小 pageSize 分页获取）' : '（如减少批量查询的条目数）'}，` +
+                                    `或在启动参数里调大 --max-chars。`,
+                                _returnedChars: fitted.chars,
+                            }),
+                        },
+                        { type: 'text', text: asText(fitted.body) },
+                    ],
+                };
             }
             const payload = await client.downloadPresign(presignUrl);
-            const { rowTruncated, charTruncated, total, chars, body: content } = summarize(payload, maxRows, maxChars);
+            const { rowTruncated, charTruncated, total, kept, chars, body: content } = summarize(payload, maxRows, maxChars);
             const notes = [];
             if (rowTruncated)
                 notes.push(`按 maxRows=${maxRows} 截断，去掉 maxRows 参数可取全量`);
             if (charTruncated) {
-                notes.push(`内容超过 ${maxChars} 字符上限已截断，尾部数据缺失。` +
+                notes.push(`内容超过 ${maxChars} 字符上限，已缩减为 ${kept ?? 0} 条。` +
                     `如需完整数据，用 download=false 拿 dataPresignUrl 自行下载，或启动时调大 --max-chars`);
             }
             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;