foliko 1.0.74 → 1.0.75

package/src/core/plugin-manager.js

@@ -1,207 +1,300 @@
 /**
  * PluginManager 插件管理器
  * 负责插件的加载、卸载、重载
+ *
+ * @module PluginManager
+ * @requires ./plugin-base
  */
 
-const { Plugin } = require('./plugin-base')
-const fs = require('fs')
-const path = require('path')
+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.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)
+    const dir = path.dirname(this._stateFile);
     if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
+      fs.mkdirSync(dir, { recursive: true });
     }
-    return this._stateFile
+    return this._stateFile;
   }
 
   /**
    * 保存插件状态到文件
    * 注意：AI 插件配置不保存（从环境变量和命令行获取）
+   * @private
    */
   _saveState() {
     try {
-      const stateFile = this._getStateFile()
+      const stateFile = this._getStateFile();
       // 读取现有状态（如果存在），保留原有内容
-      let state = {}
-      if (fs.existsSync(stateFile)) {
-        try {
-          state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'))
-        } catch (e) {
-          // 文件损坏，使用空对象
-          state = {}
-        }
-      }
+      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 }
+          state[name] = { enabled: entry.enabled };
         } else {
           state[name] = {
-            ...(state[name] || {}),  // 保留现有配置
+            ...(state[name] || {}), // 保留现有配置
             enabled: entry.enabled,
-            config: entry.instance?.config || {}
-          }
+            config: entry.instance?.config || {},
+          };
         }
       }
 
-      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2))
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+
+      // 更新缓存
+      this._stateCache = state;
     } catch (err) {
-      console.error('[PluginManager] Failed to save state:', err.message)
+      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()
+      const stateFile = this._getStateFile();
       if (fs.existsSync(stateFile)) {
-        const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'))
-        //console.log('[PluginManager] Loaded plugin state from file')
-        return state
+        this._stateCache = safeJsonParse(fs.readFileSync(stateFile, 'utf-8'), {});
+        return this._stateCache;
       }
     } catch (err) {
-      console.error('[PluginManager] Failed to load state:', err.message)
+      this._log.error('Failed to load state:', err.message);
     }
-    return {}
+    this._stateCache = {};
+    return this._stateCache;
   }
 
   /**
    * 注册插件（不加载）
    * @param {Plugin|Object} plugin - 插件实例或定义
+   * @param {Object} [options] - 注册选项
+   * @returns {PluginManager}
+   * @throws {PluginError} 插件没有名称时抛出
    */
   register(plugin, options = {}) {
     if (!plugin.name) {
-      throw new Error('Plugin must have a name')
+      throw new PluginError('Plugin must have a name');
     }
 
-    let pluginInstance = plugin
+    let pluginInstance = plugin;
     if (!(plugin instanceof Plugin)) {
       // 从对象创建插件实例
-      pluginInstance = this._createFromObject(plugin)
+      pluginInstance = this._createFromObject(plugin);
     }
 
     // 加载保存的状态
-    const savedState = this._loadState()
-    const savedEnabled = savedState[pluginInstance.name]?.enabled
-    const savedConfig = savedState[pluginInstance.name]?.config
+    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 }
+      pluginInstance.config = { ...pluginInstance.config, ...savedConfig };
     }
 
     // 系统插件强制启用，不能禁用
     // 普通插件：state 文件有记录则用 state，否则用插件默认配置
-    let enabled
+    let enabled;
     if (pluginInstance.system) {
-      enabled = true
+      enabled = true;
     } else if (savedEnabled !== undefined) {
-      enabled = savedEnabled
+      enabled = savedEnabled;
     } else {
-      enabled = pluginInstance.enabled !== undefined ? pluginInstance.enabled : true
+      enabled = pluginInstance.enabled !== undefined ? pluginInstance.enabled : true;
     }
 
     this._plugins.set(pluginInstance.name, {
       instance: pluginInstance,
       status: 'registered',
-      enabled
-    })
+      enabled,
+    });
 
