mm_machine 2.1.1 → 2.1.3

package/item.js

@@ -1,589 +1,684 @@
-require('mm_logs');
-const util = require('util');
-const conf = require('mm_config');
-const Mod = require('mm_hot_reload');
-
-
-// 初始化模块管理器
-$.mod = $.mod || new Mod();
-
-/**
- * 增强require函数，支持热更新
- * @param {String} file 文件路径
- * @param {Function} func 回调函数
- * @returns {Object} 加载的模块
- */
-$.require = function (file, func) {
-	return $.mod.load(file, func);
-};
-
-/**
- * 增强JSON加载函数，支持热更新
- * @param {String} file 文件路径
- * @param {Function} func 回调函数
- * @returns {Object} 解析的JSON对象
- */
-$.loadJson = function (file, func) {
-	return $.mod.load(file, func);
-};
-
-/**
- * 驱动基础类
- * @class
- */
-class Item {
-	/**
-	 * 构造函数
-	 * @param {String} dir 当前目录
-	 * @param {String} dir_base 模块目录
-	 * @constructor
-	 */
-	constructor(dir, dir_base) {
-		/**
-		 * 当前路径
-		 */
-		this.dir = dir;
-
-		/**
-		 * 默认文件
-		 */
-		this.default_file = './sys.json';
-
-		// 当前文件
-		this.filename = null;
-
-		/* 通用项 */
-		/**
-		 * 配置参数
-		 */
-		this.config = {
-			/**
-			 * 名称, 由中英文和下"_"组成, 用于卸载接口 例如: demo
-			 */
-			name: '',
-			/**
-			 * 标题, 介绍作用
-			 */
-			title: '',
-			/**
-			 * 描述, 用于描述该有什么用的
-			 */
-			description: '',
-			/**
-			 * 文件路径, 当调用函数不存在时，会先从文件中加载
-			 */
-			func_file: './index.js',
-			/**
-			 * 回调函数名 用于决定调用脚本的哪个函数
-			 */
-			func_name: '',
-			/**
-			 * 排序
-			 */
-			sort: 10,
-			/**
-			 * 状态, 0表示未启用, 1表示启用
-			 */
-			state: 1,
-			/**
-			 * 显示, 0表示不显示, 1表示显示
-			 */
-			show: 0
-		};
-
-		/**
-		 * 模块目录
-		 */
-		this.dir_base = dir_base;
-
-		/**
-		 * 模式 
-		 * 1.生产模式，改变文件不会重新加载
-		 * 2.热更新模式，改变配置文件会重新加载配置，不重新加载脚本
-		 * 3.热重载模式，改变配置文件都会加载配置和脚本
-		 * 4.热更新+重载模式，改变配置文件重新加载配置和脚本，执行完后重新加载脚本
-		 * 5.重载模式，执行完后重新加载脚本，避免变量污染
-		 */
-		this.mode = 1;
-
-		// 加载完成
-		this.complete = false;
-	}
-}
-
-/**
- * 设置配置
- * @param {Object} config 配置对象
- */
-Item.prototype.setConfig = function (config) {
-	if (!config) return;
-
-	// 如果func_file改变，重置加载状态
-	if (config.func_file !== this.config.func_file) {
-		this.complete = false;
-	}
-
-	// 合并配置并应用配置处理
-	this.config = conf(Object.assign({}, this.config, config), this.filename);
-};
-
-/**
- * 设置配置后钩子方法
- */
-Item.prototype.setConfig_after = function () {
-	// 空实现，供子类重写
-};
-
-/**
- * 新建脚本文件
- * @param {String} file 目标文件路径
- */
-Item.prototype.newScript = function (file) {
-	const templateFile = './script.js'.fullname(this.dir_base);
-	if (templateFile.hasFile()) {
-		templateFile.copyFile(file);
-	}
-};
-
-/**
- * 移除模块
- * @param {Object|String} module 模块对象或路径
- */
-Item.prototype._remove = function (module) {
-	if (!module) return;
-
-	try {
-		if (this.mode === 3 || this.mode === 4) {
-			// 移除模块和监听
-			$.mod.unload(module);
-		} else {
-			// 移除模块缓存
-			const filename = require.resolve(module);
-			if (require.cache[filename]) {
-				require.cache[filename] = null;
-				delete require.cache[filename];
-			}
-		}
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 移除模块失败: `, err);
-	}
-};
-
-/**
- * 卸载脚本
- * @param {string} file 脚本文件路径
- */
-Item.prototype.unloadScript = function (file) {
-	if (!file) {
-		const funcFile = this.config.func_file;
-		if (funcFile) {
-			file = funcFile.fullname(this.dir);
-		}
-	}
-
-	if (file) {
-		this._remove(file);
-	}
-
-	this.complete = false;
-};
-
-/**
- * 重新加载脚本
- */
-Item.prototype.reloadScript = function () {
-	this.unloadScript();
-	this.loadScript();
-};
-
-/**
- * 卸载钩子方法
- */
-Item.prototype.unload = async function () {
-	// 空实现，供子类重写
-};
-
-/**
- * 卸载之后处理
- * @param {Boolean} remove 是否删除文件
- */
-Item.prototype.unload_after = async function (remove) {
-	// 删除脚本
-	this.unloadScript();
-	if (remove) {
-		this.removeFile();
-	}
-};
-
-/**
- * 加载脚本
- * @param {String} file 文件路径
- * @param {String} name 函数名
- * @returns {Object|null} 返回加载的模块对象
- */
-Item.prototype.loadScript = function (file, name = '') {
-	if (!file) {
-		const funcFile = this.config.func_file;
-		if (funcFile) {
-			file = funcFile.fullname(this.dir);
-			if (!file.hasFile()) {
-				this.newScript(file);
-			}
-		} else {
-			return null;
-		}
-	}
-
-	if (!name) {
-		name = this.config.func_name;
-	}
-
-	let cs;
-	try {
-		if (this.mode === 3 || this.mode === 4) {
-			cs = $.require(file, (loadedModule, changeType) => {
-				if (changeType === 'change' && loadedModule) {
-					if (name) {
-						if (loadedModule[name]) {
-							this.main = loadedModule[name];
-						}
-					} else if ($.push) {
-						$.push(this, loadedModule, true);
-					}
-				}
-			});
-		} else {
-			cs = require(file);
-		}
-
-		if (cs) {
-			if (name) {
-				if (cs[name]) {
-					this.main = cs[name];
-				}
-			} else if ($.push) {
-				$.push(this, cs, true);
-			}
-		}
-
-		return cs;
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 加载脚本失败: `, err);
-		return null;
-	}
-};
-
-/**
- * 新建配置文件
- * @param {String} file 目标文件路径
- */
-Item.prototype.newConfig = function (file) {
-	const templateFile = './config.tpl.json'.fullname(this.dir_base);
-	templateFile.copyFile(file);
-};
-
-/**
- * 加载配置文件
- * @param {String} file 文件路径
- * @param {String} name 配置项名称
- * @return {Object|null} 配置对象
- */
-Item.prototype.loadFile = function (file, name) {
-	let config = null;
-	try {
-		const fullPath = file.fullname(this.dir);
-		let text = fullPath.loadText();
-
-		// 如果文件不存在，创建新的配置文件
-		if (!text) {
-			this.newConfig(fullPath);
-			text = fullPath.loadText();
-		}
-
-		if (text) {
-			// 根据模式决定是否使用热更新加载
-			if (this.mode === 2 || this.mode === 3 || this.mode === 4) {
-				config = $.loadJson(fullPath, function (loadedConfig, changeType) {
-					if (changeType === 'change' && loadedConfig) {
-						try {
-							if (Array.isArray(loadedConfig)) {
-								// 在数组中查找匹配的配置项
-								const targetConfig = loadedConfig.find(item => item.name === this.config.name);
-								if (targetConfig) {
-									this.setConfig(targetConfig);
-									this.setConfig_after();
-									// 根据模式决定是否重新加载脚本
-									if (this.mode === 3 || this.mode === 4) {
-										this.reloadScript();
-									}
-								}
-							} else {
-								this.setConfig(loadedConfig);
-								this.setConfig_after();
-								if (this.mode === 3 || this.mode === 4) {
-									this.reloadScript();
-								}
-							}
-						} catch (err) {
-							$.log.error(`[${this.config.name}] 配置热更新失败: `, err);
-						}
-					}
-				}.bind(this));
-			} else {
-				config = fullPath.loadJson();
-			}
-
-			// 如果指定了名称且配置是数组，查找匹配项
-			if (name && Array.isArray(config)) {
-				config = config.find(item => item.name === name) || null;
-			}
-		}
-
-		// 更新目录和文件名引用
-		this.dir = fullPath.dirname();
-		this.filename = fullPath;
-		return config;
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 加载配置文件失败: `, err);
-		return null;
-	}
-};
-
-/**
- * 删除目录
- */
-Item.prototype.delDir = function () {
-	const funcFile = this.config.func_file;
-	if (funcFile && $.dir && $.dir.del) {
-		$.dir.del(this.dir);
-	}
-};
-
-/**
- * 删除配置和脚本文件
- * @returns {String|null} 错误消息，如果没有错误则返回null
- */
-Item.prototype.removeFile = function () {
-	const name = this.config.name;
-	const file = this.filename;
-
-	let errorMessage = null;
-	try {
-		if (file && file.hasFile) {
-			if (file.hasFile()) {
-				const text = file.loadText();
-				if (text) {
-					const config = text.toJson();
-					if (Array.isArray(config)) {
-						// 在数组配置中查找并删除指定项
-						const index = config.findIndex(item => item.name === name);
-						if (index !== -1) {
-							this.delDir();
-							config.splice(index, 1);
-						}
-						// 根据剩余配置决定保存或删除文件
-						if (config.length > 0) {
-							file.saveText(JSON.stringify(config, null, 4));
-						} else if (file.delFile) {
-							file.delFile();
-						}
-					} else {
-						// 单个配置直接删除目录
-						this.delDir();
-					}
-				} else {
-					this.delDir();
-				}
-			} else {
-				errorMessage = '配置文件不存在';
-			}
-		}
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 删除文件失败: `, err);
-		errorMessage = `删除失败: ${err.message}`;
-	}
-	return errorMessage;
-};
-
-/**
- * 载入配置
- * @param {Object|String} configData 配置对象或配置路径
- * @param {String} name 配置名称
- */
-Item.prototype.loadConfig = function (configData, name) {
-	let config;
-	try {
-		if (configData) {
-			if (typeof configData === 'string') {
-				config = this.loadFile(configData, name);
-			} else {
-				config = configData;
-			}
-		} else {
-			config = this.loadFile(this.filename, name);
-		}
-
-		this.setConfig(config);
-		this.setConfig_after();
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 载入配置失败: `, err);
-	}
-};
-
-/**
- * 加载前处理
- */
-Item.prototype.load_before = async function () {
-	try {
-		const module = this.loadScript();
-		if (module) {
-			this.complete = true;
-		}
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 加载前处理失败: `, err);
-		this.complete = false;
-	}
-};
-
-/**
- * 加载处理
- */
-Item.prototype.load = async function () {
-	// 空实现，供子类重写
-};
-
-/**
- * 重载配置和脚本
- */
-Item.prototype.reload = async function () {
-	await this.run('unload');
-	await this.run('load');
-};
-
-/**
- * 保存配置
- */
-Item.prototype.save = function () {
-	try {
-		if (!this.filename) return;
-
-		const fullPath = this.filename.fullname(this.dir);
-		const text = fullPath.loadText();
-
-		if (text && text.trim().startsWith('[')) {
-			// 数组格式配置
-			const configArray = text.toJson();
-			if (Array.isArray(configArray)) {
-				// 查找并更新现有配置项
-				const existingIndex = configArray.findIndex(item => item.name === this.config.name);
-				if (existingIndex !== -1) {
-					configArray[existingIndex] = this.config;
-				} else {
-					// 如果不存在，添加新配置项
-					configArray.push(this.config);
-				}
-				fullPath.saveText(JSON.stringify(configArray, null, 4));
-				return;
-			}
-		}
-
-		// 单对象格式配置，直接保存
-		fullPath.saveText(JSON.stringify(this.config, null, 4));
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 保存配置失败: `, err);
-	}
-};
-
-/**
- * 主要执行函数
- * @param {*} params 参数集合
- * @returns {Promise<any>} 执行结果
- */
-Item.prototype.main = async function (...params) {
-	// 空实现，供子类重写
-	return null;
-};
-
-/**
- * 运行主函数
- * @param {*} params 参数集合
- * @returns {Promise<any>} 执行结果
- */
-Item.prototype.run = async function (...params) {
-	return await this.exec('main', ...params);
-};
-
-/**
- * 调用函数（核心执行方法）
- * @param {String} method 函数名
- * @param {*} params 参数集合
- * @returns {Promise<any>} 执行结果
- */
-Item.prototype.exec = async function (method, ...params) {
-	// 优先从加载的模块中获取方法
-	let methodFunc = this._mod && this._mod[method];
-	// 如果模块中没有，再检查实例自身
-	if (!methodFunc) {
-		methodFunc = this[method];
-	}
-	
-	if (!methodFunc) {
-		return null;
-	}
-
-	let result;
-
-	try {
-		// 执行前置钩子
-		const beforeMethod = `${method}_before`;
-		let beforeFunc = this._mod && this._mod[beforeMethod];
-		if (!beforeFunc) {
-			beforeFunc = this[beforeMethod];
-		}
-		if (beforeFunc) {
-			try {
-				result = beforeFunc.call(this._mod || this, ...params);
-				if (util.types.isPromise(result)) {
-					result = await result;
-				}
-			} catch (err) {
-				$.log.error(`[${this.config.name}] 执行前置钩子 ${beforeMethod} 失败: `, err);
-			}
-		}
-
-		// 执行主方法
-		const methodResult = methodFunc.call(this._mod || this, ...params);
-		result = util.types.isPromise(methodResult) ? await methodResult : methodResult;
-
-		// 执行后置钩子
-		const afterMethod = `${method}_after`;
-		let afterFunc = this._mod && this._mod[afterMethod];
-		if (!afterFunc) {
-			afterFunc = this[afterMethod];
-		}
-		if (afterFunc) {
-			try {
-				const afterResult = afterFunc.call(this._mod || this, result, ...params);
-				if (util.types.isPromise(afterResult)) {
-					const resolvedAfterResult = await afterResult;
-					if (resolvedAfterResult !== undefined) {
-						result = resolvedAfterResult;
-					}
-				} else if (afterResult !== undefined) {
-					result = afterResult;
-				}
-			} catch (err) {
-				$.log.error(`[${this.config.name}] 执行后置钩子 ${afterMethod} 失败: `, err);
-			}
-		}
-	} catch (err) {
-		$.log.error(`[${this.config.name}] 执行方法 ${method} 失败: `, err);
-		return null;
-	}
-	return result;
-};
-
-/**
- * @module 导出Item类
- */
-module.exports = Item;
+const util = require('util');
+const { conf } = require('mm_config');
+const { HotReload } = require('mm_hot_reload');
+
+// 初始化全局对象
+if (typeof global.$ === 'undefined') {
+  global.$ = {};
+}
+
+if (!$.mod) {
+  $.mod = new HotReload();
+}
+
+/**
+ * 增强require函数，支持热更新
+ * @param {string} file 文件路径
+ * @param {Function} func 回调函数
+ * @returns {object} 加载的模块
+ */
+$.require = function (file, func) {
+  return $.mod.load(file, func);
+};
+
+/**
+ * 增强JSON加载函数，支持热更新
+ * @param {string} file 文件路径
+ * @param {Function} func 回调函数
+ * @returns {object} 解析的JSON对象
+ */
+$.loadJson = function (file, func) {
+  return $.mod.load(file, func);
+};
+
+/**
+ * 驱动基础类
+ * @class
+ */
+class Item {
+  /**
+   * 构造函数
+   * @param {string} dir 当前目录
+   * @param {string} dir_base 模块目录
+   * @class
+   */
+  constructor(dir, dir_base) {
+    // 当前路径
+    this.dir = dir;
+
+    // 默认文件
+    this.default_file = './sys.json';
+
+    // 当前文件
+    this.filename = null;
+
+    // 配置参数
+    this.config = {
+      // 名称, 由中英文和下"_"组成, 用于卸载接口 例如: demo
+      name: '',
+      // 标题, 介绍作用
+      title: '',
+      // 描述, 用于描述该有什么用的
+      description: '',
+      // 文件路径, 当调用函数不存在时，会先从文件中加载
+      func_file: './index.js',
+      // 回调函数名 用于决定调用脚本的哪个函数
+      func_name: '',
+      // 排序
+      sort: 10,
+      // 状态, 0表示未启用, 1表示启用
+      state: 1,
+      // 显示, 0表示不显示, 1表示显示
+      show: 0
+    };
+
+    // 模块目录
+    this.dir_base = dir_base;
+
+    // 模式: 1.生产模式 2.热更新模式 3.热重载模式 4.热更新+重载模式 5.重载模式
+    this.mode = 1;
+
+    // 加载完成
+    this.complete = false;
+
+    this._logger = $.log || console;
+  }
+}
+
+/**
+ * 日志输出
+ * @param {string} level - 日志级别(debug/info/warn/error)
+ * @param {string} message - 日志消息
+ * @param {...*} args - 可选参数
+ */
+Item.prototype.log = function (level, message, ...args) {
+  this._logger[level](`[${this.config.name}] ${message}`, ...args);
+};
+
+/**
+ * 设置配置
+ * @param {object} config 配置对象
+ * @returns {Promise<void>}
+ */
+Item.prototype.setConfig = async function (config) {
+  if (!config) return;
+
+  // 如果func_file改变，重置加载状态
+  if (config.func_file !== this.config.func_file) {
+    this.complete = false;
+  }
+
+  // 合并配置并应用配置处理
+  const result = await conf({ ...this.config, ...config }, this.filename);
+  this.config = result;
+};
+
+/**
+ * 设置配置后钩子方法
+ */
+Item.prototype.setConfigAfter = function () {
+  // 空实现，供子类重写
+};
+
+/**
+ * 新建脚本文件
+ * @param {string} file 目标文件路径
+ */
+Item.prototype.newScript = function (file) {
+  const template_file = './script.js'.fullname(this.dir_base);
+  if (template_file.hasFile()) {
+    template_file.copyFile(file);
+  }
+};
+
+/**
+ * 移除模块
+ * @param {object | string} module 模块对象或路径
+ */
+Item.prototype._remove = function (module) {
+  if (!module) return;
+
+  try {
+    if (this.mode === 3 || this.mode === 4) {
+      // 移除模块和监听
+      $.mod.unload(module);
+    } else {
+      // 移除模块缓存
+      const filename = require.resolve(module);
+      if (require.cache[filename]) {
+        require.cache[filename] = null;
+        delete require.cache[filename];
+      }
+    }
+  } catch (err) {
+    this.log('error', `移除模块失败: `, err);
+  }
+};
+
+/**
+ * 卸载脚本
+ * @param {string} file 脚本文件路径
+ */
+Item.prototype.unloadScript = function (file) {
+  let target_file = file;
+  if (!target_file) {
+    const func_file = this.config.func_file;
+    if (func_file) {
+      target_file = func_file.fullname(this.dir);
+    }
+  }
+
+  if (target_file) {
+    this._remove(target_file);
+  }
+
+  this.complete = false;
+};
+
+/**
+ * 重新加载脚本
+ */
+Item.prototype.reloadScript = function () {
+  this.unloadScript();
+  this.loadScript();
+};
+
+/**
+ * 卸载钩子方法
+ */
+Item.prototype.unload = async function () {
+  // 空实现，供子类重写
+};
+
+/**
+ * 卸载之后处理
+ * @param {boolean} remove 是否删除文件
+ */
+Item.prototype.unloadAfter = async function (remove) {
+  // 删除脚本
+  this.unloadScript();
+  if (remove) {
+    this.removeFile();
+  }
+};
+
+/**
+ * 加载脚本
+ * @param {string} file 文件路径
+ * @param {string} name 函数名
+ * @returns {object | null} 返回加载的模块对象
+ */
+Item.prototype.loadScript = function (file, name = '') {
+  const target_file = this._getScriptFile(file);
+  if (!target_file) return null;
+
+  const target_name = this._getScriptName(name);
+
+  try {
+    const cs = this._loadScript(target_file, target_name);
+    this._setMainMethod(cs, target_name);
+    return cs;
+  } catch (err) {
+    this.log('error', `加载脚本失败: `, err);
+    return null;
+  }
+};
+
+/**
+ * 获取脚本文件路径
+ * @param {string} file 文件路径
+ * @returns {string | null} 完整文件路径
+ */
+Item.prototype._getScriptFile = function (file) {
+  if (file) return file;
+
+  const func_file = this.config.func_file;
+  if (!func_file) return null;
+
+  const target_file = func_file.fullname(this.dir);
+  if (!target_file.hasFile()) {
+    this.newScript(target_file);
+  }
+
+  return target_file;
+};
+
+/**
+ * 获取脚本函数名
+ * @param {string} name 函数名
+ * @returns {string} 函数名
+ */
+Item.prototype._getScriptName = function (name) {
+  return name || this.config.func_name;
+};
+
+/**
+ * 加载脚本模块
+ * @param {string} file 文件路径
+ * @param {string} name 函数名
+ * @returns {object | null} 模块对象
+ */
+Item.prototype._loadScript = function (file, name) {
+  if (this.mode === 3 || this.mode === 4) {
+    return $.require(file, this._handleHotReload.bind(this, name));
+  }
+  return require(file);
+};
+
+/**
+ * 处理热重载回调
+ * @param {string} name 函数名
+ * @param {object} loaded_module 加载的模块
+ * @param {string} change_type 变更类型
+ */
+Item.prototype._handleHotReload = function (name, loaded_module, change_type) {
+  if (change_type === 'change' && loaded_module) {
+    this._setMainMethod(loaded_module, name);
+  }
+};
+
+/**
+ * 设置主方法
+ * @param {object} module 模块对象
+ * @param {string} name 函数名
+ */
+Item.prototype._setMainMethod = function (module, name) {
+  if (!module) return;
+
+  if (name) {
+    if (module[name]) {
+      this.main = module[name];
+    }
+  } else if ($.push) {
+    $.push(this, module, true);
+  }
+};
+
+/**
+ * 新建配置文件
+ * @param {string} file 目标文件路径
+ */
+Item.prototype.newConfig = function (file) {
+  const template_file = './config.tpl.json'.fullname(this.dir_base);
+  template_file.copyFile(file);
+};
+
+/**
+ * 加载配置文件
+ * @param {string} file 文件路径
+ * @param {string} name 配置项名称
+ * @returns {object | null} 配置对象
+ */
+Item.prototype.loadFile = function (file, name) {
+  try {
+    const full_path = file.fullname(this.dir);
+    let text = full_path.loadText();
+
+    // 如果文件不存在，创建新的配置文件
+    if (!text) {
+      this.newConfig(full_path);
+      text = full_path.loadText();
+    }
+
+    if (!text) return null;
+
+    const config = this._loadHotReload(full_path);
+    const final_config = this._findConfigByName(config, name);
+
+    // 更新目录和文件名引用
+    this.dir = full_path.dirname();
+    this.filename = full_path;
+    return final_config;
+  } catch (err) {
+    this.log('error', `加载配置文件失败: `, err);
+    return null;
+  }
+};
+
+/**
+ * 根据模式加载配置（支持热更新）
+ * @param {string} full_path 完整文件路径
+ * @returns {object | Array | null} 配置对象
+ */
+Item.prototype._loadHotReload = function (full_path) {
+  if (this.mode === 2 || this.mode === 3 || this.mode === 4) {
+    return $.loadJson(full_path, this._handleHotReload.bind(this));
+  }
+  return full_path.loadJson();
+};
+
+/**
+ * 处理热更新回调
+ * @param {object | Array} loaded_config 加载的配置
+ * @param {string} change_type 变更类型
+ */
+Item.prototype._handleHotReload = function (loaded_config, change_type) {
+  if (change_type !== 'change' || !loaded_config) return;
+
+  try {
+    const target_config = this._findConfigByName(loaded_config, this.config.name);
+    if (target_config) {
+      this.setConfig(target_config);
+      this.setConfigAfter();
+      this._reloadIfNeeded();
+    }
+  } catch (err) {
+    this.log('error', `配置热更新失败: `, err);
+  }
+};
+
+/**
+ * 根据名称在配置数组中查找配置项
+ * @param {object | Array} config 配置对象或数组
+ * @param {string} name 配置项名称
+ * @returns {object | null} 匹配的配置项
+ */
+Item.prototype._findConfigByName = function (config, name) {
+  if (!name || !Array.isArray(config)) return config;
+  return config.find((item) => item.name === name) || null;
+};
+
+/**
+ * 根据模式决定是否重新加载脚本
+ */
+Item.prototype._reloadIfNeeded = function () {
+  if (this.mode === 3 || this.mode === 4) {
+    this.reloadScript();
+  }
+};
+
+/**
+ * 删除目录
+ */
+Item.prototype.delDir = function () {
+  const func_file = this.config.func_file;
+  if (func_file && $.dir && $.dir.del) {
+    $.dir.del(this.dir);
+  }
+};
+
+/**
+ * 删除配置和脚本文件
+ * @returns {string | null} 错误消息，如果没有错误则返回null
+ */
+Item.prototype.removeFile = function () {
+  const name = this.config.name;
+  const file = this.filename;
+
+  let error_message = null;
+  try {
+    if (!file || !file.hasFile) return null;
+
+    if (!file.hasFile()) {
+      return '配置文件不存在';
+    }
+
+    error_message = this._removeConfigFile(file, name);
+  } catch (err) {
+    this.log('error', `删除文件失败: `, err);
+    error_message = `删除失败: ${err.message}`;
+  }
+  return error_message;
+};
+
+/**
+ * 删除配置文件
+ * @param {object} file 文件对象
+ * @param {string} name 配置名称
+ * @returns {string | null} 错误消息
+ */
+Item.prototype._removeConfigFile = function (file, name) {
+  const text = file.loadText();
+  if (!text) {
+    this.delDir();
+    return null;
+  }
+
+  const config = text.toJson();
+  if (Array.isArray(config)) {
+    return this._removeArrayItem(file, config, name);
+  }
+
+  this.delDir();
+  return null;
+};
+
+/**
+ * 从数组配置中删除指定项
+ * @param {object} file 文件对象
+ * @param {Array} config 配置数组
+ * @param {string} name 配置名称
+ * @returns {string | null} 错误消息
+ */
+Item.prototype._removeArrayItem = function (file, config, name) {
+  const index = config.findIndex((item) => item.name === name);
+  if (index === -1) return null;
+
+  this.delDir();
+  config.splice(index, 1);
+
+  if (config.length > 0) {
+    file.saveText(JSON.stringify(config, null, 4));
+  } else if (file.delFile) {
+    file.delFile();
+  }
+
+  return null;
+};
+
+/**
+ * 载入配置
+ * @param {object | string} config_data 配置对象或配置路径
+ * @param {string} name 配置名称
+ */
+Item.prototype.loadConfig = async function (config_data, name) {
+  let config;
+  try {
+    if (config_data) {
+      if (typeof config_data === 'string') {
+        config = this.loadFile(config_data, name);
+      } else {
+        config = config_data;
+      }
+    } else {
+      config = this.loadFile(this.filename, name);
+    }
+
+    await this.setConfig(config);
+    this.setConfigAfter();
+  } catch (err) {
+    this.log('error', `载入配置失败: `, err);
+  }
+};
+
+/**
+ * 加载前处理
+ */
+Item.prototype.loadBefore = async function () {
+  try {
+    const module = this.loadScript();
+    if (module) {
+      this.complete = true;
+    }
+  } catch (err) {
+    this.log('error', `加载前处理失败: `, err);
+    this.complete = false;
+  }
+};
+
+/**
+ * 加载处理
+ */
+Item.prototype.load = async function () {
+  // 空实现，供子类重写
+};
+
+/**
+ * 重载配置和脚本
+ */
+Item.prototype.reload = async function () {
+  await this.run('unload');
+  await this.run('load');
+};
+
+/**
+ * 保存配置
+ */
+Item.prototype.save = function () {
+  try {
+    if (!this.filename) return;
+
+    const full_path = this.filename.fullname(this.dir);
+    const text = full_path.loadText();
+
+    if (text && text.trim().startsWith('[')) {
+      // 数组格式配置
+      const config_array = text.toJson();
+      if (Array.isArray(config_array)) {
+        // 查找并更新现有配置项
+        const existing_index = config_array.findIndex((item) => item.name === this.config.name);
+        if (existing_index !== -1) {
+          config_array[existing_index] = this.config;
+        } else {
+          // 如果不存在，添加新配置项
+          config_array.push(this.config);
+        }
+        full_path.saveText(JSON.stringify(config_array, null, 4));
+        return;
+      }
+    }
+
+    // 单对象格式配置，直接保存
+    full_path.saveText(JSON.stringify(this.config, null, 4));
+  } catch (err) {
+    this.log('error', `保存配置失败: `, err);
+  }
+};
+
+/**
+ * 主要执行函数
+ * @param {*} _params 参数集合
+ * @returns {Promise<any>} 执行结果
+ */
+Item.prototype.main = async function (..._params) {
+  // 空实现，供子类重写
+  return null;
+};
+
+/**
+ * 运行主函数
+ * @param {*} params 参数集合
+ * @returns {Promise<any>} 执行结果
+ */
+Item.prototype.run = async function (...params) {
+  return await this.exec('main', ...params);
+};
+
+/**
+ * 调用函数（核心执行方法）
+ * @param {string} method 函数名
+ * @param {*} params 参数集合
+ * @returns {Promise<any>} 执行结果
+ */
+Item.prototype.exec = async function (method, ...params) {
+  const method_func = this._getMethod(method);
+  if (!method_func) return null;
+
+  let result;
+
+  try {
+    result = await this._execBefore(method, params);
+    result = await this._execMain(method_func, params, result);
+    result = await this._execAfter(method, params, result);
+  } catch (err) {
+    this.log('error', `执行方法 ${method} 失败: `, err);
+    return null;
+  }
+
+  return result;
+};
+
+/**
+ * 获取方法函数
+ * @param {string} method 方法名
+ * @returns {Function|null} 方法函数
+ */
+Item.prototype._getMethod = function (method) {
+  let method_func = this._mod && this._mod[method];
+  if (!method_func) {
+    method_func = this[method];
+  }
+  return method_func || null;
+};
+
+/**
+ * 执行前置钩子
+ * @param {string} method 方法名
+ * @param {Array} params 参数
+ * @returns {Promise<any>} 前置钩子结果
+ */
+Item.prototype._execBefore = async function (method, params) {
+  const before_method = `${method}Before`;
+  const before_func = this._getMethod(before_method);
+
+  if (!before_func) return undefined;
+
+  try {
+    let result = before_func.call(this._mod || this, ...params);
+    if (util.types.isPromise(result)) {
+      result = await result;
+    }
+    return result;
+  } catch (err) {
+    this.log('error', `执行前置钩子 ${before_method} 失败: `, err);
+    return undefined;
+  }
+};
+
+/**
+ * 执行主方法
+ * @param {Function} method_func 方法函数
+ * @param {Array} params 参数
+ * @param {any} before_result 前置钩子结果
+ * @returns {Promise<any>} 主方法结果
+ */
+Item.prototype._execMain = async function (method_func, params, before_result) {
+  const method_result = method_func.call(this._mod || this, ...params);
+  const result = util.types.isPromise(method_result) ? await method_result : method_result;
+  return result;
+};
+
+/**
+ * 执行后置钩子
+ * @param {string} method 方法名
+ * @param {Array} params 参数
+ * @param {any} main_result 主方法结果
+ * @returns {Promise<any>} 后置钩子结果
+ */
+Item.prototype._execAfter = async function (method, params, main_result) {
+  const after_method = `${method}After`;
+  const after_func = this._getMethod(after_method);
+
+  if (!after_func) return main_result;
+
+  try {
+    const after_result = after_func.call(this._mod || this, main_result, ...params);
+
+    if (util.types.isPromise(after_result)) {
+      const resolved_result = await after_result;
+      return resolved_result !== undefined ? resolved_result : main_result;
+    }
+
+    return after_result !== undefined ? after_result : main_result;
+  } catch (err) {
+    this.log('error', `执行后置钩子 ${after_method} 失败: `, err);
+    return main_result;
+  }
+};
+
+/**
+ * @module 导出Item类
+ */
+module.exports = {
+  Item
+};