@amical/aiagent-sdk 0.1.9 → 0.1.11

package/dist/index.d.mts

@@ -21,7 +21,8 @@ interface IAgentRuntime {
          * @param filePattern (可选) 文件名匹配模式，比如 '*.ts'
          * @returns 返回格式化后的包含上下文的搜索结果字符串
          */
-        searchFiles?(path: string, regex: string, filePattern?: string): Promise<string>;
+        searchFiles?(path: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
+        searchFileContent?(path: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
     };
     path: {
         join(...paths: string[]): string;
@@ -59,6 +60,7 @@ declare enum AgentDefaultTool {
     FILE_DELETE = "agent_delete_file",
     DIR_DELETE = "agent_delete_directory",
     SEARCH = "agent_search_files",
+    SEARCH_CONTENT = "agent_search_file_content",
     LIST_FILES = "agent_list_files",
     LIST_CODE_DEF = "agent_list_code_definition_names",
     BROWSER = "agent_browser_action",
@@ -137,11 +139,21 @@ declare const defaultTools: readonly [{
     };
 }, {
     readonly name: AgentDefaultTool.SEARCH;
-    readonly description: "Search for files in a directory that match a regex pattern or glob pattern.";
+    readonly description: "Search for files or directories by name in a directory tree, matching the name against a regex (and optionally a glob). Directories are traversed level by level: all matches in the current level are returned before descending into deeper levels. Use this tool only to locate files/directories by name.";
     readonly params: {
         readonly path: "(required) The absolute or relative directory path to search.";
-        readonly regex: "(required) The regex pattern to match files against.";
+        readonly regex: "(required) The regex pattern to match file or directory names against.";
         readonly file_pattern: "(optional) glob pattern like *.ts.";
+        readonly include_node_modules: "(optional) set to true to include node_modules in the search. Defaults to false, so node_modules is skipped.";
+    };
+}, {
+    readonly name: AgentDefaultTool.SEARCH_CONTENT;
+    readonly description: "Search the contents of files in a directory tree for a regex pattern. Use this tool when you need to find text or code inside files rather than matching file or directory names.";
+    readonly params: {
+        readonly path: "(required) The absolute or relative directory path to search.";
+        readonly regex: "(required) The regex pattern to match file content against.";
+        readonly file_pattern: "(optional) glob pattern like *.ts to limit which files are searched.";
+        readonly include_node_modules: "(optional) set to true to include node_modules in the search. Defaults to false, so node_modules is skipped.";
     };
 }, {
     readonly name: AgentDefaultTool.LIST_FILES;
@@ -166,7 +178,44 @@ declare const defaultTools: readonly [{
 declare const toolUseNames: AgentDefaultTool[];
 declare function setDynamicToolUseNames(namespace: string, names: string[]): void;
 declare function getToolUseNames(): string[];
-declare const READ_ONLY_TOOLS: readonly [AgentDefaultTool.LIST_FILES, AgentDefaultTool.FILE_READ, AgentDefaultTool.SEARCH, AgentDefaultTool.LIST_CODE_DEF, AgentDefaultTool.BROWSER, AgentDefaultTool.ASK, AgentDefaultTool.WEB_SEARCH, AgentDefaultTool.WEB_FETCH, AgentDefaultTool.LOAD_SKILL, AgentDefaultTool.USE_SUBAGENTS];
+declare const READ_ONLY_TOOLS: readonly [AgentDefaultTool.LIST_FILES, AgentDefaultTool.FILE_READ, AgentDefaultTool.SEARCH, AgentDefaultTool.SEARCH_CONTENT, AgentDefaultTool.LIST_CODE_DEF, AgentDefaultTool.BROWSER, AgentDefaultTool.ASK, AgentDefaultTool.WEB_SEARCH, AgentDefaultTool.WEB_FETCH, AgentDefaultTool.LOAD_SKILL, AgentDefaultTool.USE_SUBAGENTS];
+
+/**
+ * 自定义工具的数据结构与渲染辅助函数。
+ *
+ * 自定义工具支持“工具集（tool group）”结构：
+ * - 顶层只展示工具集入口（name/description/params），避免系统提示词臃肿。
+ * - 当 Agent 调用某个工具集入口时，才把该集合的 children 注册为可用工具，
+ *   并将其 prompt 描述作为工具调用结果返回给模型。
+ */
+interface CustomToolDefinition {
+    name: string;
+    description: string;
+    params?: Record<string, string>;
+    onCall?: (params: Record<string, any>) => Promise<any> | any;
+    /**
+     * 子工具。存在时表示该工具为“工具集入口”，初始不展开 children。
+     */
+    children?: CustomToolDefinition[];
+}
+/**
+ * 判断一个自定义工具是否为工具集入口。
+ */
+declare function isCustomToolGroup(tool: CustomToolDefinition): boolean;
+/**
+ * 递归收集所有自定义工具名（含嵌套 children），用于全局唯一性校验。
+ */
+declare function collectCustomToolNames(tools: CustomToolDefinition[]): string[];
+/**
+ * 将单个工具定义渲染为系统提示词中的工具说明块。
+ *
+ * 注意：该函数只渲染工具自身的 name/description/params，不会展开 children。
+ */
+declare function renderCustomToolPrompt(tool: CustomToolDefinition, cwd?: string): string;
+/**
+ * 批量渲染工具说明。
+ */
+declare function renderCustomToolsPrompt(tools: CustomToolDefinition[], cwd?: string): string;
 
 /**
  * @description **Version 2**
@@ -198,7 +247,7 @@ interface TextStreamContent {
     content: string;
     partial: boolean;
 }
-declare const toolParamNames: readonly ["command", "requires_approval", "path", "absolutePath", "content", "diff", "regex", "file_pattern", "recursive", "action", "url", "coordinate", "text", "query", "allowed_domains", "blocked_domains", "prompt", "server_name", "tool_name", "arguments", "uri", "question", "options", "response", "result", "context", "title", "what_happened", "steps_to_reproduce", "api_request_output", "additional_context", "needs_more_exploration", "task_progress", "timeout", "input", "from_ref", "to_ref", "skill_name", "prompt_1", "prompt_2", "prompt_3", "prompt_4", "prompt_5", "start_line", "end_line"];
+declare const toolParamNames: readonly ["command", "requires_approval", "path", "absolutePath", "content", "diff", "regex", "file_pattern", "include_node_modules", "recursive", "action", "url", "coordinate", "text", "query", "allowed_domains", "blocked_domains", "prompt", "server_name", "tool_name", "arguments", "uri", "question", "options", "response", "result", "context", "title", "what_happened", "steps_to_reproduce", "api_request_output", "additional_context", "needs_more_exploration", "task_progress", "timeout", "input", "from_ref", "to_ref", "skill_name", "prompt_1", "prompt_2", "prompt_3", "prompt_4", "prompt_5", "start_line", "end_line"];
 type ToolParamName = (typeof toolParamNames)[number];
 interface ToolUse {
     type: "tool_use";
@@ -405,7 +454,7 @@ interface AgentOptions {
     promptManager: IPromptManager;
     memory: IMemoryManager;
     mcp?: IMcpManager;
-    customTools?: any[];
+    customTools?: CustomToolDefinition[];
     allowDefaultTools?: string[];
     customInstructions?: string;
     /** 最大循环次数，默认150 */
@@ -439,10 +488,20 @@ declare class ClineAgent {
     private maxLoopCount;
     skillDir: string;
     rulesDir: string;
-    customTools: any[];
+    customTools: CustomToolDefinition[];
+    /** 当前可用（已展开集合）的顶层工具列表，传给 PromptManager 渲染 */
+    activeCustomTools: CustomToolDefinition[];
+    /** 所有已知工具名（含未激活 children），便于查找定义 */
+    customToolsByName: Map<string, CustomToolDefinition>;
     customToolNames: Set<string>;
     allowDefaultTools?: string[];
     customInstructions?: string;
+    /** 已激活的工具集入口名 */
+    private activatedGroups;
+    /** activeCustomTools 变更版本号，用于 Prompt 缓存失效 */
+    private activeToolsVersion;
+    /** 缓存 sysPrompt 时记录的版本号 */
+    private promptActiveToolsVersion;
     sysPrompt?: string;
     noUseTollSysPrompt?: string;
     onStateChange?: (state: AgentState) => void;
@@ -474,6 +533,14 @@ declare class ClineAgent {
      * 核心任务循环
      */
     private loop;
+    /**
+     * 激活自定义工具集：将入口的 children 注册到活跃工具列表并返回渲染后的 prompt。
+     */
+    private activateCustomToolGroup;
+    /**
+     * 检查自上次获取 prompt 后是否有工具集被激活，若有则刷新缓存。
+     */
+    private getCurrentPrompt;
     /**
      * 简单的 Diff 解析与替换辅助方法
      */
@@ -484,9 +551,21 @@ declare class ClineAgent {
     resume(userInput?: string): Promise<void>;
     appendHistory(history: AgentMessage[]): Promise<void>;
     getHistory(): Promise<AgentMessage[]>;
-    searchFiles(dirpath: string, regex: string, filePattern?: string): Promise<string>;
+    /**
+     * 判断文件是否为可进行内容搜索的文本类文件
+     */
+    private isTextFile;
+    /**
+     * 按文件名/目录名搜索，层级优先（BFS）：
+     * 每一层先匹配完当前层级的所有条目，再进入更深的子目录。
+     */
+    searchFiles(dirpath: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
+    /**
+     * 按文件内容搜索：正则匹配文件内容，返回匹配文件路径。
+     */
+    searchFileContent(dirpath: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
 }
 
 declare const VERSION = "0.1.0";
 
-export { AgentDefaultTool, type AgentMessage, type AgentOptions, AgentState, type ApiProviderInfo, type ApiStreamChunk, type AssistantMessageContent, ClineAgent, type IAgentRuntime, type IApiHandler, type IMcpManager, type IMemoryManager, type IPromptManager, type McpServerInfo, type McpTool, type McpToolCallResult, READ_ONLY_TOOLS, type ReasoningStreamContent, TOOL_RESULT_BLOCK, type TextStreamContent, type ToolParamName, type ToolUse, VERSION, defaultTools, getToolUseNames, parseAssistantMessageV2, setDynamicToolUseNames, toolParamNames, toolUseNames };
+export { AgentDefaultTool, type AgentMessage, type AgentOptions, AgentState, type ApiProviderInfo, type ApiStreamChunk, type AssistantMessageContent, ClineAgent, type CustomToolDefinition, type IAgentRuntime, type IApiHandler, type IMcpManager, type IMemoryManager, type IPromptManager, type McpServerInfo, type McpTool, type McpToolCallResult, READ_ONLY_TOOLS, type ReasoningStreamContent, TOOL_RESULT_BLOCK, type TextStreamContent, type ToolParamName, type ToolUse, VERSION, collectCustomToolNames, defaultTools, getToolUseNames, isCustomToolGroup, parseAssistantMessageV2, renderCustomToolPrompt, renderCustomToolsPrompt, setDynamicToolUseNames, toolParamNames, toolUseNames };

package/dist/index.d.ts

@@ -21,7 +21,8 @@ interface IAgentRuntime {
          * @param filePattern (可选) 文件名匹配模式，比如 '*.ts'
          * @returns 返回格式化后的包含上下文的搜索结果字符串
          */
-        searchFiles?(path: string, regex: string, filePattern?: string): Promise<string>;
+        searchFiles?(path: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
+        searchFileContent?(path: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
     };
     path: {
         join(...paths: string[]): string;
@@ -59,6 +60,7 @@ declare enum AgentDefaultTool {
     FILE_DELETE = "agent_delete_file",
     DIR_DELETE = "agent_delete_directory",
     SEARCH = "agent_search_files",
+    SEARCH_CONTENT = "agent_search_file_content",
     LIST_FILES = "agent_list_files",
     LIST_CODE_DEF = "agent_list_code_definition_names",
     BROWSER = "agent_browser_action",
@@ -137,11 +139,21 @@ declare const defaultTools: readonly [{
     };
 }, {
     readonly name: AgentDefaultTool.SEARCH;
-    readonly description: "Search for files in a directory that match a regex pattern or glob pattern.";
+    readonly description: "Search for files or directories by name in a directory tree, matching the name against a regex (and optionally a glob). Directories are traversed level by level: all matches in the current level are returned before descending into deeper levels. Use this tool only to locate files/directories by name.";
     readonly params: {
         readonly path: "(required) The absolute or relative directory path to search.";
-        readonly regex: "(required) The regex pattern to match files against.";
+        readonly regex: "(required) The regex pattern to match file or directory names against.";
         readonly file_pattern: "(optional) glob pattern like *.ts.";
+        readonly include_node_modules: "(optional) set to true to include node_modules in the search. Defaults to false, so node_modules is skipped.";
+    };
+}, {
+    readonly name: AgentDefaultTool.SEARCH_CONTENT;
+    readonly description: "Search the contents of files in a directory tree for a regex pattern. Use this tool when you need to find text or code inside files rather than matching file or directory names.";
+    readonly params: {
+        readonly path: "(required) The absolute or relative directory path to search.";
+        readonly regex: "(required) The regex pattern to match file content against.";
+        readonly file_pattern: "(optional) glob pattern like *.ts to limit which files are searched.";
+        readonly include_node_modules: "(optional) set to true to include node_modules in the search. Defaults to false, so node_modules is skipped.";
     };
 }, {
     readonly name: AgentDefaultTool.LIST_FILES;
@@ -166,7 +178,44 @@ declare const defaultTools: readonly [{
 declare const toolUseNames: AgentDefaultTool[];
 declare function setDynamicToolUseNames(namespace: string, names: string[]): void;
 declare function getToolUseNames(): string[];
-declare const READ_ONLY_TOOLS: readonly [AgentDefaultTool.LIST_FILES, AgentDefaultTool.FILE_READ, AgentDefaultTool.SEARCH, AgentDefaultTool.LIST_CODE_DEF, AgentDefaultTool.BROWSER, AgentDefaultTool.ASK, AgentDefaultTool.WEB_SEARCH, AgentDefaultTool.WEB_FETCH, AgentDefaultTool.LOAD_SKILL, AgentDefaultTool.USE_SUBAGENTS];
+declare const READ_ONLY_TOOLS: readonly [AgentDefaultTool.LIST_FILES, AgentDefaultTool.FILE_READ, AgentDefaultTool.SEARCH, AgentDefaultTool.SEARCH_CONTENT, AgentDefaultTool.LIST_CODE_DEF, AgentDefaultTool.BROWSER, AgentDefaultTool.ASK, AgentDefaultTool.WEB_SEARCH, AgentDefaultTool.WEB_FETCH, AgentDefaultTool.LOAD_SKILL, AgentDefaultTool.USE_SUBAGENTS];
+
+/**
+ * 自定义工具的数据结构与渲染辅助函数。
+ *
+ * 自定义工具支持“工具集（tool group）”结构：
+ * - 顶层只展示工具集入口（name/description/params），避免系统提示词臃肿。
+ * - 当 Agent 调用某个工具集入口时，才把该集合的 children 注册为可用工具，
+ *   并将其 prompt 描述作为工具调用结果返回给模型。
+ */
+interface CustomToolDefinition {
+    name: string;
+    description: string;
+    params?: Record<string, string>;
+    onCall?: (params: Record<string, any>) => Promise<any> | any;
+    /**
+     * 子工具。存在时表示该工具为“工具集入口”，初始不展开 children。
+     */
+    children?: CustomToolDefinition[];
+}
+/**
+ * 判断一个自定义工具是否为工具集入口。
+ */
+declare function isCustomToolGroup(tool: CustomToolDefinition): boolean;
+/**
+ * 递归收集所有自定义工具名（含嵌套 children），用于全局唯一性校验。
+ */
+declare function collectCustomToolNames(tools: CustomToolDefinition[]): string[];
+/**
+ * 将单个工具定义渲染为系统提示词中的工具说明块。
+ *
+ * 注意：该函数只渲染工具自身的 name/description/params，不会展开 children。
+ */
+declare function renderCustomToolPrompt(tool: CustomToolDefinition, cwd?: string): string;
+/**
+ * 批量渲染工具说明。
+ */
+declare function renderCustomToolsPrompt(tools: CustomToolDefinition[], cwd?: string): string;
 
 /**
  * @description **Version 2**
@@ -198,7 +247,7 @@ interface TextStreamContent {
     content: string;
     partial: boolean;
 }
-declare const toolParamNames: readonly ["command", "requires_approval", "path", "absolutePath", "content", "diff", "regex", "file_pattern", "recursive", "action", "url", "coordinate", "text", "query", "allowed_domains", "blocked_domains", "prompt", "server_name", "tool_name", "arguments", "uri", "question", "options", "response", "result", "context", "title", "what_happened", "steps_to_reproduce", "api_request_output", "additional_context", "needs_more_exploration", "task_progress", "timeout", "input", "from_ref", "to_ref", "skill_name", "prompt_1", "prompt_2", "prompt_3", "prompt_4", "prompt_5", "start_line", "end_line"];
+declare const toolParamNames: readonly ["command", "requires_approval", "path", "absolutePath", "content", "diff", "regex", "file_pattern", "include_node_modules", "recursive", "action", "url", "coordinate", "text", "query", "allowed_domains", "blocked_domains", "prompt", "server_name", "tool_name", "arguments", "uri", "question", "options", "response", "result", "context", "title", "what_happened", "steps_to_reproduce", "api_request_output", "additional_context", "needs_more_exploration", "task_progress", "timeout", "input", "from_ref", "to_ref", "skill_name", "prompt_1", "prompt_2", "prompt_3", "prompt_4", "prompt_5", "start_line", "end_line"];
 type ToolParamName = (typeof toolParamNames)[number];
 interface ToolUse {
     type: "tool_use";
@@ -405,7 +454,7 @@ interface AgentOptions {
     promptManager: IPromptManager;
     memory: IMemoryManager;
     mcp?: IMcpManager;
-    customTools?: any[];
+    customTools?: CustomToolDefinition[];
     allowDefaultTools?: string[];
     customInstructions?: string;
     /** 最大循环次数，默认150 */
@@ -439,10 +488,20 @@ declare class ClineAgent {
     private maxLoopCount;
     skillDir: string;
     rulesDir: string;
-    customTools: any[];
+    customTools: CustomToolDefinition[];
+    /** 当前可用（已展开集合）的顶层工具列表，传给 PromptManager 渲染 */
+    activeCustomTools: CustomToolDefinition[];
+    /** 所有已知工具名（含未激活 children），便于查找定义 */
+    customToolsByName: Map<string, CustomToolDefinition>;
     customToolNames: Set<string>;
     allowDefaultTools?: string[];
     customInstructions?: string;
+    /** 已激活的工具集入口名 */
+    private activatedGroups;
+    /** activeCustomTools 变更版本号，用于 Prompt 缓存失效 */
+    private activeToolsVersion;
+    /** 缓存 sysPrompt 时记录的版本号 */
+    private promptActiveToolsVersion;
     sysPrompt?: string;
     noUseTollSysPrompt?: string;
     onStateChange?: (state: AgentState) => void;
@@ -474,6 +533,14 @@ declare class ClineAgent {
      * 核心任务循环
      */
     private loop;
+    /**
+     * 激活自定义工具集：将入口的 children 注册到活跃工具列表并返回渲染后的 prompt。
+     */
+    private activateCustomToolGroup;
+    /**
+     * 检查自上次获取 prompt 后是否有工具集被激活，若有则刷新缓存。
+     */
+    private getCurrentPrompt;
     /**
      * 简单的 Diff 解析与替换辅助方法
      */
@@ -484,9 +551,21 @@ declare class ClineAgent {
     resume(userInput?: string): Promise<void>;
     appendHistory(history: AgentMessage[]): Promise<void>;
     getHistory(): Promise<AgentMessage[]>;
-    searchFiles(dirpath: string, regex: string, filePattern?: string): Promise<string>;
+    /**
+     * 判断文件是否为可进行内容搜索的文本类文件
+     */
+    private isTextFile;
+    /**
+     * 按文件名/目录名搜索，层级优先（BFS）：
+     * 每一层先匹配完当前层级的所有条目，再进入更深的子目录。
+     */
+    searchFiles(dirpath: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
+    /**
+     * 按文件内容搜索：正则匹配文件内容，返回匹配文件路径。
+     */
+    searchFileContent(dirpath: string, regex: string, filePattern?: string, includeNodeModules?: boolean): Promise<string>;
 }
 
 declare const VERSION = "0.1.0";
 
-export { AgentDefaultTool, type AgentMessage, type AgentOptions, AgentState, type ApiProviderInfo, type ApiStreamChunk, type AssistantMessageContent, ClineAgent, type IAgentRuntime, type IApiHandler, type IMcpManager, type IMemoryManager, type IPromptManager, type McpServerInfo, type McpTool, type McpToolCallResult, READ_ONLY_TOOLS, type ReasoningStreamContent, TOOL_RESULT_BLOCK, type TextStreamContent, type ToolParamName, type ToolUse, VERSION, defaultTools, getToolUseNames, parseAssistantMessageV2, setDynamicToolUseNames, toolParamNames, toolUseNames };
+export { AgentDefaultTool, type AgentMessage, type AgentOptions, AgentState, type ApiProviderInfo, type ApiStreamChunk, type AssistantMessageContent, ClineAgent, type CustomToolDefinition, type IAgentRuntime, type IApiHandler, type IMcpManager, type IMemoryManager, type IPromptManager, type McpServerInfo, type McpTool, type McpToolCallResult, READ_ONLY_TOOLS, type ReasoningStreamContent, TOOL_RESULT_BLOCK, type TextStreamContent, type ToolParamName, type ToolUse, VERSION, collectCustomToolNames, defaultTools, getToolUseNames, isCustomToolGroup, parseAssistantMessageV2, renderCustomToolPrompt, renderCustomToolsPrompt, setDynamicToolUseNames, toolParamNames, toolUseNames };