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

package/dist/version-guide.js

@@ -17,8 +17,9 @@ export const INDICATOR_DASHBOARD_PANEL_GUIDE = [
     '  · 曲线接口（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（注意 @ 与阈值不可瞎猜）。',
+    '- 合法面板名先调 gotonline_overview_indicator_dashboard_keys（全量枚举）；勿传 fps_mean、frametime_min、android_pss_max 等统计字段名。',
+    '- 误传示例：fps_mean、android_pss_max、frametime_gt_40_pct（缺 @）、frametime_min；合法示例：fps_avg、android_memory_pss@max、frametime@gt_40_pct。',
+    '- Android PSS 峰值：只认面板 android_memory_pss@max；优先读返回顶层 pss_peak_kb / pss_peak_mb / pss_peak_frame（单位 KB）。',
     '- UE Overview 当前 Open API 未开放 custom/indicator dashboard 路径（会 24052），UE 温度汇总见 get_ue_overview_statistic_v2 的 temperature 段。',
 ].join('\n');
 /**
@@ -115,11 +116,19 @@ export const VERSION_GUIDE = {
         '【选用规则——务必先看】',
         '- 运行日志 1.0。Unity：解析日 < 2026-07-09；UE：提交日 ≤ 2026-03-25。',
         '- 新报告请用 gotonline_lg_runtime_log_entries_presign（运行日志 2.0）。',
+        '- 空列表 ≠「一定没有日志」：新报告误用本接口也可能返回空，应改调 2.0。',
     ].join('\n'),
     gotonline_lg_runtime_log_entries_presign: [
         '【选用规则——务必先看】',
         '- 运行日志 2.0（预签名）。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1。',
         '- 更早的报告请用 gotonline_overview_log_export。',
+        '- 若返回 80108 FILE_META_NOT_EXIST：Unity = 无 LG meta / 未解析 = 无可用日志数据；UE = 方案切换过，只能说「暂不支持获取当前报告的运行日志」，勿断定报告本身无日志。',
+    ].join('\n'),
+    gotonline_gpu_bound: [
+        '【选用规则——务必先看】',
+        '- 说「GPU Bound / GPU 主瓶颈」前必须先调本工具。',
+        '- 返回 [] 只能说「未检出 Bound」，禁止断言 GPU 是主要瓶颈。',
+        '- Overview 上的 WaitForVsync / RenderTexture 不能替代本接口。',
     ].join('\n'),
     gotonline_overview_group_export: [
         '【选用规则——务必先看】',
@@ -146,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: [
         '【选用规则——务必先看】',
@@ -184,18 +193,22 @@ export const VERSION_GUIDE = {
     gotonline_overview_stack_stutter_full_tree_presign: [
         '【选用规则——务必先看】',
         '- **全部卡顿帧已合并**的调用堆栈树 = 卡顿根因主入口（服务端聚合，无需客户端逐帧拉树再聚类）。',
+        '- 禁止把 WaitForVsync / Gfx.WaitForPresent 写成卡顿根因或 GPU Bound 证据。',
+        '- 说「GPU 主瓶颈」前必须先查 gotonline_gpu_bound；空数组只能说「未检出 Bound」。',
         '- 只要某一场景：用 stutter_scene_tree；只要某一尖峰帧细节：再用 stack_tree_frame。',
         STACK_ANALYSIS_GUIDE,
     ].join('\n'),
     gotonline_overview_stack_stutter_scene_tree_presign: [
         '【选用规则——务必先看】',
         '- **指定场景内卡顿帧已合并**的堆栈树；sceneIndex 来自 list_scenes 下标。',
+        '- 禁止把 WaitForVsync 当根因；GPU 主瓶颈结论须先查 gpu_bound。',
         '- 全报告卡顿用 stutter_full_tree；单帧深挖用 stack_tree_frame。',
         STACK_ANALYSIS_GUIDE,
     ].join('\n'),
     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,
@@ -203,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.8",
+  "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
+      }
     }
   }
 }