lcode-agent 0.1.0__py3-none-any.whl

lcode/tools.py

@@ -0,0 +1,1147 @@
+"""Grok Build 同名内置工具:读改搜列、终端、待办、网页。
+
+参数名和 Grok 对齐。相对路径相对当前工作目录,也允许项目外的绝对路径。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import difflib
+import shutil
+import sys
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import aiohttp
+
+ROOT = Path.cwd().resolve()
+_SKIP_DIR = {".git", "__pycache__", ".venv", "node_modules", ".lcode"}
+_before_write = None
+
+
+def set_write_hook(fn) -> None:
+    """改文件前打快照。fn(path: Path) -> None。"""
+    global _before_write
+    _before_write = fn
+
+
+def _note_write(path: Path) -> None:
+    hook = _before_write
+    if hook is None:
+        return
+    try:
+        hook(path)
+    except Exception:
+        pass
+
+
+def _safe_path(raw: str) -> Path:
+    text = (raw or "").strip() or "."
+    path = Path(text)
+    if not path.is_absolute():
+        path = ROOT / path
+    return path.resolve()
+
+
+def _clip(text: str, limit: int = 80_000) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"\n…(截断,共 {len(text)} 字)"
+
+
+def openai_tools() -> list[dict]:
+    """chat/completions 用的 tools 数组。"""
+    return [{"type": "function", "function": spec} for spec in _SPECS]
+
+
+def responses_tools() -> list[dict]:
+    """responses 用的 tools 数组。"""
+    out = []
+    for spec in _SPECS:
+        out.append(
+            {
+                "type": "function",
+                "name": spec["name"],
+                "description": spec["description"],
+                "parameters": spec["parameters"],
+            }
+        )
+    return out
+
+
+_SPECS: list[dict] = [
+    {
+        "name": "read_file",
+        "description": "Read a file. Line numbers appear as LINE|content.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "target_file": {"type": "string", "description": "Path relative to workspace or absolute."},
+                "offset": {"type": "integer", "description": "1-based start line."},
+                "limit": {"type": "integer", "description": "Max lines to read."},
+            },
+            "required": ["target_file"],
+        },
+    },
+    {
+        "name": "write",
+        "description": "Create or overwrite a file. Parent directories are created. Prefer search_replace for small edits.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string"},
+                "contents": {"type": "string", "description": "Full file contents."},
+            },
+            "required": ["file_path", "contents"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Alias of write.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string"},
+                "contents": {"type": "string"},
+            },
+            "required": ["file_path", "contents"],
+        },
+    },
+    {
+        "name": "search_replace",
+        "description": "Replace an exact string in a file. old_string must match once unless replace_all.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string"},
+                "old_string": {"type": "string"},
+                "new_string": {"type": "string"},
+                "replace_all": {"type": "boolean", "default": False},
+            },
+            "required": ["file_path", "old_string", "new_string"],
+        },
+    },
+    {
+        "name": "list_dir",
+        "description": "List files and directories. Dot files hidden. gitignored-style junk skipped.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "target_directory": {"type": "string"},
+            },
+            "required": ["target_directory"],
+        },
+    },
+    {
+        "name": "grep",
+        "description": "Search file contents with a regex. ripgrep-style filters.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "path": {"type": "string"},
+                "glob": {"type": "string"},
+                "head_limit": {"type": "integer"},
+                "-i": {"type": "boolean"},
+            },
+            "required": ["pattern"],
+        },
+    },
+    {
+        "name": "grep_search",
+        "description": "Alias of grep.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "search_path": {"type": "string"},
+                "include_pattern": {"type": "string"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "run_terminal_command",
+        "description": "Run a shell command in the workspace. Use for git, builds, scripts.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "working_directory": {"type": "string"},
+                "timeout": {"type": "integer", "description": "Seconds, default 120."},
+            },
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "bash",
+        "description": "Alias of run_terminal_command.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "working_directory": {"type": "string"},
+            },
+            "required": ["command"],
+        },
+    },
+    {
+        "name": "todo_write",
+        "description": "Create and manage a structured task list.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "todos": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "id": {"type": "string"},
+                            "content": {"type": "string"},
+                            "status": {
+                                "type": "string",
+                                "enum": ["pending", "in_progress", "completed", "cancelled"],
+                            },
+                        },
+                        "required": ["id"],
+                    },
+                },
+            },
+            "required": ["todos"],
+        },
+    },
+    {
+        "name": "web_search",
+        "description": "Search the web. Use for current facts.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "num_results": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "web_fetch",
+        "description": "Fetch a URL and return text content.",
+        "parameters": {
+            "type": "object",
+            "properties": {"url": {"type": "string"}},
+            "required": ["url"],
+        },
+    },
+]
+
+
+_TODOS: list[dict] = []
+_todo_change_hook = None
+
+
+def set_todo_hook(fn) -> None:
+    """todo_write 变化后通知界面/存储。fn(todos: list[dict]) -> None。"""
+    global _todo_change_hook
+    _todo_change_hook = fn
+
+
+def set_todos(initial: list[dict]) -> None:
+    """启动时把落库的待办灌回内存。"""
+    global _TODOS
+    _TODOS = [t for t in (initial or []) if isinstance(t, dict)]
+    hook = _todo_change_hook
+    if hook is not None:
+        try:
+            hook(_TODOS)
+        except Exception:
+            pass
+
+
+def execute_tool(name: str, arguments: dict) -> str:
+    key = (name or "").strip()
+    if key == "grep_search":
+        arguments = {
+            "pattern": arguments.get("query") or arguments.get("pattern") or "",
+            "path": arguments.get("search_path") or arguments.get("path"),
+            "glob": arguments.get("include_pattern") or arguments.get("glob"),
+        }
+        key = "grep"
+    if key == "bash":
+        key = "run_terminal_command"
+    if key == "write_file":
+        key = "write"
+    fn = {
+        "read_file": _read_file,
+        "write": _write_file,
+        "search_replace": _search_replace,
+        "list_dir": _list_dir,
+        "grep": _grep,
+        "run_terminal_command": _run_cmd,
+        "todo_write": _todo_write,
+        "web_search": None,
+        "web_fetch": None,
+    }.get(key)
+    if key in ("web_search", "web_fetch"):
+        raise RuntimeError("async")
+    if fn is None:
+        return f"未知工具: {name}"
+    try:
+        return fn(arguments or {})
+    except Exception as exc:
+        return f"工具失败: {exc}"
+
+
+async def execute_tool_async(name: str, arguments: dict, on_output=None) -> str:
+    key = (name or "").strip()
+    if key == "web_search":
+        return await _web_search(arguments or {})
+    if key == "web_fetch":
+        return await _web_fetch(arguments or {})
+    if key in ("run_terminal_command", "bash"):
+        return await _run_cmd_async(arguments or {}, on_output)
+    # 终端、文件 IO 这些同步工具丢进线程池,别把 TUI 的事件循环冻住
+    return await asyncio.to_thread(execute_tool, name, arguments or {})
+
+
+def _relpath(path: Path) -> str:
+    try:
+        return str(path.relative_to(ROOT)).replace("\\", "/")
+    except ValueError:
+        return str(path)
+
+
+def tool_title(name: str, arguments: dict) -> str:
+    args = arguments or {}
+    if name in ("read_file",):
+        return f"read_file {args.get('target_file') or ''}".strip()
+    if name in ("write", "write_file"):
+        raw = str(args.get("file_path") or args.get("target_file") or "")
+        try:
+            return f"write {_relpath(_safe_path(raw))}"
+        except Exception:
+            return f"write {raw}".strip()
+    if name == "search_replace":
+        raw = str(args.get("file_path") or "")
+        try:
+            return f"search_replace {_relpath(_safe_path(raw))}"
+        except Exception:
+            return f"search_replace {raw}".strip()
+    if name == "list_dir":
+        return f"list_dir {args.get('target_directory') or ''}".strip()
+    if name in ("grep", "grep_search"):
+        return f"grep {args.get('pattern') or args.get('query') or ''}".strip()
+    if name in ("run_terminal_command", "bash"):
+        cmd = str(args.get("command") or "")
+        return f"$ {cmd[:80]}"
+    if name == "todo_write":
+        return "todo_write"
+    if name == "web_search":
+        return f"web_search {args.get('query') or ''}".strip()
+    if name == "web_fetch":
+        return f"web_fetch {args.get('url') or ''}".strip()
+    return name
+
+
+def tool_result_summary(name: str, result: str) -> str:
+    first = (result or "").splitlines()[0] if result else ""
+    key = (name or "").strip()
+    if key == "search_replace":
+        if first.startswith("已替换"):
+            return first.split(":", 1)[0].strip()
+        return first[:40]
+    if key in ("write", "write_file"):
+        if first.startswith("已写入") or first.startswith("已覆盖"):
+            return first.split(":", 1)[0].strip()
+        return first[:40]
+    if key == "read_file":
+        if not result:
+            return "空"
+        return f"{result.count(chr(10)) + 1} 行"
+    if key == "list_dir":
+        n = len([ln for ln in (result or "").splitlines() if ln.strip()])
+        return f"{n} 项"
+    if key in ("grep", "grep_search"):
+        if first == "无匹配":
+            return "无匹配"
+        return f"{len((result or '').splitlines())} 处"
+    if key in ("run_terminal_command", "bash"):
+        return first[:32] if first else "完成"
+    if key == "todo_write":
+        return f"{len((result or '').splitlines())} 项"
+    return first[:40]
+
+
+def normalize_tool_name(name: str) -> str:
+    key = (name or "").strip()
+    if key == "write_file":
+        return "write"
+    if key == "bash":
+        return "run_terminal_command"
+    if key == "grep_search":
+        return "grep"
+    return key
+
+
+def tool_is_sensitive(name: str, arguments: dict | None = None) -> bool:
+    """ask 模式下要先问用户的操作:改文件、覆盖文件、跑终端。"""
+    key = normalize_tool_name(name)
+    return key in ("run_terminal_command", "search_replace", "write")
+
+
+_JSON_ESC = {
+    '"': '"',
+    "\\": "\\",
+    "/": "/",
+    "b": "\b",
+    "f": "\f",
+    "n": "\n",
+    "r": "\r",
+    "t": "\t",
+}
+
+_TOOL_STRING_KEYS = (
+    "file_path",
+    "target_file",
+    "target_directory",
+    "path",
+    "contents",
+    "content",
+    "old_string",
+    "new_string",
+    "command",
+    "working_directory",
+    "pattern",
+    "query",
+    "url",
+)
+
+
+def unescape_json_fragment(raw: str) -> str:
+    """把 JSON 字符串里的 \\n \\t \\\" 还原成真正字符;末尾半截转义丢掉。"""
+    out: list[str] = []
+    i = 0
+    n = len(raw or "")
+    while i < n:
+        ch = raw[i]
+        if ch != "\\":
+            out.append(ch)
+            i += 1
+            continue
+        if i + 1 >= n:
+            break
+        nxt = raw[i + 1]
+        if nxt == "u":
+            if i + 5 >= n:
+                break
+            try:
+                out.append(chr(int(raw[i + 2 : i + 6], 16)))
+            except ValueError:
+                out.append(nxt)
+                i += 2
+                continue
+            i += 6
+            continue
+        out.append(_JSON_ESC.get(nxt, nxt))
+        i += 2
+    return "".join(out)
+
+
+def _json_string_body(raw: str, start: int) -> str:
+    """取开始引号之后到未转义结束引号之前的原文(含转义);没闭合就接到末尾。"""
+    i = start
+    n = len(raw)
+    while i < n:
+        ch = raw[i]
+        if ch == '"':
+            return raw[start:i]
+        if ch == "\\":
+            i += 2
+            continue
+        i += 1
+    return raw[start:]
+
+
+def _extract_json_string(raw: str, key: str) -> str | None:
+    needle = f'"{key}"'
+    start = 0
+    while True:
+        idx = raw.find(needle, start)
+        if idx < 0:
+            return None
+        i = idx + len(needle)
+        n = len(raw)
+        while i < n and raw[i] in " \t\r\n":
+            i += 1
+        if i >= n or raw[i] != ":":
+            start = idx + 1
+            continue
+        i += 1
+        while i < n and raw[i] in " \t\r\n":
+            i += 1
+        if i >= n or raw[i] != '"':
+            start = idx + 1
+            continue
+        return unescape_json_fragment(_json_string_body(raw, i + 1))
+
+
+def parse_tool_arguments(raw: str) -> dict:
+    """完整 JSON 直接解析;流式半截则尽量抽出字符串字段,\\n 已经还原。"""
+    text = raw or ""
+    stripped = text.strip()
+    if not stripped:
+        return {}
+    try:
+        data = json.loads(stripped)
+        return data if isinstance(data, dict) else {}
+    except json.JSONDecodeError:
+        pass
+    out: dict = {}
+    for key in _TOOL_STRING_KEYS:
+        val = _extract_json_string(text, key)
+        if val is not None:
+            out[key] = val
+    return out
+
+
+def looks_like_tool_args(text: str) -> bool:
+    """助手正文里误塞进来的工具 JSON:以 { 开头,带 contents/command 这类键。"""
+    s = (text or "").lstrip()
+    if not s.startswith("{"):
+        return False
+    keys = (
+        '"contents"',
+        '"new_string"',
+        '"old_string"',
+        '"file_path"',
+        '"command"',
+        '"target_file"',
+    )
+    return any(k in s for k in keys)
+
+
+def _preview_rel(path: str) -> str:
+    raw = (path or "").strip()
+    if not raw:
+        return ""
+    try:
+        return _relpath(_safe_path(raw))
+    except Exception:
+        return raw
+
+
+def preview_tool_arguments(name: str, raw: str) -> str:
+    """流式工具参数给人看:写入/替换从第一块起就按真换行展示,不要字面 \\n。"""
+    args = parse_tool_arguments(raw)
+    key = normalize_tool_name(name)
+    if not key:
+        if "new_string" in args or "old_string" in args:
+            key = "search_replace"
+        elif "contents" in args or "content" in args:
+            key = "write"
+        elif "command" in args:
+            key = "run_terminal_command"
+    if key == "write":
+        rel = _preview_rel(
+            str(args.get("file_path") or args.get("target_file") or args.get("path") or "")
+        )
+        body = args.get("contents")
+        if body is None:
+            body = args.get("content")
+        body = str(body or "")
+        lines = body.splitlines()
+        if body and not lines:
+            lines = [body]
+        rows = [f"+{i:>5}|{line}" for i, line in enumerate(lines, start=1)]
+        header = f"写入中: {rel}" if rel else "写入中"
+        if not rows:
+            return header
+        return f"{header}\n\n" + "\n".join(_clip_rows(rows))
+    if key == "search_replace":
+        rel = _preview_rel(str(args.get("file_path") or ""))
+        old = str(args.get("old_string") or "")
+        new = str(args.get("new_string") or "")
+        rows: list[str] = []
+        if old:
+            for line in old.splitlines() or [old]:
+                rows.append(f"-{line}")
+        if new:
+            for line in new.splitlines() or [new]:
+                rows.append(f"+{line}")
+        header = f"替换中: {rel}" if rel else "替换中"
+        if not rows:
+            return header
+        return f"{header}\n\n" + "\n".join(_clip_rows(rows))
+    if key == "run_terminal_command":
+        cmd = str(args.get("command") or "")
+        cwd = str(args.get("working_directory") or "")
+        if cmd and cwd:
+            return f"{cmd}\n(cwd {cwd})"
+        return cmd or (f"cwd {cwd}" if cwd else unescape_json_fragment(raw or ""))
+    if args:
+        try:
+            return json.dumps(args, ensure_ascii=False, indent=2)
+        except (TypeError, ValueError):
+            pass
+    return unescape_json_fragment(raw or "")
+
+
+def pretty_stream_text(text: str) -> str:
+    """历史里误存的工具 JSON,展示时也按换行还原。"""
+    if not looks_like_tool_args(text):
+        return text
+    guessed = "write"
+    if '"new_string"' in text or '"old_string"' in text:
+        guessed = "search_replace"
+    elif '"command"' in text and '"contents"' not in text and '"content"' not in text:
+        guessed = "run_terminal_command"
+    preview = preview_tool_arguments(guessed, text)
+    return preview or unescape_json_fragment(text)
+
+
+def permit_preview(name: str, arguments: dict | None = None) -> str:
+    args = arguments or {}
+    key = normalize_tool_name(name)
+    if key == "run_terminal_command":
+        cmd = str(args.get("command") or "").strip()
+        return f"$ {cmd}" if cmd else "$ （空命令）"
+    if key == "write":
+        path = str(args.get("file_path") or args.get("target_file") or "")
+        try:
+            dest = _safe_path(path)
+            kind = "覆盖" if dest.is_file() else "新建"
+            return f"write {kind} {_relpath(dest)}"
+        except Exception:
+            return f"write {path}"
+    if key == "search_replace":
+        path = str(args.get("file_path") or "")
+        try:
+            return f"search_replace {_relpath(_safe_path(path))}"
+        except Exception:
+            return f"search_replace {path}"
+    return tool_title(name, args)
+
+
+_DIFF_CONTEXT = 4
+_MAX_HUNKS = 12
+_MAX_HUNK_ROWS = 120
+
+
+def _line_no(text: str, pos: int) -> int:
+    return text.count("\n", 0, max(0, pos)) + 1
+
+
+def _full_line_span(text: str, start: int, end: int) -> tuple[int, int]:
+    if end < start:
+        end = start
+    last = end - 1 if end > start else start
+    if text:
+        last = min(last, len(text) - 1)
+    line_start = text.rfind("\n", 0, start) + 1
+    nl = text.find("\n", last)
+    line_end = nl if nl >= 0 else len(text)
+    return line_start, line_end
+
+
+def _context_before(text: str, pos: int, n: int) -> tuple[list[str], int]:
+    start_line = _line_no(text, pos)
+    if pos <= 0 or n <= 0:
+        return [], start_line
+    prefix = text[:pos]
+    if prefix.endswith("\n"):
+        prefix = prefix[:-1]
+    lines = prefix.splitlines()
+    chunk = lines[-n:]
+    return chunk, start_line - len(chunk)
+
+
+def _context_after(text: str, pos: int, n: int) -> list[str]:
+    if n <= 0 or pos >= len(text):
+        return []
+    suffix = text[pos:]
+    if suffix.startswith("\n"):
+        suffix = suffix[1:]
+    return suffix.splitlines()[:n]
+
+
+def _clip_rows(rows: list[str], cap: int = _MAX_HUNK_ROWS) -> list[str]:
+    if len(rows) <= cap:
+        return rows
+    keep = cap // 2
+    omitted = len(rows) - keep * 2
+    return rows[:keep] + [f" … ({omitted} 行)"] + rows[-keep:]
+
+
+def build_replace_hunks(
+    text: str,
+    old: str,
+    new: str,
+    *,
+    context: int = _DIFF_CONTEXT,
+    replace_all: bool = False,
+) -> list[str]:
+    """把这次替换画成带上下文的 +/- 块,给终端和模型看。"""
+    if not old:
+        return []
+    hunks: list[str] = []
+    start_from = 0
+    while True:
+        idx = text.find(old, start_from)
+        if idx < 0:
+            break
+        end = idx + len(old)
+        ls, le = _full_line_span(text, idx, end)
+        old_block = text[ls:le]
+        new_block = text[ls:idx] + new + text[end:le]
+        old_lines = old_block.splitlines()
+        new_lines = new_block.splitlines()
+        if old_block != "" and not old_lines:
+            old_lines = [""]
+        if new_block != "" and not new_lines:
+            new_lines = [""]
+        before, first_ln = _context_before(text, ls, context)
+        after = _context_after(text, le, context)
+        old_all = before + old_lines + after
+        new_all = before + new_lines + after
+        matcher = difflib.SequenceMatcher(a=old_all, b=new_all, autojunk=False)
+        old_ln = first_ln
+        new_ln = first_ln
+        rows: list[str] = []
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+            if tag == "equal":
+                for line in new_all[j1:j2]:
+                    rows.append(f" {new_ln:>5}|{line}")
+                    new_ln += 1
+                    old_ln += 1
+            elif tag == "delete":
+                for line in old_all[i1:i2]:
+                    rows.append(f"-{old_ln:>5}|{line}")
+                    old_ln += 1
+            elif tag == "insert":
+                for line in new_all[j1:j2]:
+                    rows.append(f"+{new_ln:>5}|{line}")
+                    new_ln += 1
+            else:
+                for line in old_all[i1:i2]:
+                    rows.append(f"-{old_ln:>5}|{line}")
+                    old_ln += 1
+                for line in new_all[j1:j2]:
+                    rows.append(f"+{new_ln:>5}|{line}")
+                    new_ln += 1
+        rows = _clip_rows(rows)
+        if rows:
+            hunks.append("\n".join(rows))
+        start_from = end
+        if not replace_all or old == new:
+            break
+        if len(hunks) >= _MAX_HUNKS:
+            break
+    return hunks
+
+
+def format_replace_result(
+    path: Path,
+    text: str,
+    old: str,
+    new: str,
+    *,
+    count: int,
+    replace_all: bool,
+) -> str:
+    rel = _relpath(path)
+    hunks = build_replace_hunks(text, old, new, replace_all=replace_all)
+    header = f"已替换 {count} 处: {rel}"
+    extra = ""
+    if count > len(hunks) > 0:
+        extra = f"\n…还有 {count - len(hunks)} 处"
+    body = "\n\n".join(hunks)
+    if body:
+        return f"{header}\n\n{body}{extra}"
+    return header
+
+
+def _read_file(args: dict) -> str:
+    path = _safe_path(str(args.get("target_file") or ""))
+    if not path.is_file():
+        return f"不是文件: {path}"
+    text = path.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    offset = int(args.get("offset") or 1)
+    if offset < 1:
+        offset = 1
+    limit = args.get("limit")
+    end = offset - 1 + int(limit) if limit else len(lines)
+    chunk = lines[offset - 1 : end]
+    out = []
+    for i, line in enumerate(chunk, start=offset):
+        out.append(f"{i:>6}|{line}")
+    return _clip("\n".join(out) or "(空文件)")
+
+
+def _search_replace(args: dict) -> str:
+    path = _safe_path(str(args.get("file_path") or ""))
+    old = str(args.get("old_string") or "")
+    new = str(args.get("new_string") or "")
+    replace_all = bool(args.get("replace_all"))
+    if not path.is_file():
+        return f"文件不存在: {_relpath(path)}"
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not old:
+        return "old_string 为空"
+    count = text.count(old)
+    if count == 0:
+        return "找不到 old_string,未修改"
+    if count > 1 and not replace_all:
+        return f"old_string 出现 {count} 次,请加 replace_all 或写更长的上下文"
+    preview = format_replace_result(
+        path, text, old, new, count=count, replace_all=replace_all
+    )
+    _note_write(path)
+    if replace_all:
+        path.write_text(text.replace(old, new), encoding="utf-8")
+    else:
+        path.write_text(text.replace(old, new, 1), encoding="utf-8")
+    return preview
+
+
+def format_write_result(path: Path, old: str, new: str, *, created: bool) -> str:
+    rel = _relpath(path)
+    if created:
+        header = f"已写入 新文件: {rel}"
+        lines = new.splitlines()
+        if not lines and new:
+            lines = [new]
+        rows = [f"+{i:>5}|{line}" for i, line in enumerate(lines, start=1)]
+        body = "\n".join(_clip_rows(rows))
+        return f"{header}\n\n{body}" if body else header
+    if old == new:
+        return f"已覆盖: {rel}（内容相同）"
+    old_lines = old.splitlines()
+    new_lines = new.splitlines()
+    matcher = difflib.SequenceMatcher(a=old_lines, b=new_lines, autojunk=False)
+    old_ln = 1
+    new_ln = 1
+    rows: list[str] = []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == "equal":
+            for line in new_lines[j1:j2]:
+                rows.append(f" {new_ln:>5}|{line}")
+                new_ln += 1
+                old_ln += 1
+        elif tag == "delete":
+            for line in old_lines[i1:i2]:
+                rows.append(f"-{old_ln:>5}|{line}")
+                old_ln += 1
+        elif tag == "insert":
+            for line in new_lines[j1:j2]:
+                rows.append(f"+{new_ln:>5}|{line}")
+                new_ln += 1
+        else:
+            for line in old_lines[i1:i2]:
+                rows.append(f"-{old_ln:>5}|{line}")
+                old_ln += 1
+            for line in new_lines[j1:j2]:
+                rows.append(f"+{new_ln:>5}|{line}")
+                new_ln += 1
+    body = "\n".join(_clip_rows(rows))
+    header = f"已覆盖: {rel}"
+    return f"{header}\n\n{body}" if body else header
+
+
+def _write_file(args: dict) -> str:
+    raw_path = str(args.get("file_path") or args.get("target_file") or args.get("path") or "")
+    path = _safe_path(raw_path)
+    contents = args.get("contents")
+    if contents is None:
+        contents = args.get("content")
+    if contents is None:
+        return "缺少 contents"
+    text = str(contents)
+    created = not path.is_file()
+    old = ""
+    if not created:
+        old = path.read_text(encoding="utf-8", errors="replace")
+    _note_write(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return format_write_result(path, old, text, created=created)
+
+
+def _list_dir(args: dict) -> str:
+    path = _safe_path(str(args.get("target_directory") or "."))
+    if not path.is_dir():
+        return f"不是目录: {path}"
+    names = []
+    for entry in sorted(path.iterdir(), key=lambda p: (p.is_file(), p.name.lower())):
+        if entry.name.startswith("."):
+            continue
+        if entry.name in _SKIP_DIR:
+            continue
+        mark = "/" if entry.is_dir() else ""
+        names.append(entry.name + mark)
+    return "\n".join(names) or "(空目录)"
+
+
+def _rg_path() -> str:
+    """本机装了 ripgrep 就用它;没有返回空串,走纯 Python 的慢路径。"""
+    return shutil.which("rg") or ""
+
+
+def _grep_rg(rg: str, pattern: str, root: Path, glob: str, ignore_case: bool, limit: int) -> str | None:
+    """ripgrep 搜索:自动尊重 .gitignore,跳过二进制,快一个数量级。
+    返回 None 表示 rg 失败(没装或报错),调用方回退到 _grep 慢路径。"""
+    argv = [rg, "--line-number", "--no-heading", "--color", "never"]
+    if ignore_case:
+        argv.append("-i")
+    if glob:
+        argv += ["--glob", glob]
+    argv += ["--", pattern, str(root)]
+    try:
+        proc = subprocess.run(
+            argv,
+            cwd=str(ROOT),
+            capture_output=True,
+            text=True,
+            timeout=30,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode not in (0, 1):
+        return None
+    if proc.returncode == 1 or not proc.stdout.strip():
+        return "无匹配"
+    # head_limit 和慢路径同义:总共最多 limit 行
+    out = "\n".join(proc.stdout.rstrip().splitlines()[: max(1, limit)])
+    # 绝对路径统一转成相对路径展示
+    rel_root = str(ROOT)
+    if out.startswith(rel_root):
+        out = out[len(rel_root) + 1:]
+    return _clip(out)
+
+
+def _grep(args: dict) -> str:
+    pattern = str(args.get("pattern") or "")
+    if not pattern:
+        return "缺少 pattern"
+    flags = re.IGNORECASE if args.get("-i") or args.get("i") else 0
+    try:
+        rx = re.compile(pattern, flags)
+    except re.error as exc:
+        return f"正则无效: {exc}"
+    root = _safe_path(str(args.get("path") or "."))
+    glob = str(args.get("glob") or "")
+    limit = int(args.get("head_limit") or 200)
+    rg = _rg_path()
+    if rg and not root.is_file():
+        hit = _grep_rg(rg, pattern, root, glob, bool(flags), limit)
+        if hit is not None:
+            return hit
+    hits: list[str] = []
+    files: list[Path] = []
+    if root.is_file():
+        files = [root]
+    else:
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in _SKIP_DIR and not d.startswith(".")]
+            for name in filenames:
+                if name.startswith("."):
+                    continue
+                path = Path(dirpath) / name
+                if glob and not path.match(glob) and not path.name.endswith(glob.lstrip("*")):
+                    if glob.startswith("*") and path.name.endswith(glob[1:]):
+                        pass
+                    else:
+                        continue
+                files.append(path)
+    for path in files:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        rel = _relpath(path)
+        for i, line in enumerate(text.splitlines(), start=1):
+            if rx.search(line):
+                hits.append(f"{rel}:{i}:{line}")
+                if len(hits) >= limit:
+                    return "\n".join(hits)
+    return "\n".join(hits) or "无匹配"
+
+
+def _run_cmd(args: dict) -> str:
+    cmd = str(args.get("command") or "").strip()
+    if not cmd:
+        return "缺少 command"
+    cwd = args.get("working_directory") or args.get("cwd")
+    work = _safe_path(str(cwd)) if cwd else ROOT
+    timeout = int(args.get("timeout") or 120)
+    try:
+        proc = subprocess.run(
+            cmd,
+            shell=True,
+            cwd=str(work),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except subprocess.TimeoutExpired:
+        return f"超时 ({timeout}s)"
+    out = (proc.stdout or "") + (proc.stderr or "")
+    code = proc.returncode
+    return _clip(f"exit {code}\n{out}".rstrip() or f"exit {code}")
+
+
+_RUNNING_PROCS: set = set()
+
+
+def _kill_proc_sync(proc) -> None:
+    """杀终端子进程;Windows 用 taskkill 连子进程树一起,失败退回 kill()。"""
+    if sys.platform == "win32":
+        try:
+            subprocess.run(
+                ["taskkill", "/PID", str(proc.pid), "/T", "/F"],
+                capture_output=True,
+                timeout=8,
+            )
+            return
+        except Exception:
+            pass
+    try:
+        proc.kill()
+    except ProcessLookupError:
+        pass
+
+
+async def _kill_proc(proc) -> None:
+    _kill_proc_sync(proc)
+    try:
+        await proc.wait()
+    except Exception:
+        pass
+
+
+def terminate_running_tools() -> None:
+    """打断时强杀还在跑的终端命令(连同子进程,尽力而为)。"""
+    for proc in list(_RUNNING_PROCS):
+        _RUNNING_PROCS.discard(proc)
+        _kill_proc_sync(proc)
+
+
+async def _run_cmd_async(args: dict, on_output=None) -> str:
+    """终端异步版:边跑边把输出推给界面;子进程起不来就退回同步线程池。"""
+    cmd = str(args.get("command") or "").strip()
+    if not cmd:
+        return "缺少 command"
+    cwd = args.get("working_directory") or args.get("cwd")
+    work = _safe_path(str(cwd)) if cwd else ROOT
+    timeout = int(args.get("timeout") or 120)
+    try:
+        proc = await asyncio.create_subprocess_shell(
+            cmd,
+            cwd=str(work),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+    except (NotImplementedError, OSError):
+        return await asyncio.to_thread(_run_cmd, args)
+    _RUNNING_PROCS.add(proc)
+    lines: list[str] = []
+
+    async def _pump() -> None:
+        while True:
+            raw = await proc.stdout.readline()
+            if not raw:
+                break
+            text = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+            lines.append(text)
+            if on_output is not None:
+                try:
+                    on_output("\n".join(lines[-300:]))
+                except Exception:
+                    pass
+
+    try:
+        await asyncio.wait_for(_pump(), timeout=timeout)
+    except asyncio.TimeoutError:
+        await _kill_proc(proc)
+        return _clip(f"超时 ({timeout}s)\n" + "\n".join(lines[-200:]))
+    finally:
+        _RUNNING_PROCS.discard(proc)
+    code = await proc.wait()
+    out = "\n".join(lines)
+    return _clip(f"exit {code}\n{out}".rstrip() or f"exit {code}")
+
+
+def _todo_write(args: dict) -> str:
+    global _TODOS
+    incoming = args.get("todos")
+    if not isinstance(incoming, list):
+        return "todos 必须是数组"
+    by_id = {str(t.get("id")): t for t in _TODOS if isinstance(t, dict)}
+    for item in incoming:
+        if not isinstance(item, dict):
+            continue
+        tid = str(item.get("id") or "")
+        if not tid:
+            continue
+        prev = by_id.get(tid, {})
+        prev.update({k: v for k, v in item.items() if v is not None})
+        by_id[tid] = prev
+    _TODOS = list(by_id.values())
+    hook = _todo_change_hook
+    if hook is not None:
+        try:
+            hook(_TODOS)
+        except Exception:
+            pass
+    lines = []
+    for t in _TODOS:
+        lines.append(f"- [{t.get('status') or 'pending'}] {t.get('id')}: {t.get('content') or ''}")
+    return "\n".join(lines) or "(空清单)"
+
+
+async def _web_search(args: dict) -> str:
+    query = str(args.get("query") or "").strip()
+    if not query:
+        return "缺少 query"
+    n = int(args.get("num_results") or 5)
+    url = "https://html.duckduckgo.com/html/"
+    timeout = aiohttp.ClientTimeout(total=20)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        async with session.post(url, data={"q": query, "kl": "wt-wt"}) as resp:
+            html = await resp.text()
+    titles = re.findall(r'class="result__a"[^>]*>(.*?)</a>', html, flags=re.I | re.S)
+    links = re.findall(r'class="result__url"[^>]*href="([^"]+)"', html, flags=re.I)
+    if not links:
+        links = re.findall(r'uddg=([^"&]+)', html)
+    lines = []
+    for i, title in enumerate(titles[:n]):
+        clean = re.sub("<[^>]+>", "", title)
+        href = links[i] if i < len(links) else ""
+        lines.append(f"{i + 1}. {clean.strip()}\n   {href}")
+    return "\n".join(lines) or "没有搜到结果"
+
+
+async def _web_fetch(args: dict) -> str:
+    url = str(args.get("url") or "").strip()
+    if not url:
+        return "缺少 url"
+    if url.startswith("http://"):
+        url = "https://" + url[len("http://") :]
+    if not url.startswith("https://"):
+        return "只支持 https URL"
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        async with session.get(url) as resp:
+            status = resp.status
+            text = await resp.text()
+    text = re.sub(r"(?is)<script.*?>.*?</script>", " ", text)
+    text = re.sub(r"(?is)<style.*?>.*?</style>", " ", text)
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"\s+", " ", text)
+    body = text.strip() or f"HTTP {status}"
+    return _clip(body)