vite-plugin-aipanel 1.2.9 → 1.2.11

package/README.md

@@ -1,18 +1,33 @@
 # vite-plugin-aipanel
 
-在 Vite 开发环境中嵌入 AIPanel AI 助手，边聊天边改代码，HMR 实时预览。
+在 Vite 开发环境中嵌入 AIPanel AI 助手：浏览器扩展在任意 `localhost` 开发页面唤起 AI 侧边栏，边聊天边改代码，HMR 实时预览。
 
-支持 OpenCode 与 DeepSeek Harness (dsh) 两种 AI 引擎，通过 `provider` 配置一键切换。
+支持 **OpenCode** 与 **DeepSeek Harness (dsh)** 两种 AI 引擎，通过 `provider` 配置一键切换。
+
+## 环境要求
+
+- 任一 Vite ≥ 5 的 Node.js 项目
+- Chrome / Edge / Arc / Brave 等 Chromium 内核浏览器
+- 任选其一：OpenCode CLI（默认）或 DeepSeek Harness (dsh) CLI
 
 ## 快速开始
 
-### 1. 安装插件
+### 1. 安装 AI 引擎
+
+**默认引擎 OpenCode CLI：**
 
 ```bash
-npm install -D vite-plugin-aipanel
+curl -fsSL https://opencode.ai/install | bash
+opencode --version # 验证
 ```
 
-### 2. 配置 Vite
+> 使用 DeepSeek Harness 请改装：`npm i -g @deepseek-ai/dsh` + `npm i -D @aipanel/provider-deepseek`，并配置 `provider: "deepseek"`（见下）。
+
+### 2. 安装并配置 Vite 插件
+
+```bash
+npm install -D vite-plugin-aipanel
+```
 
 ```ts
 // vite.config.ts
@@ -24,67 +39,70 @@ export default defineConfig({
 });
 ```
 
-默认使用 **OpenCode** 引擎（详见下方「选择 AI 引擎」）。
-
 ### 3. 启动开发服务器
 
 ```bash
 npm run dev
 ```
 
-Vite 插件会自动启动 AIPanel Web 服务并创建当前项目的 AI 会话。
+插件自动完成：校验引擎 → 启动 AIPanel Web 服务（默认 5097）与代理（默认 6097，端口占用自动换）→ 复用/创建当前项目会话。
 
 ### 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/`。
-
-## 选择 AI 引擎
+2. Chrome 打开 `chrome://extensions/`，开启右上角**「开发者模式」**
+3. 解压 `.zip` → **「加载已解压的扩展程序」** → 选择解压目录
+4. 打开 `localhost` 开发页面，点击工具栏 **AIPanel 图标**（或 `Ctrl/Cmd + K`）唤起侧边栏
 
-插件内置两套 AI 引擎，通过 `providerOptions` 段的 `provider` 字段选择：
+> Edge / Arc / Brave 入口分别是 `edge://extensions/` / `arc://extensions/` / `brave://extensions/`。
 
