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

package/README.md

@@ -128,7 +128,15 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 - `_totalItems` — 主数据列表的条目总数
 - `_returnedChars` — 实际返回的字符数
 
-只在明确只要前 N 条时才传 `maxRows`。另有一道字符数兜底闸门（`--max-chars`，默认 50 万字符），正常报告不会触发；一旦触发会在 `_truncated` 里说清楚，此时可以用 `download: false` 取回 `dataPresignUrl` 自行下载完整文件。
+只在明确只要前 N 条时才传 `maxRows`。
+
+## 返回体积控制
+
+`--max-chars`（默认 50 万字符）对**所有**工具生效，不只是上面这类下载型接口。批量统计、报告列表这类接口一次查十几份报告就可能产生二十万字符以上的返回，容易撑爆模型上下文。
+
+超限时不会粗暴截断字符串——那样会切出无法解析的 JSON——而是按条目缩减，保证返回始终是完整合法的结构，并在 `_truncated` 里说明缩减到了多少条、该怎么拿到剩下的（分页或缩小批量）。
+
+如果你的客户端对单次工具输出有更严格的限制，把 `--max-chars` 调小即可。
 
 ## 曲线接口的双横轴
 

package/dist/tools.d.ts

@@ -28,6 +28,14 @@ export interface ToolResult {
  * 帧号范围和步长，并在点数对不上时给出警告，从结构上消除歧义。
  */
 export declare function annotateCurveAxes(data: unknown): unknown;
+/**
+ * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
+ * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
+ *
+ * 这里就地合并：按 link 里的 project= 判定真实归属，每份报告只保留在正确的组里。
+ * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
+ */
+export declare function annotateProjectGroups(data: unknown): unknown;
 export declare function makeHandler(op: Operation, client: UwaClient, defaultMaxRows: number, maxChars: number): (args: Record<string, unknown>) => Promise<ToolResult>;
 export declare function toolConfig(op: Operation): {
     title: string;

package/dist/tools.js

@@ -145,13 +145,58 @@ function summarize(payload, maxRows, maxChars) {
         rowTruncated = maxRows > 0 && lines.length > maxRows;
         body = rowTruncated ? lines.slice(0, maxRows).join('\n') : (payload.text ?? '');
     }
-    let text = typeof body === 'string' ? body : JSON.stringify(body, null, 2);
-    let charTruncated = false;
-    if (maxChars > 0 && text.length > maxChars) {
-        charTruncated = true;
-        text = text.slice(0, maxChars);
+    const fitted = fitToChars(body, maxChars);
+    return { rowTruncated, total, ...fitted };
+}
+const serialize = (v) => (typeof v === 'string' ? v : JSON.stringify(v, null, 2));
+/**
+ * 把返回内容压到字符上限以内。
+ *
+ * 直接按字符裁剪 JSON 会切出非法结构，模型没法解析。因此优先按条目缩减
+ * 主数据数组——二分找出能放下的最大条数，保留完整的 JSON 结构，
+ * 并在元信息里说明丢了多少。只有在没有数组可缩减时才退化为字符串截断。
+ */
+function fitToChars(body, maxChars) {
+    const full = serialize(body);
+    if (maxChars <= 0 || full.length <= maxChars) {
+        return { charTruncated: false, chars: full.length, body: full };
     }
-    return { rowTruncated, charTruncated, total, chars: text.length, body: text };
+    const rebuild = (n) => {
+        if (Array.isArray(body))
+            return serialize(body.slice(0, n));
+        if (body && typeof body === 'object') {
+            const obj = body;
+            const key = mainArrayKey(obj);
+            if (!key)
+                return null;
+            return serialize({ ...obj, [key]: obj[key].slice(0, n) });
+        }
+        return null;
+    };
+    const count = Array.isArray(body)
+        ? body.length
+        : body && typeof body === 'object'
+            ? (() => {
+                const key = mainArrayKey(body);
+                return key ? body[key].length : 0;
+            })()
+            : 0;
+    if (count > 0 && rebuild(0) !== null) {
+        // 二分出能放进上限的最大条数
+        let lo = 0;
+        let hi = count;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            const text = rebuild(mid);
+            if (text.length <= maxChars)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        const text = rebuild(lo);
+        return { charTruncated: true, kept: lo, chars: text.length, body: text };
+    }
+    return { charTruncated: true, chars: maxChars, body: full.slice(0, maxChars) };
 }
 function isObj(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -196,6 +241,93 @@ export function annotateCurveAxes(data) {
         _axisHint: '每条曲线按 _axisBinding[曲线名].xAxisSource 指定的横轴取值，不要统一使用外层 x_axis',
     };
 }
+const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
+/**
+ * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
+ * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
+ *
+ * 这里就地合并：按 link 里的 project= 判定真实归属，每份报告只保留在正确的组里。
+ * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
+ */
+export function annotateProjectGroups(data) {
+    if (!isObj(data) || !Array.isArray(data['content']))
+        return data;
+    const groups = data['content'].filter(isObj);
+    if (groups.length < 2)
+        return data;
+    // dataKey → 出现过的项目组；以及「该报告在哪个数组字段里、原文是什么」
+    const groupsOf = new Map();
+    const firstSeen = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid)
+            continue;
+        for (const [k, v] of Object.entries(g)) {
+            if (!RECORD_ARRAY_KEYS.test(k) || !Array.isArray(v))
+                continue;
+            for (const r of v) {
+                if (!isObj(r))
+                    continue;
+                const key = typeof r['dataKey'] === 'string' ? r['dataKey'] : null;
+                if (!key)
+                    continue;
+                if (!groupsOf.has(key))
+                    groupsOf.set(key, new Set());
+                groupsOf.get(key).add(gid);
+                if (!firstSeen.has(key)) {
+                    const fromLink = /[?&]project=(\d+)/.exec(String(r['link'] ?? ''))?.[1];
+                    firstSeen.set(key, { arrayKey: k, record: r, realGid: fromLink ?? gid });
+                }
+            }
+        }
+    }
+    const duplicated = [...groupsOf.values()].some((gs) => gs.size > 1);
+    if (!duplicated)
+        return data;
+    // 已知项目组壳子（保留名称、engine 等元信息），报告重新按真实归属灌入
+    const shells = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid || shells.has(gid))
+            continue;
+        const shell = { ...g };
+        for (const k of Object.keys(shell)) {
+            if (RECORD_ARRAY_KEYS.test(k))
+                shell[k] = [];
+        }
+        shells.set(gid, shell);
+    }
+    let placed = 0;
+    let orphaned = 0;
+    for (const { arrayKey, record, realGid } of firstSeen.values()) {
+        let shell = shells.get(realGid);
+        if (!shell) {
+            // link 指向的组不在本页 content 里——仍给出一份壳，避免报告丢失
+            shell = {
+                projectGroupId: Number.isFinite(Number(realGid)) ? Number(realGid) : realGid,
+                projectGroupName: `(id=${realGid})`,
+                engine: null,
+            };
+            shells.set(realGid, shell);
+            orphaned++;
+        }
+        if (!Array.isArray(shell[arrayKey]))
+            shell[arrayKey] = [];
+        shell[arrayKey].push(record);
+        placed++;
+    }
+    // 丢掉合并后一个报告都没有的空组（它们原先只有别人的副本）
+    const content = [...shells.values()].filter((g) => Object.entries(g).some(([k, v]) => RECORD_ARRAY_KEYS.test(k) && Array.isArray(v) && v.length > 0));
+    return {
+        ...data,
+        content,
+        _deduplicated: true,
+        _uniqueReportCount: placed,
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+            (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
+            '。可直接按项目组统计。',
+    };
+}
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
     if (typeof value === 'string')
