@uwa4d/openapi-mcp 0.2.0-beta.14 → 0.2.0-beta.16

package/dist/version-guide.js

@@ -155,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: [
         '【选用规则——务必先看】',
@@ -208,6 +208,7 @@ export const VERSION_GUIDE = {
     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,
@@ -215,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.14",
+  "version": "0.2.0-beta.16",
   "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
+      }
     }
   }
 }

package/spec/uwa-openapi.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-07T02:47:15.805Z",
+  "generatedAt": "2026-08-12T10:13:51.372Z",
   "sourceDoc": "uwa-openapi-20260730.md",
   "operationCount": 59,
   "operations": [
@@ -76,7 +76,7 @@
             }
           ],
           "body": [],
-          "docLine": 5628
+          "docLine": 5640
         },
         {
           "title": "获取报告统计数据",
@@ -116,7 +116,7 @@
             }
           ],
           "body": [],
-          "docLine": 8268
+          "docLine": 8326
         }
       ]
     },
@@ -193,7 +193,7 @@
             }
           ],
           "body": [],
-          "docLine": 6453
+          "docLine": 6465
         }
       ]
     },
@@ -269,7 +269,7 @@
             }
           ],
           "body": [],
-          "docLine": 6323
+          "docLine": 6335
         }
       ]
     },
@@ -364,7 +364,7 @@
             }
           ],
           "body": [],
-          "docLine": 5942
+          "docLine": 5954
         }
       ]
     },
@@ -483,7 +483,7 @@
             }
           ],
           "body": [],
-          "docLine": 6835
+          "docLine": 6847
         }
       ]
     },
@@ -645,7 +645,7 @@
             }
           ],
           "body": [],
-          "docLine": 6752
+          "docLine": 6764
         }
       ]
     },
@@ -753,7 +753,7 @@
             }
           ],
           "body": [],
-          "docLine": 6704
+          "docLine": 6716
         }
       ]
     },
@@ -977,7 +977,7 @@
             }
           ],
           "body": [],
-          "docLine": 6946
+          "docLine": 6958
         }
       ]
     },
@@ -1157,7 +1157,7 @@
             }
           ],
           "body": [],
-          "docLine": 5829
+          "docLine": 5841
         }
       ]
     },
@@ -1232,7 +1232,7 @@
             }
           ],
           "body": [],
-          "docLine": 5745
+          "docLine": 5757
         }
       ]
     },
@@ -1310,7 +1310,7 @@
             }
           ],
           "body": [],
-          "docLine": 5194
+          "docLine": 5206
         }
       ]
     },
@@ -1462,7 +1462,7 @@
             }
           ],
           "body": [],
-          "docLine": 6231
+          "docLine": 6243
         }
       ]
     },
@@ -1534,7 +1534,7 @@
             }
           ],
           "body": [],
-          "docLine": 6141
+          "docLine": 6153
         }
       ]
     },
@@ -1611,7 +1611,7 @@
             }
           ],
           "body": [],
-          "docLine": 6051
+          "docLine": 6063
         }
       ]
     },
@@ -1717,7 +1717,7 @@
             }
           ],
           "body": [],
-          "docLine": 4305
+          "docLine": 4317
         }
       ]
     },
@@ -1809,7 +1809,7 @@
             }
           ],
           "body": [],
-          "docLine": 4066
+          "docLine": 4078
         }
       ]
     },
@@ -1916,7 +1916,7 @@
             }
           ],
           "body": [],
-          "docLine": 4209
+          "docLine": 4221
         }
       ]
     },
@@ -2109,7 +2109,7 @@
             }
           ],
           "body": [],
-          "docLine": 3470
+          "docLine": 3482
         },
         {
           "title": "自定义变量曲线数据",
@@ -2164,7 +2164,7 @@
             }
           ],
           "body": [],
-          "docLine": 7466
+          "docLine": 7478
         }
       ]
     },