-| provider     | 引擎                    | 额外依赖                        | 特点                           |
-| ------------ | ----------------------- | ------------------------------- | ------------------------------ |
-| `opencode`   | [OpenCode CLI](https://opencode.ai) | 无（插件内置）       | 默认引擎，通用 AI CLI         |
-| `deepseek`   | DeepSeek Harness (dsh)  | 另装 `@aipanel/provider-deepseek` | DeepSeek 官方 Web 对话界面 |
+## 切换 AI 引擎
 
-使用 DeepSeek Harness 引擎需先安装依赖：
+插件默认 `provider: "default"`（等价 `"opencode"`，适配已内置，仅需安装 opencode CLI）。
 
-```bash
-npm install -D @aipanel/provider-deepseek
-npm install -g @deepseek-ai/dsh
-```
+| provider  | 引擎                   | 额外依赖                                   | 说明                        |
+| --------- | ---------------------- | ------------------------------------------ | --------------------------- |
+| `default` | OpenCode CLI           | 无（适配内置；需另装 opencode CLI）        | 默认值，同 `opencode`    |
+| `opencode` | OpenCode CLI         | 无（适配内置；需另装 opencode CLI）        | 显式指定 OpenCode           |
+| `deepseek` | DeepSeek Harness (dsh) | `@aipanel/provider-deepseek` + dsh CLI   | DeepSeek 官方 Web 对话界面  |
 
 ```ts
-// 使用 DeepSeek Harness 引擎
+// 使用 DeepSeek Harness 引擎（先安装其依赖）
 aipanelAssistant({
   provider: "deepseek",
   providerOptions: {
-    // dsh 专属配置，详见在线文档
-    // home: "~/.dsh",          // dsh 数据目录
-    // agentPreset: "standard", // 新建会话的默认 Agent 预设
+    // home: "~/.dsh",                // dsh 数据目录
+    // agentPreset: "standard",       // 新建会话的默认 Agent 预设
     // permissionPreset: "read-only", // 默认权限预设
-    // busyEnter: "queue",      // 繁忙时 Enter 行为
+    // busyEnter: "queue",            // 繁忙时 Enter 行为
   },
 });
 ```
 
-> 已预装 OpenCode 与 dsh 其中之一的用户，插件会自动检测并使用。
+> **注意**：插件**不会自动探测**已安装的引擎，引擎由 `provider` 字段决定；切换前请确认对应 CLI 已安装。
 
 ## 纯净 MCP 模式
 
-`mcpOnly: true` 时，插件只暴露 MCP 工具服务（Chrome DevTools 控制、Vue DevTools、日志读取等），不注入挂件、不启动 AI 引擎，适合作为独立 MCP server 供外部 Agent 消费。
+`mcpOnly: true` 时，插件只暴露 MCP 工具服务（Chrome DevTools 控制、Vue DevTools、日志读取等），不启动 AI 引擎、不注入对话界面，适合作为独立 MCP server 供外部 Agent 消费：
 
 ```ts
 aipanelAssistant({ mcpOnly: true });
 ```
 
-启动后 MCP 端点挂在 Vite dev server 上，外部 MCP 客户端配置 Streamable HTTP 接入 `http://localhost:5173/__aipanel_mcp__`。
+端点挂在 Vite dev server 上（需保持 `vite dev` 运行），外部 MCP 客户端按 Streamable HTTP 配置：
+
+```json
+{
+  "mcpServers": {
+    "aipanel": {
+      "type": "http",
+      "url": "http://localhost:5173/__aipanel_mcp__"
+    }
+  }
+}
+```
+
+> 端口随 Vite dev server 变化（默认 5173），以启动日志中的 `MCP endpoint` 为准；`Claude Code` / `Cursor` 等客户端配置详见在线文档。
 
 ## 工作原理
 
@@ -107,4 +125,4 @@ aipanelAssistant({ mcpOnly: true });
 
 ## License
 
-MIT
+MIT

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,10 +1,23 @@
 /** chrome-devtools-mcp 的核心受保护参数（用户不可覆盖；始终最后注入确保生效） */
-export declare const CORE_MCP_ARGS: readonly ["--auto-connect", "--no-usage-statistics", "--no-performance-crux", "--no-page-id-routing"];
+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 {
     /** 用户透传的额外 CLI 参数（追加；与核心受保护项冲突的会被剔除） */
     userArgs?: string[];
+    /** 策略控制的内部注入参数（不经用户过滤，在用户参数之后、核心参数之前注入） */
+    managedArgs?: string[];
     /** 用户透传的额外环境变量（合并到 process.env 之上） */
     env?: Record<string, string>;
     idleTimeout?: number;

package/es/core/mcp-proxy.mjs

@@ -31,7 +31,11 @@ const CORE_MCP_ARGS = [
   // chrome-devtools-mcp >=1.8.0 默认开启 pageIdRouting（要求每个页面级工具都传 pageId）。
   // 代理层已自行校验 pageId 并用 select_page 选中目标页面后再转发，故显式关闭，
   // 避免底层工具 schema 强制必填 pageId 导致转发时的参数校验失败。
-  "--no-page-id-routing"
+  "--no-page-id-routing",
+  // 客户端未协商 roots，官方默认把文件工具限制在 OS 临时目录；
+  // 为保持 upload_file “不限制项目目录”的设计，显式允许任意路径
+  // （工具层仍受白名单 + pageId 归属约束）。
+  "--allow-unrestricted-paths"
 ];
 const PROTECTED_FLAGS = /* @__PURE__ */ new Set([
   "auto-connect",
@@ -39,6 +43,23 @@ const PROTECTED_FLAGS = /* @__PURE__ */ new Set([
   "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;
@@ -46,11 +67,25 @@ function canonicalFlagName(arg) {
   if (flag.startsWith("no-")) flag = flag.slice(3);
   return flag || null;
 }
-function filterUserMcpArgs(userArgs) {
-  return userArgs.filter((arg) => {
+function classifyUserMcpArgs(userArgs) {
+  const kept = [];
+  const dropped = [];
+  for (const arg of userArgs) {
     const name = canonicalFlagName(arg);
-    return name === null || !PROTECTED_FLAGS.has(name);
-  });
+    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");
@@ -81,12 +116,15 @@ class McpProxy {
     __privateAdd(this, _idleTimeout);
     __publicField(this, "sessionId");
     const userArgs = options.userArgs ?? [];
-    const filtered = filterUserMcpArgs(userArgs);
-    if (filtered.length !== userArgs.length) {
-      const dropped = userArgs.filter((a) => !filtered.includes(a));
-      log.warn("chrome MCP \u7528\u6237\u53C2\u6570\u4E0E\u6838\u5FC3\u53D7\u4FDD\u62A4\u9879\u51B2\u7A81\uFF0C\u5DF2\u5FFD\u7565", { dropped });
+    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 }
+      );
     }
-    __privateSet(this, _args, [...filtered, ...CORE_MCP_ARGS]);
+    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();
@@ -287,5 +325,6 @@ resetIdleTimer_fn = function() {
 export {
   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,50 @@ 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）。
+ * deny 同时作用于默认面与 extra，保证 tools/list 暴露面与 isAllowedToolName 调用守卫一致。
+ */
+export declare function currentOfficialShorts(): string[];
+/** tools/call 白名单守卫（含 current_page 与动态 extra/deny） */
+export declare function isAllowedToolName(name: string): boolean;