ot-cli 0.2.1__py3-none-any.whl

openterminal/core/pump.py

@@ -0,0 +1,190 @@
+"""输出泵（Task 8 自 PipelineCore 原样搬入）——责任链编排。
+
+PTY 字节块到达后的固定次序（分支顺序/判断条件/字节处理与搬移前逐字
+一致，第一版逐条委托原组件）：
+
+    字节块到达 →
+      1. exec_events.strip_intr_echo()      # ^C 回显吞除
+      2. auth.inspect_output()              # 密码提示符/验证窗/模态代关
+      3. hook.observe_output() + note_mark  # hook 观测/shell 退出检测
+      4. exec_events.on_stream_event/feed   # exec 标记流（OSC 切分）
+      5. live 透传（emit_bytes + 幕帘扣留）
+
+泵任务体 _pump_loop 挂 _pump_guard 死亡留痕（引用被 core._pump 持有，
+asyncio 不报「未取回异常」——真机「终端彻底沉默」盲区）。
+状态**物理存 core 实例**（P3 裁定延续：close/_switch_target/测试直读
+core._pump/_sender；OutputPump.__init__ 以 hasattr 守卫补建，预置值
+不覆盖），方法体经 self.core 访问，phase 只读转发 core._pump_phase。
+_reap_zombie_ai（读 _ai_ping_at）与 _pump_eof 留 core（任务生命周期域）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from .messages import ServerMsg, _dbg
+
+
+class OutputPump:
+    def __init__(self, core) -> None:
+        self.core = core
+        for name, val in (
+            ("_sender", None),          # 出站发送任务（attach 起，close 自然退）
+            ("_pump", None),            # 输出泵任务（连接就绪起）
+            ("_pump_phase", "read"),    # 排障：泵当前所处 stage（心跳打出）
+        ):
+            if not hasattr(core, name):
+                setattr(core, name, val)
+
+    # --- 组件公开接口 ---
+    def start(self) -> None:
+        """起 _pump/_sender/_heartbeat（已运行则跳过；连接后语境调用）。"""
+        c = self.core
+        if c._sender is None:
+            c._sender = asyncio.create_task(self._sender_loop())
+        if c._hb is None:
+            c._hb = asyncio.create_task(self._heartbeat())
+        if c._pump is None or c._pump.done():
+            c._pump = asyncio.create_task(self._pump_guard())
+        if getattr(c, "_loop_beat", None) is None:
+            c._loop_beat = asyncio.create_task(self._loop_watchdog())
+
+    @property
+    def phase(self) -> str:
+        """泵当前所处 stage（排障心跳打出）。"""
+        return self.core._pump_phase
+
+    async def _pump_guard(self) -> None:
+        """泵死亡留痕：任务引用被 self.core._pump 持有，异常永远不会被 asyncio 当作
+        「未取回」打印出来——真机「终端彻底不再回显、日志一片安静」就此查无
+        实据（第 3 轮复现里降级路径之后 90s 零字节的盲区）。"""
+        try:
+            await self._pump_loop()
+        except asyncio.CancelledError:
+            raise
+        except BaseException:  # noqa: BLE001 - 只为留痕，原样重抛
+            import traceback
+            _dbg("pump died:", traceback.format_exc())
+            raise
+    async def _loop_watchdog(self) -> None:
+        """事件循环活性探针：2s 一跳，停跳即证明循环阻塞（阻塞点=最后日志后）。
+        真机「连接无响应」根因排查用——普通日志看不出循环死活。"""
+        import time as _t
+        n = 0
+        while not self.core._closed:
+            await asyncio.sleep(2)
+            n += 1
+            _dbg("loop beat", n)
+
+    async def _pump_loop(self) -> None:
+        """PTY 泵：回退/Shell 模式纯透传；集成模式下按 OSC 标记切分——
+        标记字节与需吞除的注入回显不外发，其余原样转发（唯一显示管线）。"""
+        _tick = 0
+        while not self.core._closed:
+            try:
+                data = await self.core.session._read_some(0.2)
+            except asyncio.TimeoutError:
+                # 心跳：读超时是稳态，每 10 次（≈2s）留一行。它把「远端真的
+                # 沉默」与「泵死了/卡在处理器里」分开——心跳仍在 = 泵活着且
+                # _read_some 正常返回，字节确实没来（第 3 轮真机盲区）。
+                _tick += 1
+                if _tick % 10 == 0:
+                    _dbg("pump tick", _tick, "phase=", self.core._pump_phase)
+                continue
+            except (ConnectionError, EOFError):
+                await self.core._pump_eof("连接已断开")
+                return
+            if data == b"":     # 本地 PTY 读者线程的 EOF 哨兵（如用户 exit）
+                await self.core._pump_eof("会话已结束")
+                return
+            if not data:
+                continue
+            self.core._pump_phase = "body"
+            _dbg("raw", len(data), repr(data[:60]))
+            if self.core._cs_tail is not None:
+                self.core._cs_tail.extend(data)
+                if len(self.core._cs_tail) > 8192:
+                    del self.core._cs_tail[:-8192]   # 只留尾部:提示匹配只需最近输出
+            if self.core._intr_swallow_until:
+                data = self.core.exec._strip_intr_echo(data)
+                if not data:
+                    _dbg("intr swallow: 整块被 ^C 回显吞除")
+                    continue
+            self.core.auth.inspect_output(data)
+            await self.core.hook._detect_shell_exit(data)
+            if not self.core._interactive or self.core._display == "ssh":
+                self.core._pump_phase = "passthru"
+                await self.core.emit_bytes(data)   # 回退模型 / Shell 模式：纯透传
+                continue
+            for ev in self.core._router.feed(data):
+                self.core._pump_phase = "ev:" + str(ev[0])
+                await self.core.exec.on_stream_event(ev)
+            self.core._pump_phase = "read"
+    async def _stop_pump(self) -> None:
+        """停输出泵并等它真正退出。只 cancel 不等的话，泵可能还压在
+        _read_some 上，抢走随后命令/探测的回显与哨兵字节（哨兵流被切坏
+        → run 拿空输出）。"""
+        if self.core._pump is not None:
+            t, self.core._pump = self.core._pump, None
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                # 外层任务在 `await t` 上被取消时，取消会传导给泵任务
+                # （await task 的 waiter 就是任务本身），泵的 CancelledError
+                # 会从这里冒出来——不能吞，否则外层的取消也被吞掉，任务
+                # 变成杀不死的僵尸（teardown gather 挂死）
+                if asyncio.current_task().cancelling() > 0:
+                    raise
+            except Exception:  # noqa: BLE001 - 会话关闭竞态（fd 失效等）
+                pass
+    async def _heartbeat(self) -> None:
+        """应用层心跳：5s 一个 ping，给前端看门狗当「服务端还活着」基线。
+        **直发 sink 绕过 outbox**：outbox/sender 卡死时 ping 若也排队，前端就
+        误判「连接无响应」重连（真机 R8 稳定挂根因）。ping 直达 sink 保证
+        只要 WS 没死前端就看得到心跳；sender 卡死时其余帧照常排队。
+        5s（原 10s）：输出密集期 outbox 排队会让排队的 ping 迟到。"""
+        while not self.core._closed:
+            await asyncio.sleep(5)
+            if self.core._closed:
+                break
+            # 直发 sink：不经 outbox，不与业务帧抢 sender
+            sink = self.core._sink
+            if sink is not None:
+                try:
+                    from ..web.protocol import encode_server
+                    from ..core.messages import ServerMsg
+                    await asyncio.wait_for(
+                        sink.send_text(encode_server(ServerMsg(type="ping"))),
+                        timeout=3)
+                except Exception:  # noqa: BLE001 - sink 死/慢：走 outbox 兜底
+                    self.core._emit_nowait(ServerMsg(type="ping"))
+            else:
+                self.core._emit_nowait(ServerMsg(type="ping"))
+            await self.core._reap_zombie_ai()
+    async def _sender_loop(self) -> None:
+        while True:
+            kind, payload = await self.core._outbox.get()
+            sink = self.core._sink
+            if sink is None:
+                self.core._buffer_offline(kind, payload)
+            else:
+                try:
+                    if kind == "bytes":
+                        await sink.send_bytes(payload)
+                    else:
+                        await sink.send_text(payload)
+                except Exception:
+                    # sink 已死但 detach 尚未回来（网络刚断的那几毫秒）：帧必须
+                    # 攒住，否则断线瞬间发出的收束帧就永久丢了（旧实现 continue
+                    # 直接丢弃）。顺手摘掉死 sink，后续帧不再逐条撞异常。
+                    if self.core._sink is sink:
+                        self.core._sink = None
+                    self.core._buffer_offline(kind, payload)
+            # 关闭后把剩余消息发完（含 closed）再退出，避免协程泄漏。
+            # 只看 _closed 不够：close 会先置 _closed 再入队 closed，若此刻
+            # backlog 未排空，sender 会在 closed 入队前按 empty 提前退出
+            if self.core._closed and self.core._closed_sent and self.core._outbox.empty():
+                break
+
+    # --- 主流程 ---

openterminal/core/transcript.py

@@ -0,0 +1,26 @@
+"""会话 JSONL 记录。"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+from pathlib import Path
+
+from ..config import app_dir
+
+
+class Transcript:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, kind: str, **fields) -> None:
+        row = {"ts": dt.datetime.now().isoformat(timespec="seconds"),
+               "kind": kind, **fields}
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def open_transcript(session_id: str) -> Transcript:
+    day = dt.date.today().isoformat()
+    return Transcript(app_dir() / "sessions" / day / f"{session_id}.jsonl")

