mosscode 0.1.0__py3-none-any.whl

mosscode/tools/files.py

@@ -0,0 +1,287 @@
+import os
+import tempfile
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import Params, Tool, ToolFailure, file_io
+from .diffing import unified_diff
+
+READ_LIMIT = 2000
+LINE_LIMIT = 2000  # Characters per displayed line.
+READ_BUDGET = 56 * 1024  # Bytes per page, below the registry's 64 KiB result cap.
+PREVIEW_LINES = 16  # Diff lines shown in the approval panel.
+
+
+class ReadParams(Params):
+    path: str
+    offset: int = Field(default=1, ge=1)
+    limit: int = Field(default=READ_LIMIT, ge=1, le=100000)
+
+
+class WriteParams(Params):
+    path: str
+    content: str
+
+
+class EditParams(Params):
+    path: str
+    old_text: str = Field(min_length=1)
+    new_text: str
+    replace_all: bool = False
+
+
+class FileState:
+    """What the model last saw of each file: (mtime_ns, size) at read or own write."""
+
+    def __init__(self):
+        self._seen: dict[str, tuple[int, int]] = {}
+
+    @staticmethod
+    def stamp(path: Path) -> tuple[int, int]:
+        info = path.stat()
+        return info.st_mtime_ns, info.st_size
+
+    @staticmethod
+    def _key(path: Path) -> str:
+        return os.path.normcase(str(path))
+
+    def clear(self) -> None:
+        self._seen.clear()
+
+    def copy(self) -> "FileState":
+        """A fork starts from what its parent has read."""
+        state = FileState()
+        state._seen = dict(self._seen)
+        return state
+
+    def record(self, path: Path, stamp: tuple[int, int] | None = None) -> None:
+        self._seen[self._key(path)] = stamp if stamp is not None else self.stamp(path)
+
+    def check(self, path: Path) -> None:
+        seen = self._seen.get(self._key(path))
+        if seen is None:
+            raise ToolFailure("not_read", "修改已有文件前需要先用 read_file 读取它；文件未修改。")
+        if self.stamp(path) != seen:
+            raise ToolFailure(
+                "stale_read", "文件在上次读取后被修改（可能来自用户、命令或其他程序）；请重新读取后再修改。文件未修改。"
+            )
+
+
+def read_text(path: Path) -> str:
+    with path.open("r", encoding="utf-8", newline="") as stream:
+        text = stream.read()
+    if "\0" in text:
+        raise ToolFailure("binary_file", "目标包含二进制内容，不能作为文本文件操作。")
+    return text
+
+
+def atomic_write(path: Path, text: str) -> None:
+    if path.is_dir():
+        raise IsADirectoryError()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    previous_mode = path.stat().st_mode if path.exists() else None
+    descriptor, temporary = tempfile.mkstemp(prefix=".mosscode-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as stream:
+            stream.write(text)
+        if previous_mode is not None:
+            os.chmod(temporary, previous_mode)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def line_count(text: str) -> int:
+    return len(text.splitlines())
+
+
+class FileTool(Tool):
+    def __init__(self, root: Path, state: FileState | None = None):
+        super().__init__(root)
+        self.state = state if state is not None else FileState()
+
+
+class ReadFile(FileTool):
+    read_only = True
+    name = "read_file"
+    description = (
+        f"读取 UTF-8 文本文件。每行格式为“行号 + Tab + 原文”；offset 从 1 开始，limit 默认 {READ_LIMIT} 行。"
+        f"超过 {LINE_LIMIT} 字符的行会截断，单页还有字节上限并会提示下一页的 offset。项目目录之外的路径需要用户确认。"
+    )
+    prompt_summary = "读取文本文件，可按行分段查看"
+    prompt_guidelines = (
+        "使用 read_file 查看文本原文，优先于 shell 读取；修改或覆盖已有文件前必须先用 read_file 读取，文件被外部改动后需重新读取。",
+        "read_file 输出中 Tab 之前的行号不是文件正文，不要把行号加入编辑参数。遇到截断时根据返回提示继续读取相关范围。",
+    )
+    params_model = ReadParams
+
+    async def execute(self, params: ReadParams):
+        def read():
+            path = self.read_path(params.path)
+            # Stamp before reading: a change during the read makes the record stale.
+            stamp = FileState.stamp(path)
+            selected, more, size, long_lines, total = [], False, 0, 0, 0
+            with path.open("r", encoding="utf-8", newline="") as stream:
+                for number, line in enumerate(stream, 1):
+                    total = number
+                    if "\0" in line:
+                        raise ToolFailure("binary_file", "目标包含二进制内容。")
+                    if number < params.offset:
+                        continue
+                    if more:
+                        continue  # Count remaining lines only.
+                    if len(selected) >= params.limit:
+                        more = True
+                        continue
+                    text = line.rstrip("\n").rstrip("\r")
+                    if len(text) > LINE_LIMIT:
+                        text = text[:LINE_LIMIT] + "…（本行过长，已截断）"
+                        long_lines += 1
+                    displayed = f"{number:>6}\t{text}"
+                    encoded = len(displayed.encode("utf-8")) + 1
+                    if size + encoded > READ_BUDGET:
+                        more = True
+                        continue
+                    selected.append(displayed)
+                    size += encoded
+            self.state.record(path, stamp)
+            next_offset = params.offset + len(selected)
+            if not selected:
+                output = "（文件为空）" if total == 0 else f"（offset={params.offset} 超出文件末尾，文件共 {total} 行）"
+            else:
+                output = "\n".join(selected)
+                if more:
+                    output += f"\n（共 {total} 行，还有内容，请从 offset={next_offset} 继续读取）"
+            return output, {
+                "path": str(path),
+                "lines": len(selected),
+                "total_lines": total,
+                "truncated": more,
+                "long_lines": long_lines,
+                "next_offset": next_offset if more else None,
+            }
+
+        return await file_io(read)
+
+
+class WriteFile(FileTool):
+    name = "write_file"
+    description = "创建或覆盖 UTF-8 文本文件，自动创建父目录。content 是要写入的完整文件内容。覆盖已有文件前必须先用 read_file 读取。"
+    prompt_summary = "创建文件或整体重写文件"
+    prompt_guidelines = (
+        "write_file 用于新建文件或确有必要的整体重写，优先于 shell 写入；局部修改优先使用可用的精确编辑工具。",
+        "write_file 会覆盖已有内容；覆盖前先读取文件，保留需要的原有内容和用户无关改动。",
+    )
+    params_model = WriteParams
+
+    def approval_preview(self, params: WriteParams) -> str:
+        path = self.path(params.path)
+        name = self.display(path)
+        if path.exists():
+            return unified_diff(read_text(path), params.content, name, limit=PREVIEW_LINES) or "内容与现有文件相同。"
+        lines = params.content.splitlines()
+        shown = [f"+{line}" for line in lines[:PREVIEW_LINES]]
+        if len(lines) > PREVIEW_LINES:
+            shown.append(f"…（共 {len(lines)} 行，仅显示前 {PREVIEW_LINES} 行）")
+        return "\n".join([f"新建文件 {name}（{line_count(params.content)} 行）", *shown])
+
+    async def execute(self, params: WriteParams):
+        def write():
+            path = self.path(params.path)
+            existed, before = path.is_file(), None
+            if existed:
+                self.state.check(path)
+                try:
+                    before = read_text(path)
+                except (UnicodeError, ToolFailure):
+                    pass  # Overwriting a non-text file: no diff.
+            atomic_write(path, params.content)
+            self.state.record(path)
+            name = self.display(path)
+            details = {"path": str(path), "bytes": len(params.content.encode("utf-8")), "created": not existed}
+            if not existed:
+                return f"已创建 {name}（{line_count(params.content)} 行）。", details
+            if before is None:
+                return f"已覆盖 {name}（原文件不是 UTF-8 文本）。", details
+            details["diff"] = unified_diff(before, params.content, name)
+            return f"已覆盖 {name}：{line_count(before)} 行 → {line_count(params.content)} 行。", details
+
+        return await file_io(write)
+
+
+class EditFile(FileTool):
+    name = "edit_file"
+    description = (
+        "将文件中的 old_text 精确替换为 new_text，空格和换行也参与匹配。默认要求恰好匹配一处；"
+        "replace_all=true 时替换全部匹配。零次或不唯一的匹配不修改文件。编辑前必须先用 read_file 读取。"
+    )
+    prompt_summary = "以唯一原文匹配精确替换一个片段"
+    prompt_guidelines = (
+        "局部修改优先 edit_file；编辑前读取相关原文，old_text 不包含读取输出的行号。",
+        "edit_file 的 old_text 使用足以唯一定位的最小原文上下文，避免携带大段无关内容；new_text 保留周边缩进和代码风格。重命名等需要替换全部出现位置时使用 replace_all。",
+        "edit_file 匹配为零时重新读取当前文件；匹配多次时补充邻近上下文。依据返回的错误调整参数，不猜测原文或原样重复失败调用。",
+    )
+    params_model = EditParams
+
+    @staticmethod
+    def _replace(text: str, params: EditParams) -> tuple[str, int, int, int]:
+        """New text, match count and the changed line range; nothing is written."""
+        if params.old_text == params.new_text:
+            raise ToolFailure("no_change", "old_text 与 new_text 相同，无需修改；文件未修改。")
+        # The model reads CRLF files as LF lines; match in LF and write back CRLF.
+        crlf = "\r\n" in text and text.count("\r\n") == text.count("\n")
+        work, old, new = text, params.old_text, params.new_text
+        if crlf:
+            work, old, new = (value.replace("\r\n", "\n") for value in (text, old, new))
+        positions, start = [], 0
+        step = len(old) if params.replace_all else 1  # Overlaps count when one match is required.
+        while (position := work.find(old, start)) >= 0:
+            positions.append(position)
+            start = position + step
+        count = len(positions)
+        if count == 0:
+            raise ToolFailure(
+                "match_count",
+                "原文匹配 0 次；文件未修改。请重新读取文件确认当前内容，old_text 不要包含行号。",
+                matches=0,
+            )
+        if count > 1 and not params.replace_all:
+            raise ToolFailure(
+                "match_count",
+                f"原文匹配 {count} 次，需要恰好 1 次；文件未修改。"
+                "补充邻近上下文使其唯一，或设置 replace_all=true 替换全部。",
+                matches=count,
+            )
+        result = work.replace(old, new) if params.replace_all else work.replace(old, new, 1)
+        # Line range of the change in the new text; the prefix before the first match is unchanged.
+        first = work[: positions[0]].count("\n") + 1
+        last_start = positions[-1] + (len(new) - len(old)) * (count - 1)
+        last = result[:last_start].count("\n") + 1 + new.count("\n")
+        if crlf:
+            result = result.replace("\n", "\r\n")
+        return result, count, first, last
+
+    def approval_preview(self, params: EditParams) -> str:
+        path = self.path(params.path)
+        text = read_text(path)
+        result = self._replace(text, params)[0]
+        return unified_diff(text, result, self.display(path), limit=PREVIEW_LINES)
+
+    async def execute(self, params: EditParams):
+        def edit():
+            path = self.path(params.path)
+            self.state.check(path)
+            text = read_text(path)
+            result, count, first, last = self._replace(text, params)
+            atomic_write(path, result)
+            self.state.record(path)
+            name = self.display(path)
+            where = f"第 {first} 行" if last <= first else f"第 {first}–{last} 行"
+            return (
+                f"已修改 {name}：替换 {count} 处，{where}。",
+                {"path": str(path), "matches": count, "diff": unified_diff(text, result, name)},
+            )
+
+        return await file_io(edit)

mosscode/tools/memory.py

@@ -0,0 +1,65 @@
+"""The memory tool: save or delete one note; never takes a path."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from ..memory import SCOPE_LABELS, MemoryFailure, MemoryStore
+from .base import Params, Tool, ToolFailure, file_io
+
+
+class MemoryParams(Params):
+    action: Literal["save", "delete"]
+    scope: Literal["user", "project"]
+    name: str = Field(min_length=1, max_length=200)
+    type: Literal["user", "feedback", "project", "reference"] | None = None
+    description: str = Field(default="", max_length=2000)
+    body: str = Field(default="", max_length=40000)
+
+
+class Memory(Tool):
+    name = "memory"
+    permission_kind = "memory"  # No approval: it writes only the two note directories.
+    plan_allowed = True  # Offered in plan mode too; not read-only, so it never runs concurrently.
+    description = (
+        "保存或删除跨会话的记忆笔记。save 写入或覆盖同名笔记（更新日期），delete 删除笔记；"
+        "成功后返回文件路径，索引由程序重新生成，下次会话开始时出现在系统提示中。"
+        "只写笔记目录，不需要审批，计划模式中也可以直接调用。"
+        "scope：user 为用户级（所有项目通用），project 为项目级（只用于当前项目）。"
+        "type：user（用户本人的偏好、习惯）、feedback（用户纠正或确认过的做法）、"
+        "project（代码和 git 历史看不出的项目知识，只能写到 project）、reference（外部资源的位置）。"
+    )
+    prompt_summary = "保存或删除跨会话的记忆笔记"
+    prompt_guidelines = (
+        "用户明确要求“记住……”“以后……”“不要再……”时立即调用 memory 保存；发现已有笔记有误时更新或删除。"
+        "计划模式中同样直接调用，不写进计划等待批准。",
+        "先看系统提示中的笔记索引，有同名或同义的笔记就用相同的 scope 和 name 覆盖更新，而不是新建。",
+        "不记录代码结构、git 历史中已有的内容和只与本次对话有关的细节；不记录密钥、令牌、密码。",
+        "name 只用小写字母、数字和连字符；description 一行，最多 150 字符，写清什么时候有用；body 最多 4 KB。"
+        "feedback 和 project 类型的正文写出事实后，另起两行“原因：……”和“适用方式：……”。",
+    )
+    params_model = MemoryParams
+
+    def __init__(self, root, store: MemoryStore):
+        super().__init__(root)
+        self.store = store
+
+    async def execute(self, params: MemoryParams):
+        label = SCOPE_LABELS[params.scope]
+        try:
+            if params.action == "delete":
+                path = await file_io(self.store.delete, params.scope, params.name)
+                return (
+                    f"已删除{label}笔记 {params.name}：{path}",
+                    {"action": "delete", "scope": params.scope, "name": params.name, "path": str(path)},
+                )
+            note, created = await file_io(
+                self.store.save, params.scope, params.name, params.type, params.description, params.body
+            )
+        except MemoryFailure as exc:
+            raise ToolFailure(exc.code, str(exc)) from None
+        verb = "已保存" if created else "已更新"
+        return (
+            f"{verb}{label}笔记 {note.name}：{note.path}\n索引已重新生成；本会话的系统提示不会变化，下次会话开始时生效。",
+            {"action": "save", "scope": params.scope, "name": note.name, "path": str(note.path), "created": created},
+        )

mosscode/tools/plan.py

@@ -0,0 +1,30 @@
+"""The plan-mode exit: the permission policy asks the user and switches modes."""
+
+from pydantic import Field
+
+from .base import Params, Tool
+
+
+class PlanParams(Params):
+    plan: str = Field(min_length=1, max_length=20000)
+
+
+class ExitPlanMode(Tool):
+    name = "exit_plan_mode"
+    plan_only = True  # Not read-only: runs alone, after any reads in the same response.
+    description = (
+        "计划模式下调查完成后调用，提交 Markdown 格式的实施计划请用户审阅。用户批准后立即退出计划模式，"
+        "可以继续使用写入、编辑和命令工具执行计划；用户选择继续规划时仍处于计划模式。"
+    )
+    prompt_summary = "提交计划，请用户批准后开始执行"
+    prompt_guidelines = (
+        "计划模式下完成调查后用 exit_plan_mode 提交计划，不要用文字询问用户是否开始执行；计划写明要改的文件、步骤和验证方法，简洁具体。",
+        "只为需要动手实施的任务提交计划；纯调查或问答直接回答。用户选择继续规划时，根据反馈调整后再提交。",
+    )
+    params_model = PlanParams
+
+    async def execute(self, params: PlanParams):
+        return (
+            "用户已批准计划，已退出计划模式。现在按计划执行；写入、编辑和命令按当前权限档位处理。",
+            {"plan": params.plan},
+        )

mosscode/tools/process.py

@@ -0,0 +1,216 @@
+"""Bounded asynchronous subprocess I/O, including process-tree cleanup."""
+
+import asyncio
+import os
+import signal
+import sys
+from pathlib import Path
+
+from pydantic import Field
+
+from .base import Params, Tool, ToolFailure
+from .shell import Shell, resolve_shell
+
+OUTPUT_LIMIT = 32768
+# Command output keeps both ends: failure summaries are usually at the end.
+COMMAND_HEAD, COMMAND_TAIL = 1024 * 1024, 1024 * 1024  # Memory guard; layer 1 stores large output.
+
+
+async def terminate_tree(process: asyncio.subprocess.Process) -> None:
+    if os.name == "nt":
+        # A Job Object owns only this invocation and its descendants. Closing it
+        # terminates descendants even if the original shell has already exited.
+        job = getattr(process, "_mosscode_job", None)
+        if job is not None:
+            job.close()
+        elif process.returncode is None:
+            killer = await asyncio.create_subprocess_exec(
+                "taskkill",
+                "/PID",
+                str(process.pid),
+                "/T",
+                "/F",
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+                creationflags=0x08000000,
+            )
+            await killer.wait()
+    else:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+    if process.returncode is None:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+    await process.wait()
+
+
+def _decode_cut(data: bytes, *, start: bool) -> str:
+    """Decode one side of a cut without a broken character at the cut edge."""
+    if start:
+        skip = 0
+        while skip < min(3, len(data)) and 0x80 <= data[skip] < 0xC0:
+            skip += 1
+        return data[skip:].decode("utf-8", errors="replace")
+    for trim in range(min(3, len(data)) + 1):
+        try:
+            return data[: len(data) - trim].decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+    return data.decode("utf-8", errors="replace")
+
+
+async def _feed(stream, data: bytes) -> None:
+    """Write stdin and close it; a child that exits without reading is not an error."""
+    try:
+        if data:
+            stream.write(data)
+            await stream.drain()
+    except (BrokenPipeError, ConnectionResetError):
+        pass
+    finally:
+        stream.close()
+
+
+async def run_process(
+    args: list[str],
+    cwd: Path,
+    *,
+    check: bool = True,
+    limit: int = OUTPUT_LIMIT,
+    tail: int = 0,
+    env: dict[str, str] | None = None,
+    input: bytes | None = None,
+):
+    """input, when given, is written to the child's stdin, which is then closed; otherwise stdin is empty."""
+    options = {"creationflags": 0x08000000} if os.name == "nt" else {"start_new_session": True}
+    # Windows commands wait on a one-byte gate until Job assignment completes.
+    # This closes the race in which a fast shell could spawn before assignment.
+    # os.read takes exactly the gate byte, so the child inherits the rest of the pipe as its stdin.
+    inherit = "" if input is not None else ",stdin=subprocess.DEVNULL"
+    gate = f"import os,subprocess,sys; os.read(0,1); sys.exit(subprocess.call(sys.argv[1:]{inherit}))"
+    command = [sys.executable, "-c", gate, *args] if os.name == "nt" else args
+    piped = os.name == "nt" or input is not None
+    spawn = asyncio.create_task(
+        asyncio.create_subprocess_exec(
+            *command,
+            cwd=cwd,
+            stdin=asyncio.subprocess.PIPE if piped else asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+            **options,
+        )
+    )
+    try:
+        process = await asyncio.shield(spawn)
+    except asyncio.CancelledError:
+        process = await spawn
+        await terminate_tree(process)
+        raise
+    if os.name == "nt":
+        from .windows_job import WindowsJob
+
+        try:
+            process._mosscode_job = WindowsJob(process.pid)
+        except OSError:
+            await terminate_tree(process)
+            raise ToolFailure("process_cleanup_unavailable", "无法建立命令进程的生命周期边界，命令已终止。") from None
+    feeder = None
+    if piped:
+        feeder = asyncio.create_task(_feed(process.stdin, (b"\n" if os.name == "nt" else b"") + (input or b"")))
+
+    async def drain(stream):
+        # Keep the first `limit` bytes and, with `tail`, a rolling window of the
+        # bytes after them; head + end is the whole stream when nothing was dropped.
+        head, end = bytearray(), bytearray()
+        total = 0
+        while chunk := await stream.read(8192):
+            total += len(chunk)
+            room = max(0, limit - len(head))
+            head.extend(chunk[:room])
+            if tail:
+                end.extend(chunk[room:])
+                del end[: max(0, len(end) - tail)]
+        omitted = total - len(head) - len(end)
+        if omitted <= 0:
+            return (bytes(head) + bytes(end)).decode("utf-8", errors="replace"), False
+        if not tail:
+            return head.decode("utf-8", errors="replace"), True
+        marker = f"\n…（中间省略 {omitted} 字节）…\n"
+        return _decode_cut(bytes(head), start=False) + marker + _decode_cut(bytes(end), start=True), True
+
+    stdout_task = asyncio.create_task(drain(process.stdout))
+    stderr_task = asyncio.create_task(drain(process.stderr))
+    try:
+        await process.wait()
+        stdout, stderr = await asyncio.gather(stdout_task, stderr_task)
+        details = {
+            "stdout": stdout[0],
+            "stderr": stderr[0],
+            "exit_code": process.returncode,
+            "truncated": stdout[1] or stderr[1],
+        }
+        if check and process.returncode != 0:
+            raise ToolFailure("nonzero_exit", f"命令退出码为 {process.returncode}。", **details)
+        return details
+    finally:
+        await terminate_tree(process)
+        await asyncio.gather(stdout_task, stderr_task, *(task for task in (feeder,) if task), return_exceptions=True)
+
+
+class CommandParams(Params):
+    command: str = Field(min_length=1)
+    cwd: str | None = None
+    timeout: float = Field(default=120.0, gt=0, le=600, allow_inf_nan=False)
+
+
+SHELL_GUIDELINES = {
+    "Git Bash": "当前 shell 是 Windows 上的 Git Bash：使用 bash 语法和正斜杠路径（如 C:/Users 或 /c/Users），空设备写 /dev/null 而不是 NUL；Windows 原生程序仍可直接调用。",
+    "PowerShell": "当前 shell 是 PowerShell：使用 PowerShell 语法；Windows PowerShell 5 不支持 && 和 ||，用 ; 分隔并检查 $LASTEXITCODE。",
+}
+
+
+class ExecuteCommand(Tool):
+    name = "execute_command"
+    prompt_summary = "执行测试、构建等 shell 命令"
+    params_model = CommandParams
+    plan_commands = True
+
+    def __init__(self, root: Path, shell: Shell | str | None = None):
+        super().__init__(root)
+        self.shell = shell if isinstance(shell, Shell) else resolve_shell(shell or "auto")
+        self.description = (
+            f"在 {self.shell.label} 中执行命令，返回 stdout、stderr 和退出码。cwd 可指定工作目录；"
+            "timeout 以秒计，默认 120、最大 600。输出过长时保留开头和结尾。"
+        )
+        self.prompt_guidelines = (
+            "execute_command 用于测试、构建和专用工具未覆盖的任务；已有专用工具时优先用于读取、搜索、写入和编辑。",
+            "execute_command 的命令遵循当前 shell 的语法，正确引用含空格的路径。依据退出码和输出判断结果，不能仅因有输出就宣布成功。",
+            *((SHELL_GUIDELINES[self.shell.label],) if self.shell.label in SHELL_GUIDELINES else ()),
+            "git status/diff/log/show、ls、cat、grep 等只读命令（参数限于项目内，不含管道和重定向）无需审批，计划模式中也可使用；其他命令按权限档位审批。",
+            "execute_command 超时或取消可能留下部分效果；重复有副作用的命令前先检查状态，不通过增大超时掩盖持续失败。",
+        )
+
+    async def execute(self, params: CommandParams):
+        cwd = self.path(params.cwd) if params.cwd is not None else self.root
+        details = await run_process(
+            self.shell.args(params.command),
+            cwd,
+            check=False,
+            limit=COMMAND_HEAD,
+            tail=COMMAND_TAIL,
+            env=self.shell.env(params.command),
+        )
+        output = details["stdout"]
+        if details["stderr"]:
+            output += ("\n" if output else "") + "stderr:\n" + details["stderr"]
+        if details["exit_code"] != 0:
+            # The model sees only output, so the failing command's streams must be in it.
+            raise ToolFailure(
+                "nonzero_exit", f"命令退出码为 {details['exit_code']}。" + (f"\n{output}" if output else ""), **details
+            )
+        return output or "命令完成，无输出。", details