langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/read/prompt.py

@@ -0,0 +1,73 @@
+"""
+tools/read/prompt.py — ReadRuntimeTool 工具名与 prompt 模板
+
+职责：
+    集中管理工具名常量、面向模型的 description 和 prompt 模板文本。
+    纯字符串/常量，无 I/O，无框架依赖，可单独测试。
+
+对应 CC prompt.ts，包含：
+    FILE_READ_TOOL_NAME  → TOOL_NAME
+    DESCRIPTION          → DESCRIPTION
+    FILE_UNCHANGED_STUB  → FILE_UNCHANGED_STUB
+    renderPromptTemplate → get_prompt()
+"""
+
+from __future__ import annotations
+
+TOOL_NAME = "read_file"
+"""工具名，面向模型暴露，唯一标识。"""
+
+DESCRIPTION = "Read a file from the local filesystem."
+"""简短描述，用于 bind_tools 阶段工具列表展示（对应 CC DESCRIPTION）。"""
+
+FILE_UNCHANGED_STUB = (
+    "File unchanged since last read. "
+    "The content from the earlier read result in this conversation is still current "
+    "— refer to that instead of re-reading."
+)
+"""
+重复读取去重时返回的 stub 文本（对应 CC FILE_UNCHANGED_STUB）。
+model 收到此文本后应直接引用历史上下文，而非重新读取。
+"""
+
+MAX_LINES_TO_READ = 2000
+"""面向模型 prompt 中说明的默认行数上限（与 limits.py 同步）。"""
+
+
+def get_prompt() -> str:
+    """
+    返回面向模型的完整使用说明（对应 CC renderPromptTemplate()）。
+
+    动态引用 limits 配置，确保 prompt 中展示的限制值与实际执行一致。
+    """
+    from .limits import get_read_limits
+
+    limits = get_read_limits()
+    max_size_kb = limits["max_size_bytes"] // 1024
+    pdf_max_pages = limits["pdf_max_pages"]
+
+    return (
+        f"Reads a file from the local filesystem.\n"
+        f"\n"
+        f"Usage:\n"
+        f"- file_path must be an absolute path\n"
+        f"- By default reads up to {MAX_LINES_TO_READ} lines from the start of the file\n"
+        f"- Files larger than {max_size_kb}KB will return an error; "
+        f"use offset and limit to read specific portions\n"
+        f"- You can optionally specify offset and limit for large files; "
+        f"it is recommended to read the whole file by not providing these parameters\n"
+        f"- Results are returned with line numbers starting at 1 (cat -n format: "
+        f'"   1\\t<line content>")\n'
+        f"- If a file exists but is shorter than the provided offset, a warning is returned\n"
+        f"- If a file exists but has empty contents, a warning is returned\n"
+        f"\n"
+        f"Supported file types beyond plain text:\n"
+        f"- Images (PNG, JPG, JPEG, GIF, WEBP): contents are returned as base64-encoded data\n"
+        f"- PDF files (.pdf): text is extracted page by page; "
+        f"use the pages parameter for large PDFs (e.g. pages=\"1-5\", max {pdf_max_pages} pages per request)\n"
+        f"- Jupyter notebooks (.ipynb): returns all cells with their outputs\n"
+        f"\n"
+        f"Restrictions:\n"
+        f"- This tool can only read files, not directories\n"
+        f"- Binary files (non-image, non-PDF) cannot be read; use appropriate tools instead\n"
+    )

langchain_agentx/tools/read/tool.py

