web-extend-plugin-vue2 0.1.0 → 0.1.3

package/README.md

@@ -1,22 +1,52 @@
 # web-extend-plugin-vue2
 
-Vue 2.7 宿主侧 **Web 扩展插件**运行时：拉取清单、`hostApi`、菜单与 **`registerSlotComponents` 注册表**，以及 **`ExtensionPoint`**（同一组件覆盖内容区、工具栏等任意扩展点；插件在该点挂载 Vue 组件即可）。
+面向 **Vue 2.7** 宿主的 **Web 前端扩展插件**运行时（npm 包）。在浏览器中拉取插件清单、加载入口脚本、向插件注入 **`hostApi`**（路由 / 菜单 / 扩展点 / 受控请求桥等），并提供 **`ExtensionPoint`** 组件在布局中挂载插件视图。与后端清单服务、静态资源目录约定配套使用（如 `extend-plugin-framework` 中的 `web-extend-plugin-server`）。
 
-## 依赖
+## 安装
 
-- `peerDependencies`: `vue@^2.7`, `vue-router@^3.6`
-- `dependencies`: `semver`
+```bash
+npm add web-extend-plugin-vue2 vue@^2.7 vue-router@^3.6
+```
+
+## 最小接入
+
+```js
+import Vue from 'vue'
+import {
+  bootstrapPlugins,
+  createHostApi,
+  resolveRuntimeOptions,
+  ExtensionPoint
+} from 'web-extend-plugin-vue2'
+
+Vue.component('ExtensionPoint', ExtensionPoint) // 布局：<ExtensionPoint point-id="..." />
+
+const runtime = resolveRuntimeOptions({
+  // 按需覆盖，见 defaultWebExtendPluginRuntime
+})
+
+bootstrapPlugins(router, (id, r, kit) => createHostApi(id, r, kit), runtime).catch(console.warn)
+```
+
+清单请求 URL 为 **`manifestBase` + `manifestListPath`**（默认 `/fp-api` + `/api/frontend-plugins`）。工厂请使用 **`(id, r, kit) => createHostApi(id, r, kit)`**，以便 bridge 白名单等配置生效；若仍写 `(id) => createHostApi(id, router)`，仅清单侧配置会随 `runtime` 变化，bridge 仍为内置默认。
+
+## 配置与默认值
+
+- **优先级**：`bootstrapPlugins` 第三参 → `resolveRuntimeOptions({ ... })` 显式字段 → 环境变量 → 包内 **`defaultWebExtendPluginRuntime`**（可从本包导入）。
+- **完整字段列表**：见仓库 **`src/default-runtime-config.js`** 与 **`src/PluginRuntime.js`** 中的 `resolveRuntimeOptions`。
+- **环境变量**：支持 `VITE_*`；同等含义可用 **`PLUGIN_*`**（将 `VITE_` 换成 `PLUGIN_`）。Vite 使用 `PLUGIN_` 时需在 `vite.config` 设置 `envPrefix: ['VITE_', 'PLUGIN_']`；Webpack 用 `DefinePlugin` 注入 `process.env` 即可。
 
-## 在 Vite 宿主中使用
+## 卸载
 
 ```js
-import { bootstrapPlugins, createHostApi, registries } from 'web-extend-plugin-vue2'
+import { disposeWebPlugin } from 'web-extend-plugin-vue2'
 
-bootstrapPlugins(router, (pluginId) => createHostApi(pluginId, router)).catch(console.warn)
+disposeWebPlugin('your.plugin.id')
 ```
 
-开发环境下清单前缀、插件 Vite 联调等默认从 `import.meta.env`（`VITE_FRONTEND_PLUGIN_BASE`、`VITE_WEB_PLUGIN_DEV_*`）读取。非 Vite 或需覆盖时可传入第三参数，见源码 `resolveRuntimeOptions` / `WebExtendPluginRuntimeOptions`。
+Vue Router 3 无公开 `removeRoute`，动态路由卸载后可能需整页刷新。
 
-## 发布到 npm
+## 仓库与协议
 
