mm_machine 2.9.4 → 2.9.5

package/dir_scanner.js

@@ -0,0 +1,262 @@
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * DirScanner 目录检索器
+ * 独立工具类，负责扫描目录查找 JSON 配置文件
+ * 不依赖 Manager 或 Registry，可独立使用
+ */
+class DirScanner {
+  /**
+   * 构造函数
+   * @param {object} [cfg] 配置参数
+   * @param {number} [cfg.cache_ttl=30000] 缓存有效期（毫秒），默认 30 秒
+   */
+  constructor(cfg) {
+    var opts = cfg || {};
+    this._cache = new Map();
+    this._cache_ttl = opts.cache_ttl || 30000;
+  }
+}
+
+/**
+ * 规范化扫描参数
+ * 处理参数重载：options 可选，force 可以是第三个参数
+ * @param {object|boolean} opts_in 配置对象或 force 标志
+ * @param {boolean} force_in force 标志
+ * @returns {{options: object, force: boolean}} 规范化后的参数对象
+ * @private
+ */
+DirScanner.prototype._normScanOpts = function (opts_in, force_in) {
+  var opts = opts_in;
+  var force = force_in;
+  if (typeof opts === 'boolean') {
+    force = opts;
+    opts = null;
+  }
+  return { options: opts || {}, force: force || false };
+};
+
+/**
+ * 获取缓存结果
+ * @param {string} key 缓存键
+ * @returns {Array|null} 缓存结果，不存在或已过期返回 null
+ * @private
+ */
+DirScanner.prototype._getCache = function (key) {
+  var entry = this._cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.time > this._cache_ttl) {
+    this._cache.delete(key);
+    return null;
+  }
+  return entry.results;
+};
+
+/**
+ * 设置缓存
+ * @param {string} key 缓存键
+ * @param {Array} results 扫描结果
+ * @private
+ */
+DirScanner.prototype._setCache = function (key, results) {
+  this._cache.set(key, { results: results, time: Date.now() });
+};
+
+/**
+ * 递归扫描指定目录，查找匹配的 JSON 配置文件
+ * @param {string} dir 要扫描的目录路径
+ * @param {string} pattern 文件匹配模式（如 '*.json'）
+ * @param {object} [opts_in] 可选项
+ * @param {string[]} [opts_in.exclude=['node_modules', '.git']] 排除的目录名列表
+ * @param {Function} [opts_in.filter] 自定义过滤器，接收 {file, name} 对象，返回 true 表示保留
+ * @param {boolean} [force_in] 是否强制重新扫描（忽略缓存）
+ * @returns {Array<{file: string, name: string}>} 扫描结果数组
+ */
+DirScanner.prototype.scanDir = function (dir, pattern, opts_in, force_in) {
+  if (typeof dir !== 'string' || !dir) {
+    throw new TypeError('目录路径必须是字符串');
+  }
+  if (typeof pattern !== 'string' || !pattern) {
+    throw new TypeError('文件匹配模式必须是字符串');
+  }
+
+  var opts = this._normScanOpts(opts_in, force_in);
+  var force = opts.force;
+  var options = opts.options;
+
+  // 缓存检查
+  var cache_key = dir + '::' + pattern;
+  if (!force) {
+    var cached = this._getCache(cache_key);
+    if (cached) return cached;
+  }
+
+  var exclude = options.exclude || ['node_modules', '.git'];
+  var filter = options.filter || null;
+  var results = [];
+  var abs_dir = path.resolve(dir);
+
+  // 检查目录是否存在
+  if (!fs.existsSync(abs_dir)) {
+    return results;
+  }
+
+  this._scanDirRecu(abs_dir, pattern, exclude, filter, results);
+
+  // 设置缓存
+  this._setCache(cache_key, results);
+  return results;
+};
+
+/**
+ * 递归扫描目录内部方法
+ * @param {string} dir 当前目录
+ * @param {string} pattern 匹配模式
+ * @param {string[]} exclude 排除目录
+ * @param {Function|null} filter 自定义过滤器
+ * @param {Array} results 结果数组
+ * @private
+ */
+DirScanner.prototype._scanDirRecu = function (dir, pattern, exclude, filter, results) {
+  var items;
+  try {
+    // eslint-disable-next-line mm_eslint/variable-name
+    items = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (var i = 0; i < items.length; i++) {
+    var item = items[i];
+    var cur_path = path.join(dir, item.name);
+
+    if (item.isDirectory()) {
+      // 跳过排除目录
+      if (exclude.indexOf(item.name) !== -1) {
+        continue;
+      }
+      this._scanDirRecu(cur_path, pattern, exclude, filter, results);
+    } else if (item.isFile()) {
+      // 检查文件是否匹配模式
+      if (!this._matchPattern(item.name, pattern)) {
+        continue;
+      }
+
+      var name = this._extractName(cur_path);
+      var entry = { file: cur_path, name: name };
+
+      // 应用自定义过滤器
+      if (filter) {
+        if (!filter(entry)) {
+          continue;
+        }
+      }
+
+      results.push(entry);
+    }
+  }
+};
+
+/**
+ * 检查文件名是否匹配模式
+ * @param {string} filename 文件名
+ * @param {string} pattern 匹配模式（如 *.json）
+ * @returns {boolean} 是否匹配
+ * @private
+ */
+DirScanner.prototype._matchPattern = function (filename, pattern) {
+  // 简单通配符匹配
+  if (pattern === '*') return true;
+  if (pattern === '*' + path.extname(filename)) return true;
+  if (pattern === filename) return true;
+
+  // 将 * 转换为正则
+  var regex_str = '^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$';
+  return new RegExp(regex_str).test(filename);
+};
+
+/**
+ * 从 JSON 文件提取 name
+ * 优先读取 JSON 文件中的 name 字段，失败则从文件名去扩展名
+ * @param {string} file_path 文件路径
+ * @returns {string} 模块名称
+ * @private
+ */
+DirScanner.prototype._extractName = function (file_path) {
+  try {
+    var content = fs.readFileSync(file_path, 'utf8');
+    var config = JSON.parse(content);
+    if (config && config.name) {
+      return config.name;
+    }
+  } catch {
+    // JSON 解析失败，忽略
+  }
+  // 从文件名去扩展名
+  return path.basename(file_path, path.extname(file_path));
+};
+
+/**
+ * 扫描并解析 JSON 配置文件
+ * @param {string} dir 要扫描的目录路径
+ * @param {string} pattern 文件匹配模式
+ * @param {object} [options] 可选项（同 scanDir）
+ * @param {boolean} [force] 是否强制重新扫描
+ * @returns {Array<{file: string, config: object}>} 扫描结果数组，JSON 解析失败时跳过该文件
+ */
+DirScanner.prototype.scanAndParse = function (dir, pattern, options, force) {
+  var files = this.scanDir(dir, pattern, options, force);
+  var results = [];
+
+  for (var i = 0; i < files.length; i++) {
+    var entry = files[i];
+    try {
+      var content = fs.readFileSync(entry.file, 'utf8');
+      var config = JSON.parse(content);
+      results.push({ file: entry.file, config: config });
+    } catch {
+      // JSON 解析失败时跳过该文件
+      continue;
+    }
+  }
+
+  return results;
+};
+
+/**
+ * 扫描目录并一键注册到 Manager
+ * @param {string} dir 要扫描的目录路径
+ * @param {object} manager Manager 实例
+ * @param {boolean} [force] 是否强制重新扫描
+ * @returns {number} 成功注册的模块数量
+ */
+DirScanner.prototype.scanAndRegister = function (dir, manager, force) {
+  if (!manager || typeof manager.registerMod !== 'function') {
+    throw new TypeError('manager 必须包含 registerMod 方法');
+  }
+  var entries = this.scanAndParse(dir, '*.json', null, force);
+  var count = 0;
+
+  for (var i = 0; i < entries.length; i++) {
+    var entry = entries[i];
+    try {
+      manager.registerMod(entry.file, entry.config);
+      count++;
+    } catch {
+      // 单个模块注册失败不影响其他模块
+      continue;
+    }
+  }
+
+  return count;
+};
+
+/**
+ * 清除所有扫描缓存
+ */
+DirScanner.prototype.clearCache = function () {
+  this._cache.clear();
+};
+
+module.exports = { DirScanner };

package/id_gen.js

@@ -0,0 +1,138 @@
+/**
+ * IdGen 雪花算法 ID 生成器
+ * 基于雪花算法（Snowflake）的分布式唯一 ID 生成器，生成 64 位整数 ID
+ */
+class IdGen {
+  /**
+   * 构造函数
+   * @param {object} config 配置参数
+   * @param {number} config.data_center_no 数据中心编号 (0-31)
+   * @param {number} config.machine_no 机器编号 (0-31)
+   * @param {number} [config.epoch=1700000000000] 自定义起始时间戳（毫秒），默认 2023-11-15 00:00:00 UTC
+   * @param {number} [config.sequence=0] 初始序列号
+   */
+  constructor(config = {}) {
+    this.data_center_no = config.data_center_no || config.dc_id || 0;
+    this.machine_no = config.machine_no || config.worker_id || 0;
+    this.sequence = config.sequence || 0;
+    this.epoch = config.epoch || 1700000000000;
+    this.last_timestamp = -1;
+
+    this._initBits();
+  }
+}
+
+/**
+ * 获取当前时间戳
+ * @returns {number} 当前时间戳
+ */
+IdGen.prototype._timeGen = function () {
+  return Date.now();
+};
+
+/**
+ * 等待下一毫秒
+ * @param {number} last_timestamp 上次时间戳
+ * @returns {number} 新的时间戳
+ */
+IdGen.prototype._tilNextMillis = function (last_timestamp) {
+  var timestamp = this._timeGen();
+  while (timestamp <= last_timestamp) {
+    timestamp = this._timeGen();
+  }
+  return timestamp;
+};
+
+/**
+ * 初始化位运算参数
+ * @private
+ */
+IdGen.prototype._initBits = function () {
+  this.dc_id_bits = 5;
+  this.worker_id_bits = 5;
+  this.sequence_bits = 12;
+
+  this.max_dc_id = -1 ^ (-1 << this.dc_id_bits);
+  this.max_worker_id = -1 ^ (-1 << this.worker_id_bits);
+  this.sequence_mask = -1 ^ (-1 << this.sequence_bits);
+
+  this.worker_id_shift = this.sequence_bits;
+  this.dc_id_shift = this.sequence_bits + this.worker_id_bits;
+  this.timestamp_left_shift = this.sequence_bits + this.worker_id_bits + this.dc_id_bits;
+
+  if (this.data_center_no > this.max_dc_id || this.data_center_no < 0) {
+    throw new TypeError('数据中心编号必须在0-' + this.max_dc_id + '之间');
+  }
+  if (this.machine_no > this.max_worker_id || this.machine_no < 0) {
+    throw new TypeError('机器编号必须在0-' + this.max_worker_id + '之间');
+  }
+};
+
+/**
+ * 生成下一个ID
+ * @returns {string} 唯一ID
+ */
+IdGen.prototype.nextId = function () {
+  var timestamp = this._timeGen();
+
+  if (timestamp < this.last_timestamp) {
+    throw new Error('时钟回拨，拒绝生成ID');
+  }
+
+  if (this.last_timestamp === timestamp) {
+    this.sequence = (this.sequence + 1) & this.sequence_mask;
+    if (this.sequence === 0) {
+      timestamp = this._tilNextMillis(this.last_timestamp);
+    }
+  } else {
+    this.sequence = 0;
+  }
+
+  this.last_timestamp = timestamp;
+
+  var id =
+    (BigInt(timestamp - this.epoch) << BigInt(this.timestamp_left_shift)) |
+    (BigInt(this.data_center_no) << BigInt(this.dc_id_shift)) |
+    (BigInt(this.machine_no) << BigInt(this.worker_id_shift)) |
+    BigInt(this.sequence);
+
+  return id.toString();
+};
+
+/**
+ * 生成带前缀的ID
+ * @param {string} prefix 前缀
+ * @returns {string} 带前缀的唯一ID
+ */
+IdGen.prototype.generateId = function (prefix) {
+  if (typeof prefix !== 'string') {
+    throw new TypeError('前缀必须是字符串');
+  }
+  return prefix + '_' + this.nextId();
+};
+
+/**
+ * 解析ID信息
+ * @param {string} id ID字符串
+ * @returns {object} ID信息对象
+ */
+IdGen.prototype.parseId = function (id) {
+  if (typeof id !== 'string') {
+    throw new TypeError('ID必须是字符串');
+  }
+  var num = BigInt(id.replace(/^[a-zA-Z_]+_/, ''));
+  var timestamp = Number((num >> 22n) + BigInt(this.epoch));
+  var dc_id = Number((num >> 17n) & 31n);
+  var worker_id = Number((num >> 12n) & 31n);
+  var sequence = Number(num & 4095n);
+
+  return {
+    timestamp: timestamp,
+    datetime: new Date(timestamp).toISOString(),
+    data_center_no: dc_id,
+    machine_no: worker_id,
+    sequence: sequence
+  };
+};
+
+module.exports = { IdGen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_machine",
-  "version": "2.9.4",
+  "version": "2.9.5",
   "description": "A flexible Node.js plugin mechanism system for dynamic loading, management and execution of modules. Supports hot reload, lifecycle management, and modern JavaScript features.",
   "main": "index.js",
   "scripts": {
@@ -30,6 +30,10 @@
     "mod.js",
     "index.js",
     "drive.js",
+    "dir_scanner.js",
+    "id_gen.js",
+    "registry.js",
+    "word.js",
     "README.md"
   ],
   "dependencies": {

package/registry.js

@@ -0,0 +1,634 @@
+/**
+ * Registry 注册表类
+ * 持久化存储所有模块的元数据，启动时一次 IO 读取即可恢复全部模块信息
+ * @class Registry
+ * @augments Drive
+ */
+var fs = require('fs');
+var path = require('path');
+var { Drive } = require('./drive');
+
+/**
+ * 新增条目自动补全的默认值
+ */
+var defaultEntry = {
+  title: '',
+  description: '',
+  type: 'plugin',
+  version: '1.0.0',
+  sort: 100,
+  main: '',
+  enabled: true,
+  auto_start: false,
+  lazy: 'auto',
+  state: 'stopped',
+  // eslint-disable-next-line mm_eslint/variable-name
+  registered_at: '',
+  updated_at: ''
+};
+
+class Registry extends Drive {
+  /**
+   * 构造函数
+   * @param {object} manager Manager 实例（必需），用于注册模块
+   * @param {object} [cfg] 配置参数
+   * @param {string} [cfg.file] 注册表文件绝对路径，默认从 Manager 配置拼接
+   */
+  constructor(manager, cfg) {
+    var config = cfg || {};
+    super(config);
+    this._manager = manager;
+    this._data = { version: '1.0', updated_at: '', modules: [] };
+    this._file = config.file || Registry._resolveFile(manager);
+    this._save_timer = null;
+    this._dirty = false;
+  }
+}
+
+/**
+ * 解析注册表文件路径
+ * @param {object} manager Manager 实例
+ * @returns {string} 注册表文件绝对路径
+ * @private
+ * @static
+ */
+Registry._resolveFile = function (manager) {
+  // 有显式配置时直接使用
+  if (manager.config.registry_file) {
+    return path.resolve(manager.dir || process.cwd(), manager.config.registry_file);
+  }
+  // 默认：data/register/{构造函数名}_{config.name}.json
+  var base_dir = path.resolve(manager.dir || process.cwd(), 'data/register');
+  var class_name = manager.constructor.name || 'Manager';
+  var mod_name = manager.config.name || 'default';
+  return path.join(base_dir, class_name + '_' + mod_name + '.json');
+};
+
+// ==================== 数据加载/保存 ====================
+
+/**
+ * 从文件加载注册表数据
+ * 使用 require() 加载（支持缓存），文件不存在返回空数据结构
+ * @returns {object} 注册表数据 { version, modules[] }
+ */
+Registry.prototype.load = function () {
+  try {
+    if (fs.existsSync(this._file)) {
+      var data = require(this._file);
+      if (data && data.modules) {
+        this._data = data;
+        return this._data;
+      }
+    }
+  } catch {
+    // 文件不存在或解析失败，使用空数据
+  }
+  this._data = { version: '1.0', updated_at: '', modules: [] };
+  return this._data;
+};
+
+/**
+ * 保存注册表数据到文件
+ * 防抖保存（500ms 内多次调用只写一次），写完后清除 require.cache
+ */
+Registry.prototype.save = function () {
+  this._dirty = true;
+
+  if (this._save_timer) {
+    return;
+  }
+
+  this._save_timer = setTimeout(() => {
+    this._save_timer = null;
+    this._flushSave();
+  }, 500);
+};
+
+/**
+ * 立即写入文件
+ * @private
+ */
+Registry.prototype._flushSave = function () {
+  if (!this._dirty) {
+    return;
+  }
+
+  this._data.updated_at = new Date().toISOString();
+
+  try {
+    var dir = path.dirname(this._file);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(this._file, JSON.stringify(this._data, null, 2), 'utf8');
+
+    // 清除 require.cache 确保下次 load 读取最新数据
+    try {
+      delete require.cache[require.resolve(this._file)];
+    } catch {
+      // 忽略
+    }
+
+    this._dirty = false;
+  } catch {
+    // 保存失败，记录错误
+  }
+};
+
+// ==================== 查询方法 ====================
+
+/**
+ * 获取所有注册表项的浅拷贝数组
+ * @returns {Array<object>} 注册表项数组
+ */
+Registry.prototype.getAllEntries = function () {
+  return this._data.modules.slice();
+};
+
+/**
+ * 按名称获取单个注册表项
+ * @param {string} name 模块名称
+ * @returns {object|null} 注册表项，不存在返回 null
+ */
+Registry.prototype.getEntry = function (name) {
+  var modules = this._data.modules;
+  for (var i = 0; i < modules.length; i++) {
+    if (modules[i].name === name) {
+      return modules[i];
+    }
+  }
+  return null;
+};
+
+/**
+ * 获取注册表项数量
+ * @returns {number} 数量
+ */
+Registry.prototype.getEntryCount = function () {
+  return this._data.modules.length;
+};
+
+/**
+ * 检查注册表项是否存在
+ * @param {string} name 模块名称
+ * @returns {boolean} 是否存在
+ */
+Registry.prototype.hasEntry = function (name) {
+  return this.getEntry(name) !== null;
+};
+
+// ==================== 增删改方法 ====================
+
+/**
+ * 添加注册表项
+ * 自动补全缺失字段，然后保存
+ * @param {object} data 注册表项数据
+ */
+Registry.prototype.addEntry = function (data) {
+  if (!data || !data.name) {
+    throw new TypeError('注册表项必须包含 name 字段');
+  }
+
+  if (this.hasEntry(data.name)) {
+    return;
+  }
+
+  var now = new Date().toISOString();
+  var entry = {
+    ...defaultEntry,
+    ...data,
+    // eslint-disable-next-line mm_eslint/variable-name
+    registered_at: data.registered_at || now,
+    updated_at: now
+  };
+
+  this._data.modules.push(entry);
+  this.save();
+};
+
+/**
+ * 更新注册表项
+ * 部分合并，只覆盖 data 中存在的字段
+ * @param {string} name 模块名称
+ * @param {object} data 要更新的字段
+ */
+Registry.prototype.updateEntry = function (name, data) {
+  if (!data) {
+    return;
+  }
+
+  var modules = this._data.modules;
+  for (var i = 0; i < modules.length; i++) {
+    if (modules[i].name === name) {
+      for (var k in data) {
+        modules[i][k] = data[k];
+      }
+      modules[i].updated_at = new Date().toISOString();
+      this.save();
+      return;
+    }
+  }
+};
+
+/**
+ * 移除注册表项并保存
+ * @param {string} name 模块名称
+ */
+Registry.prototype.removeEntry = function (name) {
+  var modules = this._data.modules;
+  for (var i = 0; i < modules.length; i++) {
+    if (modules[i].name === name) {
+      modules.splice(i, 1);
+      this.save();
+      return;
+    }
+  }
+};
+
+// ==================== 自启动管理 ====================
+
+/**
+ * 设置模块是否自启动
+ * @param {string} name 模块名称
+ * @param {boolean} flag 是否自启动
+ */
+Registry.prototype.setAutoStart = function (name, flag) {
+  this.updateEntry(name, { auto_start: !!flag });
+};
+
+/**
+ * 获取所有自启动模块列表
+ * @returns {Array<object>} 自启动模块列表
+ */
+Registry.prototype.getAutoStartList = function () {
+  var modules = this._data.modules;
+  var list = [];
+  for (var i = 0; i < modules.length; i++) {
+    if (modules[i].auto_start) {
+      list.push(modules[i]);
+    }
+  }
+  return list;
+};
+
+// ==================== 核心操作 ====================
+
+/**
+ * 同步注册表数据到 Manager
+ * 遍历 _data.modules，从注册表数据直接创建模块实例（0 IO）
+ * 已存在的模块跳过（不重复创建）
+ */
+Registry.prototype.syncToManager = function () {
+  var modules = this._data.modules;
+  for (var i = 0; i < modules.length; i++) {
+    var entry = modules[i];
+
+    // 跳过 config_file 不存在的模块
+    if (entry.config_file && !fs.existsSync(entry.config_file)) {
+      continue;
+    }
+
+    if (this._manager && typeof this._manager.registerModEx === 'function') {
+      this._manager.registerModEx(entry);
+    }
+  }
+};
+
+/**
+ * 启动自启动模块
+ * 遍历 getAutoStartList()，调用 mod.load() 加载，
+ * 根据 lazy 策略决定是否继续 init/start
+ * @returns {Promise<void>}
+ */
+Registry.prototype.startAutoStart = async function () {
+  var list = this.getAutoStartList();
+
+  for (var i = 0; i < list.length; i++) {
+    var entry = list[i];
+    var mod = this._manager ? this._manager.getMod(entry.name) : null;
+    if (!mod) {
+      continue;
+    }
+
+    try {
+      // 加载模块
+      await mod.load();
+
+      // 根据 lazy 策略决定是否继续
+      if (this._shouldContinue(entry)) {
+        await mod.init();
+        await mod.start();
+      }
+    } catch {
+      // 单个模块启动失败不影响其他模块
+    }
+  }
+};
+
+/**
+ * 判断是否继续推进生命周期（init + start）
+ * @param {object} entry 注册表项
+ * @returns {boolean} 是否继续
+ * @private
+ */
+Registry.prototype._shouldContinue = function (entry) {
+  var lazy = entry.lazy !== undefined ? entry.lazy : 'auto';
+
+  if (lazy === false) {
+    return true;
+  }
+  if (lazy === 'auto') {
+    var mgr_lazy = this._manager ? this._manager.config.lazy_load : false;
+    return mgr_lazy === false || mgr_lazy === 'auto';
+  }
+  return false;
+};
+
+/**
+ * 启动引导
+ * load() → syncToManager() → 注册表为空时扫描 → startAutoStart() → save()
+ * @returns {Promise<void>}
+ */
+Registry.prototype.boot = async function () {
+  // 1. 加载注册表文件
+  this.load();
+
+  // 2. 注册模块到 Manager
+  this.syncToManager();
+
+  // 3. 注册表为空时扫描文件系统（首次启动）
+  // 实际扫描由 Manager.boot() 在调用 registry.boot() 后处理
+
+  // 4. 启动自启动模块
+  await this.startAutoStart();
+
+  // 5. 保存注册表
+  this.save();
+};
+
+/**
+ * 一键注册多个模块
+ * @param {Array<string|object>} files 文件路径数组或 {file, config} 对象数组
+ * @returns {number} 成功注册的模块数量
+ */
+Registry.prototype.registerAll = function (files) {
+  if (!files || !Array.isArray(files)) {
+    return 0;
+  }
+
+  var count = 0;
+
+  for (var i = 0; i < files.length; i++) {
+    if (this._registerOne(files[i])) {
+      count++;
+    }
+  }
+
+  return count;
+};
+
+/**
+ * 注册单个文件条目
+ * @param {string|object} item 文件路径或 {file, config} 对象
+ * @returns {boolean} 是否注册成功
+ * @private
+ */
+// eslint-disable-next-line complexity, max-lines-per-function
+Registry.prototype._registerOne = function (item) {
+  var file_path = '';
+  var cfg = null;
+
+  if (typeof item === 'string') {
+    file_path = item;
+  } else if (item && item.file) {
+    file_path = item.file;
+    cfg = item.config || null;
+  } else {
+    return false;
+  }
+
+  try {
+    // 未提供配置时从文件读取
+    if (!cfg) {
+      var content = fs.readFileSync(file_path, 'utf8');
+      cfg = JSON.parse(content);
+    }
+
+    if (!cfg || !cfg.name) {
+      return false;
+    }
+
+    var entry = {
+      name: cfg.name,
+      title: cfg.title || '',
+      description: cfg.description || '',
+      type: cfg.type || 'plugin',
+      version: cfg.version || '1.0.0',
+      sort: cfg.sort || 100,
+      config_file: file_path,
+      main: cfg.main || '',
+      enabled: cfg.enabled !== false,
+      auto_start: !!cfg.auto_start,
+      lazy: cfg.lazy !== undefined ? cfg.lazy : 'auto'
+    };
+
+    this.addEntry(entry);
+
+    if (this._manager && typeof this._manager.registerModEx === 'function') {
+      this._manager.registerModEx(entry);
+    }
+
+    return true;
+  } catch {
+    // 单个模块注册失败不影响其他模块
+    return false;
+  }
+};
+
+/**
+ * 获取全量模块目录
+ * 三步交叉比对：扫描文件系统 → 交叉比对注册表 → 补充运行时状态
+ * @param {object} scanner DirScanner 实例
+ * @param {string[]} dirs 要扫描的目录列表
+ * @param {boolean} [force] 是否强制重新扫描文件系统
+ * @returns {Array<object>} 全量目录列表
+ */
+Registry.prototype.getCatalog = function (scanner, dirs, force) {
+  if (!scanner || typeof scanner.scanAndParse !== 'function') {
+    throw new TypeError('scanner 必须包含 scanAndParse 方法');
+  }
+  if (!dirs || !Array.isArray(dirs)) {
+    return [];
+  }
+
+  // 1. 扫描文件系统
+  var file_dict = this._scanFileSystem(scanner, dirs, force);
+
+  // 2. 与注册表交叉比对
+  var registry_dict = this._buildRegistryMap();
+
+  // 3. 构建全量目录
+  var result = this._buildCatalog(file_dict, registry_dict);
+
+  // 4. 补充注册表中有但文件系统中不存在的模块
+  this._appendMissingModules(result.catalog, result.processed, registry_dict);
+
+  return result.catalog;
+};
+
+/**
+ * 扫描文件系统，构建文件映射
+ * @param {object} scanner DirScanner 实例
+ * @param {string[]} dirs 目录列表
+ * @param {boolean} force 是否强制扫描
+ * @returns {object} 文件路径到配置的映射
+ * @private
+ */
+Registry.prototype._scanFileSystem = function (scanner, dirs, force) {
+  var file_dict = {};
+  for (var i = 0; i < dirs.length; i++) {
+    var dir = dirs[i];
+    var entries = scanner.scanAndParse(dir, '*.json', null, !!force);
+    for (var j = 0; j < entries.length; j++) {
+      var entry = entries[j];
+      file_dict[entry.file] = entry.config;
+    }
+  }
+  return file_dict;
+};
+
+/**
+ * 构建注册表名称映射
+ * @returns {object} 名称到注册表项的映射
+ * @private
+ */
+Registry.prototype._buildRegistryMap = function () {
+  var registry_dict = {};
+  var reg_modules = this._data.modules;
+  for (var k = 0; k < reg_modules.length; k++) {
+    var reg = reg_modules[k];
+    registry_dict[reg.name] = reg;
+  }
+  return registry_dict;
+};
+
+/**
+ * 从文件系统扫描结果构建目录条目
+ * @param {object} file_dict 文件映射
+ * @param {object} registry_dict 注册表映射
+ * @returns {Array} 目录条目列表
+ * @private
+ */
+Registry.prototype._buildCatalog = function (file_dict, registry_dict) {
+  var catalog = [];
+  var processed = {};
+
+  for (var file_path in file_dict) {
+    var cfg = file_dict[file_path];
+    var name = cfg.name || path.basename(file_path, path.extname(file_path));
+    var reg_ref = registry_dict[name] || null;
+
+    var item = {
+      name: name,
+      title: cfg.title || '',
+      type: cfg.type || 'plugin',
+      sort: cfg.sort || 100,
+      config_file: file_path,
+      main: cfg.main || '',
+      registered: !!reg_ref,
+      auto_start: reg_ref ? !!reg_ref.auto_start : false,
+      lazy: reg_ref ? reg_ref.lazy : 'auto',
+      // eslint-disable-next-line mm_eslint/variable-name
+      lifecycle_state: null,
+      file_exists: true,
+      status: 'unregistered'
+    };
+
+    this._addRuntimeState(item, reg_ref, name);
+
+    catalog.push(item);
+    processed[name] = true;
+  }
+
+  return { catalog: catalog, processed: processed };
+};
+
+/**
+ * 补充运行时状态
+ * @param {object} item 目录条目
+ * @param {object|null} reg_ref 注册表项
+ * @param {string} name 模块名称
+ * @private
+ */
+Registry.prototype._addRuntimeState = function (item, reg_ref, name) {
+  if (!reg_ref || !this._manager) {
+    return;
+  }
+
+  var mod = this._manager.getMod(name);
+  if (mod) {
+    // eslint-disable-next-line no-param-reassign
+    item.lifecycle_state = mod.lifecycle_state;
+    // eslint-disable-next-line no-param-reassign
+    item.status = Registry._calcStatus(mod.lifecycle_state);
+  } else {
+    // eslint-disable-next-line no-param-reassign
+    item.status = 'stopped';
+  }
+};
+
+/**
+ * 追加注册表中有但文件系统中不存在的模块
+ * @param {Array} catalog 目录列表
+ * @param {object} processed 已处理模块名称集合
+ * @param {object} registry_dict 注册表映射
+ * @private
+ */
+// eslint-disable-next-line complexity
+Registry.prototype._appendMissingModules = function (catalog, processed, registry_dict) {
+  var reg_modules = this._data.modules;
+
+  for (var n = 0; n < reg_modules.length; n++) {
+    var reg = reg_modules[n];
+    if (processed[reg.name]) {
+      continue;
+    }
+
+    var mod = this._manager ? this._manager.getMod(reg.name) : null;
+    catalog.push({
+      name: reg.name,
+      title: reg.title || '',
+      type: reg.type || 'plugin',
+      sort: reg.sort || 100,
+      config_file: reg.config_file || '',
+      main: reg.main || '',
+      registered: true,
+      auto_start: !!reg.auto_start,
+      lazy: reg.lazy || 'auto',
+      // eslint-disable-next-line mm_eslint/variable-name
+      lifecycle_state: mod ? mod.lifecycle_state : null,
+      file_exists: false,
+      status: 'file_missing'
+    });
+  }
+};
+
+/**
+ * 根据 lifecycle_state 计算状态
+ * @param {string} state 生命周期状态
+ * @returns {string} 状态值
+ * @private
+ * @static
+ */
+Registry._calcStatus = function (state) {
+  switch (state) {
+    case 'started':
+      return 'running';
+    case 'paused':
+      return 'paused';
+    default:
+      return 'stopped';
+  }
+};
+
+module.exports = { Registry };

package/word.js

@@ -0,0 +1,209 @@
+/**
+ * Word 命名格式转换工具类
+ * 所有方法均为静态方法，无需实例化
+ */
+class Word {
+  /**
+   * 构造函数
+   */
+  constructor() {}
+}
+
+/**
+ * 分割单词
+ * @param {string} name 名称
+ * @returns {Array} 单词数组
+ */
+Word.splitWords = function (name) {
+  if (!name || name.length === 0) {
+    return [];
+  }
+
+  var words = [];
+  var current_word = '';
+  var last_char_type = null;
+
+  for (var i = 0; i < name.length; i++) {
+    var char = name[i];
+    var char_info = Word._getCharInfo(char);
+
+    // 处理下划线和数字
+    if (char_info.is_under || char_info.is_digit) {
+      last_char_type = Word._handleSepa(words, current_word, char, char_info);
+      current_word = '';
+      continue;
+    }
+
+    // 处理第一个字符
+    if (current_word.length === 0) {
+      current_word = char;
+      last_char_type = char_info.type;
+      continue;
+    }
+
+    // 处理字符转换
+    var result = Word._handleCharTran(words, current_word, char, last_char_type, char_info.type);
+    words = result.words;
+    current_word = result.current_word;
+    last_char_type = char_info.type;
+  }
+
+  // 添加最后一个单词
+  if (current_word.length > 0) {
+    words.push(current_word);
+  }
+
+  return words;
+};
+
+/**
+ * 获取字符信息
+ * @param {string} char 字符
+ * @returns {object} 字符信息
+ * @private
+ */
+Word._getCharInfo = function (char) {
+  var is_upper = char >= 'A' && char <= 'Z';
+  var is_lower = char >= 'a' && char <= 'z';
+  var is_digit = char >= '0' && char <= '9';
+  var type = is_upper ? 'upper' : is_lower ? 'lower' : is_digit ? 'digit' : 'other';
+  return { is_upper, is_lower, is_digit, is_under: char === '_', type };
+};
+
+/**
+ * 处理分隔符
+ * @param {Array} words 单词数组
+ * @param {string} current_word 当前单词
+ * @param {string} char 字符
+ * @param {object} char_info 字符信息
+ * @returns {string} 新的字符类型
+ * @private
+ */
+Word._handleSepa = function (words, current_word, char, char_info) {
+  if (current_word.length > 0) {
+    words.push(current_word);
+  }
+  if (char_info.is_digit) {
+    words.push(char);
+    return 'digit';
+  }
+  return 'underscore';
+};
+
+/**
+ * 处理字符转换
+ * @param {Array} words 单词数组
+ * @param {string} current_word 当前单词
+ * @param {string} char 字符
+ * @param {string} last_type 上一个字符类型
+ * @param {string} current_type 当前字符类型
+ * @returns {object} 处理结果
+ * @private
+ */
+Word._handleCharTran = function (words, current_word, char, last_type, current_type) {
+  var is_last_letter = last_type === 'upper' || last_type === 'lower';
+  var is_current_letter = current_type === 'upper' || current_type === 'lower';
+
+  if (!is_last_letter || !is_current_letter) {
+    return { words, current_word: current_word + char };
+  }
+
+  if (last_type === 'upper' && current_type === 'lower') {
+    // 大写转小写
+    if (current_word.length > 1) {
+      var last_char = current_word[current_word.length - 1];
+      words.push(current_word.substring(0, current_word.length - 1));
+      return { words, current_word: last_char + char };
+    }
+    return { words, current_word: current_word + char };
+  }
+
+  if (last_type === 'lower' && current_type === 'upper') {
+    // 小写转大写
+    words.push(current_word);
+    return { words, current_word: char };
+  }
+
+  // 相同类型
+  return { words, current_word: current_word + char };
+};
+
+/**
+ * 驼峰转蛇形
+ * @param {string} name 名称
+ * @returns {string} 小写蛇形命名
+ */
+Word.camelToSnake = function (name) {
+  var words = Word.splitWords(name);
+  for (var i = 0; i < words.length; i++) {
+    words[i] = words[i].toLowerCase();
+  }
+  return words.join('_');
+};
+
+/**
+ * 蛇形转驼峰
+ * @param {string} name 名称
+ * @returns {string} 小驼峰命名
+ */
+Word.snakeToCamel = function (name) {
+  var words = Word.splitWords(name);
+  for (var i = 0; i < words.length; i++) {
+    words[i] = words[i].toLowerCase();
+    if (i > 0) {
+      words[i] = words[i].charAt(0).toUpperCase() + words[i].substring(1);
+    }
+  }
+  return words.join('');
+};
+
+/**
+ * 大驼峰转蛇形
+ * @param {string} name 名称
+ * @returns {string} 小写蛇形命名
+ */
+Word.pascalToSnake = function (name) {
+  var words = Word.splitWords(name);
+  for (var i = 0; i < words.length; i++) {
+    words[i] = words[i].toLowerCase();
+  }
+  return words.join('_');
+};
+
+/**
+ * 蛇形转大驼峰
+ * @param {string} name 名称
+ * @returns {string} 大驼峰命名
+ */
+Word.snakeToPascal = function (name) {
+  var words = Word.splitWords(name);
+  for (var i = 0; i < words.length; i++) {
+    words[i] = words[i].toLowerCase();
+    words[i] = words[i].charAt(0).toUpperCase() + words[i].substring(1);
+  }
+  return words.join('');
+};
+
+/**
+ * 驼峰转短横线
+ * @param {string} name 名称
+ * @returns {string} 短横线命名
+ */
+Word.camelToKebab = function (name) {
+  var words = Word.splitWords(name);
+  for (var i = 0; i < words.length; i++) {
+    words[i] = words[i].toLowerCase();
+  }
+  return words.join('-');
+};
+
+/**
+ * 蛇形转短横线
+ * @param {string} name 名称
+ * @returns {string} 短横线命名
+ */
+Word.snakeToKebab = function (name) {
+  return name.replace(/_/g, '-');
+};
+
+module.exports = { Word };