claxcode 0.1.1__py3-none-any.whl

claxcode/tools/execution.py

@@ -0,0 +1,114 @@
+"""Execution tools."""
+
+import asyncio
+from typing import Any
+
+from claxcode.tools.base import Tool
+from claxcode.tools.registry import tool
+
+# Global flag for tool cancellation
+_tool_cancelled = False
+
+
+def set_tool_cancelled() -> None:
+    """Set the tool cancellation flag."""
+    global _tool_cancelled
+    _tool_cancelled = True
+
+
+def clear_tool_cancelled() -> None:
+    """Reset the cancellation flag (called before each user message)."""
+    global _tool_cancelled
+    _tool_cancelled = False
+
+
+def is_tool_cancelled() -> bool:
+    """Return True if the user requested cancellation (Ctrl+C)."""
+    return _tool_cancelled
+
+
+@tool
+class RunShell(Tool):
+    name = "run_shell"
+    description = "Run a shell command and return stdout/stderr."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "Shell command to execute"},
+            "cwd": {"type": "string", "description": "Working directory", "default": "."},
+            "timeout": {"type": "integer", "default": 60},
+        },
+        "required": ["command"],
+    }
+    category = "execution"
+    required_permissions = ["execute"]
+
+    async def execute(self, command: str, cwd: str = ".", timeout: int = 60, **kwargs: Any) -> str:
+        proc: asyncio.subprocess.Process | None = None
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+            output = stdout.decode("utf-8", errors="replace")
+            if stderr:
+                output += "\n[stderr]\n" + stderr.decode("utf-8", errors="replace")
+            if proc.returncode != 0:
+                output += f"\n[exit code: {proc.returncode}]"
+            return output
+        except TimeoutError:
+            if proc is not None and proc.returncode is None:
+                proc.kill()
+                await proc.wait()
+            return f"Error: Command timed out after {timeout}s"
+        except KeyboardInterrupt:
+            if proc is not None and proc.returncode is None:
+                proc.kill()
+                await proc.wait()
+            raise
+        except Exception as exc:
+            return f"Error: {exc}"
+
+
+@tool
+class RunTests(Tool):
+    name = "run_tests"
+    description = "Run the project's test suite (pytest)."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "target": {"type": "string", "default": ".", "description": "Directory or file to test"},
+            "verbose": {"type": "boolean", "default": True},
+        },
+        "required": [],
+    }
+    category = "execution"
+    required_permissions = ["execute"]
+
+    async def execute(self, target: str = ".", verbose: bool = True, **kwargs: Any) -> str:
+        cmd = f"pytest {target}"
+        if verbose:
+            cmd += " -v"
+        return await RunShell().execute(command=cmd, cwd=".")
+
+
+@tool
+class GitCommand(Tool):
+    name = "git_command"
+    description = "Run a git command."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "args": {"type": "string", "description": "Git arguments, e.g., 'status' or 'diff HEAD'"},
+            "cwd": {"type": "string", "default": "."},
+        },
+        "required": ["args"],
+    }
+    category = "execution"
+    required_permissions = ["execute"]
+
+    async def execute(self, args: str, cwd: str = ".", **kwargs: Any) -> str:
+        return await RunShell().execute(command=f"git {args}", cwd=cwd)

claxcode/tools/file_operations.py

