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

package/dist/error-hints.js

@@ -0,0 +1,80 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export const FILE_META_REASONS = {
+    LG_META_ABSENT: 'LG_META_ABSENT',
+    LG_RUNTIME_PATH_MISSING: 'LG_RUNTIME_PATH_MISSING',
+    AT_META_ABSENT: 'AT_META_ABSENT',
+    AT_META_TYPE_INVALID: 'AT_META_TYPE_INVALID',
+    AT_META_PATH_MISSING: 'AT_META_PATH_MISSING',
+};
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export const RATE_LIMIT_HINT = 'OpenAPI 限流（31004）是 UWA 服务端保护，不是报告无数据或接口故障。可稍等重试、减少并发或缩小 assetTypes；' +
+    '若 _partialErrors 仅部分类型限流，已有 Top 仍可用，需说明可能不完整。';
+const ERROR_HINTS_BY_CODE = {
+    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
+    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
+    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
+    24052: '请求参数有误，请对照接口文档检查',
+    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
+    24056: '签名错误，检查 appSecret 是否正确',
+    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
+    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）；勿把瞬时失败说成「一定没有数据」',
+    31004: 'OpenAPI 接口限流（UWA 服务端保护，预期行为）。稍等重试，或减少并行请求/缩小查询范围（如 top_resources 的 assetTypes）；' +
+        '勿当成报告无数据或接口永久故障。',
+};
+/** OpenAPI 已按引擎写好的稳定文案（优先沿用，再补 AI 纪律）。 */
+function hintForOpenApiRuntimeLogMessage(apiMessage) {
+    if (/暂不支持获取当前报告的运行日志/.test(apiMessage)) {
+        return 'UE 运行日志方案有过切换：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。旧报告可试 gotonline_overview_log_export。';
+    }
+    if (/运行日志未解析|运行日志解析未完成/.test(apiMessage)) {
+        return 'Unity：该报告无可用运行日志数据（未解析或解析未完成）。旧报告可试 gotonline_overview_log_export。';
+    }
+    return null;
+}
+function hintForFileMetaReason(rawMessage, apiMessage) {
+    const fromApi = hintForOpenApiRuntimeLogMessage(apiMessage);
+    if (fromApi)
+        return fromApi;
+    if (rawMessage.includes(FILE_META_REASONS.LG_META_ABSENT) || rawMessage.includes(FILE_META_REASONS.LG_RUNTIME_PATH_MISSING)) {
+        return ('运行日志 file_meta 不可用（原因码见 rawMessage）。' +
+            'Unity：通常表示未解析/无可用日志数据；UE：只能说暂不支持获取当前报告的运行日志，勿断定报告本身无日志。' +
+            '旧报告可试 gotonline_overview_log_export。');
+    }
+    if (rawMessage.includes(FILE_META_REASONS.AT_META_ABSENT) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_TYPE_INVALID) ||
+        rawMessage.includes(FILE_META_REASONS.AT_META_PATH_MISSING)) {
+        return 'AT 资源 meta 不可用：可能未开启资源采集或未解析完成，勿把失败说成「一定没有资源」。';
+    }
+    return null;
+}
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export function isRateLimitMessage(text) {
+    return text.includes(`[${RATE_LIMIT_ERROR_CODE}]`) || text.includes('API_RATE_LIMIT') || text.includes('接口限流');
+}
+/** _partialErrors 中是否有限流项。 */
+export function hasRateLimitInPartialErrors(errors) {
+    return errors.some(isRateLimitMessage);
+}
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export function withRateLimitAnnotation(extra, partialErrors) {
+    if (!partialErrors?.length)
+        return extra;
+    const out = { ...extra, _partialErrors: partialErrors };
+    if (hasRateLimitInPartialErrors(partialErrors)) {
+        out._rateLimitHint = RATE_LIMIT_HINT;
+    }
+    return out;
+}
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export function resolveErrorHint(code, rawMessage, apiMessage) {
+    if (code === 80108) {
+        return (hintForFileMetaReason(rawMessage, apiMessage) ??
+            '文件 meta 不存在（FILE_META_NOT_EXIST）。运行日志/AT 等场景请结合接口 message 与报告引擎解释；勿臆造数据。');
+    }
+    return ERROR_HINTS_BY_CODE[code];
+}

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

