nexforge-cli 0.1.0__py3-none-any.whl

nexforge/tools/edit_file.py

@@ -0,0 +1,73 @@
+"""edit_file 工具:SEARCH/REPLACE 精确替换(唯一匹配)。"""
+
+from __future__ import annotations
+
+from nexforge.tools._paths import resolve
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class EditFileTool(BaseTool):
+    name = "edit_file"
+    description = (
+        "对文件做一次精确替换:把 search 文本替换为 replace。"
+        "search 必须在文件中唯一出现,否则拒绝。search 留空则创建新文件。"
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "目标文件路径"},
+            "search": {"type": "string", "description": "要查找的原文(需唯一);留空表示新建文件"},
+            "replace": {"type": "string", "description": "替换后的文本(新建时为全文)"},
+        },
+        "required": ["path", "replace"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"edit_file({args.get('path', '')})"
+
+    def run(self, path: str, replace: str, search: str = "") -> ToolResult:
+        fp = resolve(path)
+
+        # 新建文件
+        if not search:
+            if fp.exists():
+                return ToolResult(
+                    ok=False,
+                    error=f"文件已存在,无法以空 search 新建:{path}(请提供 search 做替换)",
+                )
+            try:
+                fp.parent.mkdir(parents=True, exist_ok=True)
+                fp.write_text(replace, encoding="utf-8")
+            except Exception as exc:
+                return ToolResult(ok=False, error=f"写入失败:{exc}")
+            return ToolResult(ok=True, output=f"已创建 {path}", summary=f"新建 {path}")
+
+        if not fp.exists():
+            return ToolResult(ok=False, error=f"文件不存在:{path}")
+        try:
+            text = fp.read_text(encoding="utf-8")
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"读取失败:{exc}")
+
+        occurrences = text.count(search)
+        if occurrences == 0:
+            return ToolResult(ok=False, error="未找到 search 文本(需逐字节匹配)")
+        if occurrences > 1:
+            return ToolResult(
+                ok=False,
+                error=f"search 文本出现 {occurrences} 次,不唯一;请扩大上下文使其唯一。",
+            )
+        new_text = text.replace(search, replace, 1)
+        try:
+            fp.write_text(new_text, encoding="utf-8")
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"写入失败:{exc}")
+
+        delta = new_text.count("\n") - text.count("\n")
+        return ToolResult(
+            ok=True,
+            output=f"已修改 {path}(行数变化 {delta:+d})",
+            summary=f"编辑 {path}",
+        )

nexforge/tools/fs_ops.py

