mm_filter 1.0.0 → 1.0.1

package/README.md

@@ -38,7 +38,7 @@ filter.delFilter('content', 'upper');
 filter.clear('content'); // 清空指定过滤
 filter.clear();          // 清空全部
 
-// 通过 Admin 工厂按作用域取实例（需安装 mm_corejs）
+// 通过 Admin 工厂按作用域取实例（需安装 mm_admin）
 var admin = filterAdmin('os', { /* config */ });
 ```
 
@@ -64,3 +64,12 @@ var admin = filterAdmin('os', { /* config */ });
 
 `mm_tpl` 内部的 `Hook` 类是本模块（以及 `mm_action`、`mm_func`）的组合门面：
 模板渲染中 `m.hookFilter(name, content)` 的调用最终由 `mm_filter` 执行。
+
+## 工具契约（LLM 可调用）
+
+本模块 `tool/` 下登记以下工具契约，实现位于 `lib/tools/<name>/`，`tool/<name>/index.js` 仅为薄适配层。
+其它模块可直接 `require('<pkg>').tools.<name>` 复用实现，无需经过工具注册面。
+
+| 工具名 | 标题 | 说明 |
+| --- | --- | --- |
+| `filter_hook` | 过滤钩子查询与管道执行 | 过滤清单、管道执行、删除、清空 |

package/index.js

@@ -1,16 +1,8 @@
 const Filter = require('./lib/filter');
-let Admin = null;
-try {
-  Admin = require('mm_corejs').Admin;
-} catch (e) {
-  // mm_corejs 未安装时仅提供核心类，Admin 工厂不可用
-}
+const { reg } = require('mm_admin');
 
-let admin = null;
-if (Admin) {
-  admin = new Admin();
-  admin.setClass(Filter);
-}
+const admin = reg('mm_filter');
+admin.setClass(Filter);
 
 module.exports = {
   Filter,
@@ -19,9 +11,10 @@ module.exports = {
     if (!admin) {
       throw new Error('mm_filter: mm_corejs 未安装，Admin 工厂不可用');
     }
-    if (!scope) {
-      scope = 'os';
-    }
-    return admin.get(scope, config);
+    return admin.get(scope || 'os', config);
   }
 };
+
+/* mm-tool-logic-export 工具能力层：其它模块可 require("mm_filter").tools.<name> 直接引用 */
+Object.defineProperty(module.exports, 'tools', { enumerable: true, configurable: true,
+  get: function () { return require('./lib/tools'); } });

package/lib/tools/filter_hook/index.js

@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * filter_hook —— 过滤钩子查询与管道执行工具
+ * 复用模块 Filter 实例的过滤注册表，管道语义由 runFilter 维护。
+ */
+const { filterAdmin } = require('../../../index.js');
+
+async function main(params, ctx, options) {
+  void options;
+  const p = params || {};
+  const action = p.action || 'list';
+  const done = (data) => { ctx.output = data; return data; };
+
+  try {
+    const inst = filterAdmin(p.scope || 'os');
+
+    if (action === 'list') {
+      const names = inst.listFilters(p.name);
+      return done({ code: 0, msg: '成功', name: p.name || '', count: names.length, list: names });
+    }
+
+    if (action === 'has') {
+      if (!p.name) throw new TypeError('name 不能为空');
+      return done({ code: 0, msg: '成功', name: p.name, exists: inst.hasFilter(p.name) });
+    }
+
+    if (action === 'run') {
+      if (!p.name) throw new TypeError('name 不能为空');
+      const args = Array.isArray(p.args) ? p.args : [];
+      const value = inst.runFilter(p.name, p.value, ...args);
+      return done({ code: 0, msg: '执行完成', name: p.name, value });
+    }
+
+    if (action === 'del') {
+      if (!p.name || !p.alias) throw new TypeError('del 需要 name 与 alias');
+      const ok = inst.delFilter(p.name, p.alias);
+      return done({ code: 0, msg: ok ? '删除成功' : '别名不存在', name: p.name, alias: p.alias, deleted: !!ok });
+    }
+
+    if (action === 'clear') {
+      inst.clear(p.name);
+      return done({ code: 0, msg: '已清空', name: p.name || '' });
+    }
+
+    return done({ code: 10001, msg: '不支持的操作: ' + action });
+  } catch (error) {
+    return done({ code: 10000, msg: '执行失败：' + error.message, error: { name: error.name, message: error.message } });
+  }
+}
+
+module.exports = { main };

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mm_filter",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "过滤钩子管理模块：提供过滤钩子 addFilter/delFilter/runFilter 的注册与管道执行能力",
     "main": "index.js",
     "repository": {
@@ -14,8 +14,8 @@
         "hook",
         "过滤"
     ],
-    "layer": "infra",
-    "group": "common",
+    "layer": "shared",
+    "group": "hooks",
     "author": "邱文武",
     "license": "ISC",
     "engines": {
@@ -25,6 +25,6 @@
         "test": "node test.js"
     },
     "dependencies": {
-        "mm_corejs": "^1.1.6"
+        "mm_admin": "^1.1.0"
     }
 }

package/test.js

@@ -2,7 +2,7 @@
 
 const assert = require('assert');
 const mod = require('./index.js');
-const Filter = require('./lib/filter');
+const Filter = require('./lib/filter.js');
 
 // 1. 导出结构校验
 assert.strictEqual(typeof mod.Filter, 'function', '应导出 Filter 类');

package/tool/filter_hook/index.js

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

package/tool/filter_hook/tool.json

@@ -0,0 +1,82 @@
+{
+  "name": "filter_hook",
+  "title": "过滤钩子查询与管道执行",
+  "description": "基于 mm_filter 的过滤钩子能力：列出过滤名、判断是否存在、按管道语义依次执行过滤函数并返回最终值、删除或清空过滤。适用场景：确认某过滤链挂了哪些处理器、用现有过滤链加工一段文本/数据。注意：注册过滤需要传函数，LLM 侧只做查询/执行/清理。",
+  "category": "钩子系统",
+  "group": "hooks",
+  "type": "function",
+  "main": "./index.js",
+  "params": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "description": "操作类型: list(列出过滤)/has(判断存在)/run(管道执行)/del(删除过滤)/clear(清空过滤)",
+        "enum": [
+          "list",
+          "has",
+          "run",
+          "del",
+          "clear"
+        ],
+        "default": "list"
+      },
+      "name": {
+        "type": "string",
+        "description": "过滤名称(list 可省略表示全部)"
+      },
+      "alias": {
+        "type": "string",
+        "description": "过滤别名(del 必填)"
+      },
+      "value": {
+        "description": "待过滤的初始值(run 必填)"
+      },
+      "args": {
+        "type": "array",
+        "description": "过滤函数的额外参数(run 可选)"
+      },
+      "scope": {
+        "type": "string",
+        "description": "实例作用域，缺省 os",
+        "default": "os"
+      }
+    },
+    "required": [
+      "action"
+    ]
+  },
+  "returns": {
+    "type": "object",
+    "properties": {
+      "code": {
+        "type": "number",
+        "description": "0 表示成功，1xxxx 表示业务/执行异常"
+      },
+      "msg": {
+        "type": "string",
+        "description": "结果描述"
+      },
+      "list": {
+        "type": "array",
+        "description": "过滤名称列表或过滤项摘要"
+      },
+      "count": {
+        "type": "number",
+        "description": "数量"
+      },
+      "exists": {
+        "type": "boolean",
+        "description": "是否存在(has)"
+      },
+      "value": {
+        "description": "过滤后的最终值(run)"
+      },
+      "error": {
+        "type": "object",
+        "description": "异常对象 { name, message }"
+      }
+    }
+  },
+  "handler": "manager"
+}