vite-plugin-aipanel 1.2.0-beta.0

package/README.md

@@ -0,0 +1,72 @@
+# vite-plugin-aipanel
+
+在 Vite 开发环境中嵌入 AIPanel AI 助手，边聊天边改代码，HMR 实时预览。
+
+## 快速开始
+
+### 前置条件
+
+安装 [OpenCode CLI](https://opencode.ai)（AI 引擎，必须）：
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+### 1. 安装插件
+
+```bash
+npm install -D vite-plugin-aipanel
+```
+
+### 2. 配置 Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import aipanelAssistant from "vite-plugin-aipanel";
+
+export default defineConfig({
+  plugins: [aipanelAssistant()],
+});
+```
+
+### 3. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+Vite 插件会自动启动 AIPanel Web 服务并创建当前项目的 AI 会话。
+
+### 4. 安装浏览器扩展
+
+1. [下载扩展包](https://github.com/code-farmer-i/vite-plugin-aipanel/raw/main/packages/extension/aipanel-assistant.zip)
+2. 打开 Chrome，地址栏输入 `chrome://extensions/`
+3. 打开右上角**「开发者模式」**开关
+4. 解压下载的 `.zip`，点击**「加载已解压的扩展程序」**，选择解压后的文件夹
+5. 用 Chrome 打开 `localhost` 开发页面，点击工具栏中的 AIPanel 图标即可开始对话
+
+> Edge / Arc / Brave 操作步骤相同，入口分别是 `edge://extensions/` / `arc://extensions/` / `brave://extensions/`。
+
+## 工作原理
+
+```
+┌────────────────┐      ┌────────────────┐      ┌─────────────┐
+│  Vite 插件       │      │  浏览器扩展      │      │  OpenCode   │
+│  启动 Web 服务   │◀────▶│  侧边栏面板      │◀────▶│  AI 引擎    │
+│  代理跨域        │      │  页面上下文同步   │      │  会话管理    │
+└────────────────┘      └────────────────┘      └─────────────┘
+```
+
+- Vite 插件在项目启动时自动拉起 AIPanel Web 服务
+- 浏览器扩展检测到 `localhost` 页面后自动连接该服务
+- 实时同步页面 URL、标题等上下文给 AI
+- 多标签页自动切换对应项目的会话
+
+## 文档
+
+完整使用指南请访问 [在线文档](https://code-farmer-i.github.io/vite-plugin-aipanel/)。
+
+## License
+
+MIT

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

@@ -0,0 +1,58 @@
+/**
+ * Vue DevTools 桥接脚本
+ * 注入到用户页面，初始化 @vue/devtools-kit 并暴露到 window.__aipanel_vue
+ * AI 通过 Chrome DevTools evaluate_script 调用此 API
+ *
+ * API Proxy 自动对读操作做 safeStringify，getInspectorState 额外裁剪 Vue 内部数据
+ */
+import { devtools, devtoolsRouter } from "@vue/devtools-kit";
+declare function safeStringify(obj: unknown): string;
+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>;
+    editInspectorState(payload: import("@vue/devtools-kit").DevToolsV6PluginAPIHookPayloads[import("@vue/devtools-kit").DevToolsV6PluginAPIHookKeys.EDIT_INSPECTOR_STATE]): void;
+    sendInspectorState(inspectorId: string): void;
+    inspectComponentInspector(): Promise<string>;
+    cancelInspectComponentInspector(): void;
+    getComponentRenderCode(id: string): any;
+    scrollToComponent(id: string): void;
+    openInEditor: typeof import("@vue/devtools-kit").openInEditor;
+    getVueInspector: typeof import("@vue/devtools-kit").getComponentInspector;
+    toggleApp(id: string, options?: {
+        inspectingComponent?: boolean;
+    }): void;
+    inspectDOM(instanceId: string): void;
+    updatePluginSettings(pluginId: string, key: string, value: string): void;
+    getPluginSettings(pluginId: string): {
+        options: Record<string, {
+            label: string;
+            description?: string;
+        } & ({
+            type: "boolean";
+            defaultValue: boolean;
+        } | {
+            type: "choice";
+            defaultValue: string | number;
+            options: {
+                value: string | number;
+                label: string;
+            }[];
+            component?: "select" | "button-group";
+        } | {
+            type: "text";
+            defaultValue: string;
+        })> | null;
+        values: any;
+    };
+};
+declare global {
+    interface Window {
+        __aipanel_vue: {
+            api: typeof safeApi;
+            router: typeof devtoolsRouter;
+            ctx: typeof devtools.ctx;
+            safeStringify: typeof safeStringify;
+        };
+    }
+}
+export {};

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

@@ -0,0 +1,150 @@
+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;
+  });
+}
+const READ_METHODS = /* @__PURE__ */ new Set([
+  "getInspectorState",
+  "getInspectorTree",
+  "devtoolsState",
+  "getRouterInfo",
+  "getComponentRenderCode"
+]);
+async function isNodeIdValid(nodeId) {
+  const targetId = String(nodeId);
+  try {
+    const tree = await devtools.api.getInspectorTree({
+      inspectorId: "components",
+      filter: ""
+    });
+    const find = (nodes) => nodes.some((n) => n.id === targetId || find(n.children ?? []));
+    return find(tree);
+  } catch {
+    return false;
+  }
+}
+const safeApi = new Proxy(devtools.api, {
+  get(target, prop, receiver) {
+    const original = Reflect.get(target, prop, receiver);
+    if (typeof original !== "function" || !READ_METHODS.has(prop))
+      return original;
+    return async (...args) => {
+      if (prop === "getInspectorState") {
+        const nodeId = args[0]?.nodeId;
+        if (!await isNodeIdValid(nodeId)) {
+          return safeStringify({
+            error: `\u7EC4\u4EF6 ${String(nodeId)} \u5DF2\u5931\u6548\uFF08\u9875\u9762\u53EF\u80FD\u5DF2\u5237\u65B0\u6216\u7EC4\u4EF6\u5DF2\u5378\u8F7D\uFF09\uFF0C\u8BF7\u91CD\u65B0\u8C03\u7528 vue-devtools_get_component_tree \u83B7\u53D6\u6700\u65B0 nodeId \u540E\u518D\u8BD5\u3002`
+          });
+        }
+      }
+      try {
+        const raw = await original.apply(target, args);
+        if (prop === "getInspectorState") {
+          return safeStringify({
+            state: sanitizeState(
+              raw?.state ?? raw
+            )
+          });
+        }
+        return safeStringify(raw);
+      } catch (error) {
+        return safeStringify({
+          error: `\u7EC4\u4EF6\u72B6\u6001\u83B7\u53D6\u5931\u8D25\uFF08${error.message}\uFF09\u3002\u9875\u9762\u53EF\u80FD\u5DF2\u5237\u65B0\uFF0C\u8BF7\u91CD\u65B0\u8C03\u7528 vue-devtools_get_component_tree \u83B7\u53D6\u6700\u65B0 nodeId \u540E\u518D\u8BD5\u3002`
+        });
+      }
+    };
+  }
+});
+devtools.init();
+window.__aipanel_vue = {
+  api: safeApi,
+  router: devtoolsRouter,
+  ctx: devtools.ctx,
+  safeStringify
+};