openterminal/frontend/__init__.py

@@ -0,0 +1,21 @@
+"""frontend 域（阶段二 Task 15 重组）。
+
+term.py——终端交互前端（TermFrontend/CliCore/CliRenderer，输入捕获与
+状态栏）；approval.py——审批决定归一化；render.py——Console 与命令/
+结果渲染；banner.py——启动横幅；taskview.py——任务呈现（TaskPresenter/
+ThinkingStream）；headless.py——无头执行模式（退出码约定/目标解析）。
+本 __init__ 再导出旧六模块全部公开名，旧 import 路径
+（``from openterminal.term_frontend import ...`` 等）不因拆包而变。
+"""
+
+from .approval import decision_for_choice, edit_decision, reclassify_edited  # noqa: F401
+from .banner import print_banner  # noqa: F401
+from .headless import (  # noqa: F401
+    DEFAULT_EXEC_TIMEOUT, EXIT_APPROVAL_REQUIRED, EXIT_CONNECT_FAILED,
+    EXIT_DENIED, EXIT_HOST_KEY, EXIT_TARGET_NOT_FOUND, EXIT_USAGE,
+    all_targets, resolve_target, run_headless,
+)
+from .render import console, print_answer, print_command, print_denied, \
+    print_summary  # noqa: F401
+from .taskview import TaskPresenter, ThinkingStream  # noqa: F401
+from .term import CliCore, CliRenderer, TermFrontend  # noqa: F401

