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

package/dist/client.js

@@ -1,22 +1,12 @@
 import { gunzipSync } from 'node:zlib';
 import { authHeaders } from './auth.js';
+import { resolveErrorHint } from './error-hints.js';
 function isEnvelope(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;
     const o = v;
     return o['status'] === 'success' || o['status'] === 'failed';
 }
-/** 常见错误码的排查提示，直接给到模型，省掉一轮试错。 */
-const ERROR_HINTS = {
-    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
-    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
-    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
-    24052: '请求参数有误，请对照接口文档检查',
-    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
-    24056: '签名错误，检查 appSecret 是否正确',
-    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
-    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）',
-};
 export class UwaApiError extends Error {
     code;
     rawMessage;
@@ -68,8 +58,9 @@ export class UwaClient {
         if (parsed.status === 'failed' || parsed.error) {
             const code = parsed.error?.code ?? -1;
             const raw = parsed.error?.data?.rawMessage ?? '';
-            const hint = ERROR_HINTS[code];
-            throw new UwaApiError(code, raw, `[${code}] ${parsed.error?.message ?? '请求失败'}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
+            const apiMessage = parsed.error?.message ?? '请求失败';
+            const hint = resolveErrorHint(code, raw, apiMessage);
+            throw new UwaApiError(code, raw, `[${code}] ${apiMessage}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
         }
         return parsed.data ?? {};
     }

package/dist/composite/helpers.d.ts

@@ -0,0 +1,19 @@
+import type { ToolResult } from '../tools.js';
+export declare function isObj(v: unknown): v is Record<string, unknown>;
+export declare function asText(value: unknown): string;
+/** 把任意结果压进字符闸门，超限时保留元信息 + 提示。 */
+export declare function jsonToolResult(data: unknown, maxChars: number): ToolResult;
+export declare function errorResult(err: unknown): ToolResult;
+/** 从 createDate 字符串取出 YYYY-MM-DD，无法解析则返回空。 */
+export declare function dayOf(dateStr: string | undefined | null): string | null;
+export declare function dayGte(day: string, cutoff: string): boolean;
+export declare function dayGt(day: string, cutoff: string): boolean;
+export declare function dayLt(day: string, cutoff: string): boolean;
+export declare function dayLte(day: string, cutoff: string): boolean;
+/** 宽松比较 SDK 版本号（按点分数字）。缺省或无法解析视为不满足。 */
+export declare function sdkAtLeast(sdk: string | undefined | null, min: string): boolean;
+export declare function requireReportKey(args: Record<string, unknown>): {
+    dataKey?: string;
+    recordId?: string;
+};
+export declare function topNOf(args: Record<string, unknown>, fallback?: number): number;

package/dist/composite/helpers.js

@@ -0,0 +1,90 @@
+export function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function asText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return '(无返回内容)';
+    return JSON.stringify(value, null, 2);
+}
+/** 把任意结果压进字符闸门，超限时保留元信息 + 提示。 */
+export function jsonToolResult(data, maxChars) {
+    const text = asText(data);
+    if (maxChars <= 0 || text.length <= maxChars) {
+        return { content: [{ type: 'text', text }] };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: asText({
+                    _truncated: `返回超过 ${maxChars} 字符上限已截断。请缩小 topN / 查询范围，或启动时调大 --max-chars。`,
+                    _returnedChars: maxChars,
+                }),
+            },
+            { type: 'text', text: text.slice(0, maxChars) },
+        ],
+    };
+}
+export function errorResult(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: msg }], isError: true };
+}
+/** 从 createDate 字符串取出 YYYY-MM-DD，无法解析则返回空。 */
+export function dayOf(dateStr) {
+    if (!dateStr)
+        return null;
+    const m = /(\d{4}-\d{2}-\d{2})/.exec(String(dateStr));
+    return m?.[1] ?? null;
+}
+export function dayGte(day, cutoff) {
+    return day >= cutoff;
+}
+export function dayGt(day, cutoff) {
+    return day > cutoff;
+}
+export function dayLt(day, cutoff) {
+    return day < cutoff;
+}
+export function dayLte(day, cutoff) {
+    return day <= cutoff;
+}
+/** 宽松比较 SDK 版本号（按点分数字）。缺省或无法解析视为不满足。 */
+export function sdkAtLeast(sdk, min) {
+    if (!sdk)
+        return false;
+    const parse = (s) => s
+        .replace(/^v/i, '')
+        .split(/[^0-9]+/)
+        .filter(Boolean)
+        .map((n) => Number.parseInt(n, 10));
+    const a = parse(sdk);
+    const b = parse(min);
+    if (!a.length || a.some((n) => Number.isNaN(n)))
+        return false;
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return true;
+}
+export function requireReportKey(args) {
+    const dataKey = typeof args['dataKey'] === 'string' && args['dataKey'] ? args['dataKey'] : undefined;
+    const recordId = args['recordId'] !== undefined && args['recordId'] !== null && args['recordId'] !== ''
+        ? String(args['recordId'])
+        : undefined;
+    if (!dataKey && !recordId)
+        throw new Error('必须提供 dataKey 或 recordId');
+    return { dataKey, recordId };
+}
+export function topNOf(args, fallback = 20) {
+    const n = typeof args['topN'] === 'number' ? args['topN'] : fallback;
+    if (!Number.isFinite(n) || n < 1)
+        return fallback;
+    return Math.min(Math.floor(n), 200);
+}