@@ -221,20 +353,41 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
                     if (args[p.name] !== undefined)
                         body[p.name] = args[p.name];
             }
-            const data = annotateCurveAxes(await client.call(op.method, op.path, apiVersion, query, body));
+            const raw = await client.call(op.method, op.path, apiVersion, query, body);
+            const data = annotateProjectGroups(annotateCurveAxes(raw));
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
             if (!presignUrl || !wantDownload) {
-                return { content: [{ type: 'text', text: asText(data) }] };
+                // 非预签名接口同样可能很大（如报告列表 50 条约 56K 字符、
+                // 统计接口批量查十几份报告可达 20 万字符），这里必须同样设闸门，
+                // 否则会直接撑爆模型上下文。
+                const fitted = fitToChars(data, maxChars);
+                if (!fitted.charTruncated) {
+                    return { content: [{ type: 'text', text: asText(fitted.body) }] };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: asText({
+                                _truncated: `返回内容超过 ${maxChars} 字符上限，已缩减为 ${fitted.kept ?? 0} 条。` +
+                                    `请缩小查询范围后重试${op.query.some((p) => p.name === 'pageSize') ? '（如调小 pageSize 分页获取）' : '（如减少批量查询的条目数）'}，` +
+                                    `或在启动参数里调大 --max-chars。`,
+                                _returnedChars: fitted.chars,
+                            }),
+                        },
+                        { type: 'text', text: asText(fitted.body) },
+                    ],
+                };
             }
             const payload = await client.downloadPresign(presignUrl);