-    this.framework.emit('plugin:registered', pluginInstance)
-    return this
+    this.framework.emit('plugin:registered', pluginInstance);
+    return this;
   }
 
   /**
    * 加载插件
    * @param {Plugin|Object} plugin - 插件实例或定义
-   * @param {Object} options - 加载选项
-   * @param {boolean} options.forceEnabled - 强制启用插件，忽略 state 文件的 disabled 状态（用于 .agent/plugins 目录的插件）
+   * @param {Object} [options] - 加载选项
+   * @param {boolean} [options.forceEnabled] - 强制启用插件，忽略 state 文件的 disabled 状态
+   * @returns {Promise<Plugin>}
+   * @throws {PluginError} 加载过程中发生错误时抛出
    */
   async load(plugin, options = {}) {
     if (this._loading) {
-      throw new Error('Cannot load plugin during another load operation')
+      throw new PluginError('Cannot load plugin during another load operation');
     }
 
-    this._loading = true
+    this._loading = true;
     try {
-      let pluginInstance = plugin
+      let pluginInstance = plugin;
 
       if (!(plugin instanceof Plugin)) {
-        pluginInstance = this._createFromObject(plugin)
+        pluginInstance = this._createFromObject(plugin);
       }
 
       // 如果已注册，使用已注册的实例和状态
-      const existing = this._plugins.get(pluginInstance.name)
+      const existing = this._plugins.get(pluginInstance.name);
       if (existing) {
-        pluginInstance = existing.instance
+        pluginInstance = existing.instance;
 
         // 如果插件被禁用，跳过加载
         if (!existing.enabled) {
-          console.log(`[PluginManager] Plugin '${pluginInstance.name}' is disabled`)
-          return pluginInstance
+          this._log.info(`Plugin '${pluginInstance.name}' is disabled`);
+          return pluginInstance;
         }
 
         // 如果已加载且已启动，直接返回
         if (existing.status === 'loaded' && pluginInstance._started) {
-          console.warn(`[PluginManager] Plugin '${pluginInstance.name}' already loaded`)
-          return pluginInstance
+          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
+              await pluginInstance.start(this.framework);
+              pluginInstance._started = true;
             }
           } catch (err) {
-            console.error(`[PluginManager] Start failed for '${pluginInstance.name}':`, err.message)
+            this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
           }
-          this.framework.emit('plugin:loaded', pluginInstance)
-          return pluginInstance
+          this.framework.emit('plugin:loaded', pluginInstance);
+          return pluginInstance;
         }
       } else {
         // 未注册，先注册
-        this.register(pluginInstance, options)
+        this.register(pluginInstance, options);
       }
 
-      const entry = this._plugins.get(pluginInstance.name)
+      const entry = this._plugins.get(pluginInstance.name);
 
       // 注册后再次检查 enabled 状态
       if (!entry.enabled) {
-        //console.log(`[PluginManager] Plugin '${pluginInstance.name}' is disabled, skipping install`)
-        return pluginInstance
+        return pluginInstance;
       }
 
       // 调用 install
       try {
-        await entry.instance.install(this.framework)
+        await entry.instance.install(this.framework);
       } catch (err) {
-        console.error(`[PluginManager] Install failed for '${pluginInstance.name}':`, err.message)
-        throw 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'
+      entry.status = 'loaded';
 
       // 如果处于 bootstrap 模式，由外部统一调用 startAll()
       // 否则直接启动
@@ -211,94 +304,101 @@ class PluginManager {
         // 非 bootstrap 模式下直接启动
         try {
           if (typeof pluginInstance.start === 'function') {
-            await pluginInstance.start(this.framework)
-            pluginInstance._started = true
+            await pluginInstance.start(this.framework);
+            pluginInstance._started = true;
           }
         } catch (err) {
-          console.error(`[PluginManager] Start failed for '${pluginInstance.name}':`, err.message)
+          this._log.error(`Start failed for '${pluginInstance.name}':`, err.message);
         }
       }
 
-      this.framework.emit('plugin:loaded', pluginInstance)
+      this.framework.emit('plugin:loaded', pluginInstance);
 
       // 保存状态（创建或更新 state 文件）
-      this._saveState()
+      this._saveState();
 
-      return pluginInstance
+      return pluginInstance;
     } finally {
-      this._loading = false
+      this._loading = false;
     }
   }
 
   /**
    * 设置 bootstrap 模式
+   * @param {boolean} value
    */
   setBootstrapping(value) {
-    this._bootstrapping = value
+    this._bootstrapping = value;
   }
 
   /**
    * 卸载插件
    * @param {string} name - 插件名称
+   * @returns {Promise<boolean>}
    */
   async unload(name) {
-    const entry = this._plugins.get(name)
+    const entry = this._plugins.get(name);
     if (!entry) {
-      return false
+      return false;
     }
 
-    const { instance } = entry
+    const { instance } = entry;
 
     // 调用 uninstall
     try {
-      await instance.uninstall(this.framework)
+      await instance.uninstall(this.framework);
     } catch (err) {
-      console.error(`[PluginManager] Uninstall error for '${name}':`, err.message)
+      this._log.error(`Uninstall error for '${name}':`, err.message);
     }
 
-    entry.status = 'unloaded'
-    this.framework.emit('plugin:unloaded', instance)
-    return true
+    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)
+    const entry = this._plugins.get(name);
     if (!entry) {
-      throw new Error(`Plugin '${name}' not found`)
+      throw new PluginNotFoundError(name);
     }
 