package/dist/composite/index.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Engine } from '../spec.js';
+import { type NameCase } from '../tools.js';
+import type { UwaClient } from '../client.js';
+import type { CompositeTool } from './types.js';
+/** 全部手写复合工具（不进 uwa-openapi.json）。 */
+export declare const COMPOSITE_TOOLS: readonly CompositeTool[];
+export declare const COMPOSITE_DEFAULT_IDS: readonly string[];
+export interface SelectCompositeOptions {
+    tools?: string[];
+    engine?: Engine | 'all';
+}
+/**
+ * 与原子工具同一套 --tool / --engine 过滤语义。
+ * 未指定 --tool 时视为 preset.default（复合工具若声明了该键则选中）。
+ */
+export declare function selectCompositeTools(opts: SelectCompositeOptions): CompositeTool[];
+export declare function registerCompositeTools(server: McpServer, client: UwaClient, opts: {
+    tools: string[];
+    engine: Engine | 'all';
+    nameCase: NameCase;
+    namePrefix: string;
+    maxChars: number;
+}): number;
+export declare function compositeFilterKeys(): string[];

package/dist/composite/index.js

@@ -0,0 +1,46 @@
+import { toolName } from '../tools.js';
+import { topResourcesTool } from './top-resources.js';
+import { topFunctionsTool } from './top-functions.js';
+import { reportDiagnosisTool } from './report-diagnosis.js';
+/** 全部手写复合工具（不进 uwa-openapi.json）。 */
+export const COMPOSITE_TOOLS = [
+    topResourcesTool,
+    topFunctionsTool,
+    reportDiagnosisTool,
+];
+export const COMPOSITE_DEFAULT_IDS = COMPOSITE_TOOLS.map((t) => t.id);
+/**
+ * 与原子工具同一套 --tool / --engine 过滤语义。
+ * 未指定 --tool 时视为 preset.default（复合工具若声明了该键则选中）。
+ */
+export function selectCompositeTools(opts) {
+    const wanted = new Set((opts.tools?.length ? opts.tools : ['preset.default']).map((t) => t.trim()).filter(Boolean));
+    const engine = opts.engine ?? 'all';
+    return COMPOSITE_TOOLS.filter((t) => {
+        if (engine !== 'all' && !t.engines.includes(engine))
+            return false;
+        const keys = new Set([t.id, 'preset.all', 'all', 'composite', ...t.filterKeys]);
+        return [...keys].some((k) => wanted.has(k));
+    });
+}
+export function registerCompositeTools(server, client, opts) {
+    const selected = selectCompositeTools({ tools: opts.tools, engine: opts.engine });
+    const ctx = {
+        client,
+        maxChars: opts.maxChars,
+        nameCase: opts.nameCase,
+        namePrefix: opts.namePrefix,
+        engine: opts.engine,
+    };
+    for (const tool of selected) {
+        server.registerTool(toolName(tool.id, opts.nameCase, opts.namePrefix), {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, (async (args) => tool.handler(args ?? {}, ctx)));
+    }
+    return selected.length;
+}
+export function compositeFilterKeys() {
+    return [...new Set(COMPOSITE_TOOLS.flatMap((t) => [t.id, 'composite', ...t.filterKeys]))].sort();
+}

package/dist/composite/name-pattern.d.ts

@@ -0,0 +1,8 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export declare function matchesNamePattern(name: string, pattern?: unknown): boolean;
+export declare function filterRowsByNamePattern<T extends {
+    name: string;
+}>(rows: T[], pattern: unknown): {
+    rows: T[];
+    matchedTotal: number;
+};

package/dist/composite/name-pattern.js

@@ -0,0 +1,25 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export function matchesNamePattern(name, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim()))
+        return true;
+    const p = String(pattern).trim();
+    if (p.length >= 2 && p.startsWith('/') && p.lastIndexOf('/') > 0) {
+        const last = p.lastIndexOf('/');
+        const body = p.slice(1, last);
+        const flags = p.slice(last + 1);
+        try {
+            return new RegExp(body, flags).test(name);
+        }
+        catch {
+            return name.toLowerCase().includes(p.toLowerCase());
+        }
+    }
+    return name.toLowerCase().includes(p.toLowerCase());
+}
+export function filterRowsByNamePattern(rows, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim())) {
+        return { rows, matchedTotal: rows.length };
+    }
+    const matched = rows.filter((r) => matchesNamePattern(r.name, pattern));
+    return { rows: matched, matchedTotal: matched.length };
+}

