foliko 1.1.93 → 2.0.0

package/src/{core/plugin-base.js → plugin/base.js}

@@ -1,94 +1,42 @@
+'use strict';
+
 /**
  * Plugin 基类
  * 所有插件的基类
  */
 
+const { logger } = require('../common/logger');
+const log = logger.child('plugin');
+
 class Plugin {
-  /**
-   * 插件名称
-   * @type {string}
-   */
   name = 'unnamed-plugin';
-
-  /**
-   * 插件版本
-   * @type {string}
-   */
   version = '1.0.0';
-
-  /**
-   * 插件描述
-   * @type {string}
-   */
   description = '';
-
-  /**
-   * 插件优先级，数值越小越先加载
-   * @type {number}
-   */
   priority = 100;
 
-  /**
-   * 子Agent配置数组 - 配置后自动注册子Agent
-   * 格式: [{ name: 'xxx', role: '角色', tools: {...}, parentTools: [...] }]
-   * @type {Array}
-   */
   agents = [];
-
-  /**
-   * 插件是否启用，默认为 true
-   * 设置为 false 时插件不会被加载，但在列表中仍可见
-   * @type {boolean}
-   */
   enabled = true;
-
-  /**
-   * 是否为系统插件，默认为 false
-   * 系统插件不能被禁用，始终启用
-   * @type {boolean}
-   */
   system = false;
 
   _framework = null;
   _subAgents = [];
-  _promptParts = [];  // 注册的提示词部分
-  _deferredPromptParts = null;  // 延迟注册的提示词部分（等待主 agent 创建）
-
-  /**
-   * 插件注册的工具集（供 ExtensionExecutor 自动加载）
-   * 格式: { toolName: { name, description, inputSchema, execute } }
-   * @type {Object}
-   */
+  _promptParts = [];
+  _deferredPromptParts = null;
   tools = {};
 
-  /**
-   * 安装插件 - 注册工具/事件等
-   * @param {Framework} framework - 框架实例
-   */
   install(framework) {
     this._framework = framework;
     return this;
   }
 
-  /**
-   * 注册工具到扩展执行器（供 ExtensionExecutor 统一管理）
-   * 支持三种调用方式：
-   *   this.registerTool('name', { description, inputSchema, execute })
-   *   this.registerTool({ name, description, inputSchema, execute })
-   *   this.registerTool({ name, description, inputSchema, execute, pluginName: 'xxx' })
-   * @param {string|Object} name - 工具名称或工具定义对象
-   * @param {Object} [def] - 工具定义 { description, inputSchema, execute }
-   */
   registerTool(name, def) {
     if (!this._framework) return;
-    // 支持 this.registerTool({ name, description, ... }) 形式
     if (typeof name === 'object' && name !== null) {
       def = name;
       name = def.name;
     }
     if (!name || !def) return;
 
-    // 支持自定义插件名
     const pluginName = def.pluginName || this.name;
     delete def.pluginName;
 
@@ -106,39 +54,25 @@ class Plugin {
     }
   }
 
-  /**
-   * 启动插件 - 初始化完成后的启动
-   * @param {Framework} framework - 框架实例
-   */
   start(framework) {
-    // 自动注册配置的子Agent
     this._autoRegisterSubAgents();
     return this;
   }
 
-  /**
-   * 自动注册子Agent（根据 this.agents 配置）
-   * @private
-   */
   _autoRegisterSubAgents() {
-    // 确定要注册的agent配置
     const agentsToRegister = this._deferredSubAgents || this.agents;
     if (!agentsToRegister || !Array.isArray(agentsToRegister) || agentsToRegister.length === 0) {
       return;
     }
 
-    // 获取父Agent
     const parentAgent = this._getParentAgent();
 
     if (!parentAgent) {
-      // 没有父Agent，推迟到框架准备好时再注册
       if (!this._deferredSubAgents) {
         log.debug(` No parent agent found, deferring subagent registration`);
         this._deferredSubAgents = agentsToRegister;
-        // 监听框架准备好事件
         if (this._framework) {
           this._framework.once('framework:ready', () => {
-            // 延迟注册，确保主Agent已创建
             setTimeout(() => this._autoRegisterSubAgents(), 100);
           });
         }
@@ -146,7 +80,6 @@ class Plugin {
       return;
     }
 
-    // 有父Agent了，清除延迟标记
     this._deferredSubAgents = null;
 
     for (const agentConfig of agentsToRegister) {
@@ -159,10 +92,6 @@ class Plugin {
     }
   }
 
-  /**
-   * 获取父Agent
-   * @private
-   */
   _getParentAgent() {
     if (!this._framework) return null;
     if (this._framework._mainAgent) return this._framework._mainAgent;
@@ -170,29 +99,17 @@ class Plugin {
     return agents.length > 0 ? agents[agents.length - 1] : null;
   }
 
-  /**
-   * 注册子Agent
-   * @param {Object} config - 子Agent配置
-   * @param {string} config.name - 子Agent名称
-   * @param {string} config.role - 子Agent角色
-   * @param {string} [config.description] - 子Agent描述
-   * @param {Object} [config.tools] - 自定义工具 { name: toolDef }
-   * @param {string[]} [config.parentTools] - 从父Agent继承的工具名称
-   * @returns {Object} 注册的子Agent信息
-   */
   registerSubAgent(config) {
     if (!this._framework) {
       throw new Error('Plugin not installed, call install(framework) first');
     }
 
-    // 获取 subagent-manager 插件
     const subAgentManager = this._framework.pluginManager.get('subagent-manager');
 
     if (!subAgentManager) {
       throw new Error('subagent-manager plugin not found');
     }
 
-    // 创建子Agent实例
     const agent = this._framework.createSubAgent({
       name: config.name,
       role: config.role,
@@ -201,7 +118,6 @@ class Plugin {
       parentTools: config.parentTools || [],
     });
 
-    // 注册到 subagent-manager
     subAgentManager.registerPlugin({
       name: config.name,
       role: config.role,
@@ -210,28 +126,21 @@ class Plugin {
       tools: config.tools || {},
     });
 
-    // 保存引用以便后续清理
     this._subAgents.push({
       name: config.name,
       agent,
-      plugin: null, // 兼容旧代码
+      plugin: null,
     });
 
     log.debug(` Registered subagent: ${config.name}`);
     return { name: config.name, agent };
   }
 
-  /**
-   * 热重载插件 - 手动调用重载时执行
-   * @param {Framework} framework - 框架实例
-   */
   reload(framework) {
     this._framework = framework;
-    // 清除之前的延迟注册
     this._deferredSubAgents = null;
     this._deferredPromptParts = null;
 
-    // 重新注册提示词部分
     for (const part of this._promptParts) {
       try {
         framework._mainAgent?.registerPromptPart(part.name, part.priority, part.provider);
@@ -240,38 +149,24 @@ class Plugin {
       }
     }
 
-    // 重新注册子Agent
     this._autoRegisterSubAgents();
   }
 
-  /**
-   * 工作目录变更钩子 — 框架级 cwd 切换时由 Framework.setCwd 调用
-   * 子类可重写以重新加载 cwd 相关的资源（路径、文件句柄等）
-   * @param {string} oldCwd
-   * @param {string} newCwd
-   * @param {Framework} framework
-   */
   onCwdChanged(oldCwd, newCwd, framework) {
-    // 默认 no-op
+    // default no-op
   }
 
-  /**
-   * 卸载插件 - 清理资源
-   * @param {Framework} framework - 框架实例
-   */
   uninstall(framework) {
-    // 注销所有提示词部分
     for (const part of this._promptParts) {
       try {
         framework._mainAgent?.unregisterPromptPart(part.name);
       } catch (err) {
-        // 忽略
+        // ignore
       }
     }
     this._promptParts = [];
     this._deferredPromptParts = null;
 
-    // 销毁所有子Agent
     for (const plugin of this._subAgents) {
       try {
         plugin.uninstall(framework);
@@ -283,38 +178,25 @@ class Plugin {
     this._framework = null;
   }
 
-  /**
-   * 注册系统提示词部分
-   * 插件可以在 install() 或 start() 中调用此方法注册自己的提示词
-   * @param {string} name - 部分名称（唯一标识）
-   * @param {number} [priority=100] - 优先级，数值越小越靠前
-   * @param {Function} provider - 返回提示词内容的函数，签名: () => string
-   */
   registerPromptPart(name, priority = 100, provider) {
     if (!this._framework) return;
 
-    // 保存记录
     this._promptParts.push({ name, priority, provider });
 
-    // 如果主 agent 已存在，直接注册
     const mainAgent = this._framework.getMainAgent();
     if (mainAgent) {
       mainAgent.registerPromptPart(name, priority, provider);
-      // 同步到所有子Agent
       this._framework.syncPromptPartsToSubagents();
       return;
     }
 
-    // 否则延迟注册，等待框架准备好
     if (!this._deferredPromptParts) {
       this._deferredPromptParts = [];
     }
     this._deferredPromptParts.push({ name, priority, provider });
 
-    // 监听框架准备好事件
     const alreadyListening = this._framework._events?.['framework:ready']?.length > 0;
     this._framework.once('framework:ready', () => {
-      // 延迟确保主 agent 已创建
       setTimeout(() => {
         if (this._deferredPromptParts) {
           for (const part of this._deferredPromptParts) {
@@ -326,17 +208,12 @@ class Plugin {
             }
           }
           this._deferredPromptParts = null;
-          // 同步到所有子Agent
           this._framework.syncPromptPartsToSubagents();
         }
       }, 100);
     });
   }
 
-  /**
-   * 获取插件信息
-   * @returns {Object}
-   */
   getInfo() {
     return {
       name: this.name,
@@ -347,9 +224,6 @@ class Plugin {
   }
 }
 
-/**
- * 内置插件类型常量
- */
 const PluginType = {
   AI: 'ai',
   TOOLS: 'tools',

package/src/plugin/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const { Plugin, PluginType } = require('./base');
+const { PluginManager } = require('./manager');
+const { resolvePluginPath, scanPluginNames, loadPluginFromPath } = require('./loader');
+
+module.exports = {
+  Plugin,
+  PluginType,
+  PluginManager,
+  resolvePluginPath,
+  scanPluginNames,
+  loadPluginFromPath,
+};

package/src/plugin/loader.js

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Plugin Loader - 加载插件配置与路径解析
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { logger } = require('../common/logger');
+const log = logger.child('plugin-loader');
+
+/**
+ * Resolve plugin path from name
+ * @param {string} pluginName
+ * @param {Object} options
+ * @returns {string|null}
+ */
+function resolvePluginPath(pluginName, options = {}) {
+  const { pluginDirs = [], searchPaths = [] } = options;
+
+  // Check explicit paths first
+  const allPaths = [...pluginDirs, ...searchPaths];
+  for (const dir of allPaths) {
+    const fullPath = path.resolve(dir, pluginName);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+    const indexJs = path.join(fullPath, 'index.js');
+    if (fs.existsSync(indexJs)) {
+      return fullPath;
+    }
+  }
+
+  // Check node_modules
+  try {
+    const resolved = require.resolve(pluginName);
+    return resolved;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan directory for plugin names
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function scanPluginNames(dir) {
+  if (!fs.existsSync(dir)) return [];
+
+  try {
+    return fs.readdirSync(dir)
+      .filter(f => {
+        const fullPath = path.join(dir, f);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+          return fs.existsSync(path.join(fullPath, 'index.js'));
+        }
+        return f.endsWith('.js');
+      })
+      .map(f => f.replace(/\.js$/, ''));
+  } catch (err) {
+    log.warn(`Failed to scan plugin directory ${dir}: ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * Load a plugin from a file path
+ * @param {string} pluginPath
+ * @returns {Object|null} Plugin instance
+ */
+function loadPluginFromPath(pluginPath) {
+  try {
+    const resolved = require.resolve(pluginPath);
+    const module = require(resolved);
+
+    // Handle both direct export and { Plugin } export
+    const PluginClass = module.Plugin || module.default || module;
+    if (typeof PluginClass === 'function') {
+      const instance = new PluginClass();
+      instance.sourcePath = resolved;
+      return instance;
+    }
+    // If already an instance
+    if (PluginClass.name && PluginClass.install) {
+      PluginClass.sourcePath = resolved;
+      return PluginClass;
+    }
+    return null;
+  } catch (err) {
+    log.warn(`Failed to load plugin from ${pluginPath}: ${err.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  resolvePluginPath,
+  scanPluginNames,
+  loadPluginFromPath,
+};

package/src/plugin/manager.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * PluginManager 插件管理器
+ * 负责插件的加载、卸载、重载
+ */
+
+const { Plugin } = require('./base');
+const { logger } = require('../common/logger');
+const { PluginError, PluginNotFoundError } = require('../common/errors');
+const { safeJsonParse } = require('../utils');
+const { resolvePluginPath, scanPluginNames } = require('../utils/plugin-helpers');
+const fs = require('fs');
+const path = require('path');
+
+class PluginManager {
+  constructor(framework) {
+    this.framework = framework;
+    this._plugins = new Map();
+    this._loading = false;
+    this._stateFile = path.join(
+      framework?.getCwd?.() ?? process.cwd(),
+      '.foliko',
+      'data',
+      'plugins-state.json'
+    );
+    this._knownPlugins = new Set();
+
+    this._log = logger.child('plugin-manager');
+    this._eventDescriptions = new Map();
+    this._stateCache = null;
+
+    this._registerDefaultEventDescriptions();
+  }
+
+  _registerDefaultEventDescriptions() {
+    // placeholder - plugins can register event descriptions
+  }
+
+  register(plugin) {
+    if (!(plugin instanceof Plugin)) {
+      throw new PluginError('Plugin must be an instance of Plugin');
+    }
+    this._plugins.set(plugin.name, { instance: plugin, enabled: true });
+    this._knownPlugins.add(plugin.name);
+    this._log.debug(`Plugin registered: ${plugin.name}`);
+    return this;
+  }
+
+  has(name) {
+    return this._plugins.has(name);
+  }
+
+  get(name) {
+    const entry = this._plugins.get(name);
+    return entry ? entry.instance : null;
+  }
+
+  isEnabled(name) {
+    const entry = this._plugins.get(name);
+    return entry ? entry.enabled !== false : false;
+  }
+
+  getAll() {
+    return Array.from(this._plugins.values());
+  }
+
+  getNames() {
+    return Array.from(this._plugins.keys());
+  }
+
+  /**
+   * 获取所有已知插件信息（包括已加载和未加载的）
+   * @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);
+      if (entry) {
+        const inst = entry.instance;
+        result.push({
+          name,
+          status: 'loaded',
+          enabled: entry.enabled !== false,
+          version: inst.version,
+          system: inst.system,
+        });
+      } else {
+        result.push({ name, status: 'known', enabled: false });
+      }
+    }
+    return result;
+  }
+
+  count() {
+    return this._plugins.size;
+  }
+
+  async load(plugin) {
+    const name = plugin.name;
+
+    if (this._plugins.has(name)) {
+      this._log.debug(`Plugin '${name}' already loaded, skipping`);
+      return;
+    }
+
+    this._log.info(`Loading plugin: ${name}`);
+
+    if (typeof plugin.install === 'function') {
+      plugin.install(this.framework);
+    }
+
+    this._plugins.set(name, {
+      instance: plugin,
+      sourcePath: plugin.sourcePath || null,
+      enabled: plugin.enabled !== false,
+    });
+    this._knownPlugins.add(name);
+
+    if (typeof plugin.start === 'function') {
+      await plugin.start(this.framework);
+    }
+
+    this._log.info(`Plugin loaded: ${name}`);
+  }
+
+  async unload(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(`Plugin '${name}' not found`);
+    }
+
+    const plugin = entry.instance;
+    this._log.info(`Unloading plugin: ${name}`);
+
+    if (typeof plugin.uninstall === 'function') {
+      plugin.uninstall(this.framework);
+    }
+
+    this._plugins.delete(name);
+    this._log.info(`Plugin unloaded: ${name}`);
+  }
+
+  async unloadExcept(keepSet) {
+    const unloaded = [];
+    for (const [name, entry] of this._plugins) {
+      if (keepSet.has(name) || (entry.instance && entry.instance.system)) continue;
+      try {
+        await this.unload(name);
+        this._plugins.delete(name);
+        unloaded.push(name);
+      } catch (err) {
+        this._log.warn(`unloadExcept: ${name} failed: ${err.message}`);
+      }
+    }
+    return unloaded;
+  }
+
+  async reload(name) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(`Plugin '${name}' not found`);
+    }
+
+    this._log.info(`Reloading plugin: ${name}`);
+    const plugin = entry.instance;
+
+    if (typeof plugin.reload === 'function') {
+      await plugin.reload(this.framework);
+    } else {
+      // Default reload: uninstall + install + start
+      if (typeof plugin.uninstall === 'function') {
+        plugin.uninstall(this.framework);
+      }
+      if (typeof plugin.install === 'function') {
+        plugin.install(this.framework);
+      }
+      if (typeof plugin.start === 'function') {
+        await plugin.start(this.framework);
+      }
+    }
+
+    this._log.info(`Plugin reloaded: ${name}`);
+  }
+
+  async startAll() {
+    for (const [name, entry] of this._plugins) {
+      const plugin = entry.instance;
+      if (typeof plugin.start === 'function') {
+        try {
+          await plugin.start(this.framework);
+        } catch (err) {
+          this._log.warn(`startAll: ${name} failed: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  async reloadAll() {
+    const names = this.getNames();
+    for (const name of names) {
+      try {
+        await this.reload(name);
+      } catch (err) {
+        this._log.warn(`Failed to reload '${name}': ${err.message}`);
+      }
+    }
+  }
+
+  async enable(name) {
+    const entry = this._plugins.get(name);
+    if (entry) {
+      entry.enabled = true;
+      this._log.info(`Plugin enabled: ${name}`);
+    }
+  }
+
+  async disable(name) {
+    const entry = this._plugins.get(name);
+    if (entry) {
+      if (entry.instance.system) {
+        throw new PluginError(`Cannot disable system plugin '${name}'`);
+      }
+      entry.enabled = false;
+      this._log.info(`Plugin disabled: ${name}`);
+    }
+  }
+
+  updatePluginConfig(name, config) {
+    const entry = this._plugins.get(name);
+    if (!entry) {
+      throw new PluginNotFoundError(`Plugin '${name}' not found`);
+    }
+    if (entry.instance.config) {
+      Object.assign(entry.instance.config, config);
+    }
+  }
+
+  registerEventDescription(eventType, description, schema = null) {
+    this._eventDescriptions.set(eventType, { description, schema });
+  }
+
+  getEventDescriptions() {
+    return new Map(this._eventDescriptions);
+  }
+
+  getEventDescription(eventType) {
+    return this._eventDescriptions.get(eventType) || null;
+  }
+
+  setBootstrapping(val) {
+    this._bootstrapping = val !== false;
+  }
+
+  _setStateFile(cwd) {
+    this._stateFile = path.join(cwd, '.foliko', 'data', 'plugins-state.json');
+  }
+}
+
+module.exports = { PluginManager };