package/es/core/injector.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetOptions } from "@aipanel/core";
+export declare function injectWidget(options: WidgetOptions): string;

package/es/core/injector.mjs

@@ -0,0 +1,15 @@
+import {
+  CONFIG_DATA_ATTR,
+  WIDGET_SCRIPT_PATH,
+  WIDGET_STYLE_PATH
+} from "@aipanel/core";
+function injectWidget(options) {
+  const configBase64 = Buffer.from(JSON.stringify(options)).toString("base64");
+  const scriptTag = `<script type="module" src="${WIDGET_SCRIPT_PATH}" ${CONFIG_DATA_ATTR}="${configBase64}"></script>`;
+  const styleTag = `<link rel="stylesheet" href="${WIDGET_STYLE_PATH}" />`;
+  return `${styleTag}
+${scriptTag}`;
+}
+export {
+  injectWidget
+};

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

@@ -0,0 +1,56 @@
+/**
+ * MCP Chrome 页面相关工具
+ *
+ * 专注于 Chrome DevTools 页面匹配与解析逻辑
+ */
+import type { ViteDevServer } from "vite";
+import type { McpProxy } from "./mcp-proxy";
+/** 从 Vite 服务器解析的所有 URL 中提取项目 origin 列表 */
+export declare function getProjectOrigins(server: ViteDevServer): string[];
+/** 判断页面 URL 是否属于项目的某个 origin */
+export declare function isProjectPage(url: string, origins: string[]): boolean;
+export interface PageInfo {
+    pageId: number;
+    url: string;
+    title: string;
+    /** Chrome DevTools 当前选中的页面 */
+    selected: boolean;
+}
+/** 解析 list_pages 返回的文本。格式："56: Title (URL) [selected]" */
+export declare function parseListPages(text: string): PageInfo[];
+/** 从 evaluate_script 返回的格式化文本中提取 JSON 值 */
+export declare function extractEvalValue(text: string | undefined): string | undefined;
+type PageIdResult = {
+    ok: true;
+    pageId: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 校验 pageId 是否属于项目页面
+ *
+ * 调用 list_pages → 过滤项目页面 → 检查 pageId 是否在范围内。
+ * 供 MCP 代理层和 Vue DevTools 端点共用。
+ */
+export declare function validatePageId(mcp: McpProxy, pageId: number, projectOrigins: string[]): Promise<{
+    valid: true;
+    projectPages: PageInfo[];
+} | {
+    valid: false;
+    error: string;
+    projectPages: PageInfo[];
+}>;
+/**
+ * 通过 MCP 解析当前页面对应的 Chrome DevTools pageId
+ *
+ * 策略：
+ * 1. list_pages → 解析每行的 "pageId: title (URL)" 格式
+ * 2. 仅用 sessionId（_aipanel_pk）匹配，跨导航可靠；不做 URL 降级匹配
+ *
+ * 失败时返回具体原因，由调用方透传给 Agent。
+ */
+export declare function resolveChromePageId(mcp: McpProxy | undefined, url: string, title: string, projectOrigins: string[], sessionId?: string, pages?: PageInfo[], 
+/** Chrome 当前选中的 pageId（调用方传入，避免过滤后丢失非项目页面信息） */
+chromeSelectedPageId?: number): Promise<PageIdResult>;
+export {};

package/es/core/mcp-chrome.mjs

@@ -0,0 +1,133 @@
+import { createLogger } from "@aipanel/core/node";
+const log = createLogger("McpChrome");
+function getProjectOrigins(server) {
+  const local = server.resolvedUrls?.local ?? [];
+  const network = server.resolvedUrls?.network ?? [];
+  const origins = [...new Set([...local, ...network].map((u) => new URL(u).origin))];
+  log.debug("project origins", { origins });
+  return origins;
+}
+function isProjectPage(url, origins) {
+  return origins.some((origin) => url.startsWith(origin));
+}
+function parseListPages(text) {
+  const pages = [];
+  for (const line of text.split("\n")) {
+    const match = line.match(/^(\d+):\s*(.+?)\s*\((\S+)\)/);
+    if (match) {
+      pages.push({
+        pageId: parseInt(match[1], 10),
+        title: match[2].replace(/\s*\.{3}$/, "").trim(),
+        url: match[3],
+        selected: /\[selected\]/i.test(line)
+      });
+    }
+  }
+  return pages;
+}
+function extractEvalValue(text) {
+  if (!text) return void 0;
+  const marker = "```json\n";
+  const startIdx = text.indexOf(marker);
+  if (startIdx < 0) return text.trim();
+  const contentStart = startIdx + marker.length;
+  const endIdx = text.indexOf("\n```", contentStart);
+  const jsonStr = endIdx < 0 ? text.substring(contentStart) : text.substring(contentStart, endIdx);
+  try {
+    return JSON.parse(jsonStr.trim());
+  } catch {
+    return jsonStr.trim();
+  }
+}
+async function validatePageId(mcp, pageId, projectOrigins) {
+  const listResult = await mcp.callChromeDevTool("list_pages", {});
+  if (listResult?.error || !listResult?.result) {
+    return {
+      valid: false,
+      error: listResult?.error?.message ?? "\u65E0\u6CD5\u83B7\u53D6 Chrome \u9875\u9762\u5217\u8868\uFF0C\u8BF7\u786E\u8BA4 Chrome DevTools \u5DF2\u8FDE\u63A5",
+      projectPages: []
+    };
+  }
+  const text = listResult?.result?.content?.[0]?.text;
+  const allPages = text ? parseListPages(text) : [];
+  const projectPages = allPages.filter((p) => isProjectPage(p.url, projectOrigins));
+  const isValid = projectPages.some((p) => p.pageId === pageId);
+  if (!isValid) {
+    return {
+      valid: false,
+      error: `pageId ${pageId} \u65E0\u6548\u6216\u975E\u9879\u76EE\u9875\u9762\uFF0C\u8BF7\u83B7\u53D6\u6709\u6548\u9875\u9762 ID`,
+      projectPages
+    };
+  }
+  return { valid: true, projectPages };
+}
+async function resolveChromePageId(mcp, url, title, projectOrigins, sessionId, pages, chromeSelectedPageId) {
+  if (!mcp || !mcp.isRunning) {
+    const reason = !mcp ? "MCP \u6A21\u5757\u672A\u521D\u59CB\u5316" : "Chrome DevTools MCP \u8FDB\u7A0B\u672A\u542F\u52A8";
+    log.debug(`resolveChromePageId: ${reason}`);
+    return { ok: false, error: reason };
+  }
+  if (!url) {
+    return { ok: false, error: "\u9875\u9762 URL \u4E3A\u7A7A\uFF0C\u5C1A\u672A\u6536\u5230\u4E0A\u4E0B\u6587\u4FE1\u606F" };
+  }
+  try {
+    if (!pages) {
+      const listResult = await mcp.callChromeDevTool("list_pages", {});
+      const text = listResult?.result?.content?.[0]?.text;
+      if (!text) {
+        return { ok: false, error: "\u65E0\u6CD5\u83B7\u53D6 Chrome \u9875\u9762\u5217\u8868\uFF0C\u8BF7\u786E\u8BA4\u5DF2\u6253\u5F00\u76EE\u6807\u9875\u9762" };
+      }
+      const allPages = parseListPages(text);
+      chromeSelectedPageId = allPages.find((p) => p.selected)?.pageId;
+      pages = allPages.filter((p) => isProjectPage(p.url, projectOrigins));
+    }
+    log.debug("resolveChromePageId: list_pages result", {
+      pages: pages.map((p) => ({ id: p.pageId, url: p.url, title: p.title.substring(0, 40) })),
+      target: { url, title }
+    });
+    if (sessionId) {
+      let matchedPageId = null;
+      for (const page of pages) {
+        await mcp.callChromeDevTool("select_page", { pageId: page.pageId, bringToFront: false });
+        const evalResult = await mcp.callChromeDevTool("evaluate_script", {
+          function: "() => sessionStorage.getItem('_aipanel_pk')"
+        });
+        const rawText = evalResult?.result?.content?.[0]?.text;
+        const extracted = extractEvalValue(rawText);
+        if (extracted === sessionId) {
+          matchedPageId = page.pageId;
+          break;
+        }
+      }
+      if (chromeSelectedPageId != null && chromeSelectedPageId !== matchedPageId) {
+        await mcp.callChromeDevTool("select_page", {
+          pageId: chromeSelectedPageId,
+          bringToFront: false
+        });
+      }
+      if (matchedPageId != null) {
+        return { ok: true, pageId: matchedPageId };
+      }
+      return {
+        ok: false,
+        error: `\u672A\u80FD\u901A\u8FC7\u4F1A\u8BDD\u6807\u8BC6\u627E\u5230\u76EE\u6807\u9875\u9762\uFF0C\u8BF7\u786E\u8BA4\u76EE\u6807\u9875\u9762\u5DF2\u6253\u5F00`
+      };
+    }
+    return {
+      ok: false,
+      error: `\u4E0A\u4E0B\u6587\u7F3A\u5C11\u4F1A\u8BDD\u6807\u8BC6\uFF08_aipanel_pk\uFF09\uFF0C\u65E0\u6CD5\u5B9A\u4F4D\u9875\u9762\uFF0C\u8BF7\u5237\u65B0\u76EE\u6807\u9875\u9762\u540E\u91CD\u8BD5`
+    };
+  } catch (err) {
+    const msg = `MCP \u8C03\u7528\u5931\u8D25: ${err.message}`;
+    log.debug("Failed to resolve pageId via MCP", { error: err.message });
+    return { ok: false, error: msg };
+  }
+}
+export {
+  extractEvalValue,
+  getProjectOrigins,
+  isProjectPage,
+  parseListPages,
+  resolveChromePageId,
+  validatePageId
+};

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

@@ -0,0 +1,23 @@
+export interface McpProxyOptions {
+    args?: string[];
+    idleTimeout?: number;
+}
+export declare class McpProxy {
+    #private;
+    readonly sessionId: string;
+    constructor(options?: McpProxyOptions);
+    get isRunning(): boolean;
+    start(): Promise<void>;
+    /** 转发原始 JSON-RPC 请求，保留客户端 ID */
+    forward(rawRequest: string): Promise<string>;
+    /** 调用 MCP 工具 */
+    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** 直接调用 chrome-devtools-mcp 底层工具（内部使用） */
+    callChromeDevTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** 验证 MCP 是否可用 + 预热 CDP 连接 */
+    verify(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    stop(): void;
+}