jarvis-ai-assistant 0.1.222__py3-none-any.whl → 0.7.0__py3-none-any.whl

jarvis/jarvis_tools/registry.py

@@ -7,17 +7,17 @@ import tempfile
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Protocol, Tuple
 
-import yaml
+import yaml  # type: ignore[import-untyped]
 
 from jarvis.jarvis_mcp import McpClient
 from jarvis.jarvis_mcp.sse_mcp_client import SSEMcpClient
 from jarvis.jarvis_mcp.stdio_mcp_client import StdioMcpClient
 from jarvis.jarvis_mcp.streamable_mcp_client import StreamableMcpClient
 from jarvis.jarvis_tools.base import Tool
-from jarvis.jarvis_utils.config import get_data_dir
+from jarvis.jarvis_utils.config import get_data_dir, get_tool_load_dirs
 from jarvis.jarvis_utils.output import OutputType, PrettyOutput
 from jarvis.jarvis_utils.tag import ct, ot
-from jarvis.jarvis_utils.utils import is_context_overflow
+from jarvis.jarvis_utils.utils import is_context_overflow, daily_check_git_updates
 
 tool_call_help = f"""
 <tool_system_guide>
@@ -31,6 +31,7 @@ tool_call_help = f"""
 {ot("TOOL_CALL")}
 want: 想要从执行结果中获取到的信息，如果工具输出内容过长，会根据此字段尝试提取有效信息
 name: 工具名称
+
 arguments:
   param1: 值1
   param2: 值2
@@ -50,6 +51,7 @@ arguments:
 - 完全按照上述格式
 - 使用正确的YAML格式，2个空格作为缩进
 - 包含所有必需参数
+- {ot("TOOL_CALL")} 和 {ct("TOOL_CALL")} 必须出现在行首
 </rule>
 
 <rule>
@@ -71,14 +73,15 @@ arguments:
 
 <string_format>
 # 📝 字符串参数格式
-始终使用 |2 语法表示字符串参数，防止多行字符串行首空格引起歧义：
+使用 |2 语法表示字符串参数，防止多行字符串行首空格引起歧义。
 
 {ot("TOOL_CALL")}
 want: 当前的git状态，期望获取xxx的提交记录
 name: execute_script
+
 arguments:
   interpreter: bash
-  script_cotent: |2
+  script_content: |
     git status --porcelain
 {ct("TOOL_CALL")}
 </string_format>
@@ -95,11 +98,11 @@ arguments:
 <common_errors>
 # ⚠️ 常见错误
 - 同时调用多个工具
-- 字符串参数缺少 |2
 - 假设工具结果
 - 创建虚构对话
 - 在没有所需信息的情况下继续
 - yaml 格式错误