-    const { instance } = entry
+    const { instance } = entry;
 
     // 调用 reload
     try {
-      await instance.reload(this.framework)
-      this.framework.emit('plugin:reloaded', instance)
+      await instance.reload(this.framework);
+      this.framework.emit('plugin:reloaded', instance);
     } catch (err) {
-      console.error(`[PluginManager] Reload error for '${name}':`, err.message)
-      throw err
+      this._log.error(`Reload error for '${name}':`, err.message);
+      throw new PluginError(`Reload error for '${name}'`, {
+        context: { originalError: err.message },
+      });
     }
 
-    return instance
+    return instance;
   }
 
   /**
    * 重载所有插件
+   * @returns {Promise<void>}
    */
   async reloadAll() {
     // 1. 重置所有插件的启动标志
     for (const entry of this._plugins.values()) {
-      entry.instance._started = false
+      entry.instance._started = false;
     }
 
     // 2. 扫描 .agent/plugins 目录，加载新插件
-    await this._discoverCustomPlugins()
+    await this._discoverCustomPlugins();
 
     // 3. 启动所有未启动的插件
-    await this.startAll()
+    await this.startAll();
   }
 
   /**
@@ -312,39 +412,7 @@ class PluginManager {
    * @private
    */
   _resolvePluginPath(pluginsDir, name) {
-    const folderPath = path.join(pluginsDir, name)
-    const filePath = path.join(pluginsDir, `${name}.js`)
-
-    // 文件夹优先
-    if (fs.existsSync(folderPath) && fs.statSync(folderPath).isDirectory()) {
-      const pkgPath = path.join(folderPath, 'package.json')
-      if (fs.existsSync(pkgPath)) {
-        try {
-          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
-          const main = pkg.main || 'index.js'
-          const mainPath = path.join(folderPath, main)
-          if (fs.existsSync(mainPath)) {
-            return { path: mainPath, type: 'folder' }
-          }
-        } catch (err) {
-          console.warn(`[_resolvePluginPath] Failed to parse package.json for ${name}:`, err.message)
-        }
-      }
-      // 默认加载 index.js
-      const indexPath = path.join(folderPath, 'index.js')
-      if (fs.existsSync(indexPath)) {
-        return { path: indexPath, type: 'folder' }
-      }
-      console.warn(`[_resolvePluginPath] No entry point found for plugin folder: ${name}`)
-      return null
-    }
-
-    // 单文件回退
-    if (fs.existsSync(filePath)) {
-      return { path: filePath, type: 'file' }
-    }
-
-    return null
+    return resolvePluginPath(pluginsDir, name, { logger: this._log });
   }
 
   /**
@@ -354,27 +422,7 @@ class PluginManager {
    * @private
    */
   _scanPluginNames(pluginsDir) {
-    if (!fs.existsSync(pluginsDir)) {
-      return []
-    }
-
-    const names = new Set()
-    const entries = fs.readdirSync(pluginsDir, { withFileTypes: true })
-
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        // 文件夹插件
-        names.add(entry.name)
-      } else if (entry.isFile() && entry.name.endsWith('.js')) {
-        // 单文件插件（排除与文件夹同名的）
-        const baseName = entry.name.replace(/\.js$/, '')
-        if (!names.has(baseName)) {
-          names.add(baseName)
-        }
-      }
-    }
-
-    return Array.from(names)
+    return scanPluginNames(pluginsDir);
   }
 
   /**
@@ -382,72 +430,76 @@ class PluginManager {
    * @private
    */
   async _discoverCustomPlugins() {
-    const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins')
+    const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins');
     if (!fs.existsSync(pluginsDir)) {
-      return
+      return;
     }
 
     // 扫描所有插件名称（支持文件夹和单文件）
-    const pluginNames = this._scanPluginNames(pluginsDir)
+    const pluginNames = this._scanPluginNames(pluginsDir);
 
     // 从 pluginsDir 推导 agentDir（pluginsDir = <agentDir>/plugins）
-    const agentDir = path.dirname(pluginsDir)
-    const agentNodeModules = path.join(agentDir, 'node_modules')
+    const agentDir = path.dirname(pluginsDir);
+    const agentNodeModules = path.join(agentDir, 'node_modules');
 
     for (const pluginName of pluginNames) {
       try {
-        const resolved = this._resolvePluginPath(pluginsDir, pluginName)
+        const resolved = this._resolvePluginPath(pluginsDir, pluginName);
         if (!resolved) {
-          console.warn(`[PluginManager] Cannot resolve plugin: ${pluginName}`)
-          continue
+          this._log.warn(`Cannot resolve plugin: ${pluginName}`);
+          continue;
         }
 
-        const { path: pluginPath, type } = resolved
+        const { path: pluginPath, type } = resolved;
 
         // 添加模块路径到搜索路径（优先级从高到低）
         const modulePathsToAdd = [
-          agentNodeModules,                           // .agent/node_modules（项目本地安装的包）
-          path.join(__dirname, '..', '..', 'node_modules')  // 全局安装的包
-        ]
+          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)
+            module.paths.unshift(mp);
           }
         }
 
         // 清除缓存
