mm_scanner 0.0.0-stage → 1.0.1

package/example/data/app/app.json

@@ -0,0 +1,5 @@
+{
+  "name": "demo_app",
+  "version": "1.0.0",
+  "description": "示例应用配置"
+}

package/example/data/config/db.json

@@ -0,0 +1,4 @@
+{
+  "host": "127.0.0.1",
+  "port": 3306
+}

package/example/data/config/logger.js

@@ -0,0 +1,3 @@
+module.exports = {
+  level: 'info'
+};

package/example/data/dist/build.json

@@ -0,0 +1,3 @@
+{
+  "name": "build_artifact"
+}

package/example/data/readme.txt

@@ -0,0 +1 @@
+演示文件，不会被默认配置扫描

package/example/demo.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const path = require('path');
+const { Scanner, scannerAdmin } = require('../index');
+
+/**
+ * 使用示例：扫描 example/data 目录并按多种方式检索文件
+ */
+function demo() {
+  const dir = path.join(__dirname, 'data');
+
+  // 1. 创建扫描器，默认只扫描 .json，并忽略 node_modules 与 .git
+  const scanner = new Scanner();
+  console.log('=== 默认配置 ===');
+  console.log('  扩展名: ' + scanner.extensions.join(', '));
+  console.log('  忽略目录: ' + scanner.config.ignore.join(', '));
+
+  // 2. 扫描目录，可重复调用（仅首次生效）
+  scanner.scan(dir);
+  console.log('=== 扫描结果 ===');
+  console.log('  基目录: ' + scanner.baseDir);
+  console.log('  文件数: ' + scanner.size);
+  for (const key of scanner.keys()) {
+    console.log('  ' + key);
+  }
+
+  // 3. 按 key 查询，key 可省略扩展名
+  console.log('=== 按 key 查询 ===');
+  console.log('  元信息: ' + JSON.stringify(scanner.get('app/app')));
+  console.log('  绝对路径: ' + scanner.getPath('config/db'));
+  console.log('  是否存在 config/logger: ' + scanner.has('config/logger'));
+
+  // 4. 按扩展名、目录、层级筛选
+  console.log('=== 分类检索 ===');
+  console.log('  .json 文件: ' + scanner.getByExt('.json').length + ' 个');
+  console.log('  config 目录: ' + scanner.getByDir('config').map((f) => f.key).join(', '));
+  console.log('  一级子目录: ' + scanner.dirTypes().join(', '));
+  console.log('  扩展名类型: ' + scanner.extTypes().join(', '));
+
+  // 5. 自定义扩展名与忽略目录
+  const custom = new Scanner({ extensions: ['json', 'js'], ignore: ['dist'] });
+  custom.scan(dir);
+  console.log('=== 自定义配置 ===');
+  console.log('  文件数: ' + custom.size);
+  console.log('  文件列表: ' + custom.keys().join(', '));
+  console.log('  dist 目录已被忽略: ' + (custom.getByDir('dist').length === 0));
+
+  // 6. 文件变化后重新扫描
+  custom.rescan();
+  console.log('=== 重新扫描 ===');
+  console.log('  文件数: ' + custom.size);
+
+  // 7. 通过 admin 按作用域复用扫描器实例
+  const os_scanner = scannerAdmin('os', { extensions: ['json'] });
+  const demo_scanner = scannerAdmin('demo');
+  console.log('=== 作用域实例 ===');
+  console.log('  os 实例类型正确: ' + (os_scanner instanceof Scanner));
+  console.log('  重复获取 os 实例复用缓存: ' + (scannerAdmin('os') === os_scanner));
+  console.log('  demo 实例与 os 实例相互独立: ' + (demo_scanner !== os_scanner));
+}
+
+demo();

package/index.js