@@ -2244,7 +2244,7 @@
             }
           ],
           "body": [],
-          "docLine": 3287
+          "docLine": 3299
         },
         {
           "title": "自定义变量 idmap",
@@ -2284,7 +2284,7 @@
             }
           ],
           "body": [],
-          "docLine": 7287
+          "docLine": 7299
         }
       ]
     },
@@ -2420,7 +2420,7 @@
               "description": "子属性 ID，Vector 类型变量必传，其他类型忽略"
             }
           ],
-          "docLine": 3363
+          "docLine": 3375
         },
         {
           "title": "自定义变量统计数据",
@@ -2478,7 +2478,7 @@
               "description": "子属性 ID，Vector 类型必传，来自 idmap 的 dimensionList[].id"
             }
           ],
-          "docLine": 7361
+          "docLine": 7373
         }
       ]
     },
@@ -2555,7 +2555,7 @@
             }
           ],
           "body": [],
-          "docLine": 3637
+          "docLine": 3649
         }
       ]
     },
@@ -2629,7 +2629,7 @@
             }
           ],
           "body": [],
-          "docLine": 3698
+          "docLine": 3710
         }
       ]
     },
@@ -2705,7 +2705,7 @@
             }
           ],
           "body": [],
-          "docLine": 7556
+          "docLine": 7568
         }
       ]
     },
@@ -3059,7 +3059,7 @@
             }
           ],
           "body": [],
-          "docLine": 7165
+          "docLine": 7177
         }
       ]
     },
@@ -3138,7 +3138,7 @@
             }
           ],
           "body": [],
-          "docLine": 5101
+          "docLine": 5113
         },
         {
           "title": "运行日志",
@@ -3177,7 +3177,7 @@
             }
           ],
           "body": [],
-          "docLine": 7883
+          "docLine": 7941
         }
       ]
     },
@@ -3266,7 +3266,7 @@
             }
           ],
           "body": [],
-          "docLine": 3756
+          "docLine": 3768
         }
       ]
     },
@@ -3341,7 +3341,7 @@
             }
           ],
           "body": [],
-          "docLine": 3580
+          "docLine": 3592
         }
       ]
     },
@@ -3448,7 +3448,7 @@
             }
           ],
           "body": [],
-          "docLine": 3198
+          "docLine": 3210
         }
       ]
     },
@@ -3457,7 +3457,7 @@
       "name": "函数曲线预签名",
       "method": "GET",
       "path": "/openapi/v1/data/gotonline/overview/method/curve/presign",
