xinyu-pro 0.21.0

package/lib/plugin-runtime.ts

@@ -0,0 +1,2287 @@
+// lib/plugin-runtime.ts - 插件运行时引擎
+// 负责插件加载、执行、Hook 调度、错误隔离
+
+import {
+  PluginManifest,
+  PluginInstance,
+  PluginBinding,
+  PluginHook,
+  HookHandler,
+  GameAttribute,
+  ChatCommand,
+  SidebarPanelRegistration,
+  ToolbarButtonRegistration,
+  MessageRenderer,
+  UISlotId,
+  SlotRegistration,
+  ModalRegistration,
+  ModalActionInput,
+  ConfirmOptions,
+  DependencyStatus,
+} from './plugin-types';
+import { PluginResourceTracker } from './plugin-resource-tracker';
+import { sanitizeHTML } from './plugin-html-sanitizer';
+import { createDOMSandbox } from './plugin-dom-sandbox';
+import { checkSlotPermission, checkDOMPermission, checkStylePermission, checkModalPermission, checkHostEventPermission, checkStoragePermission, checkFileReadPermission, checkFileWritePermission, checkInputControlPermission, checkGameInfoPermission, checkGameInfoWritePermission } from './plugin-security';
+
+/** Hook 注册项 */
+interface HookRegistration {
+  pluginId: string;
+  handler: HookHandler;
+}
+
+/** 宿主事件注册项 */
+interface HostEventRegistration {
+  pluginId: string;
+  eventName: string;
+  handler: HookHandler;
+}
+
+/** 插件运行时状态 */
+interface RuntimeState {
+  instances: Map<string, PluginInstance>;
+  hooks: Map<PluginHook, HookRegistration[]>;
+  gameAttributes: Map<string, GameAttribute>;
+  chatCommands: Map<string, ChatCommand>;
+  sidebarPanels: SidebarPanelRegistration[];
+  toolbarButtons: Map<string, ToolbarButtonRegistration[]>; // pluginId -> buttons
+  messageRenderers: MessageRenderer[];
+  gameState: Record<string, unknown>;
+  promptModifiers: Array<{ pluginId: string; handler: (prompt: string, worldSetting: Record<string, unknown>) => string }>;
+  beforeSendHandlers: Array<{ pluginId: string; handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[] }>;
+  beforeCompleteHandlers: Array<{ pluginId: string; handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[] }>;
+  afterReceiveHandlers: Array<{ pluginId: string; handler: (content: string) => string | Promise<string> }>;
+  requestConfigModifiers: Array<{ pluginId: string; handler: (config: { temperature: number; maxTokens: number; model: string }) => { temperature: number; maxTokens: number; model: string } }>;
+  // 新增：全局 UI API 状态
+  slotRegistrations: SlotRegistration[];
+  actionHandlers: Array<{ pluginId: string; actionName: string; handler: (e: { target: HTMLElement; actionName: string; payload?: string }) => void }>;
+  modals: Map<string, ModalRegistration>;
+  hostEventHandlers: HostEventRegistration[];
+  // 新增：依赖状态追踪
+  dependencyStatus: Map<string, DependencyStatus[]>;
+  // 新增：游戏初始化标记（确保只触发一次）
+  gameInitTriggered: boolean;
+  // 新增：权限注册表（记录 permission → pluginId 的持有关系）
+  permissionRegistry: Map<string, { pluginId: string; type: 'common' | 'exclusive' }>;
+}
+
+/** UI 回调（由 PluginProvider 注入） */
+interface UICallbacks {
+  sendMessage?: (content: string) => Promise<void>;
+  insertSystemMessage?: (content: string) => void;
+  insertNotice?: (html: string) => void;
+  toast?: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => void;
+  showModal?: (modal: ModalRegistration) => void;
+  closeModal?: (modalId: string) => void;
+  updateModal?: (modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }) => void;
+  confirm?: (title: string, message: string, options?: ConfirmOptions) => Promise<boolean>;
+  emitHostEvent?: (eventName: string, data?: unknown) => void;
+  /** 配置变更广播回调（由 PluginProvider 注入，用于跨标签页同步） */
+  onConfigChange?: (pluginId: string, config: Record<string, unknown>) => void;
+  /** 插槽内容变更回调（由 PluginProvider 注入，用于触发 UI 刷新） */
+  onSlotChange?: () => void;
+  /** 输入框控制回调（由 PluginProvider 注入） */
+  inputControl?: {
+    setInputElement: (el: HTMLTextAreaElement | null) => void;
+    getInputListeners: () => Array<(value: string) => void>;
+    getSendListeners: () => Array<(content: string) => void>;
+    getKeyDownListeners: () => Array<(event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void>;
+  };
+  /** 获取世界设定回调（由 PluginProvider 注入） */
+  getWorldSetting?: () => Record<string, unknown>;
+  /** 获取当前会话 ID 回调（由 PluginProvider 注入） */
+  getSessionId?: () => string;
+  /** 获取当前消息列表回调（由 PluginProvider 注入） */
+  getMessages?: () => { role: string; content: string }[];
+  /** 设置世界设定回调（由 PluginProvider 注入） */
+  setWorldSetting?: (data: Record<string, unknown>) => void;
+  /** 获取当前世界 ID 回调（由 PluginProvider 注入） */
+  getWorldId?: () => string | undefined;
+}
+
+/** 获取插槽容器 DOM 元素的回调类型 */
+type GetSlotContainerCallback = (slotId: UISlotId) => HTMLElement | null;
+
+/** 创建初始运行时状态 */
+function createRuntimeState(): RuntimeState {
+  return {
+    instances: new Map(),
+    hooks: new Map(),
+    gameAttributes: new Map(),
+    chatCommands: new Map(),
+    sidebarPanels: [],
+    toolbarButtons: new Map(),
+    messageRenderers: [],
+    gameState: {},
+    promptModifiers: [],
+    beforeSendHandlers: [],
+    beforeCompleteHandlers: [],
+    afterReceiveHandlers: [],
+    requestConfigModifiers: [],
+    slotRegistrations: [],
+    actionHandlers: [],
+    modals: new Map(),
+    hostEventHandlers: [],
+    dependencyStatus: new Map(),
+    gameInitTriggered: false,
+    permissionRegistry: new Map(),
+  };
+}
+
+/** 插件运行时引擎 */
+class PluginRuntimeEngine {
+  private state: RuntimeState;
+  private pluginStorage: Map<string, Map<string, unknown>>;
+  private uiCallbacks: UICallbacks;
+  private resourceTracker: PluginResourceTracker;
+  private getSlotContainerCallback: GetSlotContainerCallback | null;
+
+  constructor() {
+    this.state = createRuntimeState();
+    this.pluginStorage = new Map();
+    this.uiCallbacks = {};
+    this.resourceTracker = new PluginResourceTracker();
+    this.getSlotContainerCallback = null;
+  }
+
+  // ==================== UI 回调注入 ====================
+
+  /** 由 PluginProvider 调用，注入 UI 交互回调 */
+  setUICallbacks(callbacks: UICallbacks): void {
+    this.uiCallbacks = { ...this.uiCallbacks, ...callbacks };
+  }
+
+  /** 设置获取插槽容器 DOM 元素的回调 */
+  setGetSlotContainerCallback(callback: GetSlotContainerCallback): void {
+    this.getSlotContainerCallback = callback;
+  }
+
+  // ==================== 输入框控制 API ====================
+
+  /** 输入框控制对象，供插件沙箱 API 调用 */
+  get inputControl() {
+    const callbacks = this.uiCallbacks.inputControl;
+    return {
+      getContent: (): string | null => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        return el?.value ?? null;
+      },
+      setContent: (text: string): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+        if (nativeInputValueSetter) {
+          nativeInputValueSetter.call(el, text);
+        } else {
+          el.value = text;
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      },
+      appendContent: (text: string): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        const start = el.selectionStart ?? el.value.length;
+        const end = el.selectionEnd ?? el.value.length;
+        const before = el.value.substring(0, start);
+        const after = el.value.substring(end);
+        const newValue = before + text + after;
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+        if (nativeInputValueSetter) {
+          nativeInputValueSetter.call(el, newValue);
+        } else {
+          el.value = newValue;
+        }
+        const newCursorPos = start + text.length;
+        el.setSelectionRange(newCursorPos, newCursorPos);
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      },
+      clearContent: (): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+        if (nativeInputValueSetter) {
+          nativeInputValueSetter.call(el, '');
+        } else {
+          el.value = '';
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      },
+      setPlaceholder: (text: string): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        el.placeholder = text;
+      },
+      setDisabled: (disabled: boolean): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        el.disabled = disabled;
+      },
+      focus: (): void => {
+        (document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null)?.focus();
+      },
+      blur: (): void => {
+        (document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null)?.blur();
+      },
+      setStyle: (style: Record<string, string>): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        Object.assign(el.style, style);
+      },
+      injectStyle: (css: string): string => {
+        const styleId = `xinyu-plugin-input-style-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const styleEl = document.createElement('style');
+        styleEl.id = styleId;
+        styleEl.setAttribute('data-xinyu-input-style', 'true');
+        styleEl.textContent = css;
+        document.head.appendChild(styleEl);
+        return styleId;
+      },
+      removeStyle: (styleId: string): void => {
+        const el = document.getElementById(styleId);
+        if (el) el.remove();
+      },
+      onInput: (handler: (value: string) => void): (() => void) => {
+        if (!callbacks) return () => {};
+        callbacks.getInputListeners().push(handler);
+        return () => {
+          const listeners = callbacks.getInputListeners();
+          const idx = listeners.indexOf(handler);
+          if (idx !== -1) listeners.splice(idx, 1);
+        };
+      },
+      onSend: (handler: (content: string) => void): (() => void) => {
+        if (!callbacks) return () => {};
+        callbacks.getSendListeners().push(handler);
+        return () => {
+          const listeners = callbacks.getSendListeners();
+          const idx = listeners.indexOf(handler);
+          if (idx !== -1) listeners.splice(idx, 1);
+        };
+      },
+      onKeyDown: (handler: (event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void): (() => void) => {
+        if (!callbacks) return () => {};
+        callbacks.getKeyDownListeners().push(handler);
+        return () => {
+          const listeners = callbacks.getKeyDownListeners();
+          const idx = listeners.indexOf(handler);
+          if (idx !== -1) listeners.splice(idx, 1);
+        };
+      },
+      getSelection: (): { start: number; end: number; text: string } | null => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return null;
+        const start = el.selectionStart ?? 0;
+        const end = el.selectionEnd ?? 0;
+        return { start, end, text: el.value.substring(start, end) };
+      },
+      setSelection: (start: number, end: number): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        el.setSelectionRange(start, end);
+      },
+      insertAtCursor: (text: string): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        const start = el.selectionStart ?? el.value.length;
+        const end = el.selectionEnd ?? el.value.length;
+        const before = el.value.substring(0, start);
+        const after = el.value.substring(end);
+        const newValue = before + text + after;
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+        if (nativeInputValueSetter) {
+          nativeInputValueSetter.call(el, newValue);
+        } else {
+          el.value = newValue;
+        }
+        const newCursorPos = start + text.length;
+        el.setSelectionRange(newCursorPos, newCursorPos);
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      },
+      setMaxLength: (length: number): void => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        if (!el) return;
+        el.maxLength = length;
+      },
+      getLength: (): number => {
+        const el = document.getElementById('xinyu-chat-input') as HTMLTextAreaElement | null;
+        return el?.value.length ?? 0;
+      },
+    };
+  }
+
+  // ==================== 插件生命周期管理 ====================
+
+  /**
+   * 检查插件权限冲突
+   * 返回冲突列表，每项包含冲突的权限、冲突的插件 ID、冲突类型
+   */
+  checkPermissionConflicts(manifest: PluginManifest): Array<{
+    permission: string;
+    conflictingPluginId: string;
+    conflictingPluginName: string;
+    conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+  }> {
+    const conflicts: Array<{
+      permission: string;
+      conflictingPluginId: string;
+      conflictingPluginName: string;
+      conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+    }> = [];
+
+    const commonPerms = manifest.commonPermissions || [];
+    const exclusivePerms = manifest.exclusivePermissions || [];
+
+    // 检查排他权限：与任何已存在的权限（common 或 exclusive）都冲突
+    for (const perm of exclusivePerms) {
+      const existing = this.state.permissionRegistry.get(perm);
+      if (existing && existing.pluginId !== manifest.id) {
+        const existingInstance = this.state.instances.get(existing.pluginId);
+        conflicts.push({
+          permission: perm,
+          conflictingPluginId: existing.pluginId,
+          conflictingPluginName: existingInstance?.manifest.name || existing.pluginId,
+          conflictType: 'exclusive-vs-any',
+        });
+      }
+    }
+
+    // 检查共享权限：与已存在的排他权限冲突
+    for (const perm of commonPerms) {
+      const existing = this.state.permissionRegistry.get(perm);
+      if (existing && existing.pluginId !== manifest.id && existing.type === 'exclusive') {
+        const existingInstance = this.state.instances.get(existing.pluginId);
+        conflicts.push({
+          permission: perm,
+          conflictingPluginId: existing.pluginId,
+          conflictingPluginName: existingInstance?.manifest.name || existing.pluginId,
+          conflictType: 'common-vs-exclusive',
+        });
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * 检查必要权限是否满足
+   * 返回未满足的必要权限列表
+   */
+  checkRequiredPermissions(manifest: PluginManifest): string[] {
+    const required = manifest.requiredPermissions || [];
+    const common = manifest.commonPermissions || [];
+    const exclusive = manifest.exclusivePermissions || [];
+    const allDeclared = [...common, ...exclusive];
+
+    return required.filter(perm => !allDeclared.includes(perm));
+  }
+
+  /**
+   * 注册插件的权限到注册表
+   */
+  registerPermissions(manifest: PluginManifest): void {
+    const commonPerms = manifest.commonPermissions || [];
+    const exclusivePerms = manifest.exclusivePermissions || [];
+
+    for (const perm of commonPerms) {
+      this.state.permissionRegistry.set(perm, { pluginId: manifest.id, type: 'common' });
+    }
+    for (const perm of exclusivePerms) {
+      this.state.permissionRegistry.set(perm, { pluginId: manifest.id, type: 'exclusive' });
+    }
+  }
+
+  /**
+   * 释放插件的权限（仅释放该插件注册的）
+   */
+  unregisterPermissions(pluginId: string): void {
+    this.state.permissionRegistry.forEach((entry, perm) => {
+      if (entry.pluginId === pluginId) {
+        this.state.permissionRegistry.delete(perm);
+      }
+    });
+  }
+
+  /**
+   * 移除插件的单个权限声明
+   * @returns true 如果成功移除
+   */
+  removePluginPermission(pluginId: string, permission: string): boolean {
+    const entry = this.state.permissionRegistry.get(permission);
+    if (entry && entry.pluginId === pluginId) {
+      this.state.permissionRegistry.delete(permission);
+      return true;
+    }
+    return false;
+  }
+
+  /** loadPlugin 返回结果 */
+  loadPluginResult = {
+    success: true,
+    conflicts: [] as Array<{
+      permission: string;
+      conflictingPluginId: string;
+      conflictingPluginName: string;
+      conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+    }>,
+    missingRequired: [] as string[],
+  } as const;
+
+  /** 加载并激活插件 */
+  // @ts-ignore
+  loadPlugin(manifest: PluginManifest, binding: PluginBinding): ReturnType<typeof PluginRuntimeEngine.prototype.loadPlugin> {
+    // 防止重复加载：如果插件已加载且配置未变，跳过
+    const existing = this.state.instances.get(manifest.id);
+    if (existing && existing.enabled === binding.enabled) {
+      return { ...this.loadPluginResult };
+    }
+
+    // 如果插件已启用，先检查权限冲突
+    if (binding.enabled) {
+      const conflicts = this.checkPermissionConflicts(manifest);
+      if (conflicts.length > 0) {
+        console.warn(`[PluginRuntime] 插件 ${manifest.id} 启动失败：权限冲突`, conflicts);
+        // 仍然创建实例（标记为 disabled），但不执行 setup
+        const instance: PluginInstance = {
+          manifest,
+          enabled: false,
+          config: binding.config || {},
+          scope: binding.scope,
+          worldId: binding.worldId,
+        };
+        if (!this.pluginStorage.has(manifest.id)) {
+          this.pluginStorage.set(manifest.id, new Map());
+        }
+        const exports = this.executePluginCode(manifest.code, manifest.id);
+        instance.exports = exports;
+        this.state.instances.set(manifest.id, instance);
+        return { success: false, conflicts, missingRequired: [] };
+      }
+
+      // 检查必要权限
+      const missingRequired = this.checkRequiredPermissions(manifest);
+      if (missingRequired.length > 0) {
+        console.warn(`[PluginRuntime] 插件 ${manifest.id} 启动失败：必要权限未声明`, missingRequired);
+        const instance: PluginInstance = {
+          manifest,
+          enabled: false,
+          config: binding.config || {},
+          scope: binding.scope,
+          worldId: binding.worldId,
+        };
+        if (!this.pluginStorage.has(manifest.id)) {
+          this.pluginStorage.set(manifest.id, new Map());
+        }
+        const exports = this.executePluginCode(manifest.code, manifest.id);
+        instance.exports = exports;
+        this.state.instances.set(manifest.id, instance);
+        return { success: false, conflicts: [], missingRequired };
+      }
+    }
+
+    try {
+      // 创建运行时实例
+      const instance: PluginInstance = {
+        manifest,
+        enabled: binding.enabled,
+        config: binding.config || {},
+        scope: binding.scope,
+        worldId: binding.worldId,
+      };
+
+      // 确保有独立的持久化存储空间
+      if (!this.pluginStorage.has(manifest.id)) {
+        this.pluginStorage.set(manifest.id, new Map());
+      }
+
+      // 执行插件代码（始终执行，以获取 exports）
+      const exports = this.executePluginCode(manifest.code, manifest.id);
+      instance.exports = exports;
+
+      this.state.instances.set(manifest.id, instance);
+
+      // 注册权限
+      if (binding.enabled) {
+        this.registerPermissions(manifest);
+      }
+
+      // 检查依赖状态
+      const depStatus = this.checkDependencies(manifest);
+      this.state.dependencyStatus.set(manifest.id, depStatus);
+
+      // 判断是否有未满足的必需依赖
+      const hasUnmetRequired = depStatus.some(d => d.required && d.status !== 'satisfied');
+
+      // 如果插件已启用且依赖满足，调用 setup 函数并触发 onLoad 钩子
+      if (binding.enabled && !hasUnmetRequired) {
+        const xinyu = this.createXinyuBridge(manifest.id);
+        if (typeof exports.setup === 'function') {
+          exports.setup(xinyu);
+        }
+        // 只触发当前插件自己的 onLoad（避免在批量加载时重复触发已加载插件的 handler）
+        this.triggerHookForPlugin('onLoad', manifest.id, manifest.id);
+        // 通知所有插件：有插件加载完成
+        this.triggerHook('onPluginLoad', manifest.id);
+      } else if (hasUnmetRequired) {
+        console.warn(`[PluginRuntime] 插件 ${manifest.id} 有未满足的必需依赖，跳过 setup`);
+      }
+
+      return { ...this.loadPluginResult };
+    } catch (e) {
+      console.error(`[PluginRuntime] 加载插件 ${manifest.id} 失败:`, e);
+      return { success: false, conflicts: [], missingRequired: [] };
+    }
+  }
+
+  /** 卸载插件 */
+  unloadPlugin(pluginId: string): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+
+    // 触发卸载钩子
+    if (instance.enabled) {
+      this.triggerHook('onUnload', pluginId);
+    }
+
+    // 清理所有注册
+    this.unregisterAllForPlugin(pluginId);
+
+    // 释放权限
+    this.unregisterPermissions(pluginId);
+
+    // 清理资源追踪器中的所有资源（DOM、样式、事件等）
+    this.resourceTracker.cleanup(pluginId);
+
+    this.state.instances.delete(pluginId);
+  }
+
+  /** 启用插件 */
+  enablePlugin(pluginId: string): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+    instance.enabled = true;
+    // 调用 setup 函数注册属性、指令等
+    const xinyu = this.createXinyuBridge(pluginId);
+    if (instance.exports && typeof instance.exports.setup === 'function') {
+      instance.exports.setup(xinyu);
+    }
+    this.triggerHookForPlugin('onLoad', pluginId, pluginId);
+    this.triggerHook('onPluginLoad', pluginId);
+  }
+
+  /** 禁用插件 */
+  disablePlugin(pluginId: string): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+    this.triggerHook('onUnload', pluginId);
+    instance.enabled = false;
+  }
+
+  /**
+   * 统一配置更新入口（唯一修改配置的方法）
+   * 职责：
+   * 1. 更新内存中的 instance.config
+   * 2. 触发 onConfigChange hook（通知插件代码）
+   * 3. 异步持久化到 DB
+   * 4. 通过 UI 回调广播配置变更（跨标签页同步）
+   *
+   * @param options.persist 是否持久化到 DB（默认 true）
+   * @param options.broadcast 是否广播变更（默认 true）
+   */
+  async updatePluginConfig(
+    pluginId: string,
+    config: Record<string, unknown>,
+    options?: { persist?: boolean; broadcast?: boolean; triggerHook?: boolean },
+  ): Promise<void> {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+
+    // 1. 更新内存
+    instance.config = config;
+
+    // 2. 触发 onConfigChange hook（仅通知目标插件自身，handler 签名为 (config)）
+    const shouldTriggerHook = options?.triggerHook !== false;
+    if (shouldTriggerHook) {
+      // onConfigChange：只通知 pluginId 自身注册的 handler
+      const configRegistrations = this.state.hooks.get('onConfigChange');
+      if (configRegistrations) {
+        for (const reg of configRegistrations) {
+          if (reg.pluginId !== pluginId) continue;
+          const inst = this.state.instances.get(reg.pluginId);
+          if (!inst || !inst.enabled) continue;
+          await this.callSafe(reg.handler, [config], reg.pluginId, 'onConfigChange');
+        }
+      }
+      // onGlobalConfigChange：通知所有注册了该 hook 的插件
+      this.triggerHook('onGlobalConfigChange', pluginId, config);
+    }
+
+    // 3. 异步持久化到 DB
+    const shouldPersist = options?.persist !== false;
+    if (shouldPersist) {
+      this.persistConfig(pluginId, config);
+    }
+
+    // 4. 广播配置变更（跨标签页同步）
+    const shouldBroadcast = options?.broadcast !== false;
+    if (shouldBroadcast && this.uiCallbacks.onConfigChange) {
+      this.uiCallbacks.onConfigChange(pluginId, config);
+    }
+  }
+
+  /** 异步持久化配置到 DB（仅负责 DB 写入，不修改内存） */
+  private persistConfig(pluginId: string, config: Record<string, unknown>): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+    const scope = instance.scope || 'global';
+    const worldId = instance.worldId || '';
+    fetch('/api/plugins/bindings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        extensionId: pluginId,
+        scope,
+        worldId,
+        enabled: instance.enabled,
+        config,
+      }),
+    }).catch(e => console.error(`[PluginRuntime] 持久化配置失败:`, e));
+  }
+
+  /** 获取所有已加载的插件实例 */
+  getInstances(): PluginInstance[] {
+    return Array.from(this.state.instances.values());
+  }
+
+  /** 获取已启用的插件实例 */
+  getEnabledInstances(): PluginInstance[] {
+    return Array.from(this.state.instances.values()).filter(i => i.enabled);
+  }
+
+  /** 获取插件实例 */
+  getInstance(pluginId: string): PluginInstance | undefined {
+    return this.state.instances.get(pluginId);
+  }
+
+  // ==================== Hook 系统 ====================
+
+  /** 注册 Hook */
+  registerHook(pluginId: string, hook: PluginHook, handler: HookHandler): void {
+    if (!this.state.hooks.has(hook)) {
+      this.state.hooks.set(hook, []);
+    }
+    const arr = this.state.hooks.get(hook)!;
+    arr.push({ pluginId, handler });
+  }
+
+  /** 注销 Hook */
+  unregisterHook(pluginId: string, hook: PluginHook, handler: HookHandler): void {
+    const registrations = this.state.hooks.get(hook);
+    if (!registrations) return;
+    const idx = registrations.findIndex(r => r.pluginId === pluginId && r.handler === handler);
+    if (idx !== -1) {
+      registrations.splice(idx, 1);
+    }
+  }
+
+  // ==================== 通用 Hook 调用工具 ====================
+
+  /**
+   * 通用安全调用函数：自动判断回调函数类型（async/普通），统一调用
+   * - 普通函数：直接调用，返回结果
+   * - async 函数：await 后返回结果
+   * - 出错时打印日志并返回 undefined（不中断管道）
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async callSafe(handler: (...args: any[]) => any, args: unknown[], pluginId: string, hookName: string): Promise<any> {
+    try {
+      const result = handler(...args);
+      // 判断返回值是否为 Promise（兼容 async 函数和普通函数）
+      if (result instanceof Promise) {
+        return await result;
+      }
+      return result;
+    } catch (e) {
+      console.error(`[PluginRuntime] ${hookName} 执行出错 (插件: ${pluginId}):`, e);
+      return undefined;
+    }
+  }
+
+  /** 触发 Hook（通知型，不管道返回值，支持 async handler） */
+  async triggerHook(hook: PluginHook, ...args: unknown[]): Promise<void> {
+    const registrations = this.state.hooks.get(hook);
+    if (!registrations) return;
+
+    for (const reg of registrations) {
+      const instance = this.state.instances.get(reg.pluginId);
+      if (!instance || !instance.enabled) continue;
+      await this.callSafe(reg.handler, args, reg.pluginId, String(hook));
+    }
+  }
+
+  /** 触发 Hook（仅限指定插件） */
+  private async triggerHookForPlugin(hook: PluginHook, targetPluginId: string, ...args: unknown[]): Promise<void> {
+    const registrations = this.state.hooks.get(hook);
+    if (!registrations) return;
+
+    for (const reg of registrations) {
+      if (reg.pluginId !== targetPluginId) continue;
+      const instance = this.state.instances.get(reg.pluginId);
+      if (!instance || !instance.enabled) continue;
+      await this.callSafe(reg.handler, args, reg.pluginId, String(hook));
+    }
+  }
+
+  /** 管道式 Hook（前一个输出作为后一个输入，支持 async handler） */
+  async triggerPipelineHook<T>(hook: PluginHook, initialValue: T): Promise<T> {
+    const registrations = this.state.hooks.get(hook);
+    if (!registrations) return initialValue;
+
+    let value = initialValue;
+    for (const reg of registrations) {
+      const instance = this.state.instances.get(reg.pluginId);
+      if (!instance || !instance.enabled) continue;
+      const result = await this.callSafe(reg.handler, [value], reg.pluginId, `Pipeline ${hook}`);
+      if (result !== undefined) {
+        value = result as T;
+      }
+    }
+    return value;
+  }
+
+  /** 触发游戏初始化钩子（进入游戏且无聊天记录时调用，只触发一次） */
+  async triggerGameInit(): Promise<void> {
+    if (this.state.gameInitTriggered) return;
+    this.state.gameInitTriggered = true;
+    await this.triggerHook('onGameInit');
+  }
+
+  /** 重置游戏初始化标记（切换游戏时调用） */
+  resetGameInit(): void {
+    this.state.gameInitTriggered = false;
+  }
+
+  /** 触发插件绑定世界钩子 */
+  async triggerPluginBindingWorld(worldId: string): Promise<void> {
+    await this.triggerHook('onPluginBindingWorld', worldId);
+  }
+
+  // ==================== 跨插件通信 ====================
+
+  /** 跨插件调用（显式导出 + 按需调用，双方声明） */
+  async callPlugin(callerPluginId: string, targetPluginId: string, method: string, ...args: unknown[]): Promise<unknown> {
+    // 1. 检查调用方是否声明了依赖
+    const callerInstance = this.state.instances.get(callerPluginId);
+    if (!callerInstance) {
+      throw new Error(`[PluginRuntime] 调用方插件 ${callerPluginId} 未加载`);
+    }
+    const callerDeps = callerInstance.manifest.dependencies || [];
+    const hasDeclaredDep = callerDeps.some(d => d.pluginId === targetPluginId);
+    if (!hasDeclaredDep) {
+      throw new Error(`[PluginRuntime] 插件 ${callerPluginId} 未声明对 ${targetPluginId} 的依赖，请在 manifest.dependencies 中添加`);
+    }
+
+    // 2. 检查目标插件是否存在且已启用
+    const targetInstance = this.state.instances.get(targetPluginId);
+    if (!targetInstance || !targetInstance.enabled) {
+      throw new Error(`[PluginRuntime] 目标插件 ${targetPluginId} 未加载或未启用`);
+    }
+
+    // 3. 检查目标插件是否声明了该 publicExport
+    const publicExports = targetInstance.manifest.publicExports || {};
+    if (!(method in publicExports)) {
+      throw new Error(`[PluginRuntime] 插件 ${targetPluginId} 未公开方法 ${method}，请在 manifest.publicExports 中声明`);
+    }
+
+    // 4. 调用目标插件的导出方法
+    const targetExports = targetInstance.exports || {};
+    const fn = targetExports[method];
+    if (typeof fn !== 'function') {
+      throw new Error(`[PluginRuntime] 插件 ${targetPluginId} 的导出方法 ${method} 不是函数`);
+    }
+
+    try {
+      return await fn(...args);
+    } catch (e) {
+      console.error(`[PluginRuntime] 跨插件调用出错 (${callerPluginId} -> ${targetPluginId}.${method}):`, e);
+      throw e;
+    }
+  }
+
+  /** 检查插件是否可用 */
+  isPluginAvailable(pluginId: string): boolean {
+    const instance = this.state.instances.get(pluginId);
+    return !!instance && instance.enabled;
+  }
+
+  /** 获取插件的公开导出 API 列表 */
+  getPluginExports(pluginId: string): Record<string, { description: string; params?: string; returns?: string }> | null {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return null;
+    return instance.manifest.publicExports || null;
+  }
+
+  /** 运行时加载依赖（供插件代码中调用，支持降级） */
+  async loadDependency(callerPluginId: string, targetPluginId: string, options?: { version?: string; timeout?: number }): Promise<Record<string, (...args: unknown[]) => unknown> | null> {
+    const targetInstance = this.state.instances.get(targetPluginId);
+    if (!targetInstance || !targetInstance.enabled) {
+      console.warn(`[PluginRuntime] 插件 ${callerPluginId} 加载依赖 ${targetPluginId} 失败：目标插件未加载或未启用`);
+      return null;
+    }
+
+    // 版本检查（简单实现：精确匹配或前缀匹配）
+    if (options?.version) {
+      const installedVersion = targetInstance.manifest.version;
+      if (!this.versionSatisfies(installedVersion, options.version)) {
+        console.warn(`[PluginRuntime] 插件 ${callerPluginId} 加载依赖 ${targetPluginId} 失败：版本不满足 (需要 ${options.version}，已安装 ${installedVersion})`);
+        return null;
+      }
+    }
+
+    return targetInstance.exports || {};
+  }
+
+  // ==================== 依赖管理 ====================
+
+  /** 检查插件的依赖状态 */
+  checkDependencies(manifest: PluginManifest): DependencyStatus[] {
+    const deps = manifest.dependencies || [];
+    return deps.map(dep => {
+      const targetInstance = this.state.instances.get(dep.pluginId);
+      if (!targetInstance) {
+        return {
+          pluginId: dep.pluginId,
+          status: 'missing',
+          required: !dep.optional,
+        };
+      }
+      if (dep.versionRange && !this.versionSatisfies(targetInstance.manifest.version, dep.versionRange)) {
+        return {
+          pluginId: dep.pluginId,
+          status: 'version_mismatch',
+          required: !dep.optional,
+          installedVersion: targetInstance.manifest.version,
+        };
+      }
+      return {
+        pluginId: dep.pluginId,
+        status: 'satisfied',
+        required: !dep.optional,
+        installedVersion: targetInstance.manifest.version,
+      };
+    });
+  }
+
+  /** 获取所有插件的依赖状态 */
+  getDependencyStatus(): Map<string, DependencyStatus[]> {
+    return new Map(this.state.dependencyStatus);
+  }
+
+  /** 获取指定插件的依赖状态 */
+  getPluginDependencyStatus(pluginId: string): DependencyStatus[] {
+    return this.state.dependencyStatus.get(pluginId) || [];
+  }
+
+  /** 根据依赖关系计算拓扑排序的加载顺序 */
+  getLoadOrder(manifests: PluginManifest[]): PluginManifest[] {
+    const manifestMap = new Map(manifests.map(m => [m.id, m]));
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+    const result: PluginManifest[] = [];
+
+    const visit = (id: string) => {
+      if (visited.has(id)) return;
+      if (visiting.has(id)) {
+        console.warn(`[PluginRuntime] 检测到循环依赖，涉及插件: ${id}`);
+        return;
+      }
+      visiting.add(id);
+
+      const manifest = manifestMap.get(id);
+      if (manifest?.dependencies) {
+        for (const dep of manifest.dependencies) {
+          if (manifestMap.has(dep.pluginId)) {
+            visit(dep.pluginId);
+          }
+        }
+      }
+
+      visiting.delete(id);
+      visited.add(id);
+      if (manifest) {
+        result.push(manifest);
+      }
+    };
+
+    for (const m of manifests) {
+      visit(m.id);
+    }
+
+    return result;
+  }
+
+  /** 简单的版本范围匹配（支持 ^, ~, >=, 精确匹配） */
+  private versionSatisfies(installed: string, range: string): boolean {
+    const installedParts = installed.split('.').map(Number);
+    const rangeStr = range.trim();
+
+    // 精确匹配
+    if (!rangeStr.startsWith('^') && !rangeStr.startsWith('~') && !rangeStr.startsWith('>=')) {
+      return installed === rangeStr;
+    }
+
+    const rangeParts = rangeStr.replace(/^[~^>=]+/, '').split('.').map(Number);
+
+    if (rangeStr.startsWith('>=')) {
+      for (let i = 0; i < Math.max(installedParts.length, rangeParts.length); i++) {
+        const a = installedParts[i] || 0;
+        const b = rangeParts[i] || 0;
+        if (a > b) return true;
+        if (a < b) return false;
+      }
+      return true;
+    }
+
+    // ^: 主版本号必须相同，次版本号和补丁号 >= range
+    if (rangeStr.startsWith('^')) {
+      if (installedParts[0] !== rangeParts[0]) return false;
+      for (let i = 1; i < Math.max(installedParts.length, rangeParts.length); i++) {
+        const a = installedParts[i] || 0;
+        const b = rangeParts[i] || 0;
+        if (a > b) return true;
+        if (a < b) return false;
+      }
+      return true;
+    }
+
+    // ~: 主版本号和次版本号必须相同，补丁号 >= range
+    if (rangeStr.startsWith('~')) {
+      if (installedParts[0] !== rangeParts[0] || installedParts[1] !== rangeParts[1]) return false;
+      return (installedParts[2] || 0) >= (rangeParts[2] || 0);
+    }
+
+    return false;
+  }
+
+  // ==================== 游戏属性 ====================
+
+  /** 注册游戏属性 */
+  registerAttribute(pluginId: string, attr: GameAttribute): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.gameAttributes.set(attr.key, { ...attr, pluginId });
+  }
+
+  /** 更新属性值 */
+  setAttribute(key: string, value: number | string | boolean): void {
+    const attr = this.state.gameAttributes.get(key);
+    if (attr) {
+      attr.value = value;
+    }
+  }
+
+  /** 获取所有游戏属性 */
+  getAttributes(): GameAttribute[] {
+    return Array.from(this.state.gameAttributes.values());
+  }
+
+  // ==================== 游戏状态 ====================
+
+  /** 获取游戏状态 */
+  getGameState(): Record<string, unknown> {
+    return { ...this.state.gameState };
+  }
+
+  /** 设置游戏状态（合并更新） */
+  setGameState(partial: Record<string, unknown>): void {
+    this.state.gameState = { ...this.state.gameState, ...partial };
+    const newKeys = Object.keys(partial);
+    // 触发宿主事件
+    this.emitHostEvent('game:stateChange', { changedKeys: newKeys });
+  }
+
+  /** 重置游戏状态 */
+  resetGameState(): void {
+    this.state.gameState = {};
+  }
+
+  // ==================== 快捷指令 ====================
+
+  /** 注册快捷指令 */
+  registerCommand(pluginId: string, cmd: ChatCommand): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.chatCommands.set(cmd.name, { ...cmd, pluginId });
+  }
+
+  /** 获取所有快捷指令 */
+  getCommands(): ChatCommand[] {
+    return Array.from(this.state.chatCommands.values());
+  }
+
+  /**
+   * 执行快捷指令
+   *
+   * 支持三种格式：
+   *   1. `/command args`          → 精确匹配命令名，执行对应插件的处理函数
+   *   2. `pluginId/command args`   → 指定目标插件，仅执行该插件注册的命令
+   *   3. `/command args`（无精确匹配）→ 广播给所有注册了同名命令的插件
+   *
+   * 返回值：
+   *   - string  → 作为用户消息显示
+   *   - 'handled' → 命令已处理（静默），不发送到 AI
+   *   - undefined → 未匹配到任何命令，继续作为普通消息发送
+   */
+  async executeCommand(rawInput: string): Promise<string | void> {
+    const trimmed = rawInput.trim();
+    if (!trimmed.startsWith('/')) return undefined;
+
+    // 解析：去掉开头的 /，提取命令名和参数
+    const withoutSlash = trimmed.slice(1);
+    const spaceIdx = withoutSlash.indexOf(' ');
+    const cmdPart = spaceIdx === -1 ? withoutSlash : withoutSlash.slice(0, spaceIdx);
+    const args = spaceIdx === -1 ? '' : withoutSlash.slice(spaceIdx + 1).trim();
+
+    // 格式 2：pluginId/command — 指定目标插件
+    const slashIdx = cmdPart.indexOf('/');
+    if (slashIdx !== -1) {
+      const targetPluginId = cmdPart.slice(0, slashIdx);
+      const targetCmdName = '/' + cmdPart.slice(slashIdx + 1);
+      // 尝试带 / 和不带 / 两种 key（兼容插件注册时 name 是否带 /）
+      const cmd = this.state.chatCommands.get(targetCmdName) || this.state.chatCommands.get(cmdPart.slice(slashIdx + 1));
+      if (cmd && cmd.pluginId === targetPluginId) {
+        try {
+          return await cmd.handler(args);
+        } catch (e) {
+          console.error(`[PluginRuntime] 指令 ${targetCmdName} 执行出错:`, e);
+          return `指令执行出错: ${targetCmdName}`;
+        }
+      }
+      // 指定了插件但未找到命令
+      return `未找到命令: ${targetCmdName}（插件 ${targetPluginId}）`;
+    }
+
+    // 格式 1 & 3：/command — 精确匹配或广播
+    const cmdName = '/' + cmdPart;
+    const cmd = this.state.chatCommands.get(cmdName) || this.state.chatCommands.get(cmdPart);
+
+    if (cmd) {
+      // 精确匹配（只有一个插件注册了该命令）
+      try {
+        return await cmd.handler(args);
+      } catch (e) {
+        console.error(`[PluginRuntime] 指令 ${cmdName} 执行出错:`, e);
+        return `指令执行出错: ${cmdName}`;
+      }
+    }
+
+    // 检查是否有任何插件注册了同名命令（广播模式）
+    // 注意：chatCommands Map 中同名命令只保留最后一个注册的，
+    // 所以需要遍历所有实例的注册命令
+    const allCommands = this.getCommands();
+    const matched = allCommands.filter(c => c.name === cmdName);
+    if (matched.length === 0) {
+      return undefined; // 无匹配，继续作为普通消息
+    }
+
+    // 广播给所有注册了该命令的插件
+    let lastResult: string | void = undefined;
+    for (const mcmd of matched) {
+      try {
+        const result = await mcmd.handler(args);
+        if (result !== undefined && result !== '') lastResult = result;
+      } catch (e) {
+        console.error(`[PluginRuntime] 指令 ${cmdName} (插件 ${mcmd.pluginId}) 执行出错:`, e);
+      }
+    }
+    return lastResult !== undefined ? lastResult : 'handled';
+  }
+
+  // ==================== UI 注册 ====================
+
+  /** 注册侧边栏面板 */
+  registerSidebarPanel(pluginId: string, panel: SidebarPanelRegistration): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    const panelWithId = { ...panel, pluginId };
+    const existingIdx = this.state.sidebarPanels.findIndex(p => p.id === panel.id);
+    if (existingIdx >= 0) {
+      this.state.sidebarPanels[existingIdx] = panelWithId;
+    } else {
+      this.state.sidebarPanels.push(panelWithId);
+    }
+    this.state.sidebarPanels.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+  }
+
+  /** 获取所有侧边栏面板 */
+  getSidebarPanels(): SidebarPanelRegistration[] {
+    return [...this.state.sidebarPanels];
+  }
+
+  /** 注册工具栏按钮 */
+  registerToolbarButton(pluginId: string, button: ToolbarButtonRegistration): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+
+    // 追加按钮到列表（同 id 覆盖）
+    let buttons = this.state.toolbarButtons.get(pluginId) || [];
+    buttons = buttons.filter(b => b.id !== button.id);
+    buttons.push(button);
+    buttons.sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+    this.state.toolbarButtons.set(pluginId, buttons);
+
+    // 注册 action handler
+    const actionName = `toolbar-btn-${button.id}`;
+    this.registerActionHandler(pluginId, actionName, () => {
+      try {
+        button.onClick();
+      } catch (e) {
+        console.error(`[PluginRuntime] toolbar button onClick error (${pluginId}:${button.id}):`, e);
+      }
+    });
+
+    // 重新渲染所有按钮到 input-toolbar 插槽
+    const allHtml = buttons.map(b => {
+      const aName = `toolbar-btn-${b.id}`;
+      return `<button data-action="${aName}" title="${b.label}" style="display:inline-flex;align-items:center;gap:4px;padding:4px 10px;border-radius:6px;font-size:12px;background:var(--color-bg-tertiary);color:var(--color-text-secondary);border:none;cursor:pointer;white-space:nowrap;">${b.icon ? `<span>${b.icon}</span>` : ''}${b.label}</button>`;
+    }).join('');
+
+    if (allHtml) {
+      this.registerSlot(pluginId, 'input-toolbar', allHtml, { key: 'toolbar-buttons' });
+    } else {
+      // 没有按钮时注销插槽
+      const existing = this.state.slotRegistrations.find(r => r.pluginId === pluginId && r.slotId === 'input-toolbar' && r.id === `${pluginId}_key_toolbar-buttons`);
+      if (existing) {
+        this.unregisterSlot(existing.id);
+      }
+    }
+  }
+
+  /** 注册消息渲染器 */
+  registerMessageRenderer(pluginId: string, renderer: MessageRenderer): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.messageRenderers.push({ ...renderer, pluginId });
+  }
+
+  /** 获取所有消息渲染器 */
+  getMessageRenderers(): MessageRenderer[] {
+    return [...this.state.messageRenderers];
+  }
+
+  /**
+   * 执行 onRenderMessage 管道：多个插件依次修改消息内容
+   * 每个 handler 接收当前 content，返回修改后的 content
+   * 返回 null 表示跳过该消息的渲染（不显示）
+   * 返回经过所有 handler 链式处理后的最终 content
+   */
+  async applyRenderMessagePipeline(message: { role: string; content: string }): Promise<string | null> {
+    const registrations = this.state.hooks.get('onRenderMessage');
+    if (!registrations) return message.content;
+
+    let content: string | null = message.content;
+    for (const reg of registrations) {
+      const instance = this.state.instances.get(reg.pluginId);
+      if (!instance || !instance.enabled) continue;
+      if (content === null) break; // 已被上游标记为跳过，终止管道
+      const result = await this.callSafe(reg.handler, [{ ...message, content }], reg.pluginId, 'onRenderMessage');
+      if (result === null) {
+        content = null; // 标记为跳过渲染
+        break; // 终止管道
+      }
+      if (typeof result === 'string') {
+        content = result;
+      }
+    }
+    return content;
+  }
+
+  // ==================== 全局 UI API：插槽注册 ====================
+
+  /** 注册插槽内容 */
+  registerSlot(pluginId: string, slotId: UISlotId, content: string, options?: { priority?: number; persistent?: boolean; key?: string }): string | null {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return null;
+
+    // 权限检查
+    if (!checkSlotPermission(instance.manifest, slotId)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有 slot:${slotId} 权限`);
+      return null;
+    }
+
+    const sanitizedContent = sanitizeHTML(content);
+
+    // 按 pluginId + slotId + key 查找（key 用于区分同一插件在同一插槽中的多个注册）
+    const matchKey = options?.key;
+    const existing = this.state.slotRegistrations.find(r =>
+      r.pluginId === pluginId && r.slotId === slotId && (matchKey ? r.id === `${pluginId}_key_${matchKey}` : !r.id.startsWith(`${pluginId}_key_`))
+    );
+    let id: string;
+    if (existing) {
+      id = existing.id;
+      existing.content = sanitizedContent;
+      existing.priority = options?.priority;
+      existing.persistent = options?.persistent;
+    } else {
+      id = matchKey ? `${pluginId}_key_${matchKey}` : `${pluginId}_slot_${Date.now()}`;
+      const registration: SlotRegistration = {
+        id,
+        pluginId,
+        slotId,
+        content: sanitizedContent,
+        priority: options?.priority,
+        persistent: options?.persistent,
+      };
+      this.state.slotRegistrations.push(registration);
+      this.resourceTracker.trackSlotRegistration(pluginId, id);
+    }
+
+    this.state.slotRegistrations.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    this.uiCallbacks.onSlotChange?.();
+    return id;
+  }
+
+  /** 更新已注册的插槽内容（语义化别名，等同于 registerSlot 更新） */
+  updateSlot(registrationId: string, content: string, options?: { priority?: number }): boolean {
+    const existing = this.state.slotRegistrations.find(r => r.id === registrationId);
+    if (!existing) return false;
+    existing.content = sanitizeHTML(content);
+    if (options?.priority !== undefined) existing.priority = options.priority;
+    this.state.slotRegistrations.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    this.uiCallbacks.onSlotChange?.();
+    return true;
+  }
+
+  /** 移除插槽内容 */
+  unregisterSlot(registrationId: string): void {
+    this.state.slotRegistrations = this.state.slotRegistrations.filter(r => r.id !== registrationId);
+    this.uiCallbacks.onSlotChange?.();
+  }
+
+  /** 获取指定插槽的所有注册 */
+  getSlotRegistrations(slotId: UISlotId): SlotRegistration[] {
+    return this.state.slotRegistrations.filter(r => r.slotId === slotId);
+  }
+
+  /** 注册 action handler（用于 data-action 事件委托） */
+  registerActionHandler(pluginId: string, actionName: string, handler: (e: { target: HTMLElement; actionName: string; payload?: string }) => void): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    // 同 pluginId + actionName 时覆盖
+    const idx = this.state.actionHandlers.findIndex(h => h.pluginId === pluginId && h.actionName === actionName);
+    if (idx >= 0) {
+      this.state.actionHandlers[idx].handler = handler;
+    } else {
+      this.state.actionHandlers.push({ pluginId, actionName, handler });
+    }
+  }
+
+  /** 触发 action handler（由 PluginSlotRenderer 事件委托调用） */
+  dispatchAction(pluginId: string, actionName: string, target: HTMLElement, payload?: string): void {
+    const entry = this.state.actionHandlers.find(h => h.pluginId === pluginId && h.actionName === actionName);
+    if (entry) {
+      try {
+        entry.handler({ target, actionName, payload });
+      } catch (e) {
+        console.error(`[PluginRuntime] action handler 执行出错 (${pluginId}:${actionName}):`, e);
+      }
+    }
+  }
+
+  /** 获取所有插槽注册 */
+  getAllSlotRegistrations(): SlotRegistration[] {
+    return [...this.state.slotRegistrations];
+  }
+
+  // ==================== 全局 UI API：模态框 ====================
+
+  /** 显示模态框 */
+  showModal(pluginId: string, options: { title: string; content: string; width?: string; style?: Record<string, unknown>; closable?: boolean; backdrop?: boolean; onClose?: () => void; actions?: ModalActionInput[] }): string | null {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return null;
+
+    if (!checkModalPermission(instance.manifest)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有模态框权限`);
+      return null;
+    }
+
+    const id = `${pluginId}_modal_${Date.now()}`;
+    const wrappedActions = options.actions?.map(action => ({
+      ...action,
+      onClick: () => action.onClick({ modalId: id, close: () => this.closeModal(id) }),
+    }));
+    const modal: ModalRegistration = { id, pluginId, ...options, actions: wrappedActions };
+    this.state.modals.set(id, modal);
+    this.resourceTracker.trackModal(pluginId, id);
+
+    if (this.uiCallbacks.showModal) {
+      this.uiCallbacks.showModal(modal);
+    }
+
+    return id;
+  }
+
+  /** 更新模态框内容/样式（不关闭重开，避免闪烁） */
+  updateModal(modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }): void {
+    const modal = this.state.modals.get(modalId);
+    if (!modal) return;
+
+    if (options.title !== undefined) modal.title = options.title;
+    if (options.content !== undefined) modal.content = options.content;
+    if (options.width !== undefined) modal.width = options.width;
+    if (options.style !== undefined) modal.style = options.style as React.CSSProperties;
+
+    if (this.uiCallbacks.updateModal) {
+      this.uiCallbacks.updateModal(modalId, modal as any);
+    }
+  }
+
+  /** 关闭模态框 */
+  closeModal(modalId: string): void {
+    const modal = this.state.modals.get(modalId);
+    if (modal) {
+      if (modal.onClose) {
+        try {
+          modal.onClose();
+        } catch (e) {
+          console.error(`[PluginRuntime] 模态框关闭回调出错:`, e);
+        }
+      }
+      this.state.modals.delete(modalId);
+      if (this.uiCallbacks.closeModal) {
+        this.uiCallbacks.closeModal(modalId);
+      }
+    }
+  }
+
+  /** 获取所有模态框 */
+  getModals(): ModalRegistration[] {
+    return Array.from(this.state.modals.values());
+  }
+
+  /** 确认对话框 */
+  async confirm(pluginId: string, title: string, message: string, options?: ConfirmOptions): Promise<boolean> {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return false;
+
+    if (!checkModalPermission(instance.manifest)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有确认对话框权限`);
+      return false;
+    }
+
+    if (this.uiCallbacks.confirm) {
+      return this.uiCallbacks.confirm(title, message, options);
+    }
+    return false;
+  }
+
+  // ==================== 全局 UI API：样式注入 ====================
+
+  /** 注入 CSS 样式 */
+  injectStyle(pluginId: string, css: string): string | null {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return null;
+
+    if (!checkStylePermission(instance.manifest)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有样式注入权限`);
+      return null;
+    }
+
+    try {
+      const styleId = `${pluginId}_style_${Date.now()}`;
+      const styleElement = document.createElement('style');
+      styleElement.setAttribute('data-plugin-style-id', styleId);
+      styleElement.setAttribute('data-plugin-id', pluginId);
+      styleElement.textContent = css;
+      document.head.appendChild(styleElement);
+
+      this.resourceTracker.trackStyle(pluginId, styleId, styleElement);
+      return styleId;
+    } catch (e) {
+      console.error(`[PluginRuntime] 插件 ${pluginId} 注入样式失败:`, e);
+      return null;
+    }
+  }
+
+  /** 移除 CSS 样式 */
+  removeStyle(pluginId: string, styleId: string): void {
+    const res = this.resourceTracker.get(pluginId);
+    if (!res) return;
+
+    const styleElement = res.styleTags.get(styleId);
+    if (styleElement) {
+      try {
+        if (styleElement.parentNode) {
+          styleElement.parentNode.removeChild(styleElement);
+        }
+      } catch (e) {
+        console.error(`[PluginRuntime] 移除样式失败:`, e);
+      }
+      this.resourceTracker.untrackStyle(pluginId, styleId);
+    }
+  }
+
+  // ==================== 全局 UI API：宿主事件 ====================
+
+  /** 监听宿主事件 */
+  onHostEvent(pluginId: string, eventName: string, handler: HookHandler): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) return;
+
+    if (!checkHostEventPermission(instance.manifest)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有宿主事件监听权限`);
+      return;
+    }
+
+    this.state.hostEventHandlers.push({ pluginId, eventName, handler });
+    this.resourceTracker.trackHostEventHandler(pluginId, eventName, handler);
+  }
+
+  /** 取消监听宿主事件 */
+  offHostEvent(pluginId: string, eventName: string, handler: HookHandler): void {
+    this.state.hostEventHandlers = this.state.hostEventHandlers.filter(
+      h => !(h.pluginId === pluginId && h.eventName === eventName && h.handler === handler)
+    );
+  }
+
+  /** 触发宿主事件（供 React 端调用） */
+  emitHostEvent(eventName: string, data?: unknown): void {
+    for (const reg of this.state.hostEventHandlers) {
+      const instance = this.state.instances.get(reg.pluginId);
+      if (!instance || !instance.enabled) continue;
+      if (reg.eventName !== eventName) continue;
+      try {
+        reg.handler(data);
+      } catch (e) {
+        console.error(`[PluginRuntime] 宿主事件 ${eventName} 处理出错 (插件: ${reg.pluginId}):`, e);
+      }
+    }
+  }
+
+  // ==================== 全局 UI API：DOM 沙箱 ====================
+
+  /** 创建 DOM 沙箱 API */
+  createDOMSandboxAPI(pluginId: string) {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance) {
+      return {
+        create: () => { throw new Error('插件未加载'); },
+        append: () => null,
+        remove: () => false,
+        update: () => false,
+        getContainer: () => null,
+        query: () => [],
+        on: () => false,
+        off: () => false,
+      };
+    }
+
+    if (!checkDOMPermission(instance.manifest)) {
+      console.warn(`[PluginRuntime] 插件 ${pluginId} 没有自由 DOM 操作权限`);
+      return {
+        create: () => { throw new Error('插件没有自由 DOM 操作权限 (dom:free)'); },
+        append: () => null,
+        remove: () => false,
+        update: () => false,
+        getContainer: () => null,
+        query: () => [],
+        on: () => false,
+        off: () => false,
+      };
+    }
+
+    return createDOMSandbox({
+      pluginId,
+      resourceTracker: this.resourceTracker,
+      getContainerElement: (slotId: UISlotId) => {
+        if (this.getSlotContainerCallback) {
+          return this.getSlotContainerCallback(slotId);
+        }
+        return document.querySelector(`[data-plugin-slot="${slotId}"]`);
+      },
+    });
+  }
+
+  // ==================== AI 拦截 ====================
+
+  /** 注册 prompt 修改器 */
+  registerPromptModifier(pluginId: string, handler: (prompt: string, worldSetting: Record<string, unknown>) => string): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.promptModifiers.push({ pluginId, handler });
+  }
+
+  /** 应用所有 prompt 修改器 */
+  async applyPromptModifiers(prompt: string, worldSetting: Record<string, unknown>): Promise<string> {
+    let result = prompt;
+    for (const { handler, pluginId } of this.state.promptModifiers) {
+      const value = await this.callSafe(handler, [result, worldSetting], pluginId, 'Prompt 修改器');
+      if (typeof value === 'string') result = value;
+    }
+    return result;
+  }
+
+  /** 注册消息预处理 */
+  registerBeforeSendHandler(pluginId: string, handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[]): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.beforeSendHandlers.push({ pluginId, handler });
+  }
+
+  /** 应用所有消息预处理 */
+  async applyBeforeSendHandlers(messages: { role: string; content: string }[]): Promise<{ role: string; content: string }[]> {
+    let result = messages;
+    for (const { handler, pluginId } of this.state.beforeSendHandlers) {
+      const value = await this.callSafe(handler, [result], pluginId, '消息预处理');
+      if (Array.isArray(value)) result = value;
+    }
+    return result;
+  }
+
+  /** 注册完整消息数组预处理（system + user/assistant 合并后） */
+  registerBeforeCompleteHandler(pluginId: string, handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[]): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.beforeCompleteHandlers.push({ pluginId, handler });
+  }
+
+  /** 应用所有完整消息数组预处理 */
+  async applyBeforeCompleteHandlers(messages: { role: string; content: string }[]): Promise<{ role: string; content: string }[]> {
+    let result = messages;
+    for (const { handler, pluginId } of this.state.beforeCompleteHandlers) {
+      const value = await this.callSafe(handler, [result], pluginId, '完整消息预处理');
+      if (Array.isArray(value)) result = value;
+    }
+    return result;
+  }
+
+  /** 注册响应后处理 */
+  registerAfterReceiveHandler(pluginId: string, handler: (content: string) => string | Promise<string>): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.afterReceiveHandlers.push({ pluginId, handler });
+  }
+
+  /** 应用所有响应后处理（支持 async handler） */
+  async applyAfterReceiveHandlers(content: string): Promise<string> {
+    let result = content;
+    for (const { handler, pluginId } of this.state.afterReceiveHandlers) {
+      const value = await this.callSafe(handler, [result], pluginId, '响应后处理');
+      if (typeof value === 'string') result = value;
+    }
+    return result;
+  }
+
+  /** 注册请求配置修改器 */
+  registerRequestConfigModifier(pluginId: string, handler: (config: { temperature: number; maxTokens: number; model: string }) => { temperature: number; maxTokens: number; model: string }): void {
+    const instance = this.state.instances.get(pluginId);
+    if (!instance || !instance.enabled) return;
+    this.state.requestConfigModifiers.push({ pluginId, handler });
+  }
+
+  /** 应用所有请求配置修改器 */
+  async applyRequestConfigModifiers(config: { temperature: number; maxTokens: number; model: string }): Promise<{ temperature: number; maxTokens: number; model: string }> {
+    let result = config;
+    for (const { handler, pluginId } of this.state.requestConfigModifiers) {
+      const value = await this.callSafe(handler, [result], pluginId, '请求配置修改器');
+      if (value && typeof value === 'object' && 'temperature' in value) result = value;
+    }
+    return result;
+  }
+
+  // ==================== 插件持久化存储 ====================
+
+  /** 获取插件存储值 */
+  getPluginStorage(pluginId: string, key: string): unknown {
+    return this.pluginStorage.get(pluginId)?.get(key);
+  }
+
+  /** 设置插件存储值 */
+  setPluginStorage(pluginId: string, key: string, value: unknown): void {
+    if (!this.pluginStorage.has(pluginId)) {
+      this.pluginStorage.set(pluginId, new Map());
+    }
+    this.pluginStorage.get(pluginId)!.set(key, value);
+  }
+
+  /** 删除插件存储值 */
+  removePluginStorage(pluginId: string, key: string): void {
+    this.pluginStorage.get(pluginId)?.delete(key);
+  }
+
+  /** 获取插件存储所有键 */
+  getPluginStorageKeys(pluginId: string): string[] {
+    return Array.from(this.pluginStorage.get(pluginId)?.keys() || []);
+  }
+
+  // ==================== 内部方法 ====================
+
+  /** 执行插件代码，返回导出对象 */
+  private executePluginCode(code: string, pluginId: string): Record<string, (...args: unknown[]) => unknown> {
+    try {
+      // 使用 Function 构造器创建隔离的执行环境
+      // 插件通过 return { setup, exports } 导出 setup 函数和公开 API
+      const wrappedCode = `
+        'use strict';
+        ${code};
+        if (typeof setup === 'function') {
+          return { setup };
+        }
+        return {};
+      `;
+      const factory = new Function('xinyu', wrappedCode);
+      const exports: Record<string, (...args: unknown[]) => unknown> = {};
+
+      // 创建 xinyu API 桥接对象
+      const xinyu = this.createXinyuBridge(pluginId);
+
+      const result = factory(xinyu);
+      if (result && typeof result === 'object') {
+        Object.assign(exports, result);
+      }
+
+      return exports;
+    } catch (e) {
+      console.error(`[PluginRuntime] 执行插件代码出错 (${pluginId}):`, e);
+      return {};
+    }
+  }
+
+  /** 创建 xinyu API 桥接对象 */
+  private createXinyuBridge(pluginId: string): Record<string, unknown> {
+    // Blob 转 data URL 辅助函数
+    const blobToDataUrl = (blob: Blob): Promise<string> =>
+      new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result as string);
+        reader.onerror = reject;
+        reader.readAsDataURL(blob);
+      });
+
+    // 使用箭头函数绑定 this，避免 eslint no-this-alias
+    const getGameState = () => this.getGameState();
+    const setGameState = (partial: Record<string, unknown>) => this.setGameState(partial);
+    const getAttributes = () => this.getAttributes();
+    const registerAttribute = (attr: GameAttribute) => this.registerAttribute(pluginId, attr);
+    const setAttribute = (key: string, value: number | string | boolean) => this.setAttribute(key, value);
+    const registerCommand = (cmd: ChatCommand) => this.registerCommand(pluginId, cmd);
+    const registerMessageRenderer = (matcher: (msg: { role: string; content: string }) => boolean, renderer: (msg: { role: string; content: string }) => string) => {
+      this.registerMessageRenderer(pluginId, { matcher, renderer });
+    };
+    const registerSidebarPanel = (panel: SidebarPanelRegistration) => this.registerSidebarPanel(pluginId, panel);
+    const registerToolbarButton = (button: ToolbarButtonRegistration) => this.registerToolbarButton(pluginId, button);
+    const registerMessageCard = (matcher: (msg: { role: string; content: string }) => boolean, render: (data: Record<string, unknown>) => string) => {
+      this.registerMessageRenderer(pluginId, { matcher, renderer: render as (msg: { role: string; content: string }) => string });
+    };
+    const getManifest = () => this.state.instances.get(pluginId)?.manifest;
+    // plugin.config：插件配置读写（持久化到数据库，与 storage 独立）
+    const configApi = {
+      get: (key?: string) => {
+        const config = this.state.instances.get(pluginId)?.config || {};
+        return key !== undefined ? config[key] : config;
+      },
+      set: (keyOrConfig: string | Record<string, unknown>, value?: unknown) => {
+        const instance = this.state.instances.get(pluginId);
+        if (!instance) return;
+        if (typeof keyOrConfig === 'string') {
+          instance.config = { ...instance.config, [keyOrConfig]: value };
+        } else {
+          instance.config = keyOrConfig;
+        }
+        this.updatePluginConfig(pluginId, instance.config);
+      },
+    };
+    // plugin.storage：纯粹的运行时临时存储，不涉及配置数据
+    const getPluginStorageGet = (key: string) => {
+      return this.getPluginStorage(pluginId, key);
+    };
+    const getPluginStorageSet = (key: string, value: unknown) => {
+      this.setPluginStorage(pluginId, key, value);
+    };
+    const getPluginStorageRemove = (key: string) => this.removePluginStorage(pluginId, key);
+    const getPluginStorageKeys = () => this.getPluginStorageKeys(pluginId);
+    const registerHook = (hook: PluginHook, handler: HookHandler) => this.registerHook(pluginId, hook, handler);
+    const unregisterHook = (hook: PluginHook, handler: HookHandler) => this.unregisterHook(pluginId, hook, handler);
+    const parseDiceNotation = (notation: string) => this.parseDiceNotation(notation);
+    const formatDate = (date: Date | string, format?: string) => this.formatDate(date, format);
+    const registerPromptModifier = (handler: (prompt: string, worldSetting: Record<string, unknown>) => string) => {
+      this.registerPromptModifier(pluginId, handler);
+    };
+    const registerBeforeSendHandler = (handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[]) => {
+      this.registerBeforeSendHandler(pluginId, handler);
+    };
+    const registerBeforeCompleteHandler = (handler: (messages: { role: string; content: string }[]) => { role: string; content: string }[]) => {
+      this.registerBeforeCompleteHandler(pluginId, handler);
+    };
+    const registerAfterReceiveHandler = (handler: (content: string) => string | Promise<string>) => {
+      this.registerAfterReceiveHandler(pluginId, handler);
+    };
+    const registerRequestConfigModifier = (handler: (config: { temperature: number; maxTokens: number; model: string }) => { temperature: number; maxTokens: number; model: string }) => {
+      this.registerRequestConfigModifier(pluginId, handler);
+    };
+
+    // 全局 UI API 方法
+    const uiRegisterSlot = (slotId: UISlotId, content: string, options?: { priority?: number; persistent?: boolean }) => {
+      return this.registerSlot(pluginId, slotId, content, options);
+    };
+    const uiUnregisterSlot = (registrationId: string) => {
+      this.unregisterSlot(registrationId);
+    };
+    const uiUpdateSlot = (registrationId: string, content: string, options?: { priority?: number }) => {
+      return this.updateSlot(registrationId, content, options);
+    };
+    const uiRegisterActionHandler = (actionName: string, handler: (e: { target: HTMLElement; actionName: string; payload?: string }) => void) => {
+      this.registerActionHandler(pluginId, actionName, handler);
+    };
+    const uiShowModal = (options: { title: string; content: string; width?: string; style?: Record<string, unknown>; closable?: boolean; backdrop?: boolean; onClose?: () => void; actions?: ModalActionInput[] }) => {
+      return this.showModal(pluginId, options);
+    };
+    const uiCloseModal = (modalId: string) => {
+      this.closeModal(modalId);
+    };
+    const uiUpdateModal = (modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }) => {
+      this.updateModal(modalId, options);
+    };
+    const uiConfirm = async (title: string, message: string, options?: ConfirmOptions) => {
+      return this.confirm(pluginId, title, message, options);
+    };
+    const uiInjectStyle = (css: string) => {
+      return this.injectStyle(pluginId, css);
+    };
+    const uiRemoveStyle = (styleId: string) => {
+      this.removeStyle(pluginId, styleId);
+    };
+    const uiOnHostEvent = (eventName: string, handler: HookHandler) => {
+      this.onHostEvent(pluginId, eventName, handler);
+    };
+    const uiOffHostEvent = (eventName: string, handler: HookHandler) => {
+      this.offHostEvent(pluginId, eventName, handler);
+    };
+
+    return {
+      game: {
+        getWorldSetting: () => {
+          const manifest = getManifest();
+          if (!manifest || !checkGameInfoPermission(manifest)) return {};
+          return this.uiCallbacks.getWorldSetting?.() || {};
+        },
+        setWorldSetting: (data: Record<string, unknown>) => {
+          const manifest = getManifest();
+          if (!manifest || !checkGameInfoWritePermission(manifest)) return;
+          this.uiCallbacks.setWorldSetting?.(data);
+        },
+        getState: getGameState,
+        setState: setGameState,
+        getSessionId: () => {
+          const manifest = getManifest();
+          if (!manifest || !checkGameInfoPermission(manifest)) return '';
+          return this.uiCallbacks.getSessionId?.() || '';
+        },
+        getMessages: () => {
+          const manifest = getManifest();
+          if (!manifest || !checkGameInfoPermission(manifest)) return [];
+          return this.uiCallbacks.getMessages?.() || [];
+        },
+        getAttributes: () => {
+          const manifest = getManifest();
+          if (!manifest || !checkGameInfoPermission(manifest)) return [];
+          return getAttributes();
+        },
+        registerAttribute,
+        setAttribute,
+      },
+      chat: {
+        send: async (content: string) => {
+          if (this.uiCallbacks.sendMessage) {
+            await this.uiCallbacks.sendMessage(content);
+          }
+        },
+        insertSystemMessage: (content: string) => {
+          if (this.uiCallbacks.insertSystemMessage) {
+            this.uiCallbacks.insertSystemMessage(content);
+          }
+        },
+        insertNotice: (html: string) => {
+          if (this.uiCallbacks.insertNotice) {
+            this.uiCallbacks.insertNotice(html);
+          }
+        },
+        injectChatStyle: (css: string) => {
+          return this.injectStyle(pluginId, css);
+        },
+        removeChatStyle: (styleId: string) => {
+          this.removeStyle(pluginId, styleId);
+        },
+        getHistory: () => [],
+        clearHistory: () => {},
+        registerCommand,
+        registerMessageRenderer,
+        // 输入框控制 API（需 input:control 权限）
+        input: {
+          getContent: (): string | null => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return null;
+            return this.inputControl.getContent();
+          },
+          setContent: (text: string): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setContent(text);
+          },
+          appendContent: (text: string): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.appendContent(text);
+          },
+          clearContent: (): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.clearContent();
+          },
+          setPlaceholder: (text: string): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setPlaceholder(text);
+          },
+          setDisabled: (disabled: boolean): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setDisabled(disabled);
+          },
+          focus: (): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.focus();
+          },
+          blur: (): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.blur();
+          },
+          setStyle: (style: Record<string, string>): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setStyle(style);
+          },
+          injectStyle: (css: string): string => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return '';
+            return this.inputControl.injectStyle(css);
+          },
+          removeStyle: (styleId: string): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.removeStyle(styleId);
+          },
+          onInput: (handler: (value: string) => void): (() => void) => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return () => {};
+            return this.inputControl.onInput(handler);
+          },
+          onSend: (handler: (content: string) => void): (() => void) => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return () => {};
+            return this.inputControl.onSend(handler);
+          },
+          onKeyDown: (handler: (event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void): (() => void) => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return () => {};
+            return this.inputControl.onKeyDown(handler);
+          },
+          getSelection: (): { start: number; end: number; text: string } | null => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return null;
+            return this.inputControl.getSelection();
+          },
+          setSelection: (start: number, end: number): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setSelection(start, end);
+          },
+          insertAtCursor: (text: string): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.insertAtCursor(text);
+          },
+          setMaxLength: (length: number): void => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return;
+            this.inputControl.setMaxLength(length);
+          },
+          getLength: (): number => {
+            const manifest = getManifest();
+            if (!manifest || !checkInputControlPermission(manifest)) return 0;
+            return this.inputControl.getLength();
+          },
+        },
+      },
+      ui: {
+        // 现有 API
+        registerSidebarPanel,
+        registerInputToolbarButton: registerToolbarButton,
+        registerMessageCard,
+        toast: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => {
+          if (this.uiCallbacks.toast) {
+            this.uiCallbacks.toast(message, type);
+          }
+        },
+
+        // 新增：确认对话框
+        confirm: uiConfirm,
+
+        // 新增：自定义模态框
+        showModal: uiShowModal,
+        closeModal: uiCloseModal,
+        updateModal: uiUpdateModal,
+
+        // 新增：容器注册式 API
+        registerSlot: uiRegisterSlot,
+        unregisterSlot: uiUnregisterSlot,
+        updateSlot: uiUpdateSlot,
+
+        // 新增：事件委托 action handler
+        onAction: uiRegisterActionHandler,
+
+        // 新增：自由 DOM API
+        dom: this.createDOMSandboxAPI(pluginId),
+
+        // 新增：样式注入 API
+        injectStyle: uiInjectStyle,
+        removeStyle: uiRemoveStyle,
+
+        // 新增：宿主事件系统
+        onHostEvent: uiOnHostEvent,
+        offHostEvent: uiOffHostEvent,
+      },
+      ai: {
+        onPromptBuild: registerPromptModifier,
+        onBeforeSend: registerBeforeSendHandler,
+        onBeforeComplete: registerBeforeCompleteHandler,
+        onAfterReceive: registerAfterReceiveHandler,
+        onRequestConfig: registerRequestConfigModifier,
+      },
+      plugin: {
+        getManifest,
+        config: configApi,
+        storage: {
+          get: getPluginStorageGet,
+          set: getPluginStorageSet,
+          remove: getPluginStorageRemove,
+          keys: getPluginStorageKeys,
+        },
+        on: registerHook,
+        off: unregisterHook,
+        // 跨插件通信 API
+        callPlugin: (targetPluginId: string, method: string, ...args: unknown[]) => {
+          return this.callPlugin(pluginId, targetPluginId, method, ...args);
+        },
+        // 运行时加载依赖（支持降级）
+        loadDependency: (targetPluginId: string, options?: { version?: string; timeout?: number }) => {
+          return this.loadDependency(pluginId, targetPluginId, options);
+        },
+        // 检查插件是否可用
+        isPluginAvailable: (targetPluginId: string) => {
+          return this.isPluginAvailable(targetPluginId);
+        },
+        // 获取插件的公开导出 API 列表
+        getPluginExports: (targetPluginId: string) => {
+          return this.getPluginExports(targetPluginId);
+        },
+        // 获取插件资源文件内容（需 file:read 权限）
+        getResource: async (resourcePath: string): Promise<string | null> => {
+          const manifest = getManifest();
+          if (!manifest) return null;
+          try {
+            const params = new URLSearchParams({ pluginId, path: resourcePath });
+            const res = await fetch(`/api/plugins/resources?${params}`);
+            if (!res.ok) return null;
+            const contentType = res.headers.get('content-type') || '';
+            if (contentType.startsWith('text/') || contentType.includes('json') || contentType.includes('javascript')) {
+              return await res.text();
+            }
+            // 二进制文件返回 data URL
+            const blob = await res.blob();
+            return await blobToDataUrl(blob);
+          } catch { return null; }
+        },
+        // 获取插件资源文件的 HTTP URL（需 file:read 权限）
+        getResourceUrl: (resourcePath: string): string => {
+          return `/api/plugins/resources?pluginId=${encodeURIComponent(pluginId)}&path=${encodeURIComponent(resourcePath)}`;
+        },
+      },
+      // storage：持久化 key-value 存储（需 storage:plugin 权限）
+      storage: {
+        get: async (key: string) => {
+          const manifest = getManifest();
+          if (!manifest || !checkStoragePermission(manifest)) {
+            console.warn(`[PluginRuntime] storage.get 被拒绝: 插件 ${pluginId} 缺少 storage:plugin 权限`);
+            return null;
+          }
+          try {
+            const worldId = this.uiCallbacks.getWorldId?.() || '';
+            const params = new URLSearchParams({ pluginId, key, worldId });
+            const res = await fetch(`/api/plugins/storage?${params}`);
+            if (!res.ok) {
+              console.warn(`[PluginRuntime] storage.get 失败: ${res.status} ${res.statusText} (pluginId=${pluginId}, key=${key})`);
+              return null;
+            }
+            const data = await res.json();
+            return data.value;
+          } catch (e) {
+            console.error(`[PluginRuntime] storage.get 异常 (pluginId=${pluginId}, key=${key}):`, e);
+            return null;
+          }
+        },
+        set: async (key: string, value: unknown) => {
+          const manifest = getManifest();
+          if (!manifest || !checkStoragePermission(manifest)) {
+            console.warn(`[PluginRuntime] storage.set 被拒绝: 插件 ${pluginId} 缺少 storage:plugin 权限`);
+            return;
+          }
+          try {
+            const worldId = this.uiCallbacks.getWorldId?.() || '';
+            const res = await fetch('/api/plugins/storage', {
+              method: 'PUT',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ pluginId, key, value, worldId }),
+            });
+            if (!res.ok) {
+              console.warn(`[PluginRuntime] storage.set 失败: ${res.status} ${res.statusText} (pluginId=${pluginId}, key=${key})`);
+            }
+          } catch (e) {
+            console.error(`[PluginRuntime] storage.set 异常 (pluginId=${pluginId}, key=${key}):`, e);
+          }
+        },
+        remove: async (key: string) => {
+          const manifest = getManifest();
+          if (!manifest || !checkStoragePermission(manifest)) return;
+          try {
+            const worldId = this.uiCallbacks.getWorldId?.() || '';
+            const params = new URLSearchParams({ pluginId, key, worldId });
+            const res = await fetch(`/api/plugins/storage?${params}`, { method: 'DELETE' });
+            if (!res.ok) {
+              console.warn(`[PluginRuntime] storage.remove 失败: ${res.status} (pluginId=${pluginId}, key=${key})`);
+            }
+          } catch (e) {
+            console.error(`[PluginRuntime] storage.remove 异常 (pluginId=${pluginId}, key=${key}):`, e);
+          }
+        },
+        keys: async () => {
+          const manifest = getManifest();
+          if (!manifest || !checkStoragePermission(manifest)) return [];
+          try {
+            const worldId = this.uiCallbacks.getWorldId?.() || '';
+            const params = new URLSearchParams({ pluginId, worldId });
+            const res = await fetch(`/api/plugins/storage?${params}`);
+            if (!res.ok) return [];
+            const data = await res.json();
+            return Object.keys(data.values || {});
+          } catch { return []; }
+        },
+      },
+      // file：文件操作（需 file:read / file:write 权限）
+      file: {
+        read: async (fileName: string) => {
+          const manifest = getManifest();
+          if (!manifest || !checkFileReadPermission(manifest)) return null;
+          try {
+            const params = new URLSearchParams({ pluginId, fileName });
+            const res = await fetch(`/api/plugins/files?${params}`);
+            if (!res.ok) return null;
+            const data = await res.json();
+            return data.content;
+          } catch { return null; }
+        },
+        write: async (fileName: string, content: string) => {
+          const manifest = getManifest();
+          if (!manifest || !checkFileWritePermission(manifest)) return;
+          try {
+            await fetch('/api/plugins/files', {
+              method: 'PUT',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ pluginId, fileName, content }),
+            });
+          } catch { /* ignore */ }
+        },
+        remove: async (fileName: string) => {
+          const manifest = getManifest();
+          if (!manifest || !checkFileWritePermission(manifest)) return;
+          try {
+            const params = new URLSearchParams({ pluginId, fileName });
+            await fetch(`/api/plugins/files?${params}`, { method: 'DELETE' });
+          } catch { /* ignore */ }
+        },
+        list: async () => {
+          const manifest = getManifest();
+          if (!manifest || !checkFileReadPermission(manifest)) return [];
+          try {
+            const params = new URLSearchParams({ pluginId });
+            const res = await fetch(`/api/plugins/files?${params}`);
+            if (!res.ok) return [];
+            const data = await res.json();
+            return data.files || [];
+          } catch { return []; }
+        },
+      },
+      utils: {
+        randomInt: (min: number, max: number) => Math.floor(Math.random() * (max - min + 1)) + min,
+        rollDice: parseDiceNotation,
+        formatDate,
+        debounce: (fn: (...args: unknown[]) => unknown, ms: number) => {
+          let timer: ReturnType<typeof setTimeout> | null = null;
+          return (...args: unknown[]) => {
+            if (timer) clearTimeout(timer);
+            timer = setTimeout(() => fn(...args), ms);
+          };
+        },
+        throttle: (fn: (...args: unknown[]) => unknown, ms: number) => {
+          let lastCall = 0;
+          return (...args: unknown[]) => {
+            const now = Date.now();
+            if (now - lastCall >= ms) {
+              lastCall = now;
+              fn(...args);
+            }
+          };
+        },
+        eventBus: (() => {
+          const handlers = new Map<string, Array<(...args: unknown[]) => void>>();
+          return {
+            _handlers: handlers,
+            on(event: string, handler: (...args: unknown[]) => void) {
+              if (!handlers.has(event)) {
+                handlers.set(event, []);
+              }
+              handlers.get(event)!.push(handler);
+            },
+            off(event: string, handler: (...args: unknown[]) => void) {
+              const hs = handlers.get(event);
+              if (hs) {
+                const idx = hs.indexOf(handler);
+                if (idx !== -1) hs.splice(idx, 1);
+              }
+            },
+            emit(event: string, ...args: unknown[]) {
+              const hs = handlers.get(event);
+              if (hs) {
+                hs.forEach(h => { try { h(...args); } catch (e) { console.error(e); } });
+              }
+            },
+          };
+        })(),
+      },
+    };
+  }
+
+  /** 解析骰子表达式 */
+  private parseDiceNotation(notation: string): { notation: string; rolls: number[]; modifier: number; total: number } {
+    const trimmed = notation.trim().toLowerCase();
+    const match = trimmed.match(/^(\d+)d(\d+)([+-]\d+)?$/);
+    if (!match) {
+      return { notation: trimmed, rolls: [0], modifier: 0, total: 0 };
+    }
+    const count = parseInt(match[1]);
+    const sides = parseInt(match[2]);
+    const modifier = match[3] ? parseInt(match[3]) : 0;
+    const rolls: number[] = [];
+    for (let i = 0; i < count; i++) {
+      rolls.push(Math.floor(Math.random() * sides) + 1);
+    }
+    const sum = rolls.reduce((a, b) => a + b, 0);
+    return { notation: trimmed, rolls, modifier, total: sum + modifier };
+  }
+
+  /** 格式化日期 */
+  private formatDate(date: Date | string, format?: string): string {
+    const d = typeof date === 'string' ? new Date(date) : date;
+    const fmt = format || 'YYYY-MM-DD HH:mm:ss';
+    const pad = (n: number) => n.toString().padStart(2, '0');
+    return fmt
+      .replace('YYYY', d.getFullYear().toString())
+      .replace('MM', pad(d.getMonth() + 1))
+      .replace('DD', pad(d.getDate()))
+      .replace('HH', pad(d.getHours()))
+      .replace('mm', pad(d.getMinutes()))
+      .replace('ss', pad(d.getSeconds()));
+  }
+
+  /** 清理插件的所有注册（按 pluginId 精确过滤） */
+  private unregisterAllForPlugin(pluginId: string): void {
+    // 清理 hooks
+    this.state.hooks.forEach((registrations, hook) => {
+      this.state.hooks.set(hook, registrations.filter(r => r.pluginId !== pluginId));
+    });
+
+    // 清理 UI 注册（按 pluginId 过滤，修复原有 Bug）
+    this.state.sidebarPanels = this.state.sidebarPanels.filter(p => p.pluginId !== pluginId);
+    this.state.toolbarButtons.delete(pluginId);
+    this.state.messageRenderers = this.state.messageRenderers.filter(r => r.pluginId !== pluginId);
+
+    // 清理 AI 拦截（按 pluginId 过滤）
+    this.state.promptModifiers = this.state.promptModifiers.filter(m => m.pluginId !== pluginId);
+    this.state.beforeSendHandlers = this.state.beforeSendHandlers.filter(h => h.pluginId !== pluginId);
+    this.state.beforeCompleteHandlers = this.state.beforeCompleteHandlers.filter(h => h.pluginId !== pluginId);
+    this.state.afterReceiveHandlers = this.state.afterReceiveHandlers.filter(h => h.pluginId !== pluginId);
+    this.state.requestConfigModifiers = this.state.requestConfigModifiers.filter(m => m.pluginId !== pluginId);
+
+    // 清理插槽注册
+    this.state.slotRegistrations = this.state.slotRegistrations.filter(r => r.pluginId !== pluginId);
+    this.state.actionHandlers = this.state.actionHandlers.filter(h => h.pluginId !== pluginId);
+
+    // 清理模态框
+    this.state.modals.forEach((modal, modalId) => {
+      if (modal.pluginId === pluginId) {
+        this.state.modals.delete(modalId);
+        if (this.uiCallbacks.closeModal) {
+          this.uiCallbacks.closeModal(modalId);
+        }
+      }
+    });
+
+    // 清理宿主事件
+    this.state.hostEventHandlers = this.state.hostEventHandlers.filter(h => h.pluginId !== pluginId);
+
+    // 清理游戏属性
+    this.state.gameAttributes.forEach((attr, key) => {
+      if (attr.pluginId === pluginId) {
+        this.state.gameAttributes.delete(key);
+      }
+    });
+
+    // 清理快捷指令
+    this.state.chatCommands.forEach((cmd, name) => {
+      if (cmd.pluginId === pluginId) {
+        this.state.chatCommands.delete(name);
+      }
+    });
+  }
+
+  /** 重置整个运行时 */
+  reset(): void {
+    // 先对所有已加载的插件触发 onUnload 钩子
+    this.state.instances.forEach((instance, pluginId) => {
+      if (instance.enabled) {
+        try {
+          this.triggerHook('onUnload', pluginId);
+        } catch (e) {
+          console.error(`[PluginRuntime] 卸载插件 ${pluginId} 时出错:`, e);
+        }
+      }
+    });
+    // 清理所有插件资源
+    this.resourceTracker.reset();
+    this.state = createRuntimeState();
+    this.pluginStorage = new Map();
+  }
+}
+
+// 单例导出
+let runtimeInstance: PluginRuntimeEngine | null = null;
+
+export function getPluginRuntime(): PluginRuntimeEngine {
+  if (!runtimeInstance) {
+    runtimeInstance = new PluginRuntimeEngine();
+  }
+  return runtimeInstance;
+}
+
+export { PluginRuntimeEngine };