+- {ot("TOOL_CALL")} 和 {ct("TOOL_CALL")} 没有出现在行首
 </common_errors>
 </tool_system_guide>
 """
@@ -107,18 +110,21 @@ arguments:
 
 class OutputHandlerProtocol(Protocol):
     def name(self) -> str: ...
+
     def can_handle(self, response: str) -> bool: ...
+
     def prompt(self) -> str: ...
+
     def handle(self, response: str, agent: Any) -> Tuple[bool, Any]: ...
 
 
 class ToolRegistry(OutputHandlerProtocol):
-
     def name(self) -> str:
         return "TOOL_CALL"
 
     def can_handle(self, response: str) -> bool:
-        return ToolRegistry._has_tool_calls_block(response)
+        # 仅当 {ot("TOOL_CALL")} 出现在行首时才认为可以处理
+        return re.search(rf'(?m){re.escape(ot("TOOL_CALL"))}', response) is not None
 
     def prompt(self) -> str:
         """加载工具"""
@@ -165,11 +171,33 @@ class ToolRegistry(OutputHandlerProtocol):
             return tools_prompt
         return ""
 
-    def handle(self, response: str, agent: Any) -> Tuple[bool, Any]:
-        tool_call, err_msg = self._extract_tool_calls(response)
-        if err_msg:
-            return False, err_msg
-        return False, self.handle_tool_calls(tool_call, agent)
+    def handle(self, response: str, agent_: Any) -> Tuple[bool, Any]:
+        try:
+            tool_call, err_msg, auto_completed = self._extract_tool_calls(response)
+            if err_msg:
+                # 只要工具解析错误，追加工具使用帮助信息（相当于一次 <ToolUsage>）
+                try:
+                    from jarvis.jarvis_agent import Agent
+                    agent: Agent = agent_
+                    tool_usage = agent.get_tool_usage_prompt()
+                    return False, f"{err_msg}\n\n{tool_usage}"
+                except Exception:
+                    # 兼容处理：无法获取Agent或ToolUsage时，至少返回工具系统帮助信息
+                    return False, f"{err_msg}\n\n{tool_call_help}"
+            result = self.handle_tool_calls(tool_call, agent_)
+            if auto_completed:
+                # 如果自动补全了结束标签，在结果中添加说明信息
+                result = f"检测到工具调用缺少结束标签，已自动补全{ct('TOOL_CALL')}。请确保后续工具调用包含完整的开始和结束标签。\n\n{result}"
+            return False, result
+        except Exception as e:
+            PrettyOutput.print(f"工具调用处理失败: {str(e)}", OutputType.ERROR)
+            from jarvis.jarvis_agent import Agent
+
+            agent: Agent = agent_
+            return (
+                False,
+                f"工具调用处理失败: {str(e)}\n\n{agent.get_tool_usage_prompt()}",
+            )
 
     def __init__(self) -> None:
         """初始化工具注册表"""
@@ -178,30 +206,46 @@ class ToolRegistry(OutputHandlerProtocol):
         self._load_builtin_tools()
         self._load_external_tools()
         self._load_mcp_tools()
+        # 应用工具配置组过滤
+        self._apply_tool_config_filter()
 
     def _get_tool_stats(self) -> Dict[str, int]:
         """从数据目录获取工具调用统计"""
-        stats_file = Path(get_data_dir()) / "tool_stat.yaml"
-        if stats_file.exists():
-            try:
-                with open(stats_file, "r", encoding="utf-8") as f:
-                    return yaml.safe_load(f) or {}
-            except Exception as e:
-                PrettyOutput.print(
-                    f"加载工具调用统计失败: {str(e)}", OutputType.WARNING
-                )
-        return {}
+        from jarvis.jarvis_stats.stats import StatsManager
+        from datetime import datetime
+
+        # 获取所有工具的统计数据
+        tool_stats = {}
+        tools = self.get_all_tools()
+
+        # 获取所有历史数据（从很早的时间开始）
+        end_time = datetime.now()
+        start_time = datetime(2000, 1, 1)  # 使用一个足够早的时间
+
+        for tool in tools:
+            tool_name = tool["name"]
+            # 获取该工具的统计数据
+            stats_data = StatsManager.get_stats(
+                metric_name=tool_name,
+                start_time=start_time,
+                end_time=end_time,
+                tags={"group": "tool"},
+            )
+
+            # 计算总调用次数
+            if stats_data and "records" in stats_data:
+                total_count = sum(record["value"] for record in stats_data["records"])
+                tool_stats[tool_name] = int(total_count)
+            else:
+                tool_stats[tool_name] = 0
+
+        return tool_stats
 
     def _update_tool_stats(self, name: str) -> None:
         """更新工具调用统计"""
-        stats = self._get_tool_stats()
-        stats[name] = stats.get(name, 0) + 1
-        stats_file = Path(get_data_dir()) / "tool_stat.yaml"
-        try:
-            with open(stats_file, "w", encoding="utf-8") as f:
-                yaml.safe_dump(stats, f, allow_unicode=True)
-        except Exception as e:
-            PrettyOutput.print(f"保存工具调用统计失败: {str(e)}", OutputType.WARNING)
+        from jarvis.jarvis_stats.stats import StatsManager
+
+        StatsManager.increment(name, group="tool")
 
     def use_tools(self, name: List[str]) -> None:
         """使用指定工具
