@zhin.js/core 1.0.24 → 1.0.26

package/lib/built/tool.js

@@ -0,0 +1,749 @@
+/**
+ * ToolFeature — 统一的工具管理服务
+ * 支持 Tool ↔ Command 互转
+ */
+import { Feature } from "../feature.js";
+import { MessageCommand } from "../command.js";
+import { getPlugin } from "../plugin.js";
+// ============================================================================
+// 权限级别比较
+// ============================================================================
+/**
+ * 权限级别优先级（数字越大权限越高）
+ */
+const PERMISSION_LEVEL_PRIORITY = {
+    'user': 0,
+    'group_admin': 1,
+    'group_owner': 2,
+    'bot_admin': 3,
+    'owner': 4,
+};
+/**
+ * 比较两个权限级别
+ * @returns 如果 a >= b 返回 true
+ */
+function hasPermissionLevel(userLevel, requiredLevel) {
+    return PERMISSION_LEVEL_PRIORITY[userLevel] >= PERMISSION_LEVEL_PRIORITY[requiredLevel];
+}
+/**
+ * 从 ToolContext 推断用户的权限级别
+ */
+function inferPermissionLevel(context) {
+    if (context.senderPermissionLevel) {
+        return context.senderPermissionLevel;
+    }
+    // 按优先级检查
+    if (context.isOwner)
+        return 'owner';
+    if (context.isBotAdmin)
+        return 'bot_admin';
+    if (context.isGroupOwner)
+        return 'group_owner';
+    if (context.isGroupAdmin)
+        return 'group_admin';
+    return 'user';
+}
+/**
+ * 检查工具是否可被当前上下文访问
+ */
+function canAccessTool(tool, context) {
+    // 1. 检查平台限制
+    if (tool.platforms && tool.platforms.length > 0) {
+        if (!context.platform || !tool.platforms.includes(context.platform)) {
+            return false;
+        }
+    }
+    // 2. 检查场景限制
+    if (tool.scopes && tool.scopes.length > 0) {
+        if (!context.scope || !tool.scopes.includes(context.scope)) {
+            return false;
+        }
+    }
+    // 3. 检查权限级别
+    const requiredLevel = tool.permissionLevel || 'user';
+    const userLevel = inferPermissionLevel(context);
+    if (!hasPermissionLevel(userLevel, requiredLevel)) {
+        return false;
+    }
+    return true;
+}
+// ============================================================================
+// Tool 工具函数
+// ============================================================================
+/**
+ * 从 Tool 参数生成命令模式
+ * @example
+ * parameters: { properties: { city: { type: 'string' } }, required: ['city'] }
+ * => 'toolName <city>'
+ */
+export function generatePattern(tool) {
+    const { name, parameters } = tool;
+    if (tool.command && tool.command.pattern) {
+        return tool.command.pattern;
+    }
+    if (!parameters.properties) {
+        return name;
+    }
+    const parts = [name];
+    const props = parameters.properties;
+    const required = parameters.required || [];
+    // 按照 required 优先、字母顺序排序
+    const sortedKeys = Object.keys(props).sort((a, b) => {
+        const aReq = required.includes(a) ? 0 : 1;
+        const bReq = required.includes(b) ? 0 : 1;
+        if (aReq !== bReq)
+            return aReq - bReq;
+        return a.localeCompare(b);
+    });
+    for (const key of sortedKeys) {
+        const prop = props[key];
+        const isRequired = required.includes(key);
+        const paramType = prop.paramType || (prop.type === 'number' ? 'number' : 'text');
+        if (isRequired) {
+            parts.push(`<${key}:${paramType}>`);
+        }
+        else {
+            parts.push(`[${key}:${paramType}]`);
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * 从参数定义中提取参数信息
+ */
+export function extractParamInfo(parameters) {
+    if (!parameters.properties)
+        return [];
+    const required = parameters.required || [];
+    return Object.entries(parameters.properties).map(([name, schema]) => ({
+        name,
+        type: schema.type,
+        required: required.includes(name),
+        description: schema.description,
+        default: schema.default,
+        enum: schema.enum,
+    }));
+}
+/**
+ * 定义工具的辅助函数（提供类型推断）
+ */
+export function defineTool(tool) {
+    return tool;
+}
+/**
+ * ZhinTool 类
+ * 提供类似 MessageCommand 的链式调用风格来定义工具
+ */
+export class ZhinTool {
+    #name;
+    #description = '';
+    /** 有序的参数列表 */
+    #params = [];
+    #execute;
+    #platforms = [];
+    #scopes = [];
+    #permissionLevel = 'user';
+    #permissions = [];
+    #tags = [];
+    #keywords = [];
+    /** 命令回调（入参是 message, matchResult） */
+    #commandCallback;
+    /** 命令配置 */
+    #commandConfig = {};
+    #hidden = false;
+    #source;
+    constructor(name) {
+        this.#name = name;
+    }
+    get name() {
+        return this.#name;
+    }
+    get description() {
+        return this.#description;
+    }
+    get params() {
+        return [...this.#params];
+    }
+    desc(description) {
+        this.#description = description;
+        return this;
+    }
+    param(name, schema, required = false) {
+        const existingIndex = this.#params.findIndex(p => p.name === name);
+        if (existingIndex >= 0) {
+            this.#params[existingIndex] = { name, schema, required };
+        }
+        else {
+            this.#params.push({ name, schema, required });
+        }
+        return this;
+    }
+    platform(...platforms) {
+        this.#platforms.push(...platforms);
+        return this;
+    }
+    scope(...scopes) {
+        this.#scopes.push(...scopes);
+        return this;
+    }
+    permission(level) {
+        this.#permissionLevel = level;
+        return this;
+    }
+    permit(...permissions) {
+        this.#permissions.push(...permissions);
+        return this;
+    }
+    tag(...tags) {
+        this.#tags.push(...tags);
+        return this;
+    }
+    keyword(...keywords) {
+        this.#keywords.push(...keywords);
+        return this;
+    }
+    hidden(value = true) {
+        this.#hidden = value;
+        return this;
+    }
+    usage(...usage) {
+        this.#commandConfig.usage = [...(this.#commandConfig.usage || []), ...usage];
+        return this;
+    }
+    examples(...examples) {
+        this.#commandConfig.examples = [...(this.#commandConfig.examples || []), ...examples];
+        return this;
+    }
+    alias(...alias) {
+        this.#commandConfig.alias = [...(this.#commandConfig.alias || []), ...alias];
+        return this;
+    }
+    pattern(pattern) {
+        this.#commandConfig.pattern = pattern;
+        return this;
+    }
+    execute(callback) {
+        this.#execute = callback;
+        return this;
+    }
+    action(callback) {
+        this.#commandCallback = callback;
+        return this;
+    }
+    #buildParameters() {
+        const properties = {};
+        const required = [];
+        const sortedParams = [...this.#params].sort((a, b) => {
+            if (a.required && !b.required)
+                return -1;
+            if (!a.required && b.required)
+                return 1;
+            return 0;
+        });
+        for (const param of sortedParams) {
+            properties[param.name] = param.schema;
+            if (param.required) {
+                required.push(param.name);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined,
+        };
+    }
+    #generatePattern() {
+        if (this.#commandConfig.pattern) {
+            return this.#commandConfig.pattern;
+        }
+        const parts = [this.#name];
+        const sortedParams = [...this.#params].sort((a, b) => {
+            if (a.required && !b.required)
+                return -1;
+            if (!a.required && b.required)
+                return 1;
+            return 0;
+        });
+        for (const param of sortedParams) {
+            const paramType = param.schema.paramType || (param.schema.type === 'number' ? 'number' : 'text');
+            if (param.required) {
+                parts.push(`<${param.name}:${paramType}>`);
+            }
+            else {
+                parts.push(`[${param.name}:${paramType}]`);
+            }
+        }
+        return parts.join(' ');
+    }
+    toTool() {
+        if (!this.#execute) {
+            throw new Error(`Tool "${this.#name}" has no execute() defined`);
+        }
+        const tool = {
+            name: this.#name,
+            description: this.#description,
+            parameters: this.#buildParameters(),
+            execute: this.#execute,
+        };
+        if (this.#platforms.length > 0)
+            tool.platforms = this.#platforms;
+        if (this.#scopes.length > 0)
+            tool.scopes = this.#scopes;
+        if (this.#permissionLevel !== 'user')
+            tool.permissionLevel = this.#permissionLevel;
+        if (this.#permissions.length > 0)
+            tool.permissions = this.#permissions;
+        if (this.#tags.length > 0)
+            tool.tags = this.#tags;
+        if (this.#hidden)
+            tool.hidden = this.#hidden;
+        if (this.#source)
+            tool.source = this.#source;
+        if (this.#keywords.length > 0)
+            tool.keywords = this.#keywords;
+        if (!this.#commandCallback) {
+            tool.command = false;
+        }
+        else {
+            tool.command = {
+                ...this.#commandConfig,
+                pattern: this.#generatePattern(),
+                enabled: true,
+            };
+        }
+        return tool;
+    }
+    getActionCallback() {
+        return this.#commandCallback;
+    }
+    toJSON() {
+        const json = {
+            name: this.#name,
+            description: this.#description,
+            parameters: this.#buildParameters(),
+        };
+        if (this.#platforms.length > 0)
+            json.platforms = this.#platforms;
+        if (this.#scopes.length > 0)
+            json.scopes = this.#scopes;
+        if (this.#permissionLevel !== 'user')
+            json.permissionLevel = this.#permissionLevel;
+        if (this.#tags.length > 0)
+            json.tags = this.#tags;
+        return json;
+    }
+    get help() {
+        const lines = [this.#generatePattern()];
+        if (this.#description)
+            lines.push(`  ${this.#description}`);
+        if (this.#params.length > 0) {
+            lines.push('  参数:');
+            for (const param of this.#params) {
+                const required = param.required ? '(必填)' : '(可选)';
+                const desc = param.schema.description || '';
+                lines.push(`    ${param.name}: ${param.schema.type} ${required} ${desc}`);
+            }
+        }
+        if (this.#permissionLevel !== 'user') {
+            lines.push(`  权限: ${this.#permissionLevel}`);
+        }
+        if (this.#platforms.length > 0) {
+            lines.push(`  平台: ${this.#platforms.join(', ')}`);
+        }
+        if (this.#scopes.length > 0) {
+            lines.push(`  场景: ${this.#scopes.join(', ')}`);
+        }
+        if (this.#commandConfig.usage?.length) {
+            lines.push('  用法:');
+            for (const u of this.#commandConfig.usage) {
+                lines.push(`    ${u}`);
+            }
+        }
+        if (this.#commandConfig.examples?.length) {
+            lines.push('  示例:');
+            for (const e of this.#commandConfig.examples) {
+                lines.push(`    ${e}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    toString() {
+        return `[ZhinTool: ${this.#name}] ${this.#description}`;
+    }
+}
+export function isZhinTool(obj) {
+    return obj instanceof ZhinTool;
+}
+// ============================================================================
+// 内部工具函数
+// ============================================================================
+/**
+ * 将 Tool 转换为 MessageCommand
+ */
+function toolToCommand(tool) {
+    const pattern = generatePattern(tool);
+    const command = new MessageCommand(pattern);
+    command.desc(tool.description);
+    if (tool.command && tool.command.usage) {
+        command.usage(...tool.command.usage);
+    }
+    if (tool.command && tool.command.examples) {
+        command.examples(...tool.command.examples);
+    }
+    if (tool.permissions?.length) {
+        command.permit(...tool.permissions);
+    }
+    command.action(async (message, result) => {
+        const context = {
+            platform: message.$adapter,
+            botId: message.$bot,
+            sceneId: message.$channel?.id || message.$sender.id,
+            senderId: message.$sender.id,
+            message,
+        };
+        const args = extractArgsFromMatchResult(result, tool.parameters);
+        try {
+            const response = await tool.execute(args, context);
+            if (response === undefined || response === null) {
+                return undefined;
+            }
+            if (typeof response === 'string') {
+                return response;
+            }
+            return formatToolResult(response);
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            return `❌ 执行失败: ${errorMsg}`;
+        }
+    });
+    return command;
+}
+/**
+ * 将 MessageCommand 转换为 Tool
+ */
+function commandToToolFn(command, pluginName) {
+    const { pattern, helpInfo } = command;
+    const parameters = parseCommandPattern(pattern);
+    return {
+        name: `cmd_${pattern.split(' ')[0].replace(/[^a-zA-Z0-9_]/g, '_')}`,
+        description: helpInfo.desc.join(' ') || `执行命令: ${pattern}`,
+        parameters,
+        source: `command:${pluginName}`,
+        tags: ['command', pluginName],
+        execute: async (args, context) => {
+            const cmdParts = [pattern.split(' ')[0]];
+            if (parameters.properties) {
+                for (const [key, schema] of Object.entries(parameters.properties)) {
+                    if (args[key] !== undefined) {
+                        cmdParts.push(String(args[key]));
+                    }
+                }
+            }
+            const cmdString = cmdParts.join(' ');
+            if (context?.message) {
+                const tempMessage = Object.create(context.message);
+                tempMessage.$content = cmdString;
+                const plugin = getPlugin();
+                const result = await command.handle(tempMessage, plugin);
+                return result;
+            }
+            return {
+                error: '此工具需要消息上下文才能执行',
+                command: cmdString
+            };
+        },
+        command: false,
+    };
+}
+/**
+ * 从 MatchResult 提取参数
+ */
+function extractArgsFromMatchResult(result, schema) {
+    const args = {};
+    if (result.params) {
+        Object.assign(args, result.params);
+    }
+    if (schema.properties) {
+        for (const [key, prop] of Object.entries(schema.properties)) {
+            if (args[key] !== undefined) {
+                if (prop.type === 'number') {
+                    args[key] = Number(args[key]);
+                }
+                else if (prop.type === 'boolean') {
+                    args[key] = args[key] === 'true' || args[key] === true;
+                }
+                else if (prop.type === 'array' && typeof args[key] === 'string') {
+                    args[key] = args[key].split(',').map((s) => s.trim());
+                }
+            }
+        }
+    }
+    return args;
+}
+/**
+ * 解析命令模式，生成参数 Schema
+ */
+function parseCommandPattern(pattern) {
+    const properties = {};
+    const required = [];
+    const paramRegex = /([<\[])(\w+)(?::(\w+))?([>\]])/g;
+    let match;
+    while ((match = paramRegex.exec(pattern)) !== null) {
+        const [, bracket, name, type] = match;
+        const isRequired = bracket === '<';
+        const schemaType = type === 'number' ? 'number' : type === 'boolean' ? 'boolean' : 'string';
+        properties[name] = {
+            type: schemaType,
+            description: `参数: ${name}`,
+        };
+        if (isRequired) {
+            required.push(name);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined,
+    };
+}
+/**
+ * 格式化工具执行结果
+ */
+function formatToolResult(result) {
+    if (result === null || result === undefined) {
+        return '';
+    }
+    if (typeof result === 'string') {
+        return result;
+    }
+    if (result.error) {
+        return `❌ ${result.error}`;
+    }
+    try {
+        return JSON.stringify(result, null, 2);
+    }
+    catch {
+        return String(result);
+    }
+}
+// ============================================================================
+// ToolFeature 实现
+// ============================================================================
+export class ToolFeature extends Feature {
+    name = 'tool';
+    icon = 'Wrench';
+    desc = '工具';
+    /** 按名称索引 */
+    byName = new Map();
+    /** 工具对应的命令 */
+    toolCommands = new Map();
+    /** 工具到插件名的映射 */
+    #toolPluginMap = new Map();
+    /**
+     * 添加工具
+     * @param toolInput 工具或 ZhinTool 实例
+     * @param pluginName 注册插件名
+     * @param generateCommand 是否生成命令（默认 true）
+     */
+    addTool(toolInput, pluginName, generateCommand = true) {
+        const zhinTool = isZhinTool(toolInput) ? toolInput : null;
+        const tool = zhinTool ? zhinTool.toTool() : toolInput;
+        const toolWithSource = {
+            ...tool,
+            source: tool.source || `plugin:${pluginName}`,
+            tags: [...(tool.tags || []), 'plugin', pluginName],
+        };
+        this.byName.set(tool.name, toolWithSource);
+        this.#toolPluginMap.set(tool.name, pluginName);
+        // 生成对应的命令
+        if (generateCommand && tool.command !== false) {
+            let command;
+            const customCallback = zhinTool?.getActionCallback();
+            if (customCallback) {
+                command = new MessageCommand(tool.command && typeof tool.command === 'object' && tool.command.pattern
+                    ? tool.command.pattern
+                    : generatePattern(toolWithSource));
+                command.desc(tool.description);
+                if (tool.command && typeof tool.command === 'object') {
+                    if (tool.command.usage)
+                        command.usage(...tool.command.usage);
+                    if (tool.command.examples)
+                        command.examples(...tool.command.examples);
+                }
+                if (tool.permissions?.length) {
+                    command.permit(...tool.permissions);
+                }
+                command.action(customCallback);
+            }
+            else {
+                command = toolToCommand(toolWithSource);
+            }
+            this.toolCommands.set(tool.name, command);
+            const plugin = getPlugin();
+            const commandService = plugin.root.inject('command');
+            if (commandService) {
+                commandService.add(command, pluginName);
+            }
+        }
+        // Use Feature.add for item tracking
+        const baseDispose = super.add(toolWithSource, pluginName);
+        return () => {
+            this.removeTool(tool.name);
+            baseDispose();
+        };
+    }
+    /**
+     * 移除工具
+     */
+    removeTool(name) {
+        const tool = this.byName.get(name);
+        if (!tool)
+            return false;
+        this.byName.delete(name);
+        this.#toolPluginMap.delete(name);
+        // 移除对应的命令
+        const command = this.toolCommands.get(name);
+        if (command) {
+            const plugin = getPlugin();
+            const commandService = plugin.root.inject('command');
+            if (commandService) {
+                commandService.remove(command);
+            }
+            this.toolCommands.delete(name);
+        }
+        // 移除 item
+        super.remove(tool);
+        return true;
+    }
+    /**
+     * 获取工具
+     */
+    get(name) {
+        return this.byName.get(name);
+    }
+    /**
+     * 获取所有工具
+     */
+    getAll() {
+        return [...this.items];
+    }
+    /**
+     * 根据标签过滤工具
+     */
+    getByTags(tags) {
+        return this.items.filter(tool => tags.some(tag => tool.tags?.includes(tag)));
+    }
+    /**
+     * 执行工具
+     */
+    async execute(name, args, context) {
+        const tool = this.byName.get(name);
+        if (!tool) {
+            throw new Error(`Tool "${name}" not found`);
+        }
+        return tool.execute(args, context);
+    }
+    /**
+     * 将 Command 转换为 Tool
+     */
+    commandToTool(command, pluginName) {
+        return commandToToolFn(command, pluginName);
+    }
+    /**
+     * 收集所有可用工具（包括从 Command 转换的）
+     */
+    collectAll(plugin) {
+        const allTools = [];
+        allTools.push(...this.getAll());
+        const commandService = plugin.root.inject('command');
+        if (commandService) {
+            for (const command of commandService.items) {
+                const isFromTool = Array.from(this.toolCommands.values()).includes(command);
+                if (!isFromTool) {
+                    const toolFromCmd = commandToToolFn(command, 'command');
+                    allTools.push(toolFromCmd);
+                }
+            }
+        }
+        for (const [name, context] of plugin.root.contexts) {
+            const adapterValue = context.value;
+            if (adapterValue && typeof adapterValue === 'object' && 'getTools' in adapterValue) {
+                const adapter = adapterValue;
+                allTools.push(...adapter.getTools());
+            }
+        }
+        return allTools;
+    }
+    /**
+     * 根据上下文过滤工具
+     */
+    filterByContext(tools, context) {
+        return tools.filter(tool => canAccessTool(tool, context));
+    }
+    /**
+     * 按插件名获取工具
+     */
+    getToolsByPlugin(pluginName) {
+        const result = [];
+        for (const [toolName, pName] of this.#toolPluginMap) {
+            if (pName === pluginName) {
+                const tool = this.byName.get(toolName);
+                if (tool)
+                    result.push(tool);
+            }
+        }
+        return result;
+    }
+    /**
+     * 兼容旧接口：tools Map
+     */
+    get tools() {
+        return this.byName;
+    }
+    /**
+     * 序列化为 JSON
+     */
+    toJSON(pluginName) {
+        const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+        return {
+            name: this.name,
+            icon: this.icon,
+            desc: this.desc,
+            count: list.length,
+            items: list.map(t => ({
+                name: t.name,
+                desc: t.description,
+                platforms: t.platforms,
+                tags: t.tags,
+            })),
+        };
+    }
+    /**
+     * 提供给 Plugin.prototype 的扩展方法
+     */
+    get extensions() {
+        const feature = this;
+        return {
+            addTool(tool) {
+                const plugin = getPlugin();
+                const toolObj = isZhinTool(tool) ? tool.toTool() : tool;
+                const dispose = feature.addTool(tool, plugin.name, true);
+                plugin.recordFeatureContribution(feature.name, toolObj.name);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+            addToolOnly(tool) {
+                const plugin = getPlugin();
+                const toolObj = isZhinTool(tool) ? tool.toTool() : tool;
+                const dispose = feature.addTool(tool, plugin.name, false);
+                plugin.recordFeatureContribution(feature.name, toolObj.name);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+        };
+    }
+}
+// 导出类型和工具函数
+export { toolToCommand, commandToToolFn as commandToTool, canAccessTool, inferPermissionLevel, hasPermissionLevel, PERMISSION_LEVEL_PRIORITY, };
+//# sourceMappingURL=tool.js.map