mm_machine 5.0.1 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,509 +1,128 @@
1
1
  # mm_machine
2
2
 
3
- 一个灵活的Node.js插件化机制系统,用于动态加载、管理和执行模块。
3
+ Node.js 插件机制:按目录扫描受管模块,统一完成注册、生命周期编排、方法调用与热重载。
4
4
 
5
- ## 快速开始
5
+ 当前版本 6.0.0。入口导出 `{ Mod, Drive, Manager, MODE, addMethods }`,`Manager` 是日常使用的管理器类。
6
6
 
7
- ### 安装
7
+ ## 安装
8
8
 
9
9
  ```bash
10
10
  npm install mm_machine --save
11
11
  ```
12
12
 
13
- ### 目录结构
14
-
15
- 推荐的项目结构:
16
-
17
- ```
18
- my_project/
19
- ├── index.js # 主应用入口
20
- ├── app/ # 默认模块目录
21
- │ ├── module1/ # 模块1
22
- │ │ ├── config_demo.json # 配置文件 (注意命名规则)
23
- │ │ └── index.js # 模块实现
24
- │ └── module2/ # 模块2
25
- │ ├── config_demo.json # 配置文件
26
- │ └── main.js # 模块实现 (可以使用index.js或main.js)
27
- └── package.json
28
- ```
29
-
30
- ### 使用示例
13
+ ## 快速开始
31
14
 
32
15
  ```javascript
33
- const $ = require('mm_expand');
34
- const Machine = require('mm_machine');
35
-
36
- // 创建引擎实例
37
- const engine = new Machine();
16
+ const path = require('path');
17
+ const { Manager, MODE } = require('mm_machine');
38
18
 
39
- // 初始化并加载模块
40
- async function init() {
41
- // 更新配置(可选)
42
- engine.update_config_all({
43
- searchPath: './app/' // 默认路径,可自定义
19
+ async function run() {
20
+ const manager = new Manager({
21
+ name: 'demo_manager',
22
+ dir: path.join(__dirname, 'modules'),
23
+ filename: 'manager.json',
24
+ mode: MODE.PRODUCTION
44
25
  });
45
26
 
46
- // 加载所有模块
47
- await engine.loads();
48
-
49
- // 执行所有模块的main方法
50
- const results = await engine.exec('main');
51
- $.log.debug('执行结果:', results);
52
-
53
- // 获取特定模块
54
- const demo1 = engine.get('demo1');
55
- if (demo1) {
56
- $.log.debug('找到模块:', demo1.name);
57
- }
58
-
59
- $.log.debug(`已加载 ${engine.list.length} 个模块`);
60
- }
61
-
62
- // 启动应用
63
- init().catch((err) => {
64
- $.log.error('初始化失败:', err);
65
- });
66
- ```
67
-
68
- ### 创建模块
69
-
70
- **1. 创建配置文件**
71
-
72
- 在模块目录中创建 `config_demo.json` 文件(注意命名规则):
27
+ await manager.update(); // 扫描目录并注册模块
28
+ await manager.runAll('load'); // 按 sort 顺序执行生命周期
29
+ await manager.runAll('init');
30
+ await manager.runAll('start');
73
31
 
74
- ```json
75
- {
76
- "name": "demo1",
77
- "title": "测试模块1",
78
- "description": "这是第一个测试模块",
79
- "sort": 10,
80
- "state": 1,
81
- "show": 1,
82
- "options": {
83
- "debug": true,
84
- "timeout": 3000
85
- }
86
- }
87
- ```
88
-
89
- **2. 创建模块实现**
90
-
91
- 在同一目录中创建 `index.js` 或 `main.js` 文件:
32
+ console.log(await manager.main('hello', 'greet', '世界')); // 你好,世界!
33
+ console.log(await manager.callMod('hello', 'greet', 'mm_machine'));
92
34
 