@@ -231,6 +275,35 @@ class ToolRegistry(OutputHandlerProtocol):
             name: tool for name, tool in self.tools.items() if name not in names
         }
 
+    def _apply_tool_config_filter(self) -> None:
+        """应用工具配置组的过滤规则"""
+        from jarvis.jarvis_utils.config import get_tool_use_list, get_tool_dont_use_list
+
+        use_list = get_tool_use_list()
+        dont_use_list = get_tool_dont_use_list()
+
+        # 如果配置了 use 列表，只保留列表中的工具
+        if use_list:
+            filtered_tools = {}
+            missing = []
+            for tool_name in use_list:
+                if tool_name in self.tools:
+                    filtered_tools[tool_name] = self.tools[tool_name]
+                else:
+                    missing.append(tool_name)
+            if missing:
+                PrettyOutput.print(
+                    "警告: 配置的工具不存在: " + ", ".join(f"'{name}'" for name in missing),
+                    OutputType.WARNING,
+                )
+            self.tools = filtered_tools
+
+        # 如果配置了 dont_use 列表，排除列表中的工具
+        if dont_use_list:
+            for tool_name in dont_use_list:
+                if tool_name in self.tools:
+                    del self.tools[tool_name]
+
     def _load_mcp_tools(self) -> None:
         """加载MCP工具，优先从配置获取，其次从目录扫描"""
         from jarvis.jarvis_utils.config import get_mcp_config
@@ -254,14 +327,15 @@ class ToolRegistry(OutputHandlerProtocol):
         )
 
         # 遍历目录中的所有.yaml文件
+        error_lines = []
         for file_path in mcp_tools_dir.glob("*.yaml"):
             try:
                 config = yaml.safe_load(open(file_path, "r", encoding="utf-8"))
                 self.register_mcp_tool_by_config(config)
             except Exception as e:
-                PrettyOutput.print(
-                    f"文件 {file_path} 加载失败: {str(e)}", OutputType.WARNING
-                )
+                error_lines.append(f"文件 {file_path} 加载失败: {str(e)}")
+        if error_lines:
+            PrettyOutput.print("\n".join(error_lines), OutputType.WARNING)
 
     def _load_builtin_tools(self) -> None:
         """从内置工具目录加载工具"""
@@ -276,18 +350,52 @@ class ToolRegistry(OutputHandlerProtocol):
             self.register_tool_by_file(str(file_path))
 
     def _load_external_tools(self) -> None:
-        """从jarvis_data/tools加载外部工具"""
-        external_tools_dir = Path(get_data_dir()) / "tools"
-        if not external_tools_dir.exists():
-            return
+        """从jarvis_data/tools和配置的目录加载外部工具"""
+        from jarvis.jarvis_utils.config import get_central_tool_repo
+
+        tool_dirs = [str(Path(get_data_dir()) / "tools")] + get_tool_load_dirs()
+
+        # 如果配置了中心工具仓库，将其添加到加载路径
+        central_repo = get_central_tool_repo()
+        if central_repo:
+            # 支持本地目录路径或Git仓库URL
+            expanded = os.path.expanduser(os.path.expandvars(central_repo))
+            if os.path.isdir(expanded):
+                # 直接使用本地目录（支持Git仓库的子目录）
+                tool_dirs.append(expanded)
+            else:
+                # 中心工具仓库存储在数据目录下的特定位置
+                central_repo_path = os.path.join(get_data_dir(), "central_tool_repo")
+                tool_dirs.append(central_repo_path)
 