-        delete require.cache[require.resolve(pluginPath)]
-        const pluginModule = require(pluginPath)
+        delete require.cache[require.resolve(pluginPath)];
+        const pluginModule = require(pluginPath);
 
-        let plugin
+        let plugin;
         if (typeof pluginModule === 'function') {
-          plugin = pluginModule
+          plugin = pluginModule;
         } else if (pluginModule.default) {
-          plugin = pluginModule.default
+          plugin = pluginModule.default;
         } else {
-          plugin = pluginModule
+          plugin = pluginModule;
         }
 
         // 获取插件名称
-        let resolvedPluginName
+        let resolvedPluginName;
         try {
-          const tempPlugin = plugin.prototype instanceof require('./plugin-base')
-            ? new plugin() : (typeof plugin === 'function' ? plugin() : plugin)
-          resolvedPluginName = tempPlugin.name || pluginName
+          const tempPlugin =
+            plugin.prototype instanceof require('./plugin-base')
+              ? new plugin()
+              : typeof plugin === 'function'
+                ? plugin()
+                : plugin;
+          resolvedPluginName = tempPlugin.name || pluginName;
         } catch {
-          resolvedPluginName = pluginName
+          resolvedPluginName = pluginName;
         }
 
         // 如果插件已加载且已启动，跳过
         if (this.has(resolvedPluginName) && this.get(resolvedPluginName)?._started) {
-          continue
+          continue;
         }
 
-        console.log(`[PluginManager] Loading new plugin: ${pluginName} (${type})`)
+        this._log.info(`Loading new plugin: ${pluginName} (${type})`);
         // .agent/plugins 目录下的插件默认强制启用，不受 state 文件影响
-        await this.load(plugin, { forceEnabled: true })
+        await this.load(plugin, { forceEnabled: true });
       } catch (err) {
-        console.error(`[PluginManager] Failed to load plugin ${pluginName}:`, err.message)
+        this._log.error(`Failed to load plugin ${pluginName}:`, err.message);
       }
     }
   }
