vite-plugin-aipanel 1.2.28 → 1.3.2

package/es/client/vue-devtools-bridge.d.ts

@@ -3,10 +3,12 @@
  * 注入到用户页面，初始化 @vue/devtools-kit 并暴露到 window.__aipanel_vue
  * AI 通过 Chrome DevTools evaluate_script 调用此 API
  *
- * API Proxy 自动对读操作做 safeStringify，getInspectorState 额外裁剪 Vue 内部数据
+ * - api Proxy：对读操作自动 safeStringify，getInspectorState 额外裁剪 Vue 内部数据；
+ * - timeline：页面侧时间线采集器（常驻采集，见 vue-devtools-timeline.ts）。
  */
 import { devtools, devtoolsRouter } from "@vue/devtools-kit";
-declare function safeStringify(obj: unknown): string;
+import { safeStringify } from "./vue-devtools-sanitize";
+import { type TimelineRecorder } from "./vue-devtools-timeline";
 declare const safeApi: {
     getInspectorTree(payload: Pick<import("@vue/devtools-kit").DevToolsV6PluginAPIHookPayloads[import("@vue/devtools-kit").DevToolsV6PluginAPIHookKeys.GET_INSPECTOR_TREE], "inspectorId" | "filter">): Promise<never[]>;
     getInspectorState(payload: Pick<import("@vue/devtools-kit").DevToolsV6PluginAPIHookPayloads[import("@vue/devtools-kit").DevToolsV6PluginAPIHookKeys.GET_INSPECTOR_STATE], "inspectorId" | "nodeId">): Promise<import("@vue/devtools-kit").CustomInspectorState>;
@@ -52,6 +54,7 @@ declare global {
             router: typeof devtoolsRouter;
             ctx: typeof devtools.ctx;
             safeStringify: typeof safeStringify;
+            timeline: TimelineRecorder;
         };
     }
 }

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

@@ -1,94 +1,8 @@
 import { devtools, devtoolsRouter } from "@vue/devtools-kit";
-const MAX_STRING_LENGTH = 150;
-const MAX_DEPTH = 3;
-const MAX_KEYS = 20;
-const VUE_INTERNAL_KEYS = /* @__PURE__ */ new Set([
-  "dep",
-  "subs",
-  "subsHead",
-  "deps",
-  "depsTail",
-  "activeLink",
-  "prevActiveLink",
-  "nextDep",
-  "prevDep",
-  "flags",
-  "globalVersion",
-  "sc",
-  "isSSR",
-  "__v_isRef",
-  "__v_isReadonly",
-  "__v_skip",
-  "computed",
-  "effect",
-  "setter",
-  "fn"
-]);
-const SKIP_STATE_TYPES = /* @__PURE__ */ new Set([
-  "provided",
-  "injected",
-  "event listeners",
-  "template refs"
-]);
-function isVueInternalObject(value) {
-  if (!value || typeof value !== "object") return false;
-  if (value.__isVue === true) return true;
-  const keys = Object.keys(value);
-  const internalCount = keys.filter((k) => VUE_INTERNAL_KEYS.has(k)).length;
-  return internalCount > 0 && internalCount >= keys.length * 0.5;
-}
-function sanitizeValue(value, depth = 0) {
-  if (depth > MAX_DEPTH) return "<max depth>";
-  if (value === null || value === "__undefined__") return null;
-  if (typeof value === "string") {
-    if (value.startsWith("data:") || value.length > MAX_STRING_LENGTH)
-      return `<${value.slice(0, 50)}... (${value.length} chars)>`;
-    if (value === "[Circular Reference]" || value === "[Function]") return null;
-    return value;
-  }
-  if (typeof value !== "object") return value;
-  if (Array.isArray(value)) {
-    return value.slice(0, MAX_KEYS).map((v) => sanitizeValue(v, depth + 1));
-  }
-  if (isVueInternalObject(value)) return null;
-  const result = {};
-  const keys = Object.keys(value).filter((k) => !k.startsWith("Symbol(")).slice(0, MAX_KEYS);
-  for (const key of keys) {
-    if (VUE_INTERNAL_KEYS.has(key)) continue;
-    const v = sanitizeValue(value[key], depth + 1);
-    if (v !== null) result[key] = v;
-  }
-  return Object.keys(result).length > 0 ? result : null;
-}
-function sanitizeState(state) {
-  const result = {};
-  for (const item of state) {
-    if (SKIP_STATE_TYPES.has(item.type)) continue;
-    if (!result[item.type]) result[item.type] = {};
-    const value = sanitizeValue(item.value);
-    if (value !== null) {
-      result[item.type][item.key] = {
-        value,
-        ...item.stateType ? { type: item.stateType } : {}
-      };
-    }
-  }
-  return result;
-}
-function safeStringify(obj) {
-  const seen = /* @__PURE__ */ new WeakSet();
-  return JSON.stringify(obj, (_key, value) => {
-    if (typeof value === "object" && value !== null) {
-      if (seen.has(value)) return "[Circular Reference]";
-      seen.add(value);
-    }
-    if (typeof value === "function") return "[Function]";
-    if (typeof value === "symbol") return value.toString();
-    if (typeof value === "bigint") return `${value}n`;
-    if (value === void 0) return "__undefined__";
-    return value;
-  });
-}
+import { safeStringify, sanitizeState } from "./vue-devtools-sanitize.mjs";
+import {
+  createTimelineRecorder
+} from "./vue-devtools-timeline.mjs";
 const READ_METHODS = /* @__PURE__ */ new Set([
   "getInspectorState",
   "getInspectorTree",
@@ -141,10 +55,30 @@ const safeApi = new Proxy(devtools.api, {
     };
   }
 });