-        # 遍历目录中的所有.py文件
-        for file_path in external_tools_dir.glob("*.py"):
-            # 跳过__init__.py
-            if file_path.name == "__init__.py":
+                # 确保中心工具仓库被克隆/更新
+                if not os.path.exists(central_repo_path):
+                    try:
+                        import subprocess
+
+                        subprocess.run(
+                            ["git", "clone", central_repo, central_repo_path], check=True
+                        )
+                    except Exception as e:
+                        PrettyOutput.print(
+                            f"克隆中心工具仓库失败: {str(e)}", OutputType.ERROR
+                        )
+
+        # --- 全局每日更新检查 ---
+        daily_check_git_updates(tool_dirs, "tools")
+
+        for tool_dir in tool_dirs:
+            p_tool_dir = Path(tool_dir)
+            if not p_tool_dir.exists() or not p_tool_dir.is_dir():
                 continue
 
-            self.register_tool_by_file(str(file_path))
+            # 遍历目录中的所有.py文件
+            for file_path in p_tool_dir.glob("*.py"):
+                # 跳过__init__.py
+                if file_path.name == "__init__.py":
+                    continue
+
+                self.register_tool_by_file(str(file_path))
 
     def register_mcp_tool_by_config(self, config: Dict[str, Any]) -> bool:
         """从配置字典加载并注册工具
@@ -307,10 +415,7 @@ class ToolRegistry(OutputHandlerProtocol):
 
             # 检查enable标志
             if not config.get("enable", True):
-                PrettyOutput.print(
-                    f"MCP配置{config.get('name', '')}已禁用(enable=false)，跳过注册",
-                    OutputType.INFO,
-                )
+
                 return False
 
             name = config.get("name", "mcp")
@@ -322,10 +427,7 @@ class ToolRegistry(OutputHandlerProtocol):
                     args.pop("agent", None)
                     args.pop("want", None)
                     ret = client.get_resource_list()
-                    PrettyOutput.print(
-                        f"MCP {name} 资源列表:\n{yaml.safe_dump(ret, allow_unicode=True)}",
-                        OutputType.TOOL,
-                    )
+
                     return {
                         "success": True,
                         "stdout": yaml.safe_dump(ret, allow_unicode=True),
@@ -346,10 +448,7 @@ class ToolRegistry(OutputHandlerProtocol):
                             "stderr": "缺少必需的uri参数",
                         }
                     ret = client.get_resource(args["uri"])
-                    PrettyOutput.print(
-                        f"MCP {name} 获取资源:\n{yaml.safe_dump(ret, allow_unicode=True)}",
-                        OutputType.TOOL,
-                    )
+
                     return ret
 
                 return execute
@@ -360,10 +459,7 @@ class ToolRegistry(OutputHandlerProtocol):
                     args.pop("agent", None)
                     args.pop("want", None)
                     ret = client.execute(tool_name, args)
-                    PrettyOutput.print(
-                        f"MCP {name} {tool_name} 执行结果:\n{yaml.safe_dump(ret, allow_unicode=True)}",
-                        OutputType.TOOL,
-                    )
+
                     return ret
 
                 return execute
@@ -396,12 +492,13 @@ class ToolRegistry(OutputHandlerProtocol):
                 return False
 
             # 创建MCP客户端
+            mcp_client: McpClient
             if config["type"] == "stdio":
-                mcp_client: McpClient = StdioMcpClient(config)
+                mcp_client = StdioMcpClient(config)
             elif config["type"] == "sse":
-                mcp_client: McpClient = SSEMcpClient(config)
+                mcp_client = SSEMcpClient(config)
             elif config["type"] == "streamable":
-                mcp_client: McpClient = StreamableMcpClient(config)
+                mcp_client = StreamableMcpClient(config)
             else:
                 raise ValueError(f"不支持的MCP客户端类型: {config['type']}")
 
@@ -491,7 +588,6 @@ class ToolRegistry(OutputHandlerProtocol):
                         and hasattr(item, "execute")
                         and item.name == module_name
                     ):
-
                         if hasattr(item, "check"):
                             if not item.check():
                                 continue
@@ -505,6 +601,9 @@ class ToolRegistry(OutputHandlerProtocol):
                             description=tool_instance.description,
                             parameters=tool_instance.parameters,
                             func=tool_instance.execute,
+                            protocol_version=getattr(
+                                tool_instance, "protocol_version", "1.0"
+                            ),
                         )
                         tool_found = True
                         break
@@ -526,29 +625,72 @@ class ToolRegistry(OutputHandlerProtocol):
 
     @staticmethod
     def _has_tool_calls_block(content: str) -> bool:
-        """从内容中提取工具调用块"""
-        return (
-            re.search(ot("TOOL_CALL") + r"(.*?)" + ct("TOOL_CALL"), content, re.DOTALL)
-            is not None
-        )
+        """从内容中提取工具调用块（仅匹配行首标签）"""
+        pattern = rf'(?ms){re.escape(ot("TOOL_CALL"))}(.*?)^{re.escape(ct("TOOL_CALL"))}'
+        return re.search(pattern, content) is not None
 
     @staticmethod
-    def _extract_tool_calls(content: str) -> Tuple[Dict[str, Dict[str, Any]], str]:
+    def _extract_tool_calls(
+        content: str,
+    ) -> Tuple[Dict[str, Dict[str, Any]], str, bool]:
         """从内容中提取工具调用。
 
         参数:
             content: 包含工具调用的内容
 
         返回:
