@uwa4d/openapi-mcp 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/version-guide.js

@@ -0,0 +1,223 @@
+/**
+ * 版本成对工具的选用规则。
+ *
+ * 集中手写、挂到 describe() 首段，避免散落在 notes 里被模型漏读。
+ * 不塞进 docs/ 生成链路——刷新官方文档镜像不会冲掉这里。
+ */
+/**
+ * indicatorDashboards 传参名称说明（面板标识符，非统计维度后缀）。
+ * 挂到所有带 indicatorDashboards 的工具 description，避免模型见 _max 只读峰值。
+ */
+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、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');
+/**
+ * 堆栈 / 卡顿工具路由。卡顿树已是「多帧合并后的根因视图」，
+ * 禁止误导成「对每个 >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: [
+        '【选用规则——务必先看】',
+        '- Unity：仅适用于解析日 < 2026-07-09 的 Overview 报告。新报告请改用 get_overview_statistic_v2。',
+        '- UE：仅适用于提交日 ≤ 2026-03-25 的 Overview 报告。新报告请改用 get_ue_overview_statistic_v2。',
+        '- 不确定日期时：先调 get_report_detail 看 createDate / engine / sdkVersion；或直接用复合工具 report_diagnosis / top_functions（内部自动路由）。',
+    ].join('\n'),
+    get_overview_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的 Overview 报告。',
+        '- 更早的 Unity 报告请用 get_overview_statistic_v1。UE 报告请用 get_ue_overview_statistic_v2（或旧报告用 get_overview_statistic_v1）。',
+        '- 不确定时用复合工具 report_diagnosis / top_functions，无需自己选版本。',
+    ].join('\n'),
+    get_ue_overview_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 UE。提交日 > 2026-03-25 的 Overview 报告。',
+        '- 更早的 UE 报告请用 get_overview_statistic_v1。Unity 报告请用 get_overview_statistic_v1 或 get_overview_statistic_v2。',
+        '- 单次批量最多 30 份（文档写 50，实测上限 30）。不确定时用复合工具自动路由。',
+    ].join('\n'),
+    get_scene_statistic_v1: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 < 2026-07-09 的 Overview 报告场景统计。',
+        '- 新报告请改用 get_scene_statistic_v2。',
+    ].join('\n'),
+    get_scene_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的 Overview 报告场景统计。',
+        '- 更早的报告请用 get_scene_statistic_v1。',
+    ].join('\n'),
+    gotonline_overview_custom_dashboard: [
+        '【选用规则——务必先看】',
+        '- 自定义面板统计 1.0（抽帧曲线）。不支持 GPU 类面板。',
+        '- 需要 GPU 指标或更多统计值类型时，改用 gotonline_overview_indicator_statistic_dashboard（2.0，需 SDK ≥ 2.5.1）。',
+        '- 逐帧曲线用 gotonline_overview_indicator_curve_dashboard（2.0，最多 3 个面板）。',
+        INDICATOR_DASHBOARD_PANEL_GUIDE,
+    ].join('\n'),
+    gotonline_overview_indicator_statistic_dashboard: [
+        '【选用规则——务必先看】',
+        '- 自定义面板统计 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: [
+        '【选用规则——务必先看】',
+        '- 自定义面板帧数据 2.0。需 SDK ≥ 2.5.1，最多 3 个面板；不支持内存类面板。',
+        '- 要统计值（含场景维度）用 gotonline_overview_indicator_statistic_dashboard。',
+        '- 【横轴——勿混用】外层 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: [
+        '【选用规则——务必先看】',
+        '- GPU 模式指标面板逐帧曲线，indicatorDashboards 为 GPU 面板映射表中的传参名称。',
+        INDICATOR_DASHBOARD_PANEL_GUIDE,
+    ].join('\n'),
+    gotonline_overview_memory_usage_snapshot: [
+        '【选用规则——务必先看】',
+        '- 资源快照帧号 1.0。仅适用于解析日 < 2026-07-09 的报告。',
+        '- 新报告请用 gotonline_overview_dump_frames（快照帧 2.0）。',
+    ].join('\n'),
+    gotonline_overview_dump_frames: [
+        '【选用规则——务必先看】',
+        '- 快照帧 2.0。仅适用于解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的报告。',
+        '- 更早的报告请用 gotonline_overview_memory_usage_snapshot。',
+    ].join('\n'),
+    gotonline_overview_log_export: [
+        '【选用规则——务必先看】',
+        '- 运行日志 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: [
+        '【选用规则——务必先看】',
+        '- UE 自定义函数组统计 1.0。仅适用于提交日 ≤ 2026-03-25 的 UE 报告。',
+        '- 新 UE 报告请用 gotonline_overview_method_group_statistic（需 Header api 版本 v1.0.2）。',
+    ].join('\n'),
+    gotonline_overview_method_group_statistic: [
+        '【选用规则——务必先看】',
+        '- 自定义函数组统计（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: [
+        '【选用规则——务必先看】',
+        '- **全部卡顿帧已合并**的调用堆栈树 = 卡顿根因主入口（服务端聚合，无需客户端逐帧拉树再聚类）。',
+        '- 禁止把 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 必填）。用于已知尖峰帧深挖，不是卡顿分析的第一步。',
+        '- 卡顿共性根因请先用 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) {
+    return VERSION_GUIDE[opId];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.10",
   "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",

package/spec/overrides.json

@@ -0,0 +1,26 @@
+{
+  "$comment": [
+    "官方文档与接口实际行为不符时的修正层。",
+    "生成 spec 时套用（见 scripts/parse-docs.ts），因此刷新 docs/ 下的文档不会冲掉这里的修正。",
+    "每条都必须写明 verifiedAt 与 evidence——没有实测依据不要往这里加，",
+    "否则下一个人无法判断该修正是否已经过时。",
+    "上游修好文档后应删除对应条目，而不是留着。"
+  ],
+  "operations": {
+    "get_ue_overview_statistic_v2": {
+      "reason": "文档称单次最多 50 份，实测上限为 30 份",
+      "verifiedAt": "2026-08-04",
+      "evidence": "30 个长 dataKey（参数串 1140 字符）成功；31 个短 dataKey（参数串 1094 字符，更短）失败并返回 20001，排除 URL 长度因素。49 个 key 逐个单查均正常，故确为批量条数限制。",
+      "replaceInText": [
+        {
+          "from": "最多 50 个",
+          "to": "最多 30 个（文档写 50，实测上限 30）"
+        },
+        {
+          "from": "单次请求最多查询 50 份报告",
+          "to": "单次请求最多查询 30 份报告（文档写 50，实测上限 30，超出会返回 20001）"
+        }
+      ]
+    }
+  }
+}