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

package/README.md

@@ -107,6 +107,9 @@ npx -y @uwa4d/openapi-mcp check -a <app_id> -s <app_secret>
 # 组合：默认集 + 所有预签名类接口 + 单个指定工具
 -t preset.default,presign,gotonline_overview_stack_id_map
 
+# 只要复合工具（报告体检 / Top 资源 / Top 函数）
+-t composite
+
 # 只做 Unity 项目，砍掉 UE 专用工具
 -t preset.default -e unity
 ```
@@ -118,6 +121,18 @@ npx -y @uwa4d/openapi-mcp list-tools
 npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 ```
 
+## 复合工具
+
+默认 preset 里除了原子接口，还有三个**复合工具**——内部会串多个接口并聚合，适合对话式提问：
+
+| 工具 | 做什么 |
+| --- | --- |
+| `report_diagnosis` | 单份报告体检：自动选对统计 v1/v2，附带 Top 资源/函数与场景摘要 |
+| `top_resources` | 资源内存 Top N（默认 11 种类型；`groupBy=merged` 全局 Top / `assetType` 按类型各 Top） |
+| `top_functions` | 函数 Top N：下载堆栈树 + idmap，按函数名合并同名节点后再排序 |
+
+不确定该调统计 1.0 还是 2.0 时，优先用这三个，不必自己判断日期和 SDK。
+
 ## 大数据接口的返回方式
 
 堆栈树、资源列表、卡顿帧等接口不直接返回数据，而是返回一个有效期 600 秒的预签名下载地址。
@@ -189,8 +204,18 @@ npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
 **提示凭证错误**
 用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。注意测试环境和生产环境的凭证不通用。
 
-**返回「数据服务错误」**
-部分接口区分报告生成时间和引擎类型，例如 Unity 2026-07-09 之前的报告用 `get_overview_statistic_v1`，之后的用 `get_overview_statistic_v2`。工具描述里注明了适用范围。
+**返回「数据服务错误」或不确定该用 v1 还是 v2**
+
+部分接口按报告解析/提交日期和引擎区分版本：
+
+| 场景 | 用哪个 |
+| --- | --- |
+| Unity Overview，解析日 **&lt; 2026-07-09** | `get_overview_statistic_v1` |
+| Unity Overview，解析日 **≥ 2026-07-09** 且 SDK ≥ 2.5.1 | `get_overview_statistic_v2` |
+| UE Overview，提交日 **≤ 2026-03-25** | `get_overview_statistic_v1` |
+| UE Overview，提交日 **&gt; 2026-03-25** | `get_ue_overview_statistic_v2` |
+
+场景统计、运行日志、快照帧等也有类似 1.0/2.0 成对工具，描述开头有「选用规则」。不确定时直接用复合工具 `report_diagnosis` / `top_functions`，内部会按报告详情自动路由。
 
 ## 许可
 

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command, Option } from 'commander';
 import { UwaClient } from './client.js';
 import { loadSpec } from './spec.js';
+import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './composite/index.js';
 import { filterKeys, selectOperations } from './presets.js';
 import { DEFAULT_MAX_CHARS, DEFAULT_MAX_ROWS, toolName } from './tools.js';
 import { PACKAGE_VERSION, startStdio } from './server.js';
@@ -70,10 +71,10 @@ program
     .option('--spec <path>', '自定义 spec 文件路径')
     .action((opts) => {
     const spec = loadSpec(opts.spec);
-    const selected = new Set(selectOperations(spec.operations, {
-        tools: opts.tool ?? ['all'],
-        engine: opts.engine,
-    }).map((o) => o.id));
+    const toolFilter = opts.tool ?? ['all'];
+    const engine = opts.engine;
+    const selected = new Set(selectOperations(spec.operations, { tools: toolFilter, engine }).map((o) => o.id));
+    const selectedComposite = new Set(selectCompositeTools({ tools: toolFilter, engine }).map((t) => t.id));
     const byModule = new Map();
     for (const op of spec.operations) {
         const key = op.modules.join(',');
@@ -89,8 +90,19 @@ program
             console.log(`${mark} ${toolName(op.id, 'snake', '').padEnd(52)} ${op.method.padEnd(4)} ${engines.padEnd(7)} ${op.name}`);
         }
     }
-    console.log(`\n共 ${spec.operations.length} 个工具，当前条件选中 ${selected.size} 个（* 标记）`);
-    console.log(`可用过滤键：${[...new Set(spec.operations.flatMap(filterKeys))].sort().join(', ')}`);
+    console.log('\n## composite（手写复合工具）');
+    for (const t of COMPOSITE_TOOLS) {
+        const mark = selectedComposite.has(t.id) ? '*' : ' ';
+        const engines = t.engines.map((e) => (e === 'unity' ? 'U3D' : 'UE')).join('+');
+        console.log(`${mark} ${toolName(t.id, 'snake', '').padEnd(52)} CMP  ${engines.padEnd(7)} ${t.title}`);
+    }
+    const total = spec.operations.length + COMPOSITE_TOOLS.length;
+    const selectedCount = selected.size + selectedComposite.size;
+    console.log(`\n共 ${total} 个工具（原子 ${spec.operations.length} + 复合 ${COMPOSITE_TOOLS.length}），当前条件选中 ${selectedCount} 个（* 标记）`);
+    const keys = [
+        ...new Set([...spec.operations.flatMap(filterKeys), ...compositeFilterKeys()]),
+    ].sort();
+    console.log(`可用过滤键：${keys.join(', ')}`);
 });
 program
     .command('check')

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/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);
+}