@@ -1,7 +1,7 @@
 /** indicatorDashboards 合法面板传参名称（与 got-query OverviewIndicatorDashboardCatalogService 同源）。 */
 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 const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES: readonly ["fps_mean", "fps_maximum", "frametime_min", "frametime_gt_40_pct", "temperature_mean", "drawcall_maximum", "android_pss_max"];
 export declare function splitIndicatorDashboards(raw: unknown): string[];
 export declare function findUnknownIndicatorDashboards(raw: unknown): string[];
 /** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */

package/dist/indicator-dashboard-keys.js

@@ -12,6 +12,7 @@ export const INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES = [
     'frametime_gt_40_pct',
     'temperature_mean',
     'drawcall_maximum',
+    'android_pss_max',
 ];
 export function splitIndicatorDashboards(raw) {
     if (typeof raw !== 'string' || !raw.trim())

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export declare const PACKAGE_VERSION: string;

package/dist/package-version.js

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export const PACKAGE_VERSION = readPackageVersion();

package/dist/presets.js

@@ -31,6 +31,7 @@ export const PRESET_DEFAULT = [
     'gotonline_overview_stack_stutter_scene_tree_presign',
     'gotonline_overview_stack_tree_frame_presign',
     // 复合工具（手写，见 src/composite/）
+    'uwa_mcp_version',
     'top_resources',
     'top_functions',
     'report_diagnosis',

package/dist/server-instructions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP server instructions：客户裸问时的全局纪律（勿依赖用户粘贴规则）。
+ * 与 docs/EMPTY_STATE_CONTRACT.md 对齐。
+ */
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/server-instructions.js

@@ -0,0 +1,18 @@
+/**
+ * MCP server instructions：客户裸问时的全局纪律（勿依赖用户粘贴规则）。
+ * 与 docs/EMPTY_STATE_CONTRACT.md 对齐。
+ */
+export const SERVER_INSTRUCTIONS = [
+    '你是 UWA GOT Online OpenAPI MCP 助手。用人话查报告时遵守以下纪律：',
+    '',
+    '1. 多份候选报告：先列出备注/设备/时间，再选或先问用户；禁止静默默认却假装只有一份。',
+    '2. 没有某类报告（如 GPU/Mono）：看 list 返回的 module_available；为 false 时明确说没有并停手。禁止用 Overview 的 RenderTexture / WaitForVsync 冒充 GPU 分析。',
+    '3. 说「GPU Bound / GPU 是主要瓶颈」之前：必须先查 gotonline_gpu_bound（或看 report_diagnosis.gpuBound）。空数组 [] 只能说「未检出 Bound」，不能说主要瓶颈是 GPU。',
+    '4. 卡顿根因：优先 gotonline_overview_stack_stutter_full_tree_presign / stutter_scene_tree；禁止把 WaitForVsync 直接当根因。尖峰再查单帧树。',
+    '5. 非法面板名要纠正（fps_mean→fps_avg；android_pss_max→android_memory_pss@max）；数值带单位。PSS 优先读 pss_peak_kb/mb/frame。',
+    '6. 接口失败时说明原因：运行日志 80108 — Unity 无 LG file_meta 表示未解析、无可用日志；UE 无 meta 只能说「暂不支持获取当前报告的运行日志」（方案切换过），勿断定报告本身无日志。其它失败勿把瞬时错误说成「一定没有数据」。',
+    '7. 接口限流 31004（API_RATE_LIMIT）：UWA 服务端保护，预期行为，不是 Bug。稍等重试或减少并行/批量（如 top_resources 缩小 assetTypes）。若返回含 _partialErrors 且 _rateLimitHint，部分类型限流时已有 Top 仍可用，需说明可能不完整，勿当成报告无资源。',
+    '8. MCP 版本（每对话最多一次）：本对话第一次使用任意 UWA MCP 工具前，先调用一次 uwa_mcp_version 核对 npm（正式版只对比正式版，内部测试版只对比测试版，互不交叉）。若 updateAvailable=true / suggestTellUser=true，必须用 userNotice 主动转告并说明重启 MCP 升级；已是最新则不要打扰用户。同一对话内勿重复调用。用户显式问版本时也可再调。',
+    '',
+    '体检优先调用 report_diagnosis；细节再按 _apisUsed 深挖。对比多份报告时说明场景/时长/目标帧是否可比（见 comparability_note）。',
+].join('\n');

package/dist/server.d.ts

@@ -16,9 +16,10 @@ export interface ServerOptions {
     maxChars: number;
     timeoutMs: number;
     specPath?: string;
+    /** 覆盖默认 server instructions（用于启动时注入版本升级提醒）。 */
+    instructions?: string;
 }
-/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
-export declare const PACKAGE_VERSION: string;
+export { PACKAGE_VERSION } from './package-version.js';
 export declare function createServer(opts: ServerOptions): {
     server: McpServer;
     toolCount: number;

package/dist/server.js

@@ -1,6 +1,3 @@
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { UwaClient } from './client.js';
@@ -8,18 +5,10 @@ import { registerCompositeTools, COMPOSITE_TOOLS, selectCompositeTools } from '.
 import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
-function readPackageVersion() {
-    try {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
-        return pkg.version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
-/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
-export const PACKAGE_VERSION = readPackageVersion();
+import { SERVER_INSTRUCTIONS } from './server-instructions.js';
+import { PACKAGE_VERSION } from './package-version.js';
+import { buildMcpVersionInfo, buildUpdateInstructionAppendix, scheduleUpdateNotice, } from './version-check.js';
+export { PACKAGE_VERSION } from './package-version.js';
 export function createServer(opts) {
     const spec = loadSpec(opts.specPath);
     const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });
@@ -28,7 +17,7 @@ export function createServer(opts) {
         credentials: { appId: opts.appId, appSecret: opts.appSecret },
         timeoutMs: opts.timeoutMs,
     });
-    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION });
+    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION }, { instructions: opts.instructions ?? SERVER_INSTRUCTIONS });
     for (const op of operations) {
         server.registerTool(toolName(op.id, opts.nameCase, opts.namePrefix), toolConfig(op), makeHandler(op, client, opts.maxRows, opts.maxChars));
     }
