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

package/dist/cli.js

@@ -6,6 +6,7 @@ import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './co
 import { filterKeys, selectOperations } from './presets.js';
 import { DEFAULT_MAX_CHARS, DEFAULT_MAX_ROWS, toolName } from './tools.js';
 import { PACKAGE_VERSION, startStdio } from './server.js';
+import { checkForUpdate, describeReleaseChannel, formatUpdateNotice } from './version-check.js';
 const DEFAULT_BASE_URL = 'https://secure-api.uwa4d.com';
 const SANDBOX_BASE_URL = 'https://sandbox-api.uwa4d.com';
 function splitList(value) {
@@ -133,6 +134,16 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
+        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${describeReleaseChannel(PACKAGE_VERSION).releaseLabel}）`);
+        if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+            const update = await checkForUpdate(PACKAGE_VERSION);
+            if (update) {
+                console.log(formatUpdateNotice(update));
+            }
+            else {
+                console.log('已是最新同 release 线版本（或暂时无法连接 npm registry）。');
+            }
+        }
         console.log('\n可以按 README 配置 MCP 客户端了。');
     }
     catch (err) {

package/dist/composite/index.js

@@ -2,8 +2,10 @@ import { toolName } from '../tools.js';
 import { topResourcesTool } from './top-resources.js';
 import { topFunctionsTool } from './top-functions.js';
 import { reportDiagnosisTool } from './report-diagnosis.js';
+import { mcpVersionTool } from './mcp-version.js';
 /** 全部手写复合工具（不进 uwa-openapi.json）。 */
 export const COMPOSITE_TOOLS = [
+    mcpVersionTool,
     topResourcesTool,
     topFunctionsTool,
     reportDiagnosisTool,

package/dist/composite/mcp-version.d.ts

@@ -0,0 +1,2 @@
+import type { CompositeTool } from './types.js';
+export declare const mcpVersionTool: CompositeTool;

package/dist/composite/mcp-version.js

@@ -0,0 +1,48 @@
+import { PACKAGE_VERSION } from '../package-version.js';
+import { buildMcpVersionInfo, describeReleaseChannel } from '../version-check.js';
+import { errorResult, jsonToolResult } from './helpers.js';
+const release = describeReleaseChannel(PACKAGE_VERSION);
+const STABLE_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 正式版版本，并与 npm 最新稳定版对比（仅正式版↔正式版，不与内部测试版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告客户重启 MCP 升级；已是最新勿打扰。',
+    '不要臆测版本号。',
+].join('\n');
+const INTERNAL_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 内部测试版版本，并与 npm @beta 最新测试版对比（仅测试↔测试，不与正式版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey｜仅 UWA 内部 sandbox 联调',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告测试人员重启 MCP 升级；已是最新勿打扰。',
+    '不要臆测版本号。',
+].join('\n');
+export const mcpVersionTool = {
+    id: 'uwa_mcp_version',
+    title: release.releaseLine === 'stable' ? 'MCP 正式版与升级提示' : 'MCP 内部测试版与升级提示',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['uwa_mcp_version', 'composite', 'preset.default', 'common'],
+    description: release.releaseLine === 'stable' ? STABLE_DESCRIPTION : INTERNAL_DESCRIPTION,
+    inputSchema: {},
+    async handler(_args, ctx) {
+        try {
+            if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] === '1') {
+                return jsonToolResult({
+                    package: '@uwa4d/openapi-mcp',
+                    currentVersion: PACKAGE_VERSION,
+                    releaseLine: release.releaseLine,
+                    releaseLabel: release.releaseLabel,
+                    updateCheckSkipped: true,
+                    userNotice: `当前 MCP ${release.releaseLabel} ${PACKAGE_VERSION}（已设置 UWA_MCP_SKIP_UPDATE_CHECK，未核对 npm 最新版）。`,
+                }, ctx.maxChars);
+            }
+            const info = await buildMcpVersionInfo(PACKAGE_VERSION);
+            return jsonToolResult({
+                ...info,
+                suggestTellUser: info.updateAvailable,
+            }, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

package/dist/composite/top-resources.js

@@ -1,3 +1,4 @@
+import { withRateLimitAnnotation } from '../error-hints.js';
 import { z } from './types.js';
 import { errorResult, isObj, jsonToolResult, requireReportKey, topNOf, } from './helpers.js';
 import { fetchOverviewStatistic, fetchReportIdentity, preferAtResourceTable, } from './route-overview.js';
@@ -193,26 +194,24 @@ export async function runTopResources(client, args) {
     apisUsed.push(...fetched.apisUsed);
     if (fetched.items.length === 0) {
         const fallbackItems = typeLevelFromOverview(view);
-        return packResult(fallbackItems, {
+        return packResult(fallbackItems, withRateLimitAnnotation({
             _sourceKind: fetched.sourceKind,
             _apisUsed: apisUsed,
-            ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
             _note: fallbackItems.length > 0
                 ? '逐资源列表为空，已回退为 Overview 类型级峰值。'
                 : '逐资源列表与类型级峰值均为空（报告可能未采集资源内存）。',
             _limitations: ['per_asset_empty'],
-        });
+        }, fetched.errors.length ? fetched.errors : undefined));
     }
     const note = groupBy === 'assetType'
         ? `已按类型各取 Top ${topN}（${fetched.sourceKind}，共 ${assetTypes.length} 种）。`
         : `已按内存峰值合并 ${assetTypes.length} 种资源类型（${fetched.sourceKind}），返回全局 Top ${topN}。`;
-    return packResult(fetched.items, {
+    return packResult(fetched.items, withRateLimitAnnotation({
         totalCandidates: fetched.items.length,
         _sourceKind: fetched.sourceKind,
         _apisUsed: apisUsed,
-        ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
         _note: note,
-    });
+    }, fetched.errors.length ? fetched.errors : undefined));
 }
 function normalizeAssetTypes(raw) {
     if (Array.isArray(raw) && raw.length)
@@ -236,6 +235,7 @@ export const topResourcesTool = {
         'Unity / UE 均优先走 AT 资源总览预签名（at/resource/overall/table/presign），按 assetType 并行下载后合并排序。',
         'groupBy=merged（默认）：跨类型合并后取全局 Top N；groupBy=assetType：每种类型各取 Top N，返回 byType。',
         'Unity 旧报告（解析日 < 2026-06-25）回退 memory/manage；拉不到逐资源时再回退 Overview 类型级峰值。',
+        '内部按 assetType 并行请求，易触发 OpenAPI 限流 31004（UWA 服务端保护，预期行为）。遇限流见 _rateLimitHint：可缩小 assetTypes、稍等重试；部分类型限流时已有 Top 仍可用。',
         '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
     ].join('\n'),
     inputSchema: {

package/dist/error-hints.d.ts

@@ -9,5 +9,15 @@ export declare const FILE_META_REASONS: {
     readonly AT_META_TYPE_INVALID: "AT_META_TYPE_INVALID";
     readonly AT_META_PATH_MISSING: "AT_META_PATH_MISSING";
 };
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export declare const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export declare const RATE_LIMIT_HINT: string;
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export declare function isRateLimitMessage(text: string): boolean;
+/** _partialErrors 中是否有限流项。 */
+export declare function hasRateLimitInPartialErrors(errors: string[]): boolean;
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export declare function withRateLimitAnnotation(extra: Record<string, unknown>, partialErrors?: string[]): Record<string, unknown>;
 /** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
 export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;

package/dist/error-hints.js

@@ -9,6 +9,11 @@ export const FILE_META_REASONS = {
     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 接口），改用对应版本重试',
@@ -18,6 +23,8 @@ const ERROR_HINTS_BY_CODE = {
     24056: '签名错误，检查 appSecret 是否正确',
     24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
     30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）；勿把瞬时失败说成「一定没有数据」',
+    31004: 'OpenAPI 接口限流（UWA 服务端保护，预期行为）。稍等重试，或减少并行请求/缩小查询范围（如 top_resources 的 assetTypes）；' +
+        '勿当成报告无数据或接口永久故障。',
 };
 /** OpenAPI 已按引擎写好的稳定文案（优先沿用，再补 AI 纪律）。 */
 function hintForOpenApiRuntimeLogMessage(apiMessage) {
@@ -45,6 +52,24 @@ function hintForFileMetaReason(rawMessage, apiMessage) {
     }
     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) {

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.js

@@ -11,6 +11,8 @@ export const SERVER_INSTRUCTIONS = [
     '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';
@@ -9,18 +6,9 @@ import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
 import { SERVER_INSTRUCTIONS } from './server-instructions.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 { 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 });
@@ -29,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 }, { instructions: SERVER_INSTRUCTIONS });
+    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));
     }
@@ -45,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/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));
+    });
+}

package/dist/version-guide.js

@@ -155,15 +155,15 @@ export const VERSION_GUIDE = {
     gotonline_overview_method_curve: [
         '【选用规则——务必先看】',
         '- v1.0.1 直出曲线 JSON（按 stackMethodName 或 stackMethodId）。',
-        '- **MCP 与 Open API 推荐改用 gotonline_overview_method_curve_presign（v1.0.2）**：OSS 预签名，仅传 stackMethodId。',
+        '- **MCP 与 Open API 推荐改用 gotonline_overview_method_curve_presign（v1.0.2）**：OSS 预签名，id 或 name 至少其一。',
         '- stackMethodId 来自 gotonline_overview_method_idmap_statistic 或自定义函数组统计。',
     ].join('\n'),
     gotonline_overview_method_curve_presign: [
         '【选用规则——务必先看】',
         '- v1.0.2 OSS 预签名下载函数逐帧曲线 JSON（Unity · UE）。',
-        '- **Open API 入口仅支持 stackMethodId（必填）**；UE 另需 threadName。',
+        '- stackMethodId 与 stackMethodName **至少传一个**（同时传时优先 id）；UE 另需 threadName，Unity 不传。',
         '- 不要用 v1.0.1 gotonline_overview_method_curve 除非必须服务端直出。',
-        '- stackMethodId 优先从 gotonline_overview_method_idmap_statistic 获取。',
+        '- id 优先从 gotonline_overview_method_idmap_statistic 获取。',
     ].join('\n'),
     gotonline_overview_indicator_dashboard_keys: [
         '【选用规则——务必先看】',
@@ -208,6 +208,7 @@ export const VERSION_GUIDE = {
     gotonline_overview_stack_tree_frame_presign: [
         '【选用规则——务必先看】',
         '- **单帧**完整堆栈树（frameId 必填）。用于已知尖峰帧深挖，不是卡顿分析的第一步。',
+        '- Unity：不传 threadId=主线程；传子线程 id/名=该子线程指定帧树（thread idmap）。UE：threadId 必传（含 GameThread）。',
         '- 卡顿共性根因请先用 stutter_full_tree / stutter_scene_tree（已是多帧合并结果）。',
         '- ❌ 不要对 frametime valueGt 筛出的每个慢帧循环调用本工具来「聚类」。',
         STACK_ANALYSIS_GUIDE,
@@ -215,6 +216,7 @@ export const VERSION_GUIDE = {
     gotonline_overview_stack_sample_frame_presign: [
         '【选用规则——务必先看】',
         '- 堆栈树某个结点的逐帧曲线；结点 id 来自树文件。',
+        '- Unity 子线程须传 threadId + sampleId；不传 threadId 为主线程（可不传 sampleId 取全帧聚合）。',
         STACK_ANALYSIS_GUIDE,
     ].join('\n'),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.9",
+  "version": "0.2.0",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "prepublishOnly": "npm run build && node scripts/check-publish-tag.mjs",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",
+    "release:stable-patch": "node scripts/release-stable-patch.mjs",
     "version:beta": "node scripts/bump.mjs beta",
     "version:release": "node scripts/bump.mjs release"
   },

package/spec/overrides.json

@@ -21,6 +21,52 @@
           "to": "单次请求最多查询 30 份报告（文档写 50，实测上限 30，超出会返回 20001）"
         }
       ]
+    },
+    "gotonline_overview_method_idmap_statistic": {
+      "reason": "threadName 仅 UE 必填；Unity 主线程不传。MCP 全局 schema 不得 required，否则 Zod 拦 Unity 调用。",
+      "verifiedAt": "2026-08-12",
+      "evidence": "sandbox：Unity dataKey=20260812163333sdk6b704767 不传 threadName 返回 348 条；UE 同接口须 threadName=GameThread。",
+      "setQueryRequired": {
+        "threadName": false
+      },
+      "setQueryDescription": {
+        "threadName": "UE 必传（GameThread / RHIThread / RenderThread / FAsyncLoadingThread 等）。Unity 无需此参数（不传=主线程）"
+      }
+    },
+    "gotonline_overview_method_curve_presign": {
+      "reason": "threadName 仅 UE 必填；Unity 不传。stackMethodId/Name 至少其一即可（与线上 Open API 一致）。",
+      "verifiedAt": "2026-08-12",
+      "evidence": "sandbox：Unity 仅 stackMethodId 可取曲线；UE 须 threadName=GameThread。生产 Open API 支持 name+id。",
+      "setQueryRequired": {
+        "threadName": false,
+        "stackMethodId": false,
+        "stackMethodName": false
+      },
+      "setQueryDescription": {
+        "threadName": "UE 必传。Unity 无需此参数",
+        "stackMethodId": "函数 ID；与 stackMethodName 至少传一个，同时传时优先 id",
+        "stackMethodName": "函数名称；与 stackMethodId 至少传一个"
+      }
+    },
+    "gotonline_overview_stack_tree_frame_presign": {
+      "reason": "threadId 仅 UE 必填（含 GameThread）；Unity 不传=主线程，传子线程 id/名=子线程树。",
+      "verifiedAt": "2026-08-12",
+      "evidence": "sandbox：Unity 帧树不传 threadId 成功；UE 传 GameThread/RenderThread 成功。旧 MCP schema 把 threadId 标成全局 required，Agent 调 Unity 时被 Zod 卡住。",
+      "setQueryRequired": {
+        "threadId": false
+      },
+      "setQueryDescription": {
+        "threadId": "UE 必传（线程 id 或线程名，含 GameThread）。Unity：不传=主线程；传子线程 id/名=该子线程指定帧树"
+      }
+    },
+    "gotonline_overview_stack_sample_frame_presign": {
+      "reason": "threadId / sampleId 文档写作「UE 是」，不得升成 MCP 全局必填。",
+      "verifiedAt": "2026-08-12",
+      "evidence": "文档表写作「UE 是」；旧 isRequired 用 /是/ 子串匹配会误判。Unity 主线程可不传 threadId，可不传 sampleId 取全帧聚合。",
+      "setQueryRequired": {
+        "threadId": false,
+        "sampleId": false
+      }
     }
   }
 }