package/dist/composite/overview-view.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Overview 统计 v1 / v2 / UE 2.0 返回结构差异很大：
+ * - Unity v1：对象形 brief { fps_mean: [49] } + asset_stats
+ * - UE 2.0：数组形 brief [{ label, value }] + Resource 段
+ * - Unity v2（POST）：categories[] + basicInfo{}
+ * 这里统一抽成复合工具能用的扁平视图。
+ */
+export interface OverviewView {
+    /** 简报指标 key → 单值 */
+    brief: Record<string, unknown>;
+    /** 报告基本信息 label/key → 单值 */
+    summary: Record<string, unknown>;
+    /** 函数/卡顿相关条目 */
+    functions: {
+        name: string;
+        value: number;
+        unit?: string;
+        source: string;
+        label?: string;
+    }[];
+    /** 内存/资源相关条目（类型级） */
+    memory: {
+        name: string;
+        assetType: string;
+        memoryBytes: number;
+        _source: string;
+    }[];
+    /** 是否开启资源采集；无法判定时为 null */
+    hasResource: boolean | null;
+    shape: 'v1' | 'v2' | 'ue-v2' | 'unknown';
+}
+/** 把 unwrap 后的报告或原始 data 统一成 OverviewView。 */
+export declare function viewOverview(data: unknown): OverviewView;

package/dist/composite/overview-view.js