openterminal/frontend/approval.py

@@ -0,0 +1,40 @@
+"""审批交互的纯决策部分；TUI 提示在 cli.py。"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from ..policy import Decision, Policy
+
+Choice = Literal["y", "e", "n", "a"]
+
+
+def reclassify_edited(new_command: str, policy: Policy) -> Decision:
+    """编辑后的命令必须重新过一遍策略。"""
+    return policy.classify(new_command)
+
+
+def decision_for_choice(
+    choice: str,
+    command: str,
+    policy: Policy,
+    allowed: set[str],
+) -> dict | None:
+    if choice == "y":
+        return {"type": "approve"}
+    if choice == "a":
+        allowed.add(command)
+        return {"type": "approve"}
+    if choice == "n":
+        return {"type": "reject", "message": "用户拒绝了该命令"}
+    return None  # e：由 CLI 收集编辑后的命令
+
+
+def edit_decision(new_command: str) -> dict:
+    return {
+        "type": "edit",
+        "edited_action": {
+            "name": "execute",
+            "args": {"command": new_command},
+        },
+    }

openterminal/frontend/banner.py

@@ -0,0 +1,40 @@
+"""启动欢迎横幅（Spring Boot banner 风格）。
+
+字形由 pyfiglet "standard" 字体生成后固化为常量——运行时不引入该依赖。
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.text import Text
+
+from .render import console
+
+_BANNER = r"""                        _                      _             _
+  ___  _ __   ___ _ __ | |_ ___ _ __ _ __ ___ (_)_ __   __ _| |
+ / _ \| '_ \ / _ \ '_ \| __/ _ \ '__| '_ ` _ \| | '_ \ / _` | |
+| (_) | |_) |  __/ | | | ||  __/ |  | | | | | | | | | | (_| | |
+ \___/| .__/ \___|_| |_|\__\___|_|  |_| |_| |_|_|_| |_|\__,_|_|
+      |_|                                                        """
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("openterminal")
+    except Exception:
+        return "0.1.0"
+
+
+def print_banner() -> None:
+    """打印 ASCII 横幅 + 版本信息行。无头模式（exec/list）不要调用。"""
+    console.print(Text("\n" + _BANNER, style="bold green"))
+    label, ver = " :: OpenTerminal ::", f"(v{_version()})"
+    console.print(
+        label + " " * (len(_BANNER.splitlines()[1]) - len(label) - len(ver))
+        + ver + f"  ·  Python {sys.version.split()[0]}",
+        style="green",
+    )
+    console.print()

