citrus-code 0.1.0__py3-none-any.whl

citrus_code/cli/main.py

@@ -0,0 +1,258 @@
+"""Parse CLI options and assemble providers, tools, storage, and terminal UI."""
+
+import argparse
+import asyncio
+import os
+import sys
+from contextlib import AsyncExitStack
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+from ..ai.provider import Provider
+from ..ai.providers.deepseek import DEEPSEEK_VISION_MODEL_IDS, DeepSeekProvider
+from ..ai.providers.fake import FakeProvider
+from ..ai.types import ModelOptions, ModelSpec
+from ..coding.coding_session import CodingSession
+from ..coding.compaction.tokens import CONTEXT_WINDOW
+from ..coding.context_hooks import SystemPromptHooks
+from ..coding.project_context import load_project_context
+from ..coding.session import SessionManager
+from ..coding.session.recovery import recover_pending_tools
+from ..coding.tools import READ_ONLY_TOOLS, create_tools
+from ..config import load_connection_config
+from .prompts import build_system_prompt
+from .render import Console
+from .session_files import (
+    LaunchSettings,
+    ShellName,
+    load_settings,
+    save_settings,
+    session_lease,
+    session_paths,
+)
+from .terminal import InteractiveTerminal, cancel_on_sigint, run_turn
+
+
+@dataclass(frozen=True)
+class Options:
+    prompt: str | None
+    cwd: Path | None
+    session_dir: Path | None
+    resume: str | None
+    sessions: bool
+    fake: bool
+    shell: ShellName | None
+    tools: str | None
+    model: str | None
+    max_turns: int | None
+    max_output_tokens: int
+    model_timeout: int
+    verbose: bool
+
+
+def positive_integer(value: str) -> int:
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("必须是大于 0 的整数")
+    return number
+
+
+def parse_options(argv: list[str] | None) -> Options:
+    parser = argparse.ArgumentParser(
+        prog="citrus",
+        description="Python coding agent；不传任务进入交互模式，传入任务则单次运行。",
+    )
+    parser.add_argument("prompt", nargs="?", help="单次任务；多词任务请用引号包裹")
+    parser.add_argument("--cwd", type=Path, help="工作目录；恢复时默认使用会话原目录")
+    parser.add_argument("--session-dir", type=Path, help="会话目录，默认 <工作目录>/.citrus-code/sessions")
+    parser.add_argument("--resume", nargs="?", const="latest", metavar="FILE", help="恢复指定 JSONL 文件；省略路径时恢复当前会话目录中最近的文件")
+    parser.add_argument("--sessions", action="store_true", help="列出当前会话目录的文件并退出")
+    parser.add_argument("--fake", action="store_true", help="离线固定文字响应，不调用远程模型")
+    parser.add_argument("--shell", choices=("bash", "powershell"), help="新会话的命令工具；Windows 默认 powershell，其他平台默认 bash")
+    parser.add_argument("--tools", choices=("coding", "read-only", "all"), help="新会话的工具组合，默认 coding")
+    parser.add_argument("--model", help="模型 ID；恢复时须与会话记录匹配")
+    parser.add_argument("--max-turns", type=positive_integer, help="本次运行的模型调用轮数上限，默认不限制")
+    parser.add_argument(
+        "--max-output-tokens", type=positive_integer, default=32768,
+        help="每次模型调用的输出上限，默认 32768；工具参数和文件正文也计入",
+    )
+    parser.add_argument(
+        "--model-timeout", type=positive_integer, default=300,
+        help="等待模型响应数据的最长空闲时间（秒），默认 300；不是整项任务的总时限",
+    )
+    parser.add_argument("--verbose", action="store_true", help="同时打印成功工具调用的完整返回文字")
+    args = parser.parse_args(argv)
+    if args.sessions and (args.prompt is not None or args.resume is not None):
+        parser.error("--sessions 请单独使用，可搭配 --cwd 和 --session-dir")
+    prompt = args.prompt
+    if not args.sessions and prompt is None:
+        if not sys.stdin.isatty():
+            prompt = sys.stdin.read().strip()
+            if not prompt:
+                parser.error("标准输入为空；请传入任务或在终端中启动交互模式")
+        elif not sys.stdout.isatty():
+            parser.error("交互模式需要终端输出；重定向输出时请传入单次任务")
+    if prompt is not None and not prompt.strip():
+        parser.error("任务不能为空")
+    return Options(
+        prompt, args.cwd, args.session_dir, args.resume, args.sessions, args.fake,
+        args.shell, args.tools, args.model, args.max_turns, args.max_output_tokens,
+        args.model_timeout, args.verbose,
+    )
+
+
+def choose_tools(options: Options, default_shell: ShellName | None = None) -> LaunchSettings:
+    shell: ShellName = options.shell or default_shell or ("powershell" if os.name == "nt" else "bash")
+    if shell == "powershell" and os.name != "nt":
+        raise ValueError("当前内置 powershell 工具只支持 Windows")
+    if options.tools == "read-only":
+        names = list(READ_ONLY_TOOLS)
+    elif options.tools == "all":
+        names = ["read", "bash", "edit", "write", "grep", "find", "ls"]
+        if os.name == "nt":
+            names.append("powershell")
+    else:
+        names = ["read", shell, "edit", "write"]
+    return LaunchSettings(shell=shell, tools=names)
+
+
+def list_sessions(directory: Path) -> None:
+    paths = session_paths(directory)
+    print(f"会话目录：{directory}")
+    if not paths:
+        print("没有保存的会话。")
+    for path in paths:
+        modified = datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).isoformat(timespec="seconds")
+        print(f"{modified}  {path}")
+
+
+async def run_application(options: Options) -> int:
+    launch_cwd = (options.cwd or Path.cwd()).expanduser().resolve()
+    if not launch_cwd.is_dir():
+        raise NotADirectoryError(f"工作目录不存在：{launch_cwd}")
+    directory = (
+        options.session_dir.expanduser().resolve()
+        if options.session_dir is not None
+        else launch_cwd / ".citrus-code" / "sessions"
+    )
+    if options.sessions:
+        list_sessions(directory)
+        return 0
+
+    console = Console(options.verbose, max_output_tokens=options.max_output_tokens)
+    async with AsyncExitStack() as resources:
+        if options.resume is not None:
+            if options.resume == "latest":
+                paths = session_paths(directory)
+                if not paths:
+                    raise FileNotFoundError(f"没有可以恢复的会话：{directory}")
+                path = paths[0]
+            else:
+                path = Path(options.resume).expanduser().resolve()
+            if not path.is_file():
+                raise FileNotFoundError(f"会话文件不存在：{path}")
+            resources.enter_context(session_lease(path))
+            manager = SessionManager.load(path)
+            cwd = Path(manager.header.cwd).expanduser().resolve()
+            if options.cwd is not None and launch_cwd != cwd:
+                raise ValueError(f"--cwd 与会话原工作目录不一致：{cwd}")
+            if not cwd.is_dir():
+                raise NotADirectoryError(f"会话原工作目录不存在：{cwd}")
+            stored_settings = load_settings(path)
+            if stored_settings is not None:
+                requested = choose_tools(options, default_shell=stored_settings.shell)
+                if options.shell is not None and requested.shell != stored_settings.shell:
+                    raise ValueError("恢复时沿用原命令工具；更换工具请创建新会话")
+                if options.tools is not None and requested.tools != stored_settings.tools:
+                    raise ValueError("恢复时沿用原工具组合；更换工具请创建新会话")
+                settings = stored_settings
+            else:
+                settings = choose_tools(options)
+                console.note("[恢复] 此会话没有 CLI 工具配置，使用当前选择的工具组合。")
+        else:
+            cwd = launch_cwd
+            manager = SessionManager(cwd)
+            path = directory / f"{manager.header.id}.jsonl"
+            settings = choose_tools(options)
+            resources.enter_context(session_lease(path))
+
+        context_files = load_project_context(cwd)
+        context = manager.build_context()
+        fake = options.fake or context.provider == "fake"
+        provider: Provider
+        model: ModelSpec
+        if fake:
+            if context.provider not in (None, "fake"):
+                raise ValueError("--fake 不能用于恢复真实模型会话")
+            fake_provider = FakeProvider(
+                chunks=["这是离线模拟回答。", "当前入口已连接事件流、", "会话保存和消息队列。",
+                        "模拟模型只输出预设文字，", "不会执行你的编程任务。\n"],
+                delay_seconds=0.25,
+            )
+            provider = fake_provider
+            model = fake_provider.get_models()[0]
+            if options.model is not None and options.model != model.id:
+                raise ValueError("离线模式的模型 ID 为 fake-text")
+        else:
+            if context.provider not in (None, "deepseek"):
+                raise ValueError(f"CLI 尚未接入此 Provider：{context.provider}")
+            config = load_connection_config()
+            model_id = options.model or context.model_id or config.model_id
+            model = ModelSpec(
+                id=model_id, name=model_id, provider=config.provider_id,
+                api="chat-completions", base_url=config.base_url,
+                context_window=CONTEXT_WINDOW,
+                supports_images=model_id in DEEPSEEK_VISION_MODEL_IDS,
+            )
+            client = await resources.enter_async_context(httpx.AsyncClient(
+                timeout=httpx.Timeout(connect=30.0, read=options.model_timeout, write=120.0, pool=30.0),
+            ))
+            provider = DeepSeekProvider(client, model, config.api_key)
+
+        if context.provider is not None and (
+            context.provider != model.provider or context.model_id != model.id
+        ):
+            raise ValueError("恢复时必须使用会话记录的模型，当前尚未提供模型切换入口")
+        tools = create_tools(cwd, settings.tools)
+        system_prompt = build_system_prompt(
+            cwd, settings.tools, context_files, supports_images=model.supports_images,
+        )
+        if options.resume is None:
+            manager.save(path)
+            save_settings(path, settings)
+
+        recovered = recover_pending_tools(manager)
+        session = CodingSession(
+            provider=provider, model=model, tools=tools, session_manager=manager,
+            system_prompt=system_prompt,
+            hooks=SystemPromptHooks(system_prompt),
+            options=ModelOptions(max_output_tokens=options.max_output_tokens),
+            max_turns=options.max_turns,
+        )
+        console.welcome(
+            cwd, model, settings.tools, path, [item.path for item in context_files],
+            fake=fake, resumed=options.resume is not None, interactive=options.prompt is None,
+        )
+        if recovered:
+            console.note(f"[恢复] 为 {recovered} 个缺少结果的工具调用补充了执行状态未知记录。")
+        if options.resume is not None and options.prompt is None:
+            console.history(session, limit=4)
+        if options.prompt is not None:
+            with cancel_on_sigint(session, console):
+                outcome = await run_turn(session, console, options.prompt)
+            return outcome.exit_code
+        return await InteractiveTerminal(session, console).run()
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        options = parse_options(argv)
+        return asyncio.run(run_application(options))
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        print(f"citrus: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2

citrus_code/cli/preview.py

@@ -0,0 +1,55 @@
+"""A bounded Markdown preview rendered by the existing prompt application."""
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.formatted_text import ANSI, FormattedText
+from prompt_toolkit.layout import ConditionalContainer, HSplit, Layout, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+
+from .render import Console
+
+
+class MarkdownPreview:
+    def __init__(self, console: Console, prompt: PromptSession[str]) -> None:
+        self.console = console
+        self.prompt = prompt
+        self._cache_key: tuple[str, int, int] | None = None
+        self._cache = ANSI("")
+        original = prompt.layout
+        preview = ConditionalContainer(
+            HSplit([
+                Window(FormattedTextControl(FormattedText([
+                    ("class:prompt", " Citrus Code"),
+                    ("class:status.dim", " · 正在生成"),
+                ])), height=1),
+                Window(
+                    FormattedTextControl(self._text), dont_extend_height=True,
+                    wrap_lines=False, always_hide_cursor=True,
+                ),
+                Window(height=1),
+            ]),
+            filter=Condition(lambda: (
+                bool(console.response) and not prompt.app.is_done
+                and prompt.app.output.get_size().rows >= 12
+            )),
+        )
+        # Keep the existing buffers, completion menus, search and key bindings.
+        prompt.layout = Layout(HSplit([preview, original.container]), original.current_window)
+        prompt.app.layout = prompt.layout
+        console.set_preview_listener(prompt.app.invalidate)
+
+    def _text(self) -> ANSI:
+        size = self.prompt.app.output.get_size()
+        width = max(10, size.columns - 2)
+        height = max(2, min(18, size.rows - 11))
+        key = (self.console.response, width, height)
+        if key != self._cache_key:
+            lines = self.console.preview_ansi(width).splitlines()
+            if len(lines) > height:
+                lines = ["… 较早内容将在生成完成后显示"] + lines[-(height - 1):]
+            self._cache = ANSI("\n".join(" " + line for line in lines))
+            self._cache_key = key
+        return self._cache
+
+    def close(self) -> None:
+        self.console.set_preview_listener(None)

citrus_code/cli/prompts.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+
+from ..coding.project_context import ProjectContextFile
+
+
+def build_system_prompt(
+    cwd: Path,
+    tool_names: list[str],
+    context_files: list[ProjectContextFile],
+    *,
+    supports_images: bool = False,
+) -> str:
+    base_prompt = (
+        f"你是一个 coding agent，工作目录是 {cwd}。\n"
+        f"当前可用工具：{', '.join(tool_names)}。\n"
+        "先读取相关文件，再进行修改，以实际工具结果为依据。\n"
+        "用 edit 精确修改，用 write 创建文件或完整重写。"
+        "edit 参数是 path 和 edits；每项包含 oldText、newText。"
+        "同一批替换针对原文件定位，oldText 必须唯一且互不重叠。\n"
+        "生成较大文件时，先写可运行的骨架，再用 edit 分批补充，"
+        "避免一次工具调用携带过长内容。只有收到工具结果后，才能判断修改是否成功。\n"
+        "bash 工具使用 Bash 语法，powershell 工具使用 PowerShell 语法。\n"
+        "如果历史中的工具结果说明执行状态未知，先检查实际文件、日志或进程状态，"
+        "再决定下一步。\n"
+        "切换对话分支不会撤销项目文件的修改。\n"
+        "完成任务后简要说明修改、依据以及尚未完成的工作。使用中文回答。"
+    )
+    if "powershell" in tool_names:
+        base_prompt += (
+            "\nPowerShell 命令按 Windows PowerShell 5.1 兼容语法编写，不使用 &&、|| 或 Bash heredoc。"
+            "反斜杠不是 PowerShell 的引号转义符；正则、路径和不需要变量展开的文字优先用单引号。"
+            "每次命令使用独立会话，变量和 cd 不会传给下一次调用。"
+            "复杂 Python、JavaScript 和多层引号代码先用 write 写成脚本文件，再运行脚本，避免嵌套 -c/-e。"
+            "检查命令退出状态及预期文件，不用 Out-Null 隐藏排错所需的输出。"
+        )
+    if supports_images:
+        base_prompt += (
+            "\n当前模型配置已启用图片理解。用户给出本地图片路径时，"
+            "先调用 read 取得图片附件，再根据实际图像回答，不要仅凭路径声称无法看图。"
+            "支持 PNG、JPEG、GIF 和 WebP，其他图片格式需先转换。"
+            "SVG 和 HTML 是源码；分析源码不等于已经看到浏览器渲染结果，"
+            "需要视觉检查时应取得截图后读取。"
+        )
+    else:
+        base_prompt += "\n当前模型配置未启用图片输入；读取图片得到的附件不会发送给模型。"
+    if not context_files:
+        return base_prompt
+
+    sections = [base_prompt, "以下是当前项目的工作约定，请在执行任务时遵守。"]
+    for context_file in context_files:
+        sections.append(f"项目指令来源：{context_file.path}\n\n{context_file.content}")
+    return "\n\n".join(sections)

citrus_code/cli/render.py

@@ -0,0 +1,306 @@
+"""Rich transcript rendering; the terminal owns interactive cursor movement."""
+
+import time
+from collections.abc import Callable
+from io import StringIO
+from pathlib import Path
+
+from rich.console import Console as RichConsole, Group
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from ..agent.events import (
+    AgentEndEvent, AgentEvent, AssistantMessageCommittedEvent,
+    ContextCompactedEvent, MessageAcceptedEvent, ModelEvent,
+    ToolExecutionEndEvent, ToolExecutionStartEvent, TurnStartEvent,
+)
+from ..ai.events import DoneEvent, ErrorEvent, StartEvent, TextDeltaEvent, TextStartEvent, ToolCallStartEvent
+from ..ai.types import Message, ModelSpec, TextContent, ToolCall
+from ..coding.coding_session import CodingSession
+from ..coding.session import CompactionEntry, SessionMessageEntry
+from .theme import ACCENT, BORDER, LOGO, RICH_THEME, clean_text
+
+
+def message_text(message: Message) -> str:
+    if isinstance(message.content, str):
+        return clean_text(message.content)
+    return clean_text("\n".join(block.text for block in message.content if isinstance(block, TextContent)))
+
+
+def markdown(text: str) -> Markdown:
+    return Markdown(clean_text(text), code_theme="monokai", hyperlinks=False)
+
+
+class Console:
+    def __init__(self, verbose: bool = False, *, max_output_tokens: int | None = None) -> None:
+        self.verbose = verbose
+        self.max_output_tokens = max_output_tokens
+        self.rich = RichConsole(theme=RICH_THEME, markup=False, highlight=False, emoji=False)
+        self.model_name = ""
+        self.supports_images = False
+        self.phase = "就绪"
+        self._response = ""
+        self._preview_listener: Callable[[], None] | None = None
+        self._live: Live | None = None
+        self._started = 0.0
+        self._tool_started: dict[str, float] = {}
+        self._input_tokens = 0
+        self._output_tokens = 0
+
+    @property
+    def response(self) -> str:
+        return self._response
+
+    def set_preview_listener(self, listener: Callable[[], None] | None) -> None:
+        self._preview_listener = listener
+
+    def _refresh(self) -> None:
+        if self._preview_listener is not None:
+            self._preview_listener()
+        elif self._response and self.rich.is_terminal and not self.rich.is_dumb_terminal:
+            content = Group(Text("Citrus Code", style="accent"), markdown(self._response))
+            if self._live is None:
+                self._live = Live(
+                    content, console=self.rich, transient=True, refresh_per_second=8,
+                    redirect_stdout=False, redirect_stderr=False,
+                )
+                self._live.start()
+            else:
+                self._live.update(content)
+
+    def finish_response(self, text: str | None = None) -> None:
+        content = self._response if text is None else text
+        self._response = ""
+        if self._live is not None:
+            self._live.stop()
+            self._live = None
+        self._refresh()
+        if content.strip():
+            self.rich.print(Padding(Group(
+                Text("Citrus Code", style="accent"), markdown(content),
+            ), (1, 1, 0, 1)))
+
+    def preview_ansi(self, width: int) -> str:
+        """Format a frame only; no cursor control or direct terminal output."""
+        buffer = StringIO()
+        renderer = RichConsole(
+            file=buffer, width=max(10, width), force_terminal=True,
+            color_system="truecolor", theme=RICH_THEME, markup=False,
+            highlight=False, emoji=False,
+        )
+        renderer.print(markdown(self._response))
+        return buffer.getvalue()
+
+    def welcome(
+        self, cwd: Path, model: ModelSpec, tools: list[str], session_path: Path,
+        context_paths: list[Path], *, fake: bool, resumed: bool, interactive: bool,
+    ) -> None:
+        self.model_name = model.id
+        self.supports_images = model.supports_images
+        if interactive:
+            left = Group(
+                Text(LOGO, style="accent"), Text(),
+                Text("Citrus Code · Python coding agent", style="bold"),
+                Text(model.id + (" · 图像已启用" if model.supports_images else ""), style="muted"),
+                Text(str(cwd), style="muted"),
+            )
+            right = Group(
+                Text("继续你的项目" if resumed else "从一个具体任务开始", style="accent"),
+                Text(), Text("/help       查看全部命令"),
+                Text("/history    回看当前对话"), Text("/tree       查看与切换分支"),
+                Text(), Text("Enter 发送 · Alt+Enter 换行", style="muted"),
+                Text("Ctrl+C 取消 · Ctrl+D 退出", style="muted"),
+            )
+            if self.rich.width >= 82:
+                grid = Table.grid(expand=True, padding=(0, 2))
+                grid.add_column(ratio=1)
+                grid.add_column(ratio=1)
+                grid.add_row(left, right)
+                self.rich.print(Panel(
+                    grid, title=Text(" Citrus Code v0.1.0 ", style="accent"),
+                    title_align="left", border_style=ACCENT, padding=(1, 2),
+                ))
+            else:
+                self.rich.print(Panel(
+                    Group(left, Text(), right), title=Text(" Citrus Code v0.1.0 ", style="accent"),
+                    title_align="left", border_style=ACCENT, padding=(1, 1),
+                ))
+        else:
+            self.rich.print(Text.assemble(("Citrus Code", "accent"), f"  {model.id}  ", (str(cwd), "muted")))
+        details = Text("工具  ", style="muted")
+        details.append(" · ".join(tools))
+        details.append("\n项目指令  ", style="muted")
+        details.append(" · ".join(str(path) for path in context_paths) or "无")
+        details.append("\n会话  ", style="muted")
+        details.append(str(session_path))
+        details.append("\n上下文  1M · 60% 自动压缩", style="muted")
+        if self.max_output_tokens is not None:
+            details.append(f"\n单次输出上限  {self.max_output_tokens:,} tokens", style="muted")
+        self.rich.print(Padding(details, (0, 1, 1, 1)))
+        if fake:
+            self.note("[离线模式] 只输出预设文字，不执行编程任务。")
+
+    def begin_turn(self, text: str) -> None:
+        self.finish_response()
+        self._started = time.monotonic()
+        self._input_tokens = self._output_tokens = 0
+        self.phase = "思考中"
+        self.rich.print(Panel(
+            Text(clean_text(text)), title=Text("你", style="info"),
+            title_align="left", border_style=BORDER, padding=(0, 1),
+        ))
+        self._refresh()
+
+    def note(self, text: str) -> None:
+        style = "error" if any(word in text for word in ("失败", "错误")) else "muted"
+        self.rich.print(Padding(Text(clean_text(text), style=style), (0, 1)))
+
+    def event(self, event: AgentEvent) -> None:
+        if isinstance(event, TurnStartEvent):
+            self.phase = "思考中"
+        elif isinstance(event, ModelEvent):
+            model_event = event.event
+            if isinstance(model_event, StartEvent):
+                self.phase = "生成中"
+                self._response = ""
+            elif isinstance(model_event, TextStartEvent):
+                if self._response:
+                    self._response += "\n\n"
+            elif isinstance(model_event, TextDeltaEvent):
+                self._response += clean_text(model_event.delta)
+            elif isinstance(model_event, ToolCallStartEvent):
+                self.phase = "准备工具调用"
+            elif isinstance(model_event, DoneEvent):
+                self.finish_response(message_text(model_event.message))
+            elif isinstance(model_event, ErrorEvent):
+                self.finish_response(message_text(model_event.error) or self._response)
+        elif isinstance(event, AssistantMessageCommittedEvent):
+            if event.message.usage is not None:
+                self._input_tokens += event.message.usage.input_tokens
+                self._output_tokens += event.message.usage.output_tokens
+        elif isinstance(event, MessageAcceptedEvent):
+            label = "引导消息已接纳" if event.source == "steering" else "后续任务已接纳"
+            self.rich.print(Panel(Text(message_text(event.message)), title=label, border_style="info"))
+        elif isinstance(event, ToolExecutionStartEvent):
+            self.phase = f"执行 {event.call.name}"
+            self._tool_started[event.call.id] = time.monotonic()
+            line = Text(f"  {event.call.name}  ", style="info")
+            line.append(self._call_summary(event.call), style="muted")
+            self.rich.print(line)
+        elif isinstance(event, ToolExecutionEndEvent):
+            self._tool_result(event)
+            self.phase = "思考中"
+        elif isinstance(event, ContextCompactedEvent):
+            self.note(f"上下文已压缩  {event.tokens_before:,} → {event.tokens_after:,} tokens；继续当前任务。")
+        elif isinstance(event, AgentEndEvent):
+            self.finish_response()
+            elapsed = time.monotonic() - self._started if self._started else 0
+            label = {"stop": "完成", "aborted": "已取消", "length": "回复被截断",
+                     "max_turns": "达到轮数上限", "error": "运行错误"}[event.reason]
+            style = "success" if event.reason == "stop" else ("accent" if event.reason == "length" else "error")
+            line = Text(f"  {label} · {elapsed:.1f}s", style=style)
+            if self._input_tokens or self._output_tokens:
+                line.append(f" · 输入 {self._input_tokens:,} / 输出 {self._output_tokens:,} tokens", style="muted")
+            self.rich.print(line)
+            self.rich.print()
+            if event.error_message:
+                self.note(event.error_message)
+            elif event.reason == "error":
+                self.note("运行失败，但未收到具体错误详情。请检查模型连接；已经完成的工具结果仍保留在会话中。")
+            elif event.reason == "length":
+                self.note("模型达到本次生成长度限制。可提高 --max-output-tokens，或将较大文件分批写入。")
+            self.phase = "就绪"
+        self._refresh()
+
+    def _call_summary(self, call: ToolCall) -> str:
+        parts: list[str] = []
+        for key in ("path", "command", "pattern"):
+            value = call.arguments.get(key)
+            if isinstance(value, str) and value:
+                parts.append(value)
+        return " ".join(clean_text(" · ".join(parts)).split())[:160]
+
+    def _tool_result(self, event: ToolExecutionEndEvent) -> None:
+        call, message = event.call, event.result.message
+        started = self._tool_started.pop(call.id, time.monotonic())
+        elapsed = time.monotonic() - started
+        text = message_text(message)
+        if not self.verbose and not message.is_error:
+            lines = text.splitlines()
+            preview = "\n".join(lines[:8])
+            omitted = len(lines) > 8 or len(preview) > 1800
+            text = preview[:1800]
+            if omitted:
+                text += "\n… 输出展示已折叠；使用 --verbose 启动可查看完整返回。"
+        language = "text"
+        if call.name == "edit":
+            language = "diff"
+        elif call.name == "read":
+            path = call.arguments.get("path")
+            if isinstance(path, str):
+                language = {".py": "python", ".ts": "typescript", ".js": "javascript",
+                            ".json": "json", ".toml": "toml", ".yaml": "yaml",
+                            ".yml": "yaml", ".md": "markdown", ".java": "java"}.get(Path(path).suffix, "text")
+        body = Syntax(text or "(无文字输出)", language, theme="monokai", word_wrap=True, background_color="default")
+        status = "失败" if message.is_error else "完成"
+        self.rich.print(Padding(Panel(
+            body, title=Text(f"{call.name} · {status} · {elapsed:.1f}s"),
+            title_align="left", border_style="error" if message.is_error else BORDER,
+            padding=(0, 1),
+        ), (0, 1)))
+        for block in message.content:
+            if not isinstance(block, TextContent):
+                self.note(f"图片附件  {block.mime_type}")
+
+    def status(self, session: CodingSession) -> None:
+        manager = session.session_manager
+        estimate = session.compaction.last_estimate if session.compaction is not None else None
+        table = Table.grid(padding=(0, 2))
+        for label, value in (
+            ("状态", self.phase), ("模型", self.model_name),
+            ("模型输入", "文字、图片" if self.supports_images else "文字"),
+            ("单次输出上限", f"{self.max_output_tokens:,} tokens" if self.max_output_tokens is not None else "由调用方配置"),
+            ("轮次", str(session.agent.state.turn)),
+            ("排队消息", "有" if session.has_queued_messages() else "无"),
+            ("上下文", f"约 {estimate:,} / 1,000,000 tokens（上次检查）" if estimate is not None else "尚未估算"),
+            ("当前节点", manager.leaf_id or "无"), ("会话文件", str(manager.file_path)),
+        ):
+            table.add_row(Text(label, style="muted"), Text(clean_text(value)))
+        self.rich.print(Panel(table, title="会话状态", border_style=BORDER, title_align="left"))
+
+    def history(self, session: CodingSession, limit: int | None = None) -> None:
+        messages = [m for m in session.agent.state.messages if m.role in ("user", "assistant")]
+        if limit is not None:
+            messages = messages[-limit:]
+        for message in messages:
+            text = message_text(message)
+            if not text:
+                continue
+            if message.role == "assistant":
+                self.rich.print(Padding(Group(Text("Citrus Code", style="accent"), markdown(text[:6000])), (1, 1)))
+            else:
+                self.rich.print(Panel(Text(text[:6000]), title="你 / 历史背景", border_style=BORDER, title_align="left"))
+            if len(text) > 6000:
+                self.note("此消息展示已截断，完整内容保存在会话中。")
+
+    def tree(self, session: CodingSession) -> None:
+        manager = session.session_manager
+        table = Table(box=None, padding=(0, 1), expand=True)
+        for column in ("", "节点", "父节点", "内容"):
+            table.add_column(column, style="muted" if column == "父节点" else "")
+        for entry in manager.get_entries():
+            marker = ">" if entry.id == manager.leaf_id else ""
+            parent = entry.parent_id[:12] if entry.parent_id else "root"
+            if isinstance(entry, SessionMessageEntry):
+                label = f"{entry.message.role}: {' '.join(message_text(entry.message).split())[:90]}"
+            elif isinstance(entry, CompactionEntry):
+                label = f"压缩: {entry.tokens_before:,} → {entry.tokens_after:,} tokens"
+            else:
+                label = f"模型: {entry.provider}/{entry.model_id}"
+            table.add_row(marker, entry.id[:12], parent, Text(label))
+        self.rich.print(Panel(table, title="会话分支", border_style=BORDER, title_align="left"))