@zhin.js/agent 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/agent.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @zhin.js/agent - Agent System
+ * AI Agent 实现，支持工具调用和多轮对话
+ */
+import type { AIProvider, AgentConfig, AgentTool, AgentResult, ChatMessage, ToolFilterOptions, Usage } from '@zhin.js/core';
+/**
+ * 根据工具名和参数生成简短标题（用于日志、TOOLS.md 等）
+ */
+export declare function formatToolTitle(name: string, args?: Record<string, any>): string;
+/**
+ * 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（规范化参数以避免 "" vs "{}" 等差异）
+     */
+    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/agent.d.ts.map

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