xinyu-pro 0.21.0

package/components/ui/PluginProvider.tsx

@@ -0,0 +1,1038 @@
+// components/ui/PluginProvider.tsx - 插件系统 React Context Provider
+'use client';
+
+import React, { createContext, useContext, useEffect, useState, useCallback, useRef } from 'react';
+import { PluginManifest, PluginBinding, PluginInstance, GameAttribute, ChatCommand, SidebarPanelRegistration, MessageRenderer, UISlotId, SlotRegistration, ModalRegistration, ConfirmOptions, DependencyStatus } from '@/lib/plugin-types';
+import { onPluginBindingChange, PluginBindingChangeEvent, onPluginConfigChange, PluginConfigChangeEvent, broadcastPluginConfigChange } from '@/lib/plugin-events';
+
+/** 输入框控制 API 类型 */
+interface InputControlAPI {
+  getContent: () => string | null;
+  setContent: (text: string) => void;
+  appendContent: (text: string) => void;
+  clearContent: () => void;
+  setPlaceholder: (text: string) => void;
+  setDisabled: (disabled: boolean) => void;
+  focus: () => void;
+  blur: () => void;
+  setStyle: (style: Record<string, string>) => void;
+  injectStyle: (css: string) => string;
+  removeStyle: (styleId: string) => void;
+  onInput: (handler: (value: string) => void) => () => void;
+  onSend: (handler: (content: string) => void) => () => void;
+  onKeyDown: (handler: (event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void) => () => void;
+  getSelection: () => { start: number; end: number; text: string } | null;
+  setSelection: (start: number, end: number) => void;
+  insertAtCursor: (text: string) => void;
+  setMaxLength: (length: number) => void;
+  getLength: () => number;
+}
+
+/** PluginProvider Context 值 */
+interface PluginContextValue {
+  /** 所有已加载的插件 */
+  plugins: PluginInstance[];
+  /** 已启用的插件 */
+  enabledPlugins: PluginInstance[];
+  /** 游戏属性 */
+  attributes: GameAttribute[];
+  /** 快捷指令 */
+  commands: ChatCommand[];
+  /** 侧边栏面板 */
+  sidebarPanels: SidebarPanelRegistration[];
+  /** 消息渲染器 */
+  messageRenderers: MessageRenderer[];
+  /** 执行 onRenderMessage 管道（多个插件依次修改消息内容，返回 null 表示跳过渲染，支持 async handler） */
+  applyRenderMessagePipeline: (message: { role: string; content: string }) => Promise<string | null>;
+  /** 游戏状态 */
+  gameState: Record<string, unknown>;
+  /** 设置游戏状态 */
+  setGameState: (partial: Record<string, unknown>) => void;
+  /** 重置游戏状态 */
+  resetGameState: () => void;
+  /** 注册快捷指令（供外部组件使用） */
+  registerCommand: (cmd: ChatCommand) => void;
+  /** 执行快捷指令 */
+  executeCommand: (rawInput: string) => Promise<string | void>;
+  /** 插入系统消息回调 */
+  onInsertSystemMessage?: (content: string, metadata?: Record<string, unknown>) => void;
+  /** 设置插入系统消息回调 */
+  setInsertSystemMessageCallback: (cb: (content: string, metadata?: Record<string, unknown>) => void) => void;
+  /** 插入通知消息回调（不发给 AI，持久化到聊天记录） */
+  onInsertNotice?: (html: string) => void;
+  /** 设置插入通知消息回调 */
+  setInsertNoticeCallback: (cb: (html: string) => void) => void;
+  /** Toast 通知回调 */
+  onToast?: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => void;
+  /** 设置 Toast 回调 */
+  setToastCallback: (cb: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => void) => void;
+  /** Confirm 对话框回调 */
+  onConfirm?: (title: string, message: string, options?: ConfirmOptions) => Promise<boolean>;
+  /** 设置 Confirm 回调 */
+  setConfirmCallback: (cb: (title: string, message: string, options?: ConfirmOptions) => Promise<boolean>) => void;
+  /** 发送消息回调 */
+  onSendMessage?: (content: string) => Promise<void>;
+  /** 设置发送消息回调 */
+  setSendMessageCallback: (cb: (content: string) => Promise<void>) => void;
+  /** 获取消息列表回调 */
+  onGetMessages?: () => { role: string; content: string }[];
+  /** 设置获取消息列表回调 */
+  setGetMessagesCallback: (cb: () => { role: string; content: string }[]) => void;
+  /** 获取世界设定回调 */
+  onGetWorldSetting?: () => Record<string, unknown>;
+  /** 设置获取世界设定回调 */
+  setGetWorldSettingCallback: (cb: () => Record<string, unknown>) => void;
+  /** 设置世界设定回调 */
+  onSetWorldSetting?: (data: Record<string, unknown>) => void;
+  /** 设置设置世界设定回调 */
+  setSetWorldSettingCallback: (cb: (data: Record<string, unknown>) => void) => void;
+  /** 获取会话 ID 回调 */
+  onGetSessionId?: () => string;
+  /** 设置获取会话 ID 回调 */
+  setGetSessionIdCallback: (cb: () => string) => void;
+  /** 设置输入框元素回调（由 GamePage 调用，传入 textarea 元素） */
+  setInputElementCallback: (cb: (el: HTMLTextAreaElement | null) => void) => void;
+  /** 输入框控制 API */
+  inputControl: InputControlAPI;
+  /** 重新加载所有插件 */
+  reloadPlugins: () => Promise<void>;
+  /** 重新加载单个插件（不影响其他插件） */
+  reloadSinglePlugin: (pluginId: string, bindingOverride?: PluginBinding) => Promise<void>;
+  /** 直接更新插件 binding 并 reload（不重新 fetch DB，最可靠的路径） */
+  updateAndReload: (pluginId: string, newBinding: PluginBinding) => Promise<void>;
+  /** 轻量级更新插件运行时配置（触发 onConfigChange hook + 持久化 + 广播） */
+  updatePluginConfig: (pluginId: string, config: Record<string, unknown>, options?: { persist?: boolean; broadcast?: boolean; triggerHook?: boolean }) => void;
+  /** 刷新 UI 状态（不重新加载插件，只从 runtime 同步到 React state） */
+  refreshUI: () => void;
+  /** 更新 toast 设置（设置页保存时调用） */
+  updateToastSettings: (enabled: boolean, levels: string[]) => void;
+  /** 是否已初始化 */
+  initialized: boolean;
+  /** 获取指定插槽的注册内容 */
+  getSlotRegistrations: (slotId: UISlotId) => SlotRegistration[];
+  /** slot 版本号，变化时触发 re-render */
+  slotVersion: number;
+  /** 所有模态框 */
+  modals: ModalRegistration[];
+  /** 关闭模态框 */
+  closeModal: (modalId: string) => void;
+  /** 更新模态框内容/样式（不关闭重开） */
+  updateModal: (modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }) => void;
+  /** 触发游戏初始化钩子（进入游戏且无聊天记录时调用，支持 async handler） */
+  triggerGameInit: () => Promise<void>;
+  /** 触发插件绑定世界钩子（支持 async handler） */
+  triggerPluginBindingWorld: (worldId: string) => Promise<void>;
+  /** 所有插件的依赖状态 */
+  dependencyStatus: Map<string, DependencyStatus[]>;
+  /** 权限冲突信息 */
+  permissionConflicts: Array<{
+    manifest: PluginManifest;
+    conflicts: Array<{
+      permission: string;
+      conflictingPluginId: string;
+      conflictingPluginName: string;
+      conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+    }>;
+    missingRequired: string[];
+  }>;
+  /** 解决权限冲突（移除权限或禁用插件） */
+  resolvePermissionConflict: (conflictingPluginId: string, permission: string, action: 'remove-permission' | 'disable-plugin') => Promise<void>;
+  /** 关闭权限冲突弹窗 */
+  dismissPermissionConflicts: () => void;
+}
+
+/** 创建空操作的 inputControl 默认值 */
+function createDefaultInputControl(): InputControlAPI {
+  return {
+    getContent: () => null,
+    setContent: () => {},
+    appendContent: () => {},
+    clearContent: () => {},
+    setPlaceholder: () => {},
+    setDisabled: () => {},
+    focus: () => {},
+    blur: () => {},
+    setStyle: () => {},
+    injectStyle: () => '',
+    removeStyle: () => {},
+    onInput: () => () => {},
+    onSend: () => () => {},
+    onKeyDown: () => () => {},
+    getSelection: () => null,
+    setSelection: () => {},
+    insertAtCursor: () => {},
+    setMaxLength: () => {},
+    getLength: () => 0,
+  };
+}
+
+/** 创建安全的默认上下文值（SSR 或无 Provider 时使用） */
+function createDefaultContext(): PluginContextValue {
+  return {
+    plugins: [],
+    enabledPlugins: [],
+    attributes: [],
+    commands: [],
+    sidebarPanels: [],
+    messageRenderers: [],
+    applyRenderMessagePipeline: async (msg) => msg.content,
+    gameState: {},
+    setGameState: () => {},
+    resetGameState: () => {},
+    registerCommand: () => {},
+    executeCommand: async () => undefined,
+    setInsertSystemMessageCallback: () => {},
+    setInsertNoticeCallback: () => {},
+    setToastCallback: () => {},
+    setConfirmCallback: () => {},
+    setSendMessageCallback: () => {},
+    setGetMessagesCallback: () => {},
+    setGetWorldSettingCallback: () => {},
+    setGetSessionIdCallback: () => {},
+    setInputElementCallback: () => {},
+    inputControl: createDefaultInputControl(),
+    reloadPlugins: async () => {},
+    reloadSinglePlugin: async () => {},
+    updateAndReload: async () => {},
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    updatePluginConfig: (_pluginId: string, _config: Record<string, unknown>, _options?: { persist?: boolean; broadcast?: boolean; triggerHook?: boolean }) => {},
+    refreshUI: () => {},
+    updateToastSettings: () => {},
+    initialized: false,
+    getSlotRegistrations: () => [],
+    slotVersion: 0,
+    modals: [],
+    closeModal: () => {},
+    updateModal: () => {},
+    triggerGameInit: async () => {},
+    triggerPluginBindingWorld: async () => {},
+    dependencyStatus: new Map(),
+    permissionConflicts: [],
+    resolvePermissionConflict: async () => {},
+    dismissPermissionConflicts: () => {},
+  };
+}
+
+const PluginContext = createContext<PluginContextValue>(createDefaultContext());
+
+export function usePluginContext(): PluginContextValue {
+  return useContext(PluginContext);
+}
+
+interface PluginProviderProps {
+  children: React.ReactNode;
+  worldId?: string;
+}
+
+export function PluginProvider({ children, worldId }: PluginProviderProps) {
+  const [plugins, setPlugins] = useState<PluginInstance[]>([]);
+  const [attributes, setAttributes] = useState<GameAttribute[]>([]);
+  const [commands, setCommands] = useState<ChatCommand[]>([]);
+  const [sidebarPanels, setSidebarPanels] = useState<SidebarPanelRegistration[]>([]);
+  const [messageRenderers, setMessageRenderers] = useState<MessageRenderer[]>([]);
+  const [gameState, setGameStateInternal] = useState<Record<string, unknown>>({});
+  const [initialized, setInitialized] = useState(false);
+  const loadingRef = useRef(false);
+  const initializedRef = useRef(false);
+  // 用 ref 追踪 worldId，避免 loadPlugins 因 worldId 变化而重建导致重复触发
+  const worldIdRef = useRef(worldId);
+  worldIdRef.current = worldId;
+  // 新增：模态框状态
+  const [modals, setModals] = useState<ModalRegistration[]>([]);
+  // 新增：依赖状态
+  const [dependencyStatus, setDependencyStatus] = useState<Map<string, DependencyStatus[]>>(new Map());
+  // 新增：slot 版本号，变化时触发使用 getSlotRegistrations 的组件 re-render
+  const [slotVersion, setSlotVersion] = useState(0);
+  // 新增：权限冲突信息
+  const [permissionConflicts, setPermissionConflicts] = useState<Array<{
+    manifest: PluginManifest;
+    conflicts: Array<{
+      permission: string;
+      conflictingPluginId: string;
+      conflictingPluginName: string;
+      conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+    }>;
+    missingRequired: string[];
+  }>>([]);
+
+  const runtimeRef = useRef<import('@/lib/plugin-runtime').PluginRuntimeEngine | null>(null);
+  const insertSystemMessageRef = useRef<((content: string, metadata?: Record<string, unknown>) => void) | undefined>();
+  const insertNoticeRef = useRef<(html: string) => void | undefined>();
+  const toastRef = useRef<((message: string, type?: 'info' | 'success' | 'warning' | 'error') => void) | undefined>();
+  const toastSettingsRef = useRef<{ enabled: boolean; levels: string[] }>({ enabled: true, levels: ['info', 'success', 'warning', 'error'] });
+  const confirmRef = useRef<((title: string, message: string, options?: ConfirmOptions) => Promise<boolean>) | undefined>();
+  const sendMessageRef = useRef<((content: string) => Promise<void>) | undefined>();
+  const getMessagesRef = useRef<(() => { role: string; content: string }[]) | undefined>();
+  const getWorldSettingRef = useRef<(() => Record<string, unknown>) | undefined>();
+  const setWorldSettingRef = useRef<((data: Record<string, unknown>) => void) | undefined>();
+  const getSessionIdRef = useRef<(() => string) | undefined>();
+
+  // 输入框元素引用
+  const inputElementRef = useRef<HTMLTextAreaElement | null>(null);
+  // 输入框事件监听器
+  const inputListenersRef = useRef<Array<(value: string) => void>>([]);
+  const sendListenersRef = useRef<Array<(content: string) => void>>([]);
+  const keyDownListenersRef = useRef<Array<(event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void>>([]);
+  // 注入的样式 ID 计数器
+  const inputStyleCounterRef = useRef(0);
+
+  const setInsertSystemMessageCallback = useCallback((cb: (content: string, metadata?: Record<string, unknown>) => void) => {
+    insertSystemMessageRef.current = cb;
+  }, []);
+
+  const setInsertNoticeCallback = useCallback((cb: (html: string) => void) => {
+    insertNoticeRef.current = cb;
+  }, []);
+
+  const setToastCallback = useCallback((cb: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => void) => {
+    toastRef.current = cb;
+  }, []);
+
+  const setConfirmCallback = useCallback((cb: (title: string, message: string, options?: ConfirmOptions) => Promise<boolean>) => {
+    confirmRef.current = cb;
+  }, []);
+
+  const setSendMessageCallback = useCallback((cb: (content: string) => Promise<void>) => {
+    sendMessageRef.current = cb;
+  }, []);
+
+  const setGetMessagesCallback = useCallback((cb: () => { role: string; content: string }[]) => {
+    getMessagesRef.current = cb;
+  }, []);
+
+  const setGetWorldSettingCallback = useCallback((cb: () => Record<string, unknown>) => {
+    getWorldSettingRef.current = cb;
+  }, []);
+
+  const setSetWorldSettingCallback = useCallback((cb: (data: Record<string, unknown>) => void) => {
+    setWorldSettingRef.current = cb;
+  }, []);
+
+  const setGetSessionIdCallback = useCallback((cb: () => string) => {
+    getSessionIdRef.current = cb;
+  }, []);
+
+  /** 设置输入框元素回调（由 GamePage 调用） */
+  const setInputElementCallback = useCallback((cb: (el: HTMLTextAreaElement | null) => void) => {
+    // 先调用回调设置当前元素
+    cb(inputElementRef.current);
+    // 保存回调以便后续元素变化时通知
+    // （实际上我们直接用 ref，这里 cb 会被立即调用一次）
+  }, []);
+
+  /** 输入框控制 API 实现 */
+  const inputControl: InputControlAPI = {
+    getContent: () => {
+      return inputElementRef.current?.value ?? null;
+    },
+    setContent: (text: string) => {
+      if (!inputElementRef.current) return;
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+      if (nativeInputValueSetter) {
+        nativeInputValueSetter.call(inputElementRef.current, text);
+      } else {
+        inputElementRef.current.value = text;
+      }
+      inputElementRef.current.dispatchEvent(new Event('input', { bubbles: true }));
+    },
+    appendContent: (text: string) => {
+      const el = inputElementRef.current;
+      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: () => {
+      if (!inputElementRef.current) return;
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+      if (nativeInputValueSetter) {
+        nativeInputValueSetter.call(inputElementRef.current, '');
+      } else {
+        inputElementRef.current.value = '';
+      }
+      inputElementRef.current.dispatchEvent(new Event('input', { bubbles: true }));
+    },
+    setPlaceholder: (text: string) => {
+      if (!inputElementRef.current) return;
+      inputElementRef.current.placeholder = text;
+    },
+    setDisabled: (disabled: boolean) => {
+      if (!inputElementRef.current) return;
+      inputElementRef.current.disabled = disabled;
+    },
+    focus: () => {
+      inputElementRef.current?.focus();
+    },
+    blur: () => {
+      inputElementRef.current?.blur();
+    },
+    setStyle: (style: Record<string, string>) => {
+      if (!inputElementRef.current) return;
+      Object.assign(inputElementRef.current.style, style);
+    },
+    injectStyle: (css: string) => {
+      const styleId = `xinyu-input-style-${++inputStyleCounterRef.current}`;
+      const styleEl = document.createElement('style');
+      styleEl.id = styleId;
+      styleEl.textContent = css.replace(/#xinyu-chat-input/g, `#xinyu-chat-input`);
+      document.head.appendChild(styleEl);
+      return styleId;
+    },
+    removeStyle: (styleId: string) => {
+      const el = document.getElementById(styleId);
+      if (el) el.remove();
+    },
+    onInput: (handler: (value: string) => void) => {
+      inputListenersRef.current.push(handler);
+      return () => {
+        inputListenersRef.current = inputListenersRef.current.filter(h => h !== handler);
+      };
+    },
+    onSend: (handler: (content: string) => void) => {
+      sendListenersRef.current.push(handler);
+      return () => {
+        sendListenersRef.current = sendListenersRef.current.filter(h => h !== handler);
+      };
+    },
+    onKeyDown: (handler: (event: { key: string; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void) => {
+      keyDownListenersRef.current.push(handler);
+      return () => {
+        keyDownListenersRef.current = keyDownListenersRef.current.filter(h => h !== handler);
+      };
+    },
+    getSelection: () => {
+      const el = inputElementRef.current;
+      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) => {
+      if (!inputElementRef.current) return;
+      inputElementRef.current.setSelectionRange(start, end);
+    },
+    insertAtCursor: (text: string) => {
+      const el = inputElementRef.current;
+      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) => {
+      if (!inputElementRef.current) return;
+      inputElementRef.current.maxLength = length;
+    },
+    getLength: () => {
+      return inputElementRef.current?.value.length ?? 0;
+    },
+  };
+
+  /** 加载并初始化所有插件 */
+  const loadPlugins = useCallback(async () => {
+    // 防止并发重入
+    if (loadingRef.current) return;
+    loadingRef.current = true;
+    try {
+      const { getPluginRuntime } = await import('@/lib/plugin-runtime');
+      const runtime = getPluginRuntime();
+      runtimeRef.current = runtime;
+
+      // 重置运行时
+      runtime.reset();
+
+      // 注入 UI 回调（让插件能调用 chat.send、insertSystemMessage、toast 等）
+      runtime.setUICallbacks({
+        sendMessage: async (content: string) => {
+          if (sendMessageRef.current) {
+            await sendMessageRef.current(content);
+          }
+        },
+        insertSystemMessage: (content: string) => {
+          if (insertSystemMessageRef.current) {
+            insertSystemMessageRef.current(content);
+          }
+        },
+        insertNotice: (html: string) => {
+          if (insertNoticeRef.current) {
+            insertNoticeRef.current(html);
+          }
+        },
+        toast: (message: string, type?: 'info' | 'success' | 'warning' | 'error') => {
+          if (toastRef.current) {
+            const { enabled, levels } = toastSettingsRef.current;
+            if (enabled && levels.includes(type || 'info')) {
+              toastRef.current(message, type);
+            }
+          }
+        },
+        // 新增：模态框回调
+        showModal: (modal: ModalRegistration) => {
+          setModals(prev => [...prev, modal]);
+        },
+        closeModal: (modalId: string) => {
+          setModals(prev => prev.filter(m => m.id !== modalId));
+        },
+        updateModal: (modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }) => {
+          setModals(prev => prev.map(m => m.id === modalId ? { ...m, ...options, style: options.style ? options.style as React.CSSProperties : m.style } : m));
+        },
+        confirm: async (title: string, message: string, options?: ConfirmOptions) => {
+          if (confirmRef.current) {
+            return confirmRef.current(title, message, options);
+          }
+          return false;
+        },
+        // 配置变更广播（跨标签页同步）
+        onConfigChange: (pluginId: string, config: Record<string, unknown>) => {
+          broadcastPluginConfigChange({ pluginId, config, worldId: worldIdRef.current || undefined });
+        },
+        // 插槽内容变更时刷新 UI
+        onSlotChange: () => {
+          setSlotVersion(v => v + 1);
+        },
+        // 输入框控制回调
+        inputControl: {
+          setInputElement: (el: HTMLTextAreaElement | null) => {
+            inputElementRef.current = el;
+          },
+          getInputListeners: () => inputListenersRef.current,
+          getSendListeners: () => sendListenersRef.current,
+          getKeyDownListeners: () => keyDownListenersRef.current,
+        },
+        // 游戏数据回调（供插件 xinyu.game API 使用）
+        getWorldSetting: () => getWorldSettingRef.current?.() || {},
+        setWorldSetting: (data: Record<string, unknown>) => setWorldSettingRef.current?.(data),
+        getSessionId: () => getSessionIdRef.current?.() || '',
+        getMessages: () => getMessagesRef.current?.() || [],
+        getWorldId: () => worldIdRef.current,
+      });
+
+      // 设置获取插槽容器的回调
+      runtime.setGetSlotContainerCallback((slotId: UISlotId) => {
+        return document.querySelector(`[data-plugin-slot="${slotId}"]`);
+      });
+
+      // 获取所有插件
+      const pluginsRes = await fetch('/api/plugins');
+      if (!pluginsRes.ok) return;
+      const manifests: PluginManifest[] = await pluginsRes.json();
+
+      // 获取绑定列表（全局 + 当前世界的）
+      const bindingParams = new URLSearchParams();
+      bindingParams.set('scope', 'global');
+      const globalBindingsRes = await fetch(`/api/plugins/bindings?${bindingParams.toString()}`);
+      const globalBindings: PluginBinding[] = globalBindingsRes.ok ? await globalBindingsRes.json() : [];
+
+      let worldBindings: PluginBinding[] = [];
+      if (worldIdRef.current) {
+        const worldBindingParams = new URLSearchParams();
+        worldBindingParams.set('scope', 'world');
+        worldBindingParams.set('worldId', worldIdRef.current);
+        const worldBindingsRes = await fetch(`/api/plugins/bindings?${worldBindingParams.toString()}`);
+        worldBindings = worldBindingsRes.ok ? await worldBindingsRes.json() : [];
+      }
+
+      // 合并绑定：全局禁用优先，全局启用不传播到运行中的游戏
+      // 规则：
+      //   - 全局 enabled=false → 最终结果一定是禁用（局外关闭覆盖局内）
+      //   - 有世界级绑定 → 以世界级绑定为准（局内用户主动操作过）
+      //   - 无世界级绑定 + 有 worldId（运行中的游戏）→ 不加载（全局启用不影响运行中游戏）
+      //   - 无世界级绑定 + 无 worldId（非游戏场景）→ 使用全局默认值
+      const globalBindingMap = new Map<string, PluginBinding>();
+      for (const b of globalBindings) {
+        globalBindingMap.set(b.extensionId, b);
+      }
+      const worldBindingMap = new Map<string, PluginBinding>();
+      for (const b of worldBindings) {
+        worldBindingMap.set(b.extensionId, b);
+      }
+
+      const effectiveBindings = new Map<string, PluginBinding>();
+      for (const manifest of manifests) {
+        const global = globalBindingMap.get(manifest.id);
+        const world = worldBindingMap.get(manifest.id);
+
+        // 全局禁用 → 强制禁用（无论世界级设置如何）
+        if (global && !global.enabled) {
+          effectiveBindings.set(manifest.id, global);
+          continue;
+        }
+
+        // 有世界级绑定 → 以世界级为准
+        if (world) {
+          effectiveBindings.set(manifest.id, world);
+          continue;
+        }
+
+        // 无世界级绑定
+        if (worldIdRef.current) {
+          // 运行中的游戏：全局启用不传播，只有用户在游戏内主动启用才生效
+          // 不添加到 effectiveBindings → 该插件不会被加载
+        } else {
+          // 非游戏场景（如 extensions 页面）：使用全局默认值
+          if (global) {
+            effectiveBindings.set(manifest.id, global);
+          }
+        }
+      }
+
+      // 加载每个插件（按拓扑排序，被依赖的先加载）
+      const sortedManifests = runtime.getLoadOrder(manifests);
+      const allConflicts: Array<{
+        manifest: PluginManifest;
+        conflicts: Array<{
+          permission: string;
+          conflictingPluginId: string;
+          conflictingPluginName: string;
+          conflictType: 'exclusive-vs-any' | 'common-vs-exclusive';
+        }>;
+        missingRequired: string[];
+      }> = [];
+
+      for (const manifest of sortedManifests) {
+        const binding = effectiveBindings.get(manifest.id);
+        if (binding) {
+          const result = runtime.loadPlugin(manifest, binding);
+          if (!result.success) {
+            allConflicts.push({
+              manifest,
+              conflicts: result.conflicts,
+              missingRequired: result.missingRequired,
+            });
+          } else if (binding.scope === 'world' && binding.worldId) {
+            // 插件被绑定到世界时触发 onPluginBindingWorld 钩子
+            runtime.triggerPluginBindingWorld(binding.worldId);
+          }
+        }
+      }
+
+      // 处理冲突：弹出 toast + 显示冲突弹窗
+      for (const conflict of allConflicts) {
+        if (conflict.conflicts.length > 0) {
+          const conflictPerms = Array.from(new Set(conflict.conflicts.map(c => c.permission))).join(', ');
+          toastRef.current?.(
+            `插件 "${conflict.manifest.name}" 启动失败：权限冲突 (${conflictPerms})`,
+            'warning'
+          );
+        }
+        if (conflict.missingRequired.length > 0) {
+          toastRef.current?.(
+            `插件 "${conflict.manifest.name}" 启动失败：必要权限未声明 (${conflict.missingRequired.join(', ')})`,
+            'warning'
+          );
+        }
+      }
+      if (allConflicts.length > 0) {
+        setPermissionConflicts(allConflicts);
+      }
+
+      // 更新状态
+      setPlugins(runtime.getInstances());
+      setAttributes(runtime.getAttributes());
+      setCommands(runtime.getCommands());
+      setSidebarPanels(runtime.getSidebarPanels());
+      setMessageRenderers(runtime.getMessageRenderers());
+      setModals(runtime.getModals());
+      setDependencyStatus(runtime.getDependencyStatus());
+      setInitialized(true);
+    } catch (e) {
+      console.error('[PluginProvider] 加载插件失败:', e);
+      setInitialized(true);
+    } finally {
+      loadingRef.current = false;
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /** 重新加载所有插件 */
+  const reloadPlugins = useCallback(async () => {
+    await loadPlugins();
+  }, [loadPlugins]);
+
+  /** 刷新 UI 状态（不重新加载插件，只从 runtime 同步到 React state） */
+  const refreshUI = useCallback(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+    setPlugins(runtime.getInstances());
+    setAttributes(runtime.getAttributes());
+    setCommands(runtime.getCommands());
+    setSidebarPanels(runtime.getSidebarPanels());
+    setMessageRenderers(runtime.getMessageRenderers());
+    setModals(runtime.getModals());
+    setDependencyStatus(runtime.getDependencyStatus());
+    setSlotVersion(v => v + 1);
+  }, []);
+
+  /** 重新加载单个插件（不影响其他插件） */
+  const reloadSinglePlugin = useCallback(async (pluginId: string, bindingOverride?: PluginBinding) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+
+    // 1. 卸载旧实例
+    runtime.unloadPlugin(pluginId);
+
+    // 2. 立即更新 UI 状态（卸载后 UI 应立即消失）
+    setPlugins(runtime.getInstances());
+    setAttributes(runtime.getAttributes());
+    setCommands(runtime.getCommands());
+    setSidebarPanels(runtime.getSidebarPanels());
+    setMessageRenderers(runtime.getMessageRenderers());
+    setModals(runtime.getModals());
+    setDependencyStatus(runtime.getDependencyStatus());
+    setSlotVersion(v => v + 1);
+
+    // 3. 如果提供了 bindingOverride，直接使用；否则从 DB 获取
+    try {
+      let manifest: PluginManifest | undefined;
+      let binding: PluginBinding | undefined = bindingOverride;
+
+      if (!binding) {
+        // 从 DB 获取绑定
+        const pluginRes = await fetch('/api/plugins');
+        const allPlugins: PluginManifest[] = pluginRes.ok ? await pluginRes.json() : [];
+        manifest = allPlugins.find(p => p.id === pluginId);
+        if (!manifest) return;
+
+        if (worldIdRef.current) {
+          const params = new URLSearchParams({ scope: 'world', worldId: worldIdRef.current });
+          const worldRes = await fetch(`/api/plugins/bindings?${params}`);
+          const worldBindings: PluginBinding[] = worldRes.ok ? await worldRes.json() : [];
+          const worldBinding = worldBindings.find(b => b.extensionId === pluginId);
+          const globalRes = await fetch('/api/plugins/bindings?scope=global');
+          const globalBindings: PluginBinding[] = globalRes.ok ? await globalRes.json() : [];
+          const globalBinding = globalBindings.find(b => b.extensionId === pluginId);
+          if (globalBinding && !globalBinding.enabled) {
+            return;
+          } else if (worldBinding && worldBinding.enabled) {
+            binding = worldBinding;
+          }
+        } else {
+          const globalRes = await fetch('/api/plugins/bindings?scope=global');
+          const globalBindings: PluginBinding[] = globalRes.ok ? await globalRes.json() : [];
+          binding = globalBindings.find(b => b.extensionId === pluginId);
+        }
+      } else {
+        // 从所有插件中找到 manifest
+        const pluginRes = await fetch('/api/plugins');
+        const allPlugins: PluginManifest[] = pluginRes.ok ? await pluginRes.json() : [];
+        manifest = allPlugins.find(p => p.id === pluginId);
+        if (!manifest) return;
+      }
+
+      // 如果有有效绑定且启用，重新加载
+      if (binding && binding.enabled) {
+        runtime.loadPlugin(manifest!, binding);
+        setPlugins(runtime.getInstances());
+        setAttributes(runtime.getAttributes());
+        setCommands(runtime.getCommands());
+        setSidebarPanels(runtime.getSidebarPanels());
+        setMessageRenderers(runtime.getMessageRenderers());
+        setModals(runtime.getModals());
+        setDependencyStatus(runtime.getDependencyStatus());
+        setSlotVersion(v => v + 1);
+      }
+    } catch (e) {
+      console.error(`[PluginProvider] 重新加载插件 ${pluginId} 失败:`, e);
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  /** 直接更新插件 binding 并 reload（不重新 fetch DB，最可靠的路径） */
+  const updateAndReload = useCallback(async (pluginId: string, newBinding: PluginBinding) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+
+    // 1. 卸载旧实例
+    runtime.unloadPlugin(pluginId);
+
+    // 2. 更新 UI（卸载后立即消失）
+    setPlugins(runtime.getInstances());
+    setAttributes(runtime.getAttributes());
+    setCommands(runtime.getCommands());
+    setSidebarPanels(runtime.getSidebarPanels());
+    setMessageRenderers(runtime.getMessageRenderers());
+    setModals(runtime.getModals());
+    setDependencyStatus(runtime.getDependencyStatus());
+    setSlotVersion(v => v + 1);
+
+    // 3. 获取 manifest 并加载
+    try {
+      const pluginRes = await fetch('/api/plugins');
+      const allPlugins: PluginManifest[] = pluginRes.ok ? await pluginRes.json() : [];
+      const manifest = allPlugins.find(p => p.id === pluginId);
+      if (!manifest) {
+        console.error(`[PluginProvider] updateAndReload: 找不到插件 ${pluginId} 的 manifest`);
+        return;
+      }
+
+      if (newBinding.enabled) {
+        runtime.loadPlugin(manifest, newBinding);
+        setPlugins(runtime.getInstances());
+        setAttributes(runtime.getAttributes());
+        setCommands(runtime.getCommands());
+        setSidebarPanels(runtime.getSidebarPanels());
+        setMessageRenderers(runtime.getMessageRenderers());
+        setModals(runtime.getModals());
+        setDependencyStatus(runtime.getDependencyStatus());
+        setSlotVersion(v => v + 1);
+      }
+    } catch (e) {
+      console.error(`[PluginProvider] updateAndReload 失败:`, e);
+    }
+  }, []);
+
+  /** 轻量级更新插件运行时配置（触发 onConfigChange hook + 持久化 + 广播） */
+  const updatePluginConfig = useCallback((pluginId: string, config: Record<string, unknown>, options?: { persist?: boolean; broadcast?: boolean; triggerHook?: boolean }) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) return;
+    runtime.updatePluginConfig(pluginId, config, options);
+  }, []);
+
+  /** 更新 toast 设置（设置页保存时调用） */
+  const updateToastSettings = useCallback((enabled: boolean, levels: string[]) => {
+    toastSettingsRef.current = { enabled, levels };
+  }, []);
+
+  // 初始化时从 API 加载 toast 设置
+  useEffect(() => {
+    fetch('/api/settings')
+      .then(res => res.ok ? res.json() : null)
+      .then(data => {
+        if (data) {
+          toastSettingsRef.current = {
+            enabled: data.pluginToastEnabled !== false,
+            levels: data.pluginToastLevels || ['info', 'success', 'warning', 'error'],
+          };
+        }
+      })
+      .catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    if (initializedRef.current) return;
+    initializedRef.current = true;
+    loadPlugins();
+  }, [loadPlugins]);
+
+  // 监听跨标签页插件绑定变更（设置页禁用插件时实时同步到游戏页）
+  useEffect(() => {
+    const unsubscribe = onPluginBindingChange((event: PluginBindingChangeEvent) => {
+      if (event.source === 'global' && !event.enabled && worldIdRef.current) {
+        console.log(`[PluginProvider] 收到全局禁用指令: ${event.pluginId}，重新加载插件`);
+        loadPlugins();
+      }
+    });
+    return unsubscribe;
+  }, [loadPlugins]);
+
+  // 监听跨标签页插件配置变更
+  useEffect(() => {
+    const unsubscribe = onPluginConfigChange((event: PluginConfigChangeEvent) => {
+      if (event.worldId === worldIdRef.current) {
+        const runtime = runtimeRef.current;
+        if (!runtime) return;
+        // 跨标签页配置变更：仅更新内存，不持久化（其他标签页已持久化），不广播（避免循环）
+        runtime.updatePluginConfig(event.pluginId, event.config, {
+          persist: false,
+          broadcast: false,
+        });
+      }
+    });
+    return unsubscribe;
+  }, []);
+
+  const setGameState = useCallback((partial: Record<string, unknown>) => {
+    setGameStateInternal(prev => {
+      const next = { ...prev, ...partial };
+      runtimeRef.current?.setGameState(next);
+      return next;
+    });
+  }, []);
+
+  const resetGameState = useCallback(() => {
+    setGameStateInternal({});
+    runtimeRef.current?.resetGameState();
+    // 重新获取属性
+    if (runtimeRef.current) {
+      setAttributes(runtimeRef.current.getAttributes());
+    }
+  }, []);
+
+  const registerCommand = useCallback((cmd: ChatCommand) => {
+    setCommands(prev => {
+      const exists = prev.find(c => c.name === cmd.name);
+      if (exists) return prev;
+      return [...prev, cmd];
+    });
+  }, []);
+
+  const executeCommand = useCallback(async (rawInput: string): Promise<string | void> => {
+    if (!runtimeRef.current) return undefined;
+    return runtimeRef.current.executeCommand(rawInput);
+  }, []);
+
+  /** 获取指定插槽的注册内容 */
+  const getSlotRegistrations = useCallback((slotId: UISlotId): SlotRegistration[] => {
+    if (!runtimeRef.current) return [];
+    return runtimeRef.current.getSlotRegistrations(slotId);
+  }, []);
+
+  /** 关闭模态框 */
+  const closeModal = useCallback((modalId: string) => {
+    if (runtimeRef.current) {
+      runtimeRef.current.closeModal(modalId);
+    }
+    setModals(prev => prev.filter(m => m.id !== modalId));
+  }, []);
+
+  /** 触发游戏初始化钩子 */
+  const triggerGameInit = useCallback(async () => {
+    if (runtimeRef.current) {
+      await runtimeRef.current.triggerGameInit();
+    }
+  }, []);
+
+  /** 触发插件绑定世界钩子 */
+  const triggerPluginBindingWorld = useCallback(async (worldId: string) => {
+    if (runtimeRef.current) {
+      await runtimeRef.current.triggerPluginBindingWorld(worldId);
+    }
+  }, []);
+
+  const enabledPlugins = plugins.filter(p => p.enabled);
+
+  const value: PluginContextValue = {
+    plugins,
+    enabledPlugins,
+    attributes,
+    commands,
+    sidebarPanels,
+    messageRenderers,
+    applyRenderMessagePipeline: (message: { role: string; content: string }) => runtimeRef.current?.applyRenderMessagePipeline(message) ?? Promise.resolve(message.content),
+    gameState,
+    setGameState,
+    resetGameState,
+    registerCommand,
+    executeCommand,
+    onInsertSystemMessage: insertSystemMessageRef.current,
+    setInsertSystemMessageCallback,
+    onInsertNotice: insertNoticeRef.current,
+    setInsertNoticeCallback,
+    onToast: toastRef.current,
+    setToastCallback,
+    onConfirm: confirmRef.current,
+    setConfirmCallback,
+    onSendMessage: sendMessageRef.current,
+    setSendMessageCallback,
+    onGetMessages: getMessagesRef.current,
+    setGetMessagesCallback,
+    onGetWorldSetting: getWorldSettingRef.current,
+    setGetWorldSettingCallback,
+    onSetWorldSetting: setWorldSettingRef.current,
+    setSetWorldSettingCallback,
+    onGetSessionId: getSessionIdRef.current,
+    setGetSessionIdCallback,
+    setInputElementCallback,
+    inputControl,
+    reloadPlugins,
+    reloadSinglePlugin,
+    updateAndReload,
+    updatePluginConfig,
+    refreshUI,
+    updateToastSettings,
+    initialized,
+    getSlotRegistrations,
+    slotVersion,
+    modals,
+    closeModal,
+    updateModal: (modalId: string, options: { title?: string; content?: string; width?: string; style?: Record<string, unknown> }) => {
+      const runtime = runtimeRef.current;
+      if (runtime) runtime.updateModal(modalId, options);
+    },
+    triggerGameInit,
+    triggerPluginBindingWorld,
+    dependencyStatus,
+    permissionConflicts,
+    resolvePermissionConflict: async (conflictingPluginId: string, permission: string, action: 'remove-permission' | 'disable-plugin') => {
+      const runtime = runtimeRef.current;
+      if (!runtime) return;
+
+      if (action === 'disable-plugin') {
+        // 禁用冲突插件
+        await fetch('/api/plugins/bindings', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ extensionId: conflictingPluginId, scope: 'global', enabled: false }),
+        });
+        runtime.unloadPlugin(conflictingPluginId);
+      } else if (action === 'remove-permission') {
+        // 从冲突插件中移除该权限
+        runtime.removePluginPermission(conflictingPluginId, permission);
+        // 更新数据库中的 manifest
+        const instance = runtime.getInstances().find(i => i.manifest.id === conflictingPluginId);
+        if (instance) {
+          const manifest = instance.manifest;
+          const updatePerms = (perms: string[] | undefined) => (perms || []).filter(p => p !== permission);
+          await fetch('/api/plugins', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              id: conflictingPluginId,
+              commonPermissions: updatePerms(manifest.commonPermissions),
+              exclusivePermissions: updatePerms(manifest.exclusivePermissions),
+            }),
+          });
+          // 更新内存中的 manifest
+          manifest.commonPermissions = updatePerms(manifest.commonPermissions) as typeof manifest.commonPermissions;
+          manifest.exclusivePermissions = updatePerms(manifest.exclusivePermissions) as typeof manifest.exclusivePermissions;
+        }
+      }
+
+      // 从冲突列表中移除已解决的项
+      setPermissionConflicts(prev => {
+        const next = prev.map(c => ({
+          ...c,
+          conflicts: c.conflicts.filter(cf => !(cf.conflictingPluginId === conflictingPluginId && cf.permission === permission)),
+          missingRequired: c.missingRequired,
+        })).filter(c => c.conflicts.length > 0 || c.missingRequired.length > 0);
+
+        // 如果所有冲突都解决了，尝试重新加载失败的插件
+        if (next.length === 0 && prev.length > 0) {
+          // 延迟执行，让 UI 先更新
+          setTimeout(() => {
+            reloadPlugins();
+          }, 300);
+        }
+
+        return next;
+      });
+    },
+    dismissPermissionConflicts: () => setPermissionConflicts([]),
+  };
+
+  return (
+    <PluginContext.Provider value={value}>
+      {children}
+    </PluginContext.Provider>
+  );
+}