+async function getInspectorTree() {
+  return devtools.api.getInspectorTree({ inspectorId: "components", filter: "" });
+}
+function asRouter(value) {
+  const router = value;
+  return router && typeof router.afterEach === "function" ? router : void 0;
+}
+function resolveRouter(app) {
+  const fromApp = asRouter(app?.config?.globalProperties?.$router);
+  return fromApp ?? asRouter(devtoolsRouter.value);
+}
 devtools.init();
+const globalHook = globalThis.__VUE_DEVTOOLS_GLOBAL_HOOK__;
+const timeline = createTimelineRecorder({
+  hook: globalHook,
+  getAppRecords: () => devtools.ctx.state.appRecords,
+  getInspectorTree,
+  resolveRouter
+});
+timeline.attachRouters();
 window.__aipanel_vue = {
   api: safeApi,
   router: devtoolsRouter,
   ctx: devtools.ctx,
-  safeStringify
+  safeStringify,
+  timeline
 };

package/es/client/vue-devtools-sanitize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 注入页面的 Vue DevTools 数据裁剪能力。
+ *
+ * 桥（vue-devtools-bridge）与时间线采集器（vue-devtools-timeline）共用同一套裁剪规则，
+ * 保证任何返回给 agent 的 Vue 数据都经过同样的截断/去内部字段处理。
+ */
+import type { InspectorState } from "@vue/devtools-kit";
+/**
+ * 对 agent 无意义、被刻意裁掉的状态分类（省 token）。
+ * 导出给工具描述做一致性守卫：描述必须显式告诉模型这些分类永远查不到，
+ * 否则模型会按描述去查、再把"查不到"读成"不存在"。
+ */
+export declare const SKIP_STATE_TYPES: ReadonlySet<string>;
+/**
+ * 裁剪后出现的**值级占位记号**（导出给工具描述做一致性守卫）。
+ * 不解释它们，模型会把占位读成真实值 —— 例如 `"__undefined__"` 被当成一个字符串 prop。
+ * 长字符串另有一种形态：`<前缀... (N chars)>`（见 sanitizeValue）。
+ */
+export declare const SANITIZE_PLACEHOLDERS: readonly ["__undefined__", "[Function]", "<max depth>"];
+export declare function sanitizeValue(value: unknown, depth?: number): unknown;
+/** 裁剪 InspectorState[]，去掉 Vue 内部数据和噪音类型 */
+export declare function sanitizeState(state: InspectorState[]): Record<string, unknown>;
+/**
+ * JSON 序列化：函数/符号/bigint/undefined 换成可读占位，并处理循环引用。
+ *
+ * 判环用**当前路径上的祖先链**，而不是"见过的所有对象"：
+ * 同一对象被多处引用是合法结构（DAG）——例如路由记录会被顶层数组与嵌套 children 同时引用
+ * （实测 `routes[0].meta === routes[6].children[0].meta` 且不是环）。seen-anywhere 会把它误标成
+ * `[Circular Reference]`，agent 读到假值、还以为数据真有环。真环仍标该占位；共享对象**重复输出**而不是被吞掉。
+ */
+export declare function safeStringify(obj: unknown): string;

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