@@ -0,0 +1,287 @@
+"""File operation tools."""
+
+from pathlib import Path
+from typing import Any
+
+from claxcode.tools.base import Tool
+from claxcode.tools.registry import tool
+
+
+@tool
+class ReadFile(Tool):
+    name = "read_file"
+    description = "读取文本文件的内容。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Absolute or relative file path"},
+        },
+        "required": ["path"],
+    }
+    category = "file_operations"
+    required_permissions = ["read"]
+
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        target = Path(path)
+        if not target.exists():
+            return f"错误：文件不存在: {path}"
+        try:
+            return target.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return f"错误：文件可能是二进制文件: {path}"
+
+
+@tool
+class WriteFile(Tool):
+    name = "write_file"
+    description = "将内容写入文件（覆盖或创建）。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "content": {"type": "string"},
+        },
+        "required": ["path", "content"],
+    }
+    category = "file_operations"
+    required_permissions = ["write"]
+
+    async def execute(self, path: str, content: str, **kwargs: Any) -> str:
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        return f"文件已写入: {path}"
+
+
+@tool
+class StrReplaceFile(Tool):
+    name = "str_replace_file"
+    description = "替换文件中的指定字符串。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "old": {"type": "string"},
+            "new": {"type": "string"},
+            "replace_all": {"type": "boolean", "default": False},
+        },
+        "required": ["path", "old", "new"],
+    }
+    category = "file_operations"
+    required_permissions = ["write"]
+
+    async def execute(self, path: str, old: str, new: str, replace_all: bool = False, **kwargs: Any) -> str:
+        target = Path(path)
+        if not target.exists():
+            return f"错误：文件不存在: {path}"
+        text = target.read_text(encoding="utf-8")
+        if old not in text:
+            return f"错误：在 {path} 中未找到要替换的字符串"
+        if replace_all:
+            count = text.count(old)
+            text = text.replace(old, new)
+        else:
+            text = text.replace(old, new, 1)
+            count = 1
+        target.write_text(text, encoding="utf-8")
+        return f"已在 {path} 中替换 {count} 处"
+
+
+@tool
+class ViewFile(Tool):
+    name = "view_file"
+    description = "查看文件内容，带行号，支持分页。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "文件路径"},
+            "view_range": {
+                "type": "array",
+                "items": {"type": "integer"},
+                "minItems": 2,
+                "maxItems": 2,
+                "description": "查看范围 [起始行, 结束行]，1-based",
+            },
+            "max_lines": {"type": "integer", "default": 50, "description": "默认最大显示行数"},
+        },
+        "required": ["path"],
+    }
+    category = "file_operations"
+    required_permissions = ["read"]
+
+    async def execute(self, path: str, view_range: list[int] | None = None, max_lines: int = 50, **kwargs: Any) -> str:
+        target = Path(path)
+        if not target.exists():
+            return f"错误：文件不存在: {path}"
+        try:
+            text = target.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return f"错误：文件可能是二进制文件: {path}"
+
+        lines = text.splitlines()
+        total = len(lines)
+
+        start = 0
+        end = total
+
+        if view_range is not None:
+            start = max(0, view_range[0] - 1)
+            end = min(total, view_range[1])
+        elif total > max_lines:
+            end = max_lines
+
+        width = len(str(total))
+        output_lines = []
+        for i in range(start, end):
+            output_lines.append(f"{i + 1:>{width}} | {lines[i]}")
+
+        result = "\n".join(output_lines)
+
+        if end < total:
+            result += f"\n\n... （共 {total} 行，显示 {start + 1}-{end} 行。使用 view_range 查看更多）"
+
+        return result
+
+
+@tool
+class EditFile(Tool):
+    name = "edit_file"
+    description = "精确编辑文件：使用 old_string / new_string 块进行多行替换，自动验证匹配唯一性。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "文件路径"},
+            "edits": {
+                "type": "array",
+                "description": "编辑块列表，每个块包含 old_string 和 new_string",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "old_string": {"type": "string", "description": "要替换的精确内容（多行）"},
+                        "new_string": {"type": "string", "description": "替换后的内容"},
+                    },
+                    "required": ["old_string", "new_string"],
+                },
+            },
+        },
+        "required": ["path", "edits"],
+    }
+    category = "file_operations"
+    required_permissions = ["write"]
+
+    async def execute(self, path: str, edits: list[dict], **kwargs: Any) -> str:
+        target = Path(path)
+        if not target.exists():
+            return f"错误：文件不存在: {path}"
+        text = target.read_text(encoding="utf-8")
+
+        # 先验证所有编辑块，收集位置信息
+        edit_infos = []
+        for idx, edit in enumerate(edits):
+            old = edit["old_string"]
+            new = edit["new_string"]
+            count = text.count(old)
+
+            if count == 0:
+                # 返回文件前 50 行上下文帮助定位
+                lines = text.splitlines()
+                context_lines = lines[:50]
+                width = len(str(len(lines))) if lines else 1
+                ctx = "\n".join(f"{i + 1:>{width}} | {line}" for i, line in enumerate(context_lines))
+                return f"错误：第 {idx + 1} 个编辑块的 old_string 在文件中未找到。\n\n文件前 {len(context_lines)} 行上下文：\n{ctx}\n\n提示：请核对 old_string 是否完全匹配（包括缩进和换行）。"
+
+            if count > 1:
+                # 收集所有匹配位置
+                matches = []
+                start = 0
+                while True:
+                    pos = text.find(old, start)
+                    if pos == -1:
+                        break
+                    # 计算行号
+                    line_start = text[:pos].count("\n") + 1
+                    line_end = line_start + old.count("\n")
+                    matches.append((line_start, line_end))
+                    start = pos + 1
+                match_lines = "\n".join(f"   - 第 {s}-{e} 行" for s, e in matches)
+                return f"错误：第 {idx + 1} 个编辑块的 old_string 在文件中匹配到 {count} 处：\n{match_lines}\n提示：请增加更多上下文使匹配唯一。"
+
+            # 记录位置（用于从后往前排序）
+            pos = text.find(old)
+            edit_infos.append({"idx": idx, "old": old, "new": new, "pos": pos})
+
+        # 从后往前执行替换（避免位置偏移）
+        edit_infos.sort(key=lambda x: x["pos"], reverse=True)
+        applied = []
+        for info in edit_infos:
+            old = info["old"]
+            new = info["new"]
+            pos = text.find(old)
+            if pos == -1:
+                return (
+                    f"错误：第 {info['idx'] + 1} 个编辑块与前序编辑块冲突"
+                    "（old_string 已被前面的替换覆盖）。文件未修改，请拆分后重试。"
+                )
+            line_start = text[:pos].count("\n") + 1
+            line_end = line_start + old.count("\n")
+            new_line_end = line_start + new.count("\n")
+            text = text[:pos] + new + text[pos + len(old):]
+            applied.append((info["idx"] + 1, line_start, line_end, new_line_end))
+
+        target.write_text(text, encoding="utf-8")
+
+        # 按原始顺序输出结果
+        applied.sort(key=lambda x: x[0])
+        lines = [f"✅ 已编辑: {path}"]
+        for block_num, s, e, ne in applied:
+            if s == e and s == ne:
+                lines.append(f"   块 {block_num}: 第 {s} 行")
+            elif s == e:
+                lines.append(f"   块 {block_num}: 第 {s} 行 → 第 {s}-{ne} 行")
+            else:
+                lines.append(f"   块 {block_num}: 第 {s}-{e} 行 → 第 {s}-{ne} 行")
+        return "\n".join(lines)
+
+
+@tool
+class CreateDirectory(Tool):
+    name = "create_directory"
+    description = "创建目录及必要的父目录。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+        },
+        "required": ["path"],
+    }
+    category = "file_operations"
+    required_permissions = ["write"]
+
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        target = Path(path)
+        target.mkdir(parents=True, exist_ok=True)
+        return f"目录已创建: {path}"
+
+
+@tool
+class RenameFile(Tool):
+    name = "rename_file"
+    description = "重命名或移动文件/目录。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "old_path": {"type": "string"},
+            "new_path": {"type": "string"},
+        },
+        "required": ["old_path", "new_path"],
+    }
+    category = "file_operations"
+    required_permissions = ["write"]
+
+    async def execute(self, old_path: str, new_path: str, **kwargs: Any) -> str:
+        source = Path(old_path)
+        dest = Path(new_path)
+        if not source.exists():
+            return f"错误：源文件不存在: {old_path}"
+        source.rename(dest)
+        return f"已重命名 {old_path} -> {new_path}"