93
- ```javascript
94
- const $ = require('mm_expand');
95
-
96
- /**
97
- * 主方法
98
- */
99
- async function main() {
100
- $.log.info(`[${this.name}] 测试模块执行`);
101
-
102
- // 访问模块配置
103
- const debug = this.config.debug;
104
- if (debug) {
105
- $.log.debug(`[${this.name}] 调试模式已启用`);
106
- }
107
-
108
- return {
109
- success: true,
110
- message: `${this.name} 执行成功`
111
- };
35
+ await manager.getMod('hello').do('stop');
36
+ await manager.unwatch(); // 关闭目录监听
112
37
  }
113
38
 
114
- // 导出方法
115
- module.exports = {
116
- main
117
- };
118
- ```
119
-
120
- ### 重要:文件命名规则
121
-
122
- **配置文件必须按照以下格式命名:**
123
-
39
+ run().catch(console.error);
124
40
  ```
125
- config_{type}.json
126
- ```
127
-
128
- 其中`{type}`必须与您在Engine类中设置的`this.type`属性值完全匹配。例如:
129
41
 
130
- - 如果`this.type = "demo"`,配置文件必须命名为`config_demo.json`
131
- - 如果`this.type = "plugin"`,配置文件必须命名为`config_plugin.json`
42
+ 仓库内 `example/index.js` 是可直接运行的完整示例:`npm run demo`。
132
43
 
133
- ## 完整使用示例
44
+ ## 导出 API
134
45
 
135
- ### 示例1:创建和管理基础模块
46
+ | 导出 | 说明 |
47
+ |---|---|
48
+ | `Manager` | 受管模块集合:扫描注册、生命周期编排、方法调用、监听热重载 |
49
+ | `Mod` | 受管模块基类:在 `mm_mod.Mod` 之上增加 `do` 流水线与脚本挂载 |
50
+ | `Drive` | 驱动基类:脚本加载、配置读写、模式判断 |
51
+ | `MODE` | 运行模式枚举 |
52
+ | `addMethods` | 把脚本导出的函数批量挂到实例上 |
136
53
 
137
- 以下是一个完整的示例,展示如何创建和管理基础模块:
54
+ ## 模块目录约定
138
55
 
139
- **1. 项目结构**
56
+ 清单文件名由 `filename` 指定,示例中为 `manager.json`:
140
57
 
58
+ ```text
59
+ modules/
60
+ └── hello/
61
+ ├── manager.json # 模块配置(支持 JSON5 注释)
62
+ └── index.js # 模块脚本
141
63
  ```
142
- my_project/
143
- ├── index.js # 主应用入口
144
- ├── app/ # 模块目录
145
- │ ├── demo1/ # 模块1
146
- │ │ ├── config_demo.json # 模块配置文件
147
- │ │ └── index.js # 模块实现
148
- │ └── demo2/ # 模块2
149
- │ ├── config_demo.json # 模块配置文件
150
- │ └── main.js # 模块实现
151
- └── package.json
152
- ```
153
-
154
- **2. 主应用入口 (`index.js`)**
155
-
156
- ```javascript
157
- const $ = require('mm_expand');
158
- const Machine = require('mm_machine');
159
-
160
- // 创建引擎实例
161
- const engine = new Machine();
162
-
163
- // 初始化引擎
164
- async function init() {
165
- // 加载模块
166
- await engine.loads();
167
64
 
168
- // 执行所有模块的main方法
169
- await engine.exec('main');
170
-
171
- // 获取特定模块
172
- const demo1 = engine.get('demo1');
173
- if (demo1) {
174
- $.log.debug('模块1状态:', demo1.state ? '启用' : '禁用');
175
-
176
- // 执行特定模块的自定义方法
177
- const result = await engine.exec('my_custom_method', 'demo1');
178
- $.log.debug('自定义方法结果:', result);
179
- }
180
-
181
- // 监听文件变化(热更新模式)
182
- engine.mode = 2;
183
- engine.watch();
184
-
185
- $.log.debug(`已加载 ${engine.list.length} 个模块`);
186
- }
187
-
188
- // 启动应用
189
- init().catch((err) => {
190
- $.log.error('初始化失败:', err);
191
- });
192
- ```
193
-
194
- **3. 模块配置文件示例 (`app/demo1/config_demo.json`)**
65
+ `manager.json` 必填 `name`,常用 `title` / `description` / `main` / `scope` / `state` / `sort` / `options`:
195
66
 
196
67
  ```json
