mm_toolkit 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# mm_tools 工具模块
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+工具是服务端暴露的可执行函数，让 AI 模型能够执行具体操作（如查询天气、发送消息、计算等）。本模块负责工具的参数转换（OpenAI function calling 格式）、脚本装载与执行，基于 `mm_mod` 生命周期，无全局对象与原型扩展依赖。
+
+## 安装与引用
+
+```bash
+npm install mm_tools
+```
+
+```javascript
+const { Tool, ToolManager, toolsAdmin } = require('mm_tools');
+```
+
+## 快速使用
+
+```javascript
+const { Manager } = require('mm_tools');
+
+const manager = new Manager({ dir: './ai/tool' });
+
+// 目录加载：每个子目录一个 tool.json（支持多层分组目录）
+const tools = await manager.load('./ai/tool');
+
+// 批量初始化，注入服务器/事件/日志
+await manager.runAll('init', server, eventer, logger);
+
+const tool = manager.getMod('read_file');
+console.log(tool.toFunctionCall());
+
+// 装载脚本并执行
+tool.loadScript();
+const ret = await tool.main({ file: './README.md', encoding: 'utf-8' });
+```
+
+```javascript
+// 手动登记并初始化
+const tool = await manager.create(
+  {
+    name: 'sum',
+    title: '求和',
+    params: [
+      { name: 'a', type: 'number', required: true },
+      { name: 'b', type: 'number', required: true }
+    ]
+  },
+  server, eventer, logger
+);
+```
+
+## 工具目录结构
+
+```text
+tool/
+└── group/
+    └── read_file/
+        ├── tool.json     # 工具配置
+        └── index.js      # 工具脚本，导出 main 及子函数
+```
+
+## 工具脚本规范
+
+脚本导出对象中的函数会被绑定到工具实例，`main` 内部可通过 `this.xxx()` 复用子函数。
+
+```javascript
+module.exports = {
+  async calc(params) {
+    return params.a + params.b;
+  },
+  async main(params) {
+    try {
+      const data = await this.calc(params);
+      return { code: 0, msg: '执行成功', data };
+    } catch (error) {
+      return { code: 10000, msg: '执行失败！原因：' + error.message };
+    }
+  }
+};
+```
+
+## 主要接口
+
+| 接口 | 说明 |
+| --- | --- |
+| `manager.add(config)` | 登记工具，不初始化 |
+| `manager.create(config, server, eventer, logger)` | 登记并初始化工具 |
+| `manager.load(dir)` | 递归扫描目录加载全部工具 |
+| `manager.runAll('init', server, eventer, logger)` | 批量初始化并注入依赖 |
+| `manager.del(name)` | 注销并释放工具 |
+| `manager.reload(name)` | 重新读取配置并注册 |
+| `tool.toFunctionCall()` | 转换为 OpenAI function calling 格式 |
+| `tool.loadScript()` | 装载工具脚本并绑定导出函数 |
+| `tool.isLoaded()` | 脚本是否已装载 |
+| `tool.main(params)` | 执行工具（由脚本覆盖） |
+| `tool.getDetail()` | 获取工具详情（目录、配置文件、脚本文件） |
+| `tool.getAgent/getProject/getTask/getSkill/getTool/getLLM` | 通过服务器获取关联对象 |
+
+## 支持处理的文件
+
+- [文件工具](file.md)
+
+## 依赖
+
+- `mm_mod`：生命周期基类与管理器
+- `mm_corejs`：Admin 工厂
+- 原生 `fs` / `path`：替代 `.fullname()/.addDir()/.saveText()/.loadText()` 等原型扩展
+
+## 测试
+
+```bash
+npm test
+```

package/config.tpl.json

@@ -0,0 +1,30 @@
+{
+  // 工具名称
+  "name": "${name}",
+  // 工具标题(显示的中文名)
+  "title": "${title}",
+  // 工具描述
+  "description": "${description}",
+  // 工具分组
+  "group": "${group}",
+  // 工具类型, 默认为"function"
+  "type": "function",
+  // 工具主文件路径
+  "main": "./index.js",
+  // 工具是否严格模式参数校验
+  "strict": true,
+  // 工具参数是否允许额外字段
+  "add_params": false,
+  // 工具参数
+  "params": [],
+  // 工具返回值
+  "returns": [],
+  // 工具排序
+  "sort": 10,
+  // 工具状态, 0表示未启用, 1表示启用
+  "state": 1,
+  // 工具显示, 0表示不显示, 1表示显示
+  "show": 0,
+  // 是否结束
+  "end": false
+}

package/file.md