claxcode/tools/memory_tool.py

@@ -0,0 +1,29 @@
+"""Memory tool — lets the agent record durable facts and preferences."""
+
+from typing import Any
+
+from claxcode.memory.auto_memory import auto_memory
+from claxcode.tools.base import Tool
+from claxcode.tools.registry import tool
+
+
+@tool
+class RememberFactTool(Tool):
+    name = "remember_fact"
+    description = (
+        "记录一条稳定的全局用户偏好或事实到自动记忆（键值对），"
+        "以后的会话会自动加载。例如用户偏好的语言和通用回答风格。"
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "key": {"type": "string", "description": "事实名称，如 '回复语言'"},
+            "value": {"type": "string", "description": "事实内容，如 '始终使用中文'"},
+        },
+        "required": ["key", "value"],
+    }
+    category = "memory"
+    required_permissions = ["write"]
+
+    async def execute(self, key: str, value: str, **kwargs: Any) -> str:
+        return auto_memory.remember(key, value)

claxcode/tools/registry.py

@@ -0,0 +1,35 @@
+"""Tool registry with decorator-based registration."""
+
+
+from claxcode.tools.base import Tool
+
+
+class ToolRegistry:
+    """Central registry for tools."""
+
+    def __init__(self):
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> Tool:
+        self._tools[tool.name] = tool
+        return tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def unregister(self, name: str) -> bool:
+        """Remove a tool from the registry. Returns True if removed."""
+        return self._tools.pop(name, None) is not None
+
+
+registry = ToolRegistry()
+
+
+def tool(cls: type[Tool]) -> type[Tool]:
+    """Decorator to auto-register a Tool subclass."""
+    instance = cls()
+    registry.register(instance)
+    return cls

claxcode/tools/search.py

