langchain-agentx-cli 0.1.0__py3-none-any.whl

langchain_agentx_cli/__init__.py

@@ -0,0 +1,3 @@
+"""langchain_agentx_cli：依托 langchain_agentx_python SDK 的终端 CLI/TUI（CC Ink 迁移）。"""
+
+__version__ = "0.1.0"

langchain_agentx_cli/__main__.py

@@ -0,0 +1,8 @@
+"""
+__main__.py — python -m langchain_agentx_cli 入口。
+"""
+
+from langchain_agentx_cli.cli import main
+
+if __name__ == "__main__":
+    main()

langchain_agentx_cli/app.py

@@ -0,0 +1,149 @@
+"""
+app.py — Textual ReplApp 容器。
+
+职责：
+    应用生命周期、SessionBridge、命令注册表、历史、双次 Ctrl+C 退出。
+
+链路位置：
+    CliEntry._run_tui() 实例化并 run()；session 关闭由 CliEntry finally 负责。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual import on
+from textual.app import App
+from textual.binding import Binding
+
+from langchain_agentx_cli.bridge.session_bridge import SessionBridge
+from langchain_agentx_cli.commands.builtin import register_builtin_commands
+from langchain_agentx_cli.commands.providers import register_sdk_commands
+from langchain_agentx_cli.commands.registry import CommandRegistry
+from langchain_agentx_cli.config import (
+    AppPreferencesStore,
+    AppUserPreferences,
+    ReplLaunchConfig,
+)
+from langchain_agentx_cli.theme import ThemeManager
+from langchain_agentx_cli.history.store import HistoryStore
+from langchain_agentx_cli.screens import ReplScreen
+from langchain_agentx_cli.tui.message_selection import try_copy_message_selection
+from langchain_agentx_cli.tui.safe_screen import ReplScreenMessenger
+from langchain_agentx_cli.widgets.permission_inline import InlinePermissionWidget
+from langchain_agentx_cli.widgets.messages import UserMessage
+
+if TYPE_CHECKING:
+    from langchain_agentx import AgentSession
+
+_CANCEL_HINT = "已取消当前生成。再次按 Ctrl+C 退出。"
+_EXIT_HINT = "再次按 Ctrl+C 退出。"
+
+
+class ReplApp(App[None]):
+    """AgentX 终端 REPL 应用（Textual）。"""
+
+    TITLE = "langchain-agentx-cli"
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("ctrl+c", "cancel_stream", "Cancel / Quit"),
+        Binding("ctrl+l", "clear_screen", "Clear", show=False, priority=True),
+        Binding(
+            "ctrl+shift+l",
+            "clear_screen",
+            "Clear (Win 备用)",
+            show=False,
+            priority=True,
+        ),
+    ]
+
+    def __init__(
+        self,
+        launch_config: ReplLaunchConfig,
+        session: AgentSession | None = None,
+    ) -> None:
+        super().__init__()
+        self._launch_config = launch_config
+        self._session = session
+        self._bridge: SessionBridge | None = None
+        self._exit_armed = False
+        self.command_registry = CommandRegistry()
+        register_builtin_commands(self.command_registry)
+        self.history_store = HistoryStore()
+        self.theme_manager: ThemeManager | None = None
+        self._screen_messenger = ReplScreenMessenger(self)
+        # Phase 3: 加载用户偏好（供 MessageListWidget 和工具 Widget 使用）
+        self.preferences: AppUserPreferences = AppPreferencesStore().load()
+
+    @property
+    def screen_messenger(self) -> ReplScreenMessenger:
+        return self._screen_messenger
+
+    @property
+    def workspace_root(self):
+        return self._launch_config.workspace_root
+
+    @property
+    def launch_config(self) -> ReplLaunchConfig:
+        return self._launch_config
+
+    @property
+    def bridge(self) -> SessionBridge | None:
+        return self._bridge
+
+    def on_mount(self) -> None:
+        prefs = AppPreferencesStore().load()
+        initial_setting = self._launch_config.theme or prefs.theme
+        self.theme_manager = ThemeManager(self)
+        self.theme_manager.setup(initial=initial_setting)
+        if self._session is not None:
+            self._bridge = SessionBridge(self, self._session)
+            register_sdk_commands(self.command_registry, self._session)
+            self._bridge.permission_consumer.start()
+        self.push_screen(ReplScreen())
+
+    def on_unmount(self) -> None:
+        if self.theme_manager is not None:
+            self.theme_manager.stop_auto_watch()
+        if self._bridge is not None:
+            self._bridge.permission_consumer.stop()
+            self._bridge.cancel_stream()
+
+    def clear_messages(self) -> None:
+        screen = self.screen
+        if isinstance(screen, ReplScreen):
+            screen.clear_messages()
+
+    def action_clear_screen(self) -> None:
+        self.clear_messages()
+        self.notify("消息已清空", severity="information", timeout=2)
+
+    @on(UserMessage)
+    def _on_user_message_reset_exit_arm(self, _event: UserMessage) -> None:
+        self._exit_armed = False
+
+    def action_cancel_stream(self) -> None:
+        if try_copy_message_selection(self) is not None:
+            return
+        # Dismiss inline permission widget if active
+        try:
+            widget = self.screen.query_one(InlinePermissionWidget)
+            widget.dismiss_externally()
+            return
+        except Exception:
+            pass
+        if self._bridge is not None and self._bridge.is_streaming():
+            self._bridge.cancel_stream()
+            self._exit_armed = True
+            self.notify(_CANCEL_HINT, severity="warning", timeout=4)
+            return
+        if self._exit_armed:
+            self.action_quit()
+            return
+        self._exit_armed = True
+        self.notify(_EXIT_HINT, severity="information", timeout=4)
+
+    def action_quit(self) -> None:
+        if self._bridge is not None:
+            self._bridge.cancel_stream()
+        self.exit(0)

langchain_agentx_cli/bootstrap.py

@@ -0,0 +1,49 @@
+"""
+bootstrap.py — CLI 启动前环境检查。
+
+职责：
+    校验 SDK 可导入、workspace_root 为有效目录。
+
+链路位置：
+    CliEntry.run() 在创建 ReplApp 之前调用。
+
+当前裁剪范围：
+    不校验 API Key；AgentSession 创建失败由 session_factory 抛出 CliEnvironmentError。
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+class CliEnvironmentError(Exception):
+    """启动前环境不满足，应打印 stderr 并以非零码退出。"""
+
+
+class EnvironmentChecker:
+    """CLI 启动环境检查（OOP 协作者）。"""
+
+    def check_sdk_importable(self) -> None:
+        try:
+            import langchain_agentx  # noqa: F401
+        except ImportError as exc:
+            raise CliEnvironmentError(
+                "无法导入 langchain_agentx。请安装 SDK：\n"
+                '  pip install "langchain-agentx-python>=0.2.3"\n'
+                "或 editable：pip install -e <langchain_agentx_python 路径>"
+            ) from exc
+
+    def check_workspace_root(self, workspace_root: Path) -> None:
+        if not workspace_root.exists():
+            raise CliEnvironmentError(
+                f"workspace_root 不存在: {workspace_root}"
+            )
+        if not workspace_root.is_dir():
+            raise CliEnvironmentError(
+                f"workspace_root 不是目录: {workspace_root}"
+            )
+
+    @staticmethod
+    def emit_error(message: str) -> None:
+        print(message, file=sys.stderr)