-            List[Dict]: 包含名称和参数的提取工具调用列表
+            Tuple[Dict[str, Dict[str, Any]], str, bool]:
+                - 第一个元素是提取的工具调用字典
+                - 第二个元素是错误消息字符串(成功时为"")
+                - 第三个元素是是否自动补全了结束标签
 
         异常:
             Exception: 如果工具调用缺少必要字段
         """
+        # 如果</TOOL_CALL>出现在响应的末尾，但是前面没有换行符，自动插入一个换行符进行修复
+        if content.rstrip().endswith(ct("TOOL_CALL")):
+            pos = content.rfind(ct("TOOL_CALL"))
+            if pos > 0 and content[pos - 1] not in ("\n", "\r"):
+                content = content[:pos] + "\n" + content[pos:]
+
         # 将内容拆分为行
-        data = re.findall(
-            ot("TOOL_CALL") + r"(.*?)" + ct("TOOL_CALL"), content, re.DOTALL
-        )
+        pattern = rf'(?ms){re.escape(ot("TOOL_CALL"))}(.*?)^{re.escape(ct("TOOL_CALL"))}'
+        data = re.findall(pattern, content)
+        auto_completed = False
+        if not data:
+            # can_handle 确保 ot("TOOL_CALL") 在内容中（行首）。
+            # 如果数据为空，则表示行首的 ct("TOOL_CALL") 可能丢失。
+            has_open_at_bol = re.search(rf'(?m){re.escape(ot("TOOL_CALL"))}', content) is not None
+            has_close_at_bol = re.search(rf'(?m)^{re.escape(ct("TOOL_CALL"))}', content) is not None
+            if has_open_at_bol and not has_close_at_bol:
+                # 尝试通过附加结束标签来修复它（确保结束标签位于行首）
+                fixed_content = content.strip() + f"\n{ct('TOOL_CALL')}"
+
+                # 再次提取，并检查YAML是否有效
+                temp_data = re.findall(
+                    pattern,
+                    fixed_content,
+                )
+
+                if temp_data:
+                    try:
+                        yaml.safe_load(temp_data[0])  # Check if valid YAML
+
+                        # Ask user for confirmation
+
+                        data = temp_data
+                        auto_completed = True
+                    except (yaml.YAMLError, EOFError, KeyboardInterrupt):
+                        # Even after fixing, it's not valid YAML, or user cancelled.
+                        # Fall through to the original error.
+                        pass
+
+            if not data:
+                return (
+                    {},
+                    f"只有{ot('TOOL_CALL')}标签，未找到{ct('TOOL_CALL')}标签，调用格式错误，请检查工具调用格式。\n{tool_call_help}",
+                    False,
+                )
         ret = []
         for item in data:
             try:
@@ -560,6 +702,7 @@ class ToolRegistry(OutputHandlerProtocol):
                     {e}
 
                 {tool_call_help}""",
