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

agent_cli_lib/__init__.py

@@ -0,0 +1,48 @@
+"""agent-cli-lib: agent CLI 基座 (opencode / pi / hermes) 的统一封装."""
+
+from agent_cli_lib.api import (
+    AgentResult,
+    AgentRunner,
+    SessionInfo,
+    export_session,
+    load_session,
+    resolve_prompt,
+    resume,
+    run,
+)
+from agent_cli_lib.core.runner import get_backend
+from agent_cli_lib.errors import (
+    AcpProtocolError,
+    AgentCliError,
+    BackendLaunchError,
+    BackendNotFoundError,
+    BackendRunError,
+    PromptError,
+    RemovedAPIError,
+    RunCancelledError,
+    SessionError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AcpProtocolError",
+    "AgentCliError",
+    "AgentResult",
+    "AgentRunner",
+    "BackendLaunchError",
+    "BackendNotFoundError",
+    "BackendRunError",
+    "PromptError",
+    "RemovedAPIError",
+    "RunCancelledError",
+    "SessionError",
+    "SessionInfo",
+    "__version__",
+    "export_session",
+    "get_backend",
+    "load_session",
+    "resolve_prompt",
+    "resume",
+    "run",
+]

agent_cli_lib/api/__init__.py

@@ -0,0 +1,25 @@
+"""API 签名层（公开门面）：全部公开方法的签名、docstring 使用提示、废弃/移除注解。
+
+约定：本层只聚合不实现——每个签名一行委托 core/backends，细节按职能归位到成员模块。
+标记用法：from agent_cli_lib.api import deprecated, removed
+"""
+
+from __future__ import annotations
+
+from agent_cli_lib.api.decorators import deprecated, removed
+from agent_cli_lib.api.prompt import resolve_prompt
+from agent_cli_lib.api.runner import AgentResult, AgentRunner, export_session, resume, run
+from agent_cli_lib.api.session import SessionInfo, load_session
+
+__all__ = [
+    "AgentResult",
+    "AgentRunner",
+    "SessionInfo",
+    "deprecated",
+    "export_session",
+    "load_session",
+    "removed",
+    "resolve_prompt",
+    "resume",
+    "run",
+]

agent_cli_lib/api/decorators.py

@@ -0,0 +1,37 @@
+"""API 注解工具：废弃/移除标记（签名层的核心能力）。
+
+- deprecated：typing_extensions 的 PEP 702 实现（Python 3.13 起进标准库 warnings.deprecated）。
+  一个装饰器三合一：静态诊断（ty/pyright/pylance 报 Deprecated、IDE 划删除线）、
+  运行时发 DeprecationWarning、消息本身承载迁移/用法提示。
+- removed：签名保留但调用即抛 RemovedAPIError，hint 指向替代用法（彻底丢弃档）。
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import NoReturn, TypeVar, cast
+
+from typing_extensions import deprecated
+
+from agent_cli_lib.errors import RemovedAPIError
+
+__all__ = ["deprecated", "removed"]
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def removed(hint: str) -> Callable[[F], F]:
+    """标记 API 已彻底移除：签名保留（静态可见），调用即抛 RemovedAPIError。
+
+    hint 写替代用法，例如：@removed("改用 run(prompt, model=...)，见 docs/api.md")
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> NoReturn:
+            raise RemovedAPIError(getattr(func, "__qualname__", str(func)), hint)
+
+        return cast("F", wrapper)
+
+    return decorator

agent_cli_lib/api/prompt.py

@@ -0,0 +1,10 @@
+"""prompt 门面（签名层）：resolve_prompt 的公开出口。
+
+实现在 core.prompt（文件/字符串判别、大小上限等细节收纳在那里），本层只聚合。
+"""
+
+from __future__ import annotations
+
+from agent_cli_lib.core.prompt import resolve_prompt
+
+__all__ = ["resolve_prompt"]

agent_cli_lib/api/runner.py