@@ -0,0 +1,103 @@
+const MAX_STRING_LENGTH = 150;
+const MAX_DEPTH = 3;
+const MAX_KEYS = 20;
+const VUE_INTERNAL_KEYS = /* @__PURE__ */ new Set([
+  "dep",
+  "subs",
+  "subsHead",
+  "deps",
+  "depsTail",
+  "activeLink",
+  "prevActiveLink",
+  "nextDep",
+  "prevDep",
+  "flags",
+  "globalVersion",
+  "sc",
+  "isSSR",
+  "__v_isRef",
+  "__v_isReadonly",
+  "__v_skip",
+  "computed",
+  "effect",
+  "setter",
+  "fn"
+]);
+const SKIP_STATE_TYPES = /* @__PURE__ */ new Set([
+  "provided",
+  "injected",
+  "event listeners",
+  "template refs"
+]);
+const SANITIZE_PLACEHOLDERS = ["__undefined__", "[Function]", "<max depth>"];
+function isVueInternalObject(value) {
+  if (!value || typeof value !== "object") return false;
+  if (value.__isVue === true) return true;
+  const keys = Object.keys(value);
+  const internalCount = keys.filter((k) => VUE_INTERNAL_KEYS.has(k)).length;
+  return internalCount > 0 && internalCount >= keys.length * 0.5;
+}
+function sanitizeValue(value, depth = 0) {
+  if (depth > MAX_DEPTH) return "<max depth>";
+  if (value === null || value === "__undefined__") return null;
+  if (typeof value === "string") {
+    if (value.startsWith("data:") || value.length > MAX_STRING_LENGTH)
+      return `<${value.slice(0, 50)}... (${value.length} chars)>`;
+    if (value === "[Circular Reference]" || value === "[Function]") return null;
+    return value;
+  }
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") return "[Function]";
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_KEYS).map((v) => sanitizeValue(v, depth + 1));
+  }
+  if (isVueInternalObject(value)) return null;
+  const result = {};
+  const keys = Object.keys(value).filter((k) => !k.startsWith("Symbol(")).slice(0, MAX_KEYS);
+  for (const key of keys) {
+    if (VUE_INTERNAL_KEYS.has(key)) continue;
+    const v = sanitizeValue(value[key], depth + 1);
+    if (v !== null) result[key] = v;
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+function sanitizeState(state) {
+  const result = {};
+  for (const item of state) {
+    if (SKIP_STATE_TYPES.has(item.type)) continue;
+    if (!result[item.type]) result[item.type] = {};
+    const value = sanitizeValue(item.value);
+    if (value !== null) {
+      result[item.type][item.key] = {
+        value,
+        ...item.stateType ? { type: item.stateType } : {}
+      };
+    }
+  }
+  return result;
+}
+function safeStringify(obj) {
+  const ancestors = [];
+  return JSON.stringify(obj, function replacer(_key, value) {
+    if (typeof value === "object" && value !== null) {
+      while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) ancestors.pop();
+      if (ancestors.includes(value)) return "[Circular Reference]";
+      ancestors.push(value);
+      return value;
+    }
+    if (typeof value === "function") return "[Function]";
+    if (typeof value === "symbol") return value.toString();
+    if (typeof value === "bigint") return `${value}n`;
+    if (value === void 0) return "__undefined__";
+    return value;
+  });
+}
+export {
+  SANITIZE_PLACEHOLDERS,
+  SKIP_STATE_TYPES,
+  safeStringify,
+  sanitizeState,
+  sanitizeValue
+};

