foliko 1.1.93 → 2.0.1

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,
+};