@@ -0,0 +1,2 @@
+## 支持的文件类型
+.epub,.mobi,.azw3,.pdf,.png,.jpg,.jpeg,.svg,.svgz,.bmp,.gif,.webp,.ico,.xbm,.dib,.pjp,.tif,.pjpeg,.avif,.apng,.tiff,.jfif,.txt,.md,.csv,.tsv,.html,.json,.log,.dot,.go,.h,.c,.cpp,.cxx,.cc,.cs,.java,.js,.css,.jsp,.php,.py,.py3,.asp,.yaml,.yml,.ini,.conf,.ts,.tsx,.doc,.docx,.ppt,.pptx,.xls,.xlsx,.abap,.asc,.ash,.ampl,.mod,.g4,.apib,.apl,.dyalog,.asax,.ascx,.ashx,.asmx,.aspx,.axd,.dats,.hats,.sats,.as,.adb,.ada,.ads,.agda,.als,.apacheconf,.vhost,.cls,.applescript,.scpt,.arc,.ino,.asciidoc,.adoc,.aj,.asm,.a51,.inc,.nasm,.aug,.ahk,.ahkl,.au3,.awk,.auk,.gawk,.mawk,.nawk,.bat,.cmd,.befunge,.bison,.bb,.decls,.bmx,.bsv,.boo,.b,.bf,.brs,.bro,.cats,.idc,.w,.cake,.cshtml,.csx,.c++,.cp,.h++,.hh,.hpp,.hxx,.inl,.ipp,.tcc,.tpp,.c-objdump,.chs,.clp,.cmake,.in,.cob,.cbl,.ccp,.cobol,.cpy,.capnp,.mss,.ceylon,.chpl,.ch,.ck,.cirru,.clw,.icl,.dcl,.click,.clj,.boot,.cl2,.cljc,.cljs,.hl,.cljscm,.cljx,.hic,.coffee,._coffee,.cjsx,.cson,.iced,.cfm,.cfml,.cfc,.lisp,.asd,.cl,.l,.lsp,.ny,.podsl,.sexp,.cps,.coq,.v,.cppobjdump,.c++-objdump,.c++objdump,.cpp-objdump,.cxx-objdump,.creole,.cr,.feature,.cu,.cuh,.cy,.pyx,.pxd,.pxi,.d,.di,.d-objdump,.com,.dm,.zone,.arpa,.darcspatch,.dpatch,.dart,.diff,.patch,.dockerfile,.djs,.dylan,.dyl,.intr,.lid,.E,.ecl,.eclxml,.sch,.brd,.epj,.e,.ex,.exs,.elm,.el,.emacs,.desktop,.em,.emberscript,.erl,.es,.escript,.hrl,.xrl,.yrl,.fs,.fsi,.fsx,.fx,.flux,.f90,.f,.f03,.f08,.f77,.f95,.for,.fpp,.factor,.fy,.fancypack,.fan,.fth,.4th,.forth,.fr,.frt,.ftl,.g,.gco,.gcode,.gms,.gap,.gd,.gi,.tst,.s,.ms,.glsl,.fp,.frag,.frg,.fsh,.fshader,.geo,.geom,.glslv,.gshader,.shader,.vert,.vrx,.vsh,.vshader,.gml,.kid,.ebuild,.eclass,.po,.pot,.glf,.gp,.gnu,.gnuplot,.plot,.plt,.golo,.gs,.gst,.gsx,.vark,.grace,.gradle,.gf,.graphql,.gv,.man,.1in,.1m,.1x,.3in,.3m,.3qt,.3x,.me,.n,.rno,.roff,.groovy,.grt,.gtpl,.gvy,.gsp,.hcl,.tf,.hlsl,.fxh,.hlsli,.htm,.st,.xht,.xhtml,.mustache,.jinja,.eex,.erb,.deface,.phtml,.http,.haml,.handlebars,.hbs,.hb,.hs,.hsc,.hx,.hxsl,.hy,.pro,.dlm,.ipf,.cfg,.prefs,.properties,.irclog,.weechatlog,.idr,.lidr,.ni,.i7x,.iss,.io,.ik,.thy,.ijs,.flex,.jflex,.geojson,.lock,.topojson,.json5,.jsonld,.jq,.jsx,.jade,.j,._js,.bones,.es6,.jake,.jsb,.jscad,.jsfl,.jsm,.jss,.njs,.pac,.sjs,.ssjs,.sublime-build,.sublime-commands,.sublime-completions,.sublime-keymap,.sublime-macro,.sublime-menu,.sublime-mousemap,.sublime-project,.sublime-settings,.sublime-theme,.sublime-workspace,.sublime_metrics,.sublime_session,.xsjs,.xsjslib,.jl,.ipynb,.krl,.kicad_pcb,.kit,.kt,.ktm,.kts,.lfe,.ll,.lol,.lsl,.lslp,.lvproj,.lasso,.las,.lasso8,.lasso9,.ldml,.latte,.lean,.hlean,.less,.lex,.ly,.ily,.m,.ld,.lds,.liquid,.lagda,.litcoffee,.lhs,.ls,._ls,.xm,.x,.xi,.lgt,.logtalk,.lookml,.lua,.fcgi,.nse,.pd_lua,.rbxs,.wlua,.mumps,.m4,.mcr,.mtml,.muf,.mak,.mk,.mkfile,.mako,.mao,.markdown,.mkd,.mkdn,.mkdown,.ron,.mask,.mathematica,.cdf,.ma,.map,.mt,.nb,.nbp,.wl,.wlt,.matlab,.maxpat,.maxhelp,.maxproj,.mxt,.pat,.mediawiki,.wiki,.moo,.metal,.minid,.druby,.duby,.mir,.mirah,.mo,.mms,.mmk,.monkey,.moon,.myt,.ncl,.nl,.nsi,.nsh,.axs,.axi,.nlogo,.nginxconf,.nim,.nimrod,.ninja,.nit,.nix,.nu,.numpy,.numpyw,.numsc,.ml,.eliom,.eliomi,.ml4,.mli,.mll,.mly,.objdump,.mm,.sj,.omgrofl,.opa,.opal,.opencl,.p,.scad,.org,.ox,.oxh,.oxo,.oxygene,.oz,.pwn,.aw,.ctp,.php3,.php4,.php5,.php6,.php7,.php8,.phps,.phpt,.pls,.pck,.pkb,.pks,.plb,.plsql,.sql,.pov,.pan,.psc,.parrot,.pasm,.pir,.pas,.dfm,.dpr,.lpr,.pp,.pl,.al,.cgi,.perl,.ph,.plx,.pm,.pod,.psgi,.t,.6pl,.6pm,.nqp,.p6,.p6l,.p6m,.pl6,.pm6,.pkl,.pig,.pike,.pmod,.pogo,.pony,.ps,.eps,.ps1,.psd1,.psm1,.pde,.prolog,.yap,.spin,.proto,.pub,.pd,.pb,.pbi,.purs,.bzl,.gyp,.lmi,.pyde,.pyi,.pyp,.pyt,.pyw,.rpy,.tac,.wsgi,.xpy,.pytb,.qml,.qbs,.pri,.r,.rd,.rsx,.raml,.rdoc,.rbbas,.rbfrm,.rbmnu,.rbres,.rbtbar,.rbuistate,.rhtml,.rmd,.rkt,.rktd,.rktl,.scrbl,.rl,.raw,.reb,.r2,.r3,.rebol,.red,.reds,.cw,.rs,.rsh,.robot,.rg,.rb,.builder,.gemspec,.god,.irbrc,.jbuilder,.mspec,.pluginspec,.podspec,.rabl,.rake,.rbuild,.rbw,.rbx,.ru,.ruby,.thor,.watchr,.sas,.scss,.smt2,.smt,.sparql,.rq,.sqf,.hqf,.cql,.ddl,.prc,.tab,.udf,.viw,.db2,.ston,.sage,.sagews,.sls,.sass,.scala,.sbt,.sc,.scaml,.scm,.sld,.sps,.ss,.sci,.sce,.self,.sh,.bash,.bats,.command,.ksh,.tmux,.tool,.zsh,.sh-session,.shen,.sl,.slim,.smali,.tpl,.sp,.sma,.nut,.stan,.ML,.fun,.sig,.sml,.do,.ado,.doh,.ihlp,.mata,.matah,.sthlp,.styl,.scd,.swift,.sv,.svh,.vh,.toml,.txl,.tcl,.adp,.tm,.tcsh,.csh,.tex,.aux,.bbx,.bib,.cbx,.dtx,.ins,.lbx,.ltx,.mkii,.mkiv,.mkvi,.sty,.toc,.tea,.no,.textile,.thrift,.tu,.ttl,.twig,.upc,.anim,.asset,.mat,.meta,.prefab,.unity,.uno,.uc,.ur,.urs,.vcl,.vhdl,.vhd,.vhf,.vhi,.vho,.vhs,.vht,.vhw,.vala,.vapi,.veo,.vim,.vb,.bas,.frm,.frx,.vba,.vbhtml,.vbs,.volt,.vue,.owl,.webidl,.x10,.xc,.xml,.ant,.axml,.ccxml,.clixml,.cproject,.csl,.csproj,.ct,.dita,.ditamap,.ditaval,.config,.dotsettings,.filters,.fsproj,.fxml,.glade,.grxml,.iml,.ivy,.jelly,.jsproj,.kml,.launch,.mdpolicy,.mxml,.nproj,.nuspec,.odd,.osm,.plist,.props,.ps1xml,.psc1,.pt,.rdf,.rss,.scxml,.srdf,.storyboard,.stTheme,.sublime-snippet,.targets,.tmCommand,.tml,.tmLanguage,.tmPreferences,.tmSnippet,.tmTheme,.ui,.urdf,.ux,.vbproj,.vcxproj,.vssettings,.vxml,.wsdl,.wsf,.wxi,.wxl,.wxs,.x3d,.xacro,.xaml,.xib,.xlf,.xliff,.xmi,.dist,.xproj,.xsd,.xul,.zcml,.xsp-config,.metadata,.xpl,.xproc,.xquery,.xq,.xql,.xqm,.xqy,.xs,.xslt,.xsl,.xojo_code,.xojo_menu,.xojo_report,.xojo_script,.xojo_toolbar,.xojo_window,.xtend,.reek,.rviz,.sublime-syntax,.syntax,.yaml-tmlanguage,.yang,.y,.yacc,.yy,.zep,.zimpl,.zmpl,.zpl,.ec,.eh,.edn,.fish,.mu,.nc,.ooc,.rst,.rest,.wisp,.prg,.prw,.gitignore,.gitkeep,.gitmodules,.example,.avifs,.blp,.bufr,.bw,.cur,.dcx,.dds,.emf,.fit,.fits,.flc,.fli,.ftc,.ftu,.gbr,.grib,.h5,.hdf,.icb,.icns,.iim,.im,.j2c,.j2k,.jp2,.jpc,.jpe,.jpf,.jpx,.mpeg,.mpg,.msp,.pbm,.pcd,.pcx,.pfm,.pgm,.pnm,.ppm,.psd,.pxr,.qoi,.ras,.rgb,.rgba,.sgi,.tga,.vda,.vst,.wmf,.xpm

