mm_redis 2.1.8 → 2.3.0

package/index.js

@@ -1,16 +1,16 @@
 const Redis = require('./lib/redis');
-const Admin = require('mm_corejs').Admin;
+const { reg } = require('mm_admin');
 
-let admin = new Admin();
+const admin = reg('mm_redis');
 admin.setClass(Redis);
 
 module.exports = {
 	Redis,
 	admin,
 	redisAdmin(scope, config) {
-		if (!scope) {
-			scope = 'os';
-		}
-		return admin.get(scope, config);
+		return admin.get(scope || 'os', config);
 	}
-};
+};
+/* mm-tool-logic-export 工具能力层：其它模块可 require("<pkg>").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });

package/lib/tools/index.js

@@ -0,0 +1,16 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+/** 模块能力层：懒加载工具实现，避免模块入口被 require 时加载全部实现 */
+module.exports = new Proxy({}, {
+  get(_t, key) {
+    if (typeof key !== 'string') return undefined;
+    if (!fs.existsSync(path.join(__dirname, key, 'index.js'))) return undefined;
+    return require('./' + key);
+  },
+  has(_t, key) {
+    return typeof key === 'string' && fs.existsSync(path.join(__dirname, key, 'index.js'));
+  },
+  ownKeys() { return fs.readdirSync(__dirname, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name); },
+  getOwnPropertyDescriptor(_t, key) { return this.has(_t, key) ? { enumerable: true, configurable: true } : undefined; }
+});

package/lib/tools/push_queue/index.js

@@ -0,0 +1,115 @@
+/**
+ * 队列发信器
+ * 发送消息到消息队列（redis v4 官方包，与 mm_redis 共用底层库）
+ */
+
+/**
+ * 获取 Redis 客户端（复用 mm_redis 连接池，不可用时自建独立连接）
+ * @param {object} opts 配置选项
+ * @returns {object} { client, release } 或 null
+ */
+async function _getClient(opts) {
+  var opts2 = { ...opts };
+  // 统一 db/database 字段，mm_redis 读取的是 database 字段
+  if (opts2.db !== undefined && opts2.database === undefined) {
+    opts2.database = opts2.db;
+  }
+
+  var redis_admin = null;
+  try {
+    var { redisAdmin } = require('mm_redis');
+    if (redisAdmin) {
+      // 与 queue 管理器共用 queue 作用域，保证发布/消费配置一致
+      redis_admin = redisAdmin('queue', opts2);
+    }
+  } catch (e) {
+    // mm_redis 不可用时使用传入的 opts
+  }
+
+  // 优先复用 mm_redis 连接池，保证配置一致且不新建独立连接
+  if (redis_admin && typeof redis_admin._getConnection === 'function') {
+    var conn = await redis_admin._getConnection();
+    return {
+      client: conn,
+      release: function () {
+        try {
+          redis_admin._releaseConnection(conn);
+        } catch (e) {
+          void e;
+        }
+      }
+    };
+  }
+
+  // 回退: mm_redis 不可用，自建独立连接
+  var redis_mod = require('redis');
+  if (!redis_mod || !redis_mod.createClient) {
+    return null;
+  }
+  var createClient = redis_mod.createClient;
+  var client = createClient({
+    socket: {
+      host: opts2.host || 'localhost',
+      port: opts2.port || 6379,
+      connectTimeout: opts2.connect_timeout || 5000,
+      reconnectStrategy: false
+    },
+    password: opts2.password || '',
+    database: opts2.database || 0
+  });
+  await client.connect();
+  return {
+    client: client,
+    release: function () {
+      try {
+        client.quit();
+      } catch (e) {
+        void e;
+      }
+    }
+  };
+}
+
+/**
+ * 主方法
+ * @param {object} ctx 上下文对象
+ * @param {object} params 步骤参数
+ * @returns {object} 发送结果
+ */
+async function main(params, ctx, options) {
+  var opts = (this && typeof this.getOptions === 'function') ? this.getOptions() : {};
+  var driver = opts.driver || 'redis';
+
+  if (driver !== 'redis') {
+    throw new Error('不支持的队列驱动: ' + driver);
+  }
+
+  var queue_name = params.queue_name || '';
+  var data = params.data;
+
+  if (!queue_name) {
+    ctx.output = { error: { code: 'QUEUE_NO_NAME', message: '队列名称不能为空' } };
+    return ctx.output;
+  }
+
+  var holder = await _getClient(opts);
+  if (!holder || !holder.client) {
+    throw new Error('队列发信需要 redis 库，请手动执行: npm install redis');
+  }
+  var client = holder.client;
+  try {
+    await client.lPush(queue_name, JSON.stringify(data));
+  } finally {
+    await holder.release();
+  }
+
+  ctx.output = {
+    sent: true,
+    tip: '消息已入队',
+    queue_name: queue_name,
+    message: data
+  };
+  return ctx.output;
+}
+
+module.exports = { main };

package/lib/tools/queue/index.js

