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

package/dist/version-guide.js

@@ -11,12 +11,34 @@
 export const INDICATOR_DASHBOARD_PANEL_GUIDE = [
     '【indicatorDashboards 传参名称——勿按后缀猜统计维度】',
     '- 传参名（如 temperature_max、fps_avg、drawcall_cnt_max）是**面板标识符**，_max / _avg / @max 等为历史命名，**不限制**返回 mean / maximum / min 等统计类型。',
+    '- 【返回粒度】每个面板一次返回其下所有子指标的全部统计量（mean / min / maximum / maximum_frame / 专属指标，以及 scene_*），',
+    '  无需也无法按统计量拆成多个面板名（勿传 fps_mean、fps_max、fps_min）。面板→子指标展开见返回体 group；入参→出参映射见 _paramFieldMap。',
     '- 例：temperature_max 面板含子指标 temperature、android_temper_cpu、android_temper_gpu、android_temper_battery；',
     '  · 曲线接口（indicator_curve / custom_dashboard）→ 各子指标逐帧曲线；',
     '  · 统计 2.0（indicator_statistic_dashboard）→ statistic 下 *_mean / *_maximum / *_min 及 scene_* 等全量统计。',
     '- 查温度曲线/均值/峰值：Unity Overview 且 SDK ≥ 2.5.1 时传 indicatorDashboards=temperature_max，再读 y_axis 或 statistic；勿仅看 get_overview_statistic 的汇总段。',
+    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys（全量枚举）；勿传 fps_mean、frametime_min 等统计字段名。',
+    '- 误传示例：fps_mean、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、frametime@gt_40_pct（注意 @ 与阈值不可瞎猜）。',
     '- UE Overview 当前 Open API 未开放 custom/indicator dashboard 路径（会 24052），UE 温度汇总见 get_ue_overview_statistic_v2 的 temperature 段。',
 ].join('\n');
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >40ms 帧循环拉指定帧树再聚类」。
+ */
+export const STACK_ANALYSIS_GUIDE = [
+    '【堆栈/卡顿选用——务必先看】',
+    '- 卡顿根因主路径：用**卡顿聚合树**（已合并全部/场景内卡顿帧），不要对每个慢帧循环拉指定帧树。',
+    '- 工具分工：',
+    '  · 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 → **单帧**完整树（仅尖峰深挖，如已知 frameId=8439）',
+    '  · gotonline_overview_stack_overall_tree_presign → 整线程全量堆栈（非卡顿专用；看持续税/全局热点）',
+    '  · gotonline_overview_stack_sample_frame_presign → 树结点逐帧曲线',
+    '- 慢帧占比/挑代表帧：indicator 面板 frametime@gt_40_pct（统计或 curve+valueGt）；根因归因仍走卡顿聚合树。',
+    '- 读任何堆栈树前必须配合 gotonline_overview_stack_id_map（树里是 methodId）。',
+    '- 错误假设：❌「没有批量帧树就无法做卡顿根因」——总体/场景卡顿树就是合并结果。',
+].join('\n');
 /** 写入工具 description 的「选用规则」块，key 为 operation id。 */
 export const VERSION_GUIDE = {
     get_overview_statistic_v1: [
@@ -59,6 +81,8 @@ export const VERSION_GUIDE = {
         '- 自定义面板统计 2.0。需 SDK ≥ 2.5.1，支持 GPU 指标，最多 15 个面板。',
         '- 旧接口（抽帧、无 GPU）见 gotonline_overview_custom_dashboard。',
         '- 只要逐帧曲线不要统计值时用 gotonline_overview_indicator_curve_dashboard。',
+        '- 返回 statistic 为空时优先怀疑 indicatorDashboards 传错；响应可能含 _hint / _unknownDashboards。',
+        '- 响应可能含 _paramFieldMap（入参面板→出参字段）、_duplicateFlatAliases、_sceneUnitNote（scene_* 补单位标注）。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_overview_indicator_curve_dashboard: [
@@ -68,6 +92,8 @@ export const VERSION_GUIDE = {
         '- 【横轴——勿混用】外层 x_axis 为逐帧共享横轴（1、2、3…）；y_axis.{指标名}.x_axis 为该曲线专属横轴（常见步长 30：0、30、60…）。',
         '- 读取某条曲线时：若存在专属 x_axis 必须用专属，否则才用外层共享 x_axis。把共享横轴套到 FPS 等专属曲线会错位。',
         '- 响应另含 _axisBinding / _axisHint，按其中 xAxisSource 取值即可。',
+        '- 【过滤——MCP 侧】可选 valueGt / valueLt / topN / returnFramesOnly：只返回超阈值或 TopN 点，适合慢帧列表（例：frametime@gt_40_pct + valueGt=40）。',
+        '- 慢帧列表 ≠ 卡顿根因：根因请用 stutter_full_tree / stutter_scene_tree（卡顿帧已合并），不要对 valueGt 结果逐帧拉 stack_tree_frame。',
         INDICATOR_DASHBOARD_PANEL_GUIDE,
     ].join('\n'),
     gotonline_gpu_curve: [
@@ -102,8 +128,82 @@ export const VERSION_GUIDE = {
     ].join('\n'),
     gotonline_overview_method_group_statistic: [
         '【选用规则——务必先看】',
-        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25，且 api 版本须 v1.0.2）。',
+        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25）。',
+        '- **MCP 默认 apiVersion=v1.0.2**（勿用 v1.0.1，会参数错误）。需要旧行为时显式传 apiVersion=v1.0.1。',
         '- UE 旧报告请用 gotonline_overview_group_export。',
+        '- 未配置自定义函数组时 data=[]；Overview 热点函数曲线优先用 method_idmap_statistic + method_curve_presign，不必依赖函数组。',
+    ].join('\n'),
+    gotonline_overview_method_idmap_statistic: [
+        '【选用规则——务必先看】',
+        '- **仅 Overview 报告**；返回 id_map 全部函数的统计（不去重、不过滤）。',
+        '- stackTestMode（Overview 堆栈采集模式）决定哪些字段有值：',
+        '  · CPU_ONLY：selfTimeMean / totalTimeMean / callCountTotal',
+        '  · LUA_MEM_ONLY：callCountTotal / selfMemoryMean / selfMemoryTotal',
+        '  · CPU_AND_LUA_MEM：以上全部；UE 固定 CPU_ONLY',
+        '- Unity：dataKey/recordId；UE：另传 threadName（如 GameThread）。Header v1.0.2。',
+        '- 复合工具 top_functions（Overview）会读 stackTestMode 并校验 metric；Mono 报告不走此规则。',
+    ].join('\n'),
+    gotonline_overview_method_curve: [
+        '【选用规则——务必先看】',
+        '- v1.0.1 直出曲线 JSON（按 stackMethodName 或 stackMethodId）。',
+        '- **MCP 与 Open API 推荐改用 gotonline_overview_method_curve_presign（v1.0.2）**：OSS 预签名，仅传 stackMethodId。',
+        '- 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。',
+        '- 不要用 v1.0.1 gotonline_overview_method_curve 除非必须服务端直出。',
+        '- stackMethodId 优先从 gotonline_overview_method_idmap_statistic 获取。',
+    ].join('\n'),
+    gotonline_overview_indicator_dashboard_keys: [
+        '【选用规则——务必先看】',
+        '- 返回 Overview 指标面板传参名称全量列表（indicatorDashboards 合法取值）。',
+        '- 无需 dataKey/recordId；与 statistic/curve dashboard 调用前校验同源。',
+        '- 勿把 fps_mean、frametime_min 等 statistic 内字段名当作面板名。',
+        '- 合法示例：fps_avg、drawcall_cnt_max、frametime@gt_40_pct、temperature_max。',
+        INDICATOR_DASHBOARD_PANEL_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_id_map: [
+        '【选用规则——务必先看】',
+        '- 函数 ID ↔ 名称映射。解析任何 stack_*_tree / stutter_*_tree 前先调本工具。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_overall_tree_presign: [
+        '【选用规则——务必先看】',
+        '- 指定线程的**全量**调用堆栈树（含非卡顿帧），适合持续税/全局热点。',
+        '- 只要卡顿根因：改用 stutter_full_tree / stutter_scene_tree，勿用本接口代替卡顿聚合。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_presign: [
+        '【选用规则——务必先看】',
+        '- 卡顿**帧列表**（帧号 + 卡顿类型耗时拆分），不是堆栈树。',
+        '- 要卡顿根因堆栈：接着调 stutter_full_tree_presign（或场景版 stutter_scene_tree）。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_full_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **全部卡顿帧已合并**的调用堆栈树 = 卡顿根因主入口（服务端聚合，无需客户端逐帧拉树再聚类）。',
+        '- 只要某一场景：用 stutter_scene_tree；只要某一尖峰帧细节：再用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_stutter_scene_tree_presign: [
+        '【选用规则——务必先看】',
+        '- **指定场景内卡顿帧已合并**的堆栈树；sceneIndex 来自 list_scenes 下标。',
+        '- 全报告卡顿用 stutter_full_tree；单帧深挖用 stack_tree_frame。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_tree_frame_presign: [
+        '【选用规则——务必先看】',
+        '- **单帧**完整堆栈树（frameId 必填）。用于已知尖峰帧深挖，不是卡顿分析的第一步。',
+        '- 卡顿共性根因请先用 stutter_full_tree / stutter_scene_tree（已是多帧合并结果）。',
+        '- ❌ 不要对 frametime valueGt 筛出的每个慢帧循环调用本工具来「聚类」。',
+        STACK_ANALYSIS_GUIDE,
+    ].join('\n'),
+    gotonline_overview_stack_sample_frame_presign: [
+        '【选用规则——务必先看】',
+        '- 堆栈树某个结点的逐帧曲线；结点 id 来自树文件。',
+        STACK_ANALYSIS_GUIDE,
     ].join('\n'),
 };
 export function versionGuideFor(opId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.5",
+  "version": "0.2.0-beta.8",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "scripts": {
-    "gen": "tsx scripts/parse-docs.ts",
+    "gen": "tsx scripts/extract-dashboard-keys.ts && tsx scripts/parse-docs.ts",
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
     "smoke": "tsx scripts/smoke-test.ts",