mm_cmd 0.0.0-stage → 1.1.0

package/lib/manager.js

@@ -0,0 +1,418 @@
+const Manager = require('mm_corejs').Manager;
+const Drive = require('./drive');
+
+/**
+ * 内置会话缓存类（替代原框架注入的全局缓存服务，进程内 Map + 过期时间）
+ * @class
+ */
+class LocalCache {
+  /**
+   * 构造函数
+   * @class
+   */
+  constructor() {
+    /**
+     * 缓存存储（key => { value, expire }）
+     * @type {Map}
+     */
+    this.store = new Map();
+  }
+
+  /**
+   * 读取缓存（过期自动删除）
+   * @param {string} key 缓存键
+   * @returns {*} 缓存值，不存在返回 undefined
+   */
+  get(key) {
+    var item = this.store.get(key);
+    if (!item) {
+      return undefined;
+    }
+    if (item.expire && item.expire < Date.now()) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return item.value;
+  }
+
+  /**
+   * 写入缓存
+   * @param {string} key 缓存键
+   * @param {*} value 缓存值
+   * @param {number} timeout 有效期秒数，0 或不传为不过期
+   * @returns {void}
+   */
+  set(key, value, timeout = 0) {
+    this.store.set(key, {
+      value,
+      expire: timeout > 0 ? Date.now() + timeout * 1000 : 0,
+    });
+  }
+
+  /**
+   * 删除缓存
+   * @param {string} key 缓存键
+   * @returns {boolean} 是否删除成功
+   */
+  del(key) {
+    return this.store.delete(key);
+  }
+}
+
+/**
+ * 指令管理器类（迁移自 mm_os com/cmd，基于 mm_corejs 内置管理器模式）
+ * @augments {Manager}
+ * @class
+ */
+class Cmd extends Manager {
+  /**
+   * 配置参数（方案B：无目录扫描机制键，drive 由 add() 手动注册）
+   * @type {object}
+   */
+  static config = {
+    /**
+     * 名称
+     * @type {string}
+     */
+    name: '',
+    /**
+     * 标题
+     * @type {string}
+     */
+    title: '指令管理',
+    /**
+     * 描述
+     * @type {string}
+     */
+    description: '指令框架管理器，负责指令注册、匹配与执行',
+    /**
+     * 会话超时（秒）
+     * @type {number}
+     */
+    session_timeout: 600,
+    /**
+     * 会话缓存实例（可选注入，需含 get/set/del；未配置时使用内置进程内缓存）
+     * @type {object|null}
+     */
+    cache: null,
+  };
+
+  /**
+   * 构造函数
+   * @param {object} config 配置参数
+   * @param {object} parent 父级模块
+   */
+  constructor(config, parent) {
+    super({ ...Cmd.config, ...config }, parent);
+    this.list_before = [];
+    this.list_main = [];
+    this.list_after = [];
+    // 插件注册表（方案B：手动注册，供 usePlugin 登记）
+    this.plugins = {};
+    // 内置会话缓存（config.cache 未注入时使用）
+    this._local_cache = new LocalCache();
+  }
+}
+
+/**
+ * Cmd驱动类
+ * @type {Drive}
+ */
+Cmd.prototype.Drive = Drive;
+
+/**
+ * 注册一个指令驱动（方案B：手动注册，不扫描目录）
+ * @param {object} config 驱动配置（必须包含 name）
+ * @returns {object} 驱动实例
+ */
+Cmd.prototype.add = function (config) {
+  var drive = new Drive({ ...config }, this);
+  this.set(drive.config.name, drive);
+  this._fullList();
+  return drive;
+};
+
+/**
+ * 注销一个指令驱动（删除注册表项并重建指令列表）
+ * @param {string} name 驱动名称
+ * @returns {Promise<boolean>} 是否删除成功
+ */
+Cmd.prototype.del = async function (name) {
+  var result = await Manager.prototype.del.call(this, name);
+  this._fullList();
+  return result;
+};
+
+/**
+ * 重载一个指令驱动（重新加载脚本并重建指令列表）
+ * @param {string} name 驱动名称
+ * @returns {boolean} 是否执行成功
+ */
+Cmd.prototype.reload = function (name) {
+  var drive = this.get(name);
+  if (!drive) {
+    this.log('warn', '驱动不存在，无法重载', name);
+    return false;
+  }
+  drive.reloadScript();
+  this._fullList();
+  return true;
+};
+
+/**
+ * 注册插件集合（供驱动 plugin() 查找，替代原全局插件池）
+ * @param {string} name 插件作用域名称（app 名）
+ * @param {object} obj 插件集合对象（需含 get 方法）
+ * @returns {object} 当前管理器实例
+ */
+Cmd.prototype.usePlugin = function (name, obj) {
+  this.plugins[name] = obj;
+  return this;
+};
+
+/**
+ * 获取所有驱动配置列表（方案B：来自注册表，按 sort 升序，替代旧基类 getInfos）
+ * @returns {Array} 驱动配置数组
+ * @private
+ */
+Cmd.prototype._getInfos = function () {
+  var infos = this.values().map((d) => d.config);
+  infos.sort((a, b) => (a.sort || 0) - (b.sort || 0));
+  return infos;
+};
+
+/**
+ * 获取会话缓存实例（config.cache 注入优先，否则内置进程内缓存）
+ * @returns {object} 含 get/set/del 的缓存实例
+ * @private
+ */
+Cmd.prototype._getCache = function () {
+  var cache = this.config.cache;
+  if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') {
+    return cache;
+  }
+  return this._local_cache;
+};
+
+/**
+ * 构建指令列表（按 tense 分桶，仅启用项）
+ * @returns {void}
+ * @private
+ */
+Cmd.prototype._fullList = function () {
+  this.list_before = [];
+  this.list_main = [];
+  this.list_after = [];
+
+  var infos = this._getInfos();
+  for (var i = 0; i < infos.length; i++) {
+    var info = infos[i];
+    if (info.state !== 1) {
+      continue;
+    }
+    var mod = this.get(info.name);
+    if (!mod) {
+      continue;
+    }
+    switch (mod.config.tense) {
+      case 'before':
+        this.list_before.push(info);
+        break;
+      case 'after':
+        this.list_after.push(info);
+        break;
+      default:
+        this.list_main.push(info);
+        break;
+    }
+  }
+};
+
+/**
+ * 更新后回调
+ * @param {string} dir_path 目录路径
+ */
+Cmd.prototype.updateAfter = async function (dir_path) {
+  this._fullList();
+};
+
+/**
+ * 执行指令
+ * @param {object} msg 消息对象
+ * @param {object} db 数据管理器
+ * @returns {object|string} 返回执行结果
+ */
+Cmd.prototype.run = async function (msg, db) {
+  if (!msg || !msg.content) {
+    return null;
+  }
+  var ret;
+  var session = await this._getSession(msg);
+
+  if (session) {
+    ret = await this._runSession(msg, db, session);
+  } else {
+    ret = await this.runSub(msg, db, 'before');
+    if (!ret) {
+      ret = await this.runSub(msg, db, 'main');
+    }
+    if (!ret) {
+      ret = await this.runSub(msg, db, 'after');
+    }
+  }
+  ret = this._makeResult(msg, ret);
+  db.ret = ret;
+  return ret;
+};
+
+/**
+ * 按列表执行指令
+ * @param {object} msg 消息对象
+ * @param {object} db 数据管理器
+ * @param {string} tense 时态
+ * @returns {object|string} 返回执行结果
+ */
+Cmd.prototype.runSub = async function (msg, db, tense) {
+  var list = this['list_' + tense];
+  if (!list) {
+    return null;
+  }
+  var ret;
+  for (var i = 0; i < list.length; i++) {
+    var info = list[i];
+    if (info.state !== 1) {
+      continue;
+    }
+    var mod = this.get(info.name);
+    if (!mod) {
+      continue;
+    }
+    ret = await mod.run(msg, db);
+    if (ret) {
+      msg.cmd = info.name;
+      if (msg.end === 0) {
+        this._saveSession(msg, {
+          cmd: msg.cmd,
+          form: msg.form,
+          stage: msg.stage,
+        });
+        break;
+      }
+      if (mod.config.end) {
+        break;
+      }
+    }
+  }
+  return ret;
+};
+
+/**
+ * 继续执行会话指令
+ * @param {object} msg 消息对象
+ * @param {object} db 数据管理器
+ * @param {object} session 会话信息
+ * @returns {object|string} 返回执行结果
+ * @private
+ */
+Cmd.prototype._runSession = async function (msg, db, session) {
+  var mod = this.get(session.cmd);
+  if (!mod) {
+    this._clearSession(msg);
+    return null;
+  }
+  msg.cmd = session.cmd;
+  msg.form = session.form;
+  msg.stage = session.stage;
+  msg.end = 0;
+
+  try {
+    var ret = await mod.run(msg, db);
+    if (msg.end === 0) {
+      this._saveSession(msg, {
+        cmd: msg.cmd,
+        form: msg.form,
+        stage: msg.stage,
+      });
+    } else {
+      this._clearSession(msg);
+    }
+    return ret;
+  } catch (error) {
+    this.log('error', '会话指令执行失败', error.message);
+    this._clearSession(msg);
+    return null;
+  }
+};
+
+/**
+ * 包装出站消息, from_user/to_user 反转
+ * @param {object} msg 入站消息
+ * @param {object|string} ret 原始返回值
+ * @returns {object} 出站消息
+ * @private
+ */
+Cmd.prototype._makeResult = function (msg, ret) {
+  if (!ret) return ret;
+  var result = typeof ret === 'string' ? { content: ret } : { ...ret };
+  if (msg.to_user) result.from_user = msg.to_user;
+  if (msg.from_user) result.to_user = msg.from_user;
+  if (msg.chatid) result.chatid = msg.chatid;
+  if (msg.cmd) result.cmd = msg.cmd;
+  if (msg.form) result.form = msg.form;
+  if (msg.end != null) result.end = msg.end;
+  return result;
+};
+
+/**
+ * 获取会话
+ * @param {object} msg 消息对象
+ * @returns {object|null} 会话信息
+ * @private
+ */
+Cmd.prototype._getSession = async function (msg) {
+  var key = this._getKey(msg);
+  var val = await this._getCache().get(key);
+  if (!val) {
+    return null;
+  }
+  if (typeof val === 'string') {
+    return JSON.parse(val);
+  }
+  return val;
+};
+
+/**
+ * 保存会话
+ * @param {object} msg 消息对象
+ * @param {object} session 会话信息
+ * @private
+ */
+Cmd.prototype._saveSession = function (msg, session) {
+  var key = this._getKey(msg);
+  this._getCache().set(key, session, this.config.session_timeout);
+};
+
+/**
+ * 清除会话
+ * @param {object} msg 消息对象
+ * @private
+ */
+Cmd.prototype._clearSession = function (msg) {
+  var key = this._getKey(msg);
+  this._getCache().del(key);
+};
+
+/**
+ * 获取会话缓存键
+ * @param {object} msg 消息对象
+ * @returns {string} 缓存键
+ * @private
+ */
+Cmd.prototype._getKey = function (msg) {
+  return 'cmd_session_' + (msg.chatid || msg.from_user || 'default');
+};
+
+/**
+ * @module 导出指令管理器类
+ */
+module.exports = Cmd;