@@ -44,9 +33,25 @@ export function createServer(opts) {
     return { server, toolCount, total, atomicCount: operations.length, compositeCount };
 }
 export async function startStdio(opts) {
-    const { server, toolCount, total, atomicCount, compositeCount } = createServer(opts);
+    let instructions = SERVER_INSTRUCTIONS;
+    if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+        try {
+            const info = await buildMcpVersionInfo(PACKAGE_VERSION);
+            const appendix = buildUpdateInstructionAppendix(info);
+            if (appendix)
+                instructions = `${SERVER_INSTRUCTIONS}\n\n${appendix}`;
+        }
+        catch {
+            /* 版本检查失败不阻塞启动 */
+        }
+    }
+    const { server, toolCount, total, atomicCount, compositeCount } = createServer({
+        ...opts,
+        instructions,
+    });
     // stdout 是 MCP 协议通道，任何日志都必须走 stderr
-    console.error(`[uwa-openapi-mcp] 已加载 ${toolCount}/${total} 个工具（原子 ${atomicCount} + 复合 ${compositeCount}），接口地址 ${opts.baseUrl}`);
+    console.error(`[uwa-openapi-mcp] v${PACKAGE_VERSION} 已加载 ${toolCount}/${total} 个工具（原子 ${atomicCount} + 复合 ${compositeCount}），接口地址 ${opts.baseUrl}`);
+    scheduleUpdateNotice(PACKAGE_VERSION);
     await server.connect(new StdioServerTransport());
 }
 export { selectCompositeTools, COMPOSITE_TOOLS };

package/dist/tools.d.ts

@@ -32,6 +32,9 @@ export declare function annotateCurveAxes(data: unknown): unknown;
  * 自定义面板 statistic/curve 返回空 `{}` 时，优先提示面板名传错（静默失败高发）。
  */
 export declare function annotateDashboardEmptyResult(op: Operation, data: unknown, args: Record<string, unknown>): unknown;
+/** 各 GOT Online 子模块是否有报告；供模型「无 GPU 停手」。 */
+export declare function buildModuleAvailable(group: Record<string, unknown>): Record<string, boolean>;
+export declare function annotateModuleAvailable(data: unknown): unknown;
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
  * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