@@ -0,0 +1,85 @@
+"""运行门面（签名层）：公开签名 + 使用提示，一行委托 core（聚合层约定，不碰实现细节）。
+
+需要跨多次调用 cancel() 或复用会话上下文时，直接用 AgentRunner 实例。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from acp import SessionNotification
+
+from agent_cli_lib.core.runner import AgentResult, AgentRunner
+from agent_cli_lib.core.session import SessionInfo
+
+__all__ = ["AgentResult", "AgentRunner", "export_session", "resume", "run"]
+
+
+def run(
+    prompt: str,
+    *,
+    backend: str = "opencode",
+    model: str | None = None,
+    workdir: str | None = None,
+    export_to: str | None = None,
+    transport: str = "auto",
+    on_event: Callable[[SessionNotification], None] | None = None,
+) -> AgentResult:
+    """一次性执行 agent 任务，无需管理 runner 生命周期。
+
+    export_to：任务完成后把会话导出文件落到该路径（相对路径按调用方进程 cwd 解析，
+    父目录自动创建）。导出失败不抛异常，降级为 AgentResult.export_error；
+    成功时 AgentResult.export_path 为落盘绝对路径。各后端导出物可用性：
+    opencode 可 `opencode import` 恢复；pi 的 jsonl 可 `pi --session <path>` 恢复；
+    hermes 的 jsonl 仅归档（无 import，恢复只能 session id）。
+
+    Examples:
+        >>> from agent_cli_lib.api import run
+        >>> result = run("修复登录 bug", backend="opencode", workdir="/my/project",
+        ...              export_to="/tmp/sess.json")
+        >>> result.session_id, result.output, result.export_path
+    """
+    return AgentRunner(backend=backend, workdir=workdir, transport=transport).run(
+        prompt, model=model, export_to=export_to, on_event=on_event
+    )
+
+
+def resume(
+    session: str,
+    *,
+    backend: str = "opencode",
+    model: str | None = None,
+    prompt: str = "",
+    workdir: str | None = None,
+    transport: str = "auto",
+    on_event: Callable[[SessionNotification], None] | None = None,
+) -> AgentResult:
+    """按 session id 或 session 文件路径恢复会话。
+
+    prompt 必填性：ACP 路径（opencode 默认路由）所有 backend 必须带 prompt；
+    hermes CLI 路径必须带 prompt；pi CLI 路径可省略。
+
+    Examples:
+        >>> from agent_cli_lib.api import resume
+        >>> result = resume("sess-abc", prompt="继续优化", backend="pi")
+    """
+    return AgentRunner(backend=backend, workdir=workdir, transport=transport).resume(
+        session, model=model, prompt=prompt, on_event=on_event
+    )
+
+
+def export_session(
+    session_id: str,
+    target: str,
+    *,
+    backend: str = "opencode",
+    workdir: str | None = None,
+) -> SessionInfo:
+    """调用后端原生导出命令，把会话数据落到 target 文件。
+
+    Examples:
+        >>> from agent_cli_lib.api import export_session
+        >>> info = export_session("sess-abc", "out.json", backend="opencode")
+        >>> info.file_path
+    """
+    return AgentRunner(backend=backend, workdir=workdir).export_session(session_id, target)

agent_cli_lib/api/session.py

@@ -0,0 +1,10 @@
+"""会话门面（签名层）：SessionInfo 与 load_session 的公开出口。
+
+实现在 core.session（路径判别/校验细节收纳在那里），本层只聚合。
+"""
+
+from __future__ import annotations
+
+from agent_cli_lib.core.session import SessionInfo, load_session
+
+__all__ = ["SessionInfo", "load_session"]

agent_cli_lib/backends/__init__.py

@@ -0,0 +1 @@
+"""agent CLI 后端适配层 (opencode / pi / hermes)."""

agent_cli_lib/backends/base.py

@@ -0,0 +1,84 @@
+"""后端统一协议。
+
+每个 agent CLI 基座实现为一个小型充血模型：自己负责
+- 构造命令行 argv（把统一的 prompt/session/workdir 翻译成自己的 flag）
+- 解析进程输出（提取最终文本 + session id，含各家 stdout/stderr 的格式差异）
+- 落盘会话导出文件（把会话以原生导出格式写到 target）
+
+AgentRunner 只调用 build_argv / parse_output / export_session_file，不关心任何 backend 细节。
+传输层扩展（v8 设计）：`acp` 属性声明 ACP 可用性（None = 整体走 CLI 子进程路径）；
+`session_exists` 是 CLI 路径 resume 的廉价存在性探测（ACP 路径不需要，协议错误自带语义）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NamedTuple, Protocol
+
+
+@dataclass
+class RunRequest:
+    """一次运行的统一输入（backend 把它翻译成自己的 argv / ACP 请求）。"""
+
+    prompt: str
+    workdir: str | None = None
+    model: str | None = None
+    session: str | None = None
+
+
+@dataclass
+class RunOutput:
+    """一次运行的统一输出（从进程 stdout/stderr 或 ACP 响应解析出来）。"""
+
+    text: str
+    session_id: str = ""
+
+
+class AcpSpec(NamedTuple):
+    """backend 的 ACP 能力声明（None 表示无 ACP / 整体走 CLI）。
+
+    - command：启动 ACP agent 的完整命令（含已解析的 binary 路径）
+    - cwd_bound：resume 是否协议级绑定会话原目录（opencode v2 实测 True）。
+      说明：跨目录 cwd 错误的"可读翻译"由 wire 层按协议消息内容无条件实现
+      （不依赖本字段）；本字段是 spec 数据，供测试断言与未来前置校验使用
+    """
+
+    command: tuple[str, ...]
+    cwd_bound: bool = False
+
+
+class Backend(Protocol):
+    """agent CLI 基座协议（name/binary 为只读成员：类属性或 property 均可满足）。"""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def binary(self) -> str: ...
+
+    def build_argv(self, req: RunRequest) -> list[str]:
+        """把统一请求翻译成该 CLI 的命令行参数列表（不含二进制本身）。"""
+        ...
+
+    def parse_output(self, stdout: str, stderr: str) -> RunOutput:
+        """从进程 stdout/stderr 提取最终文本与 session id（各家格式差异收纳于此）。"""
+        ...
+
+    def export_session_file(self, session_id: str, target: str) -> None:
+        """把会话以该 CLI 的原生导出格式写到 target 文件（target 为已存在的绝对路径，
+        父目录已由调用方创建）；失败抛 AgentCliError。
+        """
+        ...
+
+    def session_exists(self, session_id: str) -> bool:
+        """廉价探测会话是否存在（CLI 路径 resume 前置校验用）。
+
+        默认恒 True（多数 CLI 对未知 id 自己报错，探测是浪费）；存在
+        "未知 id 静默新建"语义的 backend（opencode v2 CLI 兜底）真实探测。
+        """
+        ...
+
+    @property
+    def acp(self) -> AcpSpec | None:
+        """ACP 能力声明；None = 该 backend 不走 ACP 传输（pi / hermes 0.19.0）。"""
+        ...

