mm_machine 6.0.0 → 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
- **检查项目:**
454
-
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` 脚本的变更按扩展名分流):
118
+ `update(dir)` 完成后会对检索目录开启一次递归监听(经 `mm_loader` 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
500
119
 
501
120
  - 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.load_scope || 'app')`),避免重复扫描、重复监听与重复加载
502
121
  - 管理器把自己的清单文件名登记为加载器类型:类型键为文件名去掉 `.json` 后缀(`manager.json` → `manager`),已存在的类型不覆盖
503
- - 需要独立加载器时,用 `load_scope` 指定另一加载器名(一个名称对应一个目录,实例即 `Loader.<load_scope>`)
122
+ - 需要独立加载器时,用 `load_scope` 指定另一加载器名
504
123
 
505
124
  | 变更 | 模式要求 | 行为 |
506
- | --- | --- | --- |
125
+ |---|---|---|
507
126
  | 配置文件新增 | 任意 | 按配置文件注册模块,非懒加载时立即加载 |
508
127
  | 配置文件修改 | `mode >= 2`(热更新配置) | 同步配置快照并应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本 |
509
128
  | 配置文件删除 | 任意 | 注销模块(停止 → 卸载 → 移除记录) |
@@ -512,128 +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
- ### 调试技巧
554
-
555
- 1. **日志级别**:利用不同级别的日志(debug、info、error)辅助调试
556
- 2. **热更新调试**:使用热更新模式(mode=2)进行开发调试
557
- 3. **模块隔离**:出现问题时,尝试单独测试特定模块
558
- 4. **配置检查**:验证配置文件格式和内容是否正确
559
-
560
- ### 部署注意事项
561
-
562
- 1. **生产环境模式**:部署到生产环境时,设置 mode=1 以获得最佳性能
563
- 2. **配置备份**:定期备份模块配置文件
564
- 3. **版本控制**:对模块代码和配置进行版本控制
565
- 4. **依赖管理**:明确声明和管理模块依赖
146
+ ```bash
147
+ npm test # jest --coverage
148
+ npm run demo # 运行 example/index.js
149
+ ```
566
150
 
567
- ## 贡献指南
151
+ ## 依赖
568
152
 
569
- 如果您有兴趣为 mm_machine 项目贡献代码或改进,请遵循以下步骤:
153
+ 运行时依赖均按 npm 线上版本声明:
570
154
 
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
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()` 运行时格式化生成的配置与脚本代码 |
576
164
 
577
165
  ## 更新日志
578
166
 
579
167
  ### 6.0.0
580
168
 
581
- - 加载器实例键改为 `load_scope`(即 `Loader.name`),不再拼接 `@目录`:同一应用目录共用一个加载器,其他目录请配置不同的 `load_scope`(如 `data`)。
582
- - `_findFiles` 改为「扫描一次 + 按类型取切片」:先 `loader.ensureScanned()`,再从 `typeStore(type)` 读取加载器扫描根下的条目,按文件名与目标子目录过滤,多个管理器不再各自扫描。
583
- - 依赖升级:`mm_loader ^7.0.0`、新增 `mm_scanner ^5.0.0` 与 `mm_store ^1.0.1`。
584
- - 移除未使用的 `use_scope` 配置,加载器实例共享统一由 `load_scope` 控制。
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` 配置
585
173
 
586
174
  ### 5.0.1
587
175
 
588
- - 配置加载依赖升级到 `mm_loader@^4.0.1`:该版本修复了 `load()` 在 JSON5 解析之外额外对整串 `{表达式}` 做模板字段求值的 BUG,现在 `load()` 只委托 `mm_helper.loadJson` 把配置读成对象,花括号内容一律原样保留。
589
- - 本模块源码无需改动:`_readModConfig` 本就通过 `_getLoader().load()` 加载配置,**配置加载职责保持在 mm_machine 这一层**。子类(如 `mm_mcps`)不必覆盖 `_readModConfig`,也不必直接依赖 `mm_loader`;运行时内变量由各业务模块在消费配置时自行解析。
176
+ - `mm_loader@^4.0.1` 修复 `load()` 额外对整串 `{表达式}` 做模板求值的 BUG
177
+ - 配置加载职责保持在 mm_machine 这一层,子类不必覆盖 `_readModConfig`
590
178
 