@@ -455,117 +507,125 @@ class PluginManager {
   /**
    * 获取插件
    * @param {string} name - 插件名称
+   * @returns {Plugin|undefined}
    */
   get(name) {
-    return this._plugins.get(name)?.instance
+    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 }))
+      .filter((e) => e.status === 'loaded' && e.enabled)
+      .map((e) => ({ name: e.instance.name, instance: e.instance }));
   }
 
   /**
    * 注册一个已知插件（但不加载）
    * 用于显示所有可用插件列表
    * @param {string} name - 插件名称
-   * @param {Object} info - 插件信息
+   * @param {Object} [info] - 插件信息
    */
   registerKnownPlugin(name, info = {}) {
-    this._knownPlugins.add(name)
+    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
-      })
+        enabled: info.enabled !== undefined ? info.enabled : false,
+      });
     }
   }
 
   /**
    * 获取所有已知插件（包括未加载的）
-   * @returns {Array} 插件列表，包含 name, status, enabled
+   * @returns {Array<{name: string, status: string, enabled: boolean, version?: string, system?: boolean}>}
    */
   getAllKnown() {
-    const result = []
+    const result = [];
     for (const name of this._knownPlugins) {
-      const entry = this._plugins.get(name)
+      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
-      })
+        system: entry?.instance?.system || false,
+      });
     }
     // 也加入已加载但不在 knownPlugins 中的
     for (const [name, entry] of this._plugins) {
-      if (!result.find(p => p.name === name)) {
+      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
-        })
+          system: entry.instance?.system || false,
+        });
       }
     }
-    return result
+    return result;
   }
 
   /**
    * 检查插件是否存在
    * @param {string} name - 插件名称
+   * @returns {boolean}
    */
   has(name) {
-    return this._plugins.has(name) || this._knownPlugins.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'
+    return this._plugins.get(name)?.status === 'loaded';
   }
 
   /**
    * 检查插件是否启用
    * @param {string} name - 插件名称
+   * @returns {boolean}
    */
   isEnabled(name) {
-    return this._plugins.get(name)?.enabled === true
+    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)
+    const entry = this._plugins.get(name);
     if (!entry) {
-      throw new Error(`Plugin '${name}' not found`)
+      throw new PluginNotFoundError(name);
     }
 
     // 系统插件不能被禁用，所以启用没有意义
     if (entry.instance?.system) {
-      throw new Error(`Plugin '${name}' is a system plugin, cannot be disabled`)
+      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
     }
 
     if (entry.enabled) {
-      console.log(`[PluginManager] Plugin '${name}' already enabled`)
-      return
+      this._log.info(`Plugin '${name}' already enabled`);
+      return;
     }
 
-    entry.enabled = true
+    entry.enabled = true;
     // 同步更新插件实例的 enabled 属性，避免 load() 时被跳过
     if (entry.instance) {
-      entry.instance.enabled = true
+      entry.instance.enabled = true;
     }
 
     // 如果插件已加载，尝试重新启动
@@ -574,54 +634,57 @@ class PluginManager {
         // 如果之前已经启动过，先调用 stop 停止旧实例
         if (entry.instance._started) {
           if (typeof entry.instance.stop === 'function') {
-            await entry.instance.stop()
+            await entry.instance.stop();
           } else if (typeof entry.instance.stopBot === 'function') {
-            await entry.instance.stopBot()
+            await entry.instance.stopBot();
           }
         }
         // 调用 reload 让插件重新初始化（会调用 install 和 start）
-        await this.reload(name)
+        await this.reload(name);
       } catch (err) {
-        console.error(`[PluginManager] Enable/reload failed for '${name}':`, err.message)
+        this._log.error(`Enable/reload failed for '${name}':`, err.message);
       }
     } else if (entry.status === 'registered' || entry.status === 'known') {
       // 插件只注册过但未加载，现在加载它
       try {
-        await this.load(entry.instance)
+        await this.load(entry.instance);
       } catch (err) {
-        console.error(`[PluginManager] Enable/load failed for '${name}':`, err.message)
+        this._log.error(`Enable/load failed for '${name}':`, err.message);
       }
     }
 
-    this.framework.emit('plugin:enabled', entry.instance)
-    this._saveState()
-    console.log(`[PluginManager] Plugin '${name}' enabled`)
+    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)
+    const entry = this._plugins.get(name);
     if (!entry) {
-      throw new Error(`Plugin '${name}' not found`)
+      throw new PluginNotFoundError(name);
     }
 
     // 系统插件不能被禁用
     if (entry.instance?.system) {
-      throw new Error(`Plugin '${name}' is a system plugin, cannot be disabled`)
+      throw new PluginError(`Plugin '${name}' is a system plugin, cannot be disabled`);
     }
 
     if (!entry.enabled) {
-      console.log(`[PluginManager] Plugin '${name}' already disabled`)
-      return
+      this._log.info(`Plugin '${name}' already disabled`);
+      return;
     }
 