@@ -40,6 +43,8 @@ export declare function annotateDashboardEmptyResult(op: Operation, data: unknow
  * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
  */
 export declare function annotateProjectGroups(data: unknown): unknown;
+/** 空 Bound / 空日志列表等：补可教模型的语义，避免误判。 */
+export declare function annotateEmptyStateSemantics(op: Operation, data: unknown): unknown;
 export declare function makeHandler(op: Operation, client: UwaClient, defaultMaxRows: number, maxChars: number): (args: Record<string, unknown>) => Promise<ToolResult>;
 export declare function toolConfig(op: Operation): {
     title: string;

package/dist/tools.js

@@ -2,7 +2,7 @@ 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, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, } from './annotate-dashboard.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 之间，
@@ -331,6 +331,41 @@ export function annotateDashboardEmptyResult(op, data, args) {
     };
 }
 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%），直接按组统计会成倍放大。
@@ -340,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();
@@ -372,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) {
@@ -407,7 +442,7 @@ 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,
@@ -415,7 +450,7 @@ export function annotateProjectGroups(data) {
         _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
             '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
-    };
+    });
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
@@ -425,6 +460,44 @@ 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 {
@@ -480,6 +553,9 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
             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)
@@ -492,10 +568,20 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
                 }
                 if (hasCurveFilter(curveFilter)) {
                     processed = filterCurveData(processed, curveFilter);
-                    processed = annotateCurveAxes(processed);
+                    if (curveFilter.returnFramesOnly) {
+                        processed = stripOuterXAxisWhenFramesOnly(processed, curveFilter);
+                    }
+                    else {
+                        processed = annotateCurveAxes(processed);
+                    }
                 }
             }