agent_cli_lib/backends/hermes/__init__.py

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

agent_cli_lib/backends/hermes/backend.py

@@ -0,0 +1,85 @@
+"""hermes CLI 封装实现。
+
+关键映射（实测 0.19.0）：
+- 一次性运行：hermes chat -q <msg> -Q（-Q 非交互退出）
+- 工作目录：通过 subprocess cwd
+- 恢复会话：--resume <session_id>
+- session id：只在 stderr 尾部以 "session_id: <id>" 行出现，stdout 即正文
+- 导出：hermes sessions export --format jsonl（CLI 自己写 target）；导出物是归档，
+  hermes 无 import 命令，恢复只能 --resume <session_id>
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from agent_cli_lib.backends.base import AcpSpec, RunOutput, RunRequest
+from agent_cli_lib.errors import ProcessResult, SessionError, which_or_raise
+
+# hermes 把 session id 打在 stderr 尾部，形如 "session_id: 20261104_061903_4b2d3b"
+_SESSION_LINE_RE = re.compile(r"^session(?:_id)?\s*[:=]\s*([A-Za-z0-9_\-]+)", re.IGNORECASE)
+
+
+class HermesBackend:
+    @property
+    def acp(self) -> AcpSpec | None:
+        """hermes 0.19.0 ACP resume broken，整体走 CLI 子进程路径。"""
+        return None
+
+    def session_exists(self, session_id: str) -> bool:
+        """CLI 对未知 id 自己报错，无需探测。"""
+        return True
+
+    name = "hermes"
+    binary = "hermes"
+
+    def build_argv(self, req: RunRequest) -> list[str]:
+        # hermes 非 interactive 只有单查询模式；无 prompt 会退回交互式 REPL 挂起，直接拒绝
+        if not req.prompt.strip():
+            raise SessionError("hermes 恢复会话需要提供续写 prompt（其 CLI 无非交互续写模式）")
+        argv: list[str] = ["chat", f"--query={req.prompt}", "-Q"]
+        if req.model:
+            argv += ["-m", req.model]
+        if req.session:
+            argv += ["--resume", req.session]
+        return argv
+
+    def parse_output(self, stdout: str, stderr: str) -> RunOutput:
+        session_id = ""
+        for line in stderr.splitlines():
+            m = _SESSION_LINE_RE.match(line.strip())
+            if m:
+                session_id = m.group(1)
+                break
+        # stdout 即正文（reasoning 框等由 CLI 自行渲染，不在此过滤）
+        return RunOutput(text=stdout.strip(), session_id=session_id)
+
+    def export_session_file(self, session_id: str, target: str) -> None:
+        """跑原生 sessions export（jsonl），由 hermes 自己写 target。"""
+        if not session_id:
+            raise SessionError("导出需要有效的 session_id")
+        binary = which_or_raise(self.binary, self.name)
+        argv = [
+            binary,
+            "sessions",
+            "export",
+            "--session-id",
+            session_id,
+            "--format",
+            "jsonl",
+            target,
+        ]
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        if proc.returncode != 0:
+            # CLI 自己写 target，非零退出时内容不可信，不留下半截文件
+            Path(target).unlink(missing_ok=True)
+        ProcessResult(self.name, proc.returncode, proc.stdout, proc.stderr).raise_for_status()

agent_cli_lib/backends/opencode/__init__.py

@@ -0,0 +1,10 @@
+"""opencode 后端聚合包（v8 设计）：版本分派 + CLI 兜底。"""
+
+from agent_cli_lib.backends.opencode.backend import (
+    Opencode2Backend,
+    OpencodeBackend,
+    OpencodeCliImpl,
+)
+from agent_cli_lib.backends.opencode.specs import V1, V2
+
+__all__ = ["V1", "V2", "Opencode2Backend", "OpencodeBackend", "OpencodeCliImpl"]