package/index.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const ToolManager = require('./lib/manager');
+const Tool = require('./lib/tool');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 工具管理器实例（Admin 工厂）
+ * 支持：require('mm_tools').admin.setServer(server) -> admin.get('name', config)
+ */
+const admin = new Admin();
+admin.setClass(ToolManager);
+
+/**
+ * 获取指定作用域的工具管理器
+ * @param {string} scope 作用域名称
+ * @param {object} config 管理器配置
+ * @returns {ToolManager} 工具管理器实例
+ */
+function toolsAdmin(scope, config) {
+  return admin.get(scope || 'os', config);
+}
+
+module.exports = {
+  Tool,
+  ToolManager,
+  Manager: ToolManager,
+  admin,
+  toolsAdmin
+};

package/lib/manager.js

@@ -0,0 +1,279 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Manager = require('mm_mod').Manager;
+const { loadJson } = require('mm_helper');
+const Tool = require('./tool');
+
+/**
+ * 工具管理器
+ * 手动登记与目录加载两种方式，均不依赖全局对象与原型扩展。
+ * @augments {Manager}
+ */
+class ToolManager extends Manager {
+  /**
+   * 配置参数
+   * @type {object}
+   */
+  static config = {
+    // 名称
+    name: 'tool',
+    // 标题
+    title: '工具管理',
+    // 描述
+    description: '这是工具管理器',
+    // 工具配置文件名
+    filename: 'tool.json',
+    // 工具根目录，缺省为模块根目录
+    dir: ''
+  };
+
+  /**
+   * 构造函数
+   * @param {object} config 配置参数
+   * @param {object} parent 父级模块
+   */
+  constructor(config, parent) {
+    super({ ...ToolManager.config, ...config }, parent);
+    // 受管驱动类
+    this.setClass(Tool);
+  }
+}
+
+/**
+ * 获取父级模块
+ * @returns {object|null} 父级模块
+ */
+ToolManager.prototype.getParent = function () {
+  return this.getServer() || null;
+};
+
+/**
+ * 获取工具根目录
+ * @returns {string} 根目录绝对路径
+ */
+ToolManager.prototype.getDir = function () {
+  if (this.config.dir) {
+    return path.resolve(this.config.dir);
+  }
+  return path.join(__dirname, '..');
+};
+
+/**
+ * 获取工具基础目录
+ * @returns {string} 基础目录绝对路径
+ */
+ToolManager.prototype.getBaseDir = function () {
+  if (this.config.base_dir) {
+    return path.resolve(this.config.base_dir);
+  }
+  return this.getDir();
+};
+
+/**
+ * 获取模板目录
+ * @returns {string} 模板目录绝对路径
+ */
+ToolManager.prototype.getTplDir = function () {
+  if (this.config.tpl_dir) {
+    return path.resolve(this.config.tpl_dir);
+  }
+  return path.join(__dirname, '..');
+};
+
+/**
+ * 创建受管工具实例（唯一实例化入口，父级指向本管理器）
+ * @param {object} config 工具配置（必须包含 name）
+ * @returns {Tool} 工具实例
+ * @private
+ */
+ToolManager.prototype._createDrive = function (config) {
+  return new this.Cs(config, this);
+};
+
+/**
+ * 创建并初始化一个工具
+ * @param {object} config 工具配置（必须包含 name）
+ * @param {object} server 服务器实例
+ * @param {object} eventer 事件对象
+ * @param {object} logger 日志对象
+ * @returns {Promise<Tool>} 工具实例
+ */
+ToolManager.prototype.create = async function (config, server, eventer, logger) {
+  const drive = this.add(config);
+  await drive._initCore(server, eventer, logger);
+  await this._initDrive(drive);
+  return drive;
+};
+
+/**
+ * 重新加载一个工具
+ * @param {string} name 工具名称
+ * @returns {Promise<boolean>} 是否执行成功
+ */
+ToolManager.prototype.reload = async function (name) {
+  const drive = this.get(name);
+  if (!drive) {
+    this.log('warn', '工具不存在，无法重新加载', name);
+    return false;
+  }
+  try {
+    const file = drive.config.config_file || path.join(drive.getDir(), this.config.filename);
+    await this.unregister(name);
+    this._loadConfigFile(file);
+    return true;
+  } catch (error) {
+    this.log('warn', '工具重新加载失败', name, error);
+    return false;
+  }
+};
+
+/**
+ * 加载目录下的全部工具
+ * @param {string} dir 工具根目录（可选，缺省使用配置目录）
+ * @returns {Promise<Array<Tool>>} 工具实例列表
+ */
+ToolManager.prototype.load = async function (dir) {
+  const target = path.resolve(dir || this.getDir());
+  this.config.dir = target;
+  const files = this._findFiles(target);
+  for (const file of files) {
+    try {
+      this._loadConfigFile(file);
+    } catch (error) {
+      this.log('error', '加载工具配置失败', file, error);
+    }
+  }
+  return this.list();
+};
+
+/**
+ * 清空全部工具（交由管理器统一释放并重置集合）
+ * @returns {Promise<ToolManager>} 当前实例
+ */
+ToolManager.prototype.clearMods = async function () {
+  await this.clear();
+  return this;
+};
+
+/**
+ * 获取工具实例
+ * @param {string} name 工具名称
+ * @returns {Tool|undefined} 工具实例
+ */
+ToolManager.prototype.getMod = function (name) {
+  return this.get(name);
+};
+
+/**
+ * 获取工具实例列表
+ * @returns {Array<Tool>} 工具实例数组
+ */
+ToolManager.prototype.getMods = function () {
+  return this.list();
+};
+
+/**
+ * 获取工具配置列表
+ * @param {string} keyword 名称关键词（可选）
+ * @returns {Array<object>} 工具配置数组
+ */
+ToolManager.prototype.getList = function (keyword) {
+  const infos = this.values().map((drive) => drive.config);
+  if (!keyword) {
+    return infos;
+  }
+  return infos.filter((info) => info.name && info.name.indexOf(keyword) !== -1);
+};
+
+/**
+ * 批量执行驱动的生命周期方法
+ * @param {string} method 方法名称，init 时转调 _initCore 注入依赖
+ * @param {...*} args 方法参数
+ * @returns {Promise<void>} 执行完成
+ */
+ToolManager.prototype.runAll = async function (method, ...args) {
+  const drives = this.list();
+  for (const drive of drives) {
+    try {
+      if (method === 'init') {
+        await drive._initCore(...args);
+        await this._initDrive(drive);
+      } else {
+        await drive[method](...args);
+      }
+    } catch (error) {
+      this.log('error', `${drive.config.name} 执行 ${method} 失败`, error);
+    }
+  }
+};
+
+/**
+ * 初始化驱动实例（仅首次初始化，运行状态由管理器记录）
+ * @param {Tool} drive 工具实例
+ * @returns {Promise<void>} 初始化完成
+ * @private
+ */
+ToolManager.prototype._initDrive = async function (drive) {
+  const name = drive.config.name;
+  if (await this.isState(name, 'inited')) {
+    return;
+  }
+  await drive.init();
+  await this.setState(name, 'inited');
+};
+
+/**
+ * 查找目录下的全部工具配置文件
+ * @param {string} dir 根目录
+ * @returns {Array<string>} 配置文件绝对路径数组
+ * @private
+ */
+ToolManager.prototype._findFiles = function (dir) {
+  const files = [];
+  this._walkDir(path.resolve(dir), files);
+  return files;
+};
+
+/**
+ * 递归遍历目录，收集匹配的配置文件
+ * @param {string} dir 当前目录
+ * @param {Array<string>} files 结果集合
+ * @private
+ */
+ToolManager.prototype._walkDir = function (dir, files) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      this._walkDir(full, files);
+    } else if (entry.isFile() && entry.name === this.config.filename) {
+      files.push(full);
+    }
+  }
+};
+
+/**
+ * 读取配置文件并注册工具实例
+ * @param {string} file 配置文件绝对路径
+ * @returns {Tool} 工具实例
+ * @throws {Error} 配置文件不存在或内容非法时
+ * @private
+ */
+ToolManager.prototype._loadConfigFile = function (file) {
+  const target = path.resolve(file);
+  if (!fs.existsSync(target)) {
+    throw new Error(`工具配置文件不存在: ${target}`);
+  }
+  const config = loadJson(target);
+  if (!config.name) {
+    config.name = path.basename(path.dirname(target));
+  }
+  return this.add({ ...config, config_file: target });
+};
+
+module.exports = ToolManager;