@@ -0,0 +1,395 @@
+/**
+ * 消息队列管理器
+ * 管理消息队列的通用操作，支持发布、消费、确认、重试、死信、延迟、批量消费
+ * 驱动: Redis (redis v4 官方包，与 mm_redis 共用底层库)
+ */
+
+/**
+ * 带超时的 Promise 竞争，超时后抛出错误
+ * @param {Promise} promise 原始 Promise
+ * @param {number} timeout_ms 超时毫秒数
+ * @returns {Promise} 竞争结果
+ * @throws {Error} 超时时抛出
+ */
+function _withTimeout(promise, timeout_ms) {
+  var timer = null;
+  var timeout_promise = new Promise(function (resolve, reject) {
+    timer = setTimeout(function () {
+      reject(new Error('Redis 连接超时'));
+    }, timeout_ms);
+  });
+  return Promise.race([promise, timeout_promise]).finally(function () {
+    clearTimeout(timer);
+  });
+}
+
+/**
+ * 获取 Redis 客户端（通过 mm_redis 的 redisAdmin 获取配置，创建独立连接）
+ * @param {object} opts 配置选项
+ * @returns {object} Redis 客户端
+ * @throws {Error} 连接失败或超时时抛出
+ */
+async function _getClient(opts) {
+  var opts2 = { ...opts };
+  // 统一 db/database 字段，mm_redis 读取的是 database 字段
+  if (opts2.db !== undefined && opts2.database === undefined) {
+    opts2.database = opts2.db;
+  }
+
+  var redis_admin = null;
+  try {
+    var { redisAdmin } = require('mm_redis');
+    if (redisAdmin) {
+      // 使用独立作用域，避免与 redis 管理器共用 sys 池导致本模块配置被覆盖
+      redis_admin = redisAdmin('queue', opts2);
+    }
+  } catch (e) {
+    // mm_redis 不可用时使用传入的 opts
+  }
+
+  // 优先复用 mm_redis 连接池，保证配置一致且不新建独立连接
+  // 使用超时限制，避免 Redis 不可用时连接无限挂起
+  if (redis_admin && typeof redis_admin._getConnection === 'function') {
+    var conn_promise = redis_admin._getConnection();
+    var conn;
+    try {
+      conn = await _withTimeout(conn_promise, opts2.connect_timeout || 3000);
+    } catch (e) {
+      // 超时后底层连接可能仍在创建，创建完成后强制回收，避免连接泄漏
+      conn_promise.then(function (c) {
+        try {
+          redis_admin._releaseConnection(c);
+        } catch (e2) {
+          void e2;
+        }
+      }).catch(function (e2) {
+        void e2;
+      });
+      throw e;
+    }
+    return {
+      client: conn,
+      release: function () {
+        try {
+          redis_admin._releaseConnection(conn);
+        } catch (e2) {
+          void e2;
+        }
+      }
+    };
+  }
+
+  // 回退: mm_redis 不可用，自建独立连接
+  // 禁用自动重连，连接失败时立即抛出，避免无限重连挂起
+  var redis_mod = require('redis');
+  if (!redis_mod || !redis_mod.createClient) {
+    return null;
+  }
+  var createClient = redis_mod.createClient;
+  var client = createClient({
+    socket: {
+      host: opts2.host || 'localhost',
+      port: opts2.port || 6379,
+      connectTimeout: opts2.connect_timeout || 5000,
+      reconnectStrategy: false
+    },
+    password: opts2.password || '',
+    database: opts2.database || 0
+  });
+  try {
+    await client.connect();
+  } catch (e) {
+    try {
+      await client.quit();
+    } catch (e2) {
+      void e2;
+    }
+    throw new Error('Redis 连接失败: ' + (e && e.message ? e.message : String(e)));
+  }
+  return {
+    client: client,
+    release: function () {
+      try {
+        client.quit();
+      } catch (e2) {
+        void e2;
+      }
+    }
+  };
+}
+
+/**
+ * 发布消息到队列
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {*} message 消息内容
+ * @returns {object} 发布结果
+ */
+async function _publish(client, queue_name, message) {
+  // lPush 返回的是列表长度而非消息ID，这里生成唯一消息ID
+  var message_id = Date.now().toString(36) + '-' + Math.random().toString(36).substr(2, 9);
+  await client.lPush(queue_name, JSON.stringify(message));
+  return { msg: '消息发布成功', message_id: message_id, queue: queue_name };
+}
+
+/**
+ * 消费队列消息
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @returns {object} 消费结果
+ */
+async function _consume(client, queue_name) {
+  var raw = await client.rPopLPush(queue_name, queue_name + ':processing');
+  if (!raw) {
+    return { obj: null, queue: queue_name };
+  }
+  var parsed = JSON.parse(raw);
+  return { obj: parsed, queue: queue_name, _raw: raw };
+}
+
+/**
+ * 批量消费队列消息
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {number} count 消费数量
+ * @returns {object} 批量消费结果
+ */
+async function _batchConsume(client, queue_name, count) {
+  var list = [];
+  for (var i = 0; i < count; i++) {
+    var raw = await client.rPopLPush(queue_name, queue_name + ':processing');
+    if (!raw) break;
+    list.push(JSON.parse(raw));
+  }
+  return { list: list, count: list.length, queue: queue_name };
+}
+
+/**
+ * 确认消费(删除处理中消息)
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {string} message_raw 原始消息字符串
+ * @returns {object} 确认结果
+ */
+async function _ack(client, queue_name, message_raw) {
+  if (!message_raw) {
+    return { error: { code: 'QUEUE_ACK_NO_MSG', message: '确认消费需要传入 _raw 消息原文' } };
+  }
+  var removed = await client.lRem(queue_name + ':processing', 1, message_raw);
+  return { msg: removed > 0 ? '消息已确认' : '消息未找到', queue: queue_name };
+}
+
+/**
+ * 消费失败重试(移回主队列)
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {string} message_raw 原始消息字符串
+ * @param {number} max_retries 最大重试次数
+ * @returns {object} 重试结果
+ */
+async function _retry(client, queue_name, message_raw, max_retries) {
+  if (!message_raw) {
+    return { error: { code: 'QUEUE_RETRY_NO_MSG', message: '重试需要传入 _raw 消息原文' } };
+  }
+  var max_retry = max_retries || 3;
+  var parsed = JSON.parse(message_raw);
+  var retry_count = (parsed._retry_count || 0) + 1;
+  if (retry_count > max_retry) {
+    await client.lRem(queue_name + ':processing', 1, message_raw);
+    parsed._retry_count = retry_count;
+    parsed._dlq_at = new Date().toISOString();
+    await client.lPush(queue_name + ':dlq', JSON.stringify(parsed));
+    return { msg: '已达最大重试次数，移入死信队列', retry_count: retry_count, queue: queue_name };
+  }
+  parsed._retry_count = retry_count;
+  await client.lRem(queue_name + ':processing', 1, message_raw);
+  await client.lPush(queue_name, JSON.stringify(parsed));
+  return { msg: '消息已重新入队', retry_count: retry_count, queue: queue_name };
+}
+
+/**
+ * 死信队列操作
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {string} dlq_action 死信操作: view/replay/clear
+ * @returns {object} 死信队列结果
+ */
+async function _dlq(client, queue_name, dlq_action) {
+  var dlq_key = queue_name + ':dlq';
+  switch (dlq_action) {
+    case 'view': {
+      var all = await client.lRange(dlq_key, 0, -1);
+      var list = (all || []).map(function (r) { return JSON.parse(r); });
+      return { list: list, count: list.length, queue: queue_name };
+    }
+    case 'replay': {
+      var moved = 0;
+      var msg;
+      while ((msg = await client.rPopLPush(dlq_key, queue_name)) !== null) {
+        moved++;
+      }
+      return { msg: '已重放 ' + moved + ' 条死信消息到主队列', count: moved, queue: queue_name };
+    }
+    case 'clear': {
+      var deleted = await client.del(dlq_key);
+      return { msg: '已清空死信队列', queue: queue_name };
+    }
+    default:
+      return { error: { code: 'QUEUE_DLQ_UNKNOWN', message: '不支持的死信操作: ' + dlq_action } };
+  }
+}
+
+/**
+ * 延迟消息
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @param {*} message 消息内容
+ * @param {number} delay_seconds 延迟秒数
+ * @returns {object} 延迟消息结果
+ */
+async function _delay(client, queue_name, message, delay_seconds) {
+  var delay_sec = delay_seconds || 0;
+  if (delay_sec <= 0) {
+    return { error: { code: 'QUEUE_DELAY_INVALID', message: '延迟时间必须大于0秒' } };
+  }
+  var exec_at = Date.now() + delay_sec * 1000;
+  await client.zAdd(queue_name + ':delay', { score: exec_at, value: JSON.stringify(message) });
+  return { msg: '延迟消息已添加', exec_at: new Date(exec_at).toISOString(), delay_seconds: delay_sec, queue: queue_name };
+}
+
+/**
+ * 将到期延迟消息移入主队列
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @returns {object} 迁移结果
+ */
+async function _delayPoll(client, queue_name) {
+  var now = Date.now();
+  var due_msgs = await client.zRangeByScore(queue_name + ':delay', 0, now);
+  if (!due_msgs || due_msgs.length === 0) {
+    return { msg: '无到期延迟消息', count: 0, queue: queue_name };
+  }
+  for (var i = 0; i < due_msgs.length; i++) {
+    await client.lPush(queue_name, due_msgs[i]);
+  }
+  await client.zRemRangeByScore(queue_name + ':delay', 0, now);
+  return { msg: '已迁移到期消息', count: due_msgs.length, queue: queue_name };
+}
+
+/**
+ * 查看队列状态
+ * @param {object} client Redis 客户端
+ * @param {string} queue_name 队列名称
+ * @returns {object} 队列状态
+ */
+async function _status(client, queue_name) {
+  var main_len = await client.lLen(queue_name);
+  var proc_len = await client.lLen(queue_name + ':processing');
+  var dlq_len = await client.lLen(queue_name + ':dlq');
+  var delay_len = await client.zCard(queue_name + ':delay');
+  return {
+    obj: {
+      queue: queue_name,
+      pending: main_len,
+      processing: proc_len,
+      dead_letter: dlq_len,
+      delayed: delay_len
+    }
+  };
+}
+
+/**
+ * 主函数
+ * @param {object} ctx 上下文
+ * @param {object} params 参数
+ * @returns {object} 执行结果
+ */
+async function main(params, ctx, options) {
+  var opts = (this && typeof this.getOptions === 'function') ? this.getOptions() : {};
+  var driver = opts.driver || 'redis';
+
+  if (driver !== 'redis') {
+    ctx.output = {
+      error: {
+        code: 'MGR_UNSUPPORTED_DRIVER',
+        message: '不支持的队列驱动: ' + driver + '，当前支持: redis'
+      }
+    };
+    return ctx.output;
+  }
+
+  var holder;
+  try {
+    holder = await _getClient(opts);
+  } catch (e) {
+    ctx.output = {
+      error: {
+        code: 'MGR_CONNECT_FAIL',
+        message: 'Redis 连接失败: ' + e.message
+      }
+    };
+    return ctx.output;
+  }
+
+  if (!holder || !holder.client) {
+    ctx.output = {
+      error: {
+        code: 'MGR_MISSING_DEP',
+        message: '消息队列需要 redis 库，请手动执行: npm install redis'
+      }
+    };
+    return ctx.output;
+  }
+  var client = holder.client;
+
+  var action = params.action || '';
+  var queue_name = params.queue_name || '';
+
+  if (!queue_name) {
+    ctx.output = { error: { code: 'QUEUE_NO_NAME', message: '队列名称不能为空' } };
+    await holder.release();
+    return ctx.output;
+  }
+
+  try {
+    switch (action) {
+      case 'publish':
+        ctx.output = await _publish(client, queue_name, params.message);
+        break;
+      case 'consume':
+        ctx.output = await _consume(client, queue_name);
+        break;
+      case 'batch_consume':
+        ctx.output = await _batchConsume(client, queue_name, params.count || 10);
+        break;
+      case 'ack':
+        ctx.output = await _ack(client, queue_name, params._raw);
+        break;
+      case 'retry':
+        ctx.output = await _retry(client, queue_name, params._raw, params.max_retries);
+        break;
+      case 'dlq':
+        ctx.output = await _dlq(client, queue_name, params.dlq_action);
+        break;
+      case 'delay':
+        ctx.output = await _delay(client, queue_name, params.message, params.delay_seconds);
+        break;
+      case 'delay_poll':
+        ctx.output = await _delayPoll(client, queue_name);
+        break;
+      case 'status':
+        ctx.output = await _status(client, queue_name);
+        break;
+      default:
+        ctx.output = {
+          error: { code: 'MGR_UNKNOWN_ACTION', message: '不支持的操作: ' + action }
+        };
+    }
+  } finally {
+    await holder.release();
+  }
+
+  return ctx.output;
+}
+
+module.exports = { main };