197
68
  {
198
- "name": "demo1",
199
- "title": "测试模块1",
200
- "description": "这是第一个测试模块",
201
- "sort": 10,
69
+ "name": "hello",
70
+ "title": "问候模块",
71
+ "main": "./index.js",
202
72
  "state": 1,
203
- "show": 1,
73
+ "sort": 10,
204
74
  "options": {
205
- "debug": true,
206
- "timeout": 3000,
207
- "api_key": "your_api_key_here"
75
+ "greeting": { "default": "你好" }
208
76
  }
209
77
  }
210
78
  ```
211
79
 
212
- **4. 模块实现示例 (`app/demo1/index.js`)**
80
+ 脚本导出的函数挂为模块方法,非函数值挂为模块数据;`this.getOption()` / `this.setOption()` 读写选项,`this.log()` 写日志:
213
81
 
214
82
  ```javascript
215
- const $ = require('mm_expand');
216
-
217
- // 模块状态变量
218
- let counter = 0;
219
-
220
- /**
221
- * 初始化方法
222
- */
223
- async function init() {
224
- $.log.info(`[${this.name}] 模块初始化中...`);
225
- counter = 0;
226
- return true;
227
- }
228
-
229
- /**
230
- * 加载方法
231
- */
232
- async function load() {
233
- $.log.info(`[${this.name}] 模块加载中...`);
234
- // 可以在这里执行加载资源等操作
235
- return true;
236
- }
237
-
238
- /**
239
- * 主方法
240
- * @param {Object} params - 传入参数
241
- */
242
- async function main(params = {}) {
243
- $.log.info(`[${this.name}] 主方法执行,当前计数: ${counter++}`);
244
-
245
- // 访问模块配置
246
- const debug = this.config.debug;
247
- if (debug) {
248
- $.log.debug(`[${this.name}] 调试模式已启用`);
249
- }
250
-
251
- // 返回结果
252
- return {
253
- success: true,
254
- message: `${this.name} 执行成功`,
255
- count: counter,
256
- params: params
257
- };
258
- }
259
-
260
- /**
261
- * 主方法执行前钩子
262
- */
263
- async function main_before() {
264
- $.log.info(`[${this.name}] 主方法执行前处理`);
265
- return true;
266
- }
267
-
268
- /**
269
- * 主方法执行后钩子
270
- */
271
- async function main_after(result) {
272
- $.log.info(`[${this.name}] 主方法执行后处理,结果:`, result);
273
- return result;
274
- }
275
-
276
- /**
277
- * 自定义方法
278
- */
279
- async function my_custom_method() {
280
- return {
281
- custom: '这是一个自定义方法',
282
- module_name: this.name
283
- };
284
- }
285
-
286
- // 导出方法
287
83
  module.exports = {
288
- init,
289
- load,
290
- main,
291
- main_before,
292
- main_after,
293
- my_custom_method
294
- };
295
- ```
296
-
297
- ### 示例2:使用自定义模块目录
298
-
299
- 如果需要使用非默认的模块目录,可以按以下方式配置:
300
-
301
- ```javascript
302
- const engine = new Machine();
303
-
304
- // 使用自定义目录
305
- engine.update_config_all({
306
- searchPath: './custom_modules/'
307
- });
308
-
309
- // 然后加载模块
310
- await engine.loads();
311
- ```
312
-
313
- ### 示例3:实现热更新和动态管理
314
-
315
- 以下示例展示如何实现模块的热更新和动态管理:
316
-
317
- ```javascript
318
- const engine = new Machine();
319
-
320
- // 设置为热更新模式
321
- engine.mode = 2;
322
-
323
- // 初始化
324
- async function setup() {
325
- // 加载模块
326
- await engine.loads();
327
-
328
- // 开始监听文件变化
329
- engine.watch();
330
-
331
- // 定时检查模块数量
332
- setInterval(async () => {
333
- $.log.debug(`当前模块数量: ${engine.list.length}`);
334
- }, 5000);
335
-
336
- // 模拟动态管理模块
337
- setTimeout(async () => {
338
- // 重载特定模块
339
- await engine.reload('demo1');
340
- $.log.debug('已重载模块 demo1');
341
- }, 10000);
342
-
343
- setTimeout(async () => {
344
- // 卸载模块
345
- await engine.unload('demo2');
346
- $.log.debug('已卸载模块 demo2');
347
- }, 20000);
348
- }
349
-
350
- setup().catch($.log.error);
351
- ```
352
-
353
- ### 示例4:错误处理和异常捕获
354
-
355
- ```javascript
356
- const engine = new Machine();
357
-
358
- async function run() {
359
- try {
360
- // 加载模块并捕获可能的错误
361
- await engine.loads();
362
-
363
- // 安全地执行模块方法
364
- try {
365
- const result = await engine.exec('main');
366
- $.log.debug('执行结果:', result);
367
- } catch (err) {
368
- $.log.error('执行方法时出错:', err);
369
- // 继续执行,不会中断整个应用
370
- }
371
-
372
- // 单独执行特定模块并捕获可能的错误
373
- try {
374
- const demo1Result = await engine.exec('main', 'demo1');
375
- $.log.debug('demo1 执行结果:', demo1Result);
376
- } catch (err) {
377
- $.log.error('执行 demo1 时出错:', err);
378
- }
379
- } catch (err) {
380
- $.log.error('初始化失败:', err);
84
+ async _init() {
85
+ this.log('info', '模块初始化完成');
86
+ },
87
+ async greet(name) {
88
+ return `${this.getOption('greeting')},${name}!`;
89
+ },
90
+ async main(...args) {
91
+ return `main 参数:${JSON.stringify(args)}`;
381
92
  }
382
- }
383
-
384
- run();
385
- ```
386
-
387
- ## 高级功能
388
-
389
- ### 模块生命周期
390
-
391
- 每个模块支持完整的生命周期方法:
392
-
393
- - `init`: 模块初始化时调用
394
- - `load`: 模块加载时调用
395
- - `main`: 主执行方法
396
- - `main_before`: 主方法执行前的钩子
397
- - `main_after`: 主方法执行后的钩子
398
-
399
- ### 运行模式说明
400
-
401
- 系统支持4种运行模式,可通过`mode`属性设置:
402
-
403
- 1. **生产模式** (`mode = 1`): 最高性能,文件改变不会触发重新加载
404
- 2. **热更新模式** (`mode = 2`): 文件改变时自动重新加载配置和代码
405
- 3. **重载模式** (`mode = 3`): 执行完后重新加载脚本,避免变量污染
406
- 4. **热更新+重载模式** (`mode = 4`): 结合热更新和重载的特性
407
-
408
- ### 模块管理API
409
-
410
- ```javascript
411
- // 重载特定模块
412
- await engine.reload('moduleName');
413
-
414
- // 卸载模块(保留文件)
415
- await engine.unload('moduleName');
416
-
417
- // 卸载并删除模块文件
418
- await engine.unload('moduleName', true);
419
-
420
- // 保存模块配置
421
- await engine.save();
422
-
423
- // 获取特定模块
424
- const module = engine.get('moduleName');
93
+ };
425
94
  ```
426
95
 
427
- ### 路径处理
428
-
429
- - 所有相对路径都会基于模块的目录进行解析
430
- - 使用`fullname()`方法可以获取绝对路径,避免路径问题
431
-
432
- ## 常见问题与故障排除
433
-
434
- ### 1. 模块无法加载
435
-
436
- **检查项目:**
96
+ ## 生命周期与调用
437
97
 
438
- - 确认配置文件命名格式正确 (`config_{type}.json`)
439
- - 确认`type`属性与配置文件前缀匹配
440
- - 检查模块的`state`配置是否为1(启用)
441
- - 检查文件权限是否正确
98
+ - 单模块:`await mod.do('load' | 'init' | 'start' | 'stop' | 'unload' | 'destroy')`
99
+ - 批量:`await manager.runAll('load')`,按 `sort` 顺序编排全部受管模块
100
+ - 调用方法:`await manager.main(name, method, ...args)`、`await manager.callMod(name, method, ...args)`;`manager.main(null, ...)` 广播
101
+ - 查询:`getMod(name)` / `getInfo(name)` / `getInfos()` / `getList(keyword)` / `isRunning(name)`
102
+ - 关闭监听:`await manager.unwatch()`
442
103
 
443
- ### 2. 热更新不工作
104
+ ## 运行模式
444
105
 
445
- **检查项目:**
106
+ `MODE` 为只读枚举,构造时通过 `config.mode` 传入:
446
107
 
447
- - 确认`mode`设置为2或4(热更新模式)
448
- - 确认文件确实被修改了(注意编辑器的保存设置)
449
- - 检查文件路径是否正确
108
+ | 常量 | 值 | 含义 |
109
+ |---|---|---|
110
+ | `MODE.PRODUCTION` | 1 | 生产模式,不监听文件变化 |
111
+ | `MODE.HOT_CONFIG` | 2 | 热更新配置 |
112
+ | `MODE.HOT_RELOAD` | 3 | 热重载脚本 |
113
+ | `MODE.HOT_BOTH` | 4 | 配置 + 脚本同时热更新 |
114
+ | `MODE.RELOAD_ALWAYS` | 5 | 始终重载 |
450
115
 
451
- ### 3. 执行方法返回null
116
+ ## 目录监听与热重载
452
117
 
453
- **检查项目:**
118
+ `update(dir)` 完成后会对检索目录开启一次递归监听(经 `mm_loader` 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
454
119
 
455
- - 确认模块已正确加载 (`engine.list.length > 0`)
456
- - 确认方法名拼写正确
457
- - 检查模块实现中是否正确导出了该方法
458
- - 检查模块的`state`是否为1(启用状态)
459
-
460
- ### 4. 路径错误
461
-
462
- **解决方案:**
463
-
464
- - 使用绝对路径或确保相对路径正确
465
- - 利用`__dirname`和`fullname()`方法构建可靠的路径
466
-
467
- ## 模块系统设计理念与工作流程
468
-
469
- ### 设计理念
470
-
471
- mm_machine 模块系统基于以下核心设计理念:
472
-
473
- 1. **高内聚、低耦合**:每个模块独立封装功能,通过明确的接口与其他模块交互
474
- 2. **可插拔架构**:模块可以动态加载、卸载,不影响系统整体运行
475
- 3. **配置驱动**:通过配置文件控制模块行为,无需修改代码
476
- 4. **生命周期管理**:提供完整的模块生命周期钩子,便于资源管理
477
- 5. **热更新支持**:无需重启应用即可更新模块功能
478
-
479
- ### 工作流程
480
-
481
- 以下是模块系统的基本工作流程:
482
-
483
- ```
484
- 初始化引擎 → 扫描模块目录 → 解析配置文件 → 加载模块代码 → 初始化模块 → 执行方法 → 监听文件变化(热更新模式)
485
- ```
486
-
487
- 详细工作流程说明:
488
-
489
- 1. **初始化引擎**:创建 Machine 实例,设置配置项
490
- 2. **扫描模块目录**:根据 searchPath 扫描目录,查找 `config_{type}.json` 文件
491
- 3. **解析配置文件**:读取并解析配置,验证模块状态
492
- 4. **加载模块代码**:根据配置中的信息,动态加载模块的实现文件
493
- 5. **初始化模块**:按排序顺序初始化模块,执行 init 和 load 方法
494
- 6. **执行方法**:根据应用需求,执行模块的特定方法(如 main)
495
- 7. **监听文件变化**:在热更新模式下,监听文件变化并自动重新加载模块
496
-
497
- #### 目录监听与热重载
498
-
499
- `update(dir)` 完成后会对检索目录开启一次递归监听(经 mm_loader 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
500
-
501
- - 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.use_scope || 'os')`),避免重复扫描、重复监听与重复加载
120
+ - 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.load_scope || 'app')`),避免重复扫描、重复监听与重复加载
502
121
  - 管理器把自己的清单文件名登记为加载器类型:类型键为文件名去掉 `.json` 后缀(`manager.json` → `manager`),已存在的类型不覆盖
503
- - 需要独立加载器时,用 `use_scope` 指定另一共享作用域(按 `scope@目录` 派生独立实例)
122
+ - 需要独立加载器时,用 `load_scope` 指定另一加载器名
504
123
 
505
124
  | 变更 | 模式要求 | 行为 |
506
- | --- | --- | --- |
125
+ |---|---|---|
507
126
  | 配置文件新增 | 任意 | 按配置文件注册模块,非懒加载时立即加载 |
508
127
  | 配置文件修改 | `mode >= 2`(热更新配置) | 同步配置快照并应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本 |
509
128
  | 配置文件删除 | 任意 | 注销模块(停止 → 卸载 → 移除记录) |
@@ -512,121 +131,69 @@ mm_machine 模块系统基于以下核心设计理念:
512
131
  | 脚本新增/重建 | `mode = 3 / 4` | 同目录存在同名配置文件时补注册,非懒加载时立即加载 |
513
132
  | 脚本内容修改 | `mode = 3 / 4` | 是受管模块的入口:管理器重载脚本(清 require 缓存后重新加载并重挂方法);非入口:仅失效自身 require 缓存 |
514
133
 
515
- - 脚本变更按**入口精确匹配**:只有变更文件是某个受管模块的入口脚本才触发重载/注销;公共脚本(com/lib 等)变化只失效自身的 require 缓存,不追溯引用方,引用方下次加载即拿到新代码
516
- - 脚本事件只在热重载模式(`MODE.HOT_RELOAD` / `MODE.HOT_BOTH`)下纳入监听,生产与仅热更新配置模式不扫描脚本,避免无谓开销
517
- - 热更新不依赖 `mm_hot_reload`:配置与脚本的变化均由管理器的目录监听(mm_loader)统一接管;`mm_hot_reload` 仅供函数自行应用其他模块时选用
134
+ - 脚本变更按**入口精确匹配**:只有变更文件是某个受管模块的入口脚本才触发重载/注销;公共脚本(com/lib 等)变化只失效自身的 require 缓存,不追溯引用方
135
+ - 脚本事件只在热重载模式(`MODE.HOT_RELOAD` / `MODE.HOT_BOTH`)下纳入监听,生产与仅热更新配置模式不扫描脚本
518
136
  - 调用 `unwatch()` 可关闭全部目录监听
519
137
 
520
- ### 数据流向
521
-
522
- 模块间的数据流转遵循以下规则:
523
-
524
- 1. 引擎将调用参数传递给模块方法
525
- 2. 模块方法处理后返回结果
526
- 3. 钩子方法可以拦截和修改输入/输出数据
527
- 4. 模块可以访问自己的配置,但不能直接访问其他模块的数据
138
+ ## 常见问题
528
139
 
529
- ## 最佳实践与开发建议
140
+ - **模块数为 0**:检查 `dir` 是否为绝对路径、`filename` 是否与清单文件名一致、`state` 是否为 1
141
+ - **热更新不生效**:确认 `mode` 为 `MODE.HOT_CONFIG` / `HOT_RELOAD` / `HOT_BOTH`,且 `update()` 已执行
142
+ - **方法返回 null**:确认模块已 `runAll('load')` / `runAll('init')`,且脚本确实导出了该同名函数
530
143
 
531
- ### 模块设计最佳实践
144
+ ## 测试
532
145
 
533
- 1. **单一职责原则**:每个模块应专注于单一功能领域
534
- 2. **接口一致性**:遵循模块生命周期接口约定,确保兼容性
535
- 3. **错误处理**:在模块内部实现完善的错误处理机制
536
- 4. **日志记录**:使用统一的日志接口记录模块活动
537
- 5. **资源管理**:在适当的生命周期钩子中释放资源
538
-
539
- ### 配置管理建议
540
-
541
- 1. **配置分层**:将公共配置和模块特有配置分开
542
- 2. **配置验证**:在模块初始化时验证配置有效性
543
- 3. **默认值处理**:为重要配置项提供合理的默认值
544
- 4. **敏感信息保护**:避免在配置文件中直接存储敏感信息
545
-
546
- ### 性能优化建议
547
-
548
- 1. **懒加载**:对于资源密集型模块,考虑实现懒加载机制
549
- 2. **缓存策略**:合理使用缓存减少重复计算
550
- 3. **异步操作**:使用 async/await 处理异步操作,避免阻塞
551
- 4. **减少全局状态**:尽量减少模块间的状态共享
552
-
553
- ### 调试技巧
146
+ ```bash
147
+ npm test # jest --coverage
148
+ npm run demo # 运行 example/index.js
149
+ ```
554
150
 
555
- 1. **日志级别**:利用不同级别的日志(debug、info、error)辅助调试
556
- 2. **热更新调试**:使用热更新模式(mode=2)进行开发调试
557
- 3. **模块隔离**:出现问题时,尝试单独测试特定模块
558
- 4. **配置检查**:验证配置文件格式和内容是否正确
151
+ ## 依赖
559
152
 
560
- ### 部署注意事项
153
+ 运行时依赖均按 npm 线上版本声明:
561
154
 
562
- 1. **生产环境模式**:部署到生产环境时,设置 mode=1 以获得最佳性能
563
- 2. **配置备份**:定期备份模块配置文件
564
- 3. **版本控制**:对模块代码和配置进行版本控制
565
- 4. **依赖管理**:明确声明和管理模块依赖
155
+ | 包 | 用途 |
156
+ |---|---|
157
+ | `mm_mod` | 生命周期与配置基类,Manager/Mod/Drive 均继承其能力 |
158
+ | `mm_loader` | 目录扫描、清单解析与文件监听(热更新唯一入口) |
159
+ | `mm_scanner` | `typeStore(type)` 读取扫描结果,避免各管理器重复扫描 |
160
+ | `mm_files` | 配置/脚本的读写、路径与存在性判断 |
161
+ | `mm_helper` | 字符串处理与通用工具函数 |
162
+ | `mm_tpl` | 驱动生成配置/脚本时使用的模板 |
163
+ | `@prettier/sync` | `Drive.prettyCode()` 运行时格式化生成的配置与脚本代码 |
566
164
 
567
- ## 贡献指南
165
+ ## 更新日志
568
166
 
569
- 如果您有兴趣为 mm_machine 项目贡献代码或改进,请遵循以下步骤:
167
+ ### 6.0.0
570
168
 
571
- 1. Fork 项目仓库
572
- 2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
573
- 3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
574
- 4. 推送到分支 (`git push origin feature/amazing-feature`)
575
- 5. 打开 Pull Request
576
-
577
- ## 更新日志
169
+ - 加载器实例键改为 `load_scope`(即 `Loader.name`),不再拼接 `@目录`
170
+ - `_findFiles` 改为「扫描一次 + 按类型取切片」:先 `ensureScanned()`,再从 `typeStore(type)` 读取条目
171
+ - 依赖升级:`mm_loader ^7.0.0`、新增 `mm_scanner ^5.0.0` 与 `mm_store ^1.0.1`
172
+ - 移除未使用的 `use_scope` 配置
578
173
 
579
174
  ### 5.0.1
580
175
 
581
- - 配置加载依赖升级到 `mm_loader@^4.0.1`:该版本修复了 `load()` 在 JSON5 解析之外额外对整串 `{表达式}` 做模板字段求值的 BUG,现在 `load()` 只委托 `mm_helper.loadJson` 把配置读成对象,花括号内容一律原样保留。
582
- - 本模块源码无需改动:`_readModConfig` 本就通过 `_getLoader().load()` 加载配置,**配置加载职责保持在 mm_machine 这一层**。子类(如 `mm_mcps`)不必覆盖 `_readModConfig`,也不必直接依赖 `mm_loader`;运行时内变量由各业务模块在消费配置时自行解析。
176
+ - `mm_loader@^4.0.1` 修复 `load()` 额外对整串 `{表达式}` 做模板求值的 BUG
177
+ - 配置加载职责保持在 mm_machine 这一层,子类不必覆盖 `_readModConfig`
583
178
 
584
179
  ### v4.1.0
585
180
 
586
- - 配置加载器改为共享:`_getLoader()` 默认取 mm_loader 实例池中的同一个 `Loader`(`loadAdmin(config.use_scope || 'os')`),不再为每个管理器各建实例
587
- - 清单类型按文件名推导登记:`manager.json` → `manager`,通过 `addType` 幂等注册进共享实例,已存在的类型不覆盖
588
- - `_getLoader()` 直接取 mm_loader 实例池中的 `Loader`,不再自行缓存引用;需要独立实例时用 `config.use_scope` 指定另一共享作用域
589
- - `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除,不影响其他调用方的监听
590
- - `_findFiles` 改用 `Loader.scan`(物理扫描唯一入口),保证 `update` 能看到新增/删除的文件
591
- - 依赖 mm_loader ^3.0.0
181
+ - 配置加载器改为共享实例;清单类型按文件名推导登记
182
+ - `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除
592
183
 
593
184
  ### v4.0.0
594
185
 
595
- - 热更新收敛到管理器:mm_loader 移除脚本变更总线与缓存树工具(`subscribeScriptChanges` / `findImporters` / `clearScriptTree` 等),管理器直接监听 `Loader.watch` 的脚本回调
596
- - 脚本变更改为入口精确匹配:只有变更文件是受管模块入口才触发重载/注销,公共脚本变化仅失效自身 require 缓存
597
- - `_watchDir` 复用同一个 Loader:配置回调与脚本回调一次 watch 分流,删除独立的脚本订阅路径
598
- - 依赖 mm_loader ^2.0.0
186
+ - 热更新收敛到管理器,脚本变更改为入口精确匹配
187
+ - `_watchDir` 复用同一个 Loader,配置回调与脚本回调一次 watch 分流
599
188
 
600
189
  ### v3.6.0
601
190
 
602
- - 移除对 `mm_hot_reload` 的依赖:配置与脚本热更新全部由管理器目录监听(mm_loader)接管,`mm_hot_reload` 回归为函数自行应用其他模块时的可选工具
603
- - 修正 `Drive.setConfig`:`config` 为共享配置记录的 getter,改为原地深合并(原先 `conf()` 重新赋值为静默无效操作,热更新配置从未真正写入模块)
604
- - 热更新配置模式下,配置变化同步应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本
605
- - 热重载模式下,脚本内容变化由管理器重载(清缓存后重新 require 并重挂方法)
606
- - 移除 `Drive.watchConfig`、`_loadHotReload`,`_handleHotReload` 更名为 `_applyConfigUpdate`
607
-
608
- ### v1.0.0 (初始版本)
609
-
610
- - 基础模块管理功能
611
- - 配置文件加载和解析
612
- - 模块生命周期管理
613
- - 热更新支持
614
- - 基础错误处理
191
+ - 移除对 `mm_hot_reload` 的依赖,热更新全部由管理器目录监听接管
192
+ - 修正 `Drive.setConfig` 原地深合并;新增 `_applyConfigUpdate`
615
193
 
616
- ### v1.1.0
194
+ ### v1.1.0 / v1.0.0
617
195
 
618
- - 改进模块加载逻辑,支持自定义目录
619
- - 增强错误处理和异常捕获
620
- - 添加更多生命周期钩子
621
- - 优化性能和内存使用
622
-
623
- ## 依赖
624
-
625
- - mm_config: ^2.5.3
626
- - mm_helper: ^1.0.3
627
- - mm_loader: ^3.0.0(目录监听与配置/脚本热更新)
628
- - mm_mod: ^1.0.6
629
- - mm_tpl: ^2.7.3
196
+ - 基础模块管理、配置加载、生命周期与热更新支持
630
197
 
631
198
  ## 许可证
632
199
 
@@ -634,4 +201,12 @@ ISC
634
201
 
635
202
  ## 作者信息
636
203
 
637
- 本模块由 mm_modules 团队开发和维护。如有问题或建议,请联系我们。
204
+ 本模块由 mm_modules 团队开发和维护。
205
+
206
+ ## 工具契约(LLM 可调用)
207
+
208
+ `tool/` 下登记的工具契约,实现位于 `tool/<name>/index.js`:
209
+
210
+ | 工具名 | 标题 | 说明 |
211
+ |---|---|---|
212
+ | `machine` | 插件机制契约自省 | 列出 `MODE` 枚举、`Mod` / `Drive` / `Manager` 的公开方法清单与生命周期顺序;参数 `action=modes|classes` |