@@ -0,0 +1,494 @@
+"""
+tools/read/tool.py — ReadRuntimeTool 主类
+
+职责：
+    实现 RuntimeTool 的所有生命周期 hook，编排文件读取完整流程。
+    核心业务 I/O 委托给 FileBackend，描述文本来自 prompt.py，
+    数值配置来自 limits.py，输入/输出模型来自 models.py。
+
+对应 CC FileReadTool.ts 主体部分。
+present() 对应 CC UI.tsx 的 renderToolResultMessage()。
+validate_input：Windows 保留名（utils.win_reserved_paths）；UNC 与 // 前缀跳过本地 exists/stat（utils.unc_path，与 Grep/Glob 一致）。
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolHint,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+from langchain_agentx.utils.path_user_input import UserPathInputNormalizer
+from langchain_agentx.utils.unc_path import is_unc_path_skip_local_stat
+from langchain_agentx.utils.win_reserved_paths import path_uses_windows_reserved_name
+
+from .backend import BINARY_EXTENSIONS, SUPPORTED_IMAGE_EXTS, FileBackend
+from .limits import PDF_MAX_PAGES_PER_READ, get_read_limits
+from .models import (
+    FileUnchangedOutput,
+    ImageFileOutput,
+    NotebookFileOutput,
+    PDFFileOutput,
+    ReadToolInput,
+    TextFileOutput,
+)
+
+from .prompt import DESCRIPTION, FILE_UNCHANGED_STUB, TOOL_NAME, get_prompt
+
+
+class ReadRuntimeTool(RuntimeTool):
+    """
+    文件读取工具，支持文本、图片、PDF、Jupyter Notebook。
+
+    对应 CC FileReadTool，是工具体系中最高频使用的工具。
+
+    特性：
+        is_read_only=True      只读，走 read_roots 权限检查
+        is_concurrency_safe=True  只读，允许并发执行
+        never_truncate=True    自带 limit 分页，禁止 ToolOutputManager 截断
+    """
+
+    name: str = TOOL_NAME
+    description: str = DESCRIPTION
+    input_model = ReadToolInput
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    never_truncate: bool = True
+    dedupe_identical_calls: bool = True
+
+    # 阻断的设备文件路径（对应 CC BLOCKED_DEVICE_PATHS）
+    _BLOCKED_DEVICE_PATHS: frozenset[str] = frozenset({
+        "/dev/zero", "/dev/random", "/dev/urandom", "/dev/full",
+        "/dev/stdin", "/dev/tty", "/dev/console",
+        "/dev/stdout", "/dev/stderr",
+        "/dev/fd/0", "/dev/fd/1", "/dev/fd/2",
+    })
+
+    def __init__(
+        self,
+        *,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+        backend: FileBackend | None = None,
+        path_normalizer: UserPathInputNormalizer | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        self._backend = backend or FileBackend()
+        self._path_normalizer = path_normalizer or UserPathInputNormalizer()
+
+    # ------------------------------------------------------------------
+    # Hook 1: normalize_input
+    # ------------------------------------------------------------------
+
+    def normalize_input(
+        self, raw: dict[str, Any], ctx: ToolExecutionContext
+    ) -> dict[str, Any]:
+        """
+        路径规范化：展开 ~ 和 ..，转为绝对路径。
+        limit 上限收紧：不超过 max_lines。
+        对应 CC backfillObservableInput() + expandPath()。
+        """
+        raw = dict(raw)  # 不修改原始 dict
+
+        path = raw.get("file_path", "")
+        if isinstance(path, str) and path:
+            raw["file_path"] = self._path_normalizer.normalize_and_expand(
+                path, base_dir=ctx.cwd
+            )
+
+        limits = get_read_limits()
+        if raw.get("limit") is not None:
+            raw["limit"] = min(int(raw["limit"]), limits["max_lines"])
+
+        return raw
+
+    # ------------------------------------------------------------------
+    # Hook 3: validate_input
+    # ------------------------------------------------------------------
+
+    def validate_input(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> ValidationResult:
+        """
+        语义校验，执行顺序与 CC validateInput() 保持一致：
+            先无 I/O 检查（快速 fail）→ Windows 保留名（仅 win32）→ UNC 短路 → 再 I/O 检查。
+
+        对应 CC FileReadTool.validateInput()（含 UNC）；保留名为本工程 Windows 补强。
+        """
+        inp = ReadToolInput.model_validate(data)
+        path = inp.file_path
+        ext = Path(path).suffix.lower().lstrip(".")
+
+        # ---- [1] pages 参数格式校验（纯字符串，无 I/O）----
+        if inp.pages is not None:
+            if ext != "pdf":
+                return ValidationResult(
+                    ok=False,
+                    message="pages parameter is only valid for PDF files.",
+                )
+            m = re.fullmatch(r"(\d+)(?:-(\d+))?", inp.pages.strip())
+            if not m:
+                return ValidationResult(
+                    ok=False,
+                    message=(
+                        f'Invalid pages format: "{inp.pages}". '
+                        'Use formats like "1-5", "3", or "10-20".'
+                    ),
+                )
+            start = int(m.group(1))
+            end = int(m.group(2)) if m.group(2) else start
+            if end - start + 1 > PDF_MAX_PAGES_PER_READ:
+                return ValidationResult(
+                    ok=False,
+                    message=(
+                        f'Page range "{inp.pages}" exceeds maximum of '
+                        f"{PDF_MAX_PAGES_PER_READ} pages per request."
+                    ),
+                )
+
+        # ---- [2] 设备文件阻断（路径字符串检查，无 I/O）----
+        if path in self._BLOCKED_DEVICE_PATHS or self._is_proc_stdio(path):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Cannot read '{path}': "
+                    "this device file would block or produce infinite output."
+                ),
+            )
+
+        # ---- [3] Windows 保留设备名（路径段 stem，无 I/O；在 UNC 短路之前）----
+        if path_uses_windows_reserved_name(path):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Cannot read '{path}': uses a Windows reserved device name "
+                    "(CON, PRN, AUX, NUL, COM1-9, LPT1-9). "
+                    "These paths can hang or behave unpredictably."
+                ),
+            )
+
+        # ---- [4] UNC / SMB 前缀：与 CC 一致，跳过本地 exists/stat（防 NTLM 等）----
+        if is_unc_path_skip_local_stat(path):
+            return ValidationResult(ok=True)
+
+        # ---- [5] 二进制扩展名拒绝（字符串检查，无 I/O），PDF/图片例外 ----
+        if ext in BINARY_EXTENSIONS and ext not in SUPPORTED_IMAGE_EXTS and ext != "pdf":
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Cannot read binary .{ext} files. "
+                    "Use appropriate tools for binary file analysis."
+                ),
+            )
+
+        # ---- [6] 文件存在性检查（I/O）----
+        if not os.path.exists(path):
+            similar = self._find_similar_file(path)
+            hint = f" Did you mean {similar}?" if similar else ""
+            return ValidationResult(
+                ok=False,
+                message=f"File does not exist: {path}.{hint}",
+            )
+
+        # ---- [7] 目录检查（I/O）----
+        if os.path.isdir(path):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Path is a directory: {path}. "
+                    "Use the bash tool with ls to list directory contents."
+                ),
+            )
+
+        # ---- [8] 文件大小检查（I/O，stat）——图片有独立上限 ----
+        limits = get_read_limits()
+        if ext in SUPPORTED_IMAGE_EXTS:
+            size = os.path.getsize(path)
+            if size > limits["image_max_bytes"]:
+                return ValidationResult(
+                    ok=False,
+                    message=(
+                        f"Image file is too large ({size:,} bytes, "
+                        f"max {limits['image_max_bytes']:,} bytes)."
+                    ),
+                )
+        elif ext not in {"pdf", "ipynb"}:
+            size = os.path.getsize(path)
+            if size > limits["max_size_bytes"]:
+                return ValidationResult(
+                    ok=False,
+                    message=(
+                        f"File too large ({size:,} bytes, "
+                        f"max {limits['max_size_bytes']:,} bytes). "
+                        "Use offset and limit to read specific portions."
+                    ),
+                )
+
+        return ValidationResult(ok=True)
+
+    # ------------------------------------------------------------------
+    # Hook 4: check_permissions
+    # ------------------------------------------------------------------
+
+    def check_permissions(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> AuthorizationDecision:
+        """委托给注入的 PolicyEngine（走 read_roots 检查）。"""
+        return super().check_permissions(data, ctx)
+
+    # ------------------------------------------------------------------
+    # Core: invoke
+    # ------------------------------------------------------------------
+
+    def invoke(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> Any:
+        """
+        核心执行：先检查 dedup（mtime 未变则返回 stub），再调 FileBackend。
+        对应 CC FileReadTool.call() 主逻辑。
+        """
+        inp = ReadToolInput.model_validate(data)
+        path = inp.file_path
+        limits = get_read_limits()
+
+        # dedup 检查：同文件同范围且 mtime 未变，直接返回 stub
+        if self._state_bridge is not None:
+            last = self._state_bridge.get_last_read(path)
+            if (
+                last is not None
+                and last.get("offset") == inp.offset
+                and last.get("limit") == inp.limit
+            ):
+                try:
+                    mtime_ms = int(os.path.getmtime(path) * 1000)
+                    if mtime_ms == last.get("mtime_ms"):
+                        return FileUnchangedOutput(
+                            type="file_unchanged", file_path=path
+                        )
+                except OSError:
+                    pass
+
+        return self._backend.read(path, inp, limits)
+
+    # ------------------------------------------------------------------
+    # Hook 7: after_invoke
+    # ------------------------------------------------------------------
+
+    def after_invoke(
+        self, data: dict[str, Any], result: Any, ctx: ToolExecutionContext
+    ) -> None:
+        """
+        更新 state_bridge 的读取记录：
+          - 供 write/edit 工具的 read-before-write 检查使用
+          - 供下次 invoke 的 dedup 检查使用
+
+        file_unchanged 结果不更新（mtime 没变，记录仍有效）。
+        """
+        if self._state_bridge is None:
+            return
+        if isinstance(result, FileUnchangedOutput):
+            return
+
+        inp = ReadToolInput.model_validate(data)
+        try:
+            mtime_ms = int(os.path.getmtime(inp.file_path) * 1000)
+        except OSError:
+            mtime_ms = 0
+
+        self._state_bridge.set_last_read(
+            inp.file_path,
+            offset=inp.offset,
+            limit=inp.limit,
+            mtime_ms=mtime_ms,
+        )
+
+    # ------------------------------------------------------------------
+    # Hook 9: present
+    # ------------------------------------------------------------------
+
+    def present(
+        self, data: dict[str, Any], result: Any, ctx: ToolExecutionContext
+    ) -> ToolResultEnvelope:
+        """
+        将内部执行结果映射为 ToolResultEnvelope。
+        对应 CC UI.tsx 的 renderToolResultMessage()。
+        """
+        inp = ReadToolInput.model_validate(data)
+        if isinstance(result, TextFileOutput):
+            return self._present_text(result)
+        if isinstance(result, ImageFileOutput):
+            return self._present_image(result)
+        if isinstance(result, PDFFileOutput):
+            return self._present_pdf(result)
+        if isinstance(result, NotebookFileOutput):
+            return self._present_notebook(result)
+        if isinstance(result, FileUnchangedOutput):
+            return self._present_unchanged(result)
+
+        # fallback（不应发生）
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=f"Read {inp.file_path}",
+            payload=str(result),
+        )
+
+    # ------------------------------------------------------------------
+    # 内部辅助
+    # ------------------------------------------------------------------
+
+    def _present_text(self, result: TextFileOutput) -> ToolResultEnvelope:
+        if result.total_lines == 0:
+            # 空文件
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=f"Read {result.file_path} (empty file)",
+                payload=result.content,
+            )
+
+        lines_read = max(result.line_end - result.line_start + 1, 0)
+        remaining = result.total_lines - result.line_end
+        summary = (
+            f"Read {lines_read} lines from {result.file_path} "
+            f"(lines {result.line_start}-{result.line_end} of {result.total_lines})"
+        )
+
+        hints: list[ToolHint] = []
+        if remaining > 0:
+            next_offset = result.line_end + 1
+            hints.append(
+                ToolHint(
+                    message=(
+                        f"File has {remaining} more lines. "
+                        f"Call again with offset={next_offset} to continue reading."
+                    )
+                )
+            )
+
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=result.content,
+            hints=hints or None,
+            meta={"file_path": result.file_path, "type": "text"},
+        )
+
+    def _present_image(self, result: ImageFileOutput) -> ToolResultEnvelope:
+        dims = ""
+        if result.width and result.height:
+            dims = f" ({result.width}x{result.height})"
+        summary = (
+            f"Read image from {result.file_path}"
+            f"{dims} ({result.original_size:,} bytes, {result.media_type})"
+        )
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=result.base64,
+            meta={
+                "file_path": result.file_path,
+                "type": "image",
+                "media_type": result.media_type,
+                "width": result.width,
+                "height": result.height,
+                "original_size": result.original_size,
+            },
+        )
+
+    def _present_pdf(self, result: PDFFileOutput) -> ToolResultEnvelope:
+        pages_info = (
+            f"pages {result.page_start}-{result.page_end} of {result.total_pages}"
+        )
+        summary = f"Read PDF {result.file_path} ({pages_info})"
+
+        hints: list[ToolHint] = []
+        if result.truncated:
+            next_start = result.page_end + 1
+            hints.append(
+                ToolHint(
+                    message=(
+                        f"PDF has more pages. "
+                        f'Call again with pages="{next_start}-..." to continue.'
+                    )
+                )
+            )
+
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=result.content,
+            hints=hints or None,
+            meta={
+                "file_path": result.file_path,
+                "type": "pdf",
+                "page_start": result.page_start,
+                "page_end": result.page_end,
+                "total_pages": result.total_pages,
+            },
+        )
+
+    def _present_notebook(self, result: NotebookFileOutput) -> ToolResultEnvelope:
+        import json
+
+        summary = f"Read notebook {result.file_path} ({len(result.cells)} cells)"
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=json.dumps(result.cells, ensure_ascii=False),
+            meta={"file_path": result.file_path, "type": "notebook"},
+        )
+
+    def _present_unchanged(self, result: FileUnchangedOutput) -> ToolResultEnvelope:
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=f"File unchanged: {result.file_path}",
+            payload=FILE_UNCHANGED_STUB,
+            meta={"file_path": result.file_path, "type": "file_unchanged"},
+        )
+
+    @staticmethod
+    def _is_proc_stdio(path: str) -> bool:
+        """检查是否为 /proc/self/fd/0-2 或 /proc/<pid>/fd/0-2。"""
+        if not path.startswith("/proc/"):
+            return False
+        return path.endswith(("/fd/0", "/fd/1", "/fd/2"))
+
+    @staticmethod
+    def _find_similar_file(path: str) -> str | None:
+        """
+        在同目录下查找名称相似的文件，用于 "Did you mean X?" 提示。
+        对应 CC findSimilarFile()，使用 difflib 序列匹配。
+        """
+        parent = os.path.dirname(path)
+        target = os.path.basename(path)
+        if not os.path.isdir(parent):
+            return None
+        try:
+            candidates = os.listdir(parent)
+        except OSError:
+            return None
+        matches = difflib.get_close_matches(target, candidates, n=1, cutoff=0.6)
+        if matches:
+            return os.path.join(parent, matches[0])
+        return None
+
+    def __repr__(self) -> str:
+        return (
+            f"<ReadRuntimeTool name={self.name!r} "
+            f"[read_only, concurrency_safe, never_truncate]>"
+        )