package/lib/tools/redis/index.js

@@ -0,0 +1,57 @@
+/**
+ * Redis管理器
+ * 管理 Redis 连接和缓存操作（基于 mm_redis）
+ */
+async function main(params, ctx, options) {
+  const { redisAdmin } = require('mm_redis');
+  var action = params.action || '';
+  var key = params.key || '';
+  var value = params.value;
+  var ttl = params.ttl || 0;
+  var field = params.field;
+  var body = params.body || {};
+
+  var opts = this.getOptions();
+
+  let config = { ...opts };
+
+  var redis = redisAdmin('os', config);
+  await redis.open();
+
+  const SIMPLE = [
+    'get', 'set', 'del', 'has', 'exists', 'add', 'getset',
+    'expire', 'pexpire', 'persist', 'ttl',
+    'incr', 'decr', 'incrby', 'decrby', 'incrbyfloat',
+    'keys', 'clear', 'clearExpire', 'dbsize', 'flushdb', 'isConnected',
+    'mget', 'mset',
+    'strlen', 'append', 'setrange',
+    'hgetall', 'hkeys', 'hvals', 'hlen', 'hdel', 'hmset', 'hmget',
+    'setForList', 'addForList', 'getForList', 'clearForList', 'hasForList',
+    'sadd', 'srem', 'sismember', 'smembers', 'scard', 'sinter', 'sunion', 'sdiff',
+    'zcard', 'zrem', 'zcount', 'zrevrange',
+    'publish', 'unsubscribe'
+  ];
+
+  const FIELD_METHODS = [
+    'hget', 'hset', 'hexists',
+    'zadd', 'zscore', 'zrank', 'zrevrank', 'zincrby'
+  ];
+
+  if (SIMPLE.indexOf(action) !== -1) {
+    ctx.output = await redis[action](key, value, ttl);
+  } else if (FIELD_METHODS.indexOf(action) !== -1) {
+    ctx.output = await redis[action](key, field, value, ttl);
+  } else if (action === 'hsetObj') {
+    ctx.output = await redis.hmset(key, body);
+  } else if (action === 'msetObj') {
+    ctx.output = await redis.mset(body, ttl);
+  } else {
+    ctx.output = {
+      error: { code: 'MGR_UNKNOWN_ACTION', message: '不支持的操作: ' + action }
+    };
+  }
+
+  return ctx.output;
+}
+
+module.exports = { main };

