mm_machine 2.9.2 → 2.9.4

package/mod.js

@@ -1,711 +1,742 @@
-const { Base } = require('mm_expand');
-require('mm_hot_reload');
-
-/**
- * 增强require函数，专门用于脚本文件(.js)热重载
- * 当脚本文件内容发生变化时，自动重新加载并触发回调
- * @param {string} file 脚本文件路径(.js)
- * @param {Function} func 热更新回调函数，文件变化时触发
- * @returns {object} 加载的模块对象
- * @throws {TypeError} 文件路径不是字符串或回调不是函数时抛出
- */
-$.require = function (file, func) {
-  // 参数校验
-  if (typeof file !== 'string') {
-    throw new TypeError('第一个参数(file)必须是字符串');
-  }
-
-  if (func && typeof func !== 'function') {
-    throw new TypeError('第二个参数(func)必须是函数');
-  }
-
-  // 确保文件是.js文件
-  if (!file.endsWith('.js')) {
-    throw new TypeError('$.require 只能用于.js脚本文件');
-  }
-
-  return $.mod.load(file, func);
-};
-
-/**
- * 增强JSON加载函数，专门用于配置文件(.json)热重载
- * 当配置文件内容发生变化时，自动重新加载并触发回调
- * @param {string} file 配置文件路径(.json)
- * @param {Function} func 热更新回调函数，文件变化时触发
- * @returns {object} 解析的JSON对象
- * @throws {TypeError} 文件路径不是字符串或回调不是函数时抛出
- */
-$.loadJson = function (file, func) {
-  // 参数校验
-  if (typeof file !== 'string') {
-    throw new TypeError('第一个参数(file)必须是字符串');
-  }
-
-  if (func && typeof func !== 'function') {
-    throw new TypeError('第二个参数(func)必须是函数');
-  }
-
-  // 确保文件是.json文件
-  if (!file.endsWith('.json')) {
-    throw new TypeError('$.loadJson 只能用于.json配置文件');
-  }
-  return $.mod.load(file, func);
-};
-
-/**
- * 模块类
- */
-class Mod extends Base {
-  /**
-   * 配置项
-   */
-  static config = {
-    // 模块名称
-    name: '',
-    // 模块描述
-    description: '',
-    // 状态, 可选值: 1-启用, 0-禁用
-    state: 1,
-    // 是否需要缓存数据
-    need_cache: false,
-    // 缓存文件路径
-    cache_file: ''
-  };
-
-  /**
-   * 构造函数
-   * @param {object} config 配置项
-   * @param {object|null} parent 父对象
-   */
-  constructor(config, parent = null) {
-    super(config);
-    // 脚本方法
-    this._methods = {};
-    // 脚本数据
-    this._datas = {};
-    // 是否已加载
-    this.is_loaded = false;
-    // 追加查询到上级的方法
-    if (parent) {
-      this.getParent = function () {
-        return parent;
-      };
-    }
-  }
-}
-
-/**
- * 检查模块是否已加载
- * @returns {boolean} 是否已加载
- */
-Mod.prototype.isLoaded = function () {
-  return this.is_loaded;
-};
-
-/**
- * 日志输出
- * @param {string} level 日志级别
- * @param {string} message 日志消息
- * @param  {...any} params 日志参数
- */
-Mod.prototype.log = function (level, message, ...params) {
-  this.getLogger()[level](`[${this.constructor.name}.${this.config.name}] ${message}`, ...params);
-};
-
-/**
- * 监听事件
- */
-Mod.prototype._listen = function () {
-  this._onLoad();
-  this._onInit();
-  this._onStart();
-  this._onStop();
-  this._onUnload();
-  this._onDestroy();
-};
-
-/**
- * 监听销毁事件
- */
-Mod.prototype._onDestroy = function () {
-  let status_last = 'stopped';
-  // 销毁
-  this.on('destroy:before', async (ctx) => {
-    status_last = this.getState();
-    this.setState('destroying');
-  });
-  this.on('destroy:after', async (ctx) => {
-    await this._destroyCore(...ctx.params);
-  });
-  this.on('destroy:success', (ctx) => {
-    this.setState('destroyed');
-  });
-  this.on('destroy:error', (ctx) => {
-    this.setState(status_last);
-  });
-};
-
-/**
- * 监听加载事件
- * @param {object} ctx 上下文对象
- */
-Mod.prototype._onLoad = async function (ctx) {
-  // 1. 加载
-  this.on('load:before', async (ctx) => {
-    this.setState('loading');
-    await this._loadCore(...ctx.params);
-  });
-  this.on('load:after', (ctx) => {
-    this.setState('loaded');
-    this.is_loaded = true;
-  });
-};
-
-/**
- * 监听启动事件
- * @param {object} ctx 上下文对象
- */
-Mod.prototype._onStart = async function (ctx) {
-  let status_last = 'inited';
-  // 3. 启动
-  this.on('start:before', async (ctx) => {
-    status_last = this.getState();
-    this.setState('starting');
-    await this._startCore(...ctx.params);
-  });
-  this.on('start:success', (ctx) => {
-    this.setState('running');
-  });
-  this.on('start:error', (ctx) => {
-    this.setState(status_last);
-  });
-};
-
-/**
- * 监听停止事件
- * @param {object} ctx 上下文对象
- */
-Mod.prototype._onStop = async function (ctx) {
-  let status_last = 'running';
-  // 4. 停止
-  this.on('stop:before', async (ctx) => {
-    status_last = this.getState();
-    this.setState('stopping');
-  });
-  this.on('stop:after', async (ctx) => {
-    await this._stopCore(...ctx.params);
-  });
-  this.on('stop:success', async (ctx) => {
-    this.setState('stopped');
-  });
-  this.on('stop:error', (ctx) => {
-    this.setState(status_last);
-  });
-};
-
-/**
- * 监听卸载事件
- * @param {object} ctx 上下文对象
- */
-Mod.prototype._onUnload = async function (ctx) {
-  let status_last = 'stopped';
-  // 5. 卸载
-  this.on('unload:before', (ctx) => {
-    status_last = this.getState();
-    this.setState('unloading');
-  });
-  this.on('unload:check', (ctx) => {
-    if (status_last !== 'stopped') {
-      status_last = this.getState();
-      ctx.error = new Error('卸载前必须先停止');
-    }
-  });
-  this.on('unload:after', async (ctx) => {
-    this.setState('unloaded');
-    this.is_loaded = false;
-    await this._unloadCore(...ctx.params);
-  });
-};
-
-/**
- * 初始化监听事件
- * @param {object} ctx 上下文对象
- */
-Mod.prototype._onDestroy = async function (ctx) {
-  let status_last = 'unloaded';
-  // 6. 销毁
-  this.on('destroy:before', async (ctx) => {
-    status_last = this.getState();
-    this.setState('destroying');
-  });
-  this.on('destroy:check', (ctx) => {
-    if (status_last !== 'unloaded') {
-      this.setState(status_last);
-      ctx.error = new Error('销毁前必须先卸载');
-    }
-  });
-};
-
-/**
- * 加载 - 内部方法
- * @param {...any} args 加载参数
- * @returns {object} 模块对象
- * @private
- */
-Mod.prototype._load = async function (...args) {
-  return this;
-};
-
-/**
- * 加载
- * @param {...any} args 加载参数
- * @returns {object} 模块对象
- */
-Mod.prototype.load = async function (...args) {
-  return await this._load(...args);
-};
-
-/**
- * 加载核心
- * @private
- * @param {...any} args 加载参数
- */
-Mod.prototype._loadCore = async function (...args) {
-};
-
-/**
- * 启动 - 内部方法
- * @private
- * @param {...any} args 初始化参数
- * @returns {object} 模块对象
- */
-Mod.prototype._start = async function (...args) {
-  return this;
-};
-
-/**
- * 启动
- * @param {...any} args 初始化参数
- * @returns {object} 模块对象
- */
-Mod.prototype.start = async function (...args) {
-  return await this._start(...args);
-};
-
-/**
- * 启动核心
- * @private
- * @param {...any} args 初始化参数
- */
-Mod.prototype._startCore = async function (...args) {
-
-};
-
-/**
- * 停止 - 内部方法
- * @private
- * @returns {object} 模块对象
- */
-Mod.prototype._stop = async function () {
-  return this;
-};
-
-/**
- * 停止
- * @returns {object} 模块对象
- */
-Mod.prototype.stop = async function () {
-  return await this._stop();
-};
-
-/**
- * 停止核心
- * @private
- */
-Mod.prototype._stopCore = async function () {
-
-};
-
-/**
- * 卸载 - 内部方法
- * @private
- * @returns {object} 模块对象
- */
-Mod.prototype._unload = async function () {
-  return this;
-};
-
-/**
- * 卸载
- * @returns {object} 模块对象
- */
-Mod.prototype.unload = async function () {
-  return await this._unload();
-};
-
-/**
- * 卸载核心
- */
-Mod.prototype._unloadCore = async function () {
-  if (this._methods) {
-    for (let key in this._methods) {
-      delete this[key];
-    }
-    this._methods = {};
-  }
-  if (this._datas) {
-    for (let key in this._datas) {
-      delete this[key];
-    }
-    this._datas = {};
-  }
-};
-
-/**
- * 重载
- */
-Mod.prototype.reload = async function () {
-  await this.do('unload');
-  await this.do('load');
-};
-
-/**
- * 重启
- */
-Mod.prototype.restart = async function () {
-  await this.do('stop');
-  await this.do('start');
-};
-
-/**
- * 是否运行中
- * @returns {boolean} 是否运行中
- */
-Mod.prototype.isRunning = function () {
-  return this.getState() === 'running';
-};
-
-/**
- * 结束
- */
-Mod.prototype.end = async function () {
-  await this.do('stop');
-  await this.do('unload');
-  await this.do('destroy');
-};
-
-/**
- * 获取事件管理器
- * @returns {object} 事件管理器
- */
-Mod.prototype.getEventer = function () {
-  return this._eventer || $.eventer;
-};
-
-/**
- * 设置事件管理器
- * @param {object} eventer 事件管理器
- */
-Mod.prototype.setEventer = function (eventer) {
-  this._eventer = eventer;
-};
-
-/**
- * 触发事件
- * @param {string} event 事件名
- * @param {...any} args 事件参数
- */
-Mod.prototype.emitEvent = function (event, ...args) {
-  this.getEventer()?.emit(event, ...args);
-};
-
-/**
- * 触发事件 - 随机触发
- * @param {string} event 事件名
- * @param {...any} args 事件参数
- * @returns {Promise<any>} 事件触发结果
- */
-Mod.prototype.emitEventRace = async function (event, ...args) {
-  return await this.getEventer()?.emitRace(event, ...args);
-};
-
-/**
- * 触发事件 - 返回第一个非空结果
- * @param {string} event 事件名
- * @param {...any} args 事件参数
- * @returns {Promise<any>} 事件触发结果
- */
-Mod.prototype.emitEventFirst = async function (event, ...args) {
-  return await this.getEventer()?.emitFirst(event, ...args);
-};
-
-/**
- * 注册事件监听
- * @param {string} event 事件名
- * @param {Function} callback 事件回调函数
- */
-Mod.prototype.onEvent = function (event, callback) {
-  this.getEventer()?.on(event, callback);
-};
-
-/**
- * 移除事件监听
- * @param {string} event 事件名
- */
-Mod.prototype.offEvent = function (event) {
-  this.getEventer()?.off(event);
-};
-
-/**
- * 主方法名
- * @param {...any} args 方法参数
- * @returns {Promise<any>} 方法执行结果
- */
-Mod.prototype.main = async function (...args) {
-  let method = args[0];
-  let func = this.getMethod(method);
-  if (!func) {
-    throw new Error(`方法${method}不存在`);
-  }
-  let params = args.slice(1);
-  return await func(...params);
-};
-
-/**
- * 设置脚本方法
- * @param {object} methods 脚本方法对象
- */
-Mod.prototype.setMethods = function (methods) {
-  if (typeof methods !== 'object') {
-    throw new Error(`参数(methods)必须是对象`);
-  }
-  if (!methods) return;
-  if (!this._methods) {
-    this._methods = {};
-  }
-  for (let key in methods) {
-    this.setMethod(key, methods[key]);
-  }
-};
-
-/**
- * 设置脚本方法
- * @param {string} method 方法名
- * @param {Function} func 方法函数
- */
-Mod.prototype.setMethod = function (method, func) {
-  if (typeof method !== 'string') {
-    throw new Error(`第一个参数(method)必须是字符串`);
-  }
-  if (method === '_datas') {
-    throw new Error(`第一个参数(method)不能为_datas键`);
-  }
-  if (method === '_methods') {
-    throw new Error(`第一个参数(method)不能为_methods键`);
-  }
-  if (!func) throw new Error(`第二个参数(func)不能为空`);
-  if (typeof func !== 'function') {
-    throw new Error(`第二个参数(func)必须是函数`);
-  }
-  if (!this._methods) {
-    this._methods = {};
-  }
-  this._methods[method] = true;
-  this[method] = func;
-};
-
-/**
- * 获取方法函数
- * @param {string} method 方法名
- * @returns {Function} 方法函数
- */
-Mod.prototype.getMethod = function (method) {
-  if (typeof method !== 'string') {
-    throw new Error(`第一个参数(method)必须是字符串`);
-  }
-  return this[method];
-};
-
-/**
- * 获取数据
- * @returns {object} 数据对象
- */
-Mod.prototype.getDatas = function () {
-  let datas = this._datas;
-  let result = {};
-  for (let key in datas) {
-    result[key] = this[key];
-  }
-  return result;
-};
-
-/**
- * 获取数据
- * @returns {object} 数据对象
- */
-Mod.prototype.getData = function (key) {
-  return this[key];
-};
-
-/**
- * 设置数据
- * @param {object} datas 数据对象
- */
-Mod.prototype.setDatas = function (datas) {
-  if (typeof datas !== 'object') {
-    throw new Error(`参数(datas)必须是对象`);
-  }
-  if (!this._datas) {
-    this._datas = {};
-  }
-  for (let key in datas) {
-    this.setData(key, datas[key]);
-  }
-};
-
-/**
- * 设置数据
- * @param {string} key 数据键
- * @param {*} value 数据值
- */
-Mod.prototype.setData = function (key, value) {
-  if (typeof key !== 'string') {
-    throw new Error(`第一个参数(key)必须是字符串`);
-  }
-  if (key === '_datas') {
-    throw new Error(`第一个参数(key)不能为_datas键`);
-  }
-  if (key === '_methods') {
-    throw new Error(`第一个参数(key)不能为_methods键`);
-  }
-  if (value === undefined || value === null) throw new Error(`第二个参数(value)不能为undefined或null`);
-  if (typeof value == 'function') {
-    throw new Error(`第二个参数(value)不能为函数`);
-  }
-  this._datas[key] = typeof (value);
-  this[key] = value;
-};
-
-/**
- * 保存数据
- */
-Mod.prototype.saveDatas = function () {
-  let datas = this.getDatas();
-  let file = this.config.cache_file || './cache.json'.fullname(__dirname);
-  file.saveJson(datas);
-};
-
-/**
- * 加载数据
- */
-Mod.prototype.loadDatas = function () {
-  let file = this.config.cache_file || './cache.json'.fullname(__dirname);
-  let datas = file.loadJson();
-  this.setDatas(datas);
-};
-
-/**
- * 调用函数（核心执行方法）
- * @param {string} method 函数名
- * @param {*} params 参数集合
- * @returns {Promise<any>} 执行结果
- */
-Mod.prototype.call = async function (method, ...params) {
-  let method_func = this.getMethod(method);
-  if (typeof method_func !== 'function') return null;
-
-  let result;
-
-  try {
-    result = await this._callBefore(method, params);
-    if (result) return result;
-    result = await this._callMain(method_func, params, result);
-    result = await this._callAfter(method, params, result);
-  } catch (err) {
-    this.log('error', `执行方法 ${method} 失败: `, err);
-    return null;
-  }
-
-  return result;
-};
-
-/**
- * 执行前置钩子
- * @param {string} method 方法名
- * @param {Array} params 参数
- * @returns {Promise<any>} 前置钩子结果
- */
-Mod.prototype._callBefore = async function (method, params) {
-  let before_method = `${method}Before`;
-  let before_func = this.getMethod(before_method);
-
-  if (typeof before_func !== 'function') return undefined;
-
-  try {
-    let result = await before_func.call(this, ...params);
-    return result;
-  } catch (err) {
-    this.log('error', `执行前置钩子 ${before_method} 失败: `, err);
-    return undefined;
-  }
-};
-
-/**
- * 执行主方法
- * @param {Function} method_func 方法函数
- * @param {Array} params 参数
- * @param {any} result 前置钩子结果
- * @returns {Promise<any>} 主方法结果
- */
-Mod.prototype._callMain = async function (method_func, params, result) {
-  let ret = await method_func.call(this, ...params);
-  // 修复：如果主方法返回undefined，则使用前置钩子的结果
-  return ret !== undefined ? ret : result;
-};
-
-/**
- * 执行后置钩子
- * @param {string} method 方法名
- * @param {Array} params 参数
- * @param {any} result 主方法结果
- * @returns {Promise<any>} 后置钩子结果
- */
-Mod.prototype._callAfter = async function (method, params, result) {
-  let after_method = `${method}After`;
-  let after_func = this.getMethod(after_method);
-
-  if (typeof after_func !== 'function') return result;
-
-  try {
-    let after = await after_func.call(this, result, ...params);
-    return after !== undefined ? after : result;
-  } catch (err) {
-    this.log('error', `执行后置钩子 ${after_method} 失败: `, err);
-    return result;
-  }
-};
-
-/**
- * 销毁核心
- * @returns {object} 返回当前对象
- */
-Mod.prototype._destroyCore = async function () {
-  if(this.config.save_cache) {
-    this.saveDatas();
-  }
-  this._datas = {};
-  this._methods = {};
-};
-
-/**
- * 获取模块目录
- * @returns {string} 模块目录
- */
-Mod.prototype.getDir = function () {
-  if (!this.getParent) return '';
-  return this.getParent()?.getDir() || '';
-};
-
-module.exports = {
-  Mod
-};
+/**
+ * Mod 基础模块类
+ * 提供生命周期管理、方法/数据存储、事件系统、钩子机制等基础能力
+ * @class Mod
+ * @augments Base
+ */
+// eslint-disable-next-line mm_eslint/object-name, mm_eslint/variable-name
+var Base = require('mm_expand').Base;
+
+class Mod extends Base {
+  /**
+   * 构造函数
+   * @param {object} config 配置参数
+   * @param {string} [config.name] 模块名称
+   * @param {string} [config.lifecycle_state='created'] 初始生命周期状态
+   */
+  constructor(config) {
+    super(config);
+    this._methods = {};
+    this._datas = {};
+    this.lifecycle_state = (config && config.lifecycle_state) || 'created';
+    this.is_loaded = false;
+
+    // 父对象
+    if (config && config.parent) {
+      this.getParent = function () {
+        return config.parent;
+      };
+    }
+  }
+}
+
+// ==================== 生命周期公共方法 ====================
+
+/**
+ * 加载阶段：created → loaded
+ * @returns {Promise<void>}
+ */
+Mod.prototype.load = async function () {
+  return this._loadCore();
+};
+
+/**
+ * 初始化阶段：loaded → inited
+ * @returns {Promise<void>}
+ */
+Mod.prototype.init = async function () {
+  return this._initCore();
+};
+
+/**
+ * 启动阶段：inited → started
+ * @returns {Promise<void>}
+ */
+Mod.prototype.start = async function () {
+  return this._startCore();
+};
+
+/**
+ * 暂停阶段：started → paused
+ * @returns {Promise<void>}
+ */
+Mod.prototype.pause = async function () {
+  return this._pauseCore();
+};
+
+/**
+ * 恢复阶段：paused → started
+ * @returns {Promise<void>}
+ */
+Mod.prototype.resume = async function () {
+  return this._resumeCore();
+};
+
+/**
+ * 结束阶段：started/paused → ended
+ * @returns {Promise<void>}
+ */
+Mod.prototype.end = async function () {
+  return this._endCore();
+};
+
+/**
+ * 销毁阶段：ended → destroyed
+ * @returns {Promise<void>}
+ */
+Mod.prototype.destroy = async function () {
+  return this._destroyCore();
+};
+
+// ==================== 生命周期 Core 方法 ====================
+
+/**
+ * 加载核心
+ * 由 Drive 子类重写以添加脚本加载逻辑
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._loadCore = async function () {
+  if (this.lifecycle_state !== 'created') {
+    throw new Error('模块未创建，无法加载');
+  }
+
+  this.emit('load:before');
+
+  try {
+    // 执行加载操作，由 Drive 子类重写
+    this.lifecycle_state = 'loaded';
+    this.emit('load:success');
+  } catch (err) {
+    this.emit('load:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 初始化核心
+ * 调用 _init 钩子，Manager 类型自动调用 boot()
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._initCore = async function () {
+  if (this.lifecycle_state !== 'loaded') {
+    throw new Error('模块未加载，无法初始化');
+  }
+
+  this.emit('init:before');
+
+  try {
+    var init_hook = this.getMethod('_init');
+    if (init_hook) {
+      var result = init_hook(this);
+      if (result instanceof Promise) {
+        var timeout = new Promise((resolve, reject) => {
+          setTimeout(() => {
+            reject(new Error('初始化超时'));
+          }, 30000);
+        });
+        await Promise.race([result, timeout]);
+      }
+    }
+
+    // Manager 类型模块自动调用 boot()（在设置状态前执行）
+    if (typeof this.boot === 'function') {
+      await this.boot();
+    }
+
+    this.lifecycle_state = 'inited';
+    this.emit('init:success');
+  } catch (err) {
+    this.emit('init:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 启动核心
+ * 调用 _start 钩子，传播到子模块
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._startCore = async function () {
+  if (this.lifecycle_state !== 'inited') {
+    if (this.lifecycle_state === 'started') {
+      return;
+    }
+    throw new Error('模块未初始化，无法启动');
+  }
+
+  this.emit('start:before');
+
+  try {
+    var start_hook = this.getMethod('_start');
+    if (start_hook) {
+      var result = start_hook(this);
+      if (result instanceof Promise) {
+        var timeout = new Promise((resolve, reject) => {
+          setTimeout(() => {
+            reject(new Error('启动超时'));
+          }, 30000);
+        });
+        await Promise.race([result, timeout]);
+      }
+    }
+
+    this.lifecycle_state = 'started';
+    this.emit('start:success');
+  } catch (err) {
+    this.emit('start:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 暂停核心
+ * 调用 _pause 钩子，传播到子模块
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._pauseCore = async function () {
+  if (this.lifecycle_state !== 'started') {
+    throw new Error('模块未启动，无法暂停');
+  }
+
+  this.emit('pause:before');
+
+  try {
+    var pause_hook = this.getMethod('_pause');
+    if (pause_hook) {
+      pause_hook(this);
+    }
+
+    this.lifecycle_state = 'paused';
+    this.emit('pause:success');
+  } catch (err) {
+    this.emit('pause:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 恢复核心
+ * 调用 _resume 钩子，传播到子模块
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._resumeCore = async function () {
+  if (this.lifecycle_state !== 'paused') {
+    throw new Error('模块未暂停，无法恢复');
+  }
+
+  this.emit('resume:before');
+
+  try {
+    var resume_hook = this.getMethod('_resume');
+    if (resume_hook) {
+      resume_hook(this);
+    }
+
+    this.lifecycle_state = 'started';
+    this.emit('resume:success');
+  } catch (err) {
+    this.emit('resume:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 结束核心
+ * 调用 _end 钩子，传播到子模块
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._endCore = async function () {
+  if (this.lifecycle_state !== 'started' && this.lifecycle_state !== 'paused') {
+    throw new Error('模块未启动或暂停，无法结束');
+  }
+
+  this.emit('end:before');
+
+  try {
+    var end_hook = this.getMethod('_end');
+    if (end_hook) {
+      end_hook(this);
+    }
+
+    this.lifecycle_state = 'ended';
+    this.emit('end:success');
+  } catch (err) {
+    this.emit('end:error', err);
+    throw err;
+  }
+};
+
+/**
+ * 销毁核心
+ * 调用 _onDestroy 钩子，释放引用
+ * @returns {Promise<void>}
+ * @private
+ */
+Mod.prototype._destroyCore = async function () {
+  if (this.lifecycle_state !== 'ended') {
+    throw new Error('模块未结束，无法销毁');
+  }
+
+  this.emit('destroy:before');
+
+  try {
+    var destroy_hook = this.getMethod('_onDestroy');
+    if (destroy_hook) {
+      destroy_hook(this);
+    }
+
+    this._methods = {};
+    this._datas = {};
+    this.lifecycle_state = 'destroyed';
+    this.emit('destroy:success');
+  } catch (err) {
+    this.emit('destroy:error', err);
+    throw err;
+  }
+};
+
+// ==================== 实用方法 ====================
+
+/**
+ * 检查模块是否已加载
+ * @returns {boolean} 是否已加载
+ */
+Mod.prototype.isLoaded = function () {
+  return this.is_loaded;
+};
+
+/**
+ * 日志输出
+ * @param {string} level 日志级别
+ * @param {string} message 日志消息
+ * @param {...any} params 日志参数
+ */
+Mod.prototype.log = function (level, message) {
+  var logger = this.getLogger ? this.getLogger() : console;
+  var prefix = '[' + (this.constructor.name || 'Mod') + '.' + ((this.config && this.config.name) || '') + ']';
+  if (logger[level]) {
+    logger[level](prefix + ' ' + message);
+  } else {
+    console.log(prefix + ' [' + level + '] ' + message);
+  }
+};
+
+/**
+ * 获取事件管理器
+ * @returns {object} 事件管理器
+ */
+Mod.prototype.getEventer = function () {
+  return this._eventer || (typeof $.eventer !== 'undefined' ? $.eventer : this);
+};
+
+/**
+ * 设置事件管理器
+ * @param {object} eventer 事件管理器
+ */
+Mod.prototype.setEventer = function (eventer) {
+  this._eventer = eventer;
+};
+
+/**
+ * 触发事件
+ * @param {string} event 事件名
+ * @param {...any} args 事件参数
+ */
+Mod.prototype.emitEvent = async function (event) {
+  var eventer = this.getEventer();
+  if (eventer && eventer.emitWait) {
+    await eventer.emitWait(event);
+  } else if (eventer && eventer.emit) {
+    await eventer.emit(event);
+  } else if (this.emit) {
+    this.emit(event);
+  }
+};
+
+/**
+ * 触发事件 - 随机触发
+ * @param {string} event 事件名
+ * @param {...any} args 事件参数
+ * @returns {Promise<any>} 事件触发结果
+ */
+Mod.prototype.emitEventRace = async function (event) {
+  var eventer = this.getEventer();
+  if (eventer && eventer.emitRace) {
+    return await eventer.emitRace(event);
+  }
+  return null;
+};
+
+/**
+ * 触发事件 - 返回第一个非空结果
+ * @param {string} event 事件名
+ * @param {...any} args 事件参数
+ * @returns {Promise<any>} 事件触发结果
+ */
+Mod.prototype.emitEventFirst = async function (event) {
+  var eventer = this.getEventer();
+  if (eventer && eventer.emitFirst) {
+    return await eventer.emitFirst(event);
+  }
+  return null;
+};
+
+/**
+ * 注册事件监听
+ * @param {string} event 事件名
+ * @param {Function} callback 事件回调函数
+ */
+Mod.prototype.onEvent = function (event, callback) {
+  var eventer = this.getEventer();
+  if (eventer && eventer.on) {
+    eventer.on(event, callback);
+  }
+};
+
+/**
+ * 移除事件监听
+ * @param {string} event 事件名
+ */
+Mod.prototype.offEvent = function (event) {
+  var eventer = this.getEventer();
+  if (eventer && eventer.off) {
+    eventer.off(event);
+  }
+};
+
+/**
+ * 是否运行中
+ * @returns {boolean} 是否运行中
+ */
+Mod.prototype.isRunning = function () {
+  return this.lifecycle_state === 'started';
+};
+
+/**
+ * 重载
+ * 记录当前状态，清除缓存，重新执行生命周期到原状态
+ * @returns {Promise<void>}
+ */
+Mod.prototype.reload = async function () {
+  var state = this.lifecycle_state;
+  var priority = 0;
+  if (state === 'loaded') {
+    priority = 1;
+  } else if (state === 'inited') {
+    priority = 2;
+  } else if (state === 'started' || state === 'paused') {
+    priority = 3;
+  }
+
+  // 结束当前状态
+  if (this.lifecycle_state === 'started' || this.lifecycle_state === 'paused') {
+    await this._endCore();
+  }
+  if (this.lifecycle_state === 'ended') {
+    await this._destroyCore();
+  }
+  // 恢复为 created 以重新加载
+  this.lifecycle_state = 'created';
+
+  // 重新加载
+  if (priority >= 1) {
+    await this.load();
+  }
+  if (priority >= 2) {
+    await this.init();
+  }
+  if (priority >= 3) {
+    await this.start();
+  }
+};
+
+/**
+ * 重启
+ * 从 started 重新执行 start
+ * @returns {Promise<void>}
+ */
+Mod.prototype.restart = async function () {
+  if (this.lifecycle_state !== 'started') {
+    throw new Error('模块未启动，无法重启');
+  }
+  await this._endCore();
+  this.lifecycle_state = 'inited';
+  await this._startCore();
+};
+
+/**
+ * 主方法名
+ * @param {...any} args 方法参数
+ * @returns {Promise<any>} 方法执行结果
+ */
+Mod.prototype.main = async function () {
+  var method = arguments[0];
+  var func = this.getMethod(method);
+  if (!func) {
+    throw new Error('方法 [' + method + '] 不存在');
+  }
+  var params = Array.prototype.slice.call(arguments, 1);
+  return await func.apply(this, params);
+};
+
+// ==================== 数据管理 ====================
+
+/**
+ * 批量设置脚本方法
+ * @param {object} methods 脚本方法对象
+ */
+Mod.prototype.setMethods = function (methods) {
+  if (typeof methods !== 'object') {
+    throw new Error('参数(methods)必须是对象');
+  }
+  if (!methods) return;
+  for (var key in methods) {
+    this.setMethod(key, methods[key]);
+  }
+};
+
+/**
+ * 获取数据
+ * @param {string} key 数据键
+ * @returns {*} 数据值
+ */
+Mod.prototype.getData = function (key) {
+  return this[key];
+};
+
+/**
+ * 设置数据
+ * @param {string} key 数据键
+ * @param {*} value 数据值
+ */
+Mod.prototype.setData = function (key, value) {
+  if (typeof key !== 'string') {
+    throw new Error('第一个参数(key)必须是字符串');
+  }
+  if (key === '_datas' || key === '_methods') {
+    throw new Error('key 不能为保留键');
+  }
+  if (value === undefined || value === null) {
+    throw new Error('第二个参数(value)不能为undefined或null');
+  }
+  if (typeof value === 'function') {
+    throw new Error('第二个参数(value)不能为函数');
+  }
+  this._datas[key] = typeof value;
+  this[key] = value;
+};
+
+/**
+ * 获取所有数据
+ * @returns {object} 数据对象
+ */
+Mod.prototype.getDatas = function () {
+  var result = {};
+  for (var key in this._datas) {
+    result[key] = this[key];
+  }
+  return result;
+};
+
+/**
+ * 批量设置数据
+ * @param {object} datas 数据对象
+ */
+Mod.prototype.setDatas = function (datas) {
+  if (typeof datas !== 'object') {
+    throw new Error('参数(datas)必须是对象');
+  }
+  if (!datas) return;
+  for (var key in datas) {
+    // eslint-disable-next-line mm_eslint/function-name
+    this.setData(key, datas[key]);
+  }
+};
+
+/**
+ * 保存数据到缓存文件
+ */
+Mod.prototype.saveDatas = function () {
+  var fs = require('fs');
+  var path = require('path');
+  var file = (this.config && this.config.cache_file) || '';
+  if (!file) {
+    file = path.resolve(process.cwd(), 'cache', (this.config && this.config.name) || 'mod', 'data.json');
+  }
+  var dir = path.dirname(file);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  var data = this.getDatas();
+  fs.writeFileSync(file, JSON.stringify(data, null, 2), 'utf8');
+};
+
+/**
+ * 从缓存文件加载数据
+ */
+Mod.prototype.loadDatas = function () {
+  var fs = require('fs');
+  var path = require('path');
+  var file = (this.config && this.config.cache_file) || '';
+  if (!file) {
+    file = path.resolve(process.cwd(), 'cache', (this.config && this.config.name) || 'mod', 'data.json');
+  }
+  try {
+    if (fs.existsSync(file)) {
+      var content = fs.readFileSync(file, 'utf8');
+      var data = JSON.parse(content);
+      this.setDatas(data);
+    }
+  } catch {
+    // 文件不存在或解析失败
+  }
+};
+
+// ==================== 方法管理 ====================
+
+/**
+ * 注册方法
+ * @param {string} name 方法名
+ * @param {Function} func 函数
+ */
+Mod.prototype.setMethod = function (name, func) {
+  if (typeof name !== 'string') {
+    throw new TypeError('方法名必须是字符串');
+  }
+  if (typeof func !== 'function') {
+    throw new TypeError('方法必须是函数');
+  }
+  this._methods[name] = func;
+  this[name] = func;
+};
+
+/**
+ * 获取方法
+ * @param {string} name 方法名
+ * @returns {Function|null} 方法函数，不存在返回 null
+ */
+Mod.prototype.getMethod = function (name) {
+  return this._methods[name] || null;
+};
+
+/**
+ * 删除方法
+ * @param {string} name 方法名
+ */
+Mod.prototype.delMethod = function (name) {
+  delete this._methods[name];
+};
+
+/**
+ * 检查方法是否存在
+ * @param {string} name 方法名
+ * @returns {boolean} 是否存在
+ */
+Mod.prototype.hasMethod = function (name) {
+  return typeof this._methods[name] === 'function';
+};
+
+/**
+ * 调用方法
+ * 检查 lifecycle_state 和 method 是否存在，使用 _callBefore/_callMain/_callAfter 钩子模式
+ * @param {string} name 方法名
+ * @param {*} [params] 参数
+ * @returns {Promise<*>} 方法执行结果
+ */
+Mod.prototype.call = async function (name, params) {
+  var func = this.getMethod(name);
+  if (!func) {
+    return null;
+  }
+
+  if (this.lifecycle_state !== 'started' && this.lifecycle_state !== 'inited') {
+    return null;
+  }
+
+  var result;
+
+  try {
+    result = await this._callBefore(name, params);
+    if (result !== undefined) return result;
+    result = await this._callMain(func, params);
+    result = await this._callAfter(name, params, result);
+  } catch (err) {
+    this.log('error', '执行方法 ' + name + ' 失败: ', err);
+    return null;
+  }
+
+  return result;
+};
+
+/**
+ * 执行前置钩子
+ * 查找 methodBefore 方法并执行
+ * @param {string} method 方法名
+ * @param {*} params 参数
+ * @returns {Promise<*>} 前置钩子结果
+ * @private
+ */
+Mod.prototype._callBefore = async function (method, params) {
+  var before_method = method + 'Before';
+  var before_func = this.getMethod(before_method);
+  if (typeof before_func !== 'function') return undefined;
+
+  try {
+    return await before_func.call(this, params);
+  } catch (err) {
+    this.log('error', '执行前置钩子 ' + before_method + ' 失败: ', err);
+    return undefined;
+  }
+};
+
+/**
+ * 执行主方法
+ * @param {Function} method_func 方法函数
+ * @param {*} params 参数
+ * @returns {Promise<*>} 主方法结果
+ * @private
+ */
+Mod.prototype._callMain = async function (method_func, params) {
+  return await method_func.call(this, params);
+};
+
+/**
+ * 执行后置钩子
+ * 查找 methodAfter 方法并执行
+ * @param {string} method 方法名
+ * @param {*} params 参数
+ * @param {*} result 主方法结果
+ * @returns {Promise<*>} 后置钩子结果
+ * @private
+ */
+Mod.prototype._callAfter = async function (method, params, result) {
+  var after_method = method + 'After';
+  var after_func = this.getMethod(after_method);
+  if (typeof after_func !== 'function') return result;
+
+  try {
+    var after = await after_func.call(this, result, params);
+    return after !== undefined ? after : result;
+  } catch (err) {
+    this.log('error', '执行后置钩子 ' + after_method + ' 失败: ', err);
+    return result;
+  }
+};
+
+/**
+ * 获取模块目录
+ * @returns {string} 模块目录
+ */
+Mod.prototype.getDir = function () {
+  if (!this.getParent) return '';
+  var parent = this.getParent();
+  return parent ? parent.getDir() || '' : '';
+};
+
+module.exports = { Mod };