foliko 1.0.75 → 1.0.76

package/src/core/plugin-manager.js

@@ -1,863 +1,863 @@
-/**
- * PluginManager 插件管理器
- * 负责插件的加载、卸载、重载
- *
- * @module PluginManager
- * @requires ./plugin-base
- */
-
-const { Plugin } = require('./plugin-base');
-const { logger } = require('../utils/logger');
-const { PluginError, PluginNotFoundError } = require('../utils/error');
-const { safeJsonParse } = require('../utils');
-const { resolvePluginPath, scanPluginNames } = require('../utils/plugin-helpers');
-const fs = require('fs');
-const path = require('path');
-
-class PluginManager {
-  /**
-   * @param {Framework} framework - 框架实例
-   */
-  constructor(framework) {
-    this.framework = framework;
-    this._plugins = new Map();
-    this._loading = false;
-    this._stateFile = path.join(process.cwd(), '.agent', 'data', 'plugins-state.json');
-    this._knownPlugins = new Set(); // 已知插件列表（包括未加载的）
-
-    // 创建子日志器
-    this._log = logger.child('plugin-manager');
-
-    // 事件描述注册表（供 Ambient Agent 使用）
-    this._eventDescriptions = new Map();
-
-    // 状态缓存（加载后保持，避免重复读文件）
-    this._stateCache = null;
-
-    // 注册默认事件描述
-    this._registerDefaultEventDescriptions();
-  }
-
-  /**
-   * 注册默认事件描述
-   * @private
-   */
-  _registerDefaultEventDescriptions() {
-    // 这些事件由框架内置组件触发，无需注册
-    // 但为了文档完整性，提供默认描述
-    const defaultDescriptions = {
-      'tool:result': {
-        description: '工具执行结果事件',
-        params: 'name(工具名), args(执行参数), result(执行结果), error(错误信息)',
-        source: 'framework',
-      },
-      'tool:error': {
-        description: '工具执行错误事件',
-        params: 'name(工具名), args(执行参数), error(错误信息)',
-        source: 'framework',
-      },
-      'agent:message': {
-        description: '代理消息事件',
-        params: 'content(消息内容), sessionId(会话ID)',
-        source: 'framework',
-      },
-      'think:thought_completed': {
-        description: '思考完成事件',
-        params: 'mode(思考模式), topic(思考主题), thought(思考内容), depth(思考深度)',
-        source: 'think-plugin',
-      },
-      'email:received': {
-        description: '收到邮件事件',
-        params:
-          'from(发件人), to(收件人), subject(主题), text(正文), body(HTML正文), messageId(消息ID), timestamp(时间戳)',
-        source: 'email-plugin',
-      },
-      'webhook:received': {
-        description: 'Webhook接收事件',
-        params: 'headers(HTTP头), body(请求体), query(查询参数), path(请求路径)',
-        source: 'web-plugin',
-      },
-      'scheduler:reminder': {
-        description: '定时提醒事件',
-        params: 'taskId(任务ID), message(提醒消息), time(触发时间)',
-        source: 'scheduler-plugin',
-      },
-      'scheduler:task_completed': {
-        description: '任务完成事件',
-        params: 'taskId(任务ID), result(任务结果)',
-        source: 'scheduler-plugin',
-      },
-      'scheduler:task_failed': {
-        description: '任务失败事件',
-        params: 'taskId(任务ID), error(错误信息)',
-        source: 'scheduler-plugin',
-      },
-    };
-
-    for (const [eventType, info] of Object.entries(defaultDescriptions)) {
-      this._eventDescriptions.set(eventType, info);
-    }
-  }
-
-  /**
-   * 获取状态文件路径
-   * @private
-   */
-  _getStateFile() {
-    const dir = path.dirname(this._stateFile);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    return this._stateFile;
-  }
-
-  /**
-   * 保存插件状态到文件
-   * 注意：AI 插件配置不保存（从环境变量和命令行获取）
-   * @private
-   */
-  _saveState() {
-    try {
-      const stateFile = this._getStateFile();
-      // 读取现有状态（如果存在），保留原有内容
-      let state = safeJsonParse(
-        fs.existsSync(stateFile) ? fs.readFileSync(stateFile, 'utf-8') : '{}',
-        {}
-      );
-
-      // 合并新状态到现有状态
-      for (const [name, entry] of this._plugins) {
-        // AI 配置不保存，每次从环境变量和命令行获取
-        if (name === 'ai') {
-          state[name] = { enabled: entry.enabled };
-        } else {
-          state[name] = {
-            ...(state[name] || {}), // 保留现有配置
-            enabled: entry.enabled,
-            config: entry.instance?.config || {},
-          };
-        }
-      }
-
-      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
-
-      // 更新缓存
-      this._stateCache = state;
-    } catch (err) {
-      this._log.error('Failed to save state:', err.message);
-    }
-  }
-
-  /**
-   * 加载插件状态从文件（带缓存）
-   * @private
-   * @returns {Object}
-   */
-  _loadState() {
-    // 返回缓存的状态
-    if (this._stateCache !== null) {
-      return this._stateCache;
-    }
-
-    try {
-      const stateFile = this._getStateFile();
-      if (fs.existsSync(stateFile)) {
-        this._stateCache = safeJsonParse(fs.readFileSync(stateFile, 'utf-8'), {});
-        return this._stateCache;
-      }
-    } catch (err) {
-      this._log.error('Failed to load state:', err.message);
-    }
-    this._stateCache = {};
-    return this._stateCache;
-  }
-
-  /**
-   * 注册插件（不加载）
-   * @param {Plugin|Object} plugin - 插件实例或定义
-   * @param {Object} [options] - 注册选项
-   * @returns {PluginManager}
-   * @throws {PluginError} 插件没有名称时抛出
-   */
-  register(plugin, options = {}) {
-    if (!plugin.name) {
-      throw new PluginError('Plugin must have a name');
-    }
-
-    let pluginInstance = plugin;
-    if (!(plugin instanceof Plugin)) {
-      // 从对象创建插件实例
-      pluginInstance = this._createFromObject(plugin);
-    }
-
-    // 加载保存的状态
-    const savedState = this._loadState();
-    const savedEnabled = savedState[pluginInstance.name]?.enabled;
-    const savedConfig = savedState[pluginInstance.name]?.config;
-
-    // 恢复保存的配置到插件实例（AI 插件不恢复配置，从环境变量获取）
-    if (savedConfig && pluginInstance.config && pluginInstance.name !== 'ai') {
-      pluginInstance.config = { ...pluginInstance.config, ...savedConfig };
-    }
-
-    // 系统插件强制启用，不能禁用
-    // 普通插件：state 文件有记录则用 state，否则用插件默认配置
-    let enabled;
-    if (pluginInstance.system) {
-      enabled = true;
-    } else if (savedEnabled !== undefined) {
-      enabled = savedEnabled;
-    } else {
-      enabled = pluginInstance.enabled !== undefined ? pluginInstance.enabled : true;
-    }
-
-    this._plugins.set(pluginInstance.name, {
-      instance: pluginInstance,
-      status: 'registered',
-      enabled,
-    });
-
-    this.framework.emit('plugin:registered', pluginInstance);
-    return this;
-  }
-
-  /**
-   * 加载插件
-   * @param {Plugin|Object} plugin - 插件实例或定义
-   * @param {Object} [options] - 加载选项
-   * @param {boolean} [options.forceEnabled] - 强制启用插件，忽略 state 文件的 disabled 状态
-   * @returns {Promise<Plugin>}
-   * @throws {PluginError} 加载过程中发生错误时抛出
-   */
-  async load(plugin, options = {}) {
-    if (this._loading) {
-      throw new PluginError('Cannot load plugin during another load operation');
-    }
-
-    this._loading = true;
-    try {
-      let pluginInstance = plugin;
-
-      if (!(plugin instanceof Plugin)) {
-        pluginInstance = this._createFromObject(plugin);
-      }
-
-      // 如果已注册，使用已注册的实例和状态
-      const existing = this._plugins.get(pluginInstance.name);
-      if (existing) {
-        pluginInstance = existing.instance;
-
-        // 如果插件被禁用，跳过加载
-        if (!existing.enabled) {
-          this._log.info(`Plugin '${pluginInstance.name}' is disabled`);
-          return pluginInstance;
-        }
-
-        // 如果已加载且已启动，直接返回
-        if (existing.status === 'loaded' && pluginInstance._started) {
-          this._log.warn(`Plugin '${pluginInstance.name}' already loaded`);
-          return pluginInstance;
-        }
-
-        // 如果已加载但未启动（重载场景），直接启动
-        if (existing.status === 'loaded' && !pluginInstance._started) {
-          try {
-            if (typeof pluginInstance.start === 'function') {
-              await pluginInstance.start(this.framework);
-              pluginInstance._started = true;
-            }
-          } catch (err) {
-            this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
-          }
-          this.framework.emit('plugin:loaded', pluginInstance);
-          return pluginInstance;
-        }
-      } else {
-        // 未注册，先注册
-        this.register(pluginInstance, options);
-      }
-
-      const entry = this._plugins.get(pluginInstance.name);
-
-      // 注册后再次检查 enabled 状态
-      if (!entry.enabled) {
-        return pluginInstance;
-      }
-
-      // 调用 install
-      try {
-        await entry.instance.install(this.framework);
-      } catch (err) {
-        this._log.error(`Install failed for '${pluginInstance.name}':`, err.message);
-        throw new PluginError(`Install failed for '${pluginInstance.name}'`, {
-          context: { originalError: err.message },
-        });
-      }
-
-      entry.status = 'loaded';
-
-      // 如果处于 bootstrap 模式，由外部统一调用 startAll()
-      // 否则直接启动
-      if (this._bootstrapping) {
-        // bootstrap 模式下不启动，由 bootstrapDefaults 统一启动
-      } else {
-        // 非 bootstrap 模式下直接启动
-        try {
-          if (typeof pluginInstance.start === 'function') {
-            await pluginInstance.start(this.framework);
-            pluginInstance._started = true;
-          }
-        } catch (err) {
-          this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
-        }
-      }
-
-      this.framework.emit('plugin:loaded', pluginInstance);
-
-      // 保存状态（创建或更新 state 文件）
-      this._saveState();
-
-      return pluginInstance;
-    } finally {
-      this._loading = false;
-    }
-  }
-
-  /**
-   * 设置 bootstrap 模式
-   * @param {boolean} value
-   */
-  setBootstrapping(value) {
-    this._bootstrapping = value;
-  }
-
-  /**
-   * 卸载插件
-   * @param {string} name - 插件名称
-   * @returns {Promise<boolean>}
-   */
-  async unload(name) {
-    const entry = this._plugins.get(name);
-    if (!entry) {
-      return false;
-    }
-
-    const { instance } = entry;
-
-    // 调用 uninstall
-    try {
-      await instance.uninstall(this.framework);
-    } catch (err) {
-      this._log.error(`Uninstall error for '${name}':`, err.message);
-    }
-
-    entry.status = 'unloaded';
-    this.framework.emit('plugin:unloaded', instance);
-    return true;
-  }
-
-  /**
-   * 重载插件
-   * @param {string} name - 插件名称
-   * @returns {Promise<Plugin>}
-   * @throws {PluginNotFoundError} 插件不存在时抛出
-   */
-  async reload(name) {
-    const entry = this._plugins.get(name);
-    if (!entry) {
-      throw new PluginNotFoundError(name);
-    }
-
-    const { instance } = entry;
-
-    // 调用 reload
-    try {
-      await instance.reload(this.framework);
-      this.framework.emit('plugin:reloaded', instance);
-    } catch (err) {
-      this._log.error(`Reload error for '${name}':`, err.message);
-      throw new PluginError(`Reload error for '${name}'`, {
-        context: { originalError: err.message },
-      });
-    }
-
-    return instance;
-  }
-
-  /**
-   * 重载所有插件
-   * @returns {Promise<void>}
-   */
-  async reloadAll() {
-    // 1. 重置所有插件的启动标志
-    for (const entry of this._plugins.values()) {
-      entry.instance._started = false;
-    }
-
-    // 2. 扫描 .agent/plugins 目录，加载新插件
-    await this._discoverCustomPlugins();
-
-    // 3. 启动所有未启动的插件
-    await this.startAll();
-  }
-
-  /**
-   * 解析插件路径
-   * 支持两种结构：
-   * 1. 文件夹结构: .agent/plugins/my-plugin/index.js
-   * 2. 单文件结构: .agent/plugins/my-plugin.js
-   * @param {string} pluginsDir - 插件目录
-   * @param {string} name - 插件名称
-   * @returns {{path: string, type: 'folder'|'file'}|null} 插件路径和类型
-   * @private
-   */
-  _resolvePluginPath(pluginsDir, name) {
-    return resolvePluginPath(pluginsDir, name, { logger: this._log });
-  }
-
-  /**
-   * 扫描插件目录，返回所有插件名称
-   * @param {string} pluginsDir - 插件目录
-   * @returns {string[]} 插件名称列表
-   * @private
-   */
-  _scanPluginNames(pluginsDir) {
-    return scanPluginNames(pluginsDir);
-  }
-
-  /**
-   * 发现并加载自定义插件
-   * @private
-   */
-  async _discoverCustomPlugins() {
-    const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins');
-    if (!fs.existsSync(pluginsDir)) {
-      return;
-    }
-
-    // 扫描所有插件名称（支持文件夹和单文件）
-    const pluginNames = this._scanPluginNames(pluginsDir);
-
-    // 从 pluginsDir 推导 agentDir（pluginsDir = <agentDir>/plugins）
-    const agentDir = path.dirname(pluginsDir);
-    const agentNodeModules = path.join(agentDir, 'node_modules');
-
-    for (const pluginName of pluginNames) {
-      try {
-        const resolved = this._resolvePluginPath(pluginsDir, pluginName);
-        if (!resolved) {
-          this._log.warn(`Cannot resolve plugin: ${pluginName}`);
-          continue;
-        }
-
-        const { path: pluginPath, type } = resolved;
-
-        // 添加模块路径到搜索路径（优先级从高到低）
-        const modulePathsToAdd = [
-          agentNodeModules, // .agent/node_modules（项目本地安装的包）
-          path.join(__dirname, '..', '..', 'node_modules'), // 全局安装的包
-        ];
-        for (const mp of modulePathsToAdd) {
-          if (fs.existsSync(mp) && !module.paths.includes(mp)) {
-            module.paths.unshift(mp);
-          }
-        }
-
-        // 清除缓存
-        delete require.cache[require.resolve(pluginPath)];
-        const pluginModule = require(pluginPath);
-
-        let plugin;
-        if (typeof pluginModule === 'function') {
-          plugin = pluginModule;
-        } else if (pluginModule.default) {
-          plugin = pluginModule.default;
-        } else {
-          plugin = pluginModule;
-        }
-
-        // 获取插件名称
-        let resolvedPluginName;
-        try {
-          const tempPlugin =
-            plugin.prototype instanceof require('./plugin-base')
-              ? new plugin()
-              : typeof plugin === 'function'
-                ? plugin()
-                : plugin;
-          resolvedPluginName = tempPlugin.name || pluginName;
-        } catch {
-          resolvedPluginName = pluginName;
-        }
-
-        // 如果插件已加载且已启动，跳过
-        if (this.has(resolvedPluginName) && this.get(resolvedPluginName)?._started) {
-          continue;
-        }
-
-        this._log.info(`Loading new plugin: ${pluginName} (${type})`);
-        // .agent/plugins 目录下的插件默认强制启用，不受 state 文件影响
-        await this.load(plugin, { forceEnabled: true });
-      } catch (err) {
-        this._log.error(`Failed to load plugin ${pluginName}:`, err.message);
-      }
-    }
-  }
-
-  /**
-   * 获取插件
-   * @param {string} name - 插件名称
-   * @returns {Plugin|undefined}
-   */
-  get(name) {
-    return this._plugins.get(name)?.instance;
-  }
-
-  /**
-   * 获取所有已加载且已启用的插件
-   * @returns {Array<{name: string, instance: Plugin}>}
-   */
-  getAll() {
-    return Array.from(this._plugins.values())
-      .filter((e) => e.status === 'loaded' && e.enabled)
-      .map((e) => ({ name: e.instance.name, instance: e.instance }));
-  }
-
-  /**
-   * 注册一个已知插件（但不加载）
-   * 用于显示所有可用插件列表
-   * @param {string} name - 插件名称
-   * @param {Object} [info] - 插件信息
-   */
-  registerKnownPlugin(name, info = {}) {
-    this._knownPlugins.add(name);
-    // 如果插件还没注册过，记录它的信息
-    if (!this._plugins.has(name)) {
-      this._plugins.set(name, {
-        instance: { name, ...info },
-        status: 'known',
-        enabled: info.enabled !== undefined ? info.enabled : false,
-      });
-    }
-  }
-
-  /**
-   * 获取所有已知插件（包括未加载的）
-   * @returns {Array<{name: string, status: string, enabled: boolean, version?: string, system?: boolean}>}
-   */
-  getAllKnown() {
-    const result = [];
-    for (const name of this._knownPlugins) {
-      const entry = this._plugins.get(name);
-      result.push({
-        name,
-        status: entry?.status || 'unknown',
-        enabled: entry?.enabled || false,
-        version: entry?.instance?.version,
-        system: entry?.instance?.system || false,
-      });
-    }
-    // 也加入已加载但不在 knownPlugins 中的
-    for (const [name, entry] of this._plugins) {
-      if (!result.find((p) => p.name === name)) {
-        result.push({
-          name,
-          status: entry.status,
-          enabled: entry.enabled,
-          version: entry.instance?.version,
-          system: entry.instance?.system || false,
-        });
-      }
-    }
-    return result;
-  }
-
-  /**
-   * 检查插件是否存在
-   * @param {string} name - 插件名称
-   * @returns {boolean}
-   */
-  has(name) {
-    return this._plugins.has(name) || this._knownPlugins.has(name);
-  }
-
-  /**
-   * 检查插件是否已加载
-   * @param {string} name - 插件名称
-   * @returns {boolean}
-   */
-  isLoaded(name) {
-    return this._plugins.get(name)?.status === 'loaded';
-  }
-
-  /**
-   * 检查插件是否启用
-   * @param {string} name - 插件名称
-   * @returns {boolean}
-   */
-  isEnabled(name) {
-    return this._plugins.get(name)?.enabled === true;
-  }
-
-  /**
-   * 启用插件
-   * @param {string} name - 插件名称
-   * @returns {Promise<void>}
-   * @throws {PluginNotFoundError} 插件不存在时抛出
-   * @throws {PluginError} 系统插件不能被禁用
-   */
-  async enable(name) {
-    const entry = this._plugins.get(name);
-    if (!entry) {
-      throw new PluginNotFoundError(name);
-    }
-
-    // 系统插件不能被禁用，所以启用没有意义
-    if (entry.instance?.system) {
-      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
-    }
-
-    if (entry.enabled) {
-      this._log.info(`Plugin '${name}' already enabled`);
-      return;
-    }
-
-    entry.enabled = true;
-    // 同步更新插件实例的 enabled 属性，避免 load() 时被跳过
-    if (entry.instance) {
-      entry.instance.enabled = true;
-    }
-
-    // 如果插件已加载，尝试重新启动
-    if (entry.status === 'loaded') {
-      try {
-        // 如果之前已经启动过，先调用 stop 停止旧实例
-        if (entry.instance._started) {
-          if (typeof entry.instance.stop === 'function') {
-            await entry.instance.stop();
-          } else if (typeof entry.instance.stopBot === 'function') {
-            await entry.instance.stopBot();
-          }
-        }
-        // 调用 reload 让插件重新初始化（会调用 install 和 start）
-        await this.reload(name);
-      } catch (err) {
-        this._log.error(`Enable/reload failed for '${name}':`, err.message);
-      }
-    } else if (entry.status === 'registered' || entry.status === 'known') {
-      // 插件只注册过但未加载，现在加载它
-      try {
-        await this.load(entry.instance);
-      } catch (err) {
-        this._log.error(`Enable/load failed for '${name}':`, err.message);
-      }
-    }
-
-    this.framework.emit('plugin:enabled', entry.instance);
-    this._saveState();
-    this._log.info(`Plugin '${name}' enabled`);
-  }
-
-  /**
-   * 禁用插件
-   * @param {string} name - 插件名称
-   * @returns {Promise<void>}
-   * @throws {PluginNotFoundError} 插件不存在时抛出
-   * @throws {PluginError} 系统插件不能被禁用
-   */
-  async disable(name) {
-    const entry = this._plugins.get(name);
-    if (!entry) {
-      throw new PluginNotFoundError(name);
-    }
-
-    // 系统插件不能被禁用
-    if (entry.instance?.system) {
-      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
-    }
-
-    if (!entry.enabled) {
-      this._log.info(`Plugin '${name}' already disabled`);
-      return;
-    }
-
-    entry.enabled = false;
-    // 同步更新插件实例的 enabled 属性
-    if (entry.instance) {
-      entry.instance.enabled = false;
-    }
-
-    // 如果插件正在运行，停止它
-    if (entry.instance._started) {
-      try {
-        // 优先调用 stop 方法，其次调用 stopBot 方法
-        if (typeof entry.instance.stop === 'function') {
-          await entry.instance.stop();
-        } else if (typeof entry.instance.stopBot === 'function') {
-          await entry.instance.stopBot();
-        }
-        entry.instance._started = false;
-      } catch (err) {
-        this._log.error(`Stop failed for '${name}':`, err.message);
-      }
-    }
-
-    this.framework.emit('plugin:disabled', entry.instance);
-    this._saveState();
-    this._log.info(`Plugin '${name}' disabled`);
-  }
-
-  /**
-   * 更新插件配置
-   * @param {string} name - 插件名称
-   * @param {Object} config - 新配置（会合并到现有配置）
-   * @returns {Object} 更新后的配置
-   * @throws {PluginNotFoundError} 插件不存在时抛出
-   */
-  updatePluginConfig(name, config) {
-    const entry = this._plugins.get(name);
-    if (!entry) {
-      throw new PluginNotFoundError(name);
-    }
-
-    if (!entry.instance.config) {
-      entry.instance.config = {};
-    }
-
-    // 合并配置
-    entry.instance.config = { ...entry.instance.config, ...config };
-
-    // 保存状态
-    this._saveState();
-    this._log.info(`Plugin '${name}' config updated`);
-
-    return entry.instance.config;
-  }
-
-  /**
-   * 启动所有已加载但未启动的插件（按优先级排序）
-   * @returns {Promise<void>}
-   */
-  async startAll() {
-    const entries = Array.from(this._plugins.values())
-      .filter((e) => e.status === 'loaded' && e.enabled) // 只启动已启用且已加载的插件
-      .sort((a, b) => (a.instance.priority || 100) - (b.instance.priority || 100));
-
-    for (const entry of entries) {
-      const instance = entry.instance;
-      // 跳过已经启动过的插件
-      if (instance._started) {
-        continue;
-      }
-      try {
-        if (typeof instance.start === 'function') {
-          await instance.start(this.framework);
-          instance._started = true;
-        }
-      } catch (err) {
-        this._log.error(`Start failed for '${instance.name}':`, err.message);
-      }
-    }
-  }
-
-  /**
-   * 从对象创建插件实例
-   * @private
-   * @param {Object|Function} obj
-   * @returns {Plugin}
-   */
-  _createFromObject(obj) {
-    const { Plugin } = require('./plugin-base');
-
-    // 如果是类（构造函数），直接实例化
-    if (typeof obj === 'function') {
-      // 检查是否是 Plugin 的子类（通过 prototype chain）
-      if (obj.prototype instanceof Plugin) {
-        return new obj();
-      }
-      // 否则是工厂函数，调用它获取类或实例
-      const result = obj(Plugin);
-      // 递归处理返回值
-      if (typeof result === 'function' && result.prototype instanceof Plugin) {
-        return new result();
-      }
-      return result;
-    }
-
-    // 支持对象形式: { name, version, install, start, ... }
-    class AnonymousPlugin extends Plugin {
-      constructor() {
-        super();
-        this.name = obj.name;
-        this.version = obj.version || '1.0.0';
-        this.description = obj.description || '';
-        this.priority = obj.priority || 100;
-
-        // 如果提供了 install/start/reload/uninstall 方法，绑定它们
-        if (typeof obj.install === 'function') {
-          this.install = obj.install.bind(this);
-        }
-        if (typeof obj.start === 'function') {
-          this.start = obj.start.bind(this);
-        }
-        if (typeof obj.reload === 'function') {
-          this.reload = obj.reload.bind(this);
-        }
-        if (typeof obj.uninstall === 'function') {
-          this.uninstall = obj.uninstall.bind(this);
-        }
-      }
-    }
-
-    return new AnonymousPlugin();
-  }
-
-  // ============================================================================
-  // 事件描述注册（供 Ambient Agent 使用）
-  // ============================================================================
-
-  /**
-   * 注册事件描述
-   * @param {string} eventType - 事件类型
-   * @param {string} description - 事件描述
-   * @param {Object} [schema] - 事件参数 Schema
-   */
-  registerEventDescription(eventType, description, schema = null) {
-    const existing = this._eventDescriptions.get(eventType);
-    this._eventDescriptions.set(eventType, {
-      description,
-      params: schema || existing?.params || '',
-      source: 'dynamic',
-      updatedAt: new Date().toISOString(),
-    });
-    return this;
-  }
-
-  /**
-   * 获取所有事件描述
-   * @returns {Map<string, Object>}
-   */
-  getEventDescriptions() {
-    return new Map(this._eventDescriptions);
-  }
-
-  /**
-   * 获取单个事件描述
-   * @param {string} eventType
-   * @returns {Object|null}
-   */
-  getEventDescription(eventType) {
-    return this._eventDescriptions.get(eventType) || null;
-  }
-
-  /**
-   * 检查事件是否已注册
-   * @param {string} eventType
-   * @returns {boolean}
-   */
-  hasEventDescription(eventType) {
-    return this._eventDescriptions.has(eventType);
-  }
-}
-
-module.exports = { PluginManager };
+/**
+ * PluginManager 插件管理器
+ * 负责插件的加载、卸载、重载
+ *
+ * @module PluginManager
+ * @requires ./plugin-base
+ */
+
+const { Plugin } = require('./plugin-base');
+const { logger } = require('../utils/logger');
+const { PluginError, PluginNotFoundError } = require('../utils/error');
+const { safeJsonParse } = require('../utils');
+const { resolvePluginPath, scanPluginNames } = require('../utils/plugin-helpers');
+const fs = require('fs');
+const path = require('path');
+
+class PluginManager {
+  /**
+   * @param {Framework} framework - 框架实例
+   */
+  constructor(framework) {
+    this.framework = framework;
+    this._plugins = new Map();
+    this._loading = false;
+    this._stateFile = path.join(process.cwd(), '.agent', 'data', 'plugins-state.json');
+    this._knownPlugins = new Set(); // 已知插件列表（包括未加载的）
+
+    // 创建子日志器
+    this._log = logger.child('plugin-manager');
+
+    // 事件描述注册表（供 Ambient Agent 使用）
+    this._eventDescriptions = new Map();
+
+    // 状态缓存（加载后保持，避免重复读文件）
+    this._stateCache = null;
+
+    // 注册默认事件描述
+    this._registerDefaultEventDescriptions();
+  }
+
+  /**
+   * 注册默认事件描述
+   * @private
+   */
+  _registerDefaultEventDescriptions() {
+    // 这些事件由框架内置组件触发，无需注册
+    // 但为了文档完整性，提供默认描述
+    const defaultDescriptions = {
+      'tool:result': {
+        description: '工具执行结果事件',
+        params: 'name(工具名), args(执行参数), result(执行结果), error(错误信息)',
+        source: 'framework',
+      },
+      'tool:error': {
+        description: '工具执行错误事件',
+        params: 'name(工具名), args(执行参数), error(错误信息)',
+        source: 'framework',
+      },
+      'agent:message': {
+        description: '代理消息事件',
+        params: 'content(消息内容), sessionId(会话ID)',
+        source: 'framework',
+      },
+      'think:thought_completed': {
+        description: '思考完成事件',
+        params: 'mode(思考模式), topic(思考主题), thought(思考内容), depth(思考深度)',
+        source: 'think-plugin',
+      },
+      'email:received': {
+        description: '收到邮件事件',
+        params:
+          'from(发件人), to(收件人), subject(主题), text(正文), body(HTML正文), messageId(消息ID), timestamp(时间戳)',
+        source: 'email-plugin',
+      },
+      'webhook:received': {
+        description: 'Webhook接收事件',
+        params: 'headers(HTTP头), body(请求体), query(查询参数), path(请求路径)',
+        source: 'web-plugin',
+      },
+      'scheduler:reminder': {
+        description: '定时提醒事件',
+        params: 'taskId(任务ID), message(提醒消息), time(触发时间)',
+        source: 'scheduler-plugin',
+      },
+      'scheduler:task_completed': {
+        description: '任务完成事件',
+        params: 'taskId(任务ID), result(任务结果)',
+        source: 'scheduler-plugin',
+      },
+      'scheduler:task_failed': {
+        description: '任务失败事件',
+        params: 'taskId(任务ID), error(错误信息)',
+        source: 'scheduler-plugin',
+      },
+    };
+
+    for (const [eventType, info] of Object.entries(defaultDescriptions)) {
+      this._eventDescriptions.set(eventType, info);
+    }
+  }
+
+  /**
+   * 获取状态文件路径
+   * @private
+   */
+  _getStateFile() {
+    const dir = path.dirname(this._stateFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    return this._stateFile;
+  }
+
+  /**
+   * 保存插件状态到文件
+   * 注意：AI 插件配置不保存（从环境变量和命令行获取）
+   * @private
+   */
+  _saveState() {
+    try {
+      const stateFile = this._getStateFile();
+      // 读取现有状态（如果存在），保留原有内容
+      let state = safeJsonParse(
+        fs.existsSync(stateFile) ? fs.readFileSync(stateFile, 'utf-8') : '{}',
+        {}
+      );
+
+      // 合并新状态到现有状态
+      for (const [name, entry] of this._plugins) {
+        // AI 配置不保存，每次从环境变量和命令行获取
+        if (name === 'ai') {
+          state[name] = { enabled: entry.enabled };
+        } else {
+          state[name] = {
+            ...(state[name] || {}), // 保留现有配置
+            enabled: entry.enabled,
+            config: entry.instance?.config || {},
+          };
+        }
+      }
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+
+      // 更新缓存
+      this._stateCache = state;
+    } catch (err) {
+      this._log.error('Failed to save state:', err.message);
+    }
+  }
+
+  /**
+   * 加载插件状态从文件（带缓存）
+   * @private
+   * @returns {Object}
+   */
+  _loadState() {
+    // 返回缓存的状态
+    if (this._stateCache !== null) {
+      return this._stateCache;
+    }
+
+    try {
+      const stateFile = this._getStateFile();
+      if (fs.existsSync(stateFile)) {
+        this._stateCache = safeJsonParse(fs.readFileSync(stateFile, 'utf-8'), {});
+        return this._stateCache;
+      }
+    } catch (err) {
+      this._log.error('Failed to load state:', err.message);
+    }
+    this._stateCache = {};
+    return this._stateCache;
+  }
+
+  /**
+   * 注册插件（不加载）
+   * @param {Plugin|Object} plugin - 插件实例或定义
+   * @param {Object} [options] - 注册选项
+   * @returns {PluginManager}
+   * @throws {PluginError} 插件没有名称时抛出
+   */
+  register(plugin, options = {}) {
+    if (!plugin.name) {
+      throw new PluginError('Plugin must have a name');
+    }
+
+    let pluginInstance = plugin;
+    if (!(plugin instanceof Plugin)) {
+      // 从对象创建插件实例
+      pluginInstance = this._createFromObject(plugin);
+    }
+
+    // 加载保存的状态
+    const savedState = this._loadState();
+    const savedEnabled = savedState[pluginInstance.name]?.enabled;
+    const savedConfig = savedState[pluginInstance.name]?.config;
+
+    // 恢复保存的配置到插件实例（AI 插件不恢复配置，从环境变量获取）
+    if (savedConfig && pluginInstance.config && pluginInstance.name !== 'ai') {
+      pluginInstance.config = { ...pluginInstance.config, ...savedConfig };
+    }
+
+    // 系统插件强制启用，不能禁用
+    // 普通插件：state 文件有记录则用 state，否则用插件默认配置
+    let enabled;
+    if (pluginInstance.system) {
+      enabled = true;
+    } else if (savedEnabled !== undefined) {
+      enabled = savedEnabled;
+    } else {
+      enabled = pluginInstance.enabled !== undefined ? pluginInstance.enabled : true;
+    }
+
+    this._plugins.set(pluginInstance.name, {
+      instance: pluginInstance,
+      status: 'registered',
+      enabled,
+    });
+
+    this.framework.emit('plugin:registered', pluginInstance);
+    return this;
+  }
+
+  /**
+   * 加载插件
+   * @param {Plugin|Object} plugin - 插件实例或定义
+   * @param {Object} [options] - 加载选项
+   * @param {boolean} [options.forceEnabled] - 强制启用插件，忽略 state 文件的 disabled 状态
+   * @returns {Promise<Plugin>}
+   * @throws {PluginError} 加载过程中发生错误时抛出
+   */
+  async load(plugin, options = {}) {
+    if (this._loading) {
+      throw new PluginError('Cannot load plugin during another load operation');
+    }
+
+    this._loading = true;
+    try {
+      let pluginInstance = plugin;
+
+      if (!(plugin instanceof Plugin)) {
+        pluginInstance = this._createFromObject(plugin);
+      }
+
+      // 如果已注册，使用已注册的实例和状态
+      const existing = this._plugins.get(pluginInstance.name);
+      if (existing) {
+        pluginInstance = existing.instance;
+
+        // 如果插件被禁用，跳过加载
+        if (!existing.enabled) {
+          this._log.info(`Plugin '${pluginInstance.name}' is disabled`);
+          return pluginInstance;
+        }
+
+        // 如果已加载且已启动，直接返回
+        if (existing.status === 'loaded' && pluginInstance._started) {
+          this._log.warn(`Plugin '${pluginInstance.name}' already loaded`);
+          return pluginInstance;
+        }
+
+        // 如果已加载但未启动（重载场景），直接启动
+        if (existing.status === 'loaded' && !pluginInstance._started) {
+          try {
+            if (typeof pluginInstance.start === 'function') {
+              await pluginInstance.start(this.framework);
+              pluginInstance._started = true;
+            }
+          } catch (err) {
+            this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
+          }
+          this.framework.emit('plugin:loaded', pluginInstance);
+          return pluginInstance;
+        }
+      } else {
+        // 未注册，先注册
+        this.register(pluginInstance, options);
+      }
+
+      const entry = this._plugins.get(pluginInstance.name);
+
+      // 注册后再次检查 enabled 状态
+      if (!entry.enabled) {
+        return pluginInstance;
+      }
+
+      // 调用 install
+      try {
+        await entry.instance.install(this.framework);
+      } catch (err) {
+        this._log.error(`Install failed for '${pluginInstance.name}':`, err.message);
+        throw new PluginError(`Install failed for '${pluginInstance.name}'`, {
+          context: { originalError: err.message },
+        });
+      }
+
+      entry.status = 'loaded';
+
+      // 如果处于 bootstrap 模式，由外部统一调用 startAll()
+      // 否则直接启动
+      if (this._bootstrapping) {
+        // bootstrap 模式下不启动，由 bootstrapDefaults 统一启动
+      } else {
+        // 非 bootstrap 模式下直接启动
+        try {
+          if (typeof pluginInstance.start === 'function') {
+            await pluginInstance.start(this.framework);
+            pluginInstance._started = true;
+          }
+        } catch (err) {
+          this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
+        }
+      }
+
+      this.framework.emit('plugin:loaded', pluginInstance);
+
+      // 保存状态（创建或更新 state 文件）
+      this._saveState();
+
+      return pluginInstance;
+    } finally {
+      this._loading = false;
+    }
+  }
+
+  /**
+   * 设置 bootstrap 模式
+   * @param {boolean} value
+   */
+  setBootstrapping(value) {
+    this._bootstrapping = value;
+  }
+
+  /**
+   * 卸载插件
+   * @param {string} name - 插件名称
+   * @returns {Promise<boolean>}
+   */
+  async unload(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      return false;
+    }
+
+    const { instance } = entry;
+
+    // 调用 uninstall
+    try {
+      await instance.uninstall(this.framework);
+    } catch (err) {
+      this._log.error(`Uninstall error for '${name}':`, err.message);
+    }
+
+    entry.status = 'unloaded';
+    this.framework.emit('plugin:unloaded', instance);
+    return true;
+  }
+
+  /**
+   * 重载插件
+   * @param {string} name - 插件名称
+   * @returns {Promise<Plugin>}
+   * @throws {PluginNotFoundError} 插件不存在时抛出
+   */
+  async reload(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(name);
+    }
+
+    const { instance } = entry;
+
+    // 调用 reload
+    try {
+      await instance.reload(this.framework);
+      this.framework.emit('plugin:reloaded', instance);
+    } catch (err) {
+      this._log.error(`Reload error for '${name}':`, err.message);
+      throw new PluginError(`Reload error for '${name}'`, {
+        context: { originalError: err.message },
+      });
+    }
+
+    return instance;
+  }
+
+  /**
+   * 重载所有插件
+   * @returns {Promise<void>}
+   */
+  async reloadAll() {
+    // 1. 重置所有插件的启动标志
+    for (const entry of this._plugins.values()) {
+      entry.instance._started = false;
+    }
+
+    // 2. 扫描 .agent/plugins 目录，加载新插件
+    await this._discoverCustomPlugins();
+
+    // 3. 启动所有未启动的插件
+    await this.startAll();
+  }
+
+  /**
+   * 解析插件路径
+   * 支持两种结构：
+   * 1. 文件夹结构: .agent/plugins/my-plugin/index.js
+   * 2. 单文件结构: .agent/plugins/my-plugin.js
+   * @param {string} pluginsDir - 插件目录
+   * @param {string} name - 插件名称
+   * @returns {{path: string, type: 'folder'|'file'}|null} 插件路径和类型
+   * @private
+   */
+  _resolvePluginPath(pluginsDir, name) {
+    return resolvePluginPath(pluginsDir, name, { logger: this._log });
+  }
+
+  /**
+   * 扫描插件目录，返回所有插件名称
+   * @param {string} pluginsDir - 插件目录
+   * @returns {string[]} 插件名称列表
+   * @private
+   */
+  _scanPluginNames(pluginsDir) {
+    return scanPluginNames(pluginsDir);
+  }
+
+  /**
+   * 发现并加载自定义插件
+   * @private
+   */
+  async _discoverCustomPlugins() {
+    const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins');
+    if (!fs.existsSync(pluginsDir)) {
+      return;
+    }
+
+    // 扫描所有插件名称（支持文件夹和单文件）
+    const pluginNames = this._scanPluginNames(pluginsDir);
+
+    // 从 pluginsDir 推导 agentDir（pluginsDir = <agentDir>/plugins）
+    const agentDir = path.dirname(pluginsDir);
+    const agentNodeModules = path.join(agentDir, 'node_modules');
+
+    for (const pluginName of pluginNames) {
+      try {
+        const resolved = this._resolvePluginPath(pluginsDir, pluginName);
+        if (!resolved) {
+          this._log.warn(`Cannot resolve plugin: ${pluginName}`);
+          continue;
+        }
+
+        const { path: pluginPath, type } = resolved;
+
+        // 添加模块路径到搜索路径（优先级从高到低）
+        const modulePathsToAdd = [
+          agentNodeModules, // .agent/node_modules（项目本地安装的包）
+          path.join(__dirname, '..', '..', 'node_modules'), // 全局安装的包
+        ];
+        for (const mp of modulePathsToAdd) {
+          if (fs.existsSync(mp) && !module.paths.includes(mp)) {
+            module.paths.unshift(mp);
+          }
+        }
+
+        // 清除缓存
+        delete require.cache[require.resolve(pluginPath)];
+        const pluginModule = require(pluginPath);
+
+        let plugin;
+        if (typeof pluginModule === 'function') {
+          plugin = pluginModule;
+        } else if (pluginModule.default) {
+          plugin = pluginModule.default;
+        } else {
+          plugin = pluginModule;
+        }
+
+        // 获取插件名称
+        let resolvedPluginName;
+        try {
+          const tempPlugin =
+            plugin.prototype instanceof require('./plugin-base')
+              ? new plugin()
+              : typeof plugin === 'function'
+                ? plugin()
+                : plugin;
+          resolvedPluginName = tempPlugin.name || pluginName;
+        } catch {
+          resolvedPluginName = pluginName;
+        }
+
+        // 如果插件已加载且已启动，跳过
+        if (this.has(resolvedPluginName) && this.get(resolvedPluginName)?._started) {
+          continue;
+        }
+
+        this._log.info(`Loading new plugin: ${pluginName} (${type})`);
+        // .agent/plugins 目录下的插件默认强制启用，不受 state 文件影响
+        await this.load(plugin, { forceEnabled: true });
+      } catch (err) {
+        this._log.error(`Failed to load plugin ${pluginName}:`, err.message);
+      }
+    }
+  }
+
+  /**
+   * 获取插件
+   * @param {string} name - 插件名称
+   * @returns {Plugin|undefined}
+   */
+  get(name) {
+    return this._plugins.get(name)?.instance;
+  }
+
+  /**
+   * 获取所有已加载且已启用的插件
+   * @returns {Array<{name: string, instance: Plugin}>}
+   */
+  getAll() {
+    return Array.from(this._plugins.values())
+      .filter((e) => e.status === 'loaded' && e.enabled)
+      .map((e) => ({ name: e.instance.name, instance: e.instance }));
+  }
+
+  /**
+   * 注册一个已知插件（但不加载）
+   * 用于显示所有可用插件列表
+   * @param {string} name - 插件名称
+   * @param {Object} [info] - 插件信息
+   */
+  registerKnownPlugin(name, info = {}) {
+    this._knownPlugins.add(name);
+    // 如果插件还没注册过，记录它的信息
+    if (!this._plugins.has(name)) {
+      this._plugins.set(name, {
+        instance: { name, ...info },
+        status: 'known',
+        enabled: info.enabled !== undefined ? info.enabled : false,
+      });
+    }
+  }
+
+  /**
+   * 获取所有已知插件（包括未加载的）
+   * @returns {Array<{name: string, status: string, enabled: boolean, version?: string, system?: boolean}>}
+   */
+  getAllKnown() {
+    const result = [];
+    for (const name of this._knownPlugins) {
+      const entry = this._plugins.get(name);
+      result.push({
+        name,
+        status: entry?.status || 'unknown',
+        enabled: entry?.enabled || false,
+        version: entry?.instance?.version,
+        system: entry?.instance?.system || false,
+      });
+    }
+    // 也加入已加载但不在 knownPlugins 中的
+    for (const [name, entry] of this._plugins) {
+      if (!result.find((p) => p.name === name)) {
+        result.push({
+          name,
+          status: entry.status,
+          enabled: entry.enabled,
+          version: entry.instance?.version,
+          system: entry.instance?.system || false,
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 检查插件是否存在
+   * @param {string} name - 插件名称
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._plugins.has(name) || this._knownPlugins.has(name);
+  }
+
+  /**
+   * 检查插件是否已加载
+   * @param {string} name - 插件名称
+   * @returns {boolean}
+   */
+  isLoaded(name) {
+    return this._plugins.get(name)?.status === 'loaded';
+  }
+
+  /**
+   * 检查插件是否启用
+   * @param {string} name - 插件名称
+   * @returns {boolean}
+   */
+  isEnabled(name) {
+    return this._plugins.get(name)?.enabled === true;
+  }
+
+  /**
+   * 启用插件
+   * @param {string} name - 插件名称
+   * @returns {Promise<void>}
+   * @throws {PluginNotFoundError} 插件不存在时抛出
+   * @throws {PluginError} 系统插件不能被禁用
+   */
+  async enable(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(name);
+    }
+
+    // 系统插件不能被禁用，所以启用没有意义
+    if (entry.instance?.system) {
+      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
+    }
+
+    if (entry.enabled) {
+      this._log.info(`Plugin '${name}' already enabled`);
+      return;
+    }
+
+    entry.enabled = true;
+    // 同步更新插件实例的 enabled 属性，避免 load() 时被跳过
+    if (entry.instance) {
+      entry.instance.enabled = true;
+    }
+
+    // 如果插件已加载，尝试重新启动
+    if (entry.status === 'loaded') {
+      try {
+        // 如果之前已经启动过，先调用 stop 停止旧实例
+        if (entry.instance._started) {
+          if (typeof entry.instance.stop === 'function') {
+            await entry.instance.stop();
+          } else if (typeof entry.instance.stopBot === 'function') {
+            await entry.instance.stopBot();
+          }
+        }
+        // 调用 reload 让插件重新初始化（会调用 install 和 start）
+        await this.reload(name);
+      } catch (err) {
+        this._log.error(`Enable/reload failed for '${name}':`, err.message);
+      }
+    } else if (entry.status === 'registered' || entry.status === 'known') {
+      // 插件只注册过但未加载，现在加载它
+      try {
+        await this.load(entry.instance);
+      } catch (err) {
+        this._log.error(`Enable/load failed for '${name}':`, err.message);
+      }
+    }
+
+    this.framework.emit('plugin:enabled', entry.instance);
+    this._saveState();
+    this._log.info(`Plugin '${name}' enabled`);
+  }
+
+  /**
+   * 禁用插件
+   * @param {string} name - 插件名称
+   * @returns {Promise<void>}
+   * @throws {PluginNotFoundError} 插件不存在时抛出
+   * @throws {PluginError} 系统插件不能被禁用
+   */
+  async disable(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(name);
+    }
+
+    // 系统插件不能被禁用
+    if (entry.instance?.system) {
+      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
+    }
+
+    if (!entry.enabled) {
+      this._log.info(`Plugin '${name}' already disabled`);
+      return;
+    }
+
+    entry.enabled = false;
+    // 同步更新插件实例的 enabled 属性
+    if (entry.instance) {
+      entry.instance.enabled = false;
+    }
+
+    // 如果插件正在运行，停止它
+    if (entry.instance._started) {
+      try {
+        // 优先调用 stop 方法，其次调用 stopBot 方法
+        if (typeof entry.instance.stop === 'function') {
+          await entry.instance.stop();
+        } else if (typeof entry.instance.stopBot === 'function') {
+          await entry.instance.stopBot();
+        }
+        entry.instance._started = false;
+      } catch (err) {
+        this._log.error(`Stop failed for '${name}':`, err.message);
+      }
+    }
+
+    this.framework.emit('plugin:disabled', entry.instance);
+    this._saveState();
+    this._log.info(`Plugin '${name}' disabled`);
+  }
+
+  /**
+   * 更新插件配置
+   * @param {string} name - 插件名称
+   * @param {Object} config - 新配置（会合并到现有配置）
+   * @returns {Object} 更新后的配置
+   * @throws {PluginNotFoundError} 插件不存在时抛出
+   */
+  updatePluginConfig(name, config) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(name);
+    }
+
+    if (!entry.instance.config) {
+      entry.instance.config = {};
+    }
+
+    // 合并配置
+    entry.instance.config = { ...entry.instance.config, ...config };
+
+    // 保存状态
+    this._saveState();
+    this._log.info(`Plugin '${name}' config updated`);
+
+    return entry.instance.config;
+  }
+
+  /**
+   * 启动所有已加载但未启动的插件（按优先级排序）
+   * @returns {Promise<void>}
+   */
+  async startAll() {
+    const entries = Array.from(this._plugins.values())
+      .filter((e) => e.status === 'loaded' && e.enabled) // 只启动已启用且已加载的插件
+      .sort((a, b) => (a.instance.priority || 100) - (b.instance.priority || 100));
+
+    for (const entry of entries) {
+      const instance = entry.instance;
+      // 跳过已经启动过的插件
+      if (instance._started) {
+        continue;
+      }
+      try {
+        if (typeof instance.start === 'function') {
+          await instance.start(this.framework);
+          instance._started = true;
+        }
+      } catch (err) {
+        this._log.error(`Start failed for '${instance.name}':`, err.message);
+      }
+    }
+  }
+
+  /**
+   * 从对象创建插件实例
+   * @private
+   * @param {Object|Function} obj
+   * @returns {Plugin}
+   */
+  _createFromObject(obj) {
+    const { Plugin } = require('./plugin-base');
+
+    // 如果是类（构造函数），直接实例化
+    if (typeof obj === 'function') {
+      // 检查是否是 Plugin 的子类（通过 prototype chain）
+      if (obj.prototype instanceof Plugin) {
+        return new obj();
+      }
+      // 否则是工厂函数，调用它获取类或实例
+      const result = obj(Plugin);
+      // 递归处理返回值
+      if (typeof result === 'function' && result.prototype instanceof Plugin) {
+        return new result();
+      }
+      return result;
+    }
+
+    // 支持对象形式: { name, version, install, start, ... }
+    class AnonymousPlugin extends Plugin {
+      constructor() {
+        super();
+        this.name = obj.name;
+        this.version = obj.version || '1.0.0';
+        this.description = obj.description || '';
+        this.priority = obj.priority || 100;
+
+        // 如果提供了 install/start/reload/uninstall 方法，绑定它们
+        if (typeof obj.install === 'function') {
+          this.install = obj.install.bind(this);
+        }
+        if (typeof obj.start === 'function') {
+          this.start = obj.start.bind(this);
+        }
+        if (typeof obj.reload === 'function') {
+          this.reload = obj.reload.bind(this);
+        }
+        if (typeof obj.uninstall === 'function') {
+          this.uninstall = obj.uninstall.bind(this);
+        }
+      }
+    }
+
+    return new AnonymousPlugin();
+  }
+
+  // ============================================================================
+  // 事件描述注册（供 Ambient Agent 使用）
+  // ============================================================================
+
+  /**
+   * 注册事件描述
+   * @param {string} eventType - 事件类型
+   * @param {string} description - 事件描述
+   * @param {Object} [schema] - 事件参数 Schema
+   */
+  registerEventDescription(eventType, description, schema = null) {
+    const existing = this._eventDescriptions.get(eventType);
+    this._eventDescriptions.set(eventType, {
+      description,
+      params: schema || existing?.params || '',
+      source: 'dynamic',
+      updatedAt: new Date().toISOString(),
+    });
+    return this;
+  }
+
+  /**
+   * 获取所有事件描述
+   * @returns {Map<string, Object>}
+   */
+  getEventDescriptions() {
+    return new Map(this._eventDescriptions);
+  }
+
+  /**
+   * 获取单个事件描述
+   * @param {string} eventType
+   * @returns {Object|null}
+   */
+  getEventDescription(eventType) {
+    return this._eventDescriptions.get(eventType) || null;
+  }
+
+  /**
+   * 检查事件是否已注册
+   * @param {string} eventType
+   * @returns {boolean}
+   */
+  hasEventDescription(eventType) {
+    return this._eventDescriptions.has(eventType);
+  }
+}
+
+module.exports = { PluginManager };