-      "summary": "获取指定函数逐帧曲线（预签名 JSON，v1.0.2，仅 stackMethodId）",
+      "summary": "Unity 指定函数逐帧曲线（预签名，v1.0.2）",
       "engines": [
         "unity",
         "unreal"
@@ -3487,40 +3487,47 @@
         {
           "name": "stackMethodId",
           "type": "string",
-          "required": true,
+          "required": false,
           "example": "4096133288",
-          "description": "[Unity] 函数 ID（必填） [UE] 函数 ID（Open API 必填）"
+          "description": "函数 ID；与 stackMethodName 至少传一个，同时传时优先 id"
+        },
+        {
+          "name": "stackMethodName",
+          "type": "string",
+          "required": false,
+          "example": "Animators.WriteJob",
+          "description": "函数名称；与 stackMethodId 至少传一个"
         },
         {
           "name": "threadName",
           "type": "string",
-          "required": true,
+          "required": false,
           "example": "GameThread",
-          "description": "[Unity] UE 必传 [UE] UE 必传。Unity 无需此参数"
+          "description": "UE 必传。Unity 无需此参数"
         }
       ],
       "body": [],
       "returnsPresignUrl": true,
       "variants": [
         {
-          "title": "函数曲线预签名",
+          "title": "函数曲线预签名（Unity）",
           "docEngines": [
             "unity"
           ],
           "supportedEngines": [
-            "unity",
-            "unreal"
+            "unity"
           ],
           "module": "overview",
-          "description": "获取指定函数的逐帧曲线（self_times / total_times / call_counts）。返回 OSS 预签名 JSON。Open API 仅支持 stackMethodId 入参（不支持函数名）。",
+          "description": "获取指定函数的逐帧曲线（self_times / total_times / call_counts）。返回 OSS 预签名 JSON。完整说明见 函数曲线预签名（Unity）；UE 见 自定义函数组曲线数据。",
           "apiVersions": [
             "v1.0.2"
           ],
           "sdkRequirement": ">= 2.5.1",
-          "prerequisite": "stackMethodId 需从函数 idmap 统计或自定义函数组统计获取。",
+          "prerequisite": "使用 stackMethodId 时：可从函数 idmap 统计（Unity）或自定义函数组统计获取 使用 stackMethodName 时：同名函数会按 totalTimeMean 取较大者；需精确定位请传 id",
           "notes": [
-            "Header 须 v1.0.2；逐帧直出请用 v1.0.1 method/curve（按名称，不推荐 Open API 使用）",
-            "Unity 无需 threadName；UE 必须传 threadName"
+            "Header 须 v1.0.2",
+            "同名函数建议传 stackMethodId 以避免歧义",
+            "尖峰帧下钻见 指定帧堆栈树（Unity）"
           ],
           "returnRules": [],
           "query": [
@@ -3541,20 +3548,20 @@
             {
               "name": "stackMethodId",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "4096133288",
-              "description": "函数 ID（必填）"
+              "description": "函数 ID；与 name 至少传一个，同时传时优先"
             },
             {
-              "name": "threadName",
+              "name": "stackMethodName",
               "type": "string",
-              "required": true,
-              "example": "GameThread",
-              "description": "UE 必传"
+              "required": false,
+              "example": "Animators.WriteJob",
+              "description": "函数名称；与 id 至少传一个"
             }
           ],
           "body": [],
-          "docLine": 3153
+          "docLine": 3160
         },
         {
           "title": "自定义函数组曲线数据",
@@ -3562,19 +3569,18 @@
             "unreal"
           ],
           "supportedEngines": [
-            "unity",
             "unreal"
           ],
           "module": "overview",
-          "description": "获取 Overview 报告中指定函数的逐帧曲线数据。Open API 请使用本接口（v1.0.2 预签名，仅 stackMethodId）；v1.0.1 直出见 Unity 章节 method/curve。",
+          "description": "获取 UE Overview 报告中指定函数的逐帧曲线数据，包含每帧自身耗时、总耗时、调用次数。返回预签名下载地址，下载后为 JSON 格式。仅适用于 2026-03-25 之后提交的报告，UE 引擎必须指定线程名称。",
           "apiVersions": [
             "v1.0.2"
           ],
-          "prerequisite": "stackMethodId 需从函数 idmap 统计或自定义函数组统计数据 2.0获取。",
+          "prerequisite": "使用 stackMethodId：可从函数 idmap 统计（UE）或自定义函数组统计数据 2.0获取 使用 stackMethodName：按名称解析；同名时建议传 id 精确定位",
           "notes": [
             "接口版本需传 v1.0.2（Header x-uwa-api-minor-version）",
-            "Open API 仅支持 stackMethodId，不支持 stackMethodName",
-            "UE 下 threadName 必传；Unity 无需 threadName",
+            "stackMethodId / stackMethodName 至少传一个；同时传时优先 id",
+            "threadName 必传（含 GameThread）",
             "URL 有效期 600 秒，过期后需重新调用本接口获取新地址",
             "本接口仅支持 2026-03-25 之后提交的报告"
           ],
@@ -3597,20 +3603,27 @@
             {
               "name": "threadName",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "GameThread",
-              "description": "UE 必传。Unity 无需此参数"
+              "description": "必传。GameThread、RHIThread、RenderThread、FAsyncLoadingThread 等"
             },
             {
               "name": "stackMethodId",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "329",
-              "description": "函数 ID（Open API 必填）"
+              "description": "函数 ID；与 name 至少传一个，同时传时优先"
+            },
+            {
+              "name": "stackMethodName",
+              "type": "string",
+              "required": false,
+              "example": "Tick_SlateInput",
+              "description": "函数名称；与 id 至少传一个"
             }
           ],
           "body": [],