package/lib/tools/redis_lock/index.js

@@ -0,0 +1,210 @@
+/**
+ * Redis 分布式锁管理器
+ * 基于 Redis SET NX + TTL，使用 WATCH/MULTI/EXEC 实现原子释放和续期
+ * 防止锁过期后被误删：每次获取锁生成唯一 uuid，释放时验证 uuid 匹配
+ * 依赖: redis (v4+，与 mm_redis 共用同一个底层库)
+ */
+
+/**
+ * 生成唯一锁标识
+ * @returns {string} 唯一锁值
+ */
+function _genLockValue() {
+  return Date.now().toString(36) + '-' + Math.random().toString(36).substr(2, 9);
+}
+
+/**
+ * 获取 Redis 客户端（复用 mm_redis 连接池，不可用时自建独立连接）
+ * @param {object} opts 配置选项
+ * @returns {object} { client, release } 或 null
+ */
+async function _getClient(opts) {
+  var redis_admin = null;
+  try {
+    var { redisAdmin } = require('mm_redis');
+    if (redisAdmin) {
+      redis_admin = redisAdmin('os', opts);
+    }
+  } catch (e) {
+    // mm_redis 不可用时使用传入的 opts
+  }
+
+  // 优先复用 mm_redis 连接池，保证配置一致且不新建独立连接
+  if (redis_admin && typeof redis_admin._getConnection === 'function') {
+    var conn = await redis_admin._getConnection();
+    return {
+      client: conn,
+      release: function () {
+        try {
+          redis_admin._releaseConnection(conn);
+        } catch (e) {
+          void e;
+        }
+      }
+    };
+  }
+
+  // 回退: mm_redis 不可用，自建独立连接
+  var redis_mod = require('redis');
+  if (!redis_mod || !redis_mod.createClient) {
+    return null;
+  }
+  var createClient = redis_mod.createClient;
+  var client = createClient({
+    socket: {
+      host: opts.host || 'localhost',
+      port: opts.port || 6379,
+      connectTimeout: 5000
+    },
+    password: opts.password || '',
+    database: opts.db || 0
+  });
+  await client.connect();
+  return {
+    client: client,
+    release: function () {
+      try {
+        client.quit();
+      } catch (e) {
+        void e;
+      }
+    }
+  };
+}
+
+/**
+ * 获取分布式锁
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {number} ttl 锁过期时间(秒)
+ * @returns {object} 获取结果
+ */
+async function _acquire(client, lock_key, ttl) {
+  var lock_value = _genLockValue();
+  var ttl_sec = ttl || 30;
+  var result = await client.set(lock_key, lock_value, { EX: ttl_sec, NX: true });
+  if (result === 'OK') {
+    return { acquired: true, lock_key: lock_key, lock_value: lock_value, ttl: ttl_sec };
+  }
+  return { acquired: false, lock_key: lock_key, msg: '锁已被占用' };
+}
+
+/**
+ * 释放分布式锁(WATCH/MULTI/EXEC 原子操作)
+ * 原理: WATCH 监控键 → 验证持有者 → MULTI 事务删除 → EXEC 提交
+ * 如果 EXEC 返回 null 说明 WATCH 期间键被修改(锁已被他人持有或过期后重新获取)，放弃删除
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {string} lock_value 锁值(需与获取时一致)
+ * @returns {object} 释放结果
+ */
+async function _release(client, lock_key, lock_value) {
+  if (!lock_value) {
+    return { released: false, msg: '缺少 lock_value，无法安全释放锁' };
+  }
+  await client.watch(lock_key);
+  var current = await client.get(lock_key);
+  if (current !== lock_value) {
+    await client.unwatch();
+    return { released: false, lock_key: lock_key, msg: '锁已被他人持有或已过期' };
+  }
+  var exec_result = await client.multi().del(lock_key).exec();
+  if (exec_result === null) {
+    return { released: false, lock_key: lock_key, msg: '锁在释放过程中被修改，放弃删除' };
+  }
+  return { released: true, lock_key: lock_key };
+}
+
+/**
+ * 锁续期(WATCH/MULTI/EXEC 原子操作)
+ * 原理: 同释放，将 DEL 替换为 EXPIRE
+ * @param {object} client Redis 客户端
+ * @param {string} lock_key 锁键名
+ * @param {string} lock_value 锁值(需与获取时一致)
+ * @param {number} ttl 续期时间(秒)
+ * @returns {object} 续期结果
+ */
+async function _renew(client, lock_key, lock_value, ttl) {
+  if (!lock_value) {
+    return { renewed: false, msg: '缺少 lock_value，无法续期' };
+  }
+  var ttl_sec = ttl || 30;
+  await client.watch(lock_key);
+  var current = await client.get(lock_key);
+  if (current !== lock_value) {
+    await client.unwatch();
+    return { renewed: false, lock_key: lock_key, msg: '锁已被他人持有或已过期' };
+  }
+  var exec_result = await client.multi().expire(lock_key, ttl_sec).exec();
+  if (exec_result === null) {
+    return { renewed: false, lock_key: lock_key, msg: '锁在续期过程中被修改' };
+  }
+  return { renewed: true, lock_key: lock_key, ttl: ttl_sec };
+}
+
+/**
+ * 主函数
+ * @param {object} ctx 上下文
+ * @param {object} params 参数
+ * @returns {object} 执行结果
+ */
+async function main(params, ctx, options) {
+  var opts = (this && typeof this.getOptions === 'function') ? this.getOptions() : {};
+
+  var holder;
+  try {
+    holder = await _getClient(opts);
+  } catch (e) {
+    ctx.output = {
+      error: {
+        code: 'LOCK_CONNECT_FAIL',
+        message: 'Redis 连接失败: ' + e.message
+      }
+    };
+    return ctx.output;
+  }
+
+  if (!holder || !holder.client) {
+    ctx.output = {
+      error: {
+        code: 'LOCK_MISSING_DEP',
+        message: '分布式锁需要 redis 库，请手动执行: npm install redis'
+      }
+    };
+    return ctx.output;
+  }
+  var client = holder.client;
+
+  var action = params.action || '';
+  var lock_key = params.lock_key || '';
+
+  if (!lock_key) {
+    ctx.output = { error: { code: 'LOCK_NO_KEY', message: '锁键名 lock_key 不能为空' } };
+    await holder.release();
+    return ctx.output;
+  }
+
+  try {
+    switch (action) {
+      case 'acquire':
+        ctx.output = await _acquire(client, lock_key, params.ttl);
+        break;
+      case 'release':
+        ctx.output = await _release(client, lock_key, params.lock_value);
+        break;
+      case 'renew':
+        ctx.output = await _renew(client, lock_key, params.lock_value, params.ttl);
+        break;
+      default:
+        ctx.output = {
+          error: { code: 'LOCK_UNKNOWN_ACTION', message: '不支持的操作: ' + action + '，支持: acquire/release/renew' }
+        };
+    }
+  } finally {
+    await holder.release();
+  }
+
+  return ctx.output;
+}
+
+module.exports = { main };

