@baimingtao/lbs-agent 1.0.0

package/tools/tool/builtin.py

@@ -0,0 +1,656 @@
+"""
+内置工具 — 每个都是真实可执行的函数，带 JSON Schema。
+
+这些工具是 Agent Loop 自循环的基础：
+  Agent 拿到任务 → LLM 决定调哪个工具 → 真实执行 → 结果回灌给 LLM → 继续
+
+不是 mock，不是占位。每个工具都能独立运行并返回有意义的输出。
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import json
+import re
+import glob as glob_module
+from typing import Any
+
+from tools.tool.registry import ToolRegistry
+
+
+# ── read_file ─────────────────────────────────────
+
+MAX_LINE_LENGTH = 2000
+
+def _read_file(path: str, offset: int = 1, limit: int = 500, **kwargs) -> str:
+    abs_path = os.path.abspath(path)
+    if not os.path.exists(abs_path):
+        return f"ERROR: File not found: {abs_path}"
+
+    ext = os.path.splitext(abs_path)[1].lower()
+
+    # Excel 解析
+    if ext in ('.xlsx', '.xls'):
+        try:
+            import openpyxl
+            wb = openpyxl.load_workbook(abs_path, read_only=True, data_only=True)
+            parts = []
+            for ws in wb.worksheets:
+                parts.append(f"=== Sheet: {ws.title} ===")
+                row_count = 0
+                for row in ws.iter_rows(values_only=True):
+                    if row_count >= (limit or 500):
+                        parts.append(f"... ({ws.max_row - row_count} more rows)")
+                        break
+                    cells = [str(c) if c is not None else '' for c in row]
+                    parts.append('\t'.join(cells))
+                    row_count += 1
+            wb.close()
+            return f"[{abs_path}] Excel parsed ({len(parts)} rows)\n" + '\n'.join(parts)
+        except ImportError:
+            return f"[BINARY] {abs_path} — Excel 文件，需安装 openpyxl 才能解析"
+        except Exception as e:
+            return f"ERROR parsing Excel: {e}"
+
+    # CSV 按文本读
+    if ext == '.csv':
+        pass  # 走下面的文本读取逻辑
+
+    # Word 文档
+    if ext in ('.docx',):
+        try:
+            from docx import Document
+            doc = Document(abs_path)
+            lines = [p.text for p in doc.paragraphs if p.text.strip()]
+            return f"[{abs_path}] Word parsed ({len(lines)} paragraphs)\n" + '\n'.join(lines[:limit or 500])
+        except ImportError:
+            return f"[BINARY] {abs_path} — Word 文件，需安装 python-docx 才能解析"
+        except Exception as e:
+            return f"ERROR parsing Word: {e}"
+
+    # 其他二进制检测
+    try:
+        with open(abs_path, 'rb') as fb:
+            sample = fb.read(8192)
+        if b'\x00' in sample and ext not in ('.csv',):
+            return f"[BINARY] {abs_path} — 二进制文件（{ext}），read_file 无法解析"
+    except Exception:
+        pass
+    try:
+        with open(abs_path, 'r', encoding='utf-8-sig', errors='replace') as f:
+            all_lines = f.readlines()
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+    start = max(0, (offset or 1) - 1)
+    end = start + (limit or 500)
+    lines = []
+    for i in range(start, min(end, len(all_lines))):
+        raw = all_lines[i].rstrip()
+        if len(raw) > MAX_LINE_LENGTH:
+            raw = raw[:MAX_LINE_LENGTH] + " [...truncated]"
+        lines.append(f"{i+1:04d}|{raw}")
+    total = len(all_lines)
+    shown = len(lines)
+    header = f"[{abs_path}] lines {start+1}-{start+shown} of {total}\n"
+    return header + "\n".join(lines)
+
+
+_READ_FILE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "文件路径（绝对或相对）"},
+        "offset": {"type": "integer", "description": "起始行号（1-indexed），默认 1", "default": 1},
+        "limit": {"type": "integer", "description": "最多读取行数，默认 500", "default": 500},
+    },
+    "required": ["path"],
+}
+
+
+# ── write_file ────────────────────────────────────
+
+def _write_file(path: str, content: str, **kwargs) -> str:
+    abs_path = os.path.abspath(path)
+    try:
+        os.makedirs(os.path.dirname(abs_path), exist_ok=True)
+        with open(abs_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+        return f"OK: wrote {len(content)} chars to {abs_path}"
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+
+
+_WRITE_FILE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "文件路径"},
+        "content": {"type": "string", "description": "完整文件内容（覆盖写入）"},
+    },
+    "required": ["path", "content"],
+}
+
+
+# ── search_files ──────────────────────────────────
+
+def _search_files(pattern: str, path: str = ".", target: str = "content", **kwargs) -> str:
+    abs_path = os.path.abspath(path)
+    results = []
+    if target == "files":
+        full_glob = os.path.join(abs_path, "**", pattern)
+        matched = glob_module.glob(full_glob, recursive=True)
+        for m in matched[:50]:
+            results.append(os.path.relpath(m, abs_path))
+        return f"Found {len(matched)} files (showing {len(results)}):\n" + "\n".join(sorted(results))
+
+    # content search — pattern 可能是正则也可能是字面量
+    # 先尝试编译为正则；失败则降级为字面量搜索
+    compiled = None
+    literal = False
+    try:
+        compiled = re.compile(pattern)
+    except re.error:
+        # glob 或非法正则 → 字面量搜索
+        compiled = re.compile(re.escape(pattern))
+        literal = True
+
+    count = 0
+    try:
+        for root, dirs, files in os.walk(abs_path):
+            # skip hidden / __pycache__ / node_modules
+            dirs[:] = [d for d in dirs if not d.startswith('.') and d != '__pycache__' and d != 'node_modules']
+            for fname in files:
+                if count >= 50:
+                    break
+                fpath = os.path.join(root, fname)
+                try:
+                    with open(fpath, 'r', encoding='utf-8', errors='ignore') as f:
+                        for lineno, line in enumerate(f, 1):
+                            if compiled.search(line):
+                                rel = os.path.relpath(fpath, abs_path)
+                                results.append(f"{rel}:{lineno}: {line.rstrip()[:200]}")
+                                count += 1
+                                if count >= 50:
+                                    break
+                except Exception:
+                    pass
+            if count >= 50:
+                break
+    except Exception as e:
+        return f"ERROR: {e}"
+    mode = "literal" if literal else "regex"
+    return f"Found {count} matches ({mode} search for '{pattern}'):\n" + "\n".join(results)
+
+
+_SEARCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "pattern": {"type": "string", "description": "正则表达式或 glob 模式"},
+        "path": {"type": "string", "description": "搜索目录，默认当前目录", "default": "."},
+        "target": {"type": "string", "enum": ["content", "files"], "description": "搜内容还是搜文件名", "default": "content"},
+    },
+    "required": ["pattern"],
+}
+
+
+# ── terminal ──────────────────────────────────────
+
+def _terminal(command: str, timeout: int = 60, stdin: str = "", **kwargs) -> str:
+    """执行 shell 命令，支持多行脚本、heredoc 和 stdin 管道。
+
+    自动检测 Windows 环境：优先用系统 shell（bash/cmd），
+    如果命令含 heredoc (<<) 或多行换行，自动写临时脚本执行。
+    """
+    import tempfile as _tf
+
+    # 多行命令处理：如果命令含换行或 heredoc，写临时 .sh/.bat 文件执行
+    is_multiline = "\n" in command or "<<" in command
+    use_script = False
+    script_path = None
+
+    try:
+        if is_multiline:
+            # 写临时脚本文件
+            if os.name == "nt":
+                # Windows: 可能是 bash（git-bash）或 cmd
+                # 检测是否有 bash 特性（heredoc、$() 等）
+                has_bash_syntax = any(t in command for t in ("<<", "$(", "${", "#!/", "if ", "for ", "while "))
+                if has_bash_syntax:
+                    script_path = _tf.mktemp(suffix=".sh")
+                    with open(script_path, "w", encoding="utf-8", newline="\n") as f:
+                        f.write("#!/bin/bash\n")
+                        f.write(command)
+                    # 用 git-bash 执行
+                    bash_candidates = [
+                        os.environ.get("BASH", ""),
+                        "C:/Program Files/Git/bin/bash.exe",
+                        "C:/Program Files/Git/usr/bin/bash.exe",
+                    ]
+                    bash_exe = next((b for b in bash_candidates if b and os.path.exists(b)), None)
+                    if bash_exe:
+                        actual_cmd = f'"{bash_exe}" "{script_path}"'
+                    else:
+                        # 没有 bash，尝试清理命令后用 cmd 执行
+                        cleaned = command.replace("<<", "").replace("PY", "").replace("'PY'", "").replace('"PY"', "")
+                        actual_cmd = cleaned
+                        use_script = False
+                else:
+                    actual_cmd = command
+            else:
+                # Linux/Mac：直接执行（shell=True 支持 heredoc）
+                actual_cmd = command
+        else:
+            actual_cmd = command
+
+        p = subprocess.run(
+            actual_cmd,
+            shell=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            input=stdin if stdin else None,
+        )
+        parts = []
+        MAX_TERMINAL_OUTPUT = 50000
+        stdout = p.stdout or ""
+        if len(stdout) > MAX_TERMINAL_OUTPUT:
+            stdout = stdout[:MAX_TERMINAL_OUTPUT] + f"\n... [truncated, {len(p.stdout)} chars total]"
+        if stdout:
+            parts.append(stdout.rstrip())
+        stderr = p.stderr or ""
+        if len(stderr) > MAX_TERMINAL_OUTPUT:
+            stderr = stderr[:MAX_TERMINAL_OUTPUT] + f"\n... [truncated, {len(p.stderr)} chars total]"
+        if stderr:
+            parts.append(f"[STDERR]\n{stderr.rstrip()}")
+        parts.append(f"[exit={p.returncode}]")
+        return "\n".join(parts)
+    except subprocess.TimeoutExpired:
+        return f"ERROR: Command timed out after {timeout}s"
+    except FileNotFoundError as e:
+        return f"ERROR: Command not found: {e}"
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+    finally:
+        if script_path and os.path.exists(script_path):
+            try:
+                os.unlink(script_path)
+            except Exception:
+                pass
+
+
+_TERMINAL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "command": {"type": "string", "description": "Shell 命令（支持多行、heredoc、管道）"},
+        "timeout": {"type": "integer", "description": "超时秒数，默认 60", "default": 60},
+        "stdin": {"type": "string", "description": "标准输入内容（可选，用于管道场景）", "default": ""},
+    },
+    "required": ["command"],
+}
+
+
+# ── list_dir ──────────────────────────────────────
+
+def _list_dir(path: str = ".", recursive: bool = False, max_depth: int = 3, **kwargs) -> str:
+    abs_path = os.path.abspath(path)
+    if not os.path.isdir(abs_path):
+        return f"ERROR: Not a directory: {abs_path}"
+    items = []
+    try:
+        if recursive:
+            for dirpath, dirnames, filenames in os.walk(abs_path):
+                dirnames[:] = [d for d in sorted(dirnames) if not d.startswith('.') and d != '__pycache__' and d != 'node_modules']
+                rel_dir = os.path.relpath(dirpath, abs_path)
+                depth = 0 if rel_dir == '.' else rel_dir.count(os.sep) + 1
+                if depth > max_depth:
+                    continue
+                prefix = "  " * depth
+                for name in sorted(dirnames):
+                    items.append(f"{prefix}{name}/")
+                for name in sorted(filenames):
+                    full = os.path.join(dirpath, name)
+                    size = os.path.getsize(full) if os.path.isfile(full) else 0
+                    size_str = f" ({size}B)" if size < 10000 else f" ({size//1000}KB)"
+                    items.append(f"{prefix}{name}{size_str}")
+        else:
+            for name in sorted(os.listdir(abs_path)):
+                full = os.path.join(abs_path, name)
+                if os.path.isdir(full):
+                    items.append(f"  {name}/")
+                elif os.path.isfile(full):
+                    size = os.path.getsize(full)
+                    size_str = f" ({size}B)" if size < 10000 else f" ({size//1000}KB)"
+                    items.append(f"  {name}{size_str}")
+    except Exception as e:
+        return f"ERROR: {e}"
+    return f"[{abs_path}] ({len(items)} items)\n" + "\n".join(items[:200])
+
+
+_LIST_DIR_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string", "description": "目录路径", "default": "."},
+        "recursive": {"type": "boolean", "description": "递归列出子目录", "default": False},
+        "max_depth": {"type": "integer", "description": "递归最大深度", "default": 3},
+    },
+}
+
+
+# ── 注册入口 ──────────────────────────────────────
+
+
+
+# ── vision_analyze ────────────────────────────────
+
+def _vision_analyze(image_url: str = "", question: str = "描述这张图片", **kwargs) -> str:
+    """用 LLM 的视觉能力分析图片。
+
+    通过多模态 API 发送图片 URL + 问题，获取分析结果。
+    支持 http/https URL 和本地文件路径。
+    """
+    # 兼容 image_path 别名
+    if not image_url and "image_path" in kwargs:
+        image_url = kwargs["image_path"]
+    if not image_url:
+        return "ERROR: 缺少必填参数 image_url 或 image_path"
+    import json as _json
+    import urllib.request
+    import urllib.error
+    import base64
+
+    # 判断是 URL 还是本地文件
+    is_url = image_url.startswith("http://") or image_url.startswith("https://")
+    is_data_url = image_url.startswith("data:")
+
+    if not is_url and not is_data_url:
+        # 本地文件 → base64 编码
+        import os as _os
+        if not _os.path.exists(image_url):
+            return f"ERROR: File not found: {image_url}"
+        try:
+            with open(image_url, "rb") as f:
+                encoded = base64.b64encode(f.read()).decode("utf-8")
+            ext = _os.path.splitext(image_url)[1].lower().lstrip(".")
+            mime = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "gif": "gif", "webp": "webp"}.get(ext, "png")
+            image_url = f"data:image/{mime};base64,{encoded}"
+        except Exception as e:
+            return f"ERROR: Failed to read image: {e}"
+
+    # 使用 Anthropic Messages API 的 vision 能力
+    # 读取 seeyon 配置
+    try:
+        from config.config import load_config
+        seeyon = load_config().models.providers.get("seeyon")
+        if not seeyon:
+            return "ERROR: Provider not configured: seeyon"
+        api_key = seeyon.api_key
+        base_url = seeyon.base_url or "https://api.seeyoncloud.com"
+
+        url = base_url.rstrip("/") + "/v1/messages"
+        payload = {
+            "model": "gpt-5.4",
+            "max_tokens": 1024,
+            "messages": [{
+                "role": "user",
+                "content": [
+                    {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_url.split(",")[1] if "," in image_url else ""}},
+                    {"type": "text", "text": question},
+                ],
+            }],
+        }
+        # 简化：如果是 URL，用 URL 模式
+        if is_url:
+            payload["messages"][0]["content"][0] = {"type": "image", "source": {"type": "url", "url": image_url}}
+
+        data = _json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+        }
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            result = _json.loads(resp.read().decode("utf-8"))
+            text_parts = [b.get("text", "") for b in result.get("content", []) if b.get("type") == "text"]
+            return "".join(text_parts) or "(no text in response)"
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8")[:300]
+        except Exception:
+            pass
+        return f"ERROR: API error {e.code}: {body}"
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+
+
+_VISION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "image_url": {"type": "string", "description": "图片 URL 或本地文件路径"},
+        "image_path": {"type": "string", "description": "本地文件路径（image_url 别名）"},
+        "question": {"type": "string", "description": "要问的问题", "default": "描述这张图片"},
+    },
+    "required": [],
+}
+
+
+# ── web_search ────────────────────────────────────
+
+def _web_search(query: str, max_results: int = 5, **kwargs) -> str:
+    """搜索网页。使用 DuckDuckGo HTML 解析（无 API key 需要）。"""
+    # 兼容 LLM 传 lang / count 等多余参数
+    import urllib.request
+    import urllib.parse
+    import re
+
+    try:
+        encoded_query = urllib.parse.quote(query)
+        url = f"https://html.duckduckgo.com/html/?q={encoded_query}"
+
+        req = urllib.request.Request(url, headers={
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+        })
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            html = resp.read().decode("utf-8", errors="replace")
+
+        # 解析结果
+        results = []
+        # DuckDuckGo HTML 格式
+        for match in re.finditer(r'<a[^>]+class="result__a"[^>]*href="([^"]+)"[^>]*>(.*?)</a>', html, re.S):
+            href = match.group(1)
+            title = re.sub(r'<[^>]+>', '', match.group(2)).strip()
+            if title and href:
+                # DuckDuckGo 重定向 URL
+                if "uddg=" in href:
+                    href = urllib.parse.unquote(href.split("uddg=")[1].split("&")[0])
+                results.append(f"- {title}\n  {href}")
+            if len(results) >= max_results:
+                break
+
+        if not results:
+            # 备用解析
+            for match in re.finditer(r'<a[^>]+href="(https?://[^"]+)"[^>]*>(.*?)</a>', html, re.S):
+                href = match.group(1)
+                title = re.sub(r'<[^>]+>', '', match.group(2)).strip()
+                if title and "duckduckgo" not in href and len(title) > 10:
+                    results.append(f"- {title[:100]}\n  {href}")
+                if len(results) >= max_results:
+                    break
+
+        if results:
+            return f"搜索 '{query}' 找到 {len(results)} 个结果:\n" + "\n".join(results)
+        return f"搜索 '{query}' 无结果"
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+
+
+_WEB_SEARCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "query": {"type": "string", "description": "搜索关键词"},
+        "max_results": {"type": "integer", "description": "最大返回数", "default": 5},
+    },
+    "required": ["query"],
+}
+
+
+# ── image_gen ─────────────────────────────────────
+
+def _image_gen(prompt: str, size: str = "1024x1024", save_path: str = "", **kwargs) -> str:
+    """生成图片。使用 seeyon API（如果支持），否则返回提示。
+
+    当前实现：调用 seeyon 的 image 生成端点。
+    如果 API 不支持，返回需要 DALL-E/SD 的提示。
+    """
+    import json as _json
+    import urllib.request
+    import urllib.error
+
+    try:
+        from config.config import load_config
+        seeyon = load_config().models.providers.get("seeyon")
+        if not seeyon:
+            return "ERROR: Provider not configured: seeyon"
+        api_key = seeyon.api_key
+        base_url = seeyon.base_url or "https://api.seeyoncloud.com"
+
+        # 尝试 OpenAI 兼容的 image generation 端点
+        url = base_url.rstrip("/") + "/v1/images/generations"
+        payload = {
+            "model": "gpt-image-2",
+            "prompt": prompt,
+            "n": 1,
+            "size": size,
+        }
+        data = _json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        }
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            result = _json.loads(resp.read().decode("utf-8"))
+
+        images = result.get("data", [])
+        if not images:
+            return "ERROR: No image in response"
+
+        image_url = images[0].get("url", "")
+        b64 = images[0].get("b64_json", "")
+
+        if not save_path:
+            save_path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "generated_image.png")
+
+        if b64:
+            import base64
+            with open(save_path, "wb") as f:
+                f.write(base64.b64decode(b64))
+            return f"OK: 图片已保存到 {save_path}"
+        elif image_url:
+            # 下载 URL
+            urllib.request.urlretrieve(image_url, save_path)
+            return f"OK: 图片已保存到 {save_path} (源: {image_url[:100]})"
+        else:
+            return f"ERROR: No image URL or base64 in response"
+
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8")[:300]
+        except Exception:
+            pass
+        return f"ERROR: API error {e.code}: {body}"
+    except Exception as e:
+        return f"ERROR: {type(e).__name__}: {e}"
+
+
+_IMAGE_GEN_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "prompt": {"type": "string", "description": "图片描述"},
+        "size": {"type": "string", "description": "图片尺寸 (1024x1024, 512x512)", "default": "1024x1024"},
+        "save_path": {"type": "string", "description": "保存路径（可选）"},
+    },
+    "required": ["prompt"],
+}
+
+ALL_TOOLS = {
+    "vision_analyze": (_vision_analyze, "用视觉模型分析图片内容（URL 或本地文件）。", _VISION_SCHEMA),
+    "web_search": (_web_search, "搜索网页（DuckDuckGo，无需 API key）。", _WEB_SEARCH_SCHEMA),
+    "image_gen": (_image_gen, "生成图片（需要支持图片生成的 API）。", _IMAGE_GEN_SCHEMA),
+    "read_file": (_read_file, "读取文件内容（带行号）。", _READ_FILE_SCHEMA),
+    "write_file": (_write_file, "写入文件（覆盖）。返回确认信息。", _WRITE_FILE_SCHEMA),
+    "search_files": (_search_files, "搜索文件内容或按文件名查找。", _SEARCH_SCHEMA),
+    "terminal": (_terminal, "执行 shell 命令并返回输出。", _TERMINAL_SCHEMA),
+    "list_dir": (_list_dir, "列出目录内容。", _LIST_DIR_SCHEMA),
+}
+
+
+_TOOL_SAFETY = {
+    "read_file": "local_read",
+    "write_file": "local_write",
+    "search_files": "local_read",
+    "terminal": "local_exec",
+    "vision_analyze": "external_read",
+    "web_search": "external_read",
+    "image_gen": "external_write",
+    "list_dir": "local_read",
+}
+
+
+def create_default_registry(include_skills: bool = True) -> ToolRegistry:
+    """创建包含所有内置工具的 Registry。"""
+    reg = ToolRegistry()
+    for name, (func, desc, schema) in ALL_TOOLS.items():
+        reg.register(name, desc, func, schema, source="builtin", provider_id="builtin.local", safety=_TOOL_SAFETY.get(name, "local_read"))
+    try:
+        from tools.tool.todo_provider import TodoProvider
+        reg.register_provider(TodoProvider())
+    except Exception:
+        pass
+    # Hermes 对标工具：todo / memory / session_search
+    try:
+        from tools.tool.hermes_migrated import create_hermes_migrated_provider
+        reg.register_provider(create_hermes_migrated_provider())
+    except Exception:
+        pass
+    # 高级工具：patch / clarify / code_execution
+    try:
+        from tools.tool.advanced_tools import create_advanced_tools_provider
+        reg.register_provider(create_advanced_tools_provider())
+    except Exception:
+        pass
+    if include_skills:
+        try:
+            from tools.tool.skill_provider import SkillProvider
+            reg.register_provider(SkillProvider())
+        except Exception:
+            pass
+    # browser-use 原生集成
+    try:
+        from tools.tool.implementations.browser_use_provider import create_browser_use_provider
+        reg.register_provider(create_browser_use_provider())
+        logger.info("browser-use provider registered (20 browser_* tools)")
+    except Exception:
+        pass
+    # 扩展工具（research / email / data_analyst / github）
+    try:
+        from tools.tool.implementations.extended_tools import create_extended_tools_provider
+        reg.register_provider(create_extended_tools_provider())
+        logger.info("extended tools provider registered (wikipedia/email/sql)")
+    except Exception:
+        pass
+    return reg
+
+
+def create_registry_with(names: list[str]) -> ToolRegistry:
+    """创建只包含指定工具的 Registry。"""
+    reg = ToolRegistry()
+    for name in names:
+        if name in ALL_TOOLS:
+            func, desc, schema = ALL_TOOLS[name]
+            reg.register(name, desc, func, schema, source="builtin", provider_id="builtin.local", safety=_TOOL_SAFETY.get(name, "local_read"))
+    return reg