@@ -0,0 +1,125 @@
+"""文件系统操作工具:create_dir / move / copy / delete。"""
+
+from __future__ import annotations
+
+import shutil
+
+from nexforge.tools._paths import resolve
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class CreateDirTool(BaseTool):
+    name = "create_dir"
+    description = "创建目录(含必要的父目录)。"
+    parameters = {
+        "type": "object",
+        "properties": {"path": {"type": "string", "description": "目录路径"}},
+        "required": ["path"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"create_dir({args.get('path', '')})"
+
+    def run(self, path: str) -> ToolResult:
+        try:
+            resolve(path).mkdir(parents=True, exist_ok=True)
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"创建失败:{exc}")
+        return ToolResult(ok=True, output=f"已创建目录 {path}", summary=f"mkdir {path}")
+
+
+class MoveTool(BaseTool):
+    name = "move"
+    description = "移动 / 重命名文件或目录。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "source": {"type": "string"},
+            "destination": {"type": "string"},
+        },
+        "required": ["source", "destination"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"move({args.get('source', '')} → {args.get('destination', '')})"
+
+    def run(self, source: str, destination: str) -> ToolResult:
+        src = resolve(source)
+        dst = resolve(destination)
+        if not src.exists():
+            return ToolResult(ok=False, error=f"源不存在:{source}")
+        try:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(src), str(dst))
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"移动失败:{exc}")
+        return ToolResult(ok=True, output=f"已移动 {source} → {destination}",
+                          summary=f"move {source}")
+
+
+class CopyTool(BaseTool):
+    name = "copy"
+    description = "复制文件或目录(目标不存在时才复制)。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "source": {"type": "string"},
+            "destination": {"type": "string"},
+        },
+        "required": ["source", "destination"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"copy({args.get('source', '')} → {args.get('destination', '')})"
+
+    def run(self, source: str, destination: str) -> ToolResult:
+        src = resolve(source)
+        dst = resolve(destination)
+        if not src.exists():
+            return ToolResult(ok=False, error=f"源不存在:{source}")
+        if dst.exists():
+            return ToolResult(ok=False, error=f"目标已存在:{destination}")
+        try:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            if src.is_dir():
+                shutil.copytree(str(src), str(dst))
+            else:
+                shutil.copy2(str(src), str(dst))
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"复制失败:{exc}")
+        return ToolResult(ok=True, output=f"已复制 {source} → {destination}",
+                          summary=f"copy {source}")
+
+
+class DeleteTool(BaseTool):
+    name = "delete"
+    description = "删除文件或目录(目录递归删除)。危险操作,需审批。"
+    parameters = {
+        "type": "object",
+        "properties": {"path": {"type": "string"}},
+        "required": ["path"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"delete({args.get('path', '')})"
+
+    def run(self, path: str) -> ToolResult:
+        fp = resolve(path)
+        if not fp.exists():
+            return ToolResult(ok=False, error=f"不存在:{path}")
+        try:
+            if fp.is_dir():
+                shutil.rmtree(str(fp))
+            else:
+                fp.unlink()
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"删除失败:{exc}")
+        return ToolResult(ok=True, output=f"已删除 {path}", summary=f"delete {path}")

nexforge/tools/git.py

@@ -0,0 +1,89 @@
+"""Git 工具:git_status / git_diff(只读)、git_commit(审批)。"""
+
+from __future__ import annotations
+
+import subprocess
+
+from nexforge.tools._paths import truncate
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+def _git(args: list[str], timeout: int = 20) -> tuple[int, str]:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            stdin=subprocess.DEVNULL,  # 避免继承无效句柄(pytest/无 tty 场景)
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+    except FileNotFoundError:
+        return 127, "未找到 git 命令"
+    except subprocess.TimeoutExpired:
+        return 124, "git 命令超时"
+    except OSError as exc:
+        return 1, f"git 执行失败:{exc}"
+
+
+class GitStatusTool(BaseTool):
+    name = "git_status"
+    description = "查看 git 工作区状态(git status --short + 当前分支)。"
+    parameters = {"type": "object", "properties": {}}
+
+    def run(self) -> ToolResult:
+        code, out = _git(["status", "--short", "--branch"])
+        if code != 0:
+            return ToolResult(ok=False, error=out.strip() or "git status 失败")
+        return ToolResult(
+            ok=True, output=truncate(out.strip()) or "(工作区干净)", summary="git status"
+        )
+
+
+class GitDiffTool(BaseTool):
+    name = "git_diff"
+    description = "查看 git 差异。默认工作区未暂存改动;staged=true 看已暂存。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "staged": {"type": "boolean", "description": "是否看已暂存改动"},
+            "path": {"type": "string", "description": "限定路径(可选)"},
+        },
+    }
+
+    def run(self, staged: bool = False, path: str = "") -> ToolResult:
+        args = ["diff"]
+        if staged:
+            args.append("--staged")
+        if path:
+            args.append(path)
+        code, out = _git(args)
+        if code != 0:
+            return ToolResult(ok=False, error=out.strip() or "git diff 失败")
+        return ToolResult(ok=True, output=truncate(out) or "(无差异)", summary="git diff")
+
+
+class GitCommitTool(BaseTool):
+    name = "git_commit"
+    description = "暂存全部改动并提交(git add -A && git commit -m)。需审批。"
+    parameters = {
+        "type": "object",
+        "properties": {"message": {"type": "string", "description": "提交信息"}},
+        "required": ["message"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"git_commit({args.get('message', '')[:40]!r})"
+
+    def run(self, message: str) -> ToolResult:
+        code, out = _git(["add", "-A"])
+        if code != 0:
+            return ToolResult(ok=False, error=f"git add 失败:{out.strip()}")
+        code, out = _git(["commit", "-m", message])
+        if code != 0:
+            return ToolResult(ok=False, error=out.strip() or "git commit 失败")
+        return ToolResult(ok=True, output=truncate(out.strip()), summary="git commit")

nexforge/tools/list_dir.py

@@ -0,0 +1,49 @@
+"""list_dir 工具:列出目录内容。"""
+
+from __future__ import annotations
+
+from nexforge.tools._paths import resolve, truncate
+from nexforge.tools.base import BaseTool, ToolResult
+
+_SKIP = {".git", "__pycache__", ".venv", "node_modules", ".mypy_cache", ".pytest_cache"}
+
+
+class ListDirTool(BaseTool):
+    name = "list_dir"
+    description = "列出目录内容。recursive=true 时递归展示(跳过依赖/缓存目录)。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "目录路径,默认当前目录"},
+            "recursive": {"type": "boolean", "description": "是否递归,默认 false"},
+        },
+    }
+
+    def run(self, path: str = ".", recursive: bool = False) -> ToolResult:
+        dp = resolve(path)
+        if not dp.exists():
+            return ToolResult(ok=False, error=f"目录不存在:{path}")
+        if not dp.is_dir():
+            return ToolResult(ok=False, error=f"不是目录:{path}")
+
+        lines: list[str] = []
+        count = 0
+        if recursive:
+            for child in sorted(dp.rglob("*")):
+                if any(part in _SKIP for part in child.relative_to(dp).parts):
+                    continue
+                rel = child.relative_to(dp).as_posix()
+                lines.append(rel + ("/" if child.is_dir() else ""))
+                count += 1
+        else:
+            for child in sorted(dp.iterdir()):
+                if child.name in _SKIP:
+                    continue
+                lines.append(child.name + ("/" if child.is_dir() else ""))
+                count += 1
+
+        return ToolResult(
+            ok=True,
+            output=truncate("\n".join(lines) or "(空目录)"),
+            summary=f"{path} — {count} 项",
+        )

