@zhin.js/ai 0.0.2 → 1.0.1

package/CHANGELOG.md

@@ -1,12 +1,7 @@
 # @zhin.js/ai
 
-## 0.0.2
+## 1.0.1
 
 ### Patch Changes
 
-- 26d2942: fix: ai
-- 6b02c41: fix: ai
-- Updated dependencies [26d2942]
-- Updated dependencies [6b02c41]
-  - @zhin.js/logger@0.1.9
-  - @zhin.js/core@1.0.25
+- @zhin.js/logger@0.1.24

package/lib/agent.d.ts

@@ -1,8 +1,12 @@
 /**
- * @zhin.js/ai - Agent System
+ * @zhin.js/agent - Agent System
  * AI Agent 实现，支持工具调用和多轮对话
  */
-import type { AIProvider, AgentConfig, AgentTool, AgentResult, ChatMessage, Usage } from './types.js';
+import type { AIProvider, AgentConfig, AgentTool, AgentResult, ChatMessage, ToolFilterOptions, Usage } from './types.js';
+/**
+ * 根据工具名和参数生成简短标题（用于日志、TOOLS.md 等）
+ */
+export declare function formatToolTitle(name: string, args?: Record<string, any>): string;
 /**
  * Agent 执行状态
  */
@@ -58,21 +62,65 @@ export declare class Agent {
      */
     removeTool(name: string): void;
     /**
-     * 获取工具定义
+     * 获取工具定义（缓存在第一次调用后保持不变）
      */
     private getToolDefinitions;
     /**
-     * 执行工具调用
+     * 生成工具调用的去重 key（规范化参数以避免 "" vs "{}" 等差异）
+     */
+    private static toolCallKey;
+    /**
+     * 安全解析 JSON，失败则返回原始字符串
+     */
+    private static safeParse;
+    /**
+     * 程序化工具过滤 —— TF-IDF 加权的相关性评分
+     *
+     * 评分层级（基础权重 × IDF 倍率）：
+     * 1. keywords 精确匹配: base 1.0 × idf  —— 工具声明的触发关键词
+     * 2. tags 匹配:          base 0.5 × idf  —— 工具分类标签
+     * 3. 工具名 token 匹配:  base 0.3 × idf  —— 工具名按 `.` `_` `-` 拆词
+     * 4. description 关键词:  base 0.15 × idf —— 描述中的词/短语
+     *
+     * IDF = log(N / df)，N 为工具总数，df 为包含该词的工具数。
+     * 高频词（出现在大部分工具中）的 IDF 接近 0，权重被压低；
+     * 稀有词（仅少数工具有）的 IDF 较高，权重被放大。
+     *
+     * @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[]): Promise<AgentResult>;
+    run(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): Promise<AgentResult>;
     /**
      * 流式运行 Agent
+     *
+     * @param userMessage    用户消息
+     * @param context        对话上下文
+     * @param filterOptions  工具过滤选项 —— 启用后在 AI 调用之前程序化筛选工具
      */
-    runStream(userMessage: string, context?: ChatMessage[]): AsyncIterable<{
+    runStream(userMessage: string, context?: ChatMessage[], filterOptions?: ToolFilterOptions): AsyncIterable<{
         type: 'content' | 'tool_call' | 'tool_result' | 'done';
         data: any;
     }>;

package/lib/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EAGX,KAAK,EACN,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,EAAE,CAAC;IACtE,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IAC/D,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACnD,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,UAAU,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IAC1C,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,aAAa,CAAiD;gBAE1D,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAiBrD;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAW9E;;OAEG;IACH,OAAO,CAAC,IAAI;IAWZ;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI9B;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;YACW,eAAe;IAoB7B;;OAEG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAqK7E;;OAEG;IACI,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC;QAC5E,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;QACvD,IAAI,EAAE,GAAG,CAAC;KACX,CAAC;CA+HH;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,GAAG,KAAK,CAK9F"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}