-            const { rowTruncated, charTruncated, total, chars, body: content } = summarize(payload, maxRows, maxChars);
+            const { rowTruncated, charTruncated, total, kept, chars, body: content } = summarize(payload, maxRows, maxChars);
             const notes = [];
             if (rowTruncated)
                 notes.push(`按 maxRows=${maxRows} 截断，去掉 maxRows 参数可取全量`);
             if (charTruncated) {
-                notes.push(`内容超过 ${maxChars} 字符上限已截断，尾部数据缺失。` +
+                notes.push(`内容超过 ${maxChars} 字符上限，已缩减为 ${kept ?? 0} 条。` +
                     `如需完整数据，用 download=false 拿 dataPresignUrl 自行下载，或启动时调大 --max-chars`);
             }
             const meta = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.1",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {

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）"
+        }
+      ]
+    }
+  }
+}

package/spec/uwa-openapi.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-04T07:36:54.873Z",
+  "generatedAt": "2026-08-04T09:11:08.206Z",
   "sourceDoc": "uwa-openapi-20260730.md",
   "operationCount": 55,
   "operations": [
@@ -928,14 +928,14 @@
           "type": "string",
           "required": false,
           "example": "1002,1003",
-          "description": "报告 recordId 列表，逗号分隔，最多 50 个。与 dataKeys 二选一，两者均填时取交集"
+          "description": "报告 recordId 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 dataKeys 二选一，两者均填时取交集"
         },
         {
           "name": "dataKeys",
           "type": "string",
           "required": false,
           "example": "testDataKey1,testDataKey2",
-          "description": "报告 dataKey 列表，逗号分隔，最多 50 个。与 recordIds 二选一，两者均填时取交集"
+          "description": "报告 dataKey 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 recordIds 二选一，两者均填时取交集"
         }
       ],
       "body": [],
@@ -956,7 +956,7 @@
           ],
           "notes": [
             "本接口仅支持 2026-03-25 之后提交的 UE Overview 报告；更早版本的报告应使用获取报告统计数据 1.0",
-            "单次请求最多查询 50 份报告，recordIds 与 dataKeys 至少填一个",
+            "单次请求最多查询 30 份报告（文档写 50，实测上限 30，超出会返回 20001），recordIds 与 dataKeys 至少填一个",
             "LLM 字段为 UE 专属低层内存分析数据，当报告未开启 LLM 采集时该字段可能为空数组 []"
           ],
           "returnRules": [],
@@ -966,14 +966,14 @@
               "type": "string",
               "required": false,
               "example": "1002,1003",
-              "description": "报告 recordId 列表，逗号分隔，最多 50 个。与 dataKeys 二选一，两者均填时取交集"
+              "description": "报告 recordId 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 dataKeys 二选一，两者均填时取交集"
             },
             {
               "name": "dataKeys",
               "type": "string",
               "required": false,
               "example": "testDataKey1,testDataKey2",
-              "description": "报告 dataKey 列表，逗号分隔，最多 50 个。与 recordIds 二选一，两者均填时取交集"
+              "description": "报告 dataKey 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 recordIds 二选一，两者均填时取交集"
             }
           ],
           "body": [],