-在包目录执行 `npm publish`（需有权限）。本仓库可用 `file:../web-extend-plugin-vue2` 联调示例宿主。
+- 源码：[extend-plugin-framework / web-extend-plugin-vue2](https://github.com/xtemplus/extend-plugin-framework/tree/master/web-extend-plugin-vue2)
+- 许可证：Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-extend-plugin-vue2",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Vue 2.7 host runtime for web-extend-plugin: manifest bootstrap, hostApi, registries, ExtensionPoint",
   "type": "module",
   "main": "./src/index.js",

package/src/PluginRuntime.js

@@ -1,66 +1,288 @@
-import * as semver from 'semver'
+/**
+ * 宿主侧插件引导：拉取清单、dev 映射、加载入口脚本、调用 activator。
+ * 路径与白名单等默认值见 `defaultWebExtendPluginRuntime`，可通过 `resolveRuntimeOptions` / 环境变量覆盖。
+ *
+ * **Webpack 宿主**：无 `import.meta.env` 时，用 `DefinePlugin` 注入 `process.env.VITE_*` 或 **`PLUGIN_*`**（等价键）或传入第三参。
+ *
+ * @module PluginRuntime
+ */
+import { coerce, satisfies } from 'semver'
 import { HOST_PLUGIN_API_VERSION } from './constants.js'
+import { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
+
+const DEF = defaultWebExtendPluginRuntime
 
 /**
  * @typedef {object} WebExtendPluginRuntimeOptions
- * @property {string} [manifestBase] 清单服务 URL 前缀，默认 `/fp-api` 或 `VITE_FRONTEND_PLUGIN_BASE`
- * @property {boolean} [isDev] 是否开发模式；默认取 Vite `import.meta.env.DEV`
- * @property {string} [webPluginDevOrigin] 插件 Vite dev origin，如 `http://localhost:5188`
- * @property {string} [webPluginDevIds] 逗号分隔插件 id，用于隐式 dev 入口
- * @property {string} [webPluginDevMapJson] JSON 字符串，id → 入口 URL，等价 `VITE_WEB_PLUGIN_DEV_MAP`
+ * @property {string} [manifestBase] 清单服务 URL 前缀
+ * @property {string} [manifestListPath] 清单接口路径（以 `/` 开头），拼在 manifestBase 后
+ * @property {RequestCredentials} [manifestFetchCredentials] 清单 fetch 的 credentials
+ * @property {boolean} [isDev] 开发模式
+ * @property {string} [webPluginDevOrigin] 插件 dev origin
+ * @property {string} [webPluginDevIds] 逗号分隔 id，隐式 dev 映射
+ * @property {string} [webPluginDevMapJson] 显式 dev 映射 JSON
+ * @property {string} [webPluginDevEntryPath] 隐式 dev 入口路径（相对插件 dev origin）
+ * @property {string} [devPingPath] dev 存活探测路径
+ * @property {string} [devReloadSsePath] dev 热更新 SSE 路径
+ * @property {number} [devPingTimeoutMs] 探测超时
+ * @property {string[]} [defaultImplicitDevPluginIds] 无 `webPluginDevIds`/env 时用于隐式 dev 的 id；包内默认 `[]`
+ * @property {string[]} [allowedScriptHosts] 允许加载脚本的主机名
+ * @property {string[]} [bridgeAllowedPathPrefixes] bridge.request 白名单前缀
+ * @property {boolean} [bootstrapSummary] bootstrap 结束是否打印摘要
  */
 
-/** 与清单里 entryUrl 的 hostname 一致；含 IPv6 本机，避免部分环境解析 localhost → ::1 后被宿主拒绝 */
-const DEFAULT_ALLOWED_HOSTS = new Set(['localhost', '127.0.0.1', '::1'])
-
-function viteEnv(key, fallback = '') {
+/**
+ * 从 Vite 注入的 `import.meta.env` 读取字符串配置。
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+function readImportMetaEnv(key) {
   try {
-    if (typeof import.meta !== 'undefined' && import.meta.env && import.meta.env[key] !== undefined) {
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
       const v = import.meta.env[key]
-      if (v !== '' && v !== undefined) return v
+      if (v !== undefined && v !== '') {
+        return String(v)
+      }
+    }
+  } catch (_) {}
+  return undefined
+}
+
+/**
+ * 从 Webpack `DefinePlugin` 等注入的 `process.env` 读取。
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+function readProcessEnv(key) {
+  try {
+    if (typeof process !== 'undefined' && process.env && key in process.env) {
+      const v = process.env[key]
+      if (v !== undefined && v !== '') {
+        return String(v)
+      }
     }
-  } catch (_) {
-    /* non-Vite bundler */
+  } catch (_) {}
+  return undefined
+}
+
+/**
+ * `VITE_*` 的并列命名：同值可读 `PLUGIN_*`（`VITE_WEB_PLUGIN_X` → `PLUGIN_WEB_PLUGIN_X`）。
+ * Vite 需在 `defineConfig({ envPrefix: ['VITE_', 'PLUGIN_'] })` 中暴露 `PLUGIN_`；Webpack 用 DefinePlugin 注入即可。
+ * @param {string} viteStyleKey 以 `VITE_` 开头的键名
+ * @returns {string|null}
+ */
+function viteKeyToPluginAlternate(viteStyleKey) {
+  if (typeof viteStyleKey !== 'string' || !viteStyleKey.startsWith('VITE_')) {
+    return null
   }
-  return fallback
+  return `PLUGIN_${viteStyleKey.slice(5)}`
 }
 
-function viteIsDev() {
+/**
+ * 先读 `VITE_*`，再读对应的 `PLUGIN_*`，再 `process.env`，最后 `fallback`。
+ * @param {string} key 仍以 `VITE_*` 为逻辑名（与文档一致）
+ * @param {string} [fallback='']
+ */
+function resolveBundledEnv(key, fallback = '') {
+  const alt = viteKeyToPluginAlternate(key)
+  const fromMeta =
+    readImportMetaEnv(key) ?? (alt ? readImportMetaEnv(alt) : undefined)
+  const fromProcess =
+    readProcessEnv(key) ?? (alt ? readProcessEnv(alt) : undefined)
+  return fromMeta ?? fromProcess ?? fallback
+}
+
+/**
+ * @returns {boolean}
+ */
+function resolveBundledIsDev() {
   try {
-    return !!import.meta.env.DEV
-  } catch (_) {
-    return false
+    if (typeof import.meta !== 'undefined' && import.meta.env && import.meta.env.DEV === true) {
+      return true
+    }
+  } catch (_) {}
+  try {
+    if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'development') {
+      return true
+    }
+  } catch (_) {}
+  return false
+}
+
+/**
+ * @param {string} p
+ */
+function ensureLeadingPath(p) {
+  const t = String(p || '').trim()
+  if (!t) {
+    return '/'
+  }
+  return t.startsWith('/') ? t : `/${t}`
+}
+
+/**
+ * 解析 `include` | `omit` | `same-origin`，非法时回退默认值。
+ * @param {string|undefined} userVal
+ * @param {string} envKey
+ * @param {RequestCredentials} fallback
+ */
+function resolveManifestCredentials(userVal, envKey, fallback) {
+  if (userVal !== undefined && userVal !== '') {
+    const s = String(userVal)
+    if (s === 'include' || s === 'omit' || s === 'same-origin') {
+      return s
+    }
+  }
+  const e = resolveBundledEnv(envKey, '')
+  if (e === 'include' || e === 'omit' || e === 'same-origin') {
+    return e
+  }
+  return fallback
+}
+
+/**
+ * @param {number|undefined} userVal
+ * @param {string} envKey
+ * @param {number} fallback
+ */
+function resolvePositiveInt(userVal, envKey, fallback) {
+  if (typeof userVal === 'number' && Number.isFinite(userVal) && userVal > 0) {
+    return Math.floor(userVal)
+  }
+  const raw = resolveBundledEnv(envKey, '')
+  const n = raw ? parseInt(raw, 10) : NaN
+  if (Number.isFinite(n) && n > 0) {
+    return n
   }
+  return fallback
 }
 
 /**
- * 合并宿主传入项与 Vite 环境变量（便于 npm 包在 Vite 宿主中零配置；亦可在非 Vite 场景显式传入）。
+ * 合并用户、环境变量与 `defaultWebExtendPluginRuntime`，得到完整运行时选项（宿主可只传需要覆盖的字段）。
  * @param {WebExtendPluginRuntimeOptions} [user]
+ * @returns {object}
  */
 export function resolveRuntimeOptions(user = {}) {
+  const manifestBaseRaw =
+    user.manifestBase !== undefined && user.manifestBase !== ''
+      ? String(user.manifestBase)
+      : resolveBundledEnv('VITE_FRONTEND_PLUGIN_BASE', DEF.manifestBase) || DEF.manifestBase
+
+  const manifestListPath = ensureLeadingPath(
+    user.manifestListPath !== undefined && user.manifestListPath !== ''
+      ? user.manifestListPath
+      : resolveBundledEnv('VITE_WEB_PLUGIN_MANIFEST_PATH', DEF.manifestListPath)
+  )
+
+  const defaultImplicitDevPluginIds =
+    Array.isArray(user.defaultImplicitDevPluginIds)
+      ? user.defaultImplicitDevPluginIds.map(String).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_IMPLICIT_DEV_IDS', '')
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => s.trim())
+              .filter(Boolean)
+          }
+          return [...DEF.defaultImplicitDevPluginIds]
+        })()
+
+  const allowedScriptHosts =
+    Array.isArray(user.allowedScriptHosts) && user.allowedScriptHosts.length > 0
+      ? user.allowedScriptHosts.map((h) => normalizeHost(String(h))).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_ALLOWED_SCRIPT_HOSTS', '')
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => normalizeHost(s.trim()))
+              .filter(Boolean)
+          }
+          return [...DEF.allowedScriptHosts]
+        })()
+
+  const bridgeAllowedPathPrefixes =
+    Array.isArray(user.bridgeAllowedPathPrefixes) && user.bridgeAllowedPathPrefixes.length > 0
+      ? user.bridgeAllowedPathPrefixes.map((p) => ensureLeadingPath(p)).filter(Boolean)
+      : (() => {
+          const e = resolveBundledEnv('VITE_WEB_PLUGIN_BRIDGE_PREFIXES', '')
+          if (e) {
+            return e
+              .split(',')
+              .map((s) => ensureLeadingPath(s.trim()))
+              .filter(Boolean)
+          }
+          return [...DEF.bridgeAllowedPathPrefixes]
+        })()
+
   return {
-    manifestBase:
-      user.manifestBase !== undefined && user.manifestBase !== ''
-        ? user.manifestBase
-        : viteEnv('VITE_FRONTEND_PLUGIN_BASE', '/fp-api') || '/fp-api',
-    isDev: user.isDev !== undefined ? user.isDev : viteIsDev(),
+    manifestBase: manifestBaseRaw.replace(/\/$/, '') || DEF.manifestBase.replace(/\/$/, ''),
+    manifestListPath,
+    manifestFetchCredentials: resolveManifestCredentials(
+      user.manifestFetchCredentials,
+      'VITE_WEB_PLUGIN_MANIFEST_CREDENTIALS',
+      DEF.manifestFetchCredentials
+    ),
+    isDev: user.isDev !== undefined ? user.isDev : resolveBundledIsDev(),
     webPluginDevOrigin:
-      user.webPluginDevOrigin !== undefined
-        ? user.webPluginDevOrigin
-        : viteEnv('VITE_WEB_PLUGIN_DEV_ORIGIN', ''),
+      user.webPluginDevOrigin !== undefined ? user.webPluginDevOrigin : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_ORIGIN', ''),
     webPluginDevIds:
-      user.webPluginDevIds !== undefined
-        ? user.webPluginDevIds
-        : viteEnv('VITE_WEB_PLUGIN_DEV_IDS', ''),
+      user.webPluginDevIds !== undefined ? user.webPluginDevIds : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_IDS', ''),
     webPluginDevMapJson:
       user.webPluginDevMapJson !== undefined
         ? user.webPluginDevMapJson
-        : viteEnv('VITE_WEB_PLUGIN_DEV_MAP', '')
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_MAP', ''),
+    webPluginDevEntryPath: ensureLeadingPath(
+      user.webPluginDevEntryPath !== undefined && user.webPluginDevEntryPath !== ''
+        ? user.webPluginDevEntryPath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_ENTRY', DEF.webPluginDevEntryPath)
+    ),
+    devPingPath: ensureLeadingPath(
+      user.devPingPath !== undefined && user.devPingPath !== ''
+        ? user.devPingPath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_PING_PATH', DEF.devPingPath)
+    ),
+    devReloadSsePath: ensureLeadingPath(
+      user.devReloadSsePath !== undefined && user.devReloadSsePath !== ''
+        ? user.devReloadSsePath
+        : resolveBundledEnv('VITE_WEB_PLUGIN_DEV_SSE_PATH', DEF.devReloadSsePath)
+    ),
+    devPingTimeoutMs: resolvePositiveInt(user.devPingTimeoutMs, 'VITE_WEB_PLUGIN_DEV_PING_TIMEOUT_MS', DEF.devPingTimeoutMs),
+    defaultImplicitDevPluginIds,
+    allowedScriptHosts,
+    bridgeAllowedPathPrefixes,
+    bootstrapSummary: user.bootstrapSummary
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ */
+function shouldShowBootstrapSummary(opts) {
+  if (opts.bootstrapSummary === true) {
+    return true
+  }
+  if (opts.bootstrapSummary === false) {
+    return false
+  }
+  const env = resolveBundledEnv('VITE_PLUGINS_BOOTSTRAP_SUMMARY', '')
+  if (env === '0' || env === 'false') {
+    return false
+  }
+  if (env === '1' || env === 'true') {
+    return true
   }
+  return resolveBundledIsDev()
 }
 
+/**
+ * @param {string} hostname
+ */
 function normalizeHost(hostname) {
-  if (!hostname) return ''
+  if (!hostname) {
+    return ''
+  }
   const h = hostname.toLowerCase()
   if (h.startsWith('[') && h.endsWith(']')) {
     return h.slice(1, -1)
@@ -68,16 +290,41 @@ function normalizeHost(hostname) {
   return h
 }
 
-function isScriptHostAllowed(url) {
+/**
+ * @param {string[]} hostnames
+ * @returns {Set<string>}
+ */
+function buildAllowedScriptHostsSet(hostnames) {
+  const s = new Set()
+  for (const h of hostnames) {
+    const n = normalizeHost(h)
+    if (n) {
+      s.add(n)
+    }
+  }
+  return s
+}
+
+/**
+ * @param {string} url
+ * @param {Set<string>} hostSet
+ */
+function isScriptHostAllowed(url, hostSet) {
+  if (typeof window === 'undefined') {
+    return false
+  }
   try {
     const u = new URL(url, window.location.origin)
     const h = normalizeHost(u.hostname)
-    return DEFAULT_ALLOWED_HOSTS.has(h)
+    return hostSet.has(h)
   } catch {
     return false
   }
 }
 
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ */
 function parseWebPluginDevMapExplicit(opts) {
   if (!opts.isDev) {
     return null
@@ -90,29 +337,48 @@ function parseWebPluginDevMapExplicit(opts) {
     const map = JSON.parse(String(raw))
     return map && typeof map === 'object' ? map : null
   } catch {
-    console.warn('[plugins] VITE_WEB_PLUGIN_DEV_MAP is not valid JSON')
+    console.warn('[plugins] webPluginDevMapJson / VITE_WEB_PLUGIN_DEV_MAP is not valid JSON')
     return null
   }
 }
 
-async function buildImplicitWebPluginDevMap(opts) {
+/**
+ * @param {ReturnType<typeof resolveRuntimeOptions>} opts
+ * @param {Set<string>} hostSet
+ */
+async function buildImplicitWebPluginDevMap(opts, hostSet) {
   if (!opts.isDev) {
     return {}
   }
-  const origin = opts.webPluginDevOrigin === undefined || opts.webPluginDevOrigin === null
-    ? ''
-    : String(opts.webPluginDevOrigin).trim()
+  const origin =
+    opts.webPluginDevOrigin === undefined || opts.webPluginDevOrigin === null
+      ? ''
+      : String(opts.webPluginDevOrigin).trim()
   if (!origin) {
     return {}
   }
-  if (!isScriptHostAllowed(`${origin}/`)) {
+  if (!isScriptHostAllowed(`${origin}/`, hostSet)) {
+    return {}
+  }
+
+  const idsRaw = opts.webPluginDevIds
+  const ids =
+    idsRaw !== undefined && idsRaw !== null && String(idsRaw).trim() !== ''
+      ? String(idsRaw)
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [...opts.defaultImplicitDevPluginIds]
+
+  if (ids.length === 0) {
     return {}
   }
+
   const base = origin.replace(/\/$/, '')
-  const pingUrl = `${base}/__web_plugin_dev_ping`
+  const pingUrl = `${base}${opts.devPingPath}`
   try {
     const ctrl = new AbortController()
-    const timer = setTimeout(() => ctrl.abort(), 500)
+    const timer = setTimeout(() => ctrl.abort(), opts.devPingTimeoutMs)
     const r = await fetch(pingUrl, {
       mode: 'cors',
       cache: 'no-store',
@@ -130,58 +396,88 @@ async function buildImplicitWebPluginDevMap(opts) {
     return {}
   }
 
-  const idsRaw = opts.webPluginDevIds
-  const ids =
-    idsRaw !== undefined && idsRaw !== null && String(idsRaw).trim() !== ''
-      ? String(idsRaw)
-          .split(',')
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : ['com.example.frontend.demo']
-
+  const pathPart = opts.webPluginDevEntryPath
   const map = {}
   for (const id of ids) {
-    map[id] = `${base}/src/plugin-entry.js`
+    map[id] = `${base}${pathPart}`
+  }
+  if (ids.length) {
+    console.info(
+      '[plugins] 已检测到插件 dev 服务（',
+      base,
+      '），下列 id 将加载隐式 dev 入口（',
+      pathPart,
+      '）而非清单 dist：',
+      ids.join(', ')
+    )
   }
-  console.info(
-    '[plugins] 已检测到插件 Vite（',
-    base,
-    '），下列 id 将加载源码入口而非清单 dist：',
-    ids.join(', ')
-  )
   return map
 }
 
+/**
+ * @param {Record<string, string>} implicit
+ * @param {Record<string, string>|null} explicit
+ */
 function mergeDevMaps(implicit, explicit) {
   const i = implicit && typeof implicit === 'object' ? implicit : {}
   const e = explicit && typeof explicit === 'object' ? explicit : {}
   return { ...i, ...e }
 }
 
-/** @type {Set<string>} */
-const pluginDevSseStarted = typeof window !== 'undefined' ? new Set() : new Set()
+/** @type {Map<string, EventSource>} */
+const pluginDevEventSources = new Map()
 
-function isDevOriginAllowedForSse(origin) {
+let pluginDevBeforeUnloadRegistered = false
+
+function closeAllPluginDevEventSources() {
+  for (const es of pluginDevEventSources.values()) {
+    try {
+      es.close()
+    } catch (_) {}
+  }
+  pluginDevEventSources.clear()
+}
+
+function ensurePluginDevBeforeUnload() {
+  if (pluginDevBeforeUnloadRegistered || typeof window === 'undefined') {
+    return
+  }
+  pluginDevBeforeUnloadRegistered = true
+  window.addEventListener('beforeunload', closeAllPluginDevEventSources)
+}
+
+/**
+ * @param {string} origin
+ * @param {Set<string>} hostSet
+ */
+function isDevOriginAllowedForSse(origin, hostSet) {
   try {
     const u = new URL(origin)
-    return DEFAULT_ALLOWED_HOSTS.has(normalizeHost(u.hostname))
+    return hostSet.has(normalizeHost(u.hostname))
   } catch {
     return false
   }
 }
 
-function startPluginDevReloadSse(origin, isDev) {
-  if (!isDev || pluginDevSseStarted.has(origin)) {
+/**
+ * @param {string} origin
+ * @param {boolean} isDev
+ * @param {Set<string>} hostSet
+ * @param {string} ssePath
+ */
+function startPluginDevReloadSse(origin, isDev, hostSet, ssePath) {
+  if (!isDev || pluginDevEventSources.has(origin)) {
     return
   }
-  if (!isDevOriginAllowedForSse(origin)) {
+  if (!isDevOriginAllowedForSse(origin, hostSet)) {
     return
   }
-  pluginDevSseStarted.add(origin)
+  ensurePluginDevBeforeUnload()
   const base = origin.replace(/\/$/, '')
-  const url = `${base}/__web_plugin_reload_stream`
+  const url = `${base}${ssePath}`
   try {
     const es = new EventSource(url)
+    pluginDevEventSources.set(origin, es)
     es.addEventListener('reload', () => {
       window.location.reload()
     })
@@ -193,8 +489,14 @@ function startPluginDevReloadSse(origin, isDev) {
   }
 }
 
-function startPluginDevSseForMap(devMap, isDev) {
-  if (!isDev || !devMap) {
+/**
+ * @param {Record<string, string>|null|undefined} devMap
+ * @param {boolean} isDev
+ * @param {Set<string>} hostSet
+ * @param {string} ssePath
+ */
+function startPluginDevSseForMap(devMap, isDev, hostSet, ssePath) {
+  if (!isDev || !devMap || typeof window === 'undefined') {
     return
   }
   const origins = new Set()
@@ -213,40 +515,84 @@ function startPluginDevSseForMap(devMap, isDev) {
     }
   }
   for (const o of origins) {
-    startPluginDevReloadSse(o, isDev)
+    startPluginDevReloadSse(o, isDev, hostSet, ssePath)
   }
 }
 
+const loadScriptMemo = new Map()
+
 function loadScript(src) {
-  return new Promise((resolve, reject) => {
+  if (typeof document === 'undefined') {
+    return Promise.reject(new Error('loadScript: no document'))
+  }
+  if (loadScriptMemo.has(src)) {
+    return loadScriptMemo.get(src)
+  }
+  const p = new Promise((resolve, reject) => {
+    const scripts = document.getElementsByTagName('script')
+    for (let i = 0; i < scripts.length; i++) {
+      const el = scripts[i]
+      if (el.src === src) {
+        if (el.getAttribute('data-wep-loaded') === 'true') {
+          resolve()
+          return
+        }
+        el.addEventListener(
+          'load',
+          () => {
+            el.setAttribute('data-wep-loaded', 'true')
+            resolve()
+          },
+          { once: true }
+        )
+        el.addEventListener('error', () => reject(new Error('loadScript failed: ' + src)), { once: true })
+        return
+      }
+    }
     const s = document.createElement('script')
     s.async = true
     s.src = src
-    s.onload = () => resolve()
+    s.onload = () => {
+      s.setAttribute('data-wep-loaded', 'true')
+      resolve()
+    }
     s.onerror = () => reject(new Error('loadScript failed: ' + src))
     document.head.appendChild(s)
   })
+  loadScriptMemo.set(src, p)
+  p.catch(() => loadScriptMemo.delete(src))
+  return p
 }
 
-async function loadPluginEntry(p, entryUrl, devMap) {
+/**
+ * @param {{ id: string }} p
+ * @param {string} [entryUrl]
+ * @param {Record<string, string>|null|undefined} devMap
+ * @param {Set<string>} hostSet
+ */
+async function loadPluginEntry(p, entryUrl, devMap, hostSet) {
   const devEntry = devMap && typeof devMap[p.id] === 'string' ? devMap[p.id].trim() : ''
   if (devEntry) {
-    if (!isScriptHostAllowed(devEntry)) {
+    if (!isScriptHostAllowed(devEntry, hostSet)) {
       console.warn('[plugins] dev entry URL not allowed', p.id, devEntry)
       return
     }
     try {
-      await import(/* @vite-ignore */ devEntry)
+      await import(
+        /* webpackIgnore: true */
+        /* @vite-ignore */
+        devEntry
+      )
     } catch (e) {
       console.warn('[plugins] dev module import failed, try manifest entryUrl', p.id, e)
-      if (entryUrl && isScriptHostAllowed(entryUrl)) {
+      if (entryUrl && isScriptHostAllowed(entryUrl, hostSet)) {
         await loadScript(entryUrl)
       }
       return
     }
     return
   }
-  if (!entryUrl || !isScriptHostAllowed(entryUrl)) {
+  if (!entryUrl || !isScriptHostAllowed(entryUrl, hostSet)) {
     console.warn('[plugins] skip (entryUrl not allowed)', p.id, entryUrl)
     return
   }
@@ -255,18 +601,25 @@ async function loadPluginEntry(p, entryUrl, devMap) {
 
 /**
  * @param {import('vue-router').default} router
- * @param {(pluginId: string) => object} createHostApi
- * @param {WebExtendPluginRuntimeOptions} [runtimeOptions] 可选；不传则从 Vite `import.meta.env` 读取（若存在）
+ * @param {(pluginId: string, router: import('vue-router').default, hostKit?: { bridgeAllowedPathPrefixes: string[] }) => object} createHostApiFactory
+ *        始终传入三个参数；单参工厂 `(id) => createHostApi(id, router)` 仍可用，后两个实参被忽略。
+ * @param {WebExtendPluginRuntimeOptions} [runtimeOptions]
  */
-export async function bootstrapPlugins(router, createHostApi, runtimeOptions) {
+export async function bootstrapPlugins(router, createHostApiFactory, runtimeOptions) {
+  if (typeof window === 'undefined') {
+    console.warn('[plugins] bootstrapPlugins skipped: requires browser (window)')
+    return
+  }
   const opts = resolveRuntimeOptions(runtimeOptions || {})
   const base = String(opts.manifestBase).replace(/\/$/, '')
+  const manifestUrl = `${base}${opts.manifestListPath}`
+  const hostSet = buildAllowedScriptHostsSet(opts.allowedScriptHosts)
   const explicit = parseWebPluginDevMapExplicit(opts)
 
   const [manifestResult, implicit] = await Promise.all([
     (async () => {
       try {
-        const res = await fetch(`${base}/api/frontend-plugins`, { credentials: 'include' })
+        const res = await fetch(manifestUrl, { credentials: opts.manifestFetchCredentials })
         if (!res.ok) {
           return { ok: false, status: res.status, data: null }
         }
@@ -276,32 +629,40 @@ export async function bootstrapPlugins(router, createHostApi, runtimeOptions) {
         return { ok: false, error: e, data: null }
       }
     })(),
-    buildImplicitWebPluginDevMap(opts)
+    buildImplicitWebPluginDevMap(opts, hostSet)
   ])
 
   const devMap = mergeDevMaps(implicit, explicit)
-  startPluginDevSseForMap(devMap, opts.isDev)
+  startPluginDevSseForMap(devMap, opts.isDev, hostSet, opts.devReloadSsePath)
+
+  const hostKit = { bridgeAllowedPathPrefixes: opts.bridgeAllowedPathPrefixes }
 
   if (!manifestResult.ok) {
     if (manifestResult.error) {
       console.warn('[plugins] fetch manifest failed', manifestResult.error)
     } else {
-      console.warn('[plugins] manifest HTTP', manifestResult.status)
+      console.warn('[plugins] manifest HTTP', manifestResult.status, manifestUrl)
+    }
+    if (shouldShowBootstrapSummary(opts)) {
+      console.info('[plugins] bootstrap_summary', { ok: false, reason: 'manifest_fetch' })
     }
     return
   }
   /** @type {{ hostPluginApiVersion?: string, plugins?: object[] }} */
   const data = manifestResult.data
   if (!data) {
+    if (shouldShowBootstrapSummary(opts)) {
+      console.info('[plugins] bootstrap_summary', { ok: false, reason: 'manifest_empty_body' })
+    }
     return
   }
 
   const apiVer = data.hostPluginApiVersion
   if (apiVer) {
-    const coerced = semver.coerce(apiVer)
+    const coerced = coerce(apiVer)
     const maj = coerced ? coerced.major : 0
     const range = `^${maj}.0.0`
-    if (!semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
+    if (!satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
       console.warn(
         '[plugins] host API version mismatch: host implements',
         HOST_PLUGIN_API_VERSION,
@@ -316,32 +677,53 @@ export async function bootstrapPlugins(router, createHostApi, runtimeOptions) {
   const plugins = data.plugins || []
   if (plugins.length === 0) {
     console.info(
-      '[plugins] 清单为空。请检查：① web-extend-plugin-server 是否已启动；② 其 JVM 工作目录下 web-plugins-dir 是否指向含 manifest 的目录（通常应在 web-extend-plugin-server 目录执行 mvn spring-boot:run，且存在 ../web-plugins/子目录）；③ 浏览器访问清单 URL 是否有 plugins 条目。'
+      '[plugins] 清单为空。请检查：① web-extend-plugin-server 是否已启动；② frontend-plugin.web-plugins-dir 是否指向含各插件子目录及 manifest.json 的路径；③ 浏览器直接访问',
+      manifestUrl,
+      '是否返回 plugins 条目。'
     )
   }
+
+  const summary = {
+    manifestCount: plugins.length,
+    activated: 0,
+    skipEngines: 0,
+    skipLoad: 0,
+    skipNoActivator: 0,
+    activateFail: 0
+  }
+
   for (const p of plugins) {
     const range = p.engines && p.engines.host
-    if (range && !semver.satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
+    if (range && !satisfies(HOST_PLUGIN_API_VERSION, range, { includePrerelease: true })) {
       console.warn('[plugins] skip (engines.host)', p.id, range)
+      summary.skipEngines++
       continue
     }
     const entryUrl = p.entryUrl
     try {
-      await loadPluginEntry(p, entryUrl, devMap)
+      await loadPluginEntry(p, entryUrl, devMap, hostSet)
     } catch (e) {
       console.warn('[plugins] script load failed', p.id, e)
+      summary.skipLoad++
       continue
     }
     const activator = window.__PLUGIN_ACTIVATORS__[p.id]
     if (typeof activator !== 'function') {
       console.warn('[plugins] no activator for', p.id)
+      summary.skipNoActivator++
       continue
     }
-    const hostApi = createHostApi(p.id)
+    const hostApi = createHostApiFactory(p.id, router, hostKit)
     try {
       activator(hostApi)
+      summary.activated++
     } catch (e) {
       console.error('[plugins] activate failed', p.id, e)
+      summary.activateFail++
     }
   }
+
+  if (shouldShowBootstrapSummary(opts)) {
+    console.info('[plugins] bootstrap_summary', { ok: true, ...summary })
+  }
 }

package/src/bridge.js

@@ -1,15 +1,43 @@
-const ALLOWED_PREFIXES = ['/api/']
+/**
+ * 插件通过宿主访问后端的受控通道：仅允许配置的前缀路径，默认 `/api/`；强制默认 `same-origin` 携带 Cookie。
+ * 前缀列表由 `createRequestBridge({ allowedPathPrefixes })` 传入，与 `defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes` 对齐。
+ *
+ * @module bridge
+ */
+import { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
+
+/**
+ * @param {string} p
+ */
+function ensureLeadingSlash(p) {
+  const t = String(p || '').trim()
+  if (!t) {
+    return '/'
+  }
+  return t.startsWith('/') ? t : `/${t}`
+}
 
 /**
- * @returns {{ request: (path: string, init?: RequestInit) => Promise<Response> }}
+ * @param {{ allowedPathPrefixes?: string[] }} [config]
  */
-export function createRequestBridge() {
+export function createRequestBridge(config = {}) {
+  const raw =
+    Array.isArray(config.allowedPathPrefixes) && config.allowedPathPrefixes.length > 0
+      ? config.allowedPathPrefixes
+      : defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes
+  const allowedPathPrefixes = raw.map((p) => ensureLeadingSlash(p))
+
   return {
+    /**
+     * 发起受控 `fetch`。
+     * @param {string} path 必须以 `/` 开头，且匹配某一 `allowedPathPrefixes` 前缀
+     * @param {RequestInit} [init] 会与默认 `{ credentials: 'same-origin' }` 合并（后者可被覆盖）
+     */
     async request(path, init = {}) {
       if (typeof path !== 'string' || !path.startsWith('/')) {
         throw new Error('[bridge] path must be a string starting with /')
       }
-      const allowed = ALLOWED_PREFIXES.some((p) => path.startsWith(p))
+      const allowed = allowedPathPrefixes.some((p) => path.startsWith(p))
       if (!allowed) {
         throw new Error('[bridge] path not allowed: ' + path)
       }

package/src/bridge.test.js

@@ -26,4 +26,13 @@ describe('createRequestBridge', () => {
     await expect(bridge.request('/fp-api/x')).rejects.toThrow(/not allowed/)
     await expect(bridge.request('http://evil.com/api/x')).rejects.toThrow()
   })
+
+  it('honors custom allowedPathPrefixes', async () => {
+    const bridge = createRequestBridge({ allowedPathPrefixes: ['/fp-api/'] })
+    await bridge.request('/fp-api/frontend-plugins')
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      '/fp-api/frontend-plugins',
+      expect.objectContaining({ credentials: 'same-origin' })
+    )
+  })
 })

package/src/components/ExtensionPoint.vue

@@ -11,6 +11,10 @@
 </template>
 
 <script>
+/**
+ * 在宿主布局中声明扩展点；插件通过 `hostApi.registerSlotComponents(pointId, ...)` 注入组件。
+ * 使用 `Vue.observable` 注册表驱动重渲染；子树错误由边界组件捕获，避免拖垮整页。
+ */
 import { registries } from '../registries.js'
 
 const SlotErrorBoundary = {
@@ -46,6 +50,7 @@ export default {
   },
   computed: {
     items() {
+      void registries.slotRevision
       return registries.slots[this.pointId] || []
     },
     forwardProps() {

package/src/constants.js

@@ -1,2 +1,5 @@
-/** Must match web-extend-plugin-server FrontendPluginsResponse.hostPluginApiVersion */
+/**
+ * 与 `web-extend-plugin-server` 返回的 `FrontendPluginsResponse.hostPluginApiVersion` 保持一致，用于契约校验。
+ * @type {string}
+ */
 export const HOST_PLUGIN_API_VERSION = '1.0.0'

package/src/createHostApi.js

@@ -1,16 +1,68 @@
+/**
+ * 构造供插件 activator 调用的宿主 API（路由、菜单、扩展点、资源注入等）。
+ * 与打包工具无关；Webpack 宿主需已配置 `vue-loader` 以编译本包内的 `.vue` 依赖。
+ *
+ * @module createHostApi
+ */
 import Vue from 'vue'
 import { HOST_PLUGIN_API_VERSION } from './constants.js'
 import { createRequestBridge } from './bridge.js'
+import { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
 import { registries } from './registries.js'
+import { registerPluginTeardown } from './teardown-registry.js'
+
+/** 扩展点列表项 key 递增，避免用 Date.now() 导致列表重排时误卸载组件 */
+let slotItemKeySeq = 0
+/** 无 name 的动态路由合成名递增，避免多次 registerRoutes 重名 */
+let routeSynthSeq = 0
+
+/**
+ * @typedef {object} RegisterSlotEntry
+ * @property {import('vue').Component} component
+ * @property {number} [priority]
+ */
 
 /**
- * @param {string} pluginId
- * @param {import('vue-router').default} router
+ * @typedef {object} HostApi
+ * @property {string} hostPluginApiVersion 宿主实现的协议版本
+ * @property {(routes: import('vue-router').RouteConfig[]) => void} registerRoutes 注册路由；无 `name` 时自动生成稳定合成名；优先 `router.addRoute`
+ * @property {(items: object[]) => void} registerMenuItems 注册菜单并按 `order` 排序
+ * @property {(pointId: string, components: RegisterSlotEntry[]) => void} registerSlotComponents 向扩展点挂载组件
+ * @property {(urls?: string[]) => void} registerStylesheetUrls 注入 `link[rel=stylesheet]`，带 `data-plugin-asset`
+ * @property {(urls?: string[]) => void} registerScriptUrls 顺序注入外链脚本
+ * @property {() => void} registerSanitizedHtmlSnippet MVP 未实现，调用即抛错
+ * @property {() => ReturnType<typeof createRequestBridge>} getBridge 受控 `fetch` 代理
+ * @property {(pluginId: string, fn: () => void) => void} onTeardown 注册卸载回调；由 `disposeWebPlugin(pluginId)` 触发
  */
-export function createHostApi(pluginId, router) {
-  const bridge = createRequestBridge()
-  const teardowns = []
 
+/**
+ * @typedef {object} HostKitOptions
+ * @property {string[]} [bridgeAllowedPathPrefixes] 覆盖 `getBridge().request` 允许的 URL 前缀；默认见 `defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes`
+ */
+
+/**
+ * 创建单个插件在宿主侧的 API 句柄，传入插件 `activator(hostApi)`。
+ *
+ * `bootstrapPlugins` 始终以 `(pluginId, router, hostKitOptions)` 调用工厂；请使用 `(id, r, kit) => createHostApi(id, r, kit)` 传入 `bridgeAllowedPathPrefixes`。
+ * 单参工厂 `(id) => createHostApi(id, router)` 仍可用（忽略后两个实参），此时 bridge 仅用包内默认前缀。
+ *
+ * @param {string} pluginId 与 manifest.id 一致
+ * @param {import('vue-router').default} router 宿主 Vue Router 实例（vue-router@3）
+ * @param {HostKitOptions} [hostKitOptions]
+ * @returns {HostApi}
+ */
+export function createHostApi(pluginId, router, hostKitOptions = {}) {
+  const bridgePrefixes =
+    Array.isArray(hostKitOptions.bridgeAllowedPathPrefixes) &&
+    hostKitOptions.bridgeAllowedPathPrefixes.length > 0
+      ? hostKitOptions.bridgeAllowedPathPrefixes
+      : defaultWebExtendPluginRuntime.bridgeAllowedPathPrefixes
+  const bridge = createRequestBridge({ allowedPathPrefixes: bridgePrefixes })
+
+  /**
+   * 注入样式表；`disposeWebPlugin` 会按 `data-plugin-asset` 移除对应节点。
+   * @param {string} href
+   */
   function injectStylesheet(href) {
     const link = document.createElement('link')
     link.rel = 'stylesheet'
@@ -19,6 +71,11 @@ export function createHostApi(pluginId, router) {
     document.head.appendChild(link)
   }
 
+  /**
+   * 注入外链脚本（用于插件额外资源，非清单主入口）。
+   * @param {string} src
+   * @returns {Promise<void>}
+   */
   function injectScript(src) {
     return new Promise((resolve, reject) => {
       const s = document.createElement('script')
@@ -34,14 +91,29 @@ export function createHostApi(pluginId, router) {
   return {
     hostPluginApiVersion: HOST_PLUGIN_API_VERSION,
 
+    /**
+     * 动态注册路由。Vue Router 3.5+ 推荐 `addRoute`；若不存在则回退已弃用的 `addRoutes`。
+     * @param {import('vue-router').RouteConfig[]} routes
+     */
     registerRoutes(routes) {
       const wrapped = routes.map((r) => ({
         ...r,
+        name: r.name || `__wep_${pluginId}_${routeSynthSeq++}`,
         meta: { ...(r.meta || {}), pluginId }
       }))
-      router.addRoutes(wrapped)
+      if (typeof router.addRoute === 'function') {
+        for (const r of wrapped) {
+          router.addRoute(r)
+        }
+      } else {
+        router.addRoutes(wrapped)
+      }
     },
 
+    /**
+     * 写入全局菜单注册表（响应式）；按 `order` 升序排列。
+     * @param {object[]} items
+     */
     registerMenuItems(items) {
       for (const item of items) {
         registries.menus.push({ ...item, pluginId })
@@ -49,8 +121,15 @@ export function createHostApi(pluginId, router) {
       registries.menus.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
     },
 
+    /**
+     * 向指定扩展点 id 注册 Vue 组件；`ExtensionPoint` 按 `priority` 降序渲染。
+     * @param {string} pointId
+     * @param {RegisterSlotEntry[]} components
+     */
     registerSlotComponents(pointId, components) {
-      if (!pointId) return
+      if (!pointId) {
+        return
+      }
       if (!registries.slots[pointId]) {
         Vue.set(registries.slots, pointId, [])
       }
@@ -60,18 +139,28 @@ export function createHostApi(pluginId, router) {
           pluginId,
           component: c.component,
           priority: c.priority ?? 0,
-          key: `${pluginId}-${pointId}-${list.length}-${Date.now()}`
+          key: `${pluginId}-${pointId}-${++slotItemKeySeq}`
         })
       }
       list.sort((a, b) => b.priority - a.priority)
+      registries.slotRevision++
     },
 
+    /**
+     * @param {string[]|undefined} urls
+     */
     registerStylesheetUrls(urls) {
       for (const u of urls || []) {
-        if (typeof u === 'string' && u) injectStylesheet(u)
+        if (typeof u === 'string' && u) {
+          injectStylesheet(u)
+        }
       }
     },
 
+    /**
+     * 串行加载多个脚本，失败仅告警不中断宿主。
+     * @param {string[]|undefined} urls
+     */
     registerScriptUrls(urls) {
       const chain = (urls || []).filter((u) => typeof u === 'string' && u).reduce(
         (p, u) => p.then(() => injectScript(u)),
@@ -86,8 +175,15 @@ export function createHostApi(pluginId, router) {
 
     getBridge: () => bridge,
 
-    onTeardown(_pid, fn) {
-      if (typeof fn === 'function') teardowns.push(fn)
+    /**
+     * 插件卸载前清理逻辑；第一个参数为预留与协议对齐，实际以创建 API 时的 `pluginId` 为准。
+     * @param {string} _pluginId 预留，与 manifest.id 一致时可传入
+     * @param {() => void} fn
+     */
+    onTeardown(_pluginId, fn) {
+      if (typeof fn === 'function') {
+        registerPluginTeardown(pluginId, fn)
+      }
     }
   }
 }

package/src/default-runtime-config.js

@@ -0,0 +1,58 @@
+/**
+ * 宿主可覆盖的默认运行时配置（路径、白名单、超时等）。
+ * 使用方式：`resolveRuntimeOptions({ ...defaultWebExtendPluginRuntime, manifestListPath: '/api/my-plugins' })`
+ * 或只传需要改动的字段：`resolveRuntimeOptions({ manifestListPath: '/api/my-plugins' })`。
+ *
+ * @module default-runtime-config
+ */
+
+/**
+ * @typedef {typeof defaultWebExtendPluginRuntime} WebExtendPluginDefaultRuntime
+ */
+
+export const defaultWebExtendPluginRuntime = {
+  /** 清单 HTTP 服务前缀（与后端 context-path 对齐），不含尾部 `/` */
+  manifestBase: '/fp-api',
+
+  /**
+   * 拉取插件清单的 **路径段**（以 `/` 开头），拼在 `manifestBase` 之后。
+   * 完整 URL：`{manifestBase}{manifestListPath}` → 默认 `/fp-api/api/frontend-plugins`
+   */
+  manifestListPath: '/api/frontend-plugins',
+
+  /** 清单 `fetch` 的 `credentials`，需 Cookie 会话时用 `include` */
+  manifestFetchCredentials: 'include',
+
+  /** 插件 dev 服务存活探测路径（拼在 `webPluginDevOrigin` 后） */
+  devPingPath: '/__web_plugin_dev_ping',
+
+  /** 插件 dev 热更新 SSE 路径（拼在插件 dev 的 origin 后） */
+  devReloadSsePath: '/__web_plugin_reload_stream',
+
+  /** 隐式 dev 映射里，每个 id 对应的入口路径（相对插件 dev origin） */
+  webPluginDevEntryPath: '/src/plugin-entry.js',
+
+  /** `fetch(devPingUrl)` 超时毫秒数 */
+  devPingTimeoutMs: 500,
+
+  /**
+   * **隐式 dev 映射**（可选）：开发模式下若 `webPluginDevOrigin` 上 ping 成功，运行时会为若干插件 id 自动生成
+   * `{ id → origin + webPluginDevEntryPath }`，从而用 dev 服务入口替代清单里的 dist，便于热更新联调。
+   *
+   * 插件 id 来源优先级：`webPluginDevIds`（或 `VITE_WEB_PLUGIN_DEV_IDS`）→ 本字段。**默认 `[]`**，
+   * 避免把仓库示例 id 写进通用宿主；联调时在 `.env` 里设 `VITE_WEB_PLUGIN_DEV_IDS=com.xxx,com.yyy`，
+   * 或 `resolveRuntimeOptions({ defaultImplicitDevPluginIds: ['com.xxx'] })` 即可。
+   */
+  defaultImplicitDevPluginIds: [],
+
+  /**
+   * 允许通过 `<script>` / 动态 `import()` 加载的插件脚本所在主机名（小写），防误配公网 URL。
+   */
+  allowedScriptHosts: ['localhost', '127.0.0.1', '::1'],
+
+  /**
+   * `hostApi.getBridge().request(path)` 允许的 path 前缀；须以 `/` 开头。
+   * 需与后端实际 API 前缀一致。
+   */
+  bridgeAllowedPathPrefixes: ['/api/']
+}

package/src/dispose-plugin.js

@@ -0,0 +1,56 @@
+/**
+ * 单插件卸载：与 `bootstrapPlugins` / `createHostApi` 对称，清理注册表与 DOM 副作用。
+ *
+ * @module dispose-plugin
+ */
+import Vue from 'vue'
+import { registries } from './registries.js'
+import { runPluginTeardowns } from './teardown-registry.js'
+
+/**
+ * 卸载指定 id 的插件：依次执行 teardown、移除菜单与扩展点条目、删除 activator、移除带 `data-plugin-asset` 的节点。
+ *
+ * **路由**：Vue Router 3 无公开 `removeRoute`，此处不改动 matcher；动态路由需整页刷新或自行维护路由表。
+ *
+ * @param {string} pluginId 与 manifest.id 一致
+ */
+export function disposeWebPlugin(pluginId) {
+  if (!pluginId || typeof pluginId !== 'string') {
+    return
+  }
+
+  runPluginTeardowns(pluginId)
+
+  for (let i = registries.menus.length - 1; i >= 0; i--) {
+    if (registries.menus[i].pluginId === pluginId) {
+      registries.menus.splice(i, 1)
+    }
+  }
+
+  const slots = registries.slots
+  for (const pointId of Object.keys(slots)) {
+    const list = slots[pointId]
+    if (!Array.isArray(list)) {
+      continue
+    }
+    const next = list.filter((x) => x.pluginId !== pluginId)
+    if (next.length === 0) {
+      Vue.delete(slots, pointId)
+    } else if (next.length !== list.length) {
+      Vue.set(slots, pointId, next)
+    }
+  }
+  registries.slotRevision++
+
+  if (typeof window !== 'undefined' && window.__PLUGIN_ACTIVATORS__) {
+    delete window.__PLUGIN_ACTIVATORS__[pluginId]
+  }
+
+  if (typeof document !== 'undefined') {
+    document.querySelectorAll('[data-plugin-asset]').forEach((el) => {
+      if (el.getAttribute('data-plugin-asset') === pluginId) {
+        el.remove()
+      }
+    })
+  }
+}

package/src/index.js

@@ -1,5 +1,11 @@
+/**
+ * Vue 2.7 宿主 Web 扩展插件运行时公共入口。
+ * @see README 中 Webpack 宿主需配置 DefinePlugin 或显式 `resolveRuntimeOptions`
+ */
+export { defaultWebExtendPluginRuntime } from './default-runtime-config.js'
 export { bootstrapPlugins, resolveRuntimeOptions } from './PluginRuntime.js'
 export { createHostApi } from './createHostApi.js'
+export { disposeWebPlugin } from './dispose-plugin.js'
 export { registries } from './registries.js'
 export { createRequestBridge } from './bridge.js'
 export { HOST_PLUGIN_API_VERSION } from './constants.js'

package/src/registries.js

@@ -1,10 +1,23 @@
+/**
+ * 宿主全局响应式注册表：菜单与扩展点槽位，供布局与 `ExtensionPoint` 订阅。
+ *
+ * @module registries
+ */
 import Vue from 'vue'
 
 /**
- * Reactive registries for menus, extension slots, and button toolbars.
+ * @type {{
+ *   menus: object[],
+ *   slots: Record<string, Array<{ pluginId: string, component: import('vue').Component, priority: number, key: string }>>
+ * }}
  */
 export const registries = Vue.observable({
   menus: [],
-  /** pointId -> Array<{ pluginId, component, priority, key }>（工具栏等扩展点与内容区共用同一模型） */
-  slots: {}
+  /** 扩展点 id → 已注册组件列表（内容区 / 工具栏等共用模型） */
+  slots: {},
+  /**
+   * 每次变更 slots 时递增，供 ExtensionPoint 计算属性显式依赖。
+   * Vue 2 对「先访问不存在的 slots[key]、后 Vue.set 补 key」的依赖收集不可靠，会导致扩展点不刷新。
+   */
+  slotRevision: 0
 })

package/src/teardown-registry.js

@@ -0,0 +1,44 @@
+/**
+ * 按 `pluginId` 收集 `onTeardown` 回调，供 `disposeWebPlugin` 统一执行。
+ *
+ * @module teardown-registry
+ */
+
+/** @type {Map<string, Function[]>} */
+const byPlugin = new Map()
+
+/**
+ * 登记插件卸载时要执行的同步回调（建议只做解绑、清定时器等轻量逻辑）。
+ * @param {string} pluginId
+ * @param {() => void} fn
+ */
+export function registerPluginTeardown(pluginId, fn) {
+  if (typeof fn !== 'function') {
+    return
+  }
+  let arr = byPlugin.get(pluginId)
+  if (!arr) {
+    arr = []
+    byPlugin.set(pluginId, arr)
+  }
+  arr.push(fn)
+}
+
+/**
+ * 执行并清空该插件已登记的全部 teardown；调用后 Map 中不再保留该 id。
+ * @param {string} pluginId
+ */
+export function runPluginTeardowns(pluginId) {
+  const arr = byPlugin.get(pluginId)
+  if (!arr) {
+    return
+  }
+  byPlugin.delete(pluginId)
+  for (const fn of arr) {
+    try {
+      fn()
+    } catch (e) {
+      console.warn('[plugins] teardown failed', pluginId, e)
+    }
+  }
+}