591
179
  ### v4.1.0
592
180
 
593
- - 配置加载器改为共享:`_getLoader()` 默认取 mm_loader 实例池中的同一个 `Loader`(`loadAdmin(config.use_scope || 'os')`),不再为每个管理器各建实例
594
- - 清单类型按文件名推导登记:`manager.json` → `manager`,通过 `addType` 幂等注册进共享实例,已存在的类型不覆盖
595
- - `_getLoader()` 直接取 mm_loader 实例池中的 `Loader`,不再自行缓存引用;需要独立实例时用 `config.use_scope` 指定另一共享作用域
596
- - `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除,不影响其他调用方的监听
597
- - `_findFiles` 改用 `Loader.scan`(物理扫描唯一入口),保证 `update` 能看到新增/删除的文件
598
- - 依赖 mm_loader ^3.0.0
181
+ - 配置加载器改为共享实例;清单类型按文件名推导登记
182
+ - `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除
599
183
 
600
184
  ### v4.0.0
601
185
 
602
- - 热更新收敛到管理器:mm_loader 移除脚本变更总线与缓存树工具(`subscribeScriptChanges` / `findImporters` / `clearScriptTree` 等),管理器直接监听 `Loader.watch` 的脚本回调
603
- - 脚本变更改为入口精确匹配:只有变更文件是受管模块入口才触发重载/注销,公共脚本变化仅失效自身 require 缓存
604
- - `_watchDir` 复用同一个 Loader:配置回调与脚本回调一次 watch 分流,删除独立的脚本订阅路径
605
- - 依赖 mm_loader ^2.0.0
186
+ - 热更新收敛到管理器,脚本变更改为入口精确匹配
187
+ - `_watchDir` 复用同一个 Loader,配置回调与脚本回调一次 watch 分流
606
188
 
607
189
  ### v3.6.0
608
190
 
609
- - 移除对 `mm_hot_reload` 的依赖:配置与脚本热更新全部由管理器目录监听(mm_loader)接管,`mm_hot_reload` 回归为函数自行应用其他模块时的可选工具
610
- - 修正 `Drive.setConfig`:`config` 为共享配置记录的 getter,改为原地深合并(原先 `conf()` 重新赋值为静默无效操作,热更新配置从未真正写入模块)
611
- - 热更新配置模式下,配置变化同步应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本
612
- - 热重载模式下,脚本内容变化由管理器重载(清缓存后重新 require 并重挂方法)
613
- - 移除 `Drive.watchConfig`、`_loadHotReload`,`_handleHotReload` 更名为 `_applyConfigUpdate`
614
-
615
- ### v1.0.0 (初始版本)
616
-
617
- - 基础模块管理功能
618
- - 配置文件加载和解析
619
- - 模块生命周期管理
620
- - 热更新支持
621
- - 基础错误处理
191
+ - 移除对 `mm_hot_reload` 的依赖,热更新全部由管理器目录监听接管
192
+ - 修正 `Drive.setConfig` 原地深合并;新增 `_applyConfigUpdate`
622
193
 
623
- ### v1.1.0
194
+ ### v1.1.0 / v1.0.0
624
195
 
625
- - 改进模块加载逻辑,支持自定义目录
626
- - 增强错误处理和异常捕获
627
- - 添加更多生命周期钩子
628
- - 优化性能和内存使用
629
-
630
- ## 依赖
631
-
632
- - mm_config: ^2.5.3
633
- - mm_helper: ^1.0.3
634
- - mm_loader: ^3.0.0(目录监听与配置/脚本热更新)
635
- - mm_mod: ^1.0.6
636
- - mm_tpl: ^2.7.3
196
+ - 基础模块管理、配置加载、生命周期与热更新支持
637
197
 
638
198
  ## 许可证
639
199
 
@@ -641,4 +201,12 @@ ISC
641
201
 
642
202
  ## 作者信息
643
203
 