-          "docLine": 7783
+          "docLine": 7837
         }
       ]
     },
@@ -3631,7 +3644,7 @@
         "v1.0.1",
         "v1.0.2"
       ],
-      "defaultApiVersion": "v1.0.2",
+      "defaultApiVersion": "v1.0.1",
       "query": [
         {
           "name": "recordId",
@@ -3738,13 +3751,13 @@
             {
               "name": "threadName",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "GameThread",
               "description": "线程名称。UE 必传，可选值：GameThread、RHIThread、RenderThread、FAsyncLoadingThread；Unity 不传时默认主线程"
             }
           ],
           "body": [],
-          "docLine": 7651
+          "docLine": 7663
         }
       ]
     },
@@ -3753,7 +3766,7 @@
       "name": "函数 idmap 统计",
       "method": "GET",
       "path": "/openapi/v1/data/gotonline/overview/method/idmap/statistic",
-      "summary": "获取全部函数的自身/总耗时/调用次数统计（v1.0.2，不去重）",
+      "summary": "Unity 全部函数统计（v1.0.2，不去重）",
       "engines": [
         "unity",
         "unreal"
@@ -3783,25 +3796,24 @@
         {
           "name": "threadName",
           "type": "string",
-          "required": true,
+          "required": false,
           "example": "GameThread",
-          "description": "UE 必传。线程名：GameThread、RHIThread、RenderThread、FAsyncLoadingThread"
+          "description": "UE 必传（GameThread / RHIThread / RenderThread / FAsyncLoadingThread 等）。Unity 无需此参数（不传=主线程）"
         }
       ],
       "body": [],
       "returnsPresignUrl": false,
       "variants": [
         {
-          "title": "函数 idmap 统计",
+          "title": "函数 idmap 统计（Unity）",
           "docEngines": [
             "unity"
           ],
           "supportedEngines": [
-            "unity",
-            "unreal"
+            "unity"
           ],
           "module": "overview",
-          "description": "返回 id_map / stats_id_map 中全部函数的统计值（selfTimeMean、totalTimeMean、callCountTotal），不去重、不过滤无统计项。适用于需要完整函数列表或按 stackMethodId 拉曲线的场景。SDK 版本需 >= 2.5.1。",
+          "description": "返回 Unity Overview 报告 id_map 中全部函数的统计值（selfTimeMean、totalTimeMean、callCountTotal 等），不去重、不过滤无统计项。适用于需要完整函数列表或按 stackMethodId 拉曲线的场景。SDK 版本需 >= 2.5.1。",
           "apiVersions": [
             "v1.0.2"
           ],
@@ -3812,6 +3824,44 @@
             "逐帧曲线请用 method/curve/presign v1.0.2，传本接口返回的 stackMethodId"
           ],
           "returnRules": [],
+          "query": [
+            {
+              "name": "recordId",
+              "type": "string",
+              "required": false,
+              "example": "1002",
+              "description": "报告 recordId。与 dataKey 二选一"
+            },
+            {
+              "name": "dataKey",
+              "type": "string",
+              "required": false,
+              "example": "testDataKey1",
+              "description": "报告 dataKey。与 recordId 二选一"
+            }
+          ],
+          "body": [],
+          "docLine": 3015
+        },
+        {
+          "title": "函数 idmap 统计（UE）",
+          "docEngines": [
+            "unreal"
+          ],
+          "supportedEngines": [
+            "unreal"
+          ],
+          "module": "overview",
+          "description": "获取 UE Overview 报告中指定线程下全部函数的统计值（自身耗时、总耗时、调用次数等），不去重、不过滤无统计项。仅适用于 2026-03-25 之后提交的报告，UE 引擎必须指定线程名称。",
+          "apiVersions": [
+            "v1.0.2"
+          ],
+          "notes": [
+            "仅适用于 2026-03-25 之后提交的报告",
+            "接口版本须传 v1.0.2；threadName 必传（含 GameThread）",
+            "不同线程需分别调用；后续曲线接口请传相同 threadName"
+          ],
+          "returnRules": [],
           "query": [
             {
               "name": "recordId",
@@ -3830,13 +3880,13 @@
             {
               "name": "threadName",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "GameThread",
-              "description": "UE 必传。线程名：GameThread、RHIThread、RenderThread、FAsyncLoadingThread"
+              "description": "必传。GameThread、RHIThread、RenderThread、FAsyncLoadingThread 等"
             }
           ],
           "body": [],
-          "docLine": 3015
+          "docLine": 7795
         }
       ]
     },
