agent-cli-lib 0.1.0__py3-none-any.whl

agent_cli_lib/backends/opencode/backend.py

@@ -0,0 +1,296 @@
+"""opencode 聚合包：版本分派层 + CLI 兜底实现（v8 设计 §4.2–§4.5）。
+
+- `OpencodeBackend`：注册名 "opencode"，探测 PATH 上 opencode 的主版本并按 Spec 分派
+  （ACP 路径由 runner 路由到 AcpDriver；CLI 兜底与 export 委托给 `OpencodeCliImpl`）；
+- `Opencode2Backend`：注册名 "opencode2"，显式选 v2（opencode2 别名优先，适配 npm/curl 双装）；
+- `OpencodeCliImpl`：transport="cli" 与 export 的执行体，一个类按 spec 参数化 v1/v2。
+
+关键实测依据（2.2.5 / 1.19.5，见 docs/dev/backend-commands.md）：
+- v2 CLI：`run --standalone --auto --format json`；`-s` 未知 id 静默新建；无 `--dir`
+- v1 CLI：`run --format json --dir <path>`；未知 `-s` RC=1 报错
+- 导出：v1 `export <id>` / v2 `session export <id> --standalone`，stdout JSON
+- 事件流两代同构：顶层 `sessionID` + `type=="text"` 的 `part.text`；error 事件 RC 不稳
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from functools import cached_property
+
+from agent_cli_lib.backends.base import AcpSpec, RunOutput, RunRequest
+from agent_cli_lib.backends.opencode.specs import V1, V2, OpencodeSpec
+from agent_cli_lib.errors import (
+    AcpProtocolError,
+    BackendLaunchError,
+    BackendRunError,
+    ProcessResult,
+    SessionError,
+)
+
+# opencode --version 输出形如 "1.19.5"（v1）/ "opencode v2.2.5"（v2），
+# 解析口径对齐官方安装脚本：取末 token、去 v 前缀、校验 x.y.z
+_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def _looks_like_session_id(s: str) -> bool:
+    """session id / 文件路径粗判（镜像 core/session.py 启发式，避免 backends→core 反向依赖）。"""
+    return not (s.endswith((".json", ".jsonl", ".md", ".html")) or "/" in s or "\\" in s)
+
+
+def _major_version(binary: str, backend: str = "opencode") -> int:
+    """解析 opencode 主版本；失败/超时/不可读 → BackendLaunchError（不静默猜测）。"""
+    try:
+        proc = subprocess.run(
+            [binary, "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise BackendLaunchError(backend, f"版本探测失败（{binary} --version）: {e}") from e
+    tokens = (proc.stdout or "").split()
+    version = tokens[-1].lstrip("vV") if tokens else ""
+    if proc.returncode != 0 or not _VERSION_RE.match(version):
+        raise BackendLaunchError(
+            backend, f"版本探测不可读（rc={proc.returncode}）: {(proc.stdout or '')[:100]}"
+        )
+    return int(version.split(".")[0])
+
+
+def _resolve_opencode(name: str) -> str:
+    """定位 PATH 上的 opencode（分派层用；版本由调用方继续判定）。"""
+    path = shutil.which("opencode")
+    if path is None:
+        raise BackendLaunchError(
+            name,
+            "未找到可执行文件 opencode，请先安装（v1: npm i -g opencode-ai；"
+            "v2: npm i -g @opencode/cli）",
+        )
+    return path
+
+
+class OpencodeCliImpl:
+    """CLI 兜底实现：transport="cli" 的执行体与 export 的唯一路径（按 spec 参数化 v1/v2）。"""
+
+    def __init__(self, name: str, spec: OpencodeSpec, binary: str) -> None:
+        self.name = name
+        self.spec = spec
+        self.binary = binary
+
+    def build_argv(self, req: RunRequest) -> list[str]:
+        if self.spec.major == 2 and req.session and not _looks_like_session_id(req.session):
+            # v2 的 -s 未知 id 会静默新建：路径形态传进去必然"失忆"，显式拒绝
+            raise SessionError(
+                f"{self.name} 恢复会话仅支持 session id（文件路径恢复见二期 session import）"
+            )
+        argv: list[str] = ["run", *self.spec.cli_run_flags]
+        if self.spec.cli_has_dir_flag and req.workdir:
+            argv += ["--dir", req.workdir]
+        if req.model:
+            argv += ["-m", req.model]
+        if req.session:
+            if self.spec.major == 2 and not req.prompt.strip():
+                # v2 无消息恢复输出 error 事件且 RC 不稳（实测），提前拒绝；
+                # v1 实测允许空消息恢复（argv 省略 prompt），保持既有行为
+                raise SessionError(f"{self.name} 恢复会话必须带 prompt（不支持空消息恢复）")
+            argv += ["-s", req.session]
+        if req.prompt:
+            # "--" 防 - 开头 prompt 被当 flag（两代 cobra/同类 CLI 通用行为，实测可用）
+            argv += ["--", req.prompt]
+        return argv
+
+    def parse_output(self, stdout: str, stderr: str) -> RunOutput:
+        session_id = ""
+        text_parts: list[str] = []
+        errors: list[str] = []
+        for line in stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                evt = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(evt, dict):
+                continue
+            sid = evt.get("sessionID")
+            if sid and not session_id:
+                session_id = str(sid)
+            if evt.get("type") == "error":
+                err = evt.get("error")
+                if isinstance(err, dict) and err.get("message"):
+                    errors.append(str(err["message"]))
+                continue
+            if evt.get("type") == "text":
+                part = evt.get("part")
+                if isinstance(part, dict) and part.get("text"):
+                    text_parts.append(str(part["text"]))
+        if errors:
+            # 严格模式：有 error 即抛（CLI 事件流 RC 不稳，error 事件是更可信的失败信号）
+            raise BackendRunError(self.name, 0, "; ".join(errors))
+        return RunOutput(
+            text="\n".join(text_parts) if text_parts else stdout, session_id=session_id
+        )
+
+    def export_session_file(self, session_id: str, target: str) -> None:
+        """跑原生导出命令，把 stdout JSON 落盘（导出物可被 import 恢复）。
+
+        临时文件 + 原子替换：写盘中途失败不留下半截 JSON，也不破坏已有完好文件。
+        """
+        if not session_id:
+            raise SessionError("导出需要有效的 session_id")
+        argv = [part.format(id=session_id) for part in self.spec.export_argv]
+        proc = subprocess.run(
+            [self.binary, *argv],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        ProcessResult(self.name, proc.returncode, proc.stdout, proc.stderr).raise_for_status()
+        fd, tmp = tempfile.mkstemp(dir=os.path.dirname(target) or ".", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(proc.stdout)
+            os.replace(tmp, target)
+        except OSError as e:
+            _best_effort_unlink(tmp)
+            raise SessionError(f"写入导出文件失败: {target}: {e}") from e
+
+    def session_exists(self, session_id: str) -> bool:
+        """CLI 兜底路径的 resume 前置探测（仅 v2 生效；v1 恒 True，CLI 自己报错）。
+
+        fail-open：只有确定性"不存在"（RC==1 且 stderr 明示 not found）才 False，
+        DB 锁/启动失败/超时等一律放行——探测自身故障不得误伤 resume。
+        """
+        if not self.spec.cli_probe_session:
+            return True
+        if not session_id:
+            return False
+        argv = [part.format(id=session_id) for part in self.spec.export_argv]
+        try:
+            proc = subprocess.run(
+                [self.binary, *argv],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=10,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return True
+        return not (proc.returncode == 1 and "not found" in (proc.stderr or "").lower())
+
+
+class _OpencodeBase:
+    """分派层公共骨架：版本探测 + Spec 选择 + 协议成员委托。"""
+
+    # 子类覆盖：注册名
+    name: str = "opencode"
+
+    # 探测后为 "v1" | "v2"，探测前为 ""（测试/调试断言用）
+    resolved_version: str = ""
+
+    def __init__(self, name: str | None = None) -> None:
+        if name is not None:
+            self.name = name
+
+    @cached_property
+    def _cli(self) -> OpencodeCliImpl:
+        spec, binary = self._resolve()
+        self.resolved_version = f"v{spec.major}"
+        return OpencodeCliImpl(name=self.name, spec=spec, binary=binary)
+
+    def _resolve(self) -> tuple[OpencodeSpec, str]:
+        """探测并返回 (spec, binary)；子类实现各自的解析策略。"""
+        raise NotImplementedError
+
+    @property
+    def binary(self) -> str:
+        return self._cli.binary
+
+    @property
+    def acp(self) -> AcpSpec | None:
+        spec = self._cli.spec
+        return AcpSpec(command=(self._cli.binary, "acp"), cwd_bound=spec.cwd_bound)
+
+    def build_argv(self, req: RunRequest) -> list[str]:
+        return self._cli.build_argv(req)
+
+    def parse_output(self, stdout: str, stderr: str) -> RunOutput:
+        return self._cli.parse_output(stdout, stderr)
+
+    def export_session_file(self, session_id: str, target: str) -> None:
+        self._cli.export_session_file(session_id, target)
+
+    def session_exists(self, session_id: str) -> bool:
+        return self._cli.session_exists(session_id)
+
+
+class OpencodeBackend(_OpencodeBase):
+    """注册名 "opencode"：跟随 PATH 上 opencode 命令的主版本（v1 或 v2）。
+
+    真实升级路径（v1→v2 后 bin 名不变）下，调用方 backend="opencode" 零改动切换。
+    """
+
+    name = "opencode"
+
+    def _resolve(self) -> tuple[OpencodeSpec, str]:
+        binary = _resolve_opencode(self.name)
+        major = _major_version(binary)
+        if major == 1:
+            return V1, binary
+        if major == 2:
+            return V2, binary
+        # 未来 v3+ 不静默落 v1（拿 v1 的命令面打未知 CLI 比明确报错更糟）
+        raise BackendLaunchError(
+            self.name, f"PATH 上的 opencode 主版本为 {major}，本库仅支持 v1/v2"
+        )
+
+
+class Opencode2Backend(_OpencodeBase):
+    """注册名 "opencode2"：显式选 v2（npm/curl 双装机器走 opencode2 别名优先）。
+
+    别名存在也校验版本（陈旧 shim 指向 v1 时降级到 opencode 分支继续校验，两分支
+    都不匹配才报错）；只有 v1 的机器上按下面报错（调用方明确要了 v2）。
+    """
+
+    name = "opencode2"
+
+    def _resolve(self) -> tuple[OpencodeSpec, str]:
+        hint = (
+            "升级安装：npm i -g @opencode/cli 或 brew install anomalyco/tap/opencode-v2"
+            "（会替换 opencode）；双装：npm/curl 渠道自带 opencode2 别名"
+        )
+        alias = shutil.which("opencode2")
+        if alias is not None and _major_version(alias, backend=self.name) == 2:
+            return V2, alias
+        binary = shutil.which("opencode")
+        if binary is not None:
+            major = _major_version(binary)
+            if major == 2:
+                return V2, binary
+            raise BackendLaunchError(
+                self.name, f"PATH 上的 opencode 是 v{major}（opencode v2 需主版本 2）。{hint}"
+            )
+        raise BackendLaunchError(self.name, f"未找到可执行文件 opencode2/opencode（v2）。{hint}")
+
+
+def _best_effort_unlink(path: str) -> None:
+    """清理可能残留的临时文件。"""
+    with contextlib.suppress(OSError):
+        os.unlink(path)
+
+
+__all__ = ["V1", "V2", "AcpProtocolError", "Opencode2Backend", "OpencodeBackend", "OpencodeCliImpl"]

agent_cli_lib/backends/opencode/specs.py

@@ -0,0 +1,39 @@
+"""opencode v1/v2 能力与命令面声明（数据，不是类）。
+
+原则：v1/v2 差异只允许出现在本文件（设计 v8 §4.2），出现在别处即设计违规。
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class OpencodeSpec(NamedTuple):
+    """opencode 某主版本的能力与命令面。"""
+
+    major: int  # 1 | 2（分派探测结果）
+    cwd_bound: bool  # v2 True：ACP resume 协议级绑定会话原目录（v1 实测不受限）
+    export_argv: tuple[str, ...]  # 导出子命令模板，{id} 为占位符
+    cli_run_flags: tuple[str, ...]  # CLI 兜底 run 的固定旗标
+    cli_has_dir_flag: bool  # v1 True（--dir）/ v2 False（workdir 走 subprocess cwd）
+    # v2 CLI 兜底的 -s 未知 id 会静默新建，需 fail-open 存在性探测；v1 自己报错无需探测
+    cli_probe_session: bool
+
+
+V1 = OpencodeSpec(
+    major=1,
+    cwd_bound=False,
+    export_argv=("export", "{id}"),
+    cli_run_flags=("--format", "json"),
+    cli_has_dir_flag=True,
+    cli_probe_session=False,
+)
+
+V2 = OpencodeSpec(
+    major=2,
+    cwd_bound=True,
+    export_argv=("session", "export", "{id}", "--standalone"),
+    cli_run_flags=("--standalone", "--auto", "--format", "json"),
+    cli_has_dir_flag=False,
+    cli_probe_session=True,
+)