package/msg.json

@@ -0,0 +1,48 @@
+{
+  // 消息ID
+  "message_id": 0,
+  // 结束状态 0-正常 1-结束
+  "end": 0,
+  // 阶段 1-9阶段
+  "stage": 1,
+  // 微信/公众号消息ID
+  "msgid": "",
+  // 更新时间
+  "update_time": "",
+  // 创建时间
+  "create_time": "",
+  // 群组
+  "group": "",
+  // 消息类型 text-文本 image-图片 voice-语音 video-视频 file-文件 location-位置 link-链接 event-事件 other-其他
+  "msg_type": "text",
+  // 媒体ID，图片、语音、视频、文件
+  "media_id": "",
+  // 发信人姓名
+  "name": "",
+  // 一般情况下，1永久会话/群、2临时会话/群
+  "type": 1,
+  // 指令
+  "cmd": "",
+  // 应用ID
+  "appid": "",
+  // 发信人
+  "from_user": "",
+  // 收信人
+  "to_user": "",
+  // 机器人
+  "robot": "",
+  // 会话ID，用于判断是否是同一个会话
+  "chatid": "",
+  // 发信人头像
+  "avatar": "",
+  // 除指令外，过滤、抽取后的词
+  "keyword": "",
+  // 表单，用于记录用户已填参数，json格式
+  "form": "",
+  // 聊天内容
+  "content": "",
+  // 消息传递数据，json格式
+  "data": "",
+  // 备注信息
+  "note": ""
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "mm_cmd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "指令框架，用于以聊天的方式操作程序，前端发送字符串，后端判断是否为指令并执行（基于 mm_corejs，内置管理器池，无全局/原型扩展依赖）",
+  "main": "index.js",
+  "keywords": [
+    "mm_mod",
+    "mm_adapter",
+    "mm_in_adapter",
+    "cmd",
+    "command",
+    "chat",
+    "指令管理器"
+  ],
+  "layer": "adapter",
+  "group": "in_adapter",
+  "author": "邱文武",
+  "license": "ISC",
+  "dependencies": {
+    "mm_corejs": "^1.1.4",
+    "mm_matchs": "^1.1.10"
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/script.tpl.js

@@ -0,0 +1,12 @@
+module.exports = {
+  /**
+   * 执行指令主函数
+   * @param {object} msg 消息对象 (含 content 字段)
+   * @param {object} db 数据管理器
+   * @returns {object|string} 执行结果
+   */
+  async main(msg, db) {
+    // 在此编写指令业务逻辑
+    return '指令执行成功';
+  },
+};

package/test.js

@@ -0,0 +1,18 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+// 验证导出结构
+assert.ok(mod.Manager, '应导出 Manager');
+assert.ok(mod.admin, '应导出 admin');
+assert.strictEqual(typeof mod.cmdAdmin, 'function', '应导出 cmdAdmin 函数');
+
+// 验证通过工厂函数获取实例
+const inst = mod.cmdAdmin('test');
+assert.ok(inst instanceof mod.Manager, 'cmdAdmin 返回的实例应为 Manager 类型');
+
+// 验证通过 admin 获取实例
+const inst2 = mod.admin.get('test2');
+assert.ok(inst2 instanceof mod.Manager, 'admin.get 返回的实例应为 Manager 类型');
+
+console.log('mm_cmd 模块测试通过');