nexforge/tools/multi_edit.py

@@ -0,0 +1,84 @@
+"""multi_edit 工具:跨文件原子批量 SEARCH/REPLACE。
+
+所有编辑先校验(search 唯一匹配),全部通过才落盘;任一失败则全部不改。
+"""
+
+from __future__ import annotations
+
+from nexforge.tools._paths import resolve
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class MultiEditTool(BaseTool):
+    name = "multi_edit"
+    description = (
+        "跨一个或多个文件原子地做多处 SEARCH/REPLACE。edits 数组按顺序应用,"
+        "每个 search 需在其目标文件中唯一。任一失败则全部不改(原子)。"
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "edits": {
+                "type": "array",
+                "description": "编辑列表",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "search": {"type": "string"},
+                        "replace": {"type": "string"},
+                    },
+                    "required": ["path", "search", "replace"],
+                },
+            }
+        },
+        "required": ["edits"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        edits = args.get("edits", [])
+        n = len(edits) if isinstance(edits, list) else 0
+        return f"multi_edit({n} 处)"
+
+    def run(self, edits: list) -> ToolResult:
+        if not edits:
+            return ToolResult(ok=False, error="edits 为空")
+
+        # 阶段一:把每个文件读进内存,顺序应用并校验,不落盘
+        buffers: dict[str, str] = {}
+        for i, ed in enumerate(edits):
+            path = ed.get("path", "")
+            search = ed.get("search", "")
+            replace = ed.get("replace", "")
+            fp = resolve(path)
+            if path not in buffers:
+                if not fp.exists():
+                    return ToolResult(ok=False, error=f"[edit {i}] 文件不存在:{path}")
+                try:
+                    buffers[path] = fp.read_text(encoding="utf-8")
+                except Exception as exc:
+                    return ToolResult(ok=False, error=f"[edit {i}] 读取失败:{exc}")
+            text = buffers[path]
+            count = text.count(search)
+            if count == 0:
+                return ToolResult(ok=False, error=f"[edit {i}] 未找到 search:{path}")
+            if count > 1:
+                return ToolResult(
+                    ok=False, error=f"[edit {i}] search 不唯一({count} 次):{path}"
+                )
+            buffers[path] = text.replace(search, replace, 1)
+
+        # 阶段二:全部校验通过 → 落盘
+        try:
+            for path, text in buffers.items():
+                resolve(path).write_text(text, encoding="utf-8")
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"写入失败:{exc}")
+
+        return ToolResult(
+            ok=True,
+            output=f"已应用 {len(edits)} 处编辑,涉及 {len(buffers)} 个文件",
+            summary=f"multi_edit {len(edits)}处/{len(buffers)}文件",
+        )

