vite-plugin-aipanel 1.2.8 → 1.2.10

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

@@ -0,0 +1,15 @@
+/**
+ * 项目边界策略解析：在请求时把 chromeMcp.project 与 vite 自动 origins 合并为一份体。
+ * 所有边界判定（页面归属 / 导航目标 / 扩展页）均只读此解析结果，单一来源。
+ */
+import type { ViteDevServer } from "vite";
+import type { ChromeProjectOptions } from "@aipanel/core";
+export interface ProjectScope {
+    /** 项目页 origins（自动，“项目页全局一个”分类 + vue-devtools 桥可用范围） */
+    origins: string[];
+    /** 可操作范围 = 项目页 ∪ allowOrigins：chrome 页面级 list/current/pageId 校验、navigate/new 目标用 */
+    operationsOrigins: string[];
+    /** 是否允许 chrome-extension:// 页面纳入可操作范围 */
+    includeExtensions: boolean;
+}
+export declare function resolveProjectScope(server: ViteDevServer, project?: ChromeProjectOptions): ProjectScope;

package/es/core/chrome-project.mjs

@@ -0,0 +1,13 @@
+import { getProjectOrigins } from "./mcp-chrome.mjs";
+function resolveProjectScope(server, project) {
+  const auto = getProjectOrigins(server);
+  const operationsOrigins = [.../* @__PURE__ */ new Set([...auto, ...project?.allowOrigins ?? []])];
+  return {
+    origins: auto,
+    operationsOrigins,
+    includeExtensions: project?.includeExtensionPages === true
+  };
+}
+export {
+  resolveProjectScope
+};

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

@@ -7,8 +7,12 @@ import type { ViteDevServer } from "vite";
 import type { McpProxy } from "./mcp-proxy";
 /** 从 Vite 服务器解析的所有 URL 中提取项目 origin 列表 */
 export declare function getProjectOrigins(server: ViteDevServer): string[];
-/** 判断页面 URL 是否属于项目的某个 origin */
+/** 判断页面 URL 是否命中某个范围条目（allowOrigins 三种写法，见模块注释） */
+export declare function isOriginEntryMatch(url: string, entry: string): boolean;
+/** 判断页面 URL 是否命中某组范围条目（可为精确 origin / 通配符 / 正则） */
 export declare function isProjectPage(url: string, origins: string[]): boolean;
