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

package/dist/indicator-dashboard-keys.json

@@ -0,0 +1,338 @@
+{
+    "generatedAt": "2026-08-07T02:47:15.585Z",
+    "keys": [
+        "Active_Dynamic_Bodies_Count_max",
+        "Active_Kinematic_Bodies_Count_max",
+        "AnimationClip_cnt_max",
+        "AnimationClip_mem_max_mb",
+        "AnimationUpdate_cpu_avg_ms",
+        "Animation_grpcpu_avg_ms",
+        "AnimatorInitialize_cpu_avg_ms",
+        "AnimatorInitialize_jank_rate",
+        "Animator_cnt_max",
+        "Animator_mem_max_mb",
+        "AnimatorsUpdate_cpu_avg_ms",
+        "AnimatorsWriteJob_cpu_avg_ms",
+        "Application.backgroundLoadingPriority",
+        "AssetBundle_Disk_mem_max_mb",
+        "AssetBundle_Memory_mem_max_mb",
+        "AssetBundle_cnt_max",
+        "AssetBundle_mem_max_mb",
+        "Asset_Count_max",
+        "Asset_total_cnt_max",
+        "Asset_total_mem_max_mb",
+        "AudioClip_cnt_max",
+        "AudioClip_mem_max_mb",
+        "Batch_cpu_cnt_max",
+        "Batches_Count_max",
+        "CameraImageEffects_cpu_avg_ms",
+        "CameraRender_cpu_avg_ms",
+        "CanvasBuildBatch_cpu_avg_ms",
+        "CanvasRenderSubBatch_cnt_max",
+        "CanvasRendererSyncTransform_cnt_max",
+        "CanvasSendWillRenderCanvases_cpu_avg_ms",
+        "CollectGarbageIncremental_cpu_avg_ms",
+        "Culling_cpu_avg_ms",
+        "Draw_Calls_Count_max",
+        "Dynamic_Bodies_2D_Count_max",
+        "FAsyncLoadingThread_cpu_avg_ms",
+        "FDrawSceneCommand_cpu_avg_ms",
+        "FTickFunctionTask_cpu_avg_ms",
+        "FTimerManager_cpu_avg_ms",
+        "Font_cnt_max",
+        "Font_mem_max_mb",
+        "GCCollect_jank_rate",
+        "GameThread_cpu_avg_ms",
+        "Game_Object_Count_max",
+        "GarbageCollectAssetsProfile_jank_rate",
+        "Instantiate_jank_rate",
+        "Kinematic_Bodies_2D_Count_max",
+        "LoadingReadObjectThreaded_jank_rate",
+        "LoadingReadObject_jank_rate",
+        "LoadingUpdatePreloading_cpu_avg_ms",
+        "Loading_grpcpu_avg_ms",
+        "Material_cnt_max",
+        "Material_mem_max_mb",
+        "MeshSkinningUpdate_cpu_avg_ms",
+        "Mesh_cnt_max",
+        "Mesh_mem_max_mb",
+        "Native_HeapTotal_mem_max_mb",
+        "Object_Count_max",
+        "OnDemandRendering_RenderFrameInterval_Count",
+        "Overlap_Queries_2D_Count_max",
+        "Overlaps_Count_max",
+        "ParticleSystemDraw_cnt_max",
+        "ParticleSystemUpdate_cpu_avg_ms",
+        "ParticleSystem_cnt_max",
+        "ParticleSystem_grpcpu_avg_ms",
+        "ParticleSystem_mem_max_mb",
+        "PhysicsFetchResults_cpu_avg_ms",
+        "PhysicsProcessReports_cpu_avg_ms",
+        "PhysicsProcessReports_jank_rate",
+        "PhysicsProcessing_cpu_avg_ms",
+        "PhysicsSimulate_cpu_avg_ms",
+        "Physics_grpcpu_avg_ms",
+        "RHIThread_cpu_avg_ms",
+        "RenderOpaqueGeometry_cpu_avg_ms",
+        "RenderPipelineManagerDoRenderLoop_Internal_cpu_avg_ms",
+        "RenderTexture_cnt_max",
+        "RenderTexture_mem_max_mb",
+        "RenderThread_cpu_avg_ms",
+        "RenderTransparentGeometry_cpu_avg_ms",
+        "RenderingEmitWorldScreenspaceCameraGeometry_cpu_avg_ms",
+        "Rendering_grpcpu_avg_ms",
+        "ResourcesUnloadUnusedAssets_cpu_avg_ms",
+        "STAT_AI_Overall_cpu_avg_ms",
+        "STAT_AddViewDependentWholeSceneShadowsForView_cpu_avg_ms",
+        "STAT_AnimGameThreadTime_cpu_avg_ms",
+        "STAT_AnimTickTime_cpu_avg_ms",
+        "STAT_AnimTriggerAnimNotifies_cpu_avg_ms",
+        "STAT_AnisotropyPassDrawTime_cpu_avg_ms",
+        "STAT_AssetRegistryLLM_max",
+        "STAT_AsyncLoadingLLM_max",
+        "STAT_BasePassDrawTime_cpu_avg_ms",
+        "STAT_BeginOcclusionTestsTime_cpu_avg_ms",
+        "STAT_BlendInPhysics_cpu_avg_ms",
+        "STAT_BlueprintTime_cpu_avg_ms",
+        "STAT_BuildCSMVisibilityState_cpu_avg_ms",
+        "STAT_CLMM_Occlusion_cpu_avg_ms",
+        "STAT_CLMM_Opaque_cpu_avg_ms",
+        "STAT_CLMM_Post_cpu_avg_ms",
+        "STAT_CLMM_Shadows_cpu_avg_ms",
+        "STAT_CLMM_Translucency_cpu_avg_ms",
+        "STAT_CSMStaticMeshReceivers_cnt_max",
+        "STAT_CSMSubjects_cnt_max",
+        "STAT_CacheUniformExpressions_cpu_avg_ms",
+        "STAT_CharFindFloor_cpu_avg_ms",
+        "STAT_CharHandleImpact_cpu_avg_ms",
+        "STAT_CharMoveUpdateDelegate_cpu_avg_ms",
+        "STAT_CharPhysFalling_cpu_avg_ms",
+        "STAT_CharPhysNavWalking_cpu_avg_ms",
+        "STAT_CharPhysWalking_cpu_avg_ms",
+        "STAT_CharacterMovementNonSimulated_cpu_avg_ms",
+        "STAT_CharacterMovementSimulated_cpu_avg_ms",
+        "STAT_CharacterMovementSmoothClientPosition_Interp_cpu_avg_ms",
+        "STAT_CharacterMovementSmoothClientPosition_Visual_cpu_avg_ms",
+        "STAT_CharacterMovementSmoothClientPosition_cpu_avg_ms",
+        "STAT_CharacterMovementTick_cpu_avg_ms",
+        "STAT_CharacterMovement_cpu_avg_ms",
+        "STAT_CollectGarbageInternalCall_ncall_max",
+        "STAT_CollectGarbageInternal_cpu_avg_ms",
+        "STAT_CollectGarbageInternal_cpu_max_ms",
+        "STAT_Collision_SceneQueryTotal_cpu_avg_ms",
+        "STAT_ComputeViewRelevance_cpu_avg_ms",
+        "STAT_CreateLumenRayTracingPipeline_cpu_avg_ms",
+        "STAT_CreateRayTracingPipeline_cpu_avg_ms",
+        "STAT_CreateWholeSceneProjectedShadow_cpu_avg_ms",
+        "STAT_DecalsDrawTime_cpu_avg_ms",
+        "STAT_DecompressPrecomputedOcclusion_cpu_avg_ms",
+        "STAT_DepthDrawTime_cpu_avg_ms",
+        "STAT_DestroyActor_cpu_avg_ms",
+        "STAT_DynamicEmitterCount_cnt_max",
+        "STAT_DynamicPSysCompCount_cnt_max",
+        "STAT_DynamicPSysCompCount_ncall_max",
+        "STAT_DynamicPrimitiveDrawTime_cpu_avg_ms",
+        "STAT_DynamicShadowSetupTime_cpu_avg_ms",
+        "STAT_EngineInitLLM_max",
+        "STAT_EngineMiscLLM_max",
+        "STAT_EnginePreInitLLM_max",
+        "STAT_ExplicitWaitRHIThread_cpu_avg_ms",
+        "STAT_FAsyncPackage_TickAsyncLoadingGameThread_cpu_avg_ms",
+        "STAT_FAsyncPackage_TickAsyncLoadingGameThread_cpu_max_ms",
+        "STAT_FEngineLoop_Tick_SlateInput_cpu_avg_ms",
+        "STAT_FNameLLM_max",
+        "STAT_FileSystemLLM_max",
+        "STAT_FinalizeAnimationUpdate_cpu_avg_ms",
+        "STAT_FinishRenderViewTargetTime_cpu_avg_ms",
+        "STAT_FrameSyncTime_cpu_avg_ms",
+        "STAT_GCLLM_max",
+        "STAT_GatherShadowPrimitivesTime_cpu_avg_ms",
+        "STAT_GetDynamicMeshElements_cpu_avg_ms",
+        "STAT_InitDynamicShadowsTime_cpu_avg_ms",
+        "STAT_InitProjectedShadowVisibility_cpu_avg_ms",
+        "STAT_InitViewsTime_cpu_avg_ms",
+        "STAT_InterpolateVolumetricLightmapOnCPU_cpu_avg_ms",
+        "STAT_LightingDrawTime_cpu_avg_ms",
+        "STAT_LocalizationLLM_max",
+        "STAT_MaterialsLLM_max",
+        "STAT_MeshDrawCalls_cnt_max",
+        "STAT_MeshObjectUpdate_cpu_avg_ms",
+        "STAT_Montage_Advance_cpu_avg_ms",
+        "STAT_NavWorldTickTime_cpu_avg_ms",
+        "STAT_NetReceiveRPC_cpu_avg_ms",
+        "STAT_NetWorldTickTime_cpu_avg_ms",
+        "STAT_NiagaraLLM_max",
+        "STAT_NiagaraNumSprites_cnt_max",
+        "STAT_NiagaraOverview_GT_cpu_avg_ms",
+        "STAT_NiagaraOverview_RT_cpu_avg_ms",
+        "STAT_NiagaraRenderSprites_ncall_max",
+        "STAT_OcclusionCull_cpu_avg_ms",
+        "STAT_OcclusionQueries_cnt_max",
+        "STAT_OpenGLShaderCompileTime_cpu_avg_ms",
+        "STAT_OpenGLShaderLinkTime_cpu_avg_ms",
+        "STAT_OpenGLShaderLinkTime_cpu_max_ms",
+        "STAT_ParticleDrawCalls_cnt_max",
+        "STAT_ParticlesLLM_max",
+        "STAT_ParticlesOverview_GT_cpu_avg_ms",
+        "STAT_ParticlesOverview_RT_cpu_avg_ms",
+        "STAT_PlatformTotalLLM_max",
+        "STAT_PlatformTrackedTotalLLM_max",
+        "STAT_PostAnimEvaluation_cpu_avg_ms",
+        "STAT_PresentTime_cpu_avg_ms",
+        "STAT_ProcessMouseButtonDown_cpu_avg_ms",
+        "STAT_ProcessMouseButtonUp_cpu_avg_ms",
+        "STAT_ProcessMouseMove_cpu_avg_ms",
+        "STAT_ProcessedPrimitives_cnt_max",
+        "STAT_ProgramSizeLLM_max",
+        "STAT_ProjectedShadowDrawTime_cpu_avg_ms",
+        "STAT_RHIDrawPrimitiveCalls_cnt_max",
+        "STAT_RHIMiscLLM_max",
+        "STAT_RHIThreadExecute_cpu_avg_ms",
+        "STAT_RHITriangles_cnt_max",
+        "STAT_RayTracingActiveInstances_cnt_max",
+        "STAT_RayTracingTotalInstances_cnt_max",
+        "STAT_RayTracing_FinishGatherInstances_cpu_avg_ms",
+        "STAT_ReflectiveShadowMapDrawTime_cpu_avg_ms",
+        "STAT_RefreshBoneTransforms_cpu_avg_ms",
+        "STAT_RenderQueryResultTime_cpu_avg_ms",
+        "STAT_RenderVelocities_cpu_avg_ms",
+        "STAT_ResourcesSumLLM_max",
+        "STAT_SceneDecals_cnt_max",
+        "STAT_SceneLights_cnt_max",
+        "STAT_SetupInteractionShadows_cpu_avg_ms",
+        "STAT_SetupMeshPass_cpu_avg_ms",
+        "STAT_ShadersLLM_max",
+        "STAT_Shaders_RTShaderLoadTime_cpu_avg_ms",
+        "STAT_Shaders_RTShaderLoadTime_cpu_max_ms",
+        "STAT_SkeletalMeshLLM_max",
+        "STAT_SlateApplicationInput_cpu_avg_ms",
+        "STAT_SlateDrawWindowTime_cpu_avg_ms",
+        "STAT_SlateElements_cnt_max",
+        "STAT_SlateMessageTick_cpu_avg_ms",
+        "STAT_SlateNumBatches_cnt_max",
+        "STAT_SlateNumPaintedWidgets_cnt_max",
+        "STAT_SlatePostProcessingRTTime_cpu_avg_ms",
+        "STAT_SlatePreFullBufferRTTime_cpu_avg_ms",
+        "STAT_SlatePreTickEvent_cpu_avg_ms",
+        "STAT_SlateRTDrawBatches_cpu_avg_ms",
+        "STAT_SlateRenderingRTTime_cpu_avg_ms",
+        "STAT_SlateTickTime_cpu_avg_ms",
+        "STAT_SlateTotalWidgets_cnt_max",
+        "STAT_SlateUpdateBufferRTTime_cpu_avg_ms",
+        "STAT_SlateVertexCount_cnt_max",
+        "STAT_SortStaticDrawLists_cpu_avg_ms",
+        "STAT_SpawnActorTime_cpu_avg_ms",
+        "STAT_SpawnActorTime_cpu_max_ms",
+        "STAT_StaticDrawListDrawTime_cpu_avg_ms",
+        "STAT_StaticMeshLLM_max",
+        "STAT_StaticRelevance_cpu_avg_ms",
+        "STAT_StatsLLM_max",
+        "STAT_TextureMetaDataLLM_max",
+        "STAT_ThreadStackLLM_max",
+        "STAT_TickableGameObjectsTime_cpu_avg_ms",
+        "STAT_TotalGPUFrameTime_cpu_avg_ms",
+        "STAT_TotalLLM_max",
+        "STAT_TotalPhysicsTime_cpu_avg_ms",
+        "STAT_TotalSceneRenderingTime_cpu_avg_ms",
+        "STAT_TranslucencyDrawTime_cpu_avg_ms",
+        "STAT_UILLM_max",
+        "STAT_UnitFrame_cpu_avg_ms",
+        "STAT_UnitGPU_cpu_avg_ms",
+        "STAT_UnitGame_cpu_avg_ms",
+        "STAT_UnitRHIT_cpu_avg_ms",
+        "STAT_UnitRender_cpu_avg_ms",
+        "STAT_UntaggedTotalLLM_max",
+        "STAT_UpdateAlwaysVisible_cpu_avg_ms",
+        "STAT_UpdateAnimation_cpu_avg_ms",
+        "STAT_UpdateIndirectLightingCache_cpu_avg_ms",
+        "STAT_UpdateOverlaps_cpu_avg_ms",
+        "STAT_UpdatePreshadowCache_cpu_avg_ms",
+        "STAT_UpdatePrimitiveFading_cpu_avg_ms",
+        "STAT_UpdateRBBones_cpu_avg_ms",
+        "STAT_UpdateStaticMeshesTime_cpu_avg_ms",
+        "STAT_ViewRelevance_cpu_avg_ms",
+        "STAT_ViewVisibilityTime_cpu_avg_ms",
+        "STAT_VisibleDynamicPrimitives_cnt_max",
+        "STAT_VisibleRayTracingPrimitives_cnt_max",
+        "STAT_VisibleStaticMeshElements_cnt_max",
+        "STAT_VulkanQueuePresent_cpu_avg_ms",
+        "STAT_WaterPassDrawTime_cpu_avg_ms",
+        "STAT_eglSwapBuffers_cpu_avg_ms",
+        "Scene_Object_Count_max",
+        "Screen_Resolution_Height_Count",
+        "Screen_Resolution_Width_Count",
+        "Scripting_grpcpu_avg_ms",
+        "ShaderCreateGPUProgram_jank_rate",
+        "ShaderParse_jank_rate",
+        "Shader_cnt_max",
+        "Shader_mem_max_mb",
+        "SkelMeshObjectUpdateDataCommand_cpu_avg_ms",
+        "SlateDrawWindowsCommand_cpu_avg_ms",
+        "StageEngineLateUpdate_cpu_avg_ms",
+        "Stat_ChannelReceivedRawBunchCall_ncall_max",
+        "Stat_ChannelReceivedRawBunch_ncall_max",
+        "Static_Colliders_Count_max",
+        "Static_Shapes_2D_Count_max",
+        "TextAsset_cnt_max",
+        "TextAsset_mem_max_mb",
+        "Texture_cnt_max",
+        "Texture_mem_max_mb",
+        "Triangles_Count_max",
+        "UIPanelLateUpdate_cpu_avg_ms",
+        "UIRectUpdate_cpu_avg_ms",
+        "Wasm_HeapTotal_mem_max_mb",
+        "Wwise_Reserved_mem_max_mb",
+        "android_memory_pss@max",
+        "batterylevel@mean_delta_p10000",
+        "batterypower_max",
+        "batterypower_mean",
+        "big_jank_rate",
+        "cpu_freq_x@mean",
+        "drawcall_cnt_max",
+        "fps_avg",
+        "frametime@gt_40_pct",
+        "gpu_counter_bandwidth_total_avg",
+        "gpu_counter_bandwidth_total_in_seconds_avg",
+        "gpu_counter_bus_utilization",
+        "gpu_counter_clocks",
+        "gpu_counter_cycles_per_pixel",
+        "gpu_counter_fragment",
+        "gpu_counter_fragment_shaded_avg",
+        "gpu_counter_gpu_temperature_max",
+        "gpu_counter_nobaselevel_texture_avg",
+        "gpu_counter_overdraw_avg",
+        "gpu_counter_primitive_avg",
+        "gpu_counter_read_stall_avg",
+        "gpu_counter_shader_cycles_avg",
+        "gpu_counter_shader_instructions_avg",
+        "gpu_counter_texture_cache_miss_l1_avg",
+        "gpu_target_freq_usage_120_fps_pct",
+        "gpu_target_freq_usage_30_fps_pct",
+        "gpu_target_freq_usage_45_fps_pct",
+        "gpu_target_freq_usage_60_fps_pct",
+        "gpu_time_avg_ms",
+        "ios_memory_footprint@max",
+        "jank_rate",
+        "jank_time_rate",
+        "lua_function_cnt_max",
+        "lua_mem_max_mb",
+        "lua_table_cnt_max",
+        "lua_userdata_cnt_max",
+        "monoObjectRef_cnt_max",
+        "network_in@max",
+        "network_out@max",
+        "power_max",
+        "reservedMono_mem_max_mb",
+        "reservedTotal_mem_max_mb",
+        "soc_ddr_freq",
+        "soc_gpu_freq",
+        "soc_gpu_loading",
+        "soc_gpu_utilization",
+        "temperature_max",
+        "temperature_mean",
+        "triangle_cnt_max",
+        "ui_cpu_avg_ms",
+        "usedSystem_mem_max_mb",
+        "windows_memory_workingset@max"
+    ]
+}

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/tools.d.ts