openterminal/frontend/headless.py

@@ -0,0 +1,290 @@
+"""无头执行面：ot exec / ot list——供外部 AI 编程工具（Claude Code、opencode
+等）以子进程方式调用，无需进入 REPL。
+
+设计对齐"Agent 优先"原则：
+- --output json 输出结构化结果，退出码分层：远程命令退出码原样透传（< 64），
+  工具自身错误使用 ≥ 64 的保留码，Agent 可据此区分"远程成败"与"调用问题"。
+- 审批不走交互：Policy 分级映射为协议行为——auto 执行、deny/APPROVAL
+  结构化拒绝，出路只有"人的动作"（交互界面记住允许 / 编辑 config）。
+- 主机指纹沿用 TOFU，但无头下不询问：known_hosts 未收录即结构化报错，
+  请用户先在交互界面连接一次。
+
+退出码表：
+  0/1~63  远程命令退出码透传（与 SSH 行为一致）；远程码若恰好落在
+          64~69 工具保留段则收敛为 63——保证「≥64 必是工具问题」的
+          判别契约，真实值仍在 JSON payload 的 exit_code 字段里
+  64      用法错误
+  65      目标不存在
+  66      策略拒绝（deny）
+  67      需要用户审批（approve）
+  68      连接/认证失败
+  69      主机指纹未收录（TOFU）
+  124     超时（由会话层哨兵超时返回，经透传路径自然到达）
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import difflib
+import json
+import sys
+
+from ..config import Config, TargetConfig
+
+EXIT_USAGE = 64
+EXIT_TARGET_NOT_FOUND = 65
+EXIT_DENIED = 66
+EXIT_APPROVAL_REQUIRED = 67
+EXIT_CONNECT_FAILED = 68
+EXIT_HOST_KEY = 69
+
+DEFAULT_EXEC_TIMEOUT = 30
+
+
+# ---------------------------------------------------------------------------
+# 目标解析
+# ---------------------------------------------------------------------------
+
+def all_targets(cfg: Config) -> list[TargetConfig]:
+    """配置文件目标 + 记住的连接（记住的靠前展示，按 host 去重）。
+
+    config.toml 手写目标**不被 host 去重吞掉**——记住的连接里有同址条目
+    时（如手敲 root@1.2.3.4 记住后），同名之外的手写目标（prod 等别名）
+    仍须可被 `ot exec -t prod` 解析到；仅同名时跳过（记住的展示优先）。
+    """
+    saved = []
+    try:
+        from ..connections import load_saved_targets
+
+        saved = load_saved_targets()
+    except Exception:
+        pass  # 凭据库不可用时仍可使用 config.toml 里的目标
+    seen_keys: set[tuple] = set()
+    seen_names: set[str] = set()
+    merged: list[TargetConfig] = []
+    for t in saved:
+        key = (t.mode, t.host or t.name, t.user, t.port)
+        if key in seen_keys or t.name in seen_names:
+            continue
+        seen_keys.add(key)
+        seen_names.add(t.name)
+        merged.append(t)
+    for t in cfg.targets.values():
+        if t.name in seen_names:
+            continue
+        seen_names.add(t.name)
+        merged.append(t)
+    return merged
+
+
+def resolve_target(name: str, cfg: Config) -> tuple[TargetConfig | None, list[str]]:
+    """按名字解析目标：精确 → 模糊。返回 (目标 | None, 候选名列表)。"""
+    targets = all_targets(cfg)
+    names = [t.name for t in targets]
+    for t in targets:
+        if t.name == name:
+            return t, names
+    return None, difflib.get_close_matches(name, names, n=5, cutoff=0.6)
+
+
+# ---------------------------------------------------------------------------
+# JSON 输出
+# ---------------------------------------------------------------------------
+
+def _emit(payload: dict, *, as_json: bool, file) -> None:
+    if as_json:
+        json.dump(payload, file, ensure_ascii=False, indent=2)
+        file.write("\n")
+    else:
+        file.write(payload.get("message") or payload.get("output") or "")
+
+
+# ---------------------------------------------------------------------------
+# ot exec
+# ---------------------------------------------------------------------------
+
+def _gate(command: str, cfg: Config) -> tuple[int, dict] | None:
+    """Policy 分级 → 无头协议行为。返回 (退出码, 错误 payload) 或 None（放行）。"""
+    from ..policy import Policy
+
+    p = cfg.policy
+    decision = Policy(
+        mode=p.mode,
+        auto_extra=p.auto_extra,
+        approve_extra=p.approve_extra,
+        deny_extra=p.deny_extra,
+    ).classify(command)
+    if decision.level == "auto":
+        return None
+    if decision.level == "deny":
+        return EXIT_DENIED, {
+            "code": "DENIED",
+            "command": command,
+            "reasons": decision.reasons,
+            "message": f"策略拒绝执行该命令：{'；'.join(decision.reasons)}",
+        }
+    return EXIT_APPROVAL_REQUIRED, {
+        "code": "APPROVAL_REQUIRED",
+        "command": command,
+        "reasons": decision.reasons,
+        "hint": "无头模式不执行需人工审批的命令。请让用户在 ot 交互界面执行一次"
+                "并选择『记住允许』，或将其加入 config.toml 的 policy.auto_extra。",
+        "message": f"该命令需要用户审批：{'；'.join(decision.reasons)}",
+    }
+
+
+async def _exec_async(target: TargetConfig, command: str, *, timeout: int) -> int:
+    from ..connections import open_session
+    from ..connections.secrets import load_password_alias
+
+    # 只有 SSH 目标才查凭据库：local 目标 host=None，按 None 拼 keyring
+    # 键纯属噪音（还可能撞上 keyring 后端的空键校验）。别名互查与
+    # _connect 首跳同语义（None/22 同键）。
+    password = (load_password_alias(target.host, target.user, target.port)
+                if target.mode == "ssh" and target.host else None)
+    session = await open_session(
+        target,
+        password=password,
+        # 无头模式不交互：密码提示直接失败，主机指纹预先检查
+        password_prompt=lambda label: None,
+        host_key_prompt=lambda message: False,
+    )
+    try:
+        result = await session.run(command, timeout=timeout)
+        return result
+    finally:
+        await session.close()
+
+
+def cmd_exec(args: argparse.Namespace, cfg: Config, out, err) -> int:
+    command = args.command
+    if not command:
+        _emit({"code": "USAGE", "message": "缺少 -c/--command"}, as_json=args.json, file=err)
+        return EXIT_USAGE
+
+    target, candidates = resolve_target(args.target, cfg)
+    if target is None:
+        payload = {"code": "TARGET_NOT_FOUND",
+                   "message": f"目标 '{args.target}' 不存在。"}
+        if candidates:
+            payload["candidates"] = candidates
+            payload["message"] += f" 相近的可用目标: {', '.join(candidates)}"
+        _emit(payload, as_json=args.json, file=err)
+        return EXIT_TARGET_NOT_FOUND
+
+    verdict = _gate(command, cfg)
+    if verdict is not None:
+        exit_code, payload = verdict
+        _emit(payload, as_json=args.json, file=err)
+        return exit_code
+
+    # 主机指纹 TOFU 预检：无头模式不询问，未收录直接报错
+    if target.mode == "ssh":
+        from ..session.ssh import known_hosts_has_entry, known_hosts_path
+
+        host = target.host or target.name
+        if not known_hosts_has_entry(known_hosts_path(), host, target.port):
+            _emit({"code": "HOST_KEY_UNKNOWN", "host": host,
+                   "hint": "首次连接请先在 ot 交互界面完成指纹确认（TOFU）。",
+                   "message": f"known_hosts 中没有主机 {host} 的指纹记录。"},
+                  as_json=args.json, file=err)
+            return EXIT_HOST_KEY
+
+    try:
+        result = asyncio.run(_exec_async(target, command, timeout=args.timeout))
+    except Exception as e:
+        _emit({"code": "CONNECT_FAILED", "target": target.name,
+               "message": f"连接或执行失败：{type(e).__name__}: {e}"},
+              as_json=args.json, file=err)
+        return EXIT_CONNECT_FAILED
+
+    payload = {"output": result.output,
+               "exit_code": result.exit_code,
+               "truncated": result.truncated,
+               "cwd": result.cwd,
+               "target": target.name}
+    _emit(payload, as_json=args.json, file=out)
+    rc = result.exit_code & 0xFF  # 与 shell 退出码语义一致（0~255）
+    if 64 <= rc <= 69:
+        # 远程命令退出码撞上工具保留段：进程码收敛为 63（远程失败），
+        # 保住「≥64 必是工具问题」的契约；真实值在 JSON exit_code 里
+        rc = 63
+    return rc
+
+
+# ---------------------------------------------------------------------------
+# ot list targets
+# ---------------------------------------------------------------------------
+
+def cmd_list(args: argparse.Namespace, cfg: Config, out, err) -> int:
+    if args.what != "targets":
+        _emit({"code": "USAGE", "message": f"未知子项 '{args.what}'，可用: targets"},
+              as_json=args.json, file=err)
+        return EXIT_USAGE
+    targets = [{"name": t.name, "mode": t.mode, "host": t.host or t.name,
+                "user": t.user, "port": t.port}
+               for t in all_targets(cfg)]
+    if args.json:
+        json.dump({"targets": targets}, out, ensure_ascii=False, indent=2)
+        out.write("\n")
+    else:
+        for t in targets:
+            where = t["user"] + "@" if t["user"] else ""
+            where += t["host"]
+            if t["port"]:
+                where += f":{t['port']}"
+            out.write(f"{t['name']}\t{where}\n")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# 入口
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ot",
+        description="无头执行面：供脚本与 AI 编程工具调用。无参数时进入交互 REPL。",
+    )
+    sub = parser.add_subparsers(dest="subcommand", required=True)
+
+    p_exec = sub.add_parser(
+        "exec", help="在目标上执行一条命令并返回结果",
+        epilog="退出码：<64 为远程命令退出码透传；64 用法 65 目标不存在 "
+               "66 策略拒绝 67 需审批 68 连接失败 69 指纹未收录 124 超时。"
+               "失败详情看 --output json 的 code/message 字段。",
+    )
+    p_exec.add_argument("-t", "--target", required=True, help="目标名（ot list targets 可查）")
+    p_exec.add_argument("-c", "--command", required=True, help="要执行的命令")
+    p_exec.add_argument("--timeout", type=int, default=DEFAULT_EXEC_TIMEOUT,
+                        help=f"超时秒数（默认 {DEFAULT_EXEC_TIMEOUT}）")
+    p_exec.add_argument("--output", "-o", choices=["text", "json"], default="text",
+                        help="输出格式，Agent 建议用 json")
+
+    p_list = sub.add_parser("list", help="列举资源")
+    # 不用 argparse choices：未知子项要走结构化 USAGE 错误（cmd_list 校验），
+    # 否则 argparse 直接 SystemExit(2)，Agent 拿不到 JSON
+    p_list.add_argument("what", nargs="?", default="targets",
+                        help="targets：可用目标列表")
+    p_list.add_argument("--output", "-o", choices=["text", "json"], default="text",
+                        help="输出格式")
+    for p in (p_exec, p_list):
+        p.set_defaults(json=False)
+        # argparse 处理 -o json 与 --output 同义；json 布尔由 output 推导
+    return parser
+
+
+def run_headless(argv: list[str], cfg: Config | None = None,
+                 out=None, err=None) -> int:
+    """无头入口。cfg/out/err 可注入（测试用）。返回进程退出码。"""
+    out = out if out is not None else sys.stdout
+    err = err if err is not None else sys.stderr
+    cfg = cfg if cfg is not None else Config.load()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # --output json → args.json
+    args.json = getattr(args, "output", "text") == "json"
+    if args.subcommand == "exec":
+        return cmd_exec(args, cfg, out, err)
+    return cmd_list(args, cfg, out, err)

openterminal/frontend/render.py

@@ -0,0 +1,41 @@
+"""rich 输出助手。"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+console = Console()
+
+
+def print_command(command: str, host: str, *, approved: bool = False) -> int:
+    """打印命令面板；返回面板占用的屏幕行数（供审批结束后擦除）。
+
+    行数用 capture 预渲染计数（与实际打印同一个 console，宽度一致），
+    命令很长被 word_wrap 折行时同样准确。
+    """
+    tag = "执行" if approved else "将执行"
+    panel = Panel(Syntax(command, "bash", word_wrap=True, theme="ansi_dark"),
+                  title=f"[bold cyan]{tag}[/] · {host}", border_style="cyan")
+    with console.capture() as cap:
+        console.print(panel)
+    rows = cap.get().count("\n")
+    console.print(panel)
+    return rows
+
+
+def print_denied(text: str) -> None:
+    console.print(f"[bold red]✗ {text}[/]")
+
+
+def print_summary(text: str) -> None:
+    """最终总结框。Text 包一层：模型输出里的 [xx] 不当 rich 标记解析。"""
+    console.print(Panel(Text(text), title="[bold green]📝 总结[/]",
+                        title_align="left", border_style="green"))
+
+
+def print_answer(text: str) -> None:
+    console.print(Panel(text, title="[bold green]OpenTerminal[/]",
+                        border_style="green"))