+                    False,
                 )
 
             if "name" in msg and "arguments" in msg and "want" in msg:
@@ -570,10 +713,11 @@ class ToolRegistry(OutputHandlerProtocol):
                     f"""工具调用格式错误，请检查工具调用格式（缺少name、arguments、want字段）。
 
                 {tool_call_help}""",
+                    False,
                 )
         if len(ret) > 1:
-            return {}, "检测到多个工具调用，请一次只处理一个工具调用。"
-        return ret[0] if ret else {}, ""
+            return {}, "检测到多个工具调用，请一次只处理一个工具调用。", False
+        return ret[0] if ret else {}, "", auto_completed
 
     def register_tool(
         self,
@@ -581,6 +725,7 @@ class ToolRegistry(OutputHandlerProtocol):
         description: str,
         parameters: Any,
         func: Callable[..., Dict[str, Any]],
+        protocol_version: str = "1.0",
     ) -> None:
         """注册新工具
 
@@ -590,7 +735,11 @@ class ToolRegistry(OutputHandlerProtocol):
             parameters: 工具参数定义
             func: 工具执行函数
         """
-        self.tools[name] = Tool(name, description, parameters, func)
+        if name in self.tools:
+            PrettyOutput.print(
+                f"警告: 工具 '{name}' 已存在，将被覆盖", OutputType.WARNING
+            )
+        self.tools[name] = Tool(name, description, parameters, func, protocol_version)
 
     def get_tool(self, name: str) -> Optional[Tool]:
         """获取工具
@@ -611,12 +760,15 @@ class ToolRegistry(OutputHandlerProtocol):
         """
         return [tool.to_dict() for tool in self.tools.values()]
 