@@ -28,6 +28,10 @@ export interface ToolResult {
  * 帧号范围和步长，并在点数对不上时给出警告，从结构上消除歧义。
  */
 export declare function annotateCurveAxes(data: unknown): unknown;
+/**
+ * 自定义面板 statistic/curve 返回空 `{}` 时，优先提示面板名传错（静默失败高发）。
+ */
+export declare function annotateDashboardEmptyResult(op: Operation, data: unknown, args: Record<string, unknown>): unknown;
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
  * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。

package/dist/tools.js

@@ -1,6 +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, extractCurveFilterArgs, filterCurveData, hasCurveFilter, isIndicatorCurveDashboard, isIndicatorStatisticDashboard, } from './annotate-dashboard.js';
 const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
 /**
  * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
@@ -85,36 +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]) {
         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 等为历史命名，不表示只能取峰值或均值。',
-                '例：temperature_max 可拿到整机/CPU/GPU/电池温度的曲线及 mean/max/min 统计（见映射表子指标 key）。',
+                '每个面板一次返回全部统计量，勿按 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;
 }
 /** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
@@ -258,6 +298,38 @@ 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$/;
 /**
  * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
@@ -340,9 +412,9 @@ export function annotateProjectGroups(data) {
         content,
         _deduplicated: true,
         _uniqueReportCount: placed,
-        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后本页 ${placed} 份` +
             (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
-            '。可直接按项目组统计。',
+            '。按项目组统计请用本页 _uniqueReportCount / 各组 Records；跨页汇总须自行按 dataKey 去重，勿把各页条数简单相加。',
     };
 }
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
@@ -356,22 +428,74 @@ function asText(value) {
 export function makeHandler(op, client, defaultMaxRows, maxChars) {
     return async (args) => {
         try {
-            const apiVersion = args['apiVersion'] ?? op.defaultApiVersion;
+            const apiVersion = args['apiVersion'] ?? defaultApiVersionFor(op);
             const wantDownload = args['download'] ?? true;
             const maxRows = args['maxRows'] ?? defaultMaxRows;
+            const { filter: curveFilter, cleaned: argsForApi } = isIndicatorCurveDashboard(op.path)
+                ? extractCurveFilterArgs(args)
+                : { filter: {}, cleaned: args };
+            let acceptedDashboards = [];
+            let unknownDashboards = [];
+            if (typeof argsForApi['indicatorDashboards'] === 'string') {
+                const part = partitionIndicatorDashboards(argsForApi['indicatorDashboards']);
+                acceptedDashboards = part.accepted;
+                unknownDashboards = part.unknown;
+                if (part.all.length && !acceptedDashboards.length) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: asText({
+                                    error: 'PARAMETERS_WRONG',
+                                    message: `indicatorDashboards 全部无法识别：${unknownDashboards.join('、')}`,
+                                    _unknownDashboards: unknownDashboards,
+                                    _acceptedDashboards: [],
+                                    _hint: `这些是面板标识符，不是统计维度后缀。` +
+                                        `误传示例：${INDICATOR_DASHBOARD_NEGATIVE_EXAMPLES.join('、')}；` +
+                                        `合法示例：fps_avg、frametime@gt_40_pct。` +
+                                        `请调 gotonline_overview_indicator_dashboard_keys 获取全量 ${INDICATOR_DASHBOARD_KEYS.length} 个合法值。`,
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (acceptedDashboards.length) {
+                    argsForApi['indicatorDashboards'] = acceptedDashboards.join(',');
+                }
+            }
             const query = {};
             for (const p of op.query)
-                if (args[p.name] !== undefined)
-                    query[p.name] = args[p.name];
+                if (argsForApi[p.name] !== undefined)
+                    query[p.name] = argsForApi[p.name];
             let body;
             if (op.body.length) {
                 body = {};
                 for (const p of op.body)
-                    if (args[p.name] !== undefined)
-                        body[p.name] = args[p.name];
+                    if (argsForApi[p.name] !== undefined)
+                        body[p.name] = argsForApi[p.name];
             }
             const raw = await client.call(op.method, op.path, apiVersion, query, body);
-            const data = annotateProjectGroups(annotateCurveAxes(raw));
+            let processed = annotateProjectGroups(annotateCurveAxes(raw));
+            if (isIndicatorStatisticDashboard(op.path) && acceptedDashboards.length) {
+                processed = annotateStatisticDashboard(processed, acceptedDashboards, unknownDashboards);
+            }
+            else if (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);
+                    processed = annotateCurveAxes(processed);
+                }
+            }
+            const data = annotateDashboardEmptyResult(op, processed, args);
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;

package/dist/version-guide.d.ts

@@ -9,6 +9,11 @@
  * 挂到所有带 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;