langchain_agentx_cli/bridge/__init__.py

@@ -0,0 +1,5 @@
+"""TUI 与 SDK 桥接层。"""
+
+from .session_bridge import MVP_ADAPTER_CONFIG, SessionBridge
+
+__all__ = ["MVP_ADAPTER_CONFIG", "SessionBridge"]

langchain_agentx_cli/bridge/session_bridge.py

@@ -0,0 +1,261 @@
+"""
+bridge/session_bridge.py — SessionBridge（SDK 事件 → Textual Message）。
+
+职责：
+    消费 LangchainAgentEvent，经 Worker 异步调用 SDK，向 App 投递 UI Message；
+    创建权限 Queue/Resolver 并注入 AgentSession。
+
+链路位置：
+    ReplApp → SessionBridge → AgentSession.stream_loop_events
+    → LangGraphToLangchainAgentEventAdapter.adapt()；
+    权限：AgentSessionPermissionResolver ← PermissionQueueConsumer。
+
+当前裁剪范围：
+    不解析 LangGraph 原始事件名；Resolver 超时 300s（见 tui/permissions/config.py）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from langchain_agentx.tool_runtime.resolvers import (
+    AgentSessionPermissionResolver,
+    PermissionRequest,
+)
+from langchain_agentx_cli.tui.permissions import (
+    PermissionQueueConsumer,
+    SessionPermissionCache,
+    inject_permission_resolver,
+)
+from langchain_agentx_cli.tui.permissions.config import DEFAULT_PERMISSION_TIMEOUT_SECONDS
+from langchain_agentx_cli.tui.permissions.dialog import DialogPermissionDecisionPort
+
+from langchain_agentx import (
+    LangGraphToLangchainAgentEventAdapter,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+)
+
+from langchain_agentx_cli.widgets.messages import (
+    AssistantMessageChunk,
+    ErrorMessageOccurred,
+    ThinkingContentDelta,
+    ThinkingEnded,
+    ThinkingStarted,
+    ToolUseCompleted,
+    ToolUseStarted,
+    TurnInProgress,
+    UserMessage,
+)
+
+if TYPE_CHECKING:
+    from langchain_agentx import AgentSession
+
+    from langchain_agentx_cli.app import ReplApp
+
+MVP_ADAPTER_CONFIG: dict[str, bool] = {
+    "enable_reasoning_events": True,
+    "enable_step_events": False,
+    "enable_hook_events": False,
+    "enable_compact_events": True,
+    "enable_subagent_events": False,
+    "synthesize_tool_call": True,
+}
+
+_LLM_FAILED_PREFIX = "[LLM request failed]"
+
+
+class SessionBridge:
+    """TUI 与 SDK 之间的桥接层（消费 LangchainAgentEvent）。"""
+
+    def __init__(self, app: ReplApp, session: AgentSession) -> None:
+        self._app = app
+        self._screen_messenger = app.screen_messenger
+        self._session = session
+        self._adapter = LangGraphToLangchainAgentEventAdapter(config=dict(MVP_ADAPTER_CONFIG))
+        self._current_worker: Any = None
+        self._streamed_text = False
+        self._permission_queue: asyncio.Queue[PermissionRequest] = asyncio.Queue()
+        self._permission_cache = SessionPermissionCache()
+        self._permission_resolver = AgentSessionPermissionResolver(
+            request_queue=self._permission_queue,
+            timeout=DEFAULT_PERMISSION_TIMEOUT_SECONDS,
+        )
+        inject_permission_resolver(session, self._permission_resolver)
+        self._permission_consumer = PermissionQueueConsumer(
+            queue=self._permission_queue,
+            cache=self._permission_cache,
+            app=app,
+            decision_port=DialogPermissionDecisionPort(app),
+        )
+
+    def _post_ui(self, message: object) -> None:
+        self._screen_messenger.post(message)
+
+    def submit_input(self, text: str) -> None:
+        self._post_ui(UserMessage(content=text))
+        self._post_ui(TurnInProgress(in_progress=True))
+        self._current_worker = self._app.run_worker(
+            self._stream_turn(text),
+            name="sdk-stream",
+            exit_on_error=False,
+        )
+
+    async def _stream_turn(self, user_input: str) -> None:
+        self._adapter._reset_state()
+        self._streamed_text = False
+        raw_events = self._session.stream_loop_events(user_input)
+        try:
+            async for event in self._adapter.adapt(raw_events):
+                self._dispatch_event(event)
+        except Exception as exc:
+            self._post_ui(ErrorMessageOccurred(error=str(exc)))
+        finally:
+            self._post_ui(TurnInProgress(in_progress=False))
+            self._current_worker = None
+
+    def _dispatch_event(self, event: LangchainAgentEvent) -> None:
+        data = event.data or {}
+        match event.event_type:
+            case LangchainAgentEventType.TEXT_START:
+                self._post_ui(
+                    AssistantMessageChunk(delta="", is_complete=False)
+                )
+            case LangchainAgentEventType.TEXT_DELTA:
+                delta = str(data.get("text", ""))
+                if delta:
+                    self._streamed_text = True
+                self._post_ui(
+                    AssistantMessageChunk(
+                        delta=delta,
+                        is_complete=False,
+                    )
+                )
+            case LangchainAgentEventType.TEXT_END:
+                self._post_ui(
+                    AssistantMessageChunk(delta="", is_complete=True)
+                )
+            case LangchainAgentEventType.TOOL_INPUT:
+                tool_input = data.get("input")
+                if not isinstance(tool_input, dict):
+                    tool_input = data.get("params") if isinstance(data.get("params"), dict) else {}
+                self._post_ui(
+                    ToolUseStarted(
+                        tool_name=str(data.get("tool_name", "")),
+                        tool_input=tool_input,
+                    )
+                )
+            case LangchainAgentEventType.TOOL_CALL:
+                pass
+            case LangchainAgentEventType.TOOL_RESULT:
+                self._post_ui(
+                    ToolUseCompleted(
+                        tool_name=str(data.get("tool_name", "")),
+                        output=str(data.get("output", "")),
+                    )
+                )
+            case LangchainAgentEventType.TOOL_ERROR:
+                error_text = str(data.get("error", ""))
+                self._post_ui(
+                    ToolUseCompleted(
+                        tool_name=str(data.get("tool_name", "")),
+                        output=f"Error: {error_text}",
+                        error=error_text or None,
+                    )
+                )
+            case LangchainAgentEventType.ERROR:
+                self._post_ui(
+                    ErrorMessageOccurred(
+                        error=str(data.get("error", "Unknown error")),
+                    )
+                )
+            case LangchainAgentEventType.REASONING_START:
+                self._post_ui(ThinkingStarted())
+            case LangchainAgentEventType.REASONING_DELTA:
+                delta = str(data.get("text", ""))
+                if delta:
+                    self._post_ui(ThinkingContentDelta(delta=delta))
+            case LangchainAgentEventType.REASONING_END:
+                self._post_ui(ThinkingEnded())
+            case LangchainAgentEventType.START:
+                self._post_ui(TurnInProgress(in_progress=True))
+            case LangchainAgentEventType.FINISH:
+                self._emit_finish_answer(str(data.get("answer", "")))
+                self._post_ui(TurnInProgress(in_progress=False))
+            case _:
+                pass
+
+    def _emit_finish_answer(self, answer: str) -> None:
+        """非流式路径（如 API 失败合成 AIMessage）在 FINISH.answer 带回文案。"""
+        text = answer.strip()
+        if not text:
+            return
+        if text.startswith(_LLM_FAILED_PREFIX):
+            self._post_ui(ErrorMessageOccurred(error=text))
+            return
+        if not self._streamed_text:
+            self._post_ui(
+                AssistantMessageChunk(delta=text, is_complete=True)
+            )
+
+    def is_streaming(self) -> bool:
+        return self._current_worker is not None
+
+    def is_session_ready(self) -> bool:
+        return self._session is not None and getattr(self._session, "_graph", None) is not None
+
+    @property
+    def session(self) -> AgentSession:
+        return self._session
+
+    @property
+    def permission_queue(self) -> asyncio.Queue[PermissionRequest]:
+        return self._permission_queue
+
+    @property
+    def permission_cache(self) -> SessionPermissionCache:
+        return self._permission_cache
+
+    @property
+    def permission_resolver(self) -> AgentSessionPermissionResolver:
+        return self._permission_resolver
+
+    @property
+    def permission_consumer(self) -> PermissionQueueConsumer:
+        return self._permission_consumer
+
+    async def dispatch_command(
+        self,
+        raw_input: str,
+        *,
+        output: Callable[[str], None] | None = None,
+    ) -> str | None:
+        if not self.is_session_ready():
+            message = "错误：会话未建立，无法执行该命令"
+            if output is not None:
+                output(message)
+            return message
+        result = await self._session.dispatch_command(raw_input)
+        if result is None:
+            return None
+        if result.error:
+            message = str(result.error)
+            if output is not None:
+                output(message)
+            return message
+        if result.output:
+            message = str(result.output)
+            if output is not None:
+                output(message)
+            return message
+        return None
+
+    def cancel_stream(self) -> None:
+        if self._current_worker is not None:
+            cancel = getattr(self._current_worker, "cancel", None)
+            if callable(cancel):
+                cancel()
+            self._current_worker = None
+            self._post_ui(TurnInProgress(in_progress=False))

langchain_agentx_cli/cli.py

@@ -0,0 +1,223 @@
+"""
+cli.py — CLI 入口（click）。
+
+职责：
+    解析命令行、环境检查、解析 workspace、创建 AgentSession、启动 ReplApp。
+
+链路位置：
+    python -m langchain_agentx_cli / 未来 console_scripts。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from langchain_agentx_cli.app import ReplApp
+from langchain_agentx_cli.bootstrap import CliEnvironmentError, EnvironmentChecker
+from langchain_agentx_cli.config import AppPreferencesStore, ReplLaunchConfig
+from langchain_agentx_cli.llm_config import (
+    ANTHROPIC_MODEL_ENV,
+    format_resolved_config,
+    resolve_llm_config,
+    user_config_path,
+)
+from langchain_agentx_cli.session_factory import close_agent_session, open_agent_session
+from langchain_agentx_cli.session_options import ENABLE_GIT_SNAPSHOT_ENV
+
+
+class CliEntry:
+    """CLI 主编排：参数 → 校验 → Session → TUI。"""
+
+    def __init__(self, checker: EnvironmentChecker | None = None) -> None:
+        self._checker = checker or EnvironmentChecker()
+
+    def run(
+        self,
+        *,
+        workspace_root: Path | None,
+        mode: str | None,
+        agent_home: str | None,
+        model: str | None,
+        provider: str | None,
+        show_config: bool,
+        enable_git_snapshot: bool | None,
+        skip_permissions: bool = False,
+    ) -> int:
+        # Mode 到 agent_home 的映射（优先级高于 --agent-home）
+        if mode:
+            agent_home = self._resolve_mode_to_agent_home(mode)
+        try:
+            launch_config = self._build_launch_config(
+                workspace_root=workspace_root,
+                agent_home=agent_home,
+                model=model,
+                provider=provider,
+                skip_permissions=skip_permissions,
+            )
+        except CliEnvironmentError as exc:
+            EnvironmentChecker.emit_error(str(exc))
+            return 2
+
+        if show_config:
+            cfg = resolve_llm_config(
+                cli_provider=provider,
+                cli_model=model,
+            )
+            print(format_resolved_config(cfg))
+            return 0
+
+        try:
+            session = asyncio.run(
+                open_agent_session(
+                    launch_config,
+                    cli_provider=provider,
+                    cli_model=model,
+                    enable_git_snapshot=enable_git_snapshot,
+                )
+            )
+        except CliEnvironmentError as exc:
+            EnvironmentChecker.emit_error(str(exc))
+            return 2
+
+        try:
+            return self._run_tui(launch_config, session)
+        finally:
+            asyncio.run(close_agent_session(session))
+
+    def _build_launch_config(
+        self,
+        *,
+        workspace_root: Path | None,
+        agent_home: str | None,
+        model: str | None,
+        provider: str | None,
+        skip_permissions: bool = False,
+    ) -> ReplLaunchConfig:
+        self._checker.check_sdk_importable()
+
+        from langchain_agentx.workspace import (
+            resolve_agent_workspace_config,
+            resolve_workspace_root_path,
+        )
+
+        resolved_root = resolve_workspace_root_path(workspace_root)
+        self._checker.check_workspace_root(resolved_root)
+
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=resolved_root,
+            agent_home=agent_home,
+        )
+
+        llm_cfg = resolve_llm_config(cli_provider=provider, cli_model=model)
+        ui_prefs = AppPreferencesStore().load()
+
+        return ReplLaunchConfig(
+            workspace_root=Path(workspace_cfg.workspace_root),
+            agent_home=workspace_cfg.agent_home,
+            workspace_cfg=workspace_cfg,
+            model=llm_cfg.model,
+            provider=llm_cfg.provider,
+            theme=ui_prefs.theme,
+            skip_permissions=skip_permissions,
+        )
+
+    def _resolve_mode_to_agent_home(self, mode: str) -> str:
+        """将 mode 映射到 agent_home 目录名。"""
+        mode_map = {
+            "agentx": ".langchain_agentx",
+            "claude": ".claude",
+            "cursor": ".cursor",
+        }
+        return mode_map.get(mode.lower(), ".langchain_agentx")
+
+    def _run_tui(self, launch_config: ReplLaunchConfig, session) -> int:  # noqa: ANN001
+        app = ReplApp(launch_config=launch_config, session=session)
+        app.run()
+        return 0
+
+
+_CONFIG_PATH = user_config_path()
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--workspace-root",
+    type=click.Path(exists=False, file_okay=False, dir_okay=True, path_type=Path),
+    default=None,
+    help="工作区根目录（默认：当前目录或 LANGCHAIN_AGENTX_WORKSPACE_ROOT）",
+)
+@click.option(
+    "--mode",
+    type=click.Choice(["agentx", "claude", "cursor"], case_sensitive=False),
+    default=None,
+    help="配置目录模式：agentx(.langchain_agentx) / claude(.claude) / cursor(.cursor)",
+)
+@click.option(
+    "--agent-home",
+    default=None,
+    help="Agent 配置目录名（相对 workspace，优先级低于 --mode）",
+)
+@click.option(
+    "--model",
+    default=None,
+    help=(
+        f"模型名（claude：未指定时读 {ANTHROPIC_MODEL_ENV}、配置文件或默认；"
+        f"openai：配置文件或默认；见 {_CONFIG_PATH}）"
+    ),
+)
+@click.option(
+    "--provider",
+    type=click.Choice(["claude", "openai"], case_sensitive=False),
+    default=None,
+    help=(
+        "LLM provider：claude（Anthropic/CC 变量）或 openai（OpenAI 兼容）；"
+        f"未指定时读配置文件或按模型名启发式；见 {_CONFIG_PATH}"
+    ),
+)
+@click.option(
+    "--show-config",
+    is_flag=True,
+    default=False,
+    help="打印合并后的 LLM 配置（api_key 脱敏）后退出，不启动 TUI",
+)
+@click.option(
+    "--enable-git-snapshot/--no-git-snapshot",
+    default=None,
+    help=(
+        "是否在 system prompt 注入 git 启动快照（默认关）；"
+        f"未指定时读环境变量 {ENABLE_GIT_SNAPSHOT_ENV}=1"
+    ),
+)
+@click.option(
+    "-p",
+    "--skip-permissions",
+    is_flag=True,
+    default=False,
+    help="跳过工具权限确认（对齐 CC --dangerously-skip-permissions）",
+)
+def main(
+    workspace_root: Path | None,
+    mode: str | None,
+    agent_home: str | None,
+    model: str | None,
+    provider: str | None,
+    show_config: bool,
+    enable_git_snapshot: bool | None,
+    skip_permissions: bool,
+) -> None:
+    """langchain-agentx 终端 REPL（MVP）。"""
+    code = CliEntry().run(
+        workspace_root=workspace_root,
+        mode=mode,
+        agent_home=agent_home,
+        model=model,
+        provider=provider,
+        show_config=show_config,
+        enable_git_snapshot=enable_git_snapshot,
+        skip_permissions=skip_permissions,
+    )
+    raise SystemExit(code)