package/package.json

@@ -1,50 +1,51 @@
 {
-    "name": "mm_redis",
-    "version": "2.1.8",
-    "description": "高效的Redis客户端封装库，提供连接池管理、数据类型操作、错误处理和批量操作优化",
-    "main": "index.js",
-    "scripts": {
-        "test": "node test.js",
-        "dev": "nodemon test.js"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://gitee.com/qiuwenwu91/mm_redis.git"
-    },
-    "keywords": [
-        "mm_mod",
-        "mm_adapter",
-        "mm_redis",
-        "redis",
-        "cache",
-        "client",
-        "connection-pool",
-        "pipeline",
-        "hash",
-        "set",
-        "sorted-set",
-        "list",
-        "redis-client",
-        "nodejs"
-    ],
-    "layer": "adapter",
-    "group": "redis",
-    "author": "qww",
-    "license": "ISC",
-    "bugs": {
-        "url": "https://gitee.com/qiuwenwu91/mm_redis/issues"
-    },
-    "homepage": "https://www.npmjs.com/package/mm_redis",
-    "dependencies": {
-        "mm_corejs": "^1.1.4",
-        "mm_mod": "^1.0.1",
-        "mm_helper": "^1.0.0",
-        "redis": "^6.2.1"
-    },
-    "engines": {
-        "node": ">=14.0.0"
-    },
-    "devDependencies": {
-        "mm_eslint": "^1.7.7"
-    }
+  "name": "mm_redis",
+  "version": "2.3.0",
+  "description": "高效的Redis客户端封装库，提供连接池管理、数据类型操作、错误处理和批量操作优化",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js",
+    "dev": "nodemon test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_redis.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_adapter",
+    "mm_redis",
+    "redis",
+    "cache",
+    "client",
+    "connection-pool",
+    "pipeline",
+    "hash",
+    "set",
+    "sorted-set",
+    "list",
+    "redis-client",
+    "nodejs"
+  ],
+  "layer": "infrastructure",
+  "group": "cache",
+  "author": "qww",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_redis/issues"
+  },
+  "homepage": "https://www.npmjs.com/package/mm_redis",
+  "dependencies": {
+    "mm_admin": "^1.1.0",
+    "mm_eslint": "^1.0.0",
+    "mm_helper": "^1.0.0",
+    "mm_mod": "^1.0.1",
+    "redis": "^6.2.1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "mm_eslint": "^1.7.7"
+  }
 }

