vite-plugin-aipanel 1.2.27 → 1.3.1

package/lib/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;