@@ -0,0 +1,16 @@
+const Scanner = require('./lib/scanner');
+const Admin = require('mm_corejs').Admin;
+
+const admin = new Admin();
+admin.setClass(Scanner);
+
+module.exports = {
+  Scanner,
+  admin,
+  scannerAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/scanner.js

@@ -0,0 +1,915 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/* 扫描结果缓存：跨实例复用同一目录的遍历结果 */
+const _scan_cache = new Map();
+/* 目录监听器：缓存键 -> { watcher, timer, pending } */
+const _watchers = new Map();
+/* 处于监听状态的实例：缓存键 -> Set<Scanner> */
+const _instances = new Map();
+/* 缓存条目上限，超出后整体清空 */
+const _CACHE_MAX = 200;
+/* 短时间窗口内直接复用，避免每次重复校验目录与文件的时间戳 */
+const _CACHE_TTL = 2000;
+/* 文件事件防抖窗口，合并一次写入产生的多条事件 */
+const _DEBOUNCE = 100;
+/* 内部同步方法名，仅供监听器调用 */
+const _SYNC = Symbol('mm_scanner.sync');
+/* 内部回调方法名，仅供监听器调用 */
+const _NOTIFY = Symbol('mm_scanner.notify');
+
+/* key 规范化：只统一分隔符、去首尾 /，不再剥扩展名 */
+function normalizeKey(p) {
+  return String(p)
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+/* 扩展名规范化：补点、转小写 */
+function normalizeExt(ext) {
+  const e = String(ext).trim().toLowerCase();
+  return e.startsWith('.') ? e : '.' + e;
+}
+
+/**
+ * 生成扫描缓存键
+ * @param {string} dir 目录绝对路径
+ * @param {Array<string>} extensions 扩展名数组
+ * @param {Array<string>} ignore 忽略目录数组
+ * @returns {string} 缓存键
+ * @private
+ */
+function _cacheKey(dir, extensions, ignore) {
+  return [dir, extensions.join(','), ignore.join(',')].join('\u0001');
+}
+
+/**
+ * 构造单个文件的条目元信息
+ * @param {string} base_dir 扫描根目录绝对路径
+ * @param {string} abs_path 文件绝对路径
+ * @returns {{ key: string, absPath: string, relPath: string, dir: string, name: string, ext: string }} 条目
+ * @private
+ */
+function _createItem(base_dir, abs_path) {
+  const rel_path = path.relative(base_dir, abs_path).replace(/\\/g, '/');
+  const ext = path.extname(rel_path).toLowerCase();
+  const dir_part = path.posix.dirname(rel_path);
+  return {
+    key: normalizeKey(rel_path),
+    absPath: abs_path,
+    relPath: rel_path,
+    dir: dir_part === '.' ? '' : dir_part,
+    name: path.basename(rel_path, ext),
+    ext,
+  };
+}
+
+/**
+ * 判断相对路径是否位于忽略目录内
+ * @param {string} rel_path 相对路径
+ * @param {Array<string>} ignore 忽略目录数组
+ * @returns {boolean} 命中忽略目录返回 true
+ * @private
+ */
+function _isIgnored(rel_path, ignore) {
+  const parts = rel_path.split('/');
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (ignore.includes(parts[i])) return true;
+  }
+  return false;
+}
+
+/**
+ * 递归遍历目录并写入条目
+ * @param {string} dir 当前目录绝对路径
+ * @param {string} base_dir 扫描根目录绝对路径
+ * @param {{ extensions: string[], ignore: string[] }} config 扫描配置
+ * @param {Map<string, object>} files 条目容器
+ * @param {Array<string>} dirs 遍历过的目录，用于记录与缓存校验
+ * @returns {void}
+ * @private
+ */
+function _walkDir(dir, base_dir, config, files, dirs) {
+  dirs.push(dir);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const full_path = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (config.ignore.includes(entry.name)) continue;
+      _walkDir(full_path, base_dir, config, files, dirs);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+
+    const item = _createItem(base_dir, full_path);
+    if (!config.extensions.includes(item.ext)) continue;
+    files.set(item.key, item);
+  }
+}
+
+/**
+ * 获取路径的修改时间
+ * @param {string} target 文件或目录路径
+ * @returns {number} 毫秒时间戳，读取失败返回 -1
+ * @private
+ */
+function _getMtime(target) {
+  try {
+    return fs.statSync(target).mtimeMs;
+  } catch {
+    return -1;
+  }
+}
+
+/**
+ * 校验缓存是否有效
+ * @description 目录时间戳变化表示增删条目，文件时间戳变化表示内容修改
+ * @param {object} cache 缓存项
+ * @returns {boolean} 全部未变化返回 true
+ * @private
+ */
+function _isCacheValid(cache) {
+  for (let i = 0; i < cache.dirs.length; i++) {
+    if (_getMtime(cache.dirs[i]) !== cache.dir_mtimes[i]) {
+      return false;
+    }
+  }
+  for (let i = 0; i < cache.items.length; i++) {
+    if (_getMtime(cache.items[i].absPath) !== cache.file_mtimes[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * 读取仍然有效的缓存
+ * @param {string} key 缓存键
+ * @returns {object|null} 缓存项，不存在或已失效返回 null
+ * @private
+ */
+function _getCache(key) {
+  let cache = _scan_cache.get(key);
+  if (!cache) {
+    return null;
+  }
+  if (cache.watched) {
+    return cache;
+  }
+  let now = Date.now();
+  if (now - cache.time <= _CACHE_TTL) {
+    return cache;
+  }
+  if (_isCacheValid(cache)) {
+    cache.time = now;
+    return cache;
+  }
+  _scan_cache.delete(key);
+  return null;
+}
+
+/**
+ * 读取缓存项，不做有效性校验
+ * @param {string} key 缓存键
+ * @returns {object|null} 缓存项，不存在返回 null
+ * @private
+ */
+function _readCache(key) {
+  return _scan_cache.get(key) || null;
+}
+
+/**
+ * 记录缓存对应的目录与文件时间戳
+ * @param {object} cache 缓存项
+ * @returns {void}
+ * @private
+ */
+function _captureMtimes(cache) {
+  cache.dir_mtimes = [];
+  for (let i = 0; i < cache.dirs.length; i++) {
+    cache.dir_mtimes.push(_getMtime(cache.dirs[i]));
+  }
+  cache.file_mtimes = [];
+  for (let i = 0; i < cache.items.length; i++) {
+    cache.file_mtimes.push(_getMtime(cache.items[i].absPath));
+  }
+  cache.time = Date.now();
+}
+
+/**
+ * 创建缓存项
+ * @param {{ dir: string, extensions: Array<string>, ignore: Array<string>, items: Array<object>, dirs: Array<string> }} options 缓存内容
+ * @param {boolean} watched 是否已开启监听
+ * @returns {object} 缓存项
+ * @private
+ */
+function _createCache(options, watched) {
+  const items = [];
+  for (let i = 0; i < options.items.length; i++) {
+    items.push({ ...options.items[i] });
+  }
+  const cache = {
+    dir: options.dir,
+    extensions: [...options.extensions],
+    ignore: [...options.ignore],
+    items,
+    dirs: [...options.dirs],
+    watched: !!watched,
+    dir_mtimes: [],
+    file_mtimes: [],
+    time: Date.now(),
+  };
+  if (!cache.watched) {
+    _captureMtimes(cache);
+  }
+  return cache;
+}
+
+/**
+ * 写入扫描缓存
+ * @description 已有监听器时保留监听标记，避免监听期间退化回时间戳校验
+ * @param {string} key 缓存键
+ * @param {{ dir: string, extensions: Array<string>, ignore: Array<string>, items: Array<object>, dirs: Array<string> }} options 缓存内容
+ * @returns {void}
+ * @private
+ */
+function _setCache(key, options) {
+  const old = _scan_cache.get(key);
+  const watched = !!(old && old.watched);
+  if (_scan_cache.size >= _CACHE_MAX && !_scan_cache.has(key)) {
+    _clearAll();
+  }
+  _scan_cache.set(key, _createCache(options, watched));
+}
+
+/**
+ * 向缓存中新增或更新一个文件条目
+ * @param {object} cache 缓存项
+ * @param {{ key: string, absPath: string, relPath: string, dir: string, name: string, ext: string }} item 文件条目
+ * @returns {boolean} 新增返回 true，覆盖已有条目返回 false
+ * @private
+ */
+function _addItem(cache, item) {
+  const index = cache.items.findIndex((one) => one.key === item.key);
+  if (index >= 0) {
+    cache.items[index] = item;
+    return false;
+  }
+  cache.items.push(item);
+  return true;
+}
+
+/**
+ * 从缓存中移除指定条目并记录变更
+ * @param {object} cache 缓存项
+ * @param {string} key 条目键
+ * @param {Array<object>} changes 变更收集器
+ * @returns {boolean} 是否移除成功
+ * @private
+ */
+function _delItem(cache, key, changes) {
+  const index = cache.items.findIndex((one) => one.key === key);
+  if (index < 0) return false;
+  const [item] = cache.items.splice(index, 1);
+  changes.push({ type: 'unlink', key, item: { ...item } });
+  return true;
+}
+
+/**
+ * 移除同目录同文件名但扩展名不同的条目
+ * @description 文件改名后扩展名不再受支持时，需要清掉旧条目
+ * @param {object} cache 缓存项
+ * @param {{ key: string, dir: string, name: string }} item 当前文件条目
+ * @param {Array<object>} changes 变更收集器
+ * @returns {void}
+ * @private
+ */
+function _delSameName(cache, item, changes) {
+  for (let i = cache.items.length - 1; i >= 0; i--) {
+    const one = cache.items[i];
+    if (one.key === item.key || one.dir !== item.dir || one.name !== item.name) continue;
+    _delItem(cache, one.key, changes);
+  }
+}
+
+/**
+ * 按文件系统事件更新单个路径
+ * @param {object} cache 缓存项
+ * @param {string} rel_path 相对路径
+ * @param {Array<object>} changes 变更收集器
+ * @returns {boolean} 无法精确定位时返回 false，需要全量刷新
+ * @private
+ */
+function _applyPath(cache, rel_path, changes) {
+  if (!rel_path) return false;
+  if (_isIgnored(rel_path, cache.ignore)) return true;
+
+  const abs_path = path.join(cache.dir, rel_path);
+  let stat = null;
+  try {
+    stat = fs.statSync(abs_path);
+  } catch {
+    stat = null;
+  }
+
+  if (stat && stat.isDirectory()) return false;
+
+  const item = _createItem(cache.dir, abs_path);
+
+  if (!stat) {
+    return _delItem(cache, item.key, changes);
+  }
+
+  if (!stat.isFile()) return true;
+
+  if (!cache.extensions.includes(item.ext)) {
+    _delSameName(cache, item, changes);
+    return true;
+  }
+
+  const added = _addItem(cache, item);
+  changes.push({ type: added ? 'add' : 'change', key: item.key, item: { ...item } });
+  return true;
+}
+
+/**
+ * 对比两份条目集合，生成增量变更
+ * @param {Array<object>} before 变更前的条目
+ * @param {Array<object>} after 变更后的条目
+ * @returns {Array<{ type: string, key: string, item: object }>} 变更列表
+ * @private
+ */
+function _diffItems(before, after) {
+  const before_map = new Map();
+  for (let i = 0; i < before.length; i++) before_map.set(before[i].key, before[i]);
+
+  const after_map = new Map();
+  for (let i = 0; i < after.length; i++) after_map.set(after[i].key, after[i]);
+
+  const changes = [];
+  for (const [key, item] of after_map) {
+    const old = before_map.get(key);
+    if (!old) {
+      changes.push({ type: 'add', key, item: { ...item } });
+      continue;
+    }
+    if (old.absPath !== item.absPath || old.relPath !== item.relPath) {
+      changes.push({ type: 'change', key, item: { ...item } });
+    }
+  }
+  for (const [key, item] of before_map) {
+    if (!after_map.has(key)) changes.push({ type: 'unlink', key, item: { ...item } });
+  }
+  return changes;
+}
+
+/**
+ * 全量重扫缓存对应的目录
+ * @param {object} cache 缓存项
+ * @param {Array<object>} changes 变更收集器
+ * @returns {void}
+ * @private
+ */
+function _refreshCache(cache, changes) {
+  const before = cache.items;
+  const files = new Map();
+  const dirs = [];
+  _walkDir(cache.dir, cache.dir, cache, files, dirs);
+  const after = [...files.values()];
+  cache.items = after;
+  cache.dirs = dirs;
+  cache.time = Date.now();
+
+  const diff = _diffItems(before, after);
+  for (let i = 0; i < diff.length; i++) changes.push(diff[i]);
+}
+
+/**
+ * 把缓存的最新条目与变更同步到监听中的实例
+ * @param {string} key 缓存键
+ * @param {Array<object>} changes 变更列表
+ * @returns {void}
+ * @private
+ */
+function _syncInstances(key, changes) {
+  const cache = _readCache(key);
+  const set = _instances.get(key);
+  if (!cache || !set) return;
+  for (const instance of set) {
+    instance[_SYNC](cache.items, cache.dirs);
+    instance[_NOTIFY](changes);
+  }
+}
+
+/**
+ * 处理防抖窗口内累积的文件事件
+ * @param {string} key 缓存键
+ * @returns {void}
+ * @private
+ */
+function _flushChanges(key) {
+  const entry = _watchers.get(key);
+  if (!entry || !entry.pending.size) return;
+
+  const list = [...entry.pending];
+  entry.pending.clear();
+
+  const cache = _readCache(key);
+  const changes = [];
+  let need_refresh = false;
+  for (let i = 0; i < list.length; i++) {
+    if (!_applyPath(cache, list[i], changes)) {
+      need_refresh = true;
+    }
+  }
+  if (need_refresh) {
+    _refreshCache(cache, changes);
+  }
+  _syncInstances(key, changes);
+}
+
+/**
+ * 记录文件系统事件，按防抖窗口合并后处理
+ * @param {string} key 缓存键
+ * @param {string|null} filename 事件对应的相对路径，为空表示无法定位
+ * @returns {void}
+ * @private
+ */
+function _onWatchEvent(key, filename) {
+  const entry = _watchers.get(key);
+  if (!entry) return;
+
+  entry.pending.add(filename ? normalizeKey(filename) : '');
+  if (entry.timer) return;
+
+  entry.timer = setTimeout(() => {
+    entry.timer = null;
+    _flushChanges(key);
+  }, _DEBOUNCE);
+
+  if (typeof entry.timer.unref === 'function') {
+    entry.timer.unref();
+  }
+}
+
+/**
+ * 为缓存绑定目录监听器
+ * @param {string} key 缓存键
+ * @returns {boolean} 监听是否可用
+ * @private
+ */
+function _bindWatcher(key) {
+  const cache = _readCache(key);
+  if (!cache) return false;
+
+  if (_watchers.has(key)) {
+    cache.watched = true;
+    cache.dir_mtimes = [];
+    cache.file_mtimes = [];
+    return true;
+  }
+
+  let watcher = null;
+  try {
+    watcher = fs.watch(cache.dir, { recursive: true }, (event_type, filename) => {
+      _onWatchEvent(key, filename);
+    });
+  } catch {
+    return false;
+  }
+
+  cache.watched = true;
+  cache.dir_mtimes = [];
+  cache.file_mtimes = [];
+
+  if (typeof watcher.unref === 'function') watcher.unref();
+  watcher.on('error', () => _unbindWatcher(key));
+  _watchers.set(key, { watcher, timer: null, pending: new Set() });
+  return true;
+}
+
+/**
+ * 解除目录监听并恢复时间戳校验
+ * @param {string} key 缓存键
+ * @returns {void}
+ * @private
+ */
+function _unbindWatcher(key) {
+  const entry = _watchers.get(key);
+  if (entry) {
+    if (entry.timer) clearTimeout(entry.timer);
+    try {
+      entry.watcher.close();
+    } catch {
+      // 监听器已关闭时忽略
+    }
+    _watchers.delete(key);
+  }
+
+  _instances.delete(key);
+
+  const cache = _readCache(key);
+  if (cache) {
+    cache.watched = false;
+    _captureMtimes(cache);
+  }
+}
+
+/**
+ * 判断实例是否处于监听状态
+ * @param {string} key 缓存键
+ * @param {object} instance 扫描器实例
+ * @returns {boolean} 已监听返回 true
+ * @private
+ */
+function _hasInstance(key, instance) {
+  const set = _instances.get(key);
+  return !!(set && set.has(instance));
+}
+
+/**
+ * 登记监听中的实例
+ * @param {string} key 缓存键
+ * @param {object} instance 扫描器实例
+ * @returns {void}
+ * @private
+ */
+function _addInstance(key, instance) {
+  let set = _instances.get(key);
+  if (!set) {
+    set = new Set();
+    _instances.set(key, set);
+  }
+  set.add(instance);
+}
+
+/**
+ * 注销监听中的实例，最后一个实例注销时关闭监听器
+ * @param {string} key 缓存键
+ * @param {object} instance 扫描器实例
+ * @returns {void}
+ * @private
+ */
+function _delInstance(key, instance) {
+  const set = _instances.get(key);
+  if (!set) return;
+  set.delete(instance);
+  if (set.size === 0) {
+    _unbindWatcher(key);
+  }
+}
+
+/**
+ * 清空全部缓存、监听器与实例登记
+ * @returns {void}
+ * @private
+ */
+function _clearAll() {
+  const keys = [..._watchers.keys()];
+  for (let i = 0; i < keys.length; i++) {
+    _unbindWatcher(keys[i]);
+  }
+  _instances.clear();
+  _scan_cache.clear();
+}
+
+/**
+ * 合并默认配置与用户配置
+ * @param {{ extensions: string[], ignore: string[] }} default_config - 默认配置
+ * @param {{ extensions?: string[], ignore?: string[] }} config - 用户配置
+ * @returns {{ extensions: string[], ignore: string[] }} 规范化后的配置
+ */
+function createConfig(default_config, config) {
+  const extensions =
+    Array.isArray(config.extensions) && config.extensions.length
+      ? config.extensions
+      : default_config.extensions;
+  const ignore = Array.isArray(config.ignore) ? config.ignore : default_config.ignore;
+
+  return {
+    extensions: extensions.map(normalizeExt),
+    ignore: [...ignore],
+  };
+}
+
+class Scanner {
+  /**
+   * 扫描器默认配置
+   */
+  static config = {
+    /** 支持的扩展名 */
+    extensions: ['.json'],
+    /** 忽略的目录 */
+    ignore: ['node_modules', '.git'],
+  };
+
+  /** key(含扩展名) -> { key, absPath, relPath, dir, name, ext } */
+  #files = new Map();
+  #baseDir = null;
+  #scanned = false;
+  /** 本次遍历过的目录，用于缓存有效性校验 */
+  #dirs = [];
+  /** 本次扫描对应的缓存键 */
+  #cacheKey = null;
+  /** 外部变更回调 */
+  #callback = null;
+
+  /**
+   * 创建扫描器实例
+   * @param {{ extensions?: string[], ignore?: string[] }} [config] - 扫描器配置
+   */
+  constructor(config = {}) {
+    this.config = createConfig(Scanner.config, config);
+  }
+
+  /* -------- 私有 -------- */
+
+  /**
+   * 用缓存条目填充扫描结果
+   * @param {Array<object>} items 缓存中的条目
+   * @param {Array<string>} dirs 缓存中的目录列表
+   * @returns {void}
+   */
+  #fill(items, dirs) {
+    this.#files.clear();
+    for (const item of items) {
+      this.#files.set(item.key, { ...item });
+    }
+    this.#dirs = [...dirs];
+    this.#scanned = true;
+  }
+
+  /**
+   * 遍历根目录并填充扫描结果
+   * @returns {void}
+   */
+  #walkAndFill() {
+    this.#files.clear();
+    this.#dirs = [];
+    _walkDir(this.#baseDir, this.#baseDir, this.config, this.#files, this.#dirs);
+    this.#scanned = true;
+  }
+
+  /**
+   * 构造写入缓存的内容
+   * @returns {{ dir: string, extensions: Array<string>, ignore: Array<string>, items: Array<object>, dirs: Array<string> }} 缓存内容
+   */
+  #snapshot() {
+    return {
+      dir: this.#baseDir,
+      extensions: this.config.extensions,
+      ignore: this.config.ignore,
+      items: [...this.#files.values()],
+      dirs: this.#dirs,
+    };
+  }
+
+  #ensureReady() {
+    if (!this.#scanned) {
+      throw new Error('[scanner] 尚未初始化，请先在入口调用 scanner.scan(dir)');
+    }
+  }
+
+  /** 宽松解析 key：精确命中 → 按扩展名顺序尝试补全 */
+  #resolveKey(input) {
+    const norm = normalizeKey(input);
+    if (this.#files.has(norm)) return norm;
+
+    for (const ext of this.config.extensions) {
+      const tryKey = norm + ext;
+      if (this.#files.has(tryKey)) return tryKey;
+    }
+    return null;
+  }
+
+  /**
+   * 判断文件的相对目录是否命中目标目录
+   * @param {string} dir_path - 文件所在相对目录
+   * @param {string} dir_key - 规范化后的目标目录
+   * @returns {boolean} 命中返回 true，目标目录为空时视为全部命中
+   */
+  #matchDir(dir_path, dir_key) {
+    if (!dir_key) return true;
+    if (dir_key.includes('/')) {
+      return dir_path === dir_key || dir_path.endsWith('/' + dir_key);
+    }
+    return dir_path.split('/').includes(dir_key);
+  }
+
+  /* -------- 公开 API -------- */
+
+  /**
+   * 扫描目录（重复调用只生效一次）
+   * @description 优先复用其他实例的扫描缓存，命中时不再遍历目录
+   * @param {string} dir
+   * @param {{ extensions?: string[], ignore?: string[] }} [options]
+   */
+  scan = (dir, options = {}) => {
+    const resolved = path.resolve(dir);
+
+    if (this.#scanned) {
+      if (this.#baseDir !== resolved) {
+        console.warn(`[scanner] 已使用 ${this.#baseDir} 扫描过，忽略本次 scan(${resolved})`);
+      }
+      return this;
+    }
+
+    if (!fs.existsSync(resolved)) throw new Error(`[scanner] 目录不存在: ${resolved}`);
+    if (!fs.statSync(resolved).isDirectory()) throw new Error(`[scanner] 不是目录: ${resolved}`);
+
+    if (Array.isArray(options.extensions) || Array.isArray(options.ignore)) {
+      this.config = createConfig(this.config, options);
+    }
+
+    this.#baseDir = resolved;
+    this.#cacheKey = _cacheKey(resolved, this.config.extensions, this.config.ignore);
+
+    const cache = _getCache(this.#cacheKey);
+    if (cache) {
+      this.#fill(cache.items, cache.dirs);
+      return this;
+    }
+
+    this.#walkAndFill();
+    _setCache(this.#cacheKey, this.#snapshot());
+    return this;
+  };
+
+  /** 拿条目元信息（含 absPath），key 可带可不带扩展名 */
+  get = (key) => {
+    this.#ensureReady();
+    const k = this.#resolveKey(key);
+    return k ? this.#files.get(k) : undefined;
+  };
+
+  /** 拿绝对路径（给 Loader 用的最常见接口） */
+  getPath = (key) => {
+    const info = this.get(key);
+    return info ? info.absPath : undefined;
+  };
+
+  has = (key) => {
+    this.#ensureReady();
+    return this.#resolveKey(key) !== null;
+  };
+
+  keys = () => {
+    this.#ensureReady();
+    return [...this.#files.keys()];
+  };
+
+  getAll = () => {
+    this.#ensureReady();
+    return [...this.#files.values()];
+  };
+
+  /** 按"扩展名类型"筛：getByExt('.json') / getByExt('json') 都行 */
+  getByExt = (ext) => {
+    this.#ensureReady();
+    const e = normalizeExt(ext);
+    return this.getAll().filter((f) => f.ext === e);
+  };
+
+  /** 所有出现过的扩展名类型 */
+  extTypes = () => {
+    this.#ensureReady();
+    const set = new Set();
+    for (const f of this.#files.values()) set.add(f.ext);
+    return [...set];
+  };
+
+  /** 按目录筛：getByDir('config') -> data/config/**.{json,yaml,...} */
+  getByDir = (dir) => {
+    this.#ensureReady();
+    const norm = normalizeKey(dir);
+    const prefix = norm ? norm + '/' : '';
+    return this.getAll().filter((f) => f.key.startsWith(prefix));
+  };
+
+  /**
+   * 判断文件是否命中指定类型
+   * 只写扩展名（'.json' / 'json'）按扩展名匹配，写文件名（'event.json'）按文件名结尾匹配
+   * @param {{ key: string, ext: string }} file - 文件条目
+   * @param {string} ext - 扩展名或文件名
+   * @returns {boolean} 命中返回 true
+   */
+  #matchExt(file, ext) {
+    const norm = String(ext).trim().toLowerCase();
+    const bare = norm.replace(/^\./, '');
+    if (!bare.includes('.')) return file.ext === '.' + bare;
+    return file.key === bare || file.key.endsWith('/' + bare);
+  }
+
+  /**
+   * 按目录名与文件类型筛选文件
+   * 目录参数可为目录名（匹配任意层级）或相对路径（匹配路径结尾）
+   * @param {string} dir - 目录名或相对目录，如 'event_api'、'ai/event_api'
+   * @param {string} ext - 扩展名或文件名，如 '.json'、'event.json'
+   * @returns {Array<{ key: string, absPath: string, relPath: string, dir: string, name: string, ext: string }>} 命中的文件条目
+   */
+  getFileByDir = (dir, ext) => {
+    this.#ensureReady();
+    const dir_key = normalizeKey(dir);
+    return this.getAll().filter((f) => this.#matchDir(f.dir, dir_key) && this.#matchExt(f, ext));
+  };
+
+  /** 所有一级子目录名（可当作业务分类） */
+  dirTypes = () => {
+    this.#ensureReady();
+    const set = new Set();
+    for (const f of this.#files.values()) {
+      const first = f.dir.split('/')[0];
+      if (first) set.add(first);
+    }
+    return [...set];
+  };
+
+  /** 当前支持的扩展名列表 */
+  get extensions() { return [...this.config.extensions]; }
+
+  /** 重新扫描（开发环境热更新用） */
+  rescan = () => {
+    if (!this.#baseDir) throw new Error('[scanner] 尚未初始化，无法 rescan');
+    const cache = _readCache(this.#cacheKey);
+    const before = cache ? cache.items : [];
+    this.#walkAndFill();
+    _setCache(this.#cacheKey, this.#snapshot());
+    _syncInstances(this.#cacheKey, _diffItems(before, this.getAll()));
+    return this;
+  };
+
+  /**
+   * 开启目录监听，文件增删改时增量维护缓存并同步到本实例
+   * @description 监听期间不再按时间戳校验缓存；不支持递归监听的环境会静默降级
+   * @param {(changes: Array<{ type: string, key: string, item: object }>) => void} [callback] 变更回调，type 为 add/change/unlink
+   * @returns {Scanner} 当前实例
+   */
+  watch = (callback) => {
+    this.#ensureReady();
+    if (typeof callback === 'function') this.#callback = callback;
+    if (_hasInstance(this.#cacheKey, this)) return this;
+    _addInstance(this.#cacheKey, this);
+    if (!_bindWatcher(this.#cacheKey)) {
+      _delInstance(this.#cacheKey, this);
+      this.#callback = null;
+    }
+    return this;
+  };
+
+  /**
+   * 关闭本实例的目录监听并注销变更回调，最后一个实例关闭后停止监听
+   * @returns {Scanner} 当前实例
+   */
+  unwatch = () => {
+    this.#callback = null;
+    if (!this.#cacheKey) return this;
+    _delInstance(this.#cacheKey, this);
+    return this;
+  };
+
+  /**
+   * 清空全部扫描缓存
+   * @returns {void}
+   */
+  static clearCache = () => {
+    _clearAll();
+  };
+
+  get size() { return this.#files.size; }
+  get baseDir() { return this.#baseDir; }
+  /** 当前实例是否处于监听状态 */
+  get watching() { return this.#cacheKey ? _hasInstance(this.#cacheKey, this) : false; }
+
+  /**
+   * 接收监听器同步的最新条目
+   * @param {Array<object>} items 缓存中的条目
+   * @param {Array<string>} dirs 缓存中的目录列表
+   * @returns {void}
+   */
+  [_SYNC](items, dirs) {
+    this.#fill(items, dirs);
+  }
+
+  /**
+   * 把变更列表交给外部回调
+   * @param {Array<{ type: string, key: string, item: object }>} changes 变更列表
+   * @returns {void}
+   */
+  [_NOTIFY](changes) {
+    if (!this.#callback || !changes.length) return;
+    try {
+      this.#callback(changes.map((one) => ({ ...one, item: { ...one.item } })));
+    } catch (error) {
+      console.error('[scanner] watch 回调执行失败:', error);
+    }
+  }
+}
+
+/* 导出单例 + 类 */
+module.exports = Scanner;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "mm_scanner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "目录扫描器，按扩展名递归扫描目录并缓存文件元信息，支持按 key、扩展名、目录检索文件路径。",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_scanner.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_common",
+    "超级美眉",
+    "目录扫描",
+    "文件检索",
+    "scanner"
+  ],
+  "layer": "infra",
+  "group": "common",
+  "author": "邱文武",
+  "license": "ISC",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "example"
+  ],
+  "directories": {
+    "example": "example",
+    "lib": "lib"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "demo": "node example/demo.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.5"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.