package/tool/push_queue/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * push_queue —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/push_queue/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.push_queue 复用。
+ */
+module.exports = require('../../lib/tools/push_queue');

package/tool/push_queue/tool.json

@@ -0,0 +1,56 @@
+{
+  "name": "push_queue",
+  "handler": "sender",
+  "title": "队列发信器",
+  "description": "将消息写入 Redis 消息队列（lPush）。适用场景：需要异步解耦、削峰填谷或与消费端对接时。工作流提示：queue_name 必填队列名称，data 填消息数据（会 JSON 序列化），返回 sent 与 message 确认入队结果。",
+  "type": "gateway",
+  "params": {
+    "type": "object",
+    "properties": {
+      "queue_name": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "data": {
+        "description": "消息数据"
+      }
+    },
+    "required": [
+      "queue_name",
+      "data"
+    ]
+  },
+  "returns": {
+    "description": "返回队列发信结果，正常时包含队列名称与消息数据，异常时包含错误码与错误信息",
+    "type": "object",
+    "properties": {
+      "sent": {
+        "type": "boolean",
+        "description": "是否入队成功"
+      },
+      "tip": {
+        "type": "string",
+        "description": "提示信息"
+      },
+      "message": {
+        "description": "消息数据"
+      },
+      "error": {
+        "type": "object",
+        "description": "错误信息，仅调用出错时返回",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "错误码"
+          },
+          "message": {
+            "type": "string",
+            "description": "错误描述"
+          }
+        }
+      }
+    }
+  },
+  "options": {},
+  "group": "transport"
+}

