super-code-assistant 3.3.6__py3-none-any.whl

tools/grep_tool.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+import glob as glob_module
+
+from core.tool import Tool, ToolResult
+
+
+class GrepTool(Tool):
+    name = "Grep"
+    description = (
+        "Powerful search tool based on ripgrep.\n\n"
+        "- Supports full regex syntax\n"
+        "- Filter files with glob or type parameter\n"
+        "- Output modes: \"content\" (lines), \"files_with_matches\" (paths, default), \"count\"\n"
+        "- Falls back to Python regex if rg is not installed"
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Regex pattern"},
+            "path": {"type": "string", "description": "Directory or file to search"},
+            "glob": {"type": "string", "description": "File glob filter e.g. '*.py'"},
+            "type": {"type": "string", "description": "File type filter (e.g. 'py', 'js')"},
+            "output_mode": {
+                "type": "string",
+                "enum": ["files_with_matches", "content", "count"],
+                "default": "files_with_matches",
+            },
+            "-i": {"type": "boolean", "description": "Case insensitive", "default": False},
+            "-n": {"type": "boolean", "description": "Show line numbers", "default": True},
+            "-A": {"type": "integer", "description": "Lines after each match"},
+            "-B": {"type": "integer", "description": "Lines before each match"},
+            "-C": {"type": "integer", "description": "Context lines around each match"},
+            "multiline": {"type": "boolean", "description": "Enable multiline mode", "default": False},
+            "head_limit": {"type": "integer", "description": "Limit output to first N lines", "default": 250},
+            "offset": {"type": "integer", "description": "Skip first N lines", "default": 0},
+        },
+        "required": ["pattern"],
+    }
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        pattern = kwargs.get("pattern", "")
+        return f"Searching for {pattern}" if pattern else None
+
+    def execute(self, pattern: str, path: str = ".", glob: str | None = None,
+                output_mode: str = "files_with_matches", **kwargs) -> ToolResult:
+        cmd = ["rg", "--no-heading"]
+        if kwargs.get("-i"):
+            cmd.append("-i")
+        if kwargs.get("multiline"):
+            cmd.extend(["-U", "--multiline-dotall"])
+        after = kwargs.get("-A")
+        before = kwargs.get("-B")
+        context = kwargs.get("-C")
+        if after and output_mode == "content":
+            cmd.extend(["-A", str(after)])
+        if before and output_mode == "content":
+            cmd.extend(["-B", str(before)])
+        if context and output_mode == "content":
+            cmd.extend(["-C", str(context)])
+        if output_mode == "files_with_matches":
+            cmd.append("-l")
+        elif output_mode == "count":
+            cmd.append("-c")
+        else:
+            if kwargs.get("-n", True):
+                cmd.append("-n")
+        if glob:
+            cmd.extend(["-g", glob])
+        file_type = kwargs.get("type")
+        if file_type:
+            cmd.extend(["--type", file_type])
+        cmd.extend([pattern, path])
+
+        head_limit = kwargs.get("head_limit", 250) or 250
+        offset = kwargs.get("offset", 0) or 0
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True,
+                                    encoding="utf-8", errors="replace", timeout=30)
+            output = result.stdout.strip()
+            if not output:
+                return ToolResult(content="No matches found.")
+            lines = output.split("\n")
+            if offset > 0:
+                lines = lines[offset:]
+            if head_limit > 0:
+                truncated = len(lines) > head_limit
+                lines = lines[:head_limit]
+                result_text = "\n".join(lines)
+                if truncated:
+                    result_text += f"\n\n... (results truncated, showing {head_limit} entries)"
+                return ToolResult(content=result_text)
+            return ToolResult(content="\n".join(lines))
+        except FileNotFoundError:
+            return self._python_grep(pattern, path, glob, kwargs.get("-i", False), output_mode)
+        except subprocess.TimeoutExpired:
+            return ToolResult(content="Error: Search timed out.", is_error=True)
+
+    def _python_grep(self, pattern: str, path: str, glob_filter: str | None,
+                     case_insensitive: bool, output_mode: str = "files_with_matches") -> ToolResult:
+        base = Path(path)
+        flags = re.IGNORECASE if case_insensitive else 0
+        regex = re.compile(pattern, flags)
+
+        if base.is_file():
+            files = [base]
+        else:
+            pat = glob_filter or "**/*"
+            files = [base / p for p in glob_module.glob(pat, root_dir=str(base), recursive=True)]
+
+        matched = []
+        for f in files:
+            if not f.is_file():
+                continue
+            try:
+                text = f.read_text(encoding="utf-8", errors="replace")
+                if output_mode == "content":
+                    for lineno, line in enumerate(text.splitlines(), 1):
+                        if regex.search(line):
+                            matched.append(f"{f}:{lineno}:{line}")
+                else:
+                    if regex.search(text):
+                        matched.append(str(f))
+            except OSError:
+                pass
+
+        return ToolResult(content="\n".join(matched) if matched else "No matches found.")