-    def execute_tool(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    def execute_tool(
+        self, name: str, arguments: Dict[str, Any], agent: Optional[Any] = None
+    ) -> Dict[str, Any]:
         """执行指定工具
 
         参数:
             name: 工具名称
             arguments: 工具参数
+            agent: 智能体实例（由系统内部传递，用于v2.0分离agent与参数）
 
         返回:
             Dict[str, Any]: 包含执行结果的字典，包含success、stdout和stderr字段
@@ -632,7 +784,23 @@ class ToolRegistry(OutputHandlerProtocol):
         # 更新工具调用统计
         self._update_tool_stats(name)
 
-        return tool.execute(arguments)
+        # 根据工具实现声明的协议版本分发调用方式
+        try:
+            if getattr(tool, "protocol_version", "1.0") == "2.0":
+                # v2.0: agent与参数分离传递
+                return tool.func(arguments, agent)  # type: ignore[misc]
+            else:
+                # v1.0: 兼容旧实现，将agent注入到arguments（如果提供）
+                args_to_call = arguments.copy() if isinstance(arguments, dict) else {}
+                if agent is not None:
+                    args_to_call["agent"] = agent
+                return tool.execute(args_to_call)
+        except TypeError:
+            # 兼容处理：如果函数签名不匹配，回退到旧方式
+            args_to_call = arguments.copy() if isinstance(arguments, dict) else {}
+            if agent is not None:
+                args_to_call["agent"] = agent
+            return tool.execute(args_to_call)
 
     def _format_tool_output(self, stdout: str, stderr: str) -> str:
         """格式化工具输出为可读字符串
@@ -671,25 +839,51 @@ class ToolRegistry(OutputHandlerProtocol):
     def handle_tool_calls(self, tool_call: Dict[str, Any], agent: Any) -> str:
         try:
             name = tool_call["name"]  # 确保name是str类型
-            args = tool_call["arguments"]  # args已经是Dict[str, Any]
+            args = tool_call["arguments"]  # 原始参数（来自外部协议）
             want = tool_call["want"]
-            args["agent"] = agent
 
             from jarvis.jarvis_agent import Agent
 
             agent_instance: Agent = agent
 
+            # 如果args是字符串，尝试解析为JSON
             if isinstance(args, str):
                 try:
                     args = json.loads(args)
                 except json.JSONDecodeError:
-                    PrettyOutput.print(
-                        f"工具参数格式无效: {name} {tool_call_help}", OutputType.ERROR
-                    )
-                    return ""
+                    # 返回错误并附带完整的工具使用提示，指导下一次正确调用
+                    try:
+                        usage_prompt = agent_instance.get_tool_usage_prompt()
+                    except Exception:
+                        usage_prompt = tool_call_help
+                    return f"工具参数格式无效: {name}。arguments 应为可解析的 JSON 或对象，请按工具调用格式提供。\n\n{usage_prompt}"
 
-            # 执行工具调用
-            result = self.execute_tool(name, args)  # 修正参数传递
+            # 执行工具调用（根据工具实现的协议版本，由系统在内部决定agent的传递方式）
+            result = self.execute_tool(name, args, agent)
+
+            # 记录本轮实际执行的工具，供上层逻辑（如记忆保存判定）使用
+            try:
+                from jarvis.jarvis_agent import Agent  # 延迟导入避免循环依赖
+                agent_instance_for_record: Agent = agent_instance
+                # 记录最后一次执行的工具
+                agent_instance_for_record.set_user_data("__last_executed_tool__", name)  # type: ignore
+                # 记录本轮累计执行的工具列表
+                executed_list = agent_instance_for_record.get_user_data("__executed_tools__")  # type: ignore
+                if not isinstance(executed_list, list):
+                    executed_list = []
+                executed_list.append(name)
+                agent_instance_for_record.set_user_data("__executed_tools__", executed_list)  # type: ignore
+            except Exception:
+                pass
+
+            # 如果执行失败，附带工具使用提示返回
+            if not result.get("success", False):
+                try:
+                    usage_prompt = agent_instance.get_tool_usage_prompt()
+                except Exception:
+                    usage_prompt = tool_call_help
+                err_output = self._format_tool_output(result.get("stdout", ""), result.get("stderr", ""))
+                return f"{err_output}\n\n{usage_prompt}"
 
             # 格式化输出
             output = self._format_tool_output(
@@ -697,7 +891,10 @@ class ToolRegistry(OutputHandlerProtocol):
             )
 
             # 检查内容是否过大
-            is_large_content = is_context_overflow(output)
+            model_group = None
+            if agent_instance.model:
+                model_group = agent_instance.model.model_group
+            is_large_content = is_context_overflow(output, model_group)
 
             if is_large_content:
                 # 创建临时文件
@@ -719,8 +916,9 @@ class ToolRegistry(OutputHandlerProtocol):
                             [output_file]
                         )
                         if upload_success:
-                            # 删除args的agent键
-                            args.pop("agent", None)
+                            # 删除args的agent键（保持协议v2.0的“参数与agent分离”在可视化中的一致性）
+                            if isinstance(args, dict):
+                                args.pop("agent", None)
                             prompt = f"""
 以下是之前对话的关键信息总结：
 
@@ -747,4 +945,10 @@ class ToolRegistry(OutputHandlerProtocol):
 
         except Exception as e:
             PrettyOutput.print(f"工具执行失败：{str(e)}", OutputType.ERROR)
-            return f"工具调用失败: {str(e)}"
+            try:
+                from jarvis.jarvis_agent import Agent  # 延迟导入避免循环依赖
+                agent_instance_for_prompt: Agent = agent  # type: ignore
+                usage_prompt = agent_instance_for_prompt.get_tool_usage_prompt()
+            except Exception:
+                usage_prompt = tool_call_help
+            return f"工具调用失败: {str(e)}\n\n{usage_prompt}"