package/tool/queue/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * queue —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/queue/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.queue 复用。
+ */
+module.exports = require('../../lib/tools/queue');

package/tool/queue/tool.json

@@ -0,0 +1,129 @@
+{
+  "name": "queue",
+  "handler": "manager",
+  "title": "消息队列管理器",
+  "description": "消息队列发布、消费、确认、重试、死信。适用场景：异步解耦、可靠传递。工作流提示：action 与 queue_name 必填，publish/delay 配 message，消费后 _raw 做 ack/retry，死信 dlq 配 dlq_action，结果在 obj/list、ID 在 message_id。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: publish/consume/batch_consume/ack/retry/dlq/delay/delay_poll/status",
+        "enum": [
+          "publish",
+          "consume",
+          "batch_consume",
+          "ack",
+          "retry",
+          "dlq",
+          "delay",
+          "delay_poll",
+          "status"
+        ]
+      },
+      "queue_name": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "message": {
+        "description": "消息内容(publish/delay时必填)"
+      },
+      "count": {
+        "type": "number",
+        "description": "批量消费数量(batch_consume时使用，默认10)"
+      },
+      "_raw": {
+        "type": "string",
+        "description": "消费时返回的原始消息字符串(ack/retry时必填)"
+      },
+      "max_retries": {
+        "type": "number",
+        "description": "最大重试次数(retry时使用，默认3)"
+      },
+      "dlq_action": {
+        "type": "string",
+        "description": "死信操作: view/replay/clear (dlq时使用)",
+        "enum": [
+          "view",
+          "replay",
+          "clear"
+        ]
+      },
+      "delay_seconds": {
+        "type": "number",
+        "description": "延迟秒数(delay时使用，必须>0)"
+      }
+    },
+    "required": [
+      "action",
+      "queue_name"
+    ]
+  },
+  "returns": {
+    "description": "管理操作结果，读操作返回 obj/list，写操作返回 msg/message_id/queue，异常时返回 error",
+    "type": "object",
+    "properties": {
+      "obj": {
+        "description": "消费的消息内容或状态"
+      },
+      "list": {
+        "type": "array",
+        "description": "批量消费的消息列表"
+      },
+      "msg": {
+        "type": "string",
+        "description": "操作结果描述"
+      },
+      "message_id": {
+        "type": "string",
+        "description": "消息ID"
+      },
+      "queue": {
+        "type": "string",
+        "description": "队列名称"
+      },
+      "count": {
+        "type": "number",
+        "description": "操作影响的消息数量"
+      },
+      "retry_count": {
+        "type": "number",
+        "description": "当前重试次数"
+      },
+      "delay_seconds": {
+        "type": "number",
+        "description": "延迟秒数"
+      },
+      "exec_at": {
+        "type": "string",
+        "description": "延迟消息执行时间"
+      }
+    }
+  },
+  "options": {
+    "driver": {
+      "type": "string",
+      "description": "队列驱动: redis",
+      "default": "redis"
+    },
+    "host": {
+      "type": "string",
+      "description": "队列服务主机",
+      "default": "localhost"
+    },
+    "port": {
+      "type": "number",
+      "description": "队列服务端口"
+    },
+    "password": {
+      "type": "string",
+      "description": "队列服务密码"
+    },
+    "db": {
+      "type": "number",
+      "description": "Redis 数据库编号"
+    }
+  },
+  "group": "system"
+}

package/tool/redis/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * redis —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/redis/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.redis 复用。
+ */
+module.exports = require('../../lib/tools/redis');

package/tool/redis/tool.json

