@zhin.js/core 1.0.24 → 1.0.26

package/lib/adapter.js

@@ -1,8 +1,11 @@
 import { EventEmitter } from "events";
 import { segment } from "./utils.js";
+import { isZhinTool } from "./built/tool.js";
 /**
  * Adapter类：适配器抽象，管理多平台Bot实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
+ *
+ * 适配器可以提供 AI 工具，供 AI 服务调用。
  */
 export class Adapter extends EventEmitter {
     plugin;
@@ -10,6 +13,10 @@ export class Adapter extends EventEmitter {
     config;
     /** 当前适配器下所有Bot实例，key为bot名称 */
     bots = new Map();
+    /** 适配器提供的工具 */
+    tools = new Map();
+    /** Skill 注销函数（declareSkill 时设置） */
+    _skillDispose;
     /**
      * 构造函数
      * @param name 适配器名称（如 'process'、'qq' 等）
@@ -29,7 +36,20 @@ export class Adapter extends EventEmitter {
         });
         this.on('message.receive', (message) => {
             this.logger.info(`${message.$bot} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
-            this.plugin?.middleware(message, async () => { });
+            const rootPlugin = this.plugin?.root || this.plugin;
+            // 优先使用 MessageDispatcher（新架构），回退到旧中间件链（兼容）
+            const dispatcher = rootPlugin?.inject('dispatcher');
+            if (dispatcher && typeof dispatcher.dispatch === 'function') {
+                void dispatcher.dispatch(message).catch((err) => {
+                    this.logger.error('dispatcher.dispatch(message) failed', err);
+                });
+            }
+            else {
+                // 旧中间件链回退
+                void Promise.resolve(rootPlugin?.middleware(message, async () => { })).catch((err) => {
+                    this.logger.error('rootPlugin.middleware(message, next) failed', err);
+                });
+            }
         });
     }
     get logger() {
@@ -87,6 +107,9 @@ export class Adapter extends EventEmitter {
             }
             // 清理 bots Map
             this.bots.clear();
+            // 清理 Skill
+            this._skillDispose?.();
+            this._skillDispose = undefined;
             // 从 adapters 数组中移除
             const idx = this.plugin.root.adapters.indexOf(this.name);
             if (idx !== -1) {
@@ -101,6 +124,164 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * 注册工具
+     * @param input 工具定义（支持 Tool 对象或 ZhinTool 实例）
+     * @returns 返回一个移除工具的函数
+     */
+    addTool(input) {
+        // 如果是 ZhinTool 实例，转换为 Tool 对象
+        const tool = isZhinTool(input) ? input.toTool() : input;
+        // 自动添加适配器源标识
+        const toolWithSource = {
+            ...tool,
+            source: tool.source || `adapter:${this.name}`,
+            tags: [...(tool.tags || []), 'adapter', this.name],
+        };
+        this.tools.set(tool.name, toolWithSource);
+        // 同步到全局 ToolFeature（如果可用），使适配器工具出现在插件 features 统计中
+        let globalDispose;
+        const toolFeature = this.plugin?.root?.inject('tool');
+        if (toolFeature && typeof toolFeature.addTool === 'function') {
+            const adapterPluginName = this.plugin?.name || `adapter:${this.name}`;
+            globalDispose = toolFeature.addTool(toolWithSource, adapterPluginName, false);
+            // 记录到宿主插件的 feature 贡献
+            this.plugin?.recordFeatureContribution('tool', tool.name);
+        }
+        return () => {
+            this.tools.delete(tool.name);
+            globalDispose?.();
+        };
+    }
+    /**
+     * 获取所有注册的工具
+     * @returns 工具数组
+     */
+    getTools() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * 根据名称获取工具
+     * @param name 工具名称
+     * @returns 工具定义或 undefined
+     */
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * 声明适配器的 Skill（将 this.tools 聚合为一个 Skill 注册到 SkillFeature）
+     *
+     * @param metadata Skill 元数据
+     *   - description: 平台级能力描述
+     *   - keywords: 额外的触发关键词（可选，会自动从工具中聚合）
+     *   - tags: 额外的分类标签（可选，会自动从工具中聚合）
+     *   - conventions: 平台调用约定（可选，拼接到 description 末尾）
+     */
+    declareSkill(metadata) {
+        const skillFeature = this.plugin?.root?.inject('skill');
+        if (!skillFeature) {
+            this.logger.debug(`declareSkill: SkillFeature 不可用，跳过 Skill 注册`);
+            return;
+        }
+        // 收集适配器所有工具
+        const tools = this.getTools();
+        // 聚合关键词：metadata 声明 + 工具自带
+        const allKeywords = new Set(metadata.keywords || []);
+        for (const tool of tools) {
+            if (tool.keywords) {
+                for (const kw of tool.keywords) {
+                    allKeywords.add(kw);
+                }
+            }
+        }
+        // 聚合标签：metadata 声明 + 工具自带
+        const allTags = new Set(metadata.tags || []);
+        for (const tool of tools) {
+            if (tool.tags) {
+                for (const tag of tool.tags) {
+                    allTags.add(tag);
+                }
+            }
+        }
+        // 拼接描述：基础描述 + 调用约定
+        let description = metadata.description;
+        if (metadata.conventions) {
+            description += `\n\n调用约定：${metadata.conventions}`;
+        }
+        const pluginName = this.plugin?.name || `adapter:${this.name}`;
+        const skill = {
+            name: `adapter:${this.name}`,
+            description,
+            tools,
+            keywords: Array.from(allKeywords),
+            tags: Array.from(allTags),
+            pluginName,
+        };
+        // 清理旧的 Skill（如果有）
+        this._skillDispose?.();
+        // 注册到 SkillFeature
+        this._skillDispose = skillFeature.add(skill, pluginName);
+        this.plugin?.recordFeatureContribution('skill', `adapter:${this.name}`);
+        this.logger.debug(`declareSkill: 已注册 Skill "${skill.name}"，包含 ${tools.length} 个工具`);
+    }
+    /**
+     * 提供默认的适配器工具（子类可覆盖）
+     * 包含发送消息、撤回消息等基础能力
+     */
+    registerDefaultTools() {
+        // 发送消息工具
+        this.addTool({
+            name: `${this.name}_send_message`,
+            description: `使用 ${this.name} 适配器发送消息到指定目标`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    bot: {
+                        type: 'string',
+                        description: 'Bot 名称/ID',
+                    },
+                    id: {
+                        type: 'string',
+                        description: '目标 ID（用户/群/频道）',
+                    },
+                    type: {
+                        type: 'string',
+                        description: '消息类型',
+                    },
+                    content: {
+                        type: 'string',
+                        description: '消息内容',
+                    },
+                },
+                required: ['bot', 'id', 'type', 'content'],
+            },
+            execute: async (args) => {
+                const { bot, id, type, content } = args;
+                return await this.sendMessage({
+                    context: this.name,
+                    bot,
+                    id,
+                    type: type,
+                    content,
+                });
+            },
+        });
+        // 获取 Bot 列表工具
+        this.addTool({
+            name: `${this.name}_list_bots`,
+            description: `获取 ${this.name} 适配器下所有已连接的 Bot 列表`,
+            parameters: {
+                type: 'object',
+                properties: {},
+            },
+            execute: async () => {
+                return Array.from(this.bots.entries()).map(([id, bot]) => ({
+                    id,
+                    connected: bot.$connected,
+                }));
+            },
+        });
+    }
 }
 (function (Adapter) {
     /**

package/lib/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/lib/ai/agent.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @zhin.js/ai - Agent System
+ * AI Agent 实现，支持工具调用和多轮对话
+ */
+import type { AIProvider, AgentConfig, AgentTool, AgentResult, ChatMessage, ToolFilterOptions, Usage } from './types.js';
+/**
+ * Agent 执行状态
+ */
+export interface AgentState {
+    messages: ChatMessage[];
+    toolCalls: {
+        tool: string;
+        args: Record<string, any>;
+        result: any;
+    }[];
+    usage: Usage;
+    iterations: number;
+}
+/**
+ * Agent 事件
+ */
+export interface AgentEvents {
+    'thinking': (message: string) => void;
+    'tool_call': (tool: string, args: Record<string, any>) => void;
+    'tool_result': (tool: string, result: any) => void;
+    'streaming': (content: string) => void;
+    'complete': (result: AgentResult) => void;
+    'error': (error: Error) => void;
+}
+/**
+ * AI Agent 类
+ * 支持工具调用、多轮对话、流式输出
+ */
+export declare class Agent {
+    private provider;
+    private config;
+    private tools;
+    private eventHandlers;
+    constructor(provider: AIProvider, config: AgentConfig);
+    /**
+     * 默认系统提示词
+     */
+    private getDefaultSystemPrompt;
+    /**
+     * 注册事件处理器
+     */
+    on<K extends keyof AgentEvents>(event: K, handler: AgentEvents[K]): () => void;
+    /**
+     * 触发事件
+     */
+    private emit;
+    /**
+     * 添加工具
+     */
+    addTool(tool: AgentTool): void;
+    /**
+     * 移除工具
+     */
+    removeTool(name: string): void;
+    /**
+     * 获取工具定义（缓存在第一次调用后保持不变）
+     */
+    private getToolDefinitions;
+    /**
+     * 生成工具调用的去重 key
+     */
+    private static toolCallKey;
+    /**
+     * 安全解析 JSON，失败则返回原始字符串
+     */
+    private static safeParse;
+    /**
+     * 程序化工具过滤 —— 替代 AI 意图分析的高效方案
+     *
+     * 评分规则（按权重从高到低）：
+     * 1. keywords 精确匹配: +1.0 per hit   —— 工具声明的触发关键词
+     * 2. tags 匹配:          +0.5 per hit   —— 工具分类标签
+     * 3. 工具名 token 匹配:  +0.3 per hit   —— 工具名按 `.` `_` `-` 拆词
+     * 4. description 关键词:  +0.15 per hit  —— 描述中的词/短语
+     *
+     * 权限过滤发生在评分之前，直接跳过无权使用的工具。
+     *
+     * @param message      用户消息原文
+     * @param tools        候选工具列表
+     * @param options      过滤选项
+     * @returns            按相关性降序排列的工具子集
+     */
+    static filterTools(message: string, tools: AgentTool[], options?: ToolFilterOptions): AgentTool[];
+    /**
+     * 执行单个工具调用（带超时保护）
+     */
+    private executeToolCall;
+    /**
+     * 并行执行多个工具调用（跳过重复的）
+     * @returns 新执行的工具调用结果列表；如果全部重复则返回空数组
+     */
+    private executeToolCalls;
+    /**
+     * 累加 token 用量
+     */
+    private static addUsage;
+    /**
+     * 运行 Agent
+     *
+     * @param userMessage    用户消息
+     * @param context        对话上下文
+     * @param filterOptions  工具过滤选项 —— 启用后在 AI 调用之前程序化筛选工具，省去额外的 AI 意图分析往返
+     */
+    run(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): Promise<AgentResult>;
+    /**
+     * 流式运行 Agent
+     *
+     * @param userMessage    用户消息
+     * @param context        对话上下文
+     * @param filterOptions  工具过滤选项 —— 启用后在 AI 调用之前程序化筛选工具
+     */
+    runStream(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): AsyncIterable<{
+        type: 'content' | 'tool_call' | 'tool_result' | 'done';
+        data: any;
+    }>;
+}
+/**
+ * 创建 Agent 实例
+ */
+export declare function createAgent(provider: AIProvider, config: Omit<AgentConfig, 'provider'>): Agent;
+//# sourceMappingURL=agent.d.ts.map

package/lib/ai/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/ai/agent.ts"],"names":[],"mappings":"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"}