@amical/aiagent-sdk 0.1.10 → 0.1.12

package/dist/{WebMemoryManager-DXxLUDBB.d.ts → WebMemoryManager-BZNjinHF.d.ts}

@@ -2,16 +2,16 @@ import { IMemoryManager, AgentMessage } from './index.js';
 
 /**
  * Web 端 MemoryManager 实现
- * 使用 IndexedDB (通过封装) 或 LocalStorage / SessionStorage 来持久化对话历史。
- * 此处提供一个基于 SessionStorage / 内存 回退的轻量实现。
+ * 使用 SessionStorage / 内存 回退来持久化对话历史。
  */
 declare class WebMemoryManager implements IMemoryManager {
     private storageKey;
     private maxMessages;
     private inMemoryFallback;
+    onCondense?: () => void | Promise<void>;
     /**
      * @param storageKey SessionStorage 中的键名
-     * @param maxMessages 保留的最大消息数量，用于简单的历史截断（默认 150）
+     * @param maxMessages 保留的最大消息数量，用于简单的历史截断（默认 200）
      */
     constructor(storageKey?: string, maxMessages?: number);
     private isStorageAvailable;
@@ -19,6 +19,13 @@ declare class WebMemoryManager implements IMemoryManager {
     private writeMessages;
     getHistory(): Promise<AgentMessage[]>;
     appendMessage(message: AgentMessage): Promise<void>;
+    /**
+     * 压缩历史：
+     * - system 消息保持不变
+     * - 以 agent_attempt_completion 为边界切分完整对话，仅合并“后面还有其他完整对话”的旧完整对话
+     * - 其余需要压缩的场景下，对前半段工具调用结果标记为“结果已过期”
+     * - 同时触发 onCondense 回调（宿主可据此清空 dify conversationId 新开窗口）
+     */
     condenseHistory(): Promise<void>;
     clear(): Promise<void>;
 }

package/dist/{WebMemoryManager-Bk19j8i6.d.mts → WebMemoryManager-DpaY-f0l.d.mts}

@@ -2,16 +2,16 @@ import { IMemoryManager, AgentMessage } from './index.mjs';
 
 /**
  * Web 端 MemoryManager 实现
- * 使用 IndexedDB (通过封装) 或 LocalStorage / SessionStorage 来持久化对话历史。
- * 此处提供一个基于 SessionStorage / 内存 回退的轻量实现。
+ * 使用 SessionStorage / 内存 回退来持久化对话历史。
  */
 declare class WebMemoryManager implements IMemoryManager {
     private storageKey;
     private maxMessages;
     private inMemoryFallback;
+    onCondense?: () => void | Promise<void>;
     /**
      * @param storageKey SessionStorage 中的键名
-     * @param maxMessages 保留的最大消息数量，用于简单的历史截断（默认 150）
+     * @param maxMessages 保留的最大消息数量，用于简单的历史截断（默认 200）
      */
     constructor(storageKey?: string, maxMessages?: number);
     private isStorageAvailable;
@@ -19,6 +19,13 @@ declare class WebMemoryManager implements IMemoryManager {
     private writeMessages;
     getHistory(): Promise<AgentMessage[]>;
     appendMessage(message: AgentMessage): Promise<void>;
+    /**
+     * 压缩历史：
+     * - system 消息保持不变
+     * - 以 agent_attempt_completion 为边界切分完整对话，仅合并“后面还有其他完整对话”的旧完整对话
+     * - 其余需要压缩的场景下，对前半段工具调用结果标记为“结果已过期”
+     * - 同时触发 onCondense 回调（宿主可据此清空 dify conversationId 新开窗口）
+     */
     condenseHistory(): Promise<void>;
     clear(): Promise<void>;
 }

package/dist/index.d.mts

@@ -113,9 +113,11 @@ declare const defaultTools: readonly [{
     readonly example: "## Example: Requesting to make targeted edits to a file\n\n<agent_replace_in_file>\n<path>src/components/App.tsx</path>\n<diff>\n------- SEARCH\nimport React from 'react';\n=======\nimport React, { useState } from 'react';\n+++++++ REPLACE\n\n------- SEARCH\nfunction handleSubmit() {\n  saveData();\n  setLoading(false);\n}\n\n=======\n+++++++ REPLACE\n\n------- SEARCH\nreturn (\n  <div>\n=======\nfunction handleSubmit() {\n  saveData();\n  setLoading(false);\n}\n\nreturn (\n  <div>\n+++++++ REPLACE\n</diff>\n<task_progress>\n- [x] Set up project structure\n- [x] Install dependencies\n- [ ] Create components\n- [ ] Test application\n</task_progress>\n</agent_replace_in_file>";
 }, {
     readonly name: AgentDefaultTool.FILE_READ;
-    readonly description: "Read the contents of a specific file.";
+    readonly description: "Read the contents of a specific file. The returned content includes line numbers (e.g. '10|const x = 1;') so you can reference exact lines when editing.";
     readonly params: {
         readonly path: "(required) The absolute or relative file path to read.";
+        readonly start_line: "(optional) The 1-based line number to start reading from (inclusive). Defaults to 1.";
+        readonly end_line: "(optional) The 1-based line number to stop reading at (inclusive). Defaults to the last line.";
     };
 }, {
     readonly name: AgentDefaultTool.FILE_NEW;
@@ -180,6 +182,43 @@ declare function setDynamicToolUseNames(namespace: string, names: string[]): voi
 declare function getToolUseNames(): string[];
 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**
  * Parses an assistant message string potentially containing mixed text and tool usage blocks
@@ -313,6 +352,10 @@ interface IMemoryManager {
      * 截断或压缩过长历史
      */
     condenseHistory?(): Promise<void>;
+    /**
+     * 当历史被压缩时触发（宿主可在此处理例如 dify provider 清空 conversationId 等逻辑）
+     */
+    onCondense?: () => void | Promise<void>;
     /**
      * 清空记忆
      */
@@ -352,6 +395,7 @@ interface IApiHandler {
      * 获取当前配置的模型信息
      */
     getModelInfo(): ApiProviderInfo;
+    clearConversationId(): void;
 }
 
 /**
@@ -417,7 +461,7 @@ interface AgentOptions {
     promptManager: IPromptManager;
     memory: IMemoryManager;
     mcp?: IMcpManager;
-    customTools?: any[];
+    customTools?: CustomToolDefinition[];
     allowDefaultTools?: string[];
     customInstructions?: string;
     /** 最大循环次数，默认150 */
@@ -451,10 +495,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;
@@ -486,6 +540,19 @@ declare class ClineAgent {
      * 核心任务循环
      */
     private loop;
+    /**
+     * 激活自定义工具集：将入口的 children 注册到活跃工具列表并返回渲染后的 prompt。
+     */
+    private activateCustomToolGroup;
+    /**
+     * 检查自上次获取 prompt 后是否有工具集被激活，若有则刷新缓存。
+     */
+    private getCurrentPrompt;
+    /**
+     * 将文件内容格式化为带行号文本（模拟编辑器行号显示），
+     * 支持通过 start_line / end_line 截取读取范围。
+     */
+    private formatFileContentWithLineNumbers;
     /**
      * 简单的 Diff 解析与替换辅助方法
      */
@@ -513,4 +580,4 @@ declare class ClineAgent {
 
 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

@@ -113,9 +113,11 @@ declare const defaultTools: readonly [{
     readonly example: "## Example: Requesting to make targeted edits to a file\n\n<agent_replace_in_file>\n<path>src/components/App.tsx</path>\n<diff>\n------- SEARCH\nimport React from 'react';\n=======\nimport React, { useState } from 'react';\n+++++++ REPLACE\n\n------- SEARCH\nfunction handleSubmit() {\n  saveData();\n  setLoading(false);\n}\n\n=======\n+++++++ REPLACE\n\n------- SEARCH\nreturn (\n  <div>\n=======\nfunction handleSubmit() {\n  saveData();\n  setLoading(false);\n}\n\nreturn (\n  <div>\n+++++++ REPLACE\n</diff>\n<task_progress>\n- [x] Set up project structure\n- [x] Install dependencies\n- [ ] Create components\n- [ ] Test application\n</task_progress>\n</agent_replace_in_file>";
 }, {
     readonly name: AgentDefaultTool.FILE_READ;
-    readonly description: "Read the contents of a specific file.";
+    readonly description: "Read the contents of a specific file. The returned content includes line numbers (e.g. '10|const x = 1;') so you can reference exact lines when editing.";
     readonly params: {
         readonly path: "(required) The absolute or relative file path to read.";
+        readonly start_line: "(optional) The 1-based line number to start reading from (inclusive). Defaults to 1.";
+        readonly end_line: "(optional) The 1-based line number to stop reading at (inclusive). Defaults to the last line.";
     };
 }, {
     readonly name: AgentDefaultTool.FILE_NEW;
@@ -180,6 +182,43 @@ declare function setDynamicToolUseNames(namespace: string, names: string[]): voi
 declare function getToolUseNames(): string[];
 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**
  * Parses an assistant message string potentially containing mixed text and tool usage blocks
@@ -313,6 +352,10 @@ interface IMemoryManager {
      * 截断或压缩过长历史
      */
     condenseHistory?(): Promise<void>;
+    /**
+     * 当历史被压缩时触发（宿主可在此处理例如 dify provider 清空 conversationId 等逻辑）
+     */
+    onCondense?: () => void | Promise<void>;
     /**
      * 清空记忆
      */
@@ -352,6 +395,7 @@ interface IApiHandler {
      * 获取当前配置的模型信息
      */
     getModelInfo(): ApiProviderInfo;
+    clearConversationId(): void;
 }
 
 /**
@@ -417,7 +461,7 @@ interface AgentOptions {
     promptManager: IPromptManager;
     memory: IMemoryManager;
     mcp?: IMcpManager;
-    customTools?: any[];
+    customTools?: CustomToolDefinition[];
     allowDefaultTools?: string[];
     customInstructions?: string;
     /** 最大循环次数，默认150 */
@@ -451,10 +495,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;
@@ -486,6 +540,19 @@ declare class ClineAgent {
      * 核心任务循环
      */
     private loop;
+    /**
+     * 激活自定义工具集：将入口的 children 注册到活跃工具列表并返回渲染后的 prompt。
+     */
+    private activateCustomToolGroup;
+    /**
+     * 检查自上次获取 prompt 后是否有工具集被激活，若有则刷新缓存。
+     */
+    private getCurrentPrompt;
+    /**
+     * 将文件内容格式化为带行号文本（模拟编辑器行号显示），
+     * 支持通过 start_line / end_line 截取读取范围。
+     */
+    private formatFileContentWithLineNumbers;
     /**
      * 简单的 Diff 解析与替换辅助方法
      */
@@ -513,4 +580,4 @@ declare class ClineAgent {
 
 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 };