644
- 本模块由 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` |
package/lib/drive.js CHANGED
@@ -1,40 +1,34 @@
1
1
  const path = require('path');
2
2
  const { getTpl } = require('mm_tpl');
3
+ const { string, push } = require('mm_helper');
3
4
  const {
4
- string,
5
5
  fullname,
6
6
  hasFile,
7
7
  loadText,
8
8
  saveText,
9
9
  loadJson,
10
10
  saveJson,
11
- push,
12
11
  addDir,
13
12
  delFile,
14
13
  delDir,
15
14
  dirname,
16
15
  basename
17
- } = require('mm_helper');
16
+ } = require('mm_files');
18
17
  const { Mod } = require('./mod');
19
18
 
20
- const MODE = {
21
- // 生产模式
22
- PRODUCTION: 1,
23
- // 热更新配置模式
24
- HOT_CONFIG: 2,
25
- // 热更新脚本模式
26
- HOT_RELOAD: 3,
27
- // 热更新配置+脚本模式
28
- HOT_BOTH: 4,
29
- // 始终重载模式
30
- RELOAD_ALWAYS: 5
31
- };
32
-
33
19
  /**
34
20
  * 驱动基础类
35
21
  * @class
36
22
  */
37
23
  class Drive extends Mod {
24
+ static MODE = {
25
+ PRODUCTION: 1,
26
+ HOT_CONFIG: 2,
27
+ HOT_RELOAD: 3,
28
+ HOT_BOTH: 4,
29
+ RELOAD_ALWAYS: 5
30
+ };
31
+
38
32
  // 配置项
39
33
  static config = {
40
34
  // 标题, 介绍作用
@@ -701,7 +695,8 @@ Drive.prototype._applyConfigUpdate = function (config) {
701
695
  * @param {string} old_script 旧的脚本文件路径
702
696
  */
703
697
  Drive.prototype._reloadIfNeeded = function (old_script) {
704
- if (this.mode === MODE.HOT_RELOAD || this.mode === MODE.HOT_BOTH) {
698
+ const mode = Drive.MODE;
699
+ if (this.mode === mode.HOT_RELOAD || this.mode === mode.HOT_BOTH) {
705
700
  // 只在 main 发生变化时才重载脚本
706
701
  if (!old_script || old_script !== this.script_file) {
707
702
  this.reloadScript();
@@ -850,7 +845,4 @@ Drive.prototype.remove = function () {
850
845
  /**
851
846
  * @module 导出Drive类
852
847
  */
853
- module.exports = {
854
- Drive,
855
- MODE
856
- };
848
+ module.exports = { Drive, MODE: Drive.MODE };
package/lib/manager.js CHANGED
@@ -1,6 +1,7 @@
1
1
  const path = require('path');
2
2
  const { Manager: Core } = require('mm_mod');
3
- const { hasDir, hasFile, fullname, basename, dirname, string } = require('mm_helper');
3
+ const { string } = require('mm_helper');
4
+ const { hasDir, hasFile, fullname, basename, dirname } = require('mm_files');
4
5
  const { loadAdmin } = require('mm_loader');
5
6
  const { typeStore } = require('mm_scanner');
6
7
  const { Mod, addMethods } = require('./mod.js');
@@ -136,7 +137,7 @@ class Manager extends Core {
136
137
  * 构造函数
137
138
  * @param {object} config 配置项
138
139
  * @param {object} parent 父项对象
139
- * @param {object} [mods] 模块对象列表,传入时作为受管记录的实例表(保持外部引用)
140
+ * @param {object} [mods] 模块对象列表,经父类构造注入为受管实例表(保持外部引用)
140
141
  */
141
142
  constructor(config, parent, mods) {
142
143
  super(
@@ -144,7 +145,8 @@ class Manager extends Core {
144
145
  ...Manager.config,
145
146
  ...config
146
147
  },
147
- parent
148
+ parent,
149
+ mods
148
150
  );
149
151
 
150
152
  if (parent) {
@@ -156,10 +158,6 @@ class Manager extends Core {
156
158
  this._loaded = false;
157
159
  // 目录监听器,键为目录路径,值为该目录的配置加载器
158
160
  this._dir_watchers = new Map();
159
- // 外部传入实例表时,直接作为受管记录的实例表,保证外部引用同步
160
- if (mods) {
161
- this._getRecord().mods = mods;
162
- }
163
161
  // 监听事件
164
162
  this._listen();
165
163
  }
@@ -290,10 +288,9 @@ Manager.prototype.clearMods = async function () {
290
288
  * @returns {object|null} 删除的模块对象
291
289
  */
292
290
  Manager.prototype.delMod = function (name) {
293
- let record = this._getRecord();
294
- let mod = record.mods[name];
291
+ let mod = this.mods[name];
295
292
  if (mod) {
296
- delete record.mods[name];
293
+ delete this.mods[name];
297
294
  let infos = this.configs;
298
295
  let index = infos.findIndex((o) => o.name === name);
299
296
  if (index >= 0) {
@@ -309,7 +306,7 @@ Manager.prototype.delMod = function (name) {
309
306
  * @param {object} mod 模块对象
310
307
  */
311
308
  Manager.prototype.setMod = function (name, mod) {
312
- this._getRecord().mods[name] = mod;
309
+ this.mods[name] = mod;
313
310
  };
314
311
 
315
312
  /**
@@ -318,7 +315,7 @@ Manager.prototype.setMod = function (name, mod) {
318
315
  * @returns {object} 模块对象
319
316
  */
320
317
  Manager.prototype.getMod = function (name) {
321
- return this._getRecord().mods[name];
318
+ return this.mods[name];
322
319
  };
323
320
 
324
321
  /**
@@ -326,7 +323,7 @@ Manager.prototype.getMod = function (name) {
326
323
  * @returns {object[]} 模块对象数组
327
324
  */
328
325
  Manager.prototype.getMods = function () {
329
- return this._getRecord().mods;
326
+ return this.mods;
330
327
  };
331
328
 
332
329
  /**
@@ -819,7 +816,7 @@ Manager.prototype._getConfigByScript = function (file) {
819
816
  * @returns {void}
820
817
  */
821
818
  Manager.prototype.unwatch = function () {
822
- for (let [dir, entry] of this._dir_watchers) {
819
+ for (const entry of this._dir_watchers.values()) {
823
820
  entry.loader.unwatch(entry.config_callback, entry.script_callback);
824
821
  }
825
822
  this._dir_watchers.clear();
@@ -1089,12 +1086,12 @@ Manager.prototype._ensureModLoaded = async function (mod, method) {
1089
1086
  if (is_running) {
1090
1087
  try {
1091
1088
  await mod.do('load');
1092
- } catch (error) {
1089
+ } catch {
1093
1090
  throw new Error(`模块${name}加载失败,无法执行方法 ${method}`);
1094
1091
  }
1095
1092
  try {
1096
1093
  await mod.do('init');
1097
- } catch (error) {
1094
+ } catch {
1098
1095
  throw new Error(`模块${name}初始化失败,无法执行方法 ${method}`);
1099
1096
  }
1100
1097
  // 记录受管模块已完成初始化
package/lib/mod.js CHANGED
@@ -1,5 +1,5 @@
1
1
  const { Mod: CoreMod } = require('mm_mod');
2
- const { saveJson, loadJson } = require('mm_helper');
2
+ const { saveJson, loadJson } = require('mm_files');
3
3
 
4
4
  /**
5
5
  * 通用模块类
@@ -44,69 +44,12 @@ class Mod extends CoreMod {
44
44
  }
45
45
  }
46
46
 
47
- /**
48
- * 初始化(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
49
- * @returns {Promise<Mod>} 当前实例
50
- */
51
- Mod.prototype._init = async function () {
52
- return this;
53
- };
54
-
55
- /**
56
- * 初始化
57
- * @returns {Promise<Mod>} 当前实例
58
- */
59
- Mod.prototype.init = async function () {
60
- return await this._init();
61
- };
62
-
63
- /**
64
- * 启动(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
65
- * @returns {Promise<Mod>} 当前实例
66
- */
67
- Mod.prototype._start = async function () {
68
- return this;
69
- };
70
-
71
- /**
72
- * 启动
73
- * @returns {Promise<Mod>} 当前实例
74
- */
75
- Mod.prototype.start = async function () {
76
- return await this._start();
77
- };
78
-
79
- /**
80
- * 停止(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
81
- * @returns {Promise<Mod>} 当前实例
82
- */
83
- Mod.prototype._stop = async function () {
84
- return this;
85
- };
86
-
87
- /**
88
- * 停止
89
- * @returns {Promise<Mod>} 当前实例
90
- */
91
- Mod.prototype.stop = async function () {
92
- return await this._stop();
93
- };
94
-
95
- /**
96
- * 销毁(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
97
- * @returns {Promise<Mod>} 当前实例
98
- */
99
- Mod.prototype._destroy = async function () {
100
- return this;
101
- };
102
-
103
- /**
104
- * 销毁
105
- * @returns {Promise<Mod>} 当前实例
106
- */
107
- Mod.prototype.destroy = async function () {
108
- return await this._destroy();
109
- };
47
+ // 生命周期入口保留为既有调用方的公开契约;实际编排由 do 流水线的 _xxxCore 钩子承担
48
+ for (const name of ['init', 'start', 'stop', 'destroy']) {
49
+ Mod.prototype[name] = async function () {
50
+ return this;
51
+ };
52
+ }
110
53
 
111
54
  /**
112
55
  * 包装错误,附加模块文件路径上下文,用于溯源
@@ -7,59 +7,62 @@
7
7
  * - Drive 系(Drive / App / Plugin / Cmd):script_file、reloadScript()
8
8
  * - Mod 系脚本驱动(Api / Event / Service / Pendant):_getScriptFile()、
9
9
  * load() 把脚本方法挂到实例 this.main 上
10
- * 管理器判断「某个脚本属于哪个驱动」以及「如何让它生效」时走本模块,
11
10
  * 新增一种驱动类型只需注册适配器,不必修改管理器或宿主。
12
11
  */
13
12
 
14
13
  const path = require('path');
15
14
 
16
15
  /**
17
- * 入口解析器:从驱动实例推导入口脚本路径,取不到返回空串
18
- * @type {Array<function(object): string>}
16
+ * 默认入口解析器
17
+ * @returns {Array<function(object): string>} 解析器列表
19
18
  */
20
- const ENTRY_RESOLVERS = [
21
- (drive) => drive.file || '',
22
- (drive) => drive.script_file || '',
23
- (drive) => {
24
- if (typeof drive._getScriptFile !== 'function') return '';
25
- try {
26
- return drive._getScriptFile() || '';
27
- } catch {
28
- return '';
29
- }
30
- },
31
- // Pendant 等驱动 getDir() 返回空串,目录只保存在 config.dir;
32
- // 直接用 getDir() 会把入口误解析到进程 cwd 下的同名文件
33
- (drive) => {
34
- const main = drive.config && drive.config.main;
35
- if (!main) return '';
36
- let dir = (drive.config && drive.config.dir) || '';
37
- if (!dir && typeof drive.getDir === 'function') {
19
+ function defaultEntryResolvers() {
20
+ return [
21
+ (drive) => drive.file || '',
22
+ (drive) => drive.script_file || '',
23
+ (drive) => {
24
+ if (typeof drive._getScriptFile !== 'function') return '';
38
25
  try {
39
- dir = drive.getDir() || '';
26
+ return drive._getScriptFile() || '';
40
27
  } catch {
41
28
  return '';
42
29
  }
30
+ },
31
+ // Pendant 等驱动 getDir() 返回空串,目录只保存在 config.dir;
32
+ // 直接用 getDir() 会把入口误解析到进程 cwd 下的同名文件
33
+ (drive) => {
34
+ const main = drive.config && drive.config.main;
35
+ if (!main) return '';
36
+ let dir = (drive.config && drive.config.dir) || '';
37
+ if (!dir && typeof drive.getDir === 'function') {
38
+ try {
39
+ dir = drive.getDir() || '';
40
+ } catch {
41
+ return '';
42
+ }
43
+ }
44
+ return dir ? path.resolve(dir, main) : '';
43
45
  }
44
- return dir ? path.resolve(dir, main) : '';
45
- }
46
- ];
46
+ ];
47
+ }
47
48
 
48
49
  /**
49
- * 重载器:命中条件 + 执行动作,按注册顺序取第一个匹配
50
- * @type {Array<{test: function(object): boolean, run: function(object): *}>}
50
+ * 默认重载器
51
+ * @returns {Array<{test: function(object): boolean, run: function(object): *}>} 重载器列表
51
52
  */
52
- const RELOADERS = [
53
- { test: (d) => typeof d.reloadScript === 'function', run: (d) => d.reloadScript() },
54
- // 普通 Mod 的 load 是生命周期方法,额外要求 _setMainMethod 避免误触
55
- {
56
- test: (d) => typeof d._setMainMethod === 'function' && typeof d.load === 'function',
57
- run: (d) => d.load()
58
- }
59
- ];
53
+ function defaultReloaders() {
54
+ return [
55
+ { test: (d) => typeof d.reloadScript === 'function', run: (d) => d.reloadScript() },
56
+ // 普通 Mod 的 load 是生命周期方法,额外要求 _setMainMethod 避免误触
57
+ {
58
+ test: (d) => typeof d._setMainMethod === 'function' && typeof d.load === 'function',
59
+ run: (d) => d.load()
60
+ }
61
+ ];
62
+ }
60
63
 
61
- const DEFAULT_ENTRY_RESOLVERS = [...ENTRY_RESOLVERS];
62
- const DEFAULT_RELOADERS = [...RELOADERS];
64
+ const ENTRY_RESOLVERS = defaultEntryResolvers();
65
+ const RELOADERS = defaultReloaders();
63
66
 
64
67
  /**
65
68
  * 注册入口解析器(扩展点)
@@ -90,12 +93,12 @@ function registerReloader(test, run, first = false) {
90
93
  }
91
94
 
92
95
  /**
93
- * 恢复默认适配器
96
+ * 恢复默认适配器,原地替换以保持注册表引用稳定
94
97
  * @returns {void}
95
98
  */
96
99
  function resetAdapters() {
97
- ENTRY_RESOLVERS.splice(0, ENTRY_RESOLVERS.length, ...DEFAULT_ENTRY_RESOLVERS);
98
- RELOADERS.splice(0, RELOADERS.length, ...DEFAULT_RELOADERS);
100
+ ENTRY_RESOLVERS.splice(0, ENTRY_RESOLVERS.length, ...defaultEntryResolvers());
101
+ RELOADERS.splice(0, RELOADERS.length, ...defaultReloaders());
99
102
  }
100
103
 
101
104
  /**
package/package.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
- "name": "mm_machine",
3
- "version": "6.0.0",
4
- "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.",
2
+ "name": "mm_machine",
3
+ "version": "6.0.1",
4
+ "description": "Node.js 插件机制:目录扫描、生命周期编排、方法调用与热重载",
5
5
  "main": "index.js",
6
6
  "scripts": {
7
7
  "test": "jest --coverage",
8
- "demo": "node example/index.js",
9
- "dev": "nodemon ./test.js"
8
+ "demo": "node example/index.js"
10
9
  },
11
10
  "repository": {
12
11
  "type": "git",
@@ -15,7 +14,6 @@
15
14
  "keywords": [
16
15
  "mm_mod",
17
16
  "mm_infra",
18
- "mm_runtime",
19
17
  "plugin-system",
20
18
  "module-management",
21
19
  "hot-reload",
@@ -25,27 +23,27 @@
25
23
  "framework",
26
24
  "mechanism"
27
25
  ],
28
- "layer": "infrastructure",
26
+ "layer": "shared",
29
27
  "group": "runtime",
30
28
  "author": "邱文武",
31
29
  "license": "ISC",
32
30
  "engines": {
33
- "node": ">=12.0.0"
31
+ "node": ">=18"
34
32
  },
35
33
  "files": [
36
34
  "index.js",
37
- "lib/*",
35
+ "lib",
38
36
  "example",
39
- "README.md"
37
+ "README.md",
38
+ "tool"
40
39
  ],
41
40
  "dependencies": {
42
41
  "@prettier/sync": "^0.6.1",
43
- "mm_config": "^2.5.3",
42
+ "mm_files": "^1.4.0",
44
43
  "mm_helper": "^1.0.3",
45
44
  "mm_loader": "^7.0.0",
46
45
  "mm_mod": "^1.0.6",
47
46
  "mm_scanner": "^5.0.0",
48
- "mm_store": "^1.0.1",
49
47
  "mm_tpl": "^2.7.3"
50
48
  },
51
49
  "devDependencies": {
@@ -0,0 +1,51 @@
1
+ 'use strict';
2
+ /**
3
+ * machine —— 插件机制契约自省工具
4
+ * 方法清单直接从模块导出的类原型采集,避免文档与实现漂移。
5
+ */
6
+ const machine = require('../../index.js');
7
+
8
+ /**
9
+ * 采集类原型上的公开方法
10
+ * @param {Function} Cls 类
11
+ * @returns {Array<string>} 方法名列表
12
+ */
13
+ function _methods(Cls) {
14
+ if (typeof Cls !== 'function' || !Cls.prototype) return [];
15
+ return Object.getOwnPropertyNames(Cls.prototype).filter((k) => k !== 'constructor' && k[0] !== '_').sort();
16
+ }
17
+
18
+ async function main(params, ctx, options) {
19
+ void options;
20
+ const p = params || {};
21
+ const action = p.action || 'modes';
22
+ const done = (data) => { ctx.output = data; return data; };
23
+
24
+ try {
25
+ if (action === 'modes') {
26
+ return done({
27
+ code: 0,
28
+ msg: '成功',
29
+ modes: machine.MODE || {},
30
+ lifecycle: ['init', 'start', 'stop', 'destroy']
31
+ });
32
+ }
33
+
34
+ if (action === 'classes') {
35
+ const names = p.class ? [p.class] : ['Mod', 'Drive', 'Manager'];
36
+ const classes = {};
37
+ for (const name of names) {
38
+ const Cls = machine[name];
39
+ if (!Cls) throw new Error('未知类: ' + name);
40
+ classes[name] = _methods(Cls);
41
+ }
42
+ return done({ code: 0, msg: '成功', classes });
43
+ }
44
+
45
+ return done({ code: 10001, msg: '不支持的操作: ' + action });
46
+ } catch (error) {
47
+ return done({ code: 10000, msg: '执行失败:' + error.message, error: { name: error.name, message: error.message } });
48
+ }
49
+ }
50
+
51
+ module.exports = { main };
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "machine",
3
+ "title": "插件机制契约自省",
4
+ "description": "基于 mm_machine 的契约自省能力:列出模块状态枚举值、查看 Mod/Drive/Manager 三个核心类的方法清单与生命周期顺序。适用场景:写自定义受管模块前确认要实现哪些钩子、排查管理器实例该调哪个方法。",
5
+ "category": "内核运行时",
6
+ "group": "kernel",
7
+ "type": "function",
8
+ "main": "./index.js",
9
+ "params": {
10
+ "type": "object",
11
+ "properties": {
12
+ "action": {
13
+ "type": "string",
14
+ "description": "操作类型: modes(状态枚举)/classes(类方法清单)",
15
+ "enum": [
16
+ "modes",
17
+ "classes"
18
+ ],
19
+ "default": "modes"
20
+ },
21
+ "class": {
22
+ "type": "string",
23
+ "description": "类名(classes 可选): Mod/Drive/Manager,缺省全部"
24
+ }
25
+ },
26
+ "required": [
27
+ "action"
28
+ ]
29
+ },
30
+ "returns": {
31
+ "type": "object",
32
+ "properties": {
33
+ "code": {
34
+ "type": "number",
35
+ "description": "0 表示成功,1xxxx 表示业务/执行异常"
36
+ },
37
+ "msg": {
38
+ "type": "string",
39
+ "description": "结果描述"
40
+ },
41
+ "modes": {
42
+ "type": "object",
43
+ "description": "状态枚举(MODE)"
44
+ },
45
+ "classes": {
46
+ "type": "object",
47
+ "description": "类名 → 方法清单"
48
+ },
49
+ "lifecycle": {
50
+ "type": "array",
51
+ "description": "生命周期方法顺序"
52
+ },
53
+ "error": {
54
+ "type": "object",
55
+ "description": "异常对象 { name, message }"
56
+ }
57
+ }
58
+ },
59
+ "handler": "manager"
60
+ }