devmate 1.0.0__py3-none-any.whl

devmate_agent/__init__.py

@@ -0,0 +1,440 @@
+"""
+agent-harness — Agent 执行引擎
+
+核心能力：
+  - Tool 注册与发现（从模块 CLI 自动推断）
+  - ReAct 循环（思考→工具→思考→输出）
+  - LLM 集成（通过 apihub）
+  - 会话记忆（滑动窗口）
+  - 预置 Agent（code-reviewer, file-butler）
+  - 执行轨迹（Trace）
+"""
+
+import re
+import textwrap
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from devmate.bus.command import CommandResult
+
+# ═══════════════════════════════════════════════════
+# Tool 系统
+# ═══════════════════════════════════════════════════
+
+@dataclass
+class ToolParam:
+    """工具参数定义"""
+    name: str
+    type: str = "string"       # string / integer / boolean / array
+    description: str = ""
+    required: bool = False
+
+
+@dataclass
+class Tool:
+    """工具定义——Agent 可调用的能力"""
+    name: str
+    description: str
+    parameters: list[ToolParam] = field(default_factory=list)
+    handler: Callable | None = None
+
+    def to_dict(self) -> dict:
+        """转为 OpenAI function calling 格式"""
+        props = {}
+        required = []
+        for p in self.parameters:
+            props[p.name] = {
+                "type": p.type,
+                "description": p.description,
+            }
+            if p.required:
+                required.append(p.name)
+
+        schema: dict[str, Any] = {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+            },
+        }
+        if props:
+            schema["function"]["parameters"] = {
+                "type": "object",
+                "properties": props,
+            }
+            if required:
+                schema["function"]["parameters"]["required"] = required
+        return schema
+
+
+class ToolRegistry:
+    """工具注册中心"""
+
+    def __init__(self):
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool):
+        """注册工具"""
+        self._tools[tool.name] = tool
+
+    def register_builtin(self):
+        """注册内置工具"""
+        self.register(Tool(
+            name="execute_python",
+            description="执行 Python 代码并返回结果",
+            parameters=[
+                ToolParam(
+                    name="code", type="string",
+                    description="要执行的 Python 代码", required=True,
+                ),
+            ],
+            handler=self._handle_execute_python,
+        ))
+        self.register(Tool(
+            name="read_file",
+            description="读取文件内容",
+            parameters=[
+                ToolParam(name="path", type="string", description="文件路径", required=True),
+            ],
+            handler=self._handle_read_file,
+        ))
+        self.register(Tool(
+            name="write_file",
+            description="写入文件内容",
+            parameters=[
+                ToolParam(name="path", type="string", description="文件路径", required=True),
+                ToolParam(name="content", type="string", description="文件内容", required=True),
+            ],
+            handler=self._handle_write_file,
+        ))
+        self.register(Tool(
+            name="list_files",
+            description="列出目录中的文件",
+            parameters=[
+                ToolParam(name="path", type="string", description="目录路径", required=True),
+            ],
+            handler=self._handle_list_files,
+        ))
+        self.register(Tool(
+            name="run_command",
+            description="运行 shell 命令并返回输出",
+            parameters=[
+                ToolParam(name="command", type="string", description="要运行的命令", required=True),
+            ],
+            handler=self._handle_run_command,
+        ))
+        self.register(Tool(
+            name="search_text",
+            description="在文件中搜索文本",
+            parameters=[
+                ToolParam(name="pattern", type="string", description="搜索模式", required=True),
+                ToolParam(name="path", type="string", description="搜索路径", required=True),
+            ],
+            handler=self._handle_search_text,
+        ))
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[dict]:
+        return [t.to_dict() for t in self._tools.values()]
+
+    # ── 内置工具处理器 ──────────────────────────
+
+    def _handle_execute_python(self, code: str) -> str:
+        try:
+            local_ns: dict[str, Any] = {}
+            exec(code, {"__builtins__": __builtins__}, local_ns)
+            # 取最后一个表达式的值
+            output = "\n".join(f"{k} = {v}" for k, v in local_ns.items() if not k.startswith("_"))
+            return output or "(无返回值)"
+        except Exception as e:
+            return f"执行错误: {e}"
+
+    def _handle_read_file(self, path: str) -> str:
+        p = Path(path).expanduser()
+        if not p.exists():
+            return f"文件不存在: {path}"
+        try:
+            content = p.read_text(encoding="utf-8", errors="replace")
+            if len(content) > 5000:
+                content = content[:5000] + "\n...(截断)"
+            return content
+        except Exception as e:
+            return f"读取失败: {e}"
+
+    def _handle_write_file(self, path: str, content: str) -> str:
+        p = Path(path).expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return f"已写入 {len(content)} 字节到 {path}"
+
+    def _handle_list_files(self, path: str) -> str:
+        p = Path(path).expanduser()
+        if not p.is_dir():
+            return f"目录不存在: {path}"
+        files = [str(f.relative_to(p)) for f in p.iterdir() if not f.name.startswith(".")]
+        return "\n".join(files) if files else "(空目录)"
+
+    def _handle_run_command(self, command: str) -> str:
+        import subprocess
+        try:
+            result = subprocess.run(command, shell=True, capture_output=True,
+                                    text=True, timeout=30)
+            out = result.stdout[-3000:]
+            if result.stderr:
+                out += "\n[stderr]\n" + result.stderr[-1000:]
+            return out or "(无输出)"
+        except subprocess.TimeoutExpired:
+            return "命令执行超时（30s）"
+        except Exception as e:
+            return f"执行失败: {e}"
+
+    def _handle_search_text(self, pattern: str, path: str) -> str:
+        p = Path(path).expanduser()
+        if not p.exists():
+            return f"路径不存在: {path}"
+        try:
+            compiled = re.compile(pattern)
+            matches = []
+            files = [p] if p.is_file() else list(p.rglob("*"))[:100]
+            for f in files:
+                if f.is_file() and f.suffix not in (".pyc", ".so", ".dll"):
+                    try:
+                        for i, line in enumerate(f.read_text(errors="ignore").split("\n"), 1):
+                            if compiled.search(line):
+                                rel = str(f.relative_to(p) if p.is_dir() else f.name)
+                                matches.append(f"{rel}:{i}: {line.strip()[:80]}")
+                    except Exception:
+                        continue
+            return "\n".join(matches[:30]) or "(无匹配)"
+        except re.error as e:
+            return f"正则错误: {e}"
+
+
+# ═══════════════════════════════════════════════════
+# Agent Runtime
+# ═══════════════════════════════════════════════════
+
+@dataclass
+class TraceStep:
+    """单步执行轨迹"""
+    step: int
+    type: str                # "thought" / "tool_call" / "tool_result" / "output"
+    content: str = ""
+    tool_name: str = ""
+    tool_args: dict = field(default_factory=dict)
+    tool_result: str = ""
+    duration_ms: float = 0.0
+
+
+@dataclass
+class SessionMemory:
+    """会话记忆（滑动窗口）"""
+    messages: list[dict] = field(default_factory=list)
+    max_turns: int = 10
+
+    def add(self, role: str, content: str):
+        self.messages.append({"role": role, "content": content})
+        # 滑动窗口：保留最近的 max_turns*2 条消息
+        if len(self.messages) > self.max_turns * 2:
+            # 保留 system prompt（第一条）
+            if self.messages[0]["role"] == "system":
+                self.messages = [self.messages[0]] + self.messages[-(self.max_turns * 2 - 1):]
+            else:
+                self.messages = self.messages[-(self.max_turns * 2):]
+
+    def get_messages(self) -> list[dict]:
+        return self.messages
+
+    def clear(self):
+        self.messages = []
+
+
+class AgentRuntime:
+    """Agent 运行时——ReAct 循环"""
+
+    def __init__(self, system_prompt: str = ""):
+        self.tools = ToolRegistry()
+        self.tools.register_builtin()
+        self.memory = SessionMemory()
+        self.trace: list[TraceStep] = []
+        self.system_prompt = system_prompt or self._default_system_prompt()
+
+    def _default_system_prompt(self) -> str:
+        return textwrap.dedent("""\
+            你是一个 DevMate 智能助手，可以调用工具来帮助用户完成任务。
+            请按照以下流程工作：
+            1. 理解用户的请求
+            2. 如果需要工具，调用合适的工具
+            3. 根据工具返回的结果，继续思考或给出最终答案
+
+            可用的工具：
+            """)
+
+    def run(self, user_message: str, max_steps: int = 10) -> CommandResult:
+        """运行 Agent（简化版——直接解析工具指令）"""
+        start = time.time()
+        self.memory.add("user", user_message)
+
+        tool_instructions = re.findall(
+            r'!(\w+)\(([^)]*)\)', user_message
+        )
+
+        steps: list[dict] = []
+        output_parts: list[str] = []
+        error_count = 0
+
+        for i, (tool_name, args_str) in enumerate(tool_instructions[:max_steps]):
+            step_start = time.time()
+            tool = self.tools.get(tool_name)
+
+            step = {
+                "step": i + 1,
+                "tool": tool_name,
+                "args_raw": args_str,
+                "status": "running",
+            }
+
+            if tool is None:
+                step["status"] = "error"
+                step["result"] = f"未知工具: {tool_name}"
+                error_count += 1
+            else:
+                try:
+                    args = {}
+                    for pair in args_str.split(","):
+                        pair = pair.strip()
+                        if "=" in pair:
+                            k, v = pair.split("=", 1)
+                            k = k.strip()
+                            v = v.strip().strip("'\"").strip()
+                            args[k] = v
+                    result = tool.handler(**args) if tool.handler else "无处理器"
+                    step["result"] = str(result)[:500]
+                    step["status"] = "success"
+                    output_parts.append(str(result))
+                except Exception as e:
+                    step["status"] = "error"
+                    step["result"] = str(e)
+                    error_count += 1
+
+            step["duration_ms"] = round((time.time() - step_start) * 1000, 1)
+            steps.append(step)
+
+        elapsed = round((time.time() - start) * 1000, 1)
+
+        if not tool_instructions:
+            output_parts.append(
+                "我没有识别到需要调用的工具。请使用 !工具名(参数) 的格式来调用工具。\n\n"
+                "可用工具:\n" + "\n".join(
+                    f"  !{t.name}({', '.join(p.name for p in t.parameters)}) — {t.description}"
+                    for t in self.tools._tools.values()
+                )
+            )
+
+        result_text = "\n".join(output_parts)
+
+        self.memory.add("assistant", result_text)
+
+        success = error_count == 0 and len(tool_instructions) > 0
+        return CommandResult(success=success, data={
+            "output": result_text,
+            "steps": steps,
+            "step_count": len(steps),
+            "error_count": error_count,
+            "duration_ms": elapsed,
+        })
+
+    def list_available_tools(self) -> list[dict]:
+        """列出所有可用工具"""
+        return [
+            {"name": t.name, "description": t.description,
+             "parameters": [{"name": p.name, "type": p.type} for p in t.parameters]}
+            for t in self.tools._tools.values()
+        ]
+
+
+# ═══════════════════════════════════════════════════
+# 预置 Agent
+# ═══════════════════════════════════════════════════
+
+def code_review(diff_path: str = ".") -> CommandResult:
+    """代码审查 Agent：分析 git diff + 代码质量"""
+    import subprocess
+
+    runtime = AgentRuntime(system_prompt="你是一个代码审查助手，帮助检查代码质量。")
+
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--stat"],
+            capture_output=True, text=True, cwd=diff_path, timeout=10,
+        )
+        diff_stat = result.stdout or "暂存区无变更"
+
+        result = subprocess.run(
+            ["git", "diff", "--cached"],
+            capture_output=True, text=True, cwd=diff_path, timeout=10,
+        )
+        diff_content = result.stdout
+    except Exception as e:
+        diff_content = f"无法获取 git diff: {e}"
+
+    if not diff_content or len(diff_content) < 10:
+        # 改用工作区 diff
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--stat"],
+                capture_output=True, text=True, cwd=diff_path, timeout=10,
+            )
+            diff_stat = result.stdout or "无变更"
+
+            result = subprocess.run(
+                ["git", "diff"],
+                capture_output=True, text=True, cwd=diff_path, timeout=10,
+            )
+            diff_content = result.stdout
+        except Exception:
+            pass
+
+    prompt = f"""请审查以下代码变更：
+
+变更概览：
+{diff_stat}
+
+变更详情：
+{diff_content[:5000]}
+
+请检查：
+1. 是否有明显的 Bug 或逻辑错误
+2. 代码风格是否统一
+3. 是否需要添加注释
+4. 是否有安全风险
+"""
+    agent_result = runtime.run(prompt)
+
+    return CommandResult(success=agent_result.success, data={
+        "output": agent_result.data.get("output", ""),
+        "diff_stat": diff_stat,
+    })
+
+
+def file_butler(task: str, path: str = ".") -> CommandResult:
+    """文件管家 Agent：自然语言文件操作"""
+    runtime = AgentRuntime(system_prompt="你是一个文件管理助手。")
+
+    prompt = f"""请帮我执行以下文件操作任务：
+
+任务：{task}
+工作目录：{path}
+
+请使用 list_files、read_file、write_file、execute_python 等工具完成。
+"""
+    agent_result = runtime.run(prompt)
+
+    return CommandResult(success=agent_result.success, data={
+        "output": agent_result.data.get("output", ""),
+    })