@@ -0,0 +1,157 @@
+"""Search tools."""
+
+import fnmatch
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from claxcode.tools.base import Tool
+from claxcode.tools.registry import tool
+
+# 依赖/缓存目录：搜索时跳过，避免扫入海量无关文件
+IGNORED_DIRS = {
+    ".git", ".hg", ".svn",
+    ".venv", "venv", "node_modules", "__pycache__",
+    ".pytest_cache", ".ruff_cache", ".mypy_cache", ".tox", ".eggs",
+    ".claxcode", ".idea", "dist", "build",
+}
+
+
+def _iter_files(root: Path) -> Iterator[Path]:
+    """Recursively yield files under root, pruning dependency/cache dirs."""
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = sorted(current.iterdir())
+        except OSError:
+            continue
+        for p in entries:
+            if p.is_dir():
+                if p.name not in IGNORED_DIRS:
+                    stack.append(p)
+            elif p.is_file():
+                yield p
+
+
+@tool
+class GlobSearch(Tool):
+    name = "glob_search"
+    description = "递归查找匹配 glob 模式的文件（自动跳过 .git/.venv/node_modules 等目录）。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Glob pattern, e.g., src/**/*.py"},
+            "directory": {"type": "string", "default": "."},
+        },
+        "required": ["pattern"],
+    }
+    category = "search"
+    required_permissions = ["read"]
+
+    async def execute(self, pattern: str, directory: str = ".", **kwargs: Any) -> str:
+        root = Path(directory)
+        matches = []
+        for p in _iter_files(root):
+            rel = str(p.relative_to(root))
+            if fnmatch.fnmatch(rel, pattern):
+                matches.append(rel)
+        if not matches:
+            return "未找到文件。"
+        note = f"\n... [已截断，共 {len(matches)} 个]" if len(matches) > 200 else ""
+        return "\n".join(matches[:200]) + note
+
+
+@tool
+class GrepSearch(Tool):
+    name = "grep_search"
+    description = "使用正则表达式搜索文件内容（自动跳过 .git/.venv/node_modules 等目录）。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Regex pattern to search for"},
+            "directory": {"type": "string", "default": "."},
+            "glob": {"type": "string", "default": "*"},
+            "output_mode": {
+                "type": "string",
+                "enum": ["content", "files_with_matches"],
+                "default": "content",
+            },
+        },
+        "required": ["pattern"],
+    }
+    category = "search"
+    required_permissions = ["read"]
+
+    async def execute(
+        self,
+        pattern: str,
+        directory: str = ".",
+        glob: str = "*",
+        output_mode: str = "content",
+        **kwargs: Any,
+    ) -> str:
+        root = Path(directory)
+        regex = re.compile(pattern)
+        results = []
+        for p in _iter_files(root):
+            if not fnmatch.fnmatch(p.name, glob):
+                continue
+            try:
+                text = p.read_text(encoding="utf-8")
+            except Exception:
+                continue
+            if not regex.search(text):
+                continue
+            if output_mode == "files_with_matches":
+                results.append(str(p.relative_to(root)))
+            else:
+                for i, line in enumerate(text.splitlines(), 1):
+                    if regex.search(line):
+                        results.append(f"{p.relative_to(root)}:{i}:{line}")
+        if not results:
+            return "未找到匹配项。"
+        note = f"\n... [已截断，共 {len(results)} 条]" if len(results) > 250 else ""
+        return "\n".join(results[:250]) + note
+
+
+@tool
+class ExploreCodebase(Tool):
+    name = "explore_codebase"
+    description = "高级探索：列出顶层文件并总结结构。"
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "directory": {"type": "string", "default": "."},
+            "depth": {"type": "integer", "default": 2},
+        },
+        "required": [],
+    }
+    category = "search"
+    required_permissions = ["read"]
+
+    async def execute(self, directory: str = ".", depth: int = 2, **kwargs: Any) -> str:
+        root = Path(directory)
+        lines = []
+
+        def walk(current: Path, current_depth: int):
+            if current_depth > depth:
+                return
+            prefix = "  " * current_depth
+            try:
+                entries = sorted(current.iterdir())
+            except OSError:
+                return
+            for p in entries:
+                if p.name in IGNORED_DIRS:
+                    continue
+                if p.name.startswith(".") and p.name not in {".gitignore", ".env"}:
+                    continue
+                lines.append(f"{prefix}{p.name}{'/' if p.is_dir() else ''}")
+                if p.is_dir():
+                    walk(p, current_depth + 1)
+
+        if root.exists():
+            walk(root, 0)
+        return "\n".join(lines) if lines else "空目录。"