@zhin.js/core 1.0.53 → 1.0.55

package/lib/plugin.js

@@ -7,15 +7,14 @@ import { EventEmitter } from "events";
 import { createRequire } from "module";
 import * as fs from "fs";
 import * as path from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath } from "url";
 import logger from "@zhin.js/logger";
 import { compose, remove, resolveEntry } from "./utils.js";
 import { Adapter } from "./adapter.js";
-import { Feature } from "./feature.js";
 import { createHash } from "crypto";
+import { Feature } from "./feature.js";
 const contextsKey = Symbol("contexts");
-const extensionOwnersKey = Symbol("extensionOwners");
-const loadedModules = new Map();
+const loadedModules = new Map(); // 记录已加载的模块
 const require = createRequire(import.meta.url);
 // ============================================================================
 // AsyncLocalStorage 上下文
@@ -46,17 +45,16 @@ function getCurrentFile(metaUrl = import.meta.url) {
 /**
  * usePlugin - 获取或创建当前插件实例
  * 类似 React Hooks 的设计，根据调用文件自动创建插件树
- *
- * 同一个文件多次调用 usePlugin() 返回同一个实例，
- * 避免 Plugin.create() + usePlugin() 产生不必要的双层包装。
+ * 同一上下文中同一文件多次调用返回同一实例
  */
 export function usePlugin() {
     const callerFile = getCurrentFile();
-    const parentPlugin = storage.getStore();
-    // 同一文件再次调用 usePlugin()，直接复用已有实例
-    if (parentPlugin && parentPlugin.filePath === callerFile) {
-        return parentPlugin;
+    // 如果当前 store 已是同一文件创建的插件，直接返回
+    const current = storage.getStore();
+    if (current && current.filePath.replace(/\?t=\d+$/, '') === callerFile.replace(/\?t=\d+$/, '')) {
+        return current;
     }
+    const parentPlugin = current;
     const newPlugin = new Plugin(callerFile, parentPlugin);
     storage.enterWith(newPlugin);
     return newPlugin;
@@ -109,10 +107,8 @@ function watchFile(filePath, callback) {
 export class Plugin extends EventEmitter {
     parent;
     static [contextsKey] = [];
-    /** Maps extension method name → context name that owns it */
-    static [extensionOwnersKey] = new Map();
     #cachedName;
-    #explicitName;
+    #manifest;
     adapters = [];
     started = false;
     // 上下文存储
@@ -139,21 +135,20 @@ export class Plugin extends EventEmitter {
     };
     // 插件功能
     #middlewares = [this.#messageMiddleware];
-    // 本地工具存储（当 ToolService 不可用时使用）
+    // AI 工具
     #tools = new Map();
+    // Feature 贡献追踪
+    #featureContributions = new Map();
     // 统一的清理函数集合
     #disposables = new Set();
-    // 记录当前插件向哪些 Feature 贡献了哪些 item
-    #featureContributions = new Map();
     get middleware() {
         return compose(this.#middlewares);
     }
-    /**
-     * Returns custom middlewares (excluding the built-in command middleware).
-     * Used by MessageDispatcher to run legacy middlewares after dispatch.
-     */
-    _getCustomMiddlewares() {
-        return this.#middlewares.filter(m => m !== this.#messageMiddleware);
+    recordFeatureContribution(featureName, itemName) {
+        if (!this.#featureContributions.has(featureName)) {
+            this.#featureContributions.set(featureName, new Set());
+        }
+        this.#featureContributions.get(featureName).add(itemName);
     }
     /**
      * 构造函数
@@ -178,19 +173,8 @@ export class Plugin extends EventEmitter {
     /**
      * 添加中间件
      * 中间件用于处理消息流转
-     * @param middleware 中间件函数
      */
-    addMiddleware(middleware) {
-        // Always register on root so middlewares reach the global chain
-        const target = this.root;
-        if (target !== this) {
-            const dispose = target.addMiddleware(middleware);
-            this.#disposables.add(dispose);
-            return () => {
-                dispose();
-                this.#disposables.delete(dispose);
-            };
-        }
+    addMiddleware(middleware, name) {
         this.#middlewares.push(middleware);
         const dispose = () => {
             remove(this.#middlewares, middleware);
@@ -200,23 +184,13 @@ export class Plugin extends EventEmitter {
         return dispose;
     }
     /**
-     * 添加工具
-     * 工具可以被 AI 服务调用，也会自动生成对应的命令
+     * 添加 AI 工具
+     * 工具可以被 AI 服务调用来执行操作
      * @param tool 工具定义
-     * @param generateCommand 是否生成对应命令（默认 true）
      * @returns 返回一个移除工具的函数
      */
-    addTool(tool, generateCommand = true) {
-        const toolService = this.root.inject('tool');
-        if (toolService && typeof toolService.addTool === 'function') {
-            const dispose = toolService.addTool(tool, this.name, generateCommand);
-            this.#disposables.add(dispose);
-            return () => {
-                dispose();
-                this.#disposables.delete(dispose);
-            };
-        }
-        // 回退到本地存储
+    addTool(tool) {
+        // 自动添加插件源标识
         const toolWithSource = {
             ...tool,
             source: tool.source || `plugin:${this.name}`,
@@ -263,15 +237,10 @@ export class Plugin extends EventEmitter {
         return undefined;
     }
     /**
-     * 收集所有可用的工具
-     * 优先使用 ToolService，否则回退到本地收集
+     * 收集所有可用的工具（包括适配器提供的）
+     * 这是 AI 服务获取工具的主入口
      */
     collectAllTools() {
-        const toolService = this.root.inject('tool');
-        if (toolService && typeof toolService.collectAll === 'function') {
-            return toolService.collectAll(this.root);
-        }
-        // 回退到本地收集
         const tools = [];
         // 收集插件树中的所有工具
         const rootPlugin = this.root;
@@ -287,45 +256,71 @@ export class Plugin extends EventEmitter {
         return tools;
     }
     /**
-     * 显式设置插件名称（优先级高于路径推导）。
-     * 可通过以下方式声明：
-     *   1. 模块导出 `export const pluginName = 'my-plugin'`
-     *   2. 调用 `plugin.setName('my-plugin')`
-     */
-    setName(name) {
-        this.#explicitName = name;
-        this.#cachedName = name;
-        this.logger = logger.getLogger(name);
-    }
-    /**
-     * 插件名称（显式名称 > 路径推导）
+     * 插件名称
      */
     get name() {
-        if (this.#explicitName)
-            return this.#explicitName;
         if (this.#cachedName)
             return this.#cachedName;
-        let name = path
+        this.#cachedName = path
             .relative(process.cwd(), this.filePath)
             .replace(/\?t=\d+$/, "")
             .replace(/\\/g, "/")
             .replace(/\/index\.(js|ts)x?$/, "")
-            .replace(/\/(lib|src|dist)$/, "");
-        // 安全地提取 node_modules 后的包名或最后的文件名
-        const nodeModulesIndex = name.indexOf('node_modules/');
-        if (nodeModulesIndex !== -1) {
-            name = name.substring(nodeModulesIndex + 'node_modules/'.length);
-        }
-        // 提取最后一个路径段
-        const lastSlash = name.lastIndexOf('/');
-        if (lastSlash !== -1) {
-            name = name.substring(lastSlash + 1);
-        }
-        // 移除文件扩展名
-        name = name.replace(/\.(js|ts)x?$/, "");
-        this.#cachedName = name;
+            .replace(/\/(lib|src|dist)$/, "")
+            .replace(/.*\/node_modules\//, "")
+            .replace(/.*\//, "")
+            .replace(/\.(js|ts)x?$/, "");
         return this.#cachedName;
     }
+    /**
+     * 插件清单（从 plugin.yml 或 package.json 延迟读取）
+     */
+    get manifest() {
+        if (this.#manifest !== undefined)
+            return this.#manifest ?? undefined;
+        if (!this.filePath) {
+            this.#manifest = null;
+            return undefined;
+        }
+        const dir = path.dirname(this.filePath);
+        // 优先读取 plugin.yml
+        const ymlPath = path.join(dir, 'plugin.yml');
+        if (fs.existsSync(ymlPath)) {
+            try {
+                const content = fs.readFileSync(ymlPath, 'utf-8');
+                const match = content.match(/^name:\s*(.+)$/m);
+                const descMatch = content.match(/^description:\s*(.+)$/m);
+                const verMatch = content.match(/^version:\s*(.+)$/m);
+                if (match) {
+                    this.#manifest = {
+                        name: match[1].trim(),
+                        description: descMatch?.[1]?.trim(),
+                        version: verMatch?.[1]?.trim(),
+                    };
+                    return this.#manifest;
+                }
+            }
+            catch { /* ignore */ }
+        }
+        // Fallback: package.json
+        const pkgPath = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name) {
+                    this.#manifest = {
+                        name: pkg.name,
+                        description: pkg.description,
+                        version: pkg.version,
+                    };
+                    return this.#manifest;
+                }
+            }
+            catch { /* ignore */ }
+        }
+        this.#manifest = null;
+        return undefined;
+    }
     /**
      * 根插件
      */
@@ -365,6 +360,7 @@ export class Plugin extends EventEmitter {
                 sideEffect.finished = false;
             };
             this.on('context.dispose', disposeFn);
+            // 确保 dispose 时清理监听器（只注册一次）
             const cleanupOnDispose = () => {
                 this.off('context.dispose', disposeFn);
                 dispose(this.inject(args[0]));
@@ -414,9 +410,18 @@ export class Plugin extends EventEmitter {
         for (const context of this.$contexts.values()) {
             if (typeof context.mounted === "function") {
                 const result = await context.mounted(this);
-                // 仅当 value 未预设时才赋值（mounted 始终执行，以支持副作用如设置内部引用）
-                if (!context.value)
+                // 仅在没有预设 value 时才用 mounted 返回值赋值
+                if (!context.value) {
                     context.value = result;
+                }
+            }
+            // 注册扩展方法到 Plugin.prototype
+            if (context.extensions) {
+                for (const [name, fn] of Object.entries(context.extensions)) {
+                    if (typeof fn === 'function') {
+                        Reflect.set(Plugin.prototype, name, fn);
+                    }
+                }
             }
             this.dispatch('context.mounted', context.name);
         }
@@ -425,149 +430,55 @@ export class Plugin extends EventEmitter {
         for (const child of this.children) {
             await child.start(t);
         }
-        this.logger.debug(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
-    }
-    /**
-     * 记录 Feature 贡献（由 Feature extensions 内部调用）
-     * @param featureName Feature 名称（如 'command'）
-     * @param itemName item 标识（如命令 pattern）
-     */
-    recordFeatureContribution(featureName, itemName) {
-        if (!this.#featureContributions.has(featureName)) {
-            this.#featureContributions.set(featureName, new Set());
-        }
-        this.#featureContributions.get(featureName).add(itemName);
-    }
-    /**
-     * 收集本插件及所有后代插件的 Feature 贡献名称
-     * 解决 Plugin.create() 包装问题：外层插件的 #featureContributions 为空，
-     * 实际贡献记录在 usePlugin() 创建的内层子插件上
-     */
-    #collectAllFeatureNames(names) {
-        for (const name of this.#featureContributions.keys()) {
-            names.add(name);
+        // 输出启动日志（使用 debug 级别，避免重复输出）
+        // 只在根插件或重要插件时使用 info 级别
+        if (!this.parent || this.name === 'setup') {
+            this.logger.info(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
         }
-        for (const child of this.children) {
-            child.#collectAllFeatureNames(names);
+        else {
+            this.logger.debug(`Plugin "${this.name}" ${t ? `reloaded in ${Date.now() - t}ms` : "started"}`);
         }
     }
     /**
-     * 收集本插件及所有后代插件的 plugin name 集合
-     * 用于 Feature.toJSON(pluginName) 匹配
+     * 获取插件提供的功能
+     * 从各个服务中获取数据
      */
-    #collectAllPluginNames(names) {
-        names.add(this.name);
-        for (const child of this.children) {
-            child.#collectAllPluginNames(names);
-        }
+    get features() {
+        const commandService = this.inject('command');
+        const componentService = this.inject('component');
+        const cronService = this.inject('cron');
+        return {
+            commands: commandService ? commandService.items.map(c => c.pattern) : [],
+            components: componentService ? componentService.getAllNames() : [],
+            crons: cronService ? cronService.items.map(c => c.cronExpression) : [],
+            middlewares: this.#middlewares.map((m, i) => m.name || `middleware_${i}`),
+        };
     }
     /**
-     * 获取当前插件的所有 Feature 数据（用于 HTTP API）
-     * 遍历插件贡献的 Feature，调用各 Feature 的 toJSON(pluginName) 获取序列化数据
-     * 同时包含 middleware（方案 B: 本地构造）
-     *
-     * 注意：Plugin.create() 创建 "外层" 插件，usePlugin() 创建 "内层" 子插件。
-     * extension 方法 (addCommand 等) 通过 getPlugin() 记录在内层插件上。
-     * 因此需要遍历整个子树来收集 feature 贡献名称。
+     * 获取插件功能摘要（数组形式）
+     * 返回各功能类型的名称和数量
      */
     getFeatures() {
         const result = [];
-        // 收集本插件及所有后代插件的 feature 名称和 plugin 名称
-        const featureNames = new Set();
-        this.#collectAllFeatureNames(featureNames);
-        const pluginNames = new Set();
-        this.#collectAllPluginNames(pluginNames);
-        // 从 Feature 贡献中收集
-        for (const featureName of featureNames) {
-            const feature = this.inject(featureName);
-            if (feature instanceof Feature) {
-                // 先用当前插件名尝试
-                let json = feature.toJSON(this.name);
-                if (json.count === 0) {
-                    // 当前插件名匹配不到（可能名称不同），尝试后代插件名
-                    for (const pName of pluginNames) {
-                        if (pName === this.name)
-                            continue;
-                        json = feature.toJSON(pName);
-                        if (json.count > 0)
-                            break;
-                    }
-                }
-                if (json.count > 0) {
-                    result.push(json);
-                }
-            }
-        }
-        // middleware（方案 B: 本地构造，因为 middleware 是 Plugin 私有属性）
-        // 同样需要收集子插件树中的 middleware
-        const allMiddlewareNames = [];
-        const collectMiddlewares = (plugin) => {
-            const mws = plugin.#middlewares
-                .filter(m => m !== plugin.#messageMiddleware)
-                .map((m, i) => m.name || `middleware_${i}`);
-            allMiddlewareNames.push(...mws);
-            for (const child of plugin.children) {
-                collectMiddlewares(child);
-            }
-        };
-        collectMiddlewares(this);
-        if (allMiddlewareNames.length > 0) {
-            result.push({
-                name: 'middleware',
-                icon: 'Layers',
-                desc: '中间件',
-                count: allMiddlewareNames.length,
-                items: allMiddlewareNames.map(name => ({ name })),
-            });
-        }
-        // 自动检测适配器和服务上下文（从 $contexts 中发现非 Feature 的贡献）
-        const adapterItems = [];
-        const serviceItems = [];
-        const scanContexts = (plugin) => {
-            for (const [name, context] of plugin.$contexts) {
-                const value = context.value;
-                if (value instanceof Adapter) {
-                    adapterItems.push({
-                        name,
-                        bots: value.bots.size,
-                        online: Array.from(value.bots.values()).filter(b => b.$connected).length,
-                        tools: value.tools.size,
-                    });
-                }
-                else if (value !== undefined && !(value instanceof Feature)) {
-                    // 非 Feature、非 Adapter 的上下文 = 服务
-                    serviceItems.push({ name, desc: context.description || name });
-                }
-            }
-            for (const child of plugin.children) {
-                scanContexts(child);
-            }
-        };
-        scanContexts(this);
-        if (adapterItems.length > 0) {
-            result.push({
-                name: 'adapter',
-                icon: 'Plug',
-                desc: '适配器',
-                count: adapterItems.length,
-                items: adapterItems,
-            });
-        }
-        if (serviceItems.length > 0) {
-            result.push({
-                name: 'service',
-                icon: 'Server',
-                desc: '服务',
-                count: serviceItems.length,
-                items: serviceItems,
-            });
-        }
+        const f = this.features;
+        if (f.commands.length > 0)
+            result.push({ name: 'command', count: f.commands.length });
+        if (f.components.length > 0)
+            result.push({ name: 'component', count: f.components.length });
+        if (f.crons.length > 0)
+            result.push({ name: 'cron', count: f.crons.length });
+        // #middlewares includes the default command middleware, only count user-added ones
+        const userMiddlewareCount = this.#middlewares.length - 1; // subtract default #messageMiddleware
+        if (userMiddlewareCount > 0)
+            result.push({ name: 'middleware', count: userMiddlewareCount });
+        if (this.#tools.size > 0)
+            result.push({ name: 'tool', count: this.#tools.size });
         return result;
     }
     info() {
         return {
             [this.name]: {
-                features: this.getFeatures(),
+                features: this.features,
                 children: this.children.map(child => child.info())
             }
         };
@@ -585,15 +496,13 @@ export class Plugin extends EventEmitter {
             await child.stop();
         }
         this.children = [];
-        // 停止服务 — only remove extensions owned by this plugin's contexts
+        // 停止服务
         for (const [name, context] of this.$contexts) {
             remove(Plugin[contextsKey], name);
+            // 移除扩展方法
             if (context.extensions) {
                 for (const key of Object.keys(context.extensions)) {
-                    if (Plugin[extensionOwnersKey].get(key) === name) {
-                        delete Plugin.prototype[key];
-                        Plugin[extensionOwnersKey].delete(key);
-                    }
+                    delete Plugin.prototype[key];
                 }
             }
             if (typeof context.dispose === "function") {
@@ -672,16 +581,10 @@ export class Plugin extends EventEmitter {
             await child.broadcast(name, ...args);
         }
     }
-    // ============================================================================
-    // 依赖注入
-    // ============================================================================
-    /**
-     * 注册上下文（支持 Feature 实例或传统 Context 对象）
-     */
     provide(target) {
         if (target instanceof Feature) {
             const feature = target;
-            const context = {
+            const ctx = {
                 name: feature.name,
                 description: feature.desc,
                 value: feature,
@@ -696,29 +599,22 @@ export class Plugin extends EventEmitter {
                     : undefined,
                 extensions: feature.extensions,
             };
-            return this.provide(context);
+            return this.provide(ctx);
         }
         const context = target;
         if (!Plugin[contextsKey].includes(context.name)) {
             Plugin[contextsKey].push(context.name);
         }
         this.logger.debug(`Context "${context.name}" provided`);
-        // Track which extension methods this context registers.
-        // On collision, log a warning but allow override (last-write-wins).
+        this.$contexts.set(context.name, context);
+        // 立即注册扩展方法到 Plugin.prototype，确保后续 import 的插件可用
         if (context.extensions) {
-            const extNames = [];
             for (const [name, fn] of Object.entries(context.extensions)) {
                 if (typeof fn === 'function') {
-                    if (Reflect.has(Plugin.prototype, name) && !Plugin[extensionOwnersKey].has(name)) {
-                        this.logger.warn(`Extension method "${name}" shadows an existing Plugin method`);
-                    }
                     Reflect.set(Plugin.prototype, name, fn);
-                    Plugin[extensionOwnersKey].set(name, context.name);
-                    extNames.push(name);
                 }
             }
         }
-        this.$contexts.set(context.name, context);
         return this;
     }
     // ============================================================================
@@ -800,8 +696,7 @@ export class Plugin extends EventEmitter {
     static #coreMethods = new Set([
         'addMiddleware', 'useContext', 'inject', 'contextIsReady',
         'start', 'stop', 'onMounted', 'onDispose',
-        'dispatch', 'broadcast', 'provide', 'import', 'reload', 'watch', 'info',
-        'recordFeatureContribution', 'getFeatures',
+        'dispatch', 'broadcast', 'provide', 'import', 'reload', 'watch', 'info'
     ]);
     /**
      * 自动绑定核心方法（只在构造函数中调用一次）
@@ -837,41 +732,13 @@ export class Plugin extends EventEmitter {
         plugin.fileHash = getFileHash(entryFile);
         // 先记录，防止循环依赖时重复加载
         loadedModules.set(realPath, plugin);
-        let mod;
         await storage.run(plugin, async () => {
-            mod = await import(`${pathToFileURL(entryFile).href}?t=${Date.now()}`);
+            await import(`${import.meta.resolve(entryFile)}?t=${Date.now()}`);
         });
-        // 支持模块显式声明插件名称：export const pluginName = 'my-plugin'
-        if (mod?.pluginName && typeof mod.pluginName === 'string') {
-            plugin.setName(mod.pluginName);
-        }
         return plugin;
     }
 }
 export function defineContext(options) {
     return options;
 }
-/**
- * 声明式定义插件。
- * 提供显式名称 + setup 函数，自动设置当前插件名称并执行 setup。
- *
- * @example
- * ```typescript
- * // plugins/weather/index.ts
- * export default definePlugin({
- *   name: 'weather',
- *   setup(plugin) {
- *     plugin.addTool({ ... });
- *   },
- * });
- * ```
- */
-export function definePlugin(options) {
-    const plugin = usePlugin();
-    if (options.name) {
-        plugin.setName(options.name);
-    }
-    options.setup(plugin);
-    return { pluginName: options.name };
-}
 //# sourceMappingURL=plugin.js.map