@@ -3910,7 +3960,7 @@
             }
           ],
           "body": [],
-          "docLine": 4415
+          "docLine": 4427
         }
       ]
     },
@@ -4004,7 +4054,7 @@
             }
           ],
           "body": [],
-          "docLine": 4858
+          "docLine": 4870
         }
       ]
     },
@@ -4097,7 +4147,7 @@
             }
           ],
           "body": [],
-          "docLine": 4697
+          "docLine": 4709
         }
       ]
     },
@@ -4176,7 +4226,7 @@
             }
           ],
           "body": [],
-          "docLine": 4598
+          "docLine": 4610
         }
       ]
     },
@@ -4282,7 +4332,7 @@
             }
           ],
           "body": [],
-          "docLine": 4506
+          "docLine": 4518
         }
       ]
     },
@@ -4387,7 +4437,7 @@
             }
           ],
           "body": [],
-          "docLine": 3979
+          "docLine": 3991
         }
       ]
     },
@@ -4494,7 +4544,7 @@
             }
           ],
           "body": [],
-          "docLine": 4777
+          "docLine": 4789
         }
       ]
     },
@@ -4599,7 +4649,7 @@
             }
           ],
           "body": [],
-          "docLine": 3873
+          "docLine": 3885
         }
       ]
     },
@@ -4719,7 +4769,7 @@
             }
           ],
           "body": [],
-          "docLine": 7227
+          "docLine": 7239
         }
       ]
     },
@@ -4856,7 +4906,7 @@
             }
           ],
           "body": [],
-          "docLine": 7084
+          "docLine": 7096
         }
       ]
     },
@@ -4895,16 +4945,16 @@
         {
           "name": "sampleId",
           "type": "integer",
-          "required": true,
+          "required": false,
           "example": "42",
-          "description": "结点 id。UE 必传。Unity 不传则返回全帧聚合曲线"
+          "description": "结点 id。UE 必传。Unity 不传则返回全帧聚合曲线（仅主线程）"
         },
         {
           "name": "threadId",
           "type": "string",
-          "required": true,
+          "required": false,
           "example": "GameThread",
-          "description": "UE 必传。Unity 忽略"
+          "description": "UE 必传。Unity：不传 = 主线程；传子线程 id/名 = 该子线程结点曲线（须同时传 sampleId）"
         }
       ],
       "body": [],
@@ -4945,20 +4995,20 @@
             {
               "name": "sampleId",
               "type": "integer",
-              "required": true,
+              "required": false,
               "example": "42",
-              "description": "结点 id。UE 必传。Unity 不传则返回全帧聚合曲线"
+              "description": "结点 id。UE 必传。Unity 不传则返回全帧聚合曲线（仅主线程）"
             },
             {
               "name": "threadId",
               "type": "string",
-              "required": true,
+              "required": false,
               "example": "GameThread",
-              "description": "UE 必传。Unity 忽略"
+              "description": "UE 必传。Unity：不传 = 主线程；传子线程 id/名 = 该子线程结点曲线（须同时传 sampleId）"
             }
           ],
           "body": [],