agent_cli_lib/backends/pi/__init__.py

@@ -0,0 +1,5 @@
+"""pi 后端适配（占位骨架，待实现）."""
+
+from agent_cli_lib.backends.pi.backend import PiBackend
+
+__all__ = ["PiBackend"]

agent_cli_lib/backends/pi/backend.py

@@ -0,0 +1,116 @@
+"""pi CLI 封装实现。
+
+关键映射（实测 1.5.0）：
+- 一次性运行：pi -p <msg> --mode json
+- 工作目录：通过 subprocess cwd（pi 无 --dir flag）
+- 恢复会话：--session <path|id>
+- session id：--mode json 首事件 {"type":"session","id":...}（字段名是 id）
+- 最终文本：message_end 事件 message.content[].text（role=="assistant"）
+- 导出：pi 无 json 导出命令（--export 只出 HTML），session jsonl 文件即原生存储本体，
+  复制该文件即为导出物，可被 --session <path> 恢复
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import shutil
+from pathlib import Path
+
+from agent_cli_lib.backends.base import AcpSpec, RunOutput, RunRequest
+from agent_cli_lib.errors import SessionError
+
+
+def _session_dir() -> Path:
+    """pi 的 session 存储目录（PI_CODING_AGENT_SESSION_DIR / PI_CODING_AGENT_DIR 可改）。"""
+    env = os.environ.get("PI_CODING_AGENT_SESSION_DIR")
+    if env:
+        return Path(env)
+    root = os.environ.get("PI_CODING_AGENT_DIR")
+    if root:
+        return Path(root) / "sessions"
+    return Path.home() / ".pi" / "agent" / "sessions"
+
+
+class PiBackend:
+    @property
+    def acp(self) -> AcpSpec | None:
+        """pi 无 ACP，整体走 CLI 子进程路径。"""
+        return None
+
+    def session_exists(self, session_id: str) -> bool:
+        """CLI 对未知 id 自己报错，无需探测。"""
+        return True
+
+    name = "pi"
+    binary = "pi"
+
+    def build_argv(self, req: RunRequest) -> list[str]:
+        argv: list[str] = ["-p", "--mode", "json"]
+        if req.model:
+            argv += ["--model", req.model]
+        if req.session:
+            # pi 原生支持 --session <path|id>
+            argv += ["--session", req.session]
+        if req.prompt:
+            argv.append(req.prompt)
+        return argv
+
+    def parse_output(self, stdout: str, stderr: str) -> RunOutput:
+        session_id = ""
+        text_parts: list[str] = []
+        for line in stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                evt = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(evt, dict):
+                continue
+            if evt.get("type") == "session":
+                # id 为 JSON null 时 .get 默认值不生效，须显式真值判断（防 "None" 假 id）
+                sid = evt.get("id")
+                if sid and not session_id:
+                    session_id = str(sid)
+            elif evt.get("type") == "message_end":
+                msg = evt.get("message")
+                if isinstance(msg, dict) and msg.get("role") == "assistant":
+                    content = msg.get("content")
+                    if isinstance(content, list):
+                        for part in content:
+                            if isinstance(part, dict) and part.get("type") == "text":
+                                text = part.get("text")
+                                if text:
+                                    text_parts.append(str(text))
+        return RunOutput(
+            text="\n".join(text_parts) if text_parts else stdout, session_id=session_id
+        )
+
+    def export_session_file(self, session_id: str, target: str) -> None:
+        """复制 pi 的 session jsonl 原文件（存储本体即导出物，--session <path> 可直接恢复）。
+
+        ⚠️ 文件布局 <时间戳>_<session_id>.jsonl 是 pi 的内部存储格式而非文档化接口，
+        pi 升级可能改变布局，此实现需随之更新。
+        """
+        if not session_id:
+            raise SessionError("导出需要有效的 session_id")
+        base = _session_dir()
+        if not base.is_dir():
+            raise SessionError(f"pi session 目录不存在: {base}")
+        # 文件名以 session id 结尾；rglob 覆盖按 cwd slug 分组的子目录（escape 防止
+        # id 中的 glob 元字符污染模式）。注意 rglob 不跟随符号链接目录。
+        hits = sorted(base.rglob(f"*_{glob.escape(session_id)}.jsonl"))
+        if not hits:
+            raise SessionError(f"在 {base} 下未找到 session {session_id} 的 jsonl 文件")
+        if len(hits) > 1:
+            listed = ", ".join(str(h) for h in hits[:5])
+            raise SessionError(f"session {session_id} 命中多个文件，存储态异常: {listed}")
+        try:
+            shutil.copy2(hits[0], target)
+        except OSError as e:
+            # 不留下半截副本（target 不可信）
+            Path(target).unlink(missing_ok=True)
+            raise SessionError(f"复制 session 文件失败: {hits[0]} -> {target}: {e}") from e

agent_cli_lib/core/__init__.py

@@ -0,0 +1 @@
+"""核心层：统一运行入口、prompt 处理、session 管理."""

agent_cli_lib/core/acp/__init__.py

@@ -0,0 +1,13 @@
+"""ACP 传输层（官方 agent-client-protocol 类型 + 自管 stdio 泵，v8 设计）。"""
+
+from agent_cli_lib.core.acp.client import AcpConnection, AcpJsonRpcError
+from agent_cli_lib.core.acp.driver import AcpDriver
+from agent_cli_lib.core.acp.wire import message_text, parse_notification
+
+__all__ = [
+    "AcpConnection",
+    "AcpDriver",
+    "AcpJsonRpcError",
+    "message_text",
+    "parse_notification",
+]