-    entry.enabled = false
+    entry.enabled = false;
     // 同步更新插件实例的 enabled 属性
     if (entry.instance) {
-      entry.instance.enabled = false
+      entry.instance.enabled = false;
     }
 
     // 如果插件正在运行，停止它
@@ -629,86 +692,70 @@ class PluginManager {
       try {
         // 优先调用 stop 方法，其次调用 stopBot 方法
         if (typeof entry.instance.stop === 'function') {
-          await entry.instance.stop()
+          await entry.instance.stop();
         } else if (typeof entry.instance.stopBot === 'function') {
-          await entry.instance.stopBot()
+          await entry.instance.stopBot();
         }
-        entry.instance._started = false
+        entry.instance._started = false;
       } catch (err) {
-        console.error(`[PluginManager] Stop failed for '${name}':`, err.message)
+        this._log.error(`Stop failed for '${name}':`, err.message);
       }
     }
 
-    this.framework.emit('plugin:disabled', entry.instance)
-    this._saveState()
-    console.log(`[PluginManager] Plugin '${name}' disabled`)
+    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)
+    const entry = this._plugins.get(name);
     if (!entry) {
-      throw new Error(`Plugin '${name}' not found`)
+      throw new PluginNotFoundError(name);
     }
 
     if (!entry.instance.config) {
-      entry.instance.config = {}
+      entry.instance.config = {};
     }
 
     // 合并配置
-    entry.instance.config = { ...entry.instance.config, ...config }
+    entry.instance.config = { ...entry.instance.config, ...config };
 
     // 保存状态
-    this._saveState()
-    console.log(`[PluginManager] Plugin '${name}' config updated`)
+    this._saveState();
+    this._log.info(`Plugin '${name}' config updated`);
 
-    return entry.instance.config
+    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))
+      .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
+      const instance = entry.instance;
       // 跳过已经启动过的插件
       if (instance._started) {
-        continue
-      }
-      try {
-        if (typeof instance.start === 'function') {
-          await instance.start(this.framework)
-          instance._started = true
-        }
-      } catch (err) {
-        console.error(`[PluginManager] Start failed for '${instance.name}':`, err.message)
+        continue;
       }
-    }
-  }
-
-  /**
-   * 启动所有已加载插件
-   * @private
-   */
-  async _startAll() {
-    const loaded = this.getAll()
-      .sort((a, b) => (a.instance.priority || 100) - (b.instance.priority || 100))
-
-    for (const { instance } of loaded) {
       try {
         if (typeof instance.start === 'function') {
-          await instance.start(this.framework)
+          await instance.start(this.framework);
+          instance._started = true;
         }
       } catch (err) {
-        console.error(`[PluginManager] Start failed for '${instance.name}':`, err.message)
+        this._log.error(`Start failed for '${instance.name}':`, err.message);
       }
     }
   }
@@ -716,52 +763,101 @@ class PluginManager {
   /**
    * 从对象创建插件实例
    * @private
+   * @param {Object|Function} obj
+   * @returns {Plugin}
    */
   _createFromObject(obj) {
-    const { Plugin } = require('./plugin-base')
+    const { Plugin } = require('./plugin-base');
 
     // 如果是类（构造函数），直接实例化
     if (typeof obj === 'function') {
       // 检查是否是 Plugin 的子类（通过 prototype chain）
       if (obj.prototype instanceof Plugin) {
-        return new obj()
+        return new obj();
       }
       // 否则是工厂函数，调用它获取类或实例
-      const result = obj(Plugin)
+      const result = obj(Plugin);
       // 递归处理返回值
       if (typeof result === 'function' && result.prototype instanceof Plugin) {
-        return new result()
+        return new result();
       }
-      return 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
+        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)
+          this.install = obj.install.bind(this);
         }
         if (typeof obj.start === 'function') {
-          this.start = obj.start.bind(this)
+          this.start = obj.start.bind(this);
         }
         if (typeof obj.reload === 'function') {
-          this.reload = obj.reload.bind(this)
+          this.reload = obj.reload.bind(this);
         }
         if (typeof obj.uninstall === 'function') {
-          this.uninstall = obj.uninstall.bind(this)
+          this.uninstall = obj.uninstall.bind(this);
         }
       }
     }
 
-    return new AnonymousPlugin()
+    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 }
+module.exports = { PluginManager };