vite-plugin-aipanel 1.2.28 → 1.3.2

package/es/client/vue-devtools-timeline.mjs

@@ -0,0 +1,617 @@
+import {
+  VUE_DEVTOOLS_TIMELINE_DEFAULTS,
+  VUE_DEVTOOLS_TIMELINE_INCLUDE,
+  VUE_DEVTOOLS_TIMELINE_INCLUDES,
+  VUE_DEVTOOLS_TIMELINE_LAYERS
+} from "@aipanel/core";
+import { sanitizeValue } from "./vue-devtools-sanitize.mjs";
+const DEVTOOLS_HOOK_EVENTS = {
+  appInit: "app:init",
+  appUnmount: "app:unmount",
+  componentAdded: "component:added",
+  componentUpdated: "component:updated",
+  componentRemoved: "component:removed",
+  componentEmit: "component:emit",
+  performanceStart: "perf:start",
+  performanceEnd: "perf:end"
+};
+const MAX_COMPONENTS = 200;
+const MAX_MARKS = 20;
+const PENDING_TTL_MS = 5e3;
+const PENDING_PRUNE_THRESHOLD = 64;
+const MAX_PENDING = 5e3;
+const MAX_PAYLOAD_BYTES = 64 * 1024;
+const TREE_CACHE_TTL_MS = 2e3;
+function round2(value) {
+  return Math.round(value * 100) / 100;
+}
+function clampNumber(value, min, max, fallback) {
+  const num = typeof value === "number" && Number.isFinite(value) ? value : NaN;
+  if (Number.isNaN(num)) return fallback;
+  return Math.min(max, Math.max(min, num));
+}
+function readName(instance) {
+  const type = instance?.type;
+  const name = type?.name ?? type?.__name;
+  return typeof name === "string" && name ? name : "(anonymous)";
+}
+function readUid(instance) {
+  const uid = instance?.uid;
+  return typeof uid === "number" ? uid : void 0;
+}
+function readRoutePath(route) {
+  const value = route;
+  if (typeof value?.fullPath === "string") return value.fullPath;
+  if (typeof value?.path === "string") return value.path;
+  return String(route ?? "");
+}
+function readEventName(data) {
+  const event = data?.event;
+  return typeof event === "string" ? event : "(unknown)";
+}
+function collectFiles(nodes, files) {
+  if (!Array.isArray(nodes)) return;
+  for (const node of nodes) {
+    const { id, file, children } = node ?? {};
+    if (typeof id === "string" && typeof file === "string" && file) files.set(id, file);
+    collectChildren(children, files);
+  }
+}
+function collectChildren(children, files) {
+  collectFiles(children, files);
+}
+function safely(handler) {
+  return (...args) => {
+    try {
+      handler(...args);
+    } catch {
+    }
+  };
+}
+function createTimelineRecorder(options = {}) {
+  const capacity = options.capacity ?? VUE_DEVTOOLS_TIMELINE_DEFAULTS.capacity;
+  const now = options.now ?? (() => performance.now());
+  const getAppRecords = options.getAppRecords ?? (() => []);
+  const resolveRouter = options.resolveRouter ?? (() => void 0);
+  const hook = options.hook;
+  function readNow() {
+    try {
+      const value = now();
+      return typeof value === "number" && Number.isFinite(value) ? value : Date.now();
+    } catch {
+      return Date.now();
+    }
+  }
+  const bootId = Math.random().toString(36).slice(2, 10);
+  let startedAt = readNow();
+  let records = [];
+  let marks = [];
+  const pending = /* @__PURE__ */ new Map();
+  const components = /* @__PURE__ */ new Map();
+  const appRouters = /* @__PURE__ */ new WeakMap();
+  const routerSubscriptions = /* @__PURE__ */ new Map();
+  const unsubscribers = [];
+  const lifecycleTotals = { added: 0, updated: 0, removed: 0 };
+  let componentEvictions = 0;
+  let dropped = 0;
+  let droppedAt = null;
+  let unpaired = 0;
+  let prunedStarts = 0;
+  let sequence = 0;
+  let markSequence = 0;
+  let routerCount = 0;
+  let treeCache = null;
+  function appIdOf(app, instance) {
+    const appLike = app;
+    const fromApp = appLike?.__VUE_DEVTOOLS_NEXT_APP_RECORD_ID__ ?? appLike?.__VUE_DEVTOOLS_NEXT_APP_RECORD__?.id;
+    if (typeof fromApp === "string" && fromApp) return fromApp;
+    const fromInstance = instance?.appContext?.app;
+    const fromInstanceId = fromInstance?.__VUE_DEVTOOLS_NEXT_APP_RECORD_ID__ ?? fromInstance?.__VUE_DEVTOOLS_NEXT_APP_RECORD__?.id;
+    if (typeof fromInstanceId === "string" && fromInstanceId) return fromInstanceId;
+    return getAppRecords().find((record) => record.app === app)?.id ?? "?";
+  }
+  function nodeIdOf(app, uid, instance) {
+    const instanceLike = instance;
+    if (typeof instanceLike?.__VUE_DEVTOOLS_NEXT_UID__ === "string") {
+      return instanceLike.__VUE_DEVTOOLS_NEXT_UID__;
+    }
+    const appId = appIdOf(app, instance);
+    if (appId === "?") return void 0;
+    const isRoot = instanceLike != null && instanceLike.root === instance || app?._instance?.uid === uid;
+    return `${appId}:${isRoot ? "root" : uid}`;
+  }
+  function push(record) {
+    records.push({ ...record, seq: ++sequence });
+    const overflow = records.length - capacity;
+    if (overflow > 0) {
+      const evicted = records.splice(0, overflow);
+      const newest = evicted[evicted.length - 1];
+      if (newest) droppedAt = Math.max(droppedAt ?? newest.at, newest.at);
+      dropped += overflow;
+    }
+  }
+  function prunePending(nowAt) {
+    if (pending.size > PENDING_PRUNE_THRESHOLD) {
+      for (const [key, operation] of pending) {
+        if (nowAt - operation.at > PENDING_TTL_MS) {
+          pending.delete(key);
+          prunedStarts += 1;
+        }
+      }
+    }
+    while (pending.size > MAX_PENDING) {
+      const oldest = pending.keys().next().value;
+      if (oldest === void 0) break;
+      pending.delete(oldest);
+      prunedStarts += 1;
+    }
+  }
+  function touchComponent(app, uid, instance, field) {
+    const key = `${appIdOf(app, instance)}:${uid}`;
+    const nodeId = nodeIdOf(app, uid, instance);
+    const existing = components.get(key);
+    const stat = existing ?? {
+      name: readName(instance),
+      ...nodeId === void 0 ? {} : { nodeId },
+      added: 0,
+      updated: 0,
+      removed: 0,
+      lastAt: 0
+    };
+    if (existing && stat.nodeId === void 0 && nodeId !== void 0) stat.nodeId = nodeId;
+    stat[field] += 1;
+    stat.lastAt = readNow();
+    lifecycleTotals[field] += 1;
+    if (existing) components.delete(key);
+    components.set(key, stat);
+    while (components.size > MAX_COMPONENTS) {
+      const oldest = components.keys().next().value;
+      if (oldest === void 0) break;
+      components.delete(oldest);
+      componentEvictions += 1;
+    }
+  }
+  function onPerformanceStart(app, uid, vm, type, time) {
+    if (typeof uid !== "number" || typeof type !== "string") return;
+    prunePending(time);
+    const nodeId = nodeIdOf(app, uid, vm);
+    pending.set(`${appIdOf(app, vm)}:${uid}:${type}`, {
+      name: readName(vm),
+      ...nodeId === void 0 ? {} : { nodeId },
+      at: typeof time === "number" ? time : readNow()
+    });
+  }
+  function onPerformanceEnd(app, uid, vm, type, time) {
+    if (typeof uid !== "number" || typeof type !== "string") return;
+    const key = `${appIdOf(app, vm)}:${uid}:${type}`;
+    const started = pending.get(key);
+    pending.delete(key);
+    if (!started) {
+      unpaired += 1;
+      return;
+    }
+    const endAt = typeof time === "number" ? time : readNow();
+    push({
+      at: endAt,
+      layer: "perf",
+      kind: type,
+      name: started.name || readName(vm),
+      nodeId: started.nodeId,
+      dur: round2(Math.max(0, endAt - started.at))
+    });
+  }
+  function onComponentAdded(app, uid, _parentUid, instance) {
+    if (typeof uid !== "number") return;
+    touchComponent(app, uid, instance, "added");
+  }
+  function onComponentUpdated(app, uid, _parentUid, instance) {
+    if (typeof uid !== "number") return;
+    touchComponent(app, uid, instance, "updated");
+  }
+  function onComponentRemoved(app, uid, _parentUid, instance) {
+    if (typeof uid !== "number") return;
+    touchComponent(app, uid, instance, "removed");
+  }
+  function onComponentEmit(app, instance, event, params) {
+    const uid = readUid(instance);
+    const nodeId = uid === void 0 ? void 0 : nodeIdOf(app, uid, instance);
+    push({
+      at: readNow(),
+      layer: "emit",
+      kind: "emit",
+      name: readName(instance),
+      ...nodeId === void 0 ? {} : { nodeId },
+      data: { event: typeof event === "string" ? event : String(event), params: sanitizeValue(params) }
+    });
+  }
+  function onNavigated(to, from, failure) {
+    const toPath = readRoutePath(to);
+    const failureDetail = failure ? sanitizeValue(failure?.message ?? String(failure)) : void 0;
+    push({
+      at: readNow(),
+      layer: "navigate",
+      kind: "navigation",
+      name: toPath,
+      level: failure ? "warning" : "default",
+      data: {
+        from: readRoutePath(from),
+        to: toPath,
+        ...failureDetail === void 0 || failureDetail === null ? {} : { failure: failureDetail }
+      }
+    });
+  }
+  function subscribeRouter(app) {
+    const router = resolveRouter(app);
+    if (!router || typeof router.afterEach !== "function") return;
+    const appKey = typeof app === "object" && app !== null ? app : void 0;
+    if (appKey) {
+      const previous = appRouters.get(appKey);
+      if (previous === router && routerSubscriptions.has(router)) return;
+      if (previous && previous !== router) releaseRouter(previous);
+      appRouters.set(appKey, router);
+    } else if (routerSubscriptions.has(router)) {
+      return;
+    }
+    const existing = routerSubscriptions.get(router);
+    if (existing) {
+      existing.apps += 1;
+      routerCount += 1;
+      return;
+    }
+    const off = router.afterEach(safely(onNavigated));
+    if (typeof off !== "function") return;
+    routerSubscriptions.set(router, { off, apps: 1 });
+    routerCount += 1;
+  }
+  function releaseRouter(router) {
+    const entry = routerSubscriptions.get(router);
+    if (!entry) return;
+    entry.apps = Math.max(0, entry.apps - 1);
+    routerCount = Math.max(0, routerCount - 1);
+    if (entry.apps > 0) return;
+    safely(entry.off)();
+    routerSubscriptions.delete(router);
+  }
+  function unsubscribeRouter(app) {
+    const appKey = typeof app === "object" && app !== null ? app : void 0;
+    if (!appKey) return;
+    const router = appRouters.get(appKey);
+    if (!router) return;
+    appRouters.delete(appKey);
+    releaseRouter(router);
+  }
+  function onAppInit(app) {
+    subscribeRouter(app);
+  }
+  function onAppUnmount(app) {
+    unsubscribeRouter(app);
+  }
+  function attachRouters() {
+    let records2;
+    try {
+      records2 = getAppRecords();
+    } catch {
+      return;
+    }
+    for (const record of records2) {
+      try {
+        subscribeRouter(record.app);
+      } catch {
+      }
+    }
+  }
+  try {
+    if (hook && typeof hook.on === "function") {
+      const subscribe = (event, handler) => {
+        try {
+          const off = hook.on(event, safely(handler));
+          if (typeof off === "function") unsubscribers.push(off);
+        } catch {
+        }
+      };
+      subscribe(DEVTOOLS_HOOK_EVENTS.performanceStart, onPerformanceStart);
+      subscribe(DEVTOOLS_HOOK_EVENTS.performanceEnd, onPerformanceEnd);
+      subscribe(DEVTOOLS_HOOK_EVENTS.componentAdded, onComponentAdded);
+      subscribe(DEVTOOLS_HOOK_EVENTS.componentUpdated, onComponentUpdated);
+      subscribe(DEVTOOLS_HOOK_EVENTS.componentRemoved, onComponentRemoved);
+      subscribe(DEVTOOLS_HOOK_EVENTS.componentEmit, onComponentEmit);
+      subscribe(DEVTOOLS_HOOK_EVENTS.appInit, onAppInit);
+      subscribe(DEVTOOLS_HOOK_EVENTS.appUnmount, onAppUnmount);
+    }
+  } catch {
+  }
+  async function fileMap(nowAt) {
+    if (treeCache && nowAt - treeCache.at < TREE_CACHE_TTL_MS) return treeCache.files;
+    const files = /* @__PURE__ */ new Map();
+    try {
+      const tree = await options.getInspectorTree?.();
+      collectFiles(tree, files);
+    } catch {
+    }
+    treeCache = { at: nowAt, files };
+    return files;
+  }
+  function mark(label) {
+    const at = readNow();
+    const markId = `m${++markSequence}`;
+    const name = typeof label === "string" && label ? label : "mark";
+    marks.push({ id: markId, label: name, at });
+    while (marks.length > MAX_MARKS) marks.shift();
+    push({ at, layer: "agent", kind: "mark", name, data: { markId } });
+    return { markId, buffered: records.length };
+  }
+  function clear() {
+    const cleared = records.length;
+    const clearedMarks = marks.length;
+    records = [];
+    marks = [];
+    pending.clear();
+    components.clear();
+    lifecycleTotals.added = 0;
+    lifecycleTotals.updated = 0;
+    lifecycleTotals.removed = 0;
+    componentEvictions = 0;
+    dropped = 0;
+    droppedAt = null;
+    unpaired = 0;
+    prunedStarts = 0;
+    treeCache = null;
+    startedAt = readNow();
+    return { cleared, marks: clearedMarks };
+  }
+  function dispose() {
+    for (const off of unsubscribers) safely(off)();
+    unsubscribers.length = 0;
+    for (const { off } of routerSubscriptions.values()) safely(off)();
+    routerSubscriptions.clear();
+    routerCount = 0;
+  }
+  async function get(query = {}) {
+    const nowAt = readNow();
+    const include = typeof query.include === "string" && VUE_DEVTOOLS_TIMELINE_INCLUDES.includes(query.include) ? query.include : VUE_DEVTOOLS_TIMELINE_DEFAULTS.include;
+    const windowMs = clampNumber(query.windowMs, 0, 6e5, VUE_DEVTOOLS_TIMELINE_DEFAULTS.windowMs);
+    const minDurationMs = clampNumber(
+      query.minDurationMs,
+      0,
+      6e4,
+      VUE_DEVTOOLS_TIMELINE_DEFAULTS.minDurationMs
+    );
+    const limit = Math.floor(
+      clampNumber(query.limit, 1, VUE_DEVTOOLS_TIMELINE_DEFAULTS.maxLimit, VUE_DEVTOOLS_TIMELINE_DEFAULTS.limit)
+    );
+    const layers = normalizeLayers(query.layers);
+    const componentFilter = typeof query.component === "string" ? query.component.toLowerCase() : "";
+    const notes = [];
+    prunePending(nowAt);
+    let from = nowAt - windowMs;
+    if (query.sinceMark) {
+      const target = findMark(query.sinceMark);
+      if (target) {
+        from = target.at;
+      } else {
+        notes.push(
+          `\u672A\u627E\u5230 mark\u300C${query.sinceMark}\u300D\uFF08\u9875\u9762\u53EF\u80FD\u5DF2\u6574\u9875\u5237\u65B0\uFF0C\u6216\u6807\u8BB0\u5DF2\u88AB\u4E22\u5F03\uFF09\uFF1B\u5DF2\u9000\u56DE windowMs=${windowMs} \u7684\u7A97\u53E3\u3002`
+        );
+      }
+    }
+    const inWindow = records.filter((record) => record.at >= from && layers.has(record.layer));
+    const scoped = inWindow.filter((record) => {
+      if (!componentFilter) return true;
+      if (record.layer === "navigate" || record.layer === "agent") return true;
+      return record.name.toLowerCase().includes(componentFilter);
+    });
+    const windowTruncated = droppedAt !== null && droppedAt >= from;
+    if (scoped.length === 0) {
+      notes.push(
+        "\u7A97\u53E3\u5185\u65E0\u4E8B\u4EF6\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u7A97\u53E3\u5185\u6CA1\u6709\u4EA4\u4E92\u6216\u6E32\u67D3\uFF1B\u6216\u9875\u9762\u521A\u6574\u9875\u5237\u65B0\u2014\u2014SPA \u8DEF\u7531\u5207\u6362\u4FDD\u7559\u8BB0\u5F55\uFF0C\u6574\u9875\u5237\u65B0\u4F1A\u6E05\u7A7A\u7F13\u51B2\u3002"
+      );
+    }
+    if (!hook) {
+      notes.push("\u672A\u53D6\u5F97 Vue DevTools hook\uFF1A\u9875\u9762\u53EF\u80FD\u4E0D\u662F Vue \u9879\u76EE\uFF0C\u6216\u6865\u672A\u521D\u59CB\u5316\u3002");
+    }
+    if (windowTruncated) {
+      notes.push(
+        `\u7A97\u53E3\u5185\u6570\u636E\u4E0D\u5B8C\u6574\uFF1A\u7F13\u51B2\u5BB9\u91CF ${capacity} \u6761\uFF0C\u6700\u65E9\u4FDD\u7559\u8BB0\u5F55\u8D77\u4E8E -${round2(nowAt - (records[0]?.at ?? nowAt))}ms\uFF0C\u7A97\u53E3\u8D77\u70B9\u66F4\u65E9\u7684\u90E8\u5206\u5DF2\u88AB\u4E22\u5F03\uFF08\u7D2F\u8BA1\u4E22\u5F03 ${dropped} \u6761\uFF09\u3002`
+      );
+    }
+    if (unpaired > 0 || prunedStarts > 0) {
+      const parts = [
+        unpaired > 0 ? `${unpaired} \u6B21\u53EA\u6709 end \u6CA1\u6709 start` : "",
+        prunedStarts > 0 ? `${prunedStarts} \u6B21 start \u672A\u7B49\u5230 end` : ""
+      ].filter(Boolean);
+      notes.push(
+        `\u6709 ${parts.join("\u3001")}\uFF1A\u8FD9\u4E9B\u6E32\u67D3\u7684\u8017\u65F6\u662F"\u7F3A\u5931"\uFF0C\u4E0D\u662F 0ms\uFF08start \u88AB\u6E05\u7406\u540E\u624D\u6536\u5230 end \u65F6\uFF0C\u540C\u4E00\u6B21\u6E32\u67D3\u4F1A\u540C\u65F6\u8BA1\u5165\u4E24\u5904\uFF09\u3002`
+      );
+    }
+    const omitted = { perfBelowThreshold: 0, byLimit: 0, byPayload: 0 };
+    let picked;
+    let eligible;
+    if (include === VUE_DEVTOOLS_TIMELINE_INCLUDE.SUMMARY) {
+      picked = [];
+      eligible = 0;
+    } else if (include === VUE_DEVTOOLS_TIMELINE_INCLUDE.ALL) {
+      picked = scoped.slice(-limit);
+      eligible = scoped.length;
+    } else {
+      const perf = scoped.filter((record) => record.layer === "perf");
+      omitted.perfBelowThreshold = perf.filter((record) => (record.dur ?? 0) < minDurationMs).length;
+      const slow = perf.filter((record) => (record.dur ?? 0) >= minDurationMs).sort((a, b) => (b.dur ?? 0) - (a.dur ?? 0)).slice(0, limit);
+      const rest = scoped.filter((record) => record.layer !== "perf").slice(-limit);
+      picked = [...slow, ...rest];
+      eligible = perf.length - omitted.perfBelowThreshold + scoped.filter((r) => r.layer !== "perf").length;
+    }
+    omitted.byLimit = Math.max(0, eligible - picked.length);
+    picked.sort((a, b) => a.at - b.at);
+    const detail = picked.map((record) => ({
+      seq: record.seq,
+      t: round2(record.at - nowAt),
+      layer: record.layer,
+      kind: record.kind,
+      name: record.name,
+      ...record.dur === void 0 ? {} : { dur: record.dur },
+      ...record.nodeId ? { nodeId: record.nodeId } : {},
+      ...record.level ? { level: record.level } : {},
+      ...record.data === void 0 ? {} : { data: record.data }
+    }));
+    if (query.enrich !== false && detail.length > 0 && options.getInspectorTree) {
+      const files = await fileMap(nowAt);
+      for (const record of detail) {
+        if (!record.nodeId) continue;
+        const file = files.get(record.nodeId);
+        if (file) record.file = file;
+      }
+    }
+    const summary = buildSummary(scoped, layers, componentFilter, minDurationMs, nowAt);
+    const result = {
+      // ms 报实际窗口跨度（sinceMark 会覆盖 windowMs，不能谎报成请求值）
+      window: {
+        from: round2(from - nowAt),
+        to: 0,
+        ms: round2(nowAt - from),
+        ...query.sinceMark ? { sinceMark: query.sinceMark } : {}
+      },
+      buffer: {
+        capacity,
+        size: records.length,
+        dropped,
+        ...droppedAt === null ? {} : { droppedAtMsAgo: round2(droppedAt - nowAt) },
+        windowTruncated,
+        unpaired,
+        prunedStarts,
+        marks: marks.length,
+        startedAtMsAgo: round2(nowAt - startedAt),
+        bootId,
+        capture: { hook: Boolean(hook), routers: routerCount }
+      },
+      summary,
+      records: detail,
+      truncated: false,
+      detailComplete: true,
+      omitted,
+      notes
+    };
+    while (result.records.length > 0 && jsonSize(result) > MAX_PAYLOAD_BYTES) {
+      result.records.shift();
+      omitted.byPayload += 1;
+    }
+    result.truncated = omitted.byLimit > 0 || omitted.byPayload > 0;
+    result.detailComplete = omitted.perfBelowThreshold === 0 && omitted.byLimit === 0 && omitted.byPayload === 0;
+    if (omitted.perfBelowThreshold > 0 || omitted.byLimit > 0 || omitted.byPayload > 0) {
+      notes.push(
+        `\u660E\u7EC6\u975E\u5168\u91CF\uFF08\u4F4E\u4E8E ${minDurationMs}ms ${omitted.perfBelowThreshold} \u6761\u3001\u8D85\u51FA limit ${omitted.byLimit} \u6761\u3001\u8D85\u4F53\u79EF ${omitted.byPayload} \u6761\uFF09\uFF1B\u6B21\u6570\u4E0E\u8017\u65F6\u4EE5 summary \u4E3A\u51C6\u3002`
+      );
+    }
+    return result;
+    function findMark(idOrLabel) {
+      for (let index = marks.length - 1; index >= 0; index -= 1) {
+        const candidate = marks[index];
+        if (candidate && (candidate.id === idOrLabel || candidate.label === idOrLabel)) return candidate;
+      }
+      return void 0;
+    }
+    function buildSummary(windowRecords, activeLayers, nameFilter, threshold, reference) {
+      const summary2 = {};
+      if (activeLayers.has("perf")) {
+        const componentsByKey = /* @__PURE__ */ new Map();
+        let totalMs = 0;
+        const perf = windowRecords.filter((record) => record.layer === "perf");
+        for (const record of perf) {
+          const dur = record.dur ?? 0;
+          totalMs += dur;
+          const key = record.nodeId ?? record.name;
+          const entry = componentsByKey.get(key) ?? {
+            name: record.name,
+            ...record.nodeId ? { nodeId: record.nodeId } : {},
+            count: 0,
+            totalMs: 0,
+            maxMs: 0
+          };
+          entry.count += 1;
+          entry.totalMs = round2(entry.totalMs + dur);
+          entry.maxMs = Math.max(entry.maxMs, dur);
+          componentsByKey.set(key, entry);
+        }
+        const byComponent = [...componentsByKey.values()].sort((a, b) => b.totalMs - a.totalMs).slice(0, 10);
+        const slowest = [...perf].sort((a, b) => (b.dur ?? 0) - (a.dur ?? 0)).slice(0, 5).map((record) => ({
+          name: record.name,
+          kind: record.kind,
+          dur: record.dur ?? 0,
+          at: round2(record.at - reference),
+          ...record.nodeId ? { nodeId: record.nodeId } : {}
+        }));
+        summary2.perf = {
+          operations: perf.length,
+          totalMs: round2(totalMs),
+          thresholdMs: threshold,
+          byComponent,
+          slowest
+        };
+      }
+      if (activeLayers.has("lifecycle")) {
+        const stats = [...components.values()].filter(
+          (stat) => !nameFilter || stat.name.toLowerCase().includes(nameFilter)
+        );
+        summary2.lifecycle = {
+          sinceMs: round2(reference - startedAt),
+          note: "\u7D2F\u8BA1\u8BA1\u6570\uFF08\u81EA\u9875\u9762\u52A0\u8F7D/\u4E0A\u6B21 clear \u8D77\uFF09\uFF0C\u4E0D\u53D7 windowMs \u5F71\u54CD\uFF1Badded/updated/removed \u4E3A\u5168\u9875\u7CBE\u786E\u7D2F\u8BA1\uFF0Ccomponent \u8FC7\u6EE4\u53EA\u4F5C\u7528\u4E8E byComponent",
+          // 用精确累计而不是逐组件求和：逐组件表有上限，淘汰后求和会静默少报
+          added: lifecycleTotals.added,
+          updated: lifecycleTotals.updated,
+          removed: lifecycleTotals.removed,
+          trackedComponents: components.size,
+          // >0 表示组件数超过逐组件表上限，byComponent 只是其中一部分
+          componentEvictions,
+          byComponent: stats.sort((a, b) => b.updated - a.updated).slice(0, 10).map((stat) => ({
+            name: stat.name,
+            nodeId: stat.nodeId,
+            added: stat.added,
+            updated: stat.updated,
+            removed: stat.removed
+          }))
+        };
+      }
+      if (activeLayers.has("emit")) {
+        const emits = /* @__PURE__ */ new Map();
+        for (const record of windowRecords.filter((record2) => record2.layer === "emit")) {
+          const event = readEventName(record.data);
+          const key = `${record.name}|${event}`;
+          const entry = emits.get(key) ?? { name: record.name, event, count: 0, at: record.at };
+          entry.count += 1;
+          entry.at = record.at;
+          emits.set(key, entry);
+        }
+        summary2.emit = [...emits.values()].sort((a, b) => b.count - a.count).slice(0, 10).map((entry) => ({
+          name: entry.name,
+          event: entry.event,
+          count: entry.count,
+          at: round2(entry.at - reference)
+        }));
+      }
+      if (activeLayers.has("navigate")) {
+        summary2.navigate = windowRecords.filter((record) => record.layer === "navigate").slice(-10).map((record) => ({ ...record.data, at: round2(record.at - reference) }));
+      }
+      if (activeLayers.has("agent")) {
+        summary2.agent = windowRecords.filter((record) => record.layer === "agent").slice(-10).map((record) => ({ label: record.name, at: round2(record.at - reference) }));
+      }
+      return summary2;
+    }
+  }
+  return { get, mark, clear, attachRouters, dispose };
+}
+function normalizeLayers(input) {
+  const allowed = new Set(VUE_DEVTOOLS_TIMELINE_LAYERS);
+  if (!Array.isArray(input) || input.length === 0) return allowed;
+  const picked = input.filter((layer) => allowed.has(layer));
+  return new Set(picked.length > 0 ? picked : allowed);
+}
+function jsonSize(value) {
+  try {
+    return JSON.stringify(value)?.length ?? 0;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+export {
+  DEVTOOLS_HOOK_EVENTS,
+  createTimelineRecorder
+};

package/es/core/mcp-tools.d.ts

@@ -56,6 +56,13 @@ export declare const CUSTOM_TOOLS: CustomTool[];
  * 页面桥接工具：描述与输入 schema（模型可见）+ 后端 action（调用分发）单一来源。
  * tools/list 与 tools/call 都取自本定义，避免"清单"与"路由"两份来源各自漂移。
  * 只在注入 Vue DevTools 桥的项目（Vue 项目）暴露。
+ *
+ * 描述写法（description 是模型唯一能看到的说明书，会随每次请求注入，所以既要准也要省）：
+ * 1. 第一行一句话说清"给什么"；
+ * 2. **何时使用**：正向场景 + 与相邻工具的分工；
+ * 3. **返回**：字段与形态（够推理即可，不重复 inputSchema 的参数说明）；
+ * 4. **注意**：会误导判断的边界必须写明"缺失 ≠ 没有 / ≠ 0"；
+ * 5. 只承诺实现里真有的能力——被裁剪/丢弃的数据要显式说明，不能让模型按描述去查一个永远为空的东西。
  */
 export interface VueDevtoolsTool extends CustomTool {
     /** 页面桥后端 action（endpoints/vue-devtools.ts executeAction） */