mm_machine 2.9.3 → 2.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_machine",
-  "version": "2.9.3",
+  "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,13 +30,17 @@
     "mod.js",
     "index.js",
     "drive.js",
+    "dir_scanner.js",
+    "id_gen.js",
+    "registry.js",
+    "word.js",
     "README.md"
   ],
   "dependencies": {
     "@prettier/sync": "^0.6.1",
     "mm_config": "^2.4.5",
     "mm_hot_reload": "^1.4.2",
-    "mm_tpl": "^2.6.3"
+    "mm_tpl": "^2.6.4"
   },
   "devDependencies": {
     "eslint": "^10.7.0",

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