nexforge/tools/read_file.py

@@ -0,0 +1,51 @@
+"""read_file 工具:读取文件内容,支持行范围。"""
+
+from __future__ import annotations
+
+from nexforge.tools._paths import resolve, truncate
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class ReadFileTool(BaseTool):
+    name = "read_file"
+    description = "读取文本文件内容。可选 start_line/end_line 指定 1-based 闭区间行范围。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "文件路径(相对当前目录或绝对)"},
+            "start_line": {"type": "integer", "description": "起始行(1-based,含)"},
+            "end_line": {"type": "integer", "description": "结束行(1-based,含)"},
+        },
+        "required": ["path"],
+    }
+
+    def preview(self, args: dict) -> str:
+        p = args.get("path", "")
+        s, e = args.get("start_line"), args.get("end_line")
+        if s or e:
+            return f"read_file({p}:{s or ''}-{e or ''})"
+        return f"read_file({p})"
+
+    def run(self, path: str, start_line: int | None = None, end_line: int | None = None) -> ToolResult:
+        fp = resolve(path)
+        if not fp.exists():
+            return ToolResult(ok=False, error=f"文件不存在:{path}")
+        if fp.is_dir():
+            return ToolResult(ok=False, error=f"是目录而非文件:{path}")
+        try:
+            text = fp.read_text(encoding="utf-8", errors="replace")
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"读取失败:{exc}")
+
+        lines = text.splitlines()
+        total = len(lines)
+        s = max(1, start_line or 1)
+        e = min(total, end_line or total)
+        chosen = lines[s - 1 : e]
+        width = len(str(e))
+        body = "\n".join(f"{i + s:>{width}} | {ln}" for i, ln in enumerate(chosen))
+        return ToolResult(
+            ok=True,
+            output=truncate(body),
+            summary=f"{path} 第 {s}-{e} 行(共 {total} 行)",
+        )

nexforge/tools/registry.py

@@ -0,0 +1,94 @@
+"""工具注册表。default_registry() 返回内置核心工具集(M1)。"""
+
+from __future__ import annotations
+
+import json
+
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> BaseTool | None:
+        return self._tools.get(name)
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def specs(self) -> list[dict]:
+        """所有工具的 OpenAI function-calling schema。"""
+        return [t.to_openai() for t in self._tools.values()]
+
+    def parse_args(self, raw: str) -> dict:
+        if not raw or not raw.strip():
+            return {}
+        try:
+            data = json.loads(raw)
+            return data if isinstance(data, dict) else {}
+        except json.JSONDecodeError:
+            return {}
+
+    def execute(self, name: str, arguments: dict) -> ToolResult:
+        tool = self.get(name)
+        if tool is None:
+            return ToolResult(ok=False, error=f"未知工具:{name}")
+        try:
+            return tool.run(**arguments)
+        except TypeError as exc:
+            return ToolResult(ok=False, error=f"参数错误:{exc}")
+        except Exception as exc:  # 工具内部未捕获异常
+            return ToolResult(ok=False, error=f"工具执行异常:{exc}")
+
+
+def default_registry() -> ToolRegistry:
+    from nexforge.tools.background import (
+        JobOutputTool,
+        ListJobsTool,
+        RunBackgroundTool,
+        StopJobTool,
+        WaitForJobTool,
+    )
+    from nexforge.tools.edit_file import EditFileTool
+    from nexforge.tools.fs_ops import CopyTool, CreateDirTool, DeleteTool, MoveTool
+    from nexforge.tools.git import GitDiffTool, GitStatusTool
+    from nexforge.tools.list_dir import ListDirTool
+    from nexforge.tools.multi_edit import MultiEditTool
+    from nexforge.tools.read_file import ReadFileTool
+    from nexforge.tools.search_content import SearchContentTool
+    from nexforge.tools.search_files import SearchFilesTool
+    from nexforge.tools.shell import ShellTool
+    from nexforge.tools.web import WebFetchTool
+    from nexforge.tools.write_file import WriteFileTool
+
+    reg = ToolRegistry()
+    for tool in (
+        # 读
+        ReadFileTool(), ListDirTool(),
+        # 搜索
+        SearchContentTool(), SearchFilesTool(),
+        # 写
+        WriteFileTool(), EditFileTool(), MultiEditTool(),
+        # 文件操作
+        CreateDirTool(), MoveTool(), CopyTool(), DeleteTool(),
+        # Shell + 后台作业
+        ShellTool(),
+        RunBackgroundTool(), JobOutputTool(), WaitForJobTool(),
+        StopJobTool(), ListJobsTool(),
+        # Web + Git(只读)
+        WebFetchTool(),
+        GitStatusTool(), GitDiffTool(),
+    ):
+        reg.register(tool)
+    return reg
+
+
+def register_git_commit(reg: ToolRegistry) -> None:
+    """按配置开启 git_commit(默认关闭,避免误提交)。"""
+    from nexforge.tools.git import GitCommitTool
+
+    reg.register(GitCommitTool())