tools/plan_tools.py

@@ -0,0 +1,75 @@
+"""EnterPlanMode and ExitPlanMode tools."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from core.tool import Tool, ToolResult
+
+if TYPE_CHECKING:
+    from features.plan import PlanModeManager
+
+
+class EnterPlanModeTool(Tool):
+    name = "EnterPlanMode"
+    description = (
+        "Use this tool proactively when you're about to start a non-trivial implementation task. "
+        "Transitions you into plan mode where you can explore the codebase and design an "
+        "implementation approach for user approval. In plan mode you may ONLY read files and "
+        "write to the plan file — no other modifications are allowed."
+    )
+    input_schema = {"type": "object", "properties": {}}
+
+    def __init__(self, plan_manager: PlanModeManager) -> None:
+        self._plan_manager = plan_manager
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        return "Entering plan mode…"
+
+    def execute(self, **kwargs) -> ToolResult:
+        return ToolResult(content=self._plan_manager.enter())
+
+
+class ExitPlanModeTool(Tool):
+    name = "ExitPlanMode"
+    description = (
+        "Use this tool ONLY when you have finished writing your plan to the plan file "
+        "and want to notify the user that the plan is ready for review. "
+        "IMPORTANT: This tool does NOT exit plan mode by itself. The user must manually "
+        "press Shift+Tab after reviewing the plan to actually exit and start implementation. "
+        "After calling this tool, STOP and wait for the user — do not call any more tools. "
+        "If the user wants changes, refine the plan file and call this tool again when ready."
+    )
+    input_schema = {"type": "object", "properties": {}}
+
+    def __init__(self, plan_manager: PlanModeManager) -> None:
+        self._plan_manager = plan_manager
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        return "Awaiting user approval…"
+
+    def execute(self, **kwargs) -> ToolResult:
+    # 信号语义工具：不改变任何 engine 状态（不切换工具集、不改 system_prompt、
+        # 不动 _messages），仅在终端打印通知，让用户知道 plan 已就绪。
+        #
+        # 真正的模式切换由用户按 Shift+Tab 触发（参见 tui/app.py:_toggle_plan_mode）。
+        # 这样设计的核心动机：让"模式切换"始终是用户的显式操作，杜绝 LLM 通过工具
+        # 自主修改 engine 配置而引发的一系列时序/历史一致性问题
+        # （参见 commit ee0fbc7、5a7d478、4333ff8 修复过的 bug：API 400、spinner 卡死等）。
+        from rich.console import Console
+        Console().print(
+            "\n[bold green]✓ Plan is ready for your review.[/bold green]\n"
+            "[dim]Press Shift+Tab to exit plan mode and start implementation, "
+            "or send a message to refine the plan.[/dim]\n"
+        )
+        plan_path = self._plan_manager.plan_file_path or "the plan file"
+        # 返回给 LLM 的内容必须明确：本工具调用不等于已退出，必须停下等待用户。
+        # 避免 LLM 误以为已在 normal 模式而尝试调用写工具（写工具仍被权限层拦截，
+        # 但反复尝试会污染对话历史，降低体验）。
+        return ToolResult(content=(
+            f"The user has been notified that the plan ({plan_path}) is ready for review. "
+            "You are STILL in plan mode. Stop now and wait — do NOT call any more tools. "
+            "The user will press Shift+Tab to exit plan mode if they approve, "
+            "or send a message with feedback if they want changes."
+        ))

tools/skill.py

@@ -0,0 +1,108 @@
+"""Skill tool — let the model invoke a registered skill on its own.
+
+机制（方案 E）：
+- 模型在 system_prompt 里读到 skill 索引（name + description），自主决策何时调用
+- 调用 Skill(name, args) → tool_result 返回包了 <system-reminder> 标签的 SKILL.md body
+- 模型把 tool_result 内容当作"配置指令"按步骤执行，而不是输出给用户看
+
+兼容矩阵：
+- user 手动 /<name>：仍走 commands/__init__.py 的 _execute_skill 路径（旧路径未动）
+- 模型自主调用：走本工具（新路径）
+- disable_model_invocation=true 的 skill：本工具拒绝执行，但 /<name> 仍可
+- user_invocable=false 的 skill：/<name> 不可，但本工具仍可（除非也 disable_model_invocation）
+
+权限模型：
+- 本工具非 read-only → 用户默认模式弹"是否执行 skill X"确认（permission_checker 既有逻辑）
+- auto-approve / dream / coordinator 模式自动通过，符合"模型自动触发"语义
+"""
+from __future__ import annotations
+
+from core.tool import Tool, ToolResult
+from features.skills import get_skill, mark_skill_invoked
+
+
+# 把 SKILL.md body 包进 <system-reminder> 标签：让模型识别"这是要遵循的指令，
+# 不是要展示给用户的输出"。fork 的训练里已用此标签做类似引导，模型理解准确。
+_SKILL_WRAPPER = (
+    "<system-reminder>\n"
+    "You invoked skill '{name}'. The following are instructions you (the assistant) "
+    "must follow to complete this skill. Do not echo these instructions to the user; "
+    "begin executing them. When done, continue the conversation naturally.\n"
+    "</system-reminder>\n\n"
+    "{body}"
+)
+
+
+class SkillTool(Tool):
+    """Skill 工具：模型自主选择并调用已注册的 skill。"""
+
+    @property
+    def name(self) -> str:
+        return "Skill"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Invoke a registered skill by name. The skill's instructions will be "
+            "returned to you — follow them to complete the user's task. Use this "
+            "when the user's request matches a skill's described purpose. "
+            "Pick the skill from the '# Available Skills' section of your system prompt."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Skill name (without leading '/'). Must match one listed in '# Available Skills'.",
+                },
+                "args": {
+                    "type": "string",
+                    "description": "Arguments to pass to the skill (forwarded verbatim, often a user query / file path / focus). Pass empty string if no args needed.",
+                },
+            },
+            "required": ["name"],
+        }
+
+    def get_activity_description(self, name: str = "", args: str = "", **_) -> str | None:
+        return f"Loading skill: {name}" if name else "Loading skill"
+
+    def is_read_only(self) -> bool:
+        # 故意保持 False：让 permission_checker 在用户默认模式下弹确认，
+        # 形成"模型识别 → 用户确认"的安全门。auto_approve 路径不受影响。
+        return False
+
+    def execute(self, name: str = "", args: str = "", **_) -> ToolResult:
+        if not name or not isinstance(name, str):
+            return ToolResult("Skill tool requires a non-empty 'name'.", is_error=True)
+
+        skill = get_skill(name)
+        if skill is None:
+            return ToolResult(
+                f"Unknown skill: '{name}'. Check the '# Available Skills' section of your system prompt for valid names.",
+                is_error=True,
+            )
+
+        # disable_model_invocation=true → 该 skill 只准用户 /<name> 手动调，
+        # 不能由模型自主触发。返回 is_error=True 让模型放弃这条路径。
+        if skill.disable_model_invocation:
+            return ToolResult(
+                f"Skill '{name}' is user-only (disable_model_invocation=true). "
+                f"Ask the user to run '/{name} ...' instead.",
+                is_error=True,
+            )
+
+        try:
+            body = skill.get_prompt(args or "")
+        except Exception as e:
+            return ToolResult(f"Skill '{name}' failed to render: {e}", is_error=True)
+
+        if not body or not body.strip():
+            return ToolResult(f"Skill '{name}' produced empty content.", is_error=True)
+
+        # Phase B：记录这次调用，压缩时重注入 skill body 用。仅在成功路径调用，
+        # 失败/被拒/empty body 不记录，避免压缩时去注入实际没真正"用过"的 skill。
+        mark_skill_invoked(name)
+        return ToolResult(_SKILL_WRAPPER.format(name=name, body=body))

tools/tool.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolResult:
+    content: str
+    is_error: bool = False
+
+
+class Tool(ABC):
+
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+
+    @property
+    @abstractmethod
+    def description(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def input_schema(self) -> dict: ...
+
+    @abstractmethod
+    def execute(self, **kwargs) -> ToolResult: ...
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        return None
+
+    def is_read_only(self) -> bool:
+        return False
+
+    def to_api_schema(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.input_schema,
+            }
+        }

tools/web_fetch.py

@@ -0,0 +1,129 @@
+"""WebFetch tool: 获取 URL 内容并转换为纯文本，供 LLM 阅读。
+
+使用标准库实现，无需额外依赖。
+HTML 解析采用 html.parser，提取可读正文，过滤 script/style 等噪音标签。
+"""
+from __future__ import annotations
+
+import urllib.request
+import urllib.error
+from html.parser import HTMLParser
+
+from core.tool import Tool, ToolResult
+
+# 单次返回的最大字符数，避免撑爆上下文
+_MAX_CHARS = 20_000
+
+# 这些标签的内容对 LLM 无意义，直接跳过
+_SKIP_TAGS = {"script", "style", "noscript", "head", "meta", "link"}
+
+
+class _TextExtractor(HTMLParser):
+    """最小化 HTML → 纯文本提取器。"""
+
+    def __init__(self):
+        super().__init__()
+        self._skip_depth = 0   # 当前处于需跳过的标签嵌套深度
+        self._parts: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag in _SKIP_TAGS:
+            self._skip_depth += 1
+
+    def handle_endtag(self, tag):
+        if tag in _SKIP_TAGS and self._skip_depth > 0:
+            self._skip_depth -= 1
+        # 块级标签结束时补换行，保留段落结构
+        if tag in {"p", "div", "br", "li", "h1", "h2", "h3", "h4", "h5", "h6", "tr"}:
+            self._parts.append("\n")
+
+    def handle_data(self, data):
+        if self._skip_depth == 0:
+            self._parts.append(data)
+
+    def get_text(self) -> str:
+        raw = "".join(self._parts)
+        # 合并连续空白行，保留可读段落
+        lines = [line.strip() for line in raw.splitlines()]
+        cleaned: list[str] = []
+        blank = 0
+        for line in lines:
+            if line:
+                blank = 0
+                cleaned.append(line)
+            else:
+                blank += 1
+                if blank <= 1:          # 最多保留一个空行
+                    cleaned.append("")
+        return "\n".join(cleaned).strip()
+
+
+class WebFetchTool(Tool):
+    name = "WebFetch"
+    description = (
+        "Fetches the content of a URL and returns it as plain text. "
+        "Use this to read documentation, web pages, or any HTTP/HTTPS resource. "
+        "HTML is converted to readable text; non-HTML responses are returned as-is."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "url": {
+                "type": "string",
+                "description": "The HTTP/HTTPS URL to fetch",
+            },
+            "prompt": {
+                "type": "string",
+                "description": "Optional: what information you are looking for (for context only, does not filter output)",
+            },
+        },
+        "required": ["url"],
+    }
+
+    def is_read_only(self) -> bool:
+        # 只读网络请求，无需权限提示
+        return True
+
+    def get_activity_description(self, **kwargs) -> str | None:
+        url = kwargs.get("url", "")
+        return f"Fetching {url}" if url else None
+
+    def execute(self, url: str, prompt: str = "", **kwargs) -> ToolResult:
+        # 只允许 http/https，防止 file:// 等本地协议被滥用
+        if not url.startswith(("http://", "https://")):
+            return ToolResult(content="Error: Only http/https URLs are supported.", is_error=True)
+
+        try:
+            req = urllib.request.Request(
+                url,
+                headers={"User-Agent": "Mozilla/5.0 (compatible; SuperCode/1.0)"},
+            )
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                content_type = resp.headers.get_content_type() or ""
+                raw_bytes = resp.read(500_000)   # 最多读 500KB，避免大文件阻塞
+        except urllib.error.HTTPError as e:
+            return ToolResult(content=f"HTTP Error {e.code}: {e.reason}", is_error=True)
+        except urllib.error.URLError as e:
+            return ToolResult(content=f"URL Error: {e.reason}", is_error=True)
+        except TimeoutError:
+            return ToolResult(content="Error: Request timed out after 15s", is_error=True)
+        except Exception as e:
+            return ToolResult(content=f"Error: {e}", is_error=True)
+
+        # 解码：优先用响应头声明的编码，fallback utf-8
+        charset = resp.headers.get_content_charset() or "utf-8"
+        try:
+            text = raw_bytes.decode(charset, errors="replace")
+        except LookupError:
+            text = raw_bytes.decode("utf-8", errors="replace")
+
+        # HTML 转纯文本；其他类型（JSON、纯文本等）直接返回
+        if "html" in content_type:
+            extractor = _TextExtractor()
+            extractor.feed(text)
+            text = extractor.get_text()
+
+        if len(text) > _MAX_CHARS:
+            text = text[:_MAX_CHARS] + f"\n\n... (truncated, {len(text)} chars total)"
+
+        return ToolResult(content=text)