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

package/dist/composite/report-diagnosis.js

@@ -1,9 +1,10 @@
 import { z } from './types.js';
-import { errorResult, jsonToolResult, requireReportKey } from './helpers.js';
+import { errorResult, isObj, jsonToolResult, requireReportKey } from './helpers.js';
 import { fetchOverviewStatistic, fetchReportIdentity, fetchSceneStatistic, } from './route-overview.js';
 import { viewOverview } from './overview-view.js';
 import { runTopFunctions } from './top-functions.js';
 import { runTopResources } from './top-resources.js';
+import { extractPssPeakCard } from '../annotate-dashboard.js';
 function summarizeScenes(data) {
     if (!data)
         return { sceneCount: 0 };
@@ -20,6 +21,25 @@ function summarizeScenes(data) {
     }
     return { keys: Object.keys(obj).slice(0, 30) };
 }
+/** list_scenes 返回起止帧；归一成 sceneIdx + sceneName + frameStart/End。 */
+function normalizeSceneList(data) {
+    const arr = Array.isArray(data)
+        ? data
+        : data && typeof data === 'object' && Array.isArray(data['scenes'])
+            ? data['scenes']
+            : [];
+    return arr.slice(0, 50).map((item, idx) => {
+        if (!item || typeof item !== 'object')
+            return { sceneIdx: idx, raw: item };
+        const o = item;
+        return {
+            sceneIdx: idx,
+            sceneName: o['sceneName'] ?? o['name'] ?? null,
+            frameStart: o['frameStart'] ?? o['startFrame'] ?? null,
+            frameEnd: o['frameEnd'] ?? o['endFrame'] ?? null,
+        };
+    });
+}
 /** brief 全量可能很长，体检只保留常见关键指标（含 Unity key 与 UE 中文 label）。 */
 function pickImportantBrief(brief) {
     const preferExact = [
@@ -57,17 +77,110 @@ function pickImportantBrief(brief) {
     }
     return out;
 }
+function numOf(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (Array.isArray(v) && typeof v[0] === 'number')
+        return v[0];
+    if (typeof v === 'string' && v.trim() && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/** 从 overview brief/summary 尽量抽出 PSS 峰值答题卡。 */
+function extractPssFromView(brief, summary) {
+    const sources = [brief, summary];
+    for (const src of sources) {
+        const peak = numOf(src['android_memory_pss_maximum']) ??
+            numOf(src['android_memory_pss@max']) ??
+            numOf(src['PSS峰值']) ??
+            numOf(src['设备内存峰值（MB）']);
+        const frame = numOf(src['android_memory_pss_maximum_frame']) ??
+            numOf(src['android_memory_pss@max_frame']) ??
+            null;
+        if (peak == null)
+            continue;
+        // brief 里设备内存峰值多为 MB；android_memory_pss 多为 KB
+        const looksMb = peak < 50_000 && (src['设备内存峰值（MB）'] !== undefined || peak < 2048);
+        const peakKb = looksMb ? Math.round(peak * 1024) : peak;
+        return {
+            pss_peak_kb: peakKb,
+            pss_peak_mb: Math.round((peakKb / 1024) * 100) / 100,
+            pss_peak_frame: frame,
+            pss_unit: 'KB',
+            _pssHint: 'Android PSS 峰值请优先读 pss_peak_kb/mb/frame；合法面板名 android_memory_pss@max（不是 android_pss_max）。',
+        };
+    }
+    return null;
+}
+/** 优先走 indicator statistic 拿完整 PSS 峰值+帧；失败再回退 overview brief。 */
+async function resolvePssPeakCard(client, identity, brief, summary, apisUsed, limitations) {
+    const keyQuery = {
+        indicatorDashboards: 'android_memory_pss@max',
+    };
+    if (identity.dataKey)
+        keyQuery['dataKey'] = identity.dataKey;
+    else if (identity.recordId != null)
+        keyQuery['recordId'] = identity.recordId;
+    else
+        return extractPssFromView(brief, summary);
+    try {
+        const raw = await client.call('GET', '/openapi/v1/data/gotonline/overview/indicator/statistic/dashboard', 'v1.0.1', keyQuery);
+        apisUsed.push('gotonline_overview_indicator_statistic_dashboard');
+        const card = extractPssPeakCard(raw);
+        if (card)
+            return card;
+        limitations.push('indicator PSS 面板无峰值字段，已回退 overview 摘要');
+    }
+    catch (e) {
+        limitations.push(`PSS 面板查询失败，已回退 overview 摘要：${e instanceof Error ? e.message : String(e)}`);
+    }
+    return extractPssFromView(brief, summary);
+}
+function isWaitForVsyncName(name) {
+    return /wait\s*for\s*vsync|WaitForVsync|Gfx\.WaitForPresent/i.test(String(name ?? ''));
+}
+function buildBottleneckCandidates(topFunctions, gpuBoundEmpty) {
+    const items = topFunctions && Array.isArray(topFunctions['items']) ? topFunctions['items'] : [];
+    const out = [];
+    for (const raw of items.slice(0, 8)) {
+        if (!isObj(raw))
+            continue;
+        const name = raw['name'] ?? raw['methodName'] ?? raw['stackMethodName'];
+        const wait = isWaitForVsyncName(name);
+        out.push({
+            name,
+            selfTimeMean: raw['selfTimeMean'] ?? raw['value'] ?? null,
+            source: 'top_functions',
+            role: wait ? 'frame_sync_wait' : 'cpu_candidate',
+            note: wait
+                ? 'WaitForVsync/Present 等待是帧同步表现，不能直接当卡顿根因或 GPU Bound 证据'
+                : '需结合 stutter 合并树确认是否为卡顿根因',
+        });
+    }
+    if (gpuBoundEmpty === true) {
+        out.push({
+            name: 'GPU Bound',
+            source: 'gotonline_gpu_bound',
+            role: 'not_detected',
+            note: 'targetFps=30 下未检出 GPU Bound 区间',
+        });
+    }
+    return out;
+}
 export const reportDiagnosisTool = {
     id: 'report_diagnosis',
     title: '报告体检',
     engines: ['unity', 'unreal'],
     filterKeys: ['report_diagnosis', 'composite', 'preset.default', 'overview'],
     description: [
-        '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数与场景摘要。',
+        '对单份 GOT Online 报告做一次结构化体检：自动选对 Overview 统计 v1/v2，并串联 Top 资源、Top 函数、场景摘要与 GPU Bound@30。',
         '适用引擎：Unity / UE｜复合工具',
         '调用方不必自己判断 2026-07-09 / 2026-03-25 分界或 SDK 版本——内部按 get_report_detail 路由。',
-        'Top 函数：Overview 走 method/idmap/statistic v1.0.2 + stackTestMode；Mono 走堆栈树；逐帧曲线用 method/curve/presign v1.0.2。',
-        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys 核对 indicatorDashboards（勿把 fps_mean 等统计字段当面板名）。',
+        '返回答题卡：forbidden_claims、bottleneck_candidates（与 topFunctions 分栏）、gpuBound、pss_peak_*、comparability_note。',
+        '卡顿根因：优先 stutter_full_tree / stutter_scene_tree；禁止把 WaitForVsync 写成根因或 GPU 主瓶颈。',
+        'gpuBound 为空时只能说「未检出 Bound」，禁止断言 GPU 是主要瓶颈。',
+        '查面板统计/曲线前先调 gotonline_overview_indicator_dashboard_keys（勿把 fps_mean 等统计字段当面板名）。',
+        'scenes 含 list_scenes 起止帧（sceneIdx/sceneName/frameStart/frameEnd）。',
         '返回摘要而非原始大包；需要明细时再按 _apisUsed 中的原子工具深挖。',
     ].join('\n'),
     inputSchema: {
@@ -121,16 +234,68 @@ export const reportDiagnosisTool = {
                     apisUsed.push(scene.target.id);
                 }
                 else {
-                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景摘要');
+                    limitations.push('当前引擎无 Unity 场景统计路由，已跳过场景统计摘要');
                 }
             }
             catch (e) {
                 limitations.push(`场景统计失败：${e instanceof Error ? e.message : String(e)}`);
             }
+            // list_scenes 补起止帧（场景统计摘要经常只有名称/索引）
+            try {
+                const keyQuery = {};
+                if (identity.dataKey)
+                    keyQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    keyQuery['recordId'] = identity.recordId;
+                const sceneList = await ctx.client.call('GET', '/openapi/v1/data/gotonline/scene/info', 'v1.0.1', keyQuery);
+                const list = normalizeSceneList(sceneList);
+                if (list.length) {
+                    scenes = { ...(scenes ?? {}), sceneCount: list.length, scenes: list };
+                    if (!apisUsed.includes('list_scenes'))
+                        apisUsed.push('list_scenes');
+                }
+            }
+            catch (e) {
+                limitations.push(`场景列表(list_scenes)失败：${e instanceof Error ? e.message : String(e)}`);
+            }
+            let gpuBound = null;
+            let gpuBoundEmpty = null;
+            try {
+                const boundQuery = { targetFps: 30 };
+                if (identity.dataKey)
+                    boundQuery['dataKey'] = identity.dataKey;
+                else if (identity.recordId)
+                    boundQuery['recordId'] = identity.recordId;
+                gpuBound = await ctx.client.call('GET', '/openapi/v1/data/gotonline/gpu/bound', 'v1.0.1', boundQuery);
+                apisUsed.push('gotonline_gpu_bound');
+                const intervals = Array.isArray(gpuBound)
+                    ? gpuBound
+                    : isObj(gpuBound) && Array.isArray(gpuBound['data'])
+                        ? gpuBound['data']
+                        : null;
+                gpuBoundEmpty = Array.isArray(intervals) ? intervals.length === 0 : null;
+            }
+            catch (e) {
+                limitations.push(`gpu_bound 失败：${e instanceof Error ? e.message : String(e)}`);
+            }
             // 仅在明确未开启时提示；hasResource === null 表示无法判定，不误报关闭
             if (view.hasResource === false) {
                 limitations.push('未开启资源采集，逐资源 Top 可能为空');
             }
+            const forbidden_claims = [];
+            if (gpuBoundEmpty === true) {
+                forbidden_claims.push('GPU是主要瓶颈', 'GPU Bound明显', 'GPU主瓶颈');
+            }
+            forbidden_claims.push('WaitForVsync是卡顿根因');
+            const pssCard = await resolvePssPeakCard(ctx.client, identity, view.brief, view.summary, apisUsed, limitations);
+            const sceneCount = isObj(scenes) ? Number(scenes['sceneCount'] ?? 0) : 0;
+            const comparability_note = [
+                '与其它报告对比时：请核对场景名/数量、测试时长、目标帧率、SDK/引擎版本是否一致。',
+                sceneCount > 0 ? `本报告场景数=${sceneCount}。` : '',
+                '仅比较 FPS 均值不能视为严格同场景对比。',
+            ]
+                .filter(Boolean)
+                .join(' ');
             const result = {
                 report: {
                     dataKey: identity.dataKey,
@@ -146,6 +311,11 @@ export const reportDiagnosisTool = {
                 hasResource: view.hasResource,
                 summary: view.summary,
                 brief: pickImportantBrief(view.brief),
+                ...(pssCard ?? {}),
+                gpuBound: Array.isArray(gpuBound) ? gpuBound : isObj(gpuBound) ? gpuBound['data'] ?? gpuBound : gpuBound,
+                gpuBoundEmpty,
+                forbidden_claims,
+                bottleneck_candidates: buildBottleneckCandidates(topFunctions, gpuBoundEmpty),
                 topResources: topResources
                     ? {
                         items: topResources['items'],
@@ -159,12 +329,14 @@ export const reportDiagnosisTool = {
                         metric: topFunctions['metric'],
                         uniqueFunctions: topFunctions['uniqueFunctions'],
                         note: topFunctions['_note'],
+                        _columnNote: 'topFunctions 是耗时排行，不等于卡顿根因；根因看 stutter 合并树与 bottleneck_candidates。',
                     }
                     : null,
                 scenes,
+                comparability_note,
                 _apisUsed: apisUsed,
                 _limitations: limitations,
-                _note: '结构化体检摘要。细节请按 _apisUsed 调用对应原子工具。',
+                _note: '结构化体检摘要（含答题卡）。GPU Bound 空时禁止 GPU 主瓶颈结论；卡顿根因优先 stutter 树。细节请按 _apisUsed 调用对应原子工具。',
             };
             return jsonToolResult(result, ctx.maxChars);
         }

package/dist/error-hints.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenAPI / 下游错误码 → AI 友好排查建议。
+ * 产品语义按引擎在此投影；got-query 只提供稳定 rawMessage 原因码。
+ */
+export declare const FILE_META_REASONS: {
+    readonly LG_META_ABSENT: "LG_META_ABSENT";
+    readonly LG_RUNTIME_PATH_MISSING: "LG_RUNTIME_PATH_MISSING";
+    readonly AT_META_ABSENT: "AT_META_ABSENT";
+    readonly AT_META_TYPE_INVALID: "AT_META_TYPE_INVALID";
+    readonly AT_META_PATH_MISSING: "AT_META_PATH_MISSING";
+};
+/** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
+export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;

package/dist/error-hints.js

@@ -0,0 +1,55 @@
+/**
+ * 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',
+};
+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 专用接口）；勿把瞬时失败说成「一定没有数据」',
+};
+/** 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;
+}
+/** 组装给模型看的排查建议；优先 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,6 +1,12 @@
 /** 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[];
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export declare function partitionIndicatorDashboards(raw: unknown): {
+    accepted: string[];
+    unknown: string[];
+    all: 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())
@@ -28,3 +29,22 @@ export function findUnknownIndicatorDashboards(raw) {
     const valid = new Set(INDICATOR_DASHBOARD_KEYS);
     return parts.filter((k) => !valid.has(k));
 }
+/** 拆成已接受 / 未识别面板名（保持请求顺序，已接受去重）。 */
+export function partitionIndicatorDashboards(raw) {
+    const all = splitIndicatorDashboards(raw);
+    const valid = new Set(INDICATOR_DASHBOARD_KEYS);
+    const accepted = [];
+    const unknown = [];
+    const seen = new Set();
+    for (const k of all) {
+        if (!valid.has(k)) {
+            unknown.push(k);
+            continue;
+        }
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        accepted.push(k);
+    }
+    return { accepted, unknown, all };
+}

package/dist/presets.js

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

package/dist/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,16 @@
+/**
+ * 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 只能说「暂不支持获取当前报告的运行日志」（方案切换过），勿断定报告本身无日志。其它失败勿把瞬时错误说成「一定没有数据」。',
+    '',
+    '体检优先调用 report_diagnosis；细节再按 _apisUsed 深挖。对比多份报告时说明场景/时长/目标帧是否可比（见 comparability_note）。',
+].join('\n');

package/dist/server.js

@@ -8,6 +8,7 @@ import { registerCompositeTools, COMPOSITE_TOOLS, selectCompositeTools } from '.
 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));
@@ -28,7 +29,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: 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));
     }

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;