@@ -0,0 +1,133 @@
+{
+  "name": "redis",
+  "handler": "manager",
+  "title": "Redis管理器",
+  "description": "管理 Redis 缓存，覆盖键值、哈希、列表、集合、有序集合、发布订阅。适用场景：缓存数据、计数器、分布式协作或消息订阅时。工作流提示：action 与 key 必填，字符串配 value/ttl，哈希配 field/body，集合/有序集合/pub/sub 有专属 action，返回随操作而定。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型",
+        "enum": [
+          "get",
+          "set",
+          "del",
+          "has",
+          "exists",
+          "add",
+          "getset",
+          "expire",
+          "pexpire",
+          "persist",
+          "ttl",
+          "incr",
+          "decr",
+          "incrby",
+          "decrby",
+          "incrbyfloat",
+          "keys",
+          "clear",
+          "clearExpire",
+          "dbsize",
+          "flushdb",
+          "isConnected",
+          "mget",
+          "mset",
+          "msetObj",
+          "strlen",
+          "append",
+          "setrange",
+          "hget",
+          "hset",
+          "hgetall",
+          "hkeys",
+          "hvals",
+          "hlen",
+          "hdel",
+          "hmset",
+          "hmget",
+          "hexists",
+          "hsetObj",
+          "setForList",
+          "addForList",
+          "getForList",
+          "clearForList",
+          "hasForList",
+          "sadd",
+          "srem",
+          "sismember",
+          "smembers",
+          "scard",
+          "sinter",
+          "sunion",
+          "sdiff",
+          "zadd",
+          "zrem",
+          "zscore",
+          "zrank",
+          "zrevrank",
+          "zincrby",
+          "zcard",
+          "zcount",
+          "zrevrange",
+          "publish",
+          "unsubscribe"
+        ]
+      },
+      "key": {
+        "type": "string",
+        "description": "缓存键"
+      },
+      "value": {
+        "description": "缓存值/增量值/成员等"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "过期时间(秒)",
+        "min": 0,
+        "max": 31536000
+      },
+      "field": {
+        "type": "string",
+        "description": "哈希字段名/有序集合成员名(哈希和有序集合操作)"
+      },
+      "body": {
+        "type": "object",
+        "description": "批量数据对象(hsetObj/msetObj 操作)"
+      }
+    },
+    "required": [
+      "action",
+      "key"
+    ]
+  },
+  "returns": {
+    "description": "管理操作结果，返回值类型根据操作而定",
+    "type": "object"
+  },
+  "options": {
+    "host": {
+      "type": "string",
+      "description": "Redis主机地址",
+      "default": "127.0.0.1"
+    },
+    "port": {
+      "type": "number",
+      "description": "Redis端口",
+      "default": 6379
+    },
+    "password": {
+      "type": "string",
+      "description": "Redis密码",
+      "default": "asd159357"
+    },
+    "db": {
+      "type": "number",
+      "description": "数据库编号",
+      "default": 0
+    }
+  },
+  "group": "storage"
+}

package/tool/redis_lock/index.js

@@ -0,0 +1,7 @@
+'use strict';
+/**
+ * redis_lock —— 工具契约适配层
+ * 业务实现归位于模块 lib/tools/redis_lock/，本文件只把模块能力暴露给加载器。
+ * 其它模块可直接 require('mm_redis').tools.redis_lock 复用。
+ */
+module.exports = require('../../lib/tools/redis_lock');

package/tool/redis_lock/tool.json

@@ -0,0 +1,91 @@
+{
+  "name": "redis_lock",
+  "handler": "manager",
+  "title": "Redis分布式锁",
+  "description": "基于 Redis 的分布式锁，支持获取、释放、续期，防过期误删。适用场景：多实例并发互斥访问共享资源时。工作流提示：action 选 acquire/release/renew，lock_key 必填，release/renew 回传 acquire 的 lock_value，ttl 设秒数，获取在 acquired。",
+  "type": "data",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: acquire/release/renew",
+        "enum": [
+          "acquire",
+          "release",
+          "renew"
+        ]
+      },
+      "lock_key": {
+        "type": "string",
+        "description": "锁键名，建议格式: lock:业务:资源ID"
+      },
+      "lock_value": {
+        "type": "string",
+        "description": "锁值(release/renew时必填，需与acquire返回的lock_value一致)"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "锁过期时间(秒)，默认30秒"
+      }
+    },
+    "required": [
+      "action",
+      "lock_key"
+    ]
+  },
+  "returns": {
+    "description": "锁操作结果，acquire返回lock_value用于后续释放/续期",
+    "type": "object",
+    "properties": {
+      "acquired": {
+        "type": "boolean",
+        "description": "是否获取锁成功(acquire操作)"
+      },
+      "released": {
+        "type": "boolean",
+        "description": "是否释放锁成功(release操作)"
+      },
+      "renewed": {
+        "type": "boolean",
+        "description": "是否续期成功(renew操作)"
+      },
+      "lock_key": {
+        "type": "string",
+        "description": "锁键名"
+      },
+      "lock_value": {
+        "type": "string",
+        "description": "锁唯一标识(acquire时返回，用于后续释放/续期)"
+      },
+      "ttl": {
+        "type": "number",
+        "description": "锁过期时间(秒)"
+      },
+      "msg": {
+        "type": "string",
+        "description": "操作结果描述"
+      }
+    }
+  },
+  "options": {
+    "host": {
+      "type": "string",
+      "description": "Redis 主机",
+      "default": "localhost"
+    },
+    "port": {
+      "type": "number",
+      "description": "Redis 端口"
+    },
+    "password": {
+      "type": "string",
+      "description": "Redis 密码"
+    },
+    "db": {
+      "type": "number",
+      "description": "Redis 数据库编号"
+    }
+  },
+  "group": "system"
+}