-          "docLine": 3117
+          "docLine": 3124
         }
       ]
     },
@@ -5041,7 +5091,7 @@
             }
           ],
           "body": [],
-          "docLine": 5323
+          "docLine": 5335
         },
         {
           "title": "获取卡顿帧列表",
@@ -5086,7 +5136,7 @@
             }
           ],
           "body": [],
-          "docLine": 7974
+          "docLine": 8032
         }
       ]
     },
@@ -5167,7 +5217,7 @@
             }
           ],
           "body": [],
-          "docLine": 5435
+          "docLine": 5447
         },
         {
           "title": "获取卡顿帧汇总堆栈树",
@@ -5210,7 +5260,7 @@
             }
           ],
           "body": [],
-          "docLine": 8082
+          "docLine": 8140
         }
       ]
     },
@@ -5305,7 +5355,7 @@
             }
           ],
           "body": [],
-          "docLine": 5530
+          "docLine": 5542
         },
         {
           "title": "获取指定场景卡顿帧汇总堆栈树",
@@ -5355,7 +5405,7 @@
             }
           ],
           "body": [],
-          "docLine": 8173
+          "docLine": 8231
         }
       ]
     },
@@ -5364,7 +5414,7 @@
       "name": "指定帧堆栈树",
       "method": "GET",
       "path": "/openapi/v1/data/gotonline/overview/stack/tree/frame/presign",
-      "summary": "获取指定帧的调用堆栈树（预签名）",
+      "summary": "Unity 指定帧调用堆栈树（预签名）",
       "engines": [
         "unity",
         "unreal"
@@ -5401,25 +5451,24 @@
         {
           "name": "threadId",
           "type": "string",
-          "required": true,
-          "example": "GameThread",
-          "description": "UE 必传（线程 id 或线程名）。Unity 主线程可不传"
+          "required": false,
+          "example": "4261395632",
+          "description": "UE 必传（线程 id 或线程名，含 GameThread）。Unity：不传=主线程；传子线程 id/名=该子线程指定帧树"
         }
       ],
       "body": [],
       "returnsPresignUrl": true,
       "variants": [
         {
-          "title": "指定帧堆栈树",
+          "title": "指定帧堆栈树（Unity）",
           "docEngines": [
             "unity"
           ],
           "supportedEngines": [
-            "unity",
-            "unreal"
+            "unity"
           ],
           "module": "overview",
-          "description": "获取指定帧的函数调用堆栈树。返回 OSS 预签名地址，下载后为 gzip 压缩的树结构文件（与面板 stack/tree/frame 同源）。",
+          "description": "获取指定帧的函数调用堆栈树。返回 OSS 预签名地址，下载后为 gzip 压缩的树结构文件。完整说明见 指定帧堆栈树（Unity）；UE 见 指定帧堆栈树（UE）。",
           "apiVersions": [
             "v1.0.1"
           ],
@@ -5451,13 +5500,13 @@
             {
               "name": "threadId",
               "type": "string",
-              "required": true,
-              "example": "GameThread",
-              "description": "UE 必传（线程 id 或线程名）。Unity 主线程可不传"
+              "required": false,
+              "example": "4261395632",
+              "description": "不传 = 主线程；传子线程 id/名 = 该子线程指定帧树（见线程 idmap）"
             }
           ],
           "body": [],
-          "docLine": 3081
+          "docLine": 3088
         }
       ]
     },
@@ -5532,7 +5581,7 @@
             }
           ],
           "body": [],
-          "docLine": 4979
+          "docLine": 4991
         }
       ]
     },
@@ -5716,7 +5765,7 @@
             }
           ],
           "body": [],
-          "docLine": 6554
+          "docLine": 6566
         }
       ]
     },