ot-cli 0.2.1__py3-none-any.whl

openterminal/session/base.py

@@ -0,0 +1,328 @@
+"""持久 shell 会话接口与哨兵捕获主循环（local / ssh 共用）。"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+BEGIN_MARKER = "__OT_BEGIN__"
+END_MARKER = "__OT_END__"
+_BEGIN_RE = re.compile(rb"__OT_BEGIN__\r?\n")
+_END_RE = re.compile(rb"__OT_END__(-?\d+)__(.*)__\r?\n")
+_ANSI_RE = re.compile(rb"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07]*(?:\x07|\x1b\\)")
+
+# 中文提示符（密码：/口令：）单独以 str 编码拼进 bytes 正则（bytes 字面量
+# 不能含非 ASCII）
+_PASSWORD_PROMPT_RE = re.compile(
+    rb"(\[sudo\] password for |'s password:|\([^)\r\n]{1,80}\)\s*password:"
+    rb"|^password:|" + "密码[:：]|口令[:：]".encode() + rb")",
+    re.IGNORECASE | re.MULTILINE,
+)
+_PASSWORD_NEEDING_PREFIXES = {"sudo", "su", "ssh", "scp", "rsync"}
+
+
+def _needs_password_prompt(command: str) -> bool:
+    head = command.strip().split()[0] if command.strip() else ""
+    return os.path.basename(head) in _PASSWORD_NEEDING_PREFIXES
+
+
+@dataclass
+class CommandResult:
+    output: str
+    exit_code: int
+    truncated: bool
+    cwd: str
+    reconnected: bool = False
+
+
+class ShellSession(Protocol):
+    cwd: str
+
+    async def start(self) -> None: ...
+    async def run(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        on_output: Callable[[str], None] | None = None,
+    ) -> CommandResult: ...
+    async def send_raw(self, data: bytes) -> None: ...
+    async def resize(self, rows: int, cols: int) -> None: ...
+    async def close(self) -> None: ...
+
+
+def wrap_command(command: str) -> str:
+    """把用户命令包进 BEGIN/END 哨兵的单行复合命令。
+
+    必须是单行：多行输入可能被会读 stdin 的命令（如 cat）偷吃掉。
+    """
+    one_line = command.replace("\n", " ; ").replace("\r", " ")
+    return (
+        f"printf '{BEGIN_MARKER}\\n'; {one_line}; "
+        f"printf '{END_MARKER}%s__%s__\\n' \"$?\" \"$PWD\"\n"
+    )
+
+
+def wrap_passthrough(command: str, marker: str) -> str:
+    """交互式内联直通的单行包装：命令 ; printf 随机哨兵（带退出码）。
+
+    与 wrap_command 的差别：不打 BEGIN 标记（活块从命令回显起显示），哨兵用
+    调用方给的随机 marker。sudo su - / vim 等退出后 shell 会接着执行 printf，
+    worker 在字节流里扫描它即可自动检测「交互命令已结束」并取到退出码。
+    """
+    one_line = command.replace("\n", " ; ").replace("\r", " ")
+    return f"{one_line} ; printf '{marker}_%s__\\n' \"$?\"\r"
+
+
+def _clean(raw: bytes) -> str:
+    raw = _ANSI_RE.sub(b"", raw)
+    return raw.decode("utf-8", errors="replace").replace("\r", "").rstrip("\n")
+
+
+def slice_capture(data: bytes) -> tuple[str, int, str] | None:
+    """从 PTY 字节流里切出（命令输出, exit_code, cwd）；哨兵未到齐返回 None。"""
+    # 必须锚定"标记 + 真实换行"：tty 回显的命令行里也含字面 __OT_BEGIN__\n，
+    # 但那是引号内的反斜杠+n 两字符，后面并非真正的 CR/LF（真实 printf 输出
+    # 在 cooked PTY 上是 __OT_BEGIN__\r\n）。
+    m_begin = _BEGIN_RE.search(data)
+    if not m_begin:
+        return None
+    body_start = m_begin.end()
+    end_idx = data.find(END_MARKER.encode(), body_start)
+    if end_idx < 0:
+        return None
+    line_end = data.find(b"\n", end_idx)
+    # 切片右端是排他的，必须把行尾 \n 包进窗口，否则要求 \r?\n 收尾的
+    # _END_RE 永不匹配。
+    search_end = line_end + 1 if line_end > 0 else len(data)
+    m = _END_RE.search(data[end_idx:search_end])
+    if not m:
+        return None
+    output = _clean(data[body_start:end_idx])
+    cwd = m.group(2).decode("utf-8", errors="replace")
+    return output, int(m.group(1)), cwd
+
+
+def truncate_output(text: str, limit: int) -> tuple[str, bool]:
+    if len(text) <= limit:
+        return text, False
+    head = text[: limit // 2]
+    tail = text[-limit // 2 :]
+    return f"{head}\n\n... 输出已截断（中间省略）...\n{tail}", True
+
+
+class BasePtySession:
+    """子类提供字节级读写，本类实现哨兵主循环、超时、截断、断线恢复。"""
+
+    def __init__(self, *, default_timeout: int = 120, max_output_bytes: int = 102_400):
+        self.cwd = ""
+        self._buf = bytearray()
+        self._default_timeout = default_timeout
+        self._max_output = max_output_bytes
+        # 一个 PTY 就是一条交互式 shell：模型一轮并行发起多个 execute 时，
+        # langgraph 会并发调用 run()，而哨兵捕获/cwd 跟踪都要求命令严格串行，
+        # 否则两条命令的写入与回读互相截胡（命令拼坏、输出互吞、超时重置）。
+        self._run_lock = asyncio.Lock()
+        # 断线自动重连成功后的回调（async def () -> None），worker 用于把
+        # 历史命令重新注入新 shell；None = 无操作。
+        self.on_reconnect = None
+
+    def _wrap(self, command: str) -> str:
+        """把命令包进哨兵；POSIX shell 语法，PowerShell 会话覆写此方法。"""
+        return wrap_command(command)
+
+    def _wrap_passthrough(self, command: str, marker: str) -> str:
+        """交互式内联直通包装；PowerShell 会话覆写此方法。"""
+        return wrap_passthrough(command, marker)
+
+    # --- 子类实现 ---
+    async def _write_raw(self, data: bytes) -> None:
+        raise NotImplementedError
+
+    async def drain_to_silence(self, quiet: float = 0.2) -> None:
+        """排空积压输出直到静默（默认无操作，本地会话覆写）。
+
+        只在**哨兵批写入前**调用：本地 tty 回显/重绘会把哨兵锚点搞乱
+        （zle cooked 模式整行回显、ConPTY 提示符重绘）。交互按键
+        （send_raw）绝不能排空——那会与 _pump_loop 抢读、吞掉提示符/
+        OSC 标记字节，还给每次按键加固定 quiet 延迟。
+        """
+        return
+
+    async def _read_some(self, idle_timeout: float) -> bytes:
+        raise NotImplementedError
+
+    async def _interrupt(self) -> None:
+        raise NotImplementedError
+
+    async def recover(self) -> bool:
+        """外部（worker 键盘路径）触发的断线恢复；成功时已回调 on_reconnect。"""
+        return await self._recover_connection()
+
+    async def _recover_connection(self) -> bool:
+        return False
+
+    async def _notify_reconnect(self) -> None:
+        """重连成功后通知 worker（历史注入等）；回调异常不外泄。"""
+        cb = self.on_reconnect
+        if cb is None:
+            return
+        try:
+            await cb()
+        except Exception:  # noqa: BLE001 - 钩子失败不能打断恢复流程
+            pass
+
+    async def _still_alive(self) -> bool:
+        """超时中断后哨兵缺失时的存活探测；默认不探测（视为已死）。
+
+        PowerShell 的 Ctrl-C 会中止整行提交、finally 里的 END 哨兵也不
+        输出，但 shell 本身还活着——ConPTY 会话覆写此方法保住会话状态。
+        """
+        return False
+
+    # --- 主循环 ---
+    async def run(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        on_output: Callable[[str], None] | None = None,
+    ) -> CommandResult:
+        async with self._run_lock:
+            return await self._run_locked(
+                command, timeout=timeout, on_output=on_output)
+
+    async def _run_locked(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+        on_output: Callable[[str], None] | None = None,
+    ) -> CommandResult:
+        effective = timeout or self._default_timeout
+        self._buf.clear()
+        tee_started = False
+        deadline = asyncio.get_running_loop().time() + effective
+        try:
+            # 哨兵批写入前排空到静默（本地会话：防回显/重绘错位锚点；
+            # SSH 无此问题，基类默认 no-op）。交互按键不经过这里。
+            await self.drain_to_silence()
+            await self._write_raw(self._wrap(command).encode())
+        except (ConnectionError, EOFError):
+            if await self._recover_connection():
+                return self._reconnected_result()
+            raise
+
+        while True:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                return await self._handle_timeout()
+            try:
+                chunk = await self._read_some(min(5.0, remaining))
+            except asyncio.TimeoutError:
+                continue
+            except (ConnectionError, EOFError):
+                if await self._recover_connection():
+                    return self._reconnected_result()
+                raise
+            if not chunk:
+                if await self._recover_connection():
+                    return self._reconnected_result()
+                raise ConnectionError("shell 通道已关闭")
+
+            prev_len = len(self._buf)
+            self._buf.extend(chunk)
+            if on_output:
+                # 实时回显：从真实 BEGIN 标记行起、到 END 止，原样 tee（保留颜色）。
+                # 用 _BEGIN_RE（标记+真实换行）锚定，跳过命令行 tty 回显。
+                if not tee_started:
+                    m_begin = _BEGIN_RE.search(self._buf)
+                    if m_begin:
+                        tee_started = True
+                        head = bytes(self._buf[m_begin.end() :])
+                        if END_MARKER.encode() in head:
+                            head = head[: head.find(END_MARKER.encode())]
+                        if head:
+                            on_output(head.decode("utf-8", errors="replace"))
+                else:
+                    view = chunk
+                    if END_MARKER.encode() in view:
+                        view = view[: view.find(END_MARKER.encode())]
+                    if view:
+                        on_output(view.decode("utf-8", errors="replace"))
+
+            sliced = slice_capture(bytes(self._buf))
+            if sliced is not None:
+                output, code, cwd = sliced
+                output, truncated = truncate_output(output, self._max_output)
+                if not output:
+                    output = "<no output>"
+                self.cwd = cwd or self.cwd
+                return CommandResult(output=output, exit_code=code,
+                                     truncated=truncated, cwd=self.cwd)
+
+            # 兜底：sudo/su/ssh 出现密码提示 → 提前中断，别等 120s 超时丢会话。
+            # 仅当提示串位于缓冲末尾（真实提示阻塞等待输入、其后无换行）才触发，
+            # 避免误杀输出里恰好含 password 字样的正常命令。
+            m = _PASSWORD_PROMPT_RE.search(self._buf)
+            if m and b"\n" not in self._buf[m.end():] and _needs_password_prompt(command):
+                await self._interrupt()
+                hint = (
+                    "检测到密码/凭据提示：该命令需要交互输入密码，命令模式无法完成。\n"
+                    "请按 Ctrl+R 进入终端透传模式手动执行（Web 端切换透传模式），"
+                    "或先执行 sudo -v 刷新凭据后再试。"
+                )
+                if on_output is not None:
+                    on_output(hint + "\n")
+                return CommandResult(
+                    output=hint, exit_code=130, truncated=False, cwd=self.cwd,
+                )
+
+            # 防止异常输出无限占内存：保留尾部，哨兵在尾部 64KB 内必能再次出现
+            if len(self._buf) > max(self._max_output * 4, 1_000_000):
+                del self._buf[: len(self._buf) - 262_144]
+
+    def _reconnected_result(self) -> CommandResult:
+        return CommandResult(
+            output="[ssh] 连接中断后已自动重连；为避免非幂等重复执行，原命令未重跑，"
+                   "请确认后重试。",
+            exit_code=1,
+            truncated=False,
+            cwd=self.cwd,
+            reconnected=True,
+        )
+
+    async def _handle_timeout(self) -> CommandResult:
+        # 先 Ctrl-C 给命令优雅退出的机会，再等 3 秒哨兵
+        await self._interrupt()
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 3
+        while loop.time() < deadline:
+            try:
+                self._buf.extend(await self._read_some(deadline - loop.time()))
+            except asyncio.TimeoutError:
+                break
+            except (ConnectionError, EOFError):
+                break
+            if slice_capture(bytes(self._buf)) is not None:
+                output, code, cwd = slice_capture(bytes(self._buf))  # type: ignore[misc]
+                self.cwd = cwd or self.cwd
+                return CommandResult(
+                    output=f"{output}\n\n[命令在 {self._default_timeout}s 后被中断 (Ctrl-C)",
+                    exit_code=130, truncated=False, cwd=self.cwd,
+                )
+        if await self._still_alive():
+            return CommandResult(
+                output=f"[命令在 {self._default_timeout}s 后被中断 (Ctrl-C)，"
+                       "shell 仍存活，会话状态保留。]",
+                exit_code=130, truncated=False, cwd=self.cwd,
+            )
+        if await self._recover_connection():
+            return self._reconnected_result()
+        return CommandResult(
+            output=f"Error: 命令超时（{self._default_timeout}s），shell 已重置，会话状态丢失。",
+            exit_code=124, truncated=False, cwd=self.cwd,
+        )

openterminal/session/local_posix.py

@@ -0,0 +1,184 @@
+"""macOS/Linux 本地持久 shell：openpty + 非阻塞读取。"""
+
+from __future__ import annotations
+
+import asyncio
+import fcntl
+import os
+import pty
+import signal
+import struct
+import termios
+
+from .base import BasePtySession, CommandResult
+
+
+def _stall_dbg(n: int, first: bool = False) -> None:
+    """临时排障：写入 EAGAIN 停滞计数（OT_WEB_DEBUG=1 时可见）。"""
+    import os as _os
+    if _os.environ.get("OT_WEB_DEBUG"):
+        import sys
+        print(f"[otdbg] write stalled x{n}{'' if first else ' (recovered)'}",
+              flush=True)
+
+
+class LocalPtySession(BasePtySession):
+    def __init__(self, shell: str | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._shell = shell or os.environ.get("SHELL", "/bin/bash")
+        self._pid: int | None = None
+        self._fd: int | None = None
+        # 写入停顿期的输出接收器（asyncio 单线程，同步回调）：setup 注入期
+        # 由 worker 设为喂 StreamRouter，打破回显塞满输出队列的死锁
+        self._write_sink = None
+
+    async def start(self) -> None:
+        pid, fd = pty.fork()
+        if pid == 0:  # 子进程
+            try:
+                env = os.environ.copy()
+                env["TERM"] = "xterm-256color"
+                os.execve(self._shell, [self._shell, "-l"], env)
+            except Exception:
+                os._exit(127)
+        self._pid, self._fd = pid, fd
+        # 壳继承进程 CWD（pty.fork 不 chdir）：文件根 _local_root 在构造时读
+        # session.cwd，这里不填就会空着回退主目录——用户/测试的相对文件全踩空
+        self.cwd = os.getcwd()
+        flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+        await self.resize(40, 120)
+        # 等初始提示符输出排空
+        await self._quiet()
+
+    async def _quiet(self) -> None:
+        # 偏离计划（最小）：必须先等到 shell 的首批输出，再做静默排空。
+        # 本机登录 zsh 加载 rc 时约 2.4s 内无任何输出；原实现首次 0.5s
+        # 超时即返回，会让命令在行编辑器就绪前写入，zsh 随后重绘该行，
+        # 重绘文本里的字面哨兵会把 slice_capture 的锚点永久锁死。
+        try:
+            if not await self._read_some(5.0):
+                return
+            while True:
+                await self._read_some(0.5)
+        except (asyncio.TimeoutError, OSError):
+            pass
+
+    async def _write_raw(self, data: bytes) -> None:
+        assert self._fd is not None
+        # 直写，不排空：交互按键（send_raw）走这里，排空会与主循环读者
+        # 抢 fd 数据、吞掉提示符/OSC 标记字节，还引入固定 200ms 延迟。
+        # fd 是 O_NONBLOCK（读泵需要）：tty 输入队列满（TTYHOG）时 write
+        # 抛 BlockingIOError，须等待消费者（shell 行编辑器）排空后重试。
+        # 死锁防护：若写方回显已塞满输出队列（泵未启动的 setup 注入期），
+        # 行规程因 echo 无处写而拒绝接受输入 → 双向永久 EAGAIN。此时
+        # _write_sink（setup 注入期设为喂 router）边写边读输出，打破死锁；
+        # 无 sink 时丢弃——该输出本就无读者，不丢则死锁。
+        stalls = 0
+        while data:
+            try:
+                n = os.write(self._fd, data)
+                data = data[n:]
+                if stalls:
+                    _stall_dbg(stalls)
+                    stalls = 0
+            except BlockingIOError:
+                stalls += 1
+                if stalls == 100:
+                    _stall_dbg(stalls, first=True)
+                got = b""
+                if self._write_sink is not None:
+                    try:
+                        got = os.read(self._fd, 65_536)
+                    except (BlockingIOError, OSError):
+                        got = b""
+                    if got:
+                        self._write_sink(got)
+                await asyncio.sleep(0.02)
+
+    async def drain_to_silence(self, quiet: float = 0.2) -> None:
+        # 哨兵批写入前：排空到静默。上一条命令的哨兵返回时，zsh 往往还没
+        # 画完新提示符，此刻 tty 处于 cooked 模式：写入会被行规范整行回显，
+        # 再被 zle 重绘，产生多份带真实换行的字面哨兵，使 slice_capture
+        # 锚点永久错位。等提示符画完（zle 就绪）再写。仅批路径调用。
+        while True:
+            try:
+                chunk = await self._read_some(quiet)
+            except (asyncio.TimeoutError, OSError):
+                break
+            if not chunk:
+                break
+
+    async def _read_some(self, idle_timeout: float) -> bytes:
+        assert self._fd is not None
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[bytes] = loop.create_future()
+
+        def _readable() -> None:
+            if fut.done():
+                return
+            try:
+                data = os.read(self._fd, 65_536)
+            except BlockingIOError:
+                return
+            except OSError:
+                fut.set_result(b"")
+                return
+            fut.set_result(data)
+
+        loop.add_reader(self._fd, _readable)
+        try:
+            return await asyncio.wait_for(fut, timeout=idle_timeout)
+        finally:
+            loop.remove_reader(self._fd)
+
+    async def _interrupt(self) -> None:
+        if self._fd is not None:
+            os.write(self._fd, b"\x03")  # Ctrl-C
+
+    async def _recover_connection(self) -> bool:
+        """本地：关掉死掉的进程组并重启 shell，语义等同"重新连上"。"""
+        await self.close()
+        try:
+            await self.start()
+            await self._notify_reconnect()
+            return True
+        except OSError:
+            return False
+
+    async def _handle_timeout(self) -> CommandResult:
+        # 偏离计划（最小）：Ctrl-C 后 zsh 会直接丢弃当前命令行、不打印哨兵，
+        # 基类于是重启 shell 并返回 reconnected（exit 1）。本地重启后会话
+        # 状态确已丢失，按超时语义返回 124（Task 4 测试约定 124/130）。
+        result = await super()._handle_timeout()
+        if result.reconnected:
+            return CommandResult(
+                output=f"Error: 命令超时（{self._default_timeout}s），shell 已重置，会话状态丢失。",
+                exit_code=124, truncated=False, cwd=self.cwd,
+            )
+        return result
+
+    async def resize(self, rows: int, cols: int) -> None:
+        if self._fd is None:
+            return
+        size = struct.pack("HHHH", rows, cols, 0, 0)
+        fcntl.ioctl(self._fd, termios.TIOCSWINSZ, size)
+
+    async def send_raw(self, data: bytes) -> None:
+        await self._write_raw(data)
+
+    async def close(self) -> None:
+        if self._pid is not None:
+            try:
+                os.killpg(os.getpgid(self._pid), signal.SIGKILL)
+            except (ProcessLookupError, OSError):
+                try:
+                    os.kill(self._pid, signal.SIGKILL)
+                except (ProcessLookupError, OSError):
+                    pass
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            except OSError:
+                pass
+        self._pid = self._fd = None

openterminal/session/local_win.py

@@ -0,0 +1,173 @@
+"""Windows 本地持久 shell：ConPTY（pywinpty）+ 专职读者线程。
+
+与 LocalPtySession 实现同一个 ShellSession 协议（BasePtySession 哨兵主循环
+复用），差别只在字节层：ConPTY 没有非阻塞 fd，用线程阻塞读并经线程安全
+队列投递给事件循环。命令包装用 PowerShell 语法覆写 _wrap。
+
+仅 Windows 可导入；Linux/macOS 路径不经过本模块。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+
+from .base import BasePtySession
+
+
+class WinPtySession(BasePtySession):
+    def __init__(self, shell: str | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._shell = shell or "powershell.exe -NoLogo"
+        self._proc = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._queue: asyncio.Queue[bytes] | None = None
+        self._reader: threading.Thread | None = None
+
+    # --- PowerShell 哨兵包装（与 wrap_command 的 POSIX 版对应）---
+    def _wrap(self, command: str) -> str:
+        one_line = command.replace("\n", " ; ").replace("\r", " ")
+        # 结尾必须 \r：PSReadLine 把 LF 当 Shift-Enter（编辑缓冲区换行、
+        # 出 >> 续行提示），命令不会被提交执行
+        # 退出码：先清 $LASTEXITCODE——原生命令码只在它非空时取（cmd /c
+        # exit 3 时 $? 也是 False，不能用它兜底）；为空说明只跑了 cmdlet，
+        # 用 $? 判成败。try/finally 让正常路径的 END 一定输出
+        return (
+            "$LASTEXITCODE = $null; Write-Output '__OT_BEGIN__'; "
+            "try { " + one_line + " } finally { "
+            "$otc = if ($null -eq $LASTEXITCODE) { "
+            "if ($?) { 0 } else { 1 } } else { $LASTEXITCODE }; "
+            "Write-Output ('__OT_END__' + $otc + '__'"
+            " + (Get-Location).Path + '__') }\r"
+        )
+
+    def _wrap_passthrough(self, command: str, marker: str) -> str:
+        one_line = command.replace("\n", " ; ").replace("\r", " ")
+        # 与 POSIX 版一致：交互程序退出后输出带随机 marker 的哨兵；
+        # $LASTEXITCODE 为空说明只跑了 cmdlet/无原生命令退出码，按 0 处理
+        return (one_line + " ; Write-Output ('" + marker + "_' + "
+                "$(if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } else { 0 })"
+                " + '__')\r")
+
+    # --- 生命周期 ---
+    async def start(self) -> None:
+        from winpty import PtyProcess
+
+        self._proc = PtyProcess.spawn(
+            self._shell.split(), dimensions=(40, 120))
+        # 同 local_posix：壳继承进程 CWD，文件根构造时读 session.cwd
+        self.cwd = os.getcwd()
+        self._loop = asyncio.get_running_loop()
+        self._queue = asyncio.Queue()
+        self._reader = threading.Thread(
+            target=self._pump, name="ot-conpty-reader", daemon=True)
+        self._reader.start()
+        await self._quiet()  # 等 PowerShell 横幅/提示符排空
+
+    async def _quiet(self) -> None:
+        try:
+            if not await self._read_some(10.0):
+                return
+            while True:
+                await self._read_some(0.5)
+        except (asyncio.TimeoutError, OSError):
+            pass
+
+    def _pump(self) -> None:
+        """专职读者线程：ConPTY 无非阻塞读，阻塞读并投递进事件循环。"""
+        assert self._loop is not None and self._queue is not None
+        while self._proc is not None:
+            try:
+                data = self._proc.read(65_536)
+            except (EOFError, OSError):
+                self._loop.call_soon_threadsafe(self._queue.put_nowait, b"")
+                return
+            if not data:
+                continue
+            payload = data if isinstance(data, bytes) else \
+                data.encode("utf-8", errors="replace")
+            self._loop.call_soon_threadsafe(self._queue.put_nowait, payload)
+
+    # --- 字节层 ---
+    async def _write_raw(self, data: bytes) -> None:
+        # 直写，不排空：交互按键（send_raw）走这里，排空会与 pump 的
+        # 读者线程抢读、吞掉提示符/OSC 标记字节，还引入固定 200ms 延迟。
+        # 哨兵批写入需要静默的场景由 drain_to_silence()（仅批路径调用）承担。
+        if self._proc is not None:
+            self._proc.write(data.decode("utf-8", errors="replace"))
+
+    async def drain_to_silence(self, quiet: float = 0.2) -> None:
+        # 哨兵批写入前：排空到静默，避免回显/重绘把哨兵锚点搞乱
+        while True:
+            try:
+                chunk = await self._read_some(quiet)
+            except (asyncio.TimeoutError, OSError):
+                break
+            if not chunk:
+                break
+
+    async def _read_some(self, idle_timeout: float) -> bytes:
+        assert self._queue is not None
+        return await asyncio.wait_for(self._queue.get(), timeout=idle_timeout)
+
+    async def _interrupt(self) -> None:
+        if self._proc is not None:
+            try:
+                self._proc.sendintr()  # Ctrl-C
+            except OSError:
+                pass
+
+    async def _recover_connection(self) -> bool:
+        """本地 shell 死掉：关掉重启，语义等同"重新连上"。"""
+        await self.close()
+        try:
+            await self.start()
+            await self._notify_reconnect()
+            return True
+        except OSError:
+            return False
+
+    async def _still_alive(self) -> bool:
+        """超时 Ctrl-C 后 shell 通常还活着（PS 的中断只作废当前行，
+        finally 里的 END 哨兵不会输出）。发一条探针命令确认，避免整个
+        会话被无谓重启、cd 等状态丢失。"""
+        probe = "Write-Output ('ot-al' + 'ive-ok')\r"
+        try:
+            await self._write_raw(probe.encode())
+        except (ConnectionError, EOFError, OSError):
+            return False
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 5
+        buf = b""
+        while loop.time() < deadline:
+            try:
+                chunk = await self._read_some(min(2.0, deadline - loop.time()))
+            except asyncio.TimeoutError:
+                continue  # 高负载下回显可能迟于单次 2s 读：等满 5s 总预算
+            except (ConnectionError, EOFError, OSError):
+                return False
+            # 探针命令回显里是 'ot-al'+'ive-ok' 拆开的，只有真实输出才出现
+            # 连续的 ot-alive-ok；标记可能跨 chunk 拆分，累积后再判断
+            buf += chunk
+            if b"ot-alive-ok" in buf:
+                return True
+        return False
+
+    async def resize(self, rows: int, cols: int) -> None:
+        if self._proc is not None:
+            try:
+                self._proc.setwinsize(rows, cols)
+            except OSError:
+                pass
+
+    async def send_raw(self, data: bytes) -> None:
+        await self._write_raw(data)
+
+    async def close(self) -> None:
+        proc, self._proc = self._proc, None
+        if proc is not None:
+            try:
+                proc.terminate(force=True)
+            except OSError:
+                pass
+        # 读者线程随 proc 关闭读到 EOFError 自行退出