-            const data = annotateDashboardEmptyResult(op, processed, args);
+            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;
@@ -533,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,41 @@
+/** npm 包名（与 package.json 同步）。 */
+export declare const PACKAGE_NAME = "@uwa4d/openapi-mcp";
+export interface UpdateCheckResult {
+    current: string;
+    latest: string;
+    /** npm dist-tag，仅作逻辑区分 */
+    registryTag: 'beta' | 'latest';
+}
+/** uwa_mcp_version 工具与启动 instructions 用的结构化版本信息。 */
+export interface McpVersionInfo {
+    package: string;
+    currentVersion: string;
+    /** stable=正式版（客户） / internal=内部测试版；与 npm dist-tag 一一对应，互不交叉比对 */
+    releaseLine: 'stable' | 'internal';
+    /** 对用户/模型可见的通道名，正式版不说 beta */
+    releaseLabel: string;
+    latestOnChannel: string | null;
+    registryReachable: boolean;
+    updateAvailable: boolean;
+    userNotice: string;
+    upgradeHint: string;
+}
+export interface ReleaseChannelPresentation {
+    registryTag: 'beta' | 'latest';
+    releaseLine: 'stable' | 'internal';
+    releaseLabel: string;
+    packageInstallRef: string;
+}
+/** 当前运行版本应跟哪个 npm dist-tag 比对新版（正式↔latest，测试↔beta，不交叉）。 */
+export declare function resolveUpdateChannel(version: string): 'beta' | 'latest';
+/** 正式版与内部测试版的分发呈现（客户侧不出现 beta 字样）。 */
+export declare function describeReleaseChannel(version: string): ReleaseChannelPresentation;
+/** 查询 registry 是否有比 current 更新的同通道版本；失败时返回 null。 */
+export declare function checkForUpdate(current: string): Promise<UpdateCheckResult | null>;
+/** 拉取完整版本信息（工具返回 + 启动 instructions）。 */
+export declare function buildMcpVersionInfo(current: string): Promise<McpVersionInfo>;
+/** 有新版本时追加到 server instructions，让模型在对话里主动提醒用户。 */
+export declare function buildUpdateInstructionAppendix(info: McpVersionInfo): string | 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,161 @@
+/** 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;
+/** 当前运行版本应跟哪个 npm dist-tag 比对新版（正式↔latest，测试↔beta，不交叉）。 */
+export function resolveUpdateChannel(version) {
+    return version.includes('-') ? 'beta' : 'latest';
+}
+/** 正式版与内部测试版的分发呈现（客户侧不出现 beta 字样）。 */
+export function describeReleaseChannel(version) {
+    const registryTag = resolveUpdateChannel(version);
+    if (registryTag === 'beta') {
+        return {
+            registryTag: 'beta',
+            releaseLine: 'internal',
+            releaseLabel: '内部测试版',
+            packageInstallRef: `${PACKAGE_NAME}@beta`,
+        };
+    }
+    return {
+        registryTag: 'latest',
+        releaseLine: 'stable',
+        releaseLabel: '正式版',
+        packageInstallRef: PACKAGE_NAME,
+    };
+}
+/** 简易 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 info = await buildMcpVersionInfo(current);
+    if (!info.updateAvailable || !info.latestOnChannel)
+        return null;
+    return { current: info.currentVersion, latest: info.latestOnChannel, registryTag: describeReleaseChannel(current).registryTag };
+}
+function buildUpgradeHint(presentation) {
+    return (`若 MCP 配置未锁定具体版本号，请在您使用的 AI 客户端中重启 MCP 服务以升级（重载 MCP 配置或重启客户端均可）；` +
+        `终端核对：npx --yes --prefer-online ${presentation.packageInstallRef} --version`);
+}
+/** 拉取完整版本信息（工具返回 + 启动 instructions）。 */
+export async function buildMcpVersionInfo(current) {
+    const presentation = describeReleaseChannel(current);
+    const latestOnChannel = await fetchDistTagVersion(presentation.registryTag);
+    const registryReachable = latestOnChannel !== null;
+    const updateAvailable = registryReachable && latestOnChannel !== null && compareVersions(latestOnChannel, current) > 0;
+    const upgradeHint = buildUpgradeHint(presentation);
+    if (updateAvailable && latestOnChannel) {
+        return {
+            package: PACKAGE_NAME,
+            currentVersion: current,
+            releaseLine: presentation.releaseLine,
+            releaseLabel: presentation.releaseLabel,
+            latestOnChannel,
+            registryReachable,
+            updateAvailable: true,
+            userNotice: `UWA OpenAPI MCP（${presentation.releaseLabel}）有新版本：当前 ${current}，${presentation.releaseLabel}最新 ${latestOnChannel}。` +
+                upgradeHint,
+            upgradeHint,
+        };
+    }
+    const latestLabel = latestOnChannel ?? '(暂时无法连接 npm 核对最新版)';
+    return {
+        package: PACKAGE_NAME,
+        currentVersion: current,
+        releaseLine: presentation.releaseLine,
+        releaseLabel: presentation.releaseLabel,
+        latestOnChannel,
+        registryReachable,
+        updateAvailable: false,
+        userNotice: registryReachable
+            ? `UWA OpenAPI MCP（${presentation.releaseLabel}）已是最新：当前 ${current}，${presentation.releaseLabel}最新 ${latestLabel}。`
+            : `UWA OpenAPI MCP（${presentation.releaseLabel}）当前版本 ${current}；暂时无法连接 npm 核对最新版。`,
+        upgradeHint,
+    };
+}
+/** 有新版本时追加到 server instructions，让模型在对话里主动提醒用户。 */
+export function buildUpdateInstructionAppendix(info) {
+    if (!info.updateAvailable || !info.latestOnChannel)
+        return null;
+    const headline = info.releaseLine === 'stable'
+        ? '【MCP 正式版有新版本 — 请主动告知用户】'
+        : '【MCP 内部测试版有新版本 — 请主动告知内部测试人员】';
+    return (`${headline}当前运行 ${info.currentVersion}，${info.releaseLabel}最新 ${info.latestOnChannel}。` +
+        `请用自然语言转告用户重启 MCP 升级（勿只写 stderr 日志）。详情可调工具 uwa_mcp_version。` +
+        ` ${info.upgradeHint}`);
+}
+export function formatUpdateNotice(result) {
+    const presentation = describeReleaseChannel(result.current);
+    return (`[uwa-openapi-mcp] ${presentation.releaseLabel}有新版本 ${result.latest}（当前 ${result.current}）。` +
+        buildUpgradeHint(presentation));
+}
+/** 启动时异步检查；仅写 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));
+    });
+}