+/** 判断页面 URL 是否属于可操作范围（范围条目，或启用时的扩展页） */
+export declare function isPageAllowed(url: string, origins: string[], includeExtensions: boolean): boolean;
 export interface PageInfo {
     pageId: number;
     url: string;
@@ -28,18 +32,18 @@ type PageIdResult = {
     error: string;
 };
 /**
- * 校验 pageId 是否属于项目页面
+ * 校验 pageId 是否属于可操作范围（项目页 ∪ allowOrigins）
  *
- * 调用 list_pages → 过滤项目页面 → 检查 pageId 是否在范围内。
+ * 调用 list_pages → 过滤允许页面 → 检查 pageId 是否在范围内。
  * 供 MCP 代理层和 Vue DevTools 端点共用。
  */
-export declare function validatePageId(mcp: McpProxy, pageId: number, projectOrigins: string[]): Promise<{
+export declare function validatePageId(mcp: McpProxy, pageId: number, operationsOrigins: string[], includeExtensions?: boolean): Promise<{
     valid: true;
-    projectPages: PageInfo[];
+    allowedPages: PageInfo[];
 } | {
     valid: false;
     error: string;
-    projectPages: PageInfo[];
+    allowedPages: PageInfo[];
 }>;
 /**
  * 通过 MCP 解析当前页面对应的 Chrome DevTools pageId
@@ -50,7 +54,7 @@ export declare function validatePageId(mcp: McpProxy, pageId: number, projectOri
  *
  * 失败时返回具体原因，由调用方透传给 Agent。
  */
-export declare function resolveChromePageId(mcp: McpProxy | undefined, url: string, title: string, projectOrigins: string[], sessionId?: string, pages?: PageInfo[], 
-/** Chrome 当前选中的 pageId（调用方传入，避免过滤后丢失非项目页面信息） */
+export declare function resolveChromePageId(mcp: McpProxy | undefined, url: string, title: string, operationsOrigins: string[], sessionId?: string, pages?: PageInfo[], 
+/** Chrome 当前选中的 pageId（调用方传入，避免过滤后丢失范围外页面信息） */
 chromeSelectedPageId?: number): Promise<PageIdResult>;
 export {};

package/es/core/mcp-chrome.mjs

@@ -1,3 +1,4 @@
+import picomatch from "picomatch";
 import { createLogger } from "@aipanel/core/node";
 const log = createLogger("McpChrome");
 function getProjectOrigins(server) {
@@ -7,8 +8,45 @@ function getProjectOrigins(server) {
   log.debug("project origins", { origins });
   return origins;
 }
+const entryMatcherCache = /* @__PURE__ */ new Map();
+function parseRegexEntry(entry) {
+  if (!entry.startsWith("/")) return void 0;
+  const lastSlash = entry.lastIndexOf("/");
+  if (lastSlash <= 0) return void 0;
+  const source = entry.slice(1, lastSlash);
+  const flags = entry.slice(lastSlash + 1);
+  if (!/^[a-z]*$/.test(flags)) return void 0;
+  try {
+    return { kind: "regex", re: new RegExp(source, flags) };
+  } catch {
+    return void 0;
+  }
+}
+function compileEntryMatcher(entry) {
+  const cached = entryMatcherCache.get(entry);
+  if (cached) return cached;
+  let compiled = { kind: "prefix" };
+  const regexMatcher = parseRegexEntry(entry);
+  if (regexMatcher) {
+    compiled = regexMatcher;
+  } else if (picomatch.scan(entry).isGlob) {
+    compiled = { kind: "glob", match: picomatch(entry) };
+  }
+  entryMatcherCache.set(entry, compiled);
+  return compiled;
+}
+function isOriginEntryMatch(url, entry) {
+  const matcher = compileEntryMatcher(entry);
+  if (matcher.kind === "regex") return matcher.re.test(url);
+  if (matcher.kind === "glob") return matcher.match(url);
+  return url.startsWith(entry);
+}
 function isProjectPage(url, origins) {
-  return origins.some((origin) => url.startsWith(origin));
+  return origins.some((entry) => isOriginEntryMatch(url, entry));
+}
+function isPageAllowed(url, origins, includeExtensions) {
+  if (origins.some((entry) => isOriginEntryMatch(url, entry))) return true;
+  return includeExtensions && url.startsWith("chrome-extension://");
 }
 function parseListPages(text) {
   const pages = [];
@@ -39,29 +77,31 @@ function extractEvalValue(text) {
     return jsonStr.trim();
   }
 }
-async function validatePageId(mcp, pageId, projectOrigins) {
+async function validatePageId(mcp, pageId, operationsOrigins, includeExtensions = false) {
   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: []
+      allowedPages: []
     };
   }
   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);
+  const allowedPages = allPages.filter(
+    (p) => isPageAllowed(p.url, operationsOrigins, includeExtensions)
+  );
+  const isValid = allowedPages.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
+      error: `pageId ${pageId} \u4E0D\u5728\u53EF\u64CD\u4F5C\u8303\u56F4\uFF08\u9879\u76EE\u9875\u6216 allowOrigins \u767D\u540D\u5355\u9875\uFF09\uFF0C\u8BF7\u5148\u7528 list_pages \u83B7\u53D6\u6709\u6548\u9875\u9762 ID`,
+      allowedPages
     };
   }
-  return { valid: true, projectPages };
+  return { valid: true, allowedPages };
 }