nexforge/tools/search_content.py

@@ -0,0 +1,90 @@
+"""search_content 工具:内容 grep(支持正则、glob 过滤、上下文)。"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from nexforge.tools._paths import resolve, truncate
+from nexforge.tools.base import BaseTool, ToolResult
+
+_SKIP_DIRS = {".git", "__pycache__", ".venv", "node_modules", ".mypy_cache",
+              ".pytest_cache", "dist", "build", ".nexforge"}
+_MAX_HITS = 200
+
+
+class SearchContentTool(BaseTool):
+    name = "search_content"
+    description = (
+        "在文件内容中搜索(正则)。可用 glob 过滤文件名(如 *.py),"
+        "context 指定上下文行数。返回 path:line: text。"
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "正则表达式"},
+            "path": {"type": "string", "description": "起始目录,默认当前目录"},
+            "glob": {"type": "string", "description": "文件名 glob,如 *.py"},
+            "context": {"type": "integer", "description": "上下文行数,默认 0"},
+        },
+        "required": ["pattern"],
+    }
+
+    def preview(self, args: dict) -> str:
+        return f"search_content({args.get('pattern', '')!r})"
+
+    def run(self, pattern: str, path: str = ".", glob: str = "*", context: int = 0) -> ToolResult:
+        base = resolve(path)
+        if not base.exists():
+            return ToolResult(ok=False, error=f"路径不存在:{path}")
+        try:
+            rx = re.compile(pattern)
+        except re.error as exc:
+            return ToolResult(ok=False, error=f"正则错误:{exc}")
+
+        files = [base] if base.is_file() else base.rglob(glob or "*")
+        hits: list[str] = []
+        n_files = 0
+        for fp in files:
+            if not fp.is_file():
+                continue
+            if any(part in _SKIP_DIRS for part in fp.parts):
+                continue
+            try:
+                lines = fp.read_text(encoding="utf-8", errors="ignore").splitlines()
+            except Exception:
+                continue
+            rel = self._rel(fp, base)
+            matched_here = False
+            for idx, line in enumerate(lines):
+                if rx.search(line):
+                    matched_here = True
+                    lo = max(0, idx - context)
+                    hi = min(len(lines), idx + context + 1)
+                    for j in range(lo, hi):
+                        sep = ":" if j == idx else "-"
+                        hits.append(f"{rel}:{j + 1}{sep} {lines[j]}")
+                        if len(hits) >= _MAX_HITS:
+                            break
+                if len(hits) >= _MAX_HITS:
+                    break
+            if matched_here:
+                n_files += 1
+            if len(hits) >= _MAX_HITS:
+                hits.append(f"… 命中过多,已截断到 {_MAX_HITS} 行")
+                break
+
+        if not hits:
+            return ToolResult(ok=True, output="(无匹配)", summary=f"{pattern} — 0 命中")
+        return ToolResult(
+            ok=True,
+            output=truncate("\n".join(hits)),
+            summary=f"{pattern} — {n_files} 个文件命中",
+        )
+
+    @staticmethod
+    def _rel(fp: Path, base: Path) -> str:
+        try:
+            return fp.relative_to(base if base.is_dir() else base.parent).as_posix()
+        except ValueError:
+            return fp.as_posix()