@@ -0,0 +1,373 @@
+import { isObj } from './helpers.js';
+function firstVal(v) {
+    return Array.isArray(v) ? v[0] : v;
+}
+function numOf(v) {
+    const x = firstVal(v);
+    if (typeof x === 'number' && Number.isFinite(x))
+        return x;
+    if (typeof x === 'string' && x.trim() && !Number.isNaN(Number(x)))
+        return Number(x);
+    return null;
+}
+function toBytes(value, unit) {
+    const u = (unit ?? '').toLowerCase();
+    if (u === 'b' || u === 'byte' || u === 'bytes')
+        return Math.round(value);
+    if (u === 'kb')
+        return Math.round(value * 1024);
+    if (u === 'mb')
+        return Math.round(value * 1024 * 1024);
+    if (u === 'gb')
+        return Math.round(value * 1024 * 1024 * 1024);
+    // 无单位时：很大的数当字节，否则当 MB（兼容 v1 brief 的 _mem_max_mb）
+    return value > 10_000 ? Math.round(value) : Math.round(value * 1024 * 1024);
+}
+function unitFromLabel(label) {
+    const m = /[（(]\s*(MB|KB|GB|B|字节)\s*[）)]/i.exec(label);
+    return m?.[1]?.toLowerCase() === '字节' ? 'b' : m?.[1]?.toLowerCase();
+}
+/** 排除「数量峰值」这类非内存指标。 */
+function looksLikeMemoryMetric(label, key, unit) {
+    if (/数量|count|cnt/i.test(label) || /count|cnt/i.test(key))
+        return false;
+    if (/^(b|byte|bytes|kb|mb|gb)$/i.test(unit))
+        return true;
+    return /内存|memory|mem|reserved|used|heap|gfx|mono|lua/i.test(label + key);
+}
+function guessAssetType(label, fallback) {
+    const rules = [
+        [/RenderTexture/i, 'RenderTexture'],
+        [/纹理|Texture/i, 'Texture'],
+        [/网格|Mesh/i, 'Mesh'],
+        [/Shader/i, 'Shader'],
+        [/材质|Material/i, 'Material'],
+        [/动画|Animation/i, 'AnimationClip'],
+        [/音频|Audio/i, 'AudioClip'],
+        [/字体|Font/i, 'Font'],
+        [/AssetBundle/i, 'AssetBundle'],
+        [/TextAsset|文本资源/i, 'TextAsset'],
+        [/粒子|Particle/i, 'ParticleSystem'],
+        [/Lua/i, 'Lua'],
+        [/Mono/i, 'Mono'],
+        [/Gfx/i, 'Gfx'],
+    ];
+    for (const [re, t] of rules)
+        if (re.test(label))
+            return t;
+    return fallback;
+}
+/** 把 summary / UE brief 一类 [{label,value}] 展开成 map。 */
+function expandLabelValueRows(rows) {
+    const out = {};
+    for (const row of rows) {
+        if (!isObj(row))
+            continue;
+        const label = String(row['label'] ?? row['key'] ?? '');
+        if (!label)
+            continue;
+        out[label] = firstVal(row['value'] ?? row['data']);
+        const key = row['key'];
+        if (typeof key === 'string' && key && !(key in out))
+            out[key] = out[label];
+    }
+    return out;
+}
+function basicInfoMap(basicInfo) {
+    const out = {};
+    if (!basicInfo)
+        return out;
+    const rows = Array.isArray(basicInfo)
+        ? basicInfo
+        : isObj(basicInfo)
+            ? Object.values(basicInfo)
+            : [];
+    for (const row of rows) {
+        if (!isObj(row))
+            continue;
+        const key = String(row['key'] ?? row['label'] ?? '');
+        if (!key)
+            continue;
+        out[key] = firstVal(row['data'] ?? row['value']);
+        const label = row['label'];
+        if (typeof label === 'string' && label && !(label in out))
+            out[label] = out[key];
+    }
+    return out;
+}
+function parseHasResource(summary, brief) {
+    for (const src of [brief, summary]) {
+        for (const [k, v] of Object.entries(src)) {
+            const keyHit = /^(OverviewHasResource|Resource|resourceMemory|resourceManagement|资源内存|资源管理|资源采集)$/i.test(k);
+            if (!keyHit)
+                continue;
+            const n = numOf(v);
+            if (n != null)
+                return n !== 0;
+            const s = String(firstVal(v) ?? '');
+            if (s === '1' || s === '2' || /详细|开启|千帧|60|模式/.test(s))
+                return true;
+            if (s === '0' || /关闭|无|关/.test(s))
+                return false;
+        }
+    }
+    return null;
+}
+/**
+ * UE 2.0：从 Resource / resource 段判定资源采集。
+ * 「资源内存占用峰值」> 0 → true；段存在但无法确认时返回 null（不误报关闭）。
+ */
+function parseHasResourceFromResourceSection(report) {
+    const section = report['Resource'] ?? report['resource'];
+    if (!Array.isArray(section) || section.length === 0)
+        return null;
+    let peak = null;
+    let anyMemPositive = false;
+    for (const item of section) {
+        if (!isObj(item))
+            continue;
+        const label = String(item['label'] ?? item['key'] ?? '');
+        const n = numOf(item['value'] ?? item['data']);
+        if (n == null)
+            continue;
+        if (/^资源内存占用峰值/.test(label) || /资源内存占用峰值（MB）/.test(label))
+            peak = n;
+        const unit = unitFromLabel(label) ?? '';
+        if (looksLikeMemoryMetric(label, '', unit) && n > 0)
+            anyMemPositive = true;
+    }
+    if (peak != null && peak > 0)
+        return true;
+    if (anyMemPositive)
+        return true;
+    return null;
+}
+/** 解析 Resource / resource 数组 → memory[]（排除数量峰值）。 */
+function memoryFromResourceSection(report) {
+    const section = report['Resource'] ?? report['resource'];
+    if (!Array.isArray(section))
+        return [];
+    const memory = [];
+    for (const item of section) {
+        if (!isObj(item))
+            continue;
+        const label = String(item['label'] ?? item['key'] ?? '');
+        const num = numOf(item['value'] ?? item['data']);
+        if (!label || num == null)
+            continue;
+        const unit = unitFromLabel(label) ?? 'mb';
+        if (!looksLikeMemoryMetric(label, '', unit))
+            continue;
+        // 总「资源内存占用峰值」不绑具体类型，仍保留便于看总量
+        memory.push({
+            name: label,
+            assetType: guessAssetType(label, 'Resource'),
+            memoryBytes: toBytes(num, unit),
+            _source: 'overview.Resource',
+        });
+    }
+    return memory;
+}
+function extractV2(data) {
+    const summary = basicInfoMap(data['basicInfo']);
+    const brief = {};
+    const functions = [];
+    const memory = [];
+    const categories = Array.isArray(data['categories']) ? data['categories'] : [];
+    for (const cat of categories) {
+        if (!isObj(cat))
+            continue;
+        const catName = String(cat['category'] ?? '');
+        const indicators = Array.isArray(cat['indicators']) ? cat['indicators'] : [];
+        for (const ind of indicators) {
+            if (!isObj(ind))
+                continue;
+            const label = String(ind['label'] ?? ind['key'] ?? '');
+            const key = String(ind['key'] ?? ind['indicatorKey'] ?? label);
+            const value = numOf(ind['data'] ?? ind['value']);
+            const unitObj = ind['unit'];
+            const unit = isObj(unitObj) ? String(unitObj['value'] ?? unitObj['description'] ?? '') : String(unitObj ?? '');
+            if (value != null && key)
+                brief[key] = value;
+            if (value != null && label && !(label in brief))
+                brief[label] = value;
+            const isFuncCat = /卡顿|重点函数|函数/.test(catName);
+            const isMemCat = /内存|资源|LLM/i.test(catName);
+            if (isFuncCat && value != null && label) {
+                functions.push({
+                    name: label,
+                    value,
+                    unit: unit || undefined,
+                    source: `overview.v2.${catName}`,
+                    label: catName,
+                });
+            }
+            if (isMemCat && value != null && label && looksLikeMemoryMetric(label, key, unit)) {
+                memory.push({
+                    name: label,
+                    assetType: guessAssetType(label, catName),
+                    memoryBytes: toBytes(value, unit),
+                    _source: `overview.v2.${catName}`,
+                });
+            }
+        }
+    }
+    functions.sort((a, b) => b.value - a.value);
+    memory.sort((a, b) => b.memoryBytes - a.memoryBytes);
+    return {
+        brief,
+        summary,
+        functions,
+        memory,
+        hasResource: parseHasResource(summary, brief),
+        shape: 'v2',
+    };
+}
+function extractV1OrUe(report) {
+    const brief = {};
+    const summary = {};
+    const functions = [];
+    const memory = [];
+    const briefIsArray = Array.isArray(report['brief']);
+    if (briefIsArray) {
+        Object.assign(brief, expandLabelValueRows(report['brief']));
+    }
+    else if (isObj(report['brief'])) {
+        for (const [k, v] of Object.entries(report['brief']))
+            brief[k] = firstVal(v);
+    }
+    if (Array.isArray(report['summary'])) {
+        Object.assign(summary, expandLabelValueRows(report['summary']));
+    }
+    else if (isObj(report['reportInfo'])) {
+        Object.assign(summary, report['reportInfo']);
+    }
+    if (Array.isArray(report['func'])) {
+        for (const item of report['func']) {
+            if (!isObj(item))
+                continue;
+            const name = String(item['label'] ?? item['key'] ?? item['name'] ?? '');
+            const value = numOf(item['value'] ?? item['data']);
+            if (!name || value == null)
+                continue;
+            functions.push({ name, value, source: 'overview.func', label: name });
+        }
+    }
+    if (isObj(report['brief'])) {
+        for (const [k, v] of Object.entries(report['brief'])) {
+            if (!/_mem_max_mb$/i.test(k) && !/Memory.*max/i.test(k))
+                continue;
+            const num = numOf(v);
+            if (num == null)
+                continue;
+            memory.push({
+                name: k,
+                assetType: k.replace(/_mem_max_mb$/i, ''),
+                memoryBytes: toBytes(num, 'mb'),
+                _source: 'overview.brief',
+            });
+        }
+    }
+    // UE 数组 brief 里也可能夹带内存类指标（类型级）
+    if (briefIsArray) {
+        for (const [label, v] of Object.entries(brief)) {
+            if (!looksLikeMemoryMetric(label, '', unitFromLabel(label) ?? ''))
+                continue;
+            const num = numOf(v);
+            if (num == null)
+                continue;
+            if (memory.some((m) => m.name === label))
+                continue;
+            memory.push({
+                name: label,
+                assetType: guessAssetType(label, 'brief'),
+                memoryBytes: toBytes(num, unitFromLabel(label) ?? 'mb'),
+                _source: 'overview.brief',
+            });
+        }
+    }
+    for (const row of memoryFromResourceSection(report)) {
+        if (memory.some((m) => m.name === row.name))
+            continue;
+        memory.push(row);
+    }
+    if (Array.isArray(report['asset_stats'])) {
+        for (const item of report['asset_stats']) {
+            if (!isObj(item))
+                continue;
+            const label = String(item['label'] ?? item['key'] ?? '');
+            const num = numOf(item['value'] ?? item['data']);
+            if (!label || num == null)
+                continue;
+            if (memory.some((m) => m.name === label))
+                continue;
+            const looksMb = /mb|内存/i.test(label);
+            memory.push({
+                name: label,
+                assetType: guessAssetType(label, label),
+                memoryBytes: looksMb ? toBytes(num, 'mb') : toBytes(num, 'b'),
+                _source: 'overview.asset_stats',
+            });
+        }
+    }
+    if (Array.isArray(report['LLM'])) {
+        for (const item of report['LLM']) {
+            if (!isObj(item))
+                continue;
+            const label = String(item['label'] ?? item['key'] ?? '');
+            const num = numOf(item['value'] ?? item['data']);
+            if (!label || num == null)
+                continue;
+            memory.push({ name: label, assetType: 'LLM', memoryBytes: toBytes(num, 'b'), _source: 'overview.LLM' });
+        }
+    }
+    functions.sort((a, b) => b.value - a.value);
+    memory.sort((a, b) => b.memoryBytes - a.memoryBytes);
+    const fromSection = parseHasResourceFromResourceSection(report);
+    const fromFields = parseHasResource(summary, brief);
+    return {
+        brief,
+        summary,
+        functions,
+        memory,
+        hasResource: fromSection ?? fromFields,
+        shape: briefIsArray ? 'ue-v2' : 'v1',
+    };
+}
+/** 把 unwrap 后的报告或原始 data 统一成 OverviewView。 */
+export function viewOverview(data) {
+    if (!data) {
+        return { brief: {}, summary: {}, functions: [], memory: [], hasResource: null, shape: 'unknown' };
+    }
+    // 数组取第一份
+    let root = data;
+    if (Array.isArray(data) && data.length)
+        root = data[0];
+    if (!isObj(root)) {
+        return { brief: {}, summary: {}, functions: [], memory: [], hasResource: null, shape: 'unknown' };
+    }
+    if (Array.isArray(root['categories']) || root['basicInfo'] != null)
+        return extractV2(root);
+    // batch map: { [dataKey]: { categories... } }
+    const values = Object.values(root);
+    if (values.length === 1 && isObj(values[0]) && (Array.isArray(values[0]['categories']) || values[0]['basicInfo'])) {
+        return extractV2(values[0]);
+    }
+    for (const k of ['reports', 'list', 'content', 'data', 'records']) {
+        const v = root[k];
+        if (Array.isArray(v) && v.length && isObj(v[0]))
+            return viewOverview(v[0]);
+    }
+    if ('brief' in root ||
+        'func' in root ||
+        'summary' in root ||
+        'asset_stats' in root ||
+        'Resource' in root ||
+        'resource' in root) {
+        return extractV1OrUe(root);
+    }
+    // 可能整包就是 v2 包在更深一层
+    if (values.length && isObj(values[0]) && Array.isArray(values[0]['categories']))
+        return extractV2(values[0]);
+    return extractV1OrUe(root);
+}

package/dist/composite/report-diagnosis.d.ts

@@ -0,0 +1,2 @@
+import type { CompositeTool } from './types.js';
+export declare const reportDiagnosisTool: CompositeTool;