-async function resolveChromePageId(mcp, url, title, projectOrigins, sessionId, pages, chromeSelectedPageId) {
+async function resolveChromePageId(mcp, url, title, operationsOrigins, 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}`);
@@ -79,7 +119,7 @@ async function resolveChromePageId(mcp, url, title, projectOrigins, sessionId, p
       }
       const allPages = parseListPages(text);
       chromeSelectedPageId = allPages.find((p) => p.selected)?.pageId;
-      pages = allPages.filter((p) => isProjectPage(p.url, projectOrigins));
+      pages = allPages.filter((p) => isProjectPage(p.url, operationsOrigins));
     }
     log.debug("resolveChromePageId: list_pages result", {
       pages: pages.map((p) => ({ id: p.pageId, url: p.url, title: p.title.substring(0, 40) })),
@@ -126,6 +166,8 @@ async function resolveChromePageId(mcp, url, title, projectOrigins, sessionId, p
 export {
   extractEvalValue,
   getProjectOrigins,
+  isOriginEntryMatch,
+  isPageAllowed,
   isProjectPage,
   parseListPages,
   resolveChromePageId,

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

@@ -1,5 +1,25 @@
+/** chrome-devtools-mcp 的核心受保护参数（用户不可覆盖；始终最后注入确保生效） */
+export declare const CORE_MCP_ARGS: readonly ["--auto-connect", "--no-usage-statistics", "--no-performance-crux", "--no-page-id-routing", "--allow-unrestricted-paths"];
+/** 过滤用户透传参数：剔除与核心受保护 flag 冲突的项，其余原样保留 */
+export type McpArgDropKind = "protected" | "managed";
+export interface McpArgDrop {
+    arg: string;
+    kind: McpArgDropKind;
+}
+/** 分类用户透传参数：保留可透传项，列出被剔除项及原因 */
+export declare function classifyUserMcpArgs(userArgs: readonly string[]): {
+    kept: string[];
+    dropped: McpArgDrop[];
+};
+/** 过滤用户透传参数：剔除与核心受保护/策略接管 flag 冲突的项 */
+export declare function filterUserMcpArgs(userArgs: readonly string[]): string[];
 export interface McpProxyOptions {
-    args?: string[];
+    /** 用户透传的额外 CLI 参数（追加；与核心受保护项冲突的会被剔除） */
+    userArgs?: string[];
+    /** 策略控制的内部注入参数（不经用户过滤，在用户参数之后、核心参数之前注入） */
+    managedArgs?: string[];
+    /** 用户透传的额外环境变量（合并到 process.env 之上） */
+    env?: Record<string, string>;
     idleTimeout?: number;
 }
 export declare class McpProxy {

package/es/core/mcp-proxy.mjs

@@ -17,13 +17,76 @@ var __privateWrapper = (obj, member, setter, getter) => ({
     return __privateGet(obj, member, getter);
   }
 });
-var _proc, _rl, _messageId, _internalIdBase, _pending, _args, _startPromise, _lastExit, _stderrTail, _idleTimer, _idleTimeout, _McpProxy_instances, doStart_fn, formatNotAvailable_fn, resetIdleTimer_fn;
+var _proc, _rl, _messageId, _internalIdBase, _pending, _args, _env, _startPromise, _lastExit, _stderrTail, _idleTimer, _idleTimeout, _McpProxy_instances, doStart_fn, formatNotAvailable_fn, resetIdleTimer_fn;
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import crypto from "node:crypto";
 import path from "node:path";
 import { createLogger, createPackageRequire, resolvePackageDir } from "@aipanel/core/node";
 const log = createLogger("McpProxy");
+const CORE_MCP_ARGS = [
+  "--auto-connect",
+  "--no-usage-statistics",
+  "--no-performance-crux",
+  // chrome-devtools-mcp >=1.8.0 默认开启 pageIdRouting（要求每个页面级工具都传 pageId）。
+  // 代理层已自行校验 pageId 并用 select_page 选中目标页面后再转发，故显式关闭，
+  // 避免底层工具 schema 强制必填 pageId 导致转发时的参数校验失败。
+  "--no-page-id-routing",
+  // 客户端未协商 roots，官方默认把文件工具限制在 OS 临时目录；
+  // 为保持 upload_file “不限制项目目录”的设计，显式允许任意路径
+  // （工具层仍受白名单 + pageId 归属约束）。
+  "--allow-unrestricted-paths"
+];
+const PROTECTED_FLAGS = /* @__PURE__ */ new Set([
+  "auto-connect",
+  "usage-statistics",
+  "performance-crux",
+  "page-id-routing"
+]);
+const MANAGED_FLAGS = /* @__PURE__ */ new Set([
+  "slim",
+  "category-extensions",
+  "category-pwa",
+  "category-experimental-third-party",
+  "category-experimental-webmcp",
+  "category-performance",
+  "category-network",
+  "category-emulation",
+  "experimental-vision",
+  "experimental-interop-tools",
+  "experimental-memory",
+  "experimental-screencast",
+  "experimental-structured-content",
+  "experimental-include-all-pages",
+  "allow-unrestricted-paths"
+]);
+function canonicalFlagName(arg) {
+  let flag = arg.trim();
+  if (!flag.startsWith("-")) return null;
+  flag = flag.replace(/^--?/, "").split("=")[0] ?? "";
+  if (flag.startsWith("no-")) flag = flag.slice(3);
+  return flag || null;
+}
+function classifyUserMcpArgs(userArgs) {
+  const kept = [];
+  const dropped = [];
+  for (const arg of userArgs) {
+    const name = canonicalFlagName(arg);
+    if (name === null) {
+      kept.push(arg);
+    } else if (PROTECTED_FLAGS.has(name)) {
+      dropped.push({ arg, kind: "protected" });
+    } else if (MANAGED_FLAGS.has(name)) {
+      dropped.push({ arg, kind: "managed" });
+    } else {
+      kept.push(arg);
+    }
+  }
+  return { kept, dropped };
+}
+function filterUserMcpArgs(userArgs) {
+  return classifyUserMcpArgs(userArgs).kept;
+}
 function resolveChromeDevToolsMcpBin() {
   const pluginDir = resolvePackageDir("vite-plugin-aipanel");
   const require2 = createPackageRequire(pluginDir);
@@ -43,6 +106,7 @@ class McpProxy {
     __privateAdd(this, _internalIdBase, 1e6);
     __privateAdd(this, _pending, /* @__PURE__ */ new Map());
     __privateAdd(this, _args);
+    __privateAdd(this, _env);
     __privateAdd(this, _startPromise, null);
     /** 最近一次进程退出信息，用于生成精确错误（无退出记录时为 null） */
     __privateAdd(this, _lastExit, null);
@@ -51,15 +115,17 @@ class McpProxy {
     __privateAdd(this, _idleTimer, null);
     __privateAdd(this, _idleTimeout);
     __publicField(this, "sessionId");
-    __privateSet(this, _args, options.args ?? [
-      "--auto-connect",
-      "--no-usage-statistics",
-      "--no-performance-crux",
-      // chrome-devtools-mcp >=1.8.0 默认开启 pageIdRouting（要求每个页面级工具都传 pageId）。
-      // 代理层已自行校验 pageId 并用 select_page 选中目标页面后再转发，故显式关闭，
-      // 避免底层工具 schema 强制必填 pageId 导致转发时的参数校验失败。
-      "--no-page-id-routing"
-    ]);
+    const userArgs = options.userArgs ?? [];
+    const { kept, dropped } = classifyUserMcpArgs(userArgs);
+    if (dropped.length > 0) {
+      log.warn(
+        "chrome MCP \u7528\u6237\u53C2\u6570\u4E0E\u53D7\u4FDD\u62A4/\u7B56\u7565\u63A5\u7BA1 flag \u51B2\u7A81\uFF0C\u5DF2\u5FFD\u7565\uFF1B\u8BF7\u7528 chromeMcp.project \u914D\u7F6E\u5BF9\u5E94\u884C\u4E3A",
+        { dropped }
+      );
+    }
+    const managedArgs = options.managedArgs ?? [];
+    __privateSet(this, _args, [...kept, ...managedArgs, ...CORE_MCP_ARGS]);
+    __privateSet(this, _env, options.env);
     __privateSet(this, _idleTimeout, options.idleTimeout ?? 0);
     this.sessionId = crypto.randomUUID();
   }
@@ -153,6 +219,7 @@ _messageId = new WeakMap();
 _internalIdBase = new WeakMap();
 _pending = new WeakMap();
 _args = new WeakMap();
+_env = new WeakMap();
 _startPromise = new WeakMap();
 _lastExit = new WeakMap();
 _stderrTail = new WeakMap();
@@ -166,7 +233,8 @@ doStart_fn = async function() {
     __privateSet(this, _lastExit, null);
     __privateSet(this, _stderrTail, []);
     __privateSet(this, _proc, spawn(process.execPath, [binPath, ...__privateGet(this, _args)], {
-      stdio: ["pipe", "pipe", "pipe"]
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...__privateGet(this, _env) }
     }));
     log.debug("Using local chrome-devtools-mcp");
   } catch {
@@ -255,5 +323,8 @@ resetIdleTimer_fn = function() {
   }, __privateGet(this, _idleTimeout)));
 };
 export {
-  McpProxy
+  CORE_MCP_ARGS,
+  McpProxy,
+  classifyUserMcpArgs,
+  filterUserMcpArgs
 };

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

@@ -1,8 +1,13 @@
 /**
- * 自定义 DevTools 工具定义
- * 所有工具（除 chrome-devtools_list_pages）必须传入 pageId 参数，
- * 代理层校验 pageId 是否为项目页面后方可调用 chrome-devtools-mcp。
+ * Chrome DevTools 工具层的项目维度元数据与自定义工具。
+ *
+ * 模型可见的 chrome-devtools_* 工具 = 官方 chrome-devtools-mcp 工具的白名单子集
+ * （schema/描述运行时同步自官方 tools/list，见 official-tools.ts）+ 本项目自定义工具。
+ * 工具层限制（白名单、必填 pageId、仅项目页）由本文件 + endpoints/mcp.ts 的 tools/call 共同执行。
  */
+/** 模型可见名前缀：官方短名 → chrome-devtools_<name> */
+export declare const MCP_PREFIX = "chrome-devtools_";
+export declare function displayToolName(short: string): string;
 export interface CustomTool {
     name: string;
     description: string;
@@ -12,4 +17,47 @@ export interface CustomTool {
         required?: string[];
     };
 }
+/**
+ * 默认暴露的官方页面级工具 = 元数据规则推导（pageScoped && 无条件 && 分类安全），
+ * 具体由 officialDefaultShorts() 给出。
+ * 以下为 meta 无法从 pageScoped 推断、需要“按页面上下文使用/列表/新建”的产品全局特例（短名）。
+ */
+export declare const OFFICIAL_GLOBAL_POLICY: readonly ["evaluate_script", "list_console_messages", "list_pages", "new_page"];
+export type OfficialToolShortName = string;
+/** 不需要 pageId 的官方工具（无目标页，由调用层特别处理） */
+export declare const OFFICIAL_NO_PAGE_TOOLS: ReadonlySet<string>;
+/** 目标页参数：pageId 必须在可操作范围（项目页或 allowOrigins 白名单页）内 */
+export declare const PAGE_ID_PROP: {
+    readonly pageId: {
+        readonly type: "number";
+        readonly description: "The ID of a page within the operation scope (project pages or chromeMcp.project.allowOrigins pages) to operate on";
+    };
+};
+/** 往官方 schema 上统一追加必填 pageId（保持工具层项目限制） */
+export declare function withPageIdSchema(schema: CustomTool["inputSchema"]): CustomTool["inputSchema"];
+/**
+ * 追加到官方描述末尾的项目维度说明（英文，按工具特例）。
+ * 只填“调用层真正实现的语义与官方不一样”的工具，
+ * 避免描述过度承诺（如 navigate_page 目标 URL 未被调用层限制，不填“必须在项目内”）。
+ * 其余页面级工具的项目边界由必填 pageId 参数说明表达（PAGE_ID_PROP）。
+ */
+export declare const PROJECT_DESCRIPTION_NOTES: Record<string, string>;
+/** 自定义工具（官方无对应，工具层本地实现） */
 export declare const CUSTOM_TOOLS: CustomTool[];
+/** 官方声明了条件、且属于可开启范围的工具（由官方元数据派生，无手写） */
+export declare function isOfficialExtraTool(short: string): boolean;
+/** 由官方 conditions 推导所需 flag（experimentalX → --experimental-x，与官方 CLI 一致） */
+export declare function extraToolFlag(short: string): string | undefined;
+/** 可开启的二级工具名单（用于验证与提示） */
+export declare function officialExtraCandidates(): string[];
+/**
+ * 默认暴露的官方工具集：
+ * 页面级（pageScoped && 无 conditions && 分类安全）由官方元数据规则推导 + 全局特例 GLOBAL_POLICY。
+ */
+export declare function officialDefaultShorts(): string[];
+/** 配置工具面范围（默认为纯白名单） */
+export declare function configureToolScope(extra?: readonly string[], deny?: readonly string[], warn?: (msg: string) => void): void;
+/** 当前生效的官方白名单（短名，含 extra 减 deny） */
+export declare function currentOfficialShorts(): string[];
+/** tools/call 白名单守卫（含 current_page 与动态 extra/deny） */
+export declare function isAllowedToolName(name: string): boolean;