package/lib/tool.js

@@ -0,0 +1,555 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Base = require('mm_mod').Base;
+
+/**
+ * 工具
+ * 面向 OpenAI function calling 的函数单元，负责参数转换与脚本装载。
+ * @augments {Base}
+ */
+class Tool extends Base {
+  /**
+   * 工具配置对象
+   * @type {object}
+   */
+  static config = {
+    // 工具名称
+    name: '',
+    // 工具标题(显示的中文名)
+    title: '',
+    // 工具描述
+    description: '',
+    // 工具示例
+    example: '',
+    // 工具类型, 默认为'function'
+    type: 'function',
+    // 工具分类
+    category: '物联网',
+    // 工具分组
+    group: 'web',
+    // 工具主文件路径
+    main: './index.js',
+    // 工具是否严格模式参数校验。严格模式下，参数必须严格符合定义，否则会抛出错误
+    strict: true,
+    // 工具参数是否允许额外字段。默认为false，即不允许额外字段
+    add_params: false,
+    // 工具参数
+    params: [],
+    // 结果
+    returns: [],
+    // 请求参数
+    request: [],
+    // 工具响应，默认不变
+    response: [
+      {
+        name: 'result',
+        type: 'object',
+        description: '操作结果',
+        example: '{}',
+        default: null
+      },
+      {
+        name: 'error',
+        type: 'object',
+        description: '错误信息',
+        example: '{"code":10000,"message":"执行失败"}',
+        default: null,
+        props: [
+          {
+            name: 'code',
+            description: '错误码',
+            example: '10000',
+            type: 'number',
+            default: 10000
+          },
+          {
+            name: 'message',
+            description: '错误信息',
+            example: '执行失败',
+            type: 'string',
+            default: ''
+          }
+        ]
+      }
+    ],
+    // 工具目录，缺省时按配置文件目录或管理器目录 + 工具名称推导
+    dir: ''
+  };
+
+  /**
+   * 构造函数
+   * @param {object} config 工具配置对象
+   * @param {object} parent 父级管理器
+   */
+  constructor(config, parent) {
+    super({ ...Tool.config, ...config }, parent);
+    // 事件触发器
+    this._eventer = null;
+    // 脚本是否已装载
+    this._loaded = false;
+  }
+}
+
+/**
+ * 获取父级管理器
+ * @returns {object|null} 父级管理器
+ */
+Tool.prototype.getParent = function () {
+  return this.getServer() || null;
+};
+
+/**
+ * 获取工具目录
+ * 取值顺序：配置目录 -> 配置文件所在目录 -> 父级目录 + 工具名称 -> 模块根目录
+ * @returns {string} 工具目录绝对路径
+ */
+Tool.prototype.getDir = function () {
+  if (this.config.dir) {
+    return path.resolve(this.config.dir);
+  }
+  if (this.config.config_file) {
+    return path.dirname(path.resolve(this.config.config_file));
+  }
+  const parent = this.getParent();
+  if (parent && typeof parent.getDir === 'function') {
+    return path.join(parent.getDir(), this.config.name);
+  }
+  return path.join(__dirname, '..');
+};
+
+/**
+ * 设置事件触发器
+ * @param {object} eventer 事件触发器
+ * @returns {Tool} 当前实例
+ */
+Tool.prototype.setEventer = function (eventer) {
+  this._eventer = eventer || null;
+  return this;
+};
+
+/**
+ * 获取事件触发器
+ * @returns {object|null} 事件触发器
+ */
+Tool.prototype.getEventer = function () {
+  if (this._eventer) {
+    return this._eventer;
+  }
+  const parent = this.getParent();
+  if (parent && typeof parent.getEventer === 'function') {
+    return parent.getEventer();
+  }
+  return null;
+};
+
+/**
+ * 触发事件
+ * @param {string} event 事件名称
+ * @param {...*} args 事件参数
+ * @returns {boolean} 是否触发成功
+ */
+Tool.prototype.emitEvent = function (event, ...args) {
+  const eventer = this.getEventer();
+  if (!eventer || typeof eventer.emit !== 'function') {
+    return false;
+  }
+  eventer.emit(event, ...args);
+  return true;
+};
+
+/**
+ * 初始化工具核心
+ * @param {object} server 服务器实例
+ * @param {object} eventer 事件触发器
+ * @param {object} logger 日志记录器
+ * @returns {Promise<Tool>} 当前实例
+ */
+Tool.prototype._initCore = async function (server, eventer, logger) {
+  if (server) {
+    this.setServer(server);
+  }
+  if (eventer) {
+    this.setEventer(eventer);
+  }
+  if (logger) {
+    this.setLogger(logger);
+  }
+  return this;
+};
+
+/**
+ * 装载工具脚本
+ * 将脚本导出的函数绑定到当前实例，供 main 内部以 this.xxx 方式复用。
+ * @returns {Tool} 当前实例
+ * @throws {Error} 脚本文件不存在时
+ */
+Tool.prototype.loadScript = function () {
+  const file = this.getScriptFile();
+  if (!file || !fs.existsSync(file)) {
+    throw new Error(`工具脚本文件不存在: ${file}`);
+  }
+  const resolved = require.resolve(file);
+  delete require.cache[resolved];
+  this._applyScript(require(resolved));
+  this._loaded = true;
+  return this;
+};
+
+/**
+ * 将脚本导出项绑定到实例
+ * @param {object} script 脚本导出对象
+ * @private
+ */
+Tool.prototype._applyScript = function (script) {
+  if (!script || typeof script !== 'object') {
+    return;
+  }
+  for (const key of Object.keys(script)) {
+    const value = script[key];
+    this[key] = typeof value === 'function' ? value.bind(this) : value;
+  }
+};
+
+/**
+ * 脚本是否已装载
+ * @returns {boolean} 是否已装载
+ */
+Tool.prototype.isLoaded = function () {
+  return this._loaded;
+};
+
+/**
+ * 转为参数 - 用于兼容openAI的工具
+ * @param {object} params 参数配置对象
+ * @returns {object} 参数对象
+ * @private
+ */
+Tool.prototype._toParam = function (params) {
+  const config = params || {};
+  const type = config.type || 'object';
+  let properties;
+  let required = [];
+  let additionalProperties;
+  if (type === 'object') {
+    properties = {};
+    if (Array.isArray(config)) {
+      for (const item of config) {
+        this._getProps(properties, required, item);
+      }
+      if (this.config.add_params !== undefined) {
+        additionalProperties = this.config.add_params;
+      }
+    } else {
+      additionalProperties = this._toParamByObj(properties, required, config);
+    }
+  }
+  const parameters = { type };
+  if (Object.keys(properties).length > 0) {
+    parameters.properties = properties;
+    if (required.length > 0) {
+      parameters.required = required;
+    }
+    if (additionalProperties !== undefined) {
+      parameters.additionalProperties = additionalProperties;
+    }
+  }
+  return parameters;
+};
+
+/**
+ * 按对象结构转为参数
+ * @param {object} properties 参数属性集合
+ * @param {Array<string>} required 必填参数集合
+ * @param {object} params 参数配置对象
+ * @returns {boolean|undefined} 是否允许额外字段
+ * @private
+ */
+Tool.prototype._toParamByObj = function (properties, required, params) {
+  let additionalProperties;
+  if (params.type) {
+    if (params.required) {
+      for (const name of params.required) {
+        if (required.indexOf(name) === -1) {
+          required.push(name);
+        }
+      }
+    }
+    const props = params.props || params.properties;
+    if (props) {
+      if (Array.isArray(props)) {
+        this._getPropsByArr(properties, required, props);
+      } else {
+        this._getPropsByObj(properties, required, props);
+      }
+    }
+    if (params.additionalProperties !== undefined) {
+      additionalProperties = params.additionalProperties;
+    }
+  } else {
+    this._getProps(properties, required, params);
+    if (this.config.add_params !== undefined) {
+      additionalProperties = this.config.add_params;
+    }
+  }
+  return additionalProperties;
+};
+
+/**
+ * 按数组结构转换参数
+ * @param {object} properties 参数属性集合
+ * @param {Array<string>} required 必填参数集合
+ * @param {Array<object>} params 参数配置数组
+ * @private
+ */
+Tool.prototype._getPropsByArr = function (properties, required, params) {
+  for (const param of params) {
+    this._getProps(properties, required, param);
+  }
+};
+
+/**
+ * 按对象结构转换参数
+ * @param {object} properties 参数属性集合
+ * @param {Array<string>} required 必填参数集合
+ * @param {object} params 参数配置对象
+ * @private
+ */
+Tool.prototype._getPropsByObj = function (properties, required, params) {
+  for (const key in params) {
+    this._getProps(properties, required, params[key], key);
+  }
+};
+
+/**
+ * 获取参数属性
+ * @param {object} properties 参数属性集合
+ * @param {Array<string>} required 必填参数集合
+ * @param {object} param 参数配置对象
+ * @param {string} key 参数名称
+ * @private
+ */
+Tool.prototype._getProps = function (properties, required, param, key) {
+  const key_name = key || param.name;
+  const pm = { ...param };
+  delete pm.name;
+  if (param.required) {
+    required.push(key_name);
+  }
+  delete pm.required;
+  let description = '';
+  if (param.title) {
+    description += param.title + ': ';
+  }
+  delete pm.title;
+  if (!description) {
+    description += param.description;
+  }
+  if (param.default !== undefined) {
+    description += ' 默认值为' + param.default;
+  }
+  if (param.example) {
+    description += ' 示例：' + param.example;
+  }
+  delete pm.example;
+  if (param.items) {
+    pm.items = this._toItems(param.items);
+  }
+  const props = param.properties || param.props;
+  if (props) {
+    const _properties = {};
+    const _required = [];
+    if (Array.isArray(props)) {
+      this._getPropsByArr(_properties, _required, props);
+    } else {
+      this._getPropsByObj(_properties, _required, props);
+    }
+    if (Object.keys(_properties).length > 0) {
+      pm.properties = _properties;
+    }
+    if (_required.length > 0) {
+      pm.required = _required;
+    }
+  }
+  properties[key_name] = {
+    ...pm,
+    description
+  };
+};
+
+/**
+ * 转换数组项参数
+ * @param {object|Array<object>} items 数组项配置
+ * @returns {object} 参数对象
+ * @private
+ */
+Tool.prototype._toItems = function (items) {
+  const type = items.type || 'object';
+  const properties = {};
+  const required = [];
+  if (Array.isArray(items)) {
+    for (const item of items) {
+      this._getProps(properties, required, item);
+    }
+  } else if (type === 'object') {
+    const props = items.properties || items.props || {};
+    for (const key in props) {
+      this._getProps(properties, required, props[key], key);
+    }
+  }
+  const parameters = { type };
+  if (Object.keys(properties).length > 0) {
+    parameters.properties = properties;
+    if (required.length > 0) {
+      parameters.required = required;
+    }
+  }
+  return parameters;
+};
+
+/**
+ * 转为openAI的调用函数
+ * @returns {object} 调用函数对象
+ */
+Tool.prototype.toFunctionCall = function () {
+  const cg = this.config;
+  const { name, title, type = 'function', description, example = '' } = cg;
+  let desc = title || '';
+  if (description) {
+    desc += ': ' + description;
+  }
+  const info = { type };
+  if (type === 'function') {
+    if (example) {
+      desc += ' 示例：' + example;
+    }
+    const parameters = this._toParam(cg.parameters || cg.params || {});
+    info.function = {
+      name,
+      description: desc
+    };
+    if (parameters && Object.keys(parameters).length > 0) {
+      info.function.parameters = parameters;
+    }
+  }
+  return info;
+};
+
+/**
+ * 获取工具配置文件
+ * @returns {string} 配置文件绝对路径，未配置时为空字符串
+ */
+Tool.prototype.getConfigFile = function () {
+  const file = this.config.config_file;
+  return file ? path.resolve(this.getDir(), file) : '';
+};
+
+/**
+ * 获取工具脚本文件
+ * @returns {string} 脚本文件绝对路径，未配置时为空字符串
+ */
+Tool.prototype.getScriptFile = function () {
+  const file = this.config.script_file || this.config.main;
+  return file ? path.resolve(this.getDir(), file) : '';
+};
+
+/**
+ * 获取工具明细
+ * @returns {object} 工具明细对象
+ */
+Tool.prototype.getDetail = function () {
+  return {
+    ...this.config,
+    dir: this.getDir(),
+    config_file: this.getConfigFile(),
+    script_file: this.getScriptFile()
+  };
+};
+
+/**
+ * 调用工具
+ * @param {object} params 参数
+ * @returns {object} 执行结果
+ */
+Tool.prototype.main = function (params) {
+  return params;
+};
+
+/**
+ * 获取智能体
+ * @param {string} agent_name 智能体名称(英文名，唯一标识)
+ * @returns {object} 智能体对象
+ */
+Tool.prototype.getAgent = function (agent_name) {
+  if (typeof agent_name !== 'string' || !agent_name.trim()) {
+    throw new TypeError('智能体名称必须是有效的字符串');
+  }
+  return this.getServer().getAgent(agent_name);
+};
+
+/**
+ * 获取项目
+ * @param {string} project_name 项目名称(英文名，唯一标识)
+ * @returns {object} 项目对象
+ */
+Tool.prototype.getProject = function (project_name) {
+  if (typeof project_name !== 'string' || !project_name.trim()) {
+    throw new TypeError('项目名称必须是有效的字符串');
+  }
+  return this.getServer().getProject(project_name);
+};
+
+/**
+ * 获取任务
+ * @param {string} project_name 项目名称(英文名，唯一标识)
+ * @param {string} task_name 任务名称(英文名，唯一标识)
+ * @returns {object} 任务对象
+ */
+Tool.prototype.getTask = function (project_name, task_name) {
+  if (typeof project_name !== 'string' || !project_name.trim()) {
+    throw new TypeError('项目名称必须是有效的字符串');
+  }
+  if (typeof task_name !== 'string' || !task_name.trim()) {
+    throw new TypeError('任务名称必须是有效的字符串');
+  }
+  return this.getServer().getTask(project_name, task_name);
+};
+
+/**
+ * 获取技能
+ * @param {string} skill_name 技能名称(英文名，唯一标识)
+ * @returns {object} 技能对象
+ */
+Tool.prototype.getSkill = function (skill_name) {
+  if (typeof skill_name !== 'string' || !skill_name.trim()) {
+    throw new TypeError('技能名称必须是有效的字符串');
+  }
+  return this.getServer().getSkill(skill_name);
+};
+
+/**
+ * 获取工具
+ * @param {string} tool_name 工具名称(英文名，唯一标识)
+ * @returns {object} 工具对象
+ */
+Tool.prototype.getTool = function (tool_name) {
+  if (typeof tool_name !== 'string' || !tool_name.trim()) {
+    throw new TypeError('工具名称必须是有效的字符串');
+  }
+  return this.getServer().getTool(tool_name);
+};
+
+/**
+ * 获取LLM模型
+ * @param {string} llm_name LLM模型名称
+ * @returns {object} LLM模型对象
+ */
+Tool.prototype.getLLM = function (llm_name) {
+  if (typeof llm_name !== 'string' || !llm_name.trim()) {
+    throw new TypeError('LLM模型名称必须是有效的字符串');
+  }
+  return this.getServer().getLLM(llm_name);
+};
+
+module.exports = Tool;

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "mm_toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "工具模块，面向 OpenAI function calling 的函数单元，负责参数转换与脚本装载，基于 mm_mod 生命周期，无全局对象与原型扩展依赖",
+  "main": "index.js",
+  "keywords": [
+    "mm_mod",
+    "mm_domain",
+    "mm_agent",
+    "tool",
+    "工具"
+  ],
+  "layer": "domain",
+  "group": "agent",
+  "author": "邱文武",
+  "license": "ISC",
+  "dependencies": {
+    "mm_corejs": "^1.1.4",
+    "mm_helper": "^1.0.0",
+    "mm_mod": "^1.0.1"
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/script.tpl.js

@@ -0,0 +1,44 @@
+module.exports = {
+  /**
+   * 主要逻辑
+   * @param {object} params 参数
+   * @param {string} params.client_id 客户端ID
+   * @param {string} params.id 指令ID
+   * @param {string} params.method 方法类型
+   * @param {object} params.data 数据参数
+   */
+  async xxx(params) {
+    // 主要代码写在这
+    if (!params.client_id) {
+      throw new Error('客户端ID不能为空');
+    }
+    if (!params.id) {
+      throw new Error('指令ID不能为空');
+    }
+    if (!params.method) {
+      throw new Error('方法类型不能为空');
+    }
+  },
+  /**
+   * 主要逻辑
+   * @param {object} params 参数
+   * @returns {object} 执行结果对象
+   */
+  async main(params) {
+    let ret;
+    try {
+      let data = await this.xxx(params);
+      ret = {
+        code: 0,
+        msg: '执行成功',
+        data
+      };
+    } catch (error) {
+      ret = {
+        code: 10000,
+        msg: '执行失败！原因：' + error.message
+      };
+    }
+    return ret;
+  },
+};

package/test.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const mod = require('./index.js');
+
+/**
+ * 测试导出结构
+ */
+function testExports() {
+  assert.ok(mod.Tool, '应导出 Tool');
+  assert.ok(mod.Manager, '应导出 Manager');
+  assert.ok(mod.admin, '应导出 admin');
+  assert.strictEqual(typeof mod.toolsAdmin, 'function', '应导出 toolsAdmin 函数');
+  const instance = mod.toolsAdmin('test');
+  assert.ok(instance instanceof mod.Manager, 'toolsAdmin 返回的实例应为 Manager 类型');
+}
+
+/**
+ * 测试参数转换
+ * @param {string} dir 临时目录
+ */
+async function testFunctionCall(dir) {
+  const manager = new mod.Manager({ name: 'function', dir });
+  const tool = await manager.create(
+    {
+      name: 'sum',
+      title: '求和',
+      description: '计算两个数字之和',
+      dir: path.join(dir, 'sum'),
+      params: [
+        { name: 'a', description: '第一个数字', type: 'number', required: true },
+        { name: 'b', description: '第二个数字', type: 'number', required: true }
+      ]
+    },
+    { name: 'server' }
+  );
+  assert.ok(tool instanceof mod.Tool, 'create 返回的实例应为 Tool 类型');
+  assert.ok(await manager.isState('sum', 'inited'), '工具创建后应处于 inited 状态');
+
+  const info = tool.toFunctionCall();
+  assert.strictEqual(info.type, 'function', '类型应为 function');
+  assert.strictEqual(info.function.name, 'sum', '函数名应一致');
+  assert.ok(info.function.description.indexOf('计算两个数字之和') !== -1, '描述应包含工具描述');
+  assert.deepStrictEqual(info.function.parameters.required, ['a', 'b'], '必填参数应一致');
+  assert.strictEqual(info.function.parameters.properties.a.type, 'number', '参数类型应一致');
+  assert.ok(info.function.parameters.properties.a.description.indexOf('默认值') === -1, '无默认值时不追加默认值说明');
+}
+
+/**
+ * 测试脚本装载与执行
+ * @param {string} dir 临时目录
+ */
+async function testScript(dir) {
+  const target = path.join(dir, 'load');
+  const item = path.join(target, 'file', 'add');
+  fs.mkdirSync(item, { recursive: true });
+  const config = {
+    name: 'add',
+    title: '加法',
+    description: '两个数相加',
+    group: 'math',
+    main: './index.js',
+    params: [{ name: 'a', type: 'number', required: true }, { name: 'b', type: 'number', required: true }]
+  };
+  fs.writeFileSync(path.join(item, 'tool.json'), JSON.stringify(config), 'utf8');
+  fs.writeFileSync(
+    path.join(item, 'index.js'),
+    [
+      'module.exports = {',
+      '  async calc(params) {',
+      '    return params.a + params.b;',
+      '  },',
+      '  async main(params) {',
+      '    const data = await this.calc(params);',
+      '    return { code: 0, msg: "执行成功", data };',
+      '  }',
+      '};',
+      ''
+    ].join('\n'),
+    'utf8'
+  );
+
+  const manager = new mod.Manager({ name: 'load' });
+  const list = await manager.load(target);
+  assert.strictEqual(list.length, 1, '应加载 1 个工具');
+
+  const tool = list[0];
+  assert.strictEqual(tool.getDir(), item, '工具目录应为配置文件所在目录');
+  assert.strictEqual(tool.getScriptFile(), path.join(item, 'index.js'), '脚本文件应指向 main');
+
+  await tool._initCore({ name: 'server' });
+  assert.strictEqual(tool.isLoaded(), false, '装载前应为未装载状态');
+  tool.loadScript();
+  assert.strictEqual(tool.isLoaded(), true, '装载后应为已装载状态');
+
+  const ret = await tool.main({ a: 1, b: 2 });
+  assert.strictEqual(ret.code, 0, '执行应成功');
+  assert.strictEqual(ret.data, 3, '脚本内部应能通过 this 调用子函数');
+
+  const detail = tool.getDetail();
+  assert.strictEqual(detail.config_file, path.join(item, 'tool.json'), '详情应包含配置文件');
+  assert.strictEqual(detail.script_file, path.join(item, 'index.js'), '详情应包含脚本文件');
+}
+
+/**
+ * 主测试入口
+ */
+async function main() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mm_tools_'));
+  try {
+    testExports();
+    await testFunctionCall(dir);
+    await testScript(dir);
+    console.log('mm_tools 模块测试通过');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});