package/es/client/vue-devtools-timeline.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Vue DevTools 时间线采集器（页面侧，供 agent 调试）。
+ *
+ * 为什么自己实现存储：devtools-kit 的 timeline 事件只转发给已连接的 DevTools 客户端，不落盘
+ * （没有 clientConnected 时事件即发即弃），且内置层受 recordingState/highPerfModeEnabled 门控。
+ * 本模块直接订阅 `__VUE_DEVTOOLS_GLOBAL_HOOK__` 的原始 Vue 事件（实测不受上述两个门控影响），
+ * 在页面内存里维护一个有界环形缓冲，供 `vue-devtools_get_timeline` 按窗口查询。
+ *
+ * 采集约定：
+ * - 常驻采集（无 start/stop 状态）：`clear()` 等价于"从现在开始录"，`mark()` 只插边界不清历史；
+ * - 捕获期就把数据降级为 primitive（绝不持有 app/vm/instance 引用），生命周期事件只累计计数；
+ * - 所有 hook 回调都包在 try/catch 里：devtools hook 的 emit 是同步遍历，回调抛错会影响页面渲染。
+ */
+import { type VueDevtoolsTimelineInclude, type VueDevtoolsTimelineLayer } from "@aipanel/core";
+/**
+ * 原始 devtools hook 的事件名（唯一来源）。
+ * @vue/devtools-kit 的 DevToolsHooks 枚举只有 d.ts 声明、运行时未导出（import 值为 undefined），
+ * 故无法 import；这里集中定义一次，值对齐 @vue/devtools-kit@8.2.1 的 DevToolsHooks
+ * （dist/index.d.ts:718-733），升级该依赖时需同步核对（vue-devtools-timeline.test.ts 锁住配合行为）。
+ */
+export declare const DEVTOOLS_HOOK_EVENTS: {
+    readonly appInit: "app:init";
+    readonly appUnmount: "app:unmount";
+    readonly componentAdded: "component:added";
+    readonly componentUpdated: "component:updated";
+    readonly componentRemoved: "component:removed";
+    readonly componentEmit: "component:emit";
+    readonly performanceStart: "perf:start";
+    readonly performanceEnd: "perf:end";
+};
+/**
+ * devtools hook 的监听器签名随事件而异，注册时按动态签名处理（devtools-kit 自己用的是 `Function`）。
+ * `never[]` 是下界：任何声明了具体参数的监听器都能注册，但取出来调用时需按事件自行收窄。
+ */
+export type HookListener = (...args: never[]) => void;
+/**
+ * 原始 devtools hook 的最小结构。
+ * 不用 devtools-kit 的 DevToolsHook 类型：其 on() 的事件参数是未导出的枚举类型。
+ */
+export interface TimelineHook {
+    on(event: string, listener: HookListener): () => void;
+}
+/** Vue 应用实例上与时间线相关的最小形状（避免依赖 Vue 类型） */
+export interface TimelineAppLike {
+    _instance?: {
+        uid?: number;
+    };
+    /** devtools-kit 写在 app 上的记录标识；按引用比对 appRecords 会漏（实测出现 ?:uid） */
+    __VUE_DEVTOOLS_NEXT_APP_RECORD_ID__?: string;
+    __VUE_DEVTOOLS_NEXT_APP_RECORD__?: {
+        id?: string;
+    };
+}
+/** Vue 组件实例上与 nodeId 相关的最小形状 */
+export interface TimelineInstanceLike {
+    uid?: number;
+    root?: unknown;
+    type?: {
+        name?: string;
+        __name?: string;
+    };
+    /** devtools-kit 写在实例上的完整 nodeId（与组件树 id 同源） */
+    __VUE_DEVTOOLS_NEXT_UID__?: string;
+    /** 挂载早期 app 上还没有记录标识时，用它兜底解析 appId */
+    appContext?: {
+        app?: TimelineAppLike;
+    };
+}
+/** vue-router 实例上与时间线相关的最小形状 */
+export interface TimelineRouterLike {
+    afterEach: (handler: (to: unknown, from: unknown, failure?: unknown) => void) => () => void;
+}
+export interface TimelineAppRecord {
+    id: string;
+    app: unknown;
+}
+/** 时间线明细记录（t 为相对查询时刻的毫秒数，负数表示过去） */
+export interface TimelineRecord {
+    seq: number;
+    t: number;
+    layer: VueDevtoolsTimelineLayer;
+    kind: string;
+    name: string;
+    dur?: number;
+    nodeId?: string;
+    file?: string;
+    level?: "default" | "warning" | "error";
+    data?: unknown;
+}
+/** 时间线查询参数（来自 MCP 工具入参，全部可省略） */
+export interface TimelineQuery {
+    windowMs?: number;
+    sinceMark?: string;
+    layers?: string[];
+    minDurationMs?: number;
+    component?: string;
+    include?: VueDevtoolsTimelineInclude;
+    limit?: number;
+    /** 是否用最新组件树补全 file（默认开，2s 缓存） */
+    enrich?: boolean;
+}
+export interface TimelineQueryResult {
+    window: {
+        from: number;
+        to: number;
+        ms: number;
+        sinceMark?: string;
+    };
+    buffer: {
+        capacity: number;
+        size: number;
+        dropped: number;
+        /**
+         * 已丢弃记录里最新一条的时间（相对现在的 ms）。
+         * 用它判断"窗口内数据是否被丢弃过"：只有当它落在窗口内才说明窗口不完整。
+         */
+        droppedAtMsAgo?: number;
+        /** 窗口起点早于被丢弃的记录 ⇒ 窗口内数据不完整（与 droppedAtMsAgo 配套，避免误报） */
+        windowTruncated: boolean;
+        /** 只有 end 没有 start 的渲染次数（耗时缺失，不等于 0ms） */
+        unpaired: number;
+        /** 因长时间没有 end 而被清掉的 start 次数（同样属于耗时缺失） */
+        prunedStarts: number;
+        marks: number;
+        startedAtMsAgo: number;
+        bootId: string;
+        capture: {
+            hook: boolean;
+            routers: number;
+        };
+    };
+    summary: Record<string, unknown>;
+    records: TimelineRecord[];
+    /** 明细被 limit / 体积上限裁剪过（阈值裁剪见 omitted.perfBelowThreshold）——摘要计数不受影响 */
+    truncated: boolean;
+    /**
+     * 明细是否全量：omitted 三项全为 0 才为 true。判断"有没有被裁"只看这一个字段。
+     * include=summary 时 records 按请求为空、本字段恒 true（按请求口径，不代表窗口内没有事件）。
+     */
+    detailComplete: boolean;
+    /** 明细裁剪的去向，保证"没看到的不是没发生" */
+    omitted: {
+        perfBelowThreshold: number;
+        byLimit: number;
+        byPayload: number;
+    };
+    notes: string[];
+}
+export interface TimelineRecorderOptions {
+    hook?: TimelineHook;
+    getAppRecords?: () => TimelineAppRecord[];
+    /** 组件树（用于把 nodeId 补成源码文件路径） */
+    getInspectorTree?: () => Promise<unknown>;
+    /** 由桥决定如何从 Vue 应用取 router（采集器不感知 Vue 内部结构） */
+    resolveRouter?: (app: unknown) => TimelineRouterLike | undefined;
+    now?: () => number;
+    capacity?: number;
+}
+export interface TimelineRecorder {
+    get(query?: TimelineQuery): Promise<TimelineQueryResult>;
+    mark(label: string): {
+        markId: string;
+        buffered: number;
+    };
+    clear(): {
+        cleared: number;
+        marks: number;
+    };
+    /** 为已注册的应用补订阅 router（桥注入晚于 app 挂载时的兜底；正常路径由 app:init 覆盖） */
+    attachRouters(): void;
+    dispose(): void;
+}
+export declare function createTimelineRecorder(options?: TimelineRecorderOptions): TimelineRecorder;