agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/tracing/span_utils.py

@@ -0,0 +1,114 @@
+"""
+Tracing 工具函数
+
+提供公共的 Trace 元数据准备函数，供所有 Runner 使用。
+"""
+
+from pathlib import Path
+from typing import Any, List, Optional, Tuple
+
+
+def prepare_trace_metadata(
+    detection_result: Any = None,
+) -> Tuple[Optional[str], List[str], Optional[str], Optional[str]]:
+    """准备 Trace 元数据 (Tags, UserID, etc.)
+
+    Args:
+        detection_result: 框架检测结果，用于获取 Agent 名称
+
+    Returns:
+        Tuple of (user_id, tags, version, agent_name)
+    """
+    user_id = None
+    tags: List[str] = []
+    version = None
+    agent_name = None
+
+    try:
+        from ksadk.configs import settings
+
+        agent_config = settings.agent
+
+        user_id = agent_config.user_id
+        version = agent_config.version
+        tags = list(agent_config.tags or [])
+
+        # Add Environment
+        if agent_config.environment and agent_config.environment not in tags:
+            tags.append(agent_config.environment)
+
+        # Add Region (Kingsoft Cloud)
+        if settings.cloud.region and settings.cloud.region not in tags:
+            tags.append(settings.cloud.region)
+
+        # Add Model Name
+        if settings.model.model_name and settings.model.model_name not in tags:
+            tags.append(settings.model.model_name)
+
+        # Add Agent Name (Configured -> Fallback)
+        agent_name = agent_config.agent_name
+        if not agent_name and detection_result:
+            try:
+                # Fallback to package name
+                agent_name = Path(detection_result.package_path).name
+            except Exception:
+                pass
+
+        if agent_name and agent_name not in tags:
+            tags.append(agent_name)
+
+        # Add Agent ID
+        if agent_config.agent_id and agent_config.agent_id not in tags:
+            tags.append(agent_config.agent_id)
+
+        # Add Tenant ID (Account ID)
+        if agent_config.tenant_id and agent_config.tenant_id not in tags:
+            tags.append(agent_config.tenant_id)
+
+    except ImportError:
+        pass
+    except Exception:
+        pass
+
+    return user_id, tags, version, agent_name
+
+
+def get_langfuse_callback(
+    session_id: str,
+    user_id: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    version: Optional[str] = None,
+    trace_name: Optional[str] = None,
+) -> Optional[Any]:
+    """获取 Langfuse Callback Handler
+
+    Args:
+        session_id: 会话 ID
+        user_id: 用户 ID
+        tags: 标签列表
+        version: 版本号
+        trace_name: Trace 名称
+
+    Returns:
+        Langfuse callback handler 或 None
+    """
+    try:
+        from ksadk.tracing import get_langfuse_callback_handler
+
+        handler = get_langfuse_callback_handler()
+        if handler:
+            # 设置 session 和 metadata
+            handler.session_id = session_id
+            if user_id:
+                handler.user_id = user_id
+            if tags:
+                handler.tags = tags
+            if version:
+                handler.version = version
+            if trace_name:
+                handler.trace_name = trace_name
+        return handler
+    except ImportError:
+        return None
+    except Exception:
+        return None

ksadk/tui/__init__.py

@@ -0,0 +1,12 @@
+"""
+KsADK TUI - Textual Terminal User Interface
+
+提供简洁的交互体验:
+- 流式 Markdown 输出
+- 历史记录支持
+- 思考过程显示
+"""
+
+from ksadk.tui.app import AgentTUI
+
+__all__ = ["AgentTUI"]

ksadk/tui/app.py

@@ -0,0 +1,400 @@
+"""
+KsADK Agent TUI - 简洁交互界面
+
+基本功能：
+- 对话交互
+- 思考过程显示（通过 --show-thinking 参数控制）
+- 工具调用显示
+- 退出：输入 exit/quit 或 Ctrl+C/Ctrl+D
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from textual import on
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Static
+from textual.events import MouseUp
+
+from rich.panel import Panel
+
+from ksadk.tui.clipboard import copy_selection_to_clipboard
+from ksadk.tui.widgets.user import UserMessage
+from ksadk.tui.widgets.assistant import AssistantMessage
+from ksadk.tui.widgets.thinking import ThinkingMessage
+from ksadk.tui.widgets.system import SystemMessage
+from ksadk.tui.widgets.chat_input import ChatInput
+
+if TYPE_CHECKING:
+    from ksadk.runners.base_runner import BaseRunner
+
+
+def _clean_response(text: str) -> str:
+    """清理 LLM 响应中的内部调试信息"""
+    text = re.sub(r'\[Tool Result:.*?\]', '', text, flags=re.DOTALL)
+    text = re.sub(r'<tool_call>.*?</tool_call>', '', text, flags=re.DOTALL)
+    text = re.sub(r"name='[^']*'\s*tool_call_id='[^']*'", '', text)
+    return text.strip()
+
+
+class ApprovalScreen(ModalScreen[bool]):
+    """敏感操作确认弹窗"""
+
+    BINDINGS = [
+        Binding("y", "approve", "确认"),
+        Binding("n", "reject", "取消"),
+        Binding("escape", "reject", "取消"),
+    ]
+
+    def __init__(self, tool_name: str, args: Dict[str, Any], **kwargs):
+        super().__init__(**kwargs)
+        self.tool_name = tool_name
+        self.tool_args = args
+
+    def compose(self) -> ComposeResult:
+        args_str = "\n".join(f"  {k}: {v}" for k, v in self.tool_args.items()) if self.tool_args else "  (无参数)"
+        yield Container(
+            Static(
+                Panel(
+                    f"[bold yellow]⚠️  需要您确认敏感操作[/]\n\n"
+                    f"[bold]操作:[/] {self.tool_name}\n"
+                    f"[bold]参数:[/]\n{args_str}\n\n"
+                    f"[green]y[/] 确认  [red]n[/] 取消",
+                    title="🔒 确认",
+                    border_style="yellow",
+                ),
+            ),
+            id="approval-dialog",
+        )
+
+    def action_approve(self) -> None:
+        self.dismiss(True)
+
+    def action_reject(self) -> None:
+        self.dismiss(False)
+
+    CSS = """
+    #approval-dialog {
+        align: center middle;
+        width: 60;
+        height: auto;
+    }
+    """
+
+
+class AgentTUI(App):
+    """KsADK Agent TUI - 简洁交互界面"""
+
+    CSS = """
+    Screen {
+        background: $background;
+    }
+
+    #main-scroll {
+        height: 100%;
+        padding: 0 1;
+    }
+
+    #title-bar {
+        height: 1;
+        color: $primary;
+        padding: 0;
+    }
+
+    #welcome-area {
+        height: auto;
+        padding: 2 0;
+        content-align: center middle;
+        text-align: center;
+    }
+
+    #chat-log {
+        height: auto;
+        background: transparent;
+        padding: 0;
+    }
+
+    #input-area {
+        height: auto;
+        padding: 1 0;
+    }
+
+    #hint {
+        height: 1;
+        color: $text-muted;
+        padding: 0 0 0 2;
+    }
+
+    .started #welcome-area {
+        display: none;
+    }
+    """
+
+    BINDINGS = [
+        Binding("escape", "interrupt", "中断", show=False, priority=True),
+        Binding("ctrl+c", "quit_or_interrupt", "退出/中断", show=False),
+        Binding("ctrl+d", "quit_app", "退出", show=False, priority=True),
+        Binding("ctrl+q", "quit_app", "退出", show=False),
+    ]
+
+    TITLE = "KsADK"
+
+    def __init__(
+        self,
+        runner: "BaseRunner",
+        show_thinking: bool = False,
+        project_dir: str = ".",
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.runner = runner
+        self.show_thinking = show_thinking
+        self.project_dir = Path(project_dir).resolve()
+
+        self.session_id = getattr(runner, "session_id", None) or str(uuid.uuid4())[:8]
+        if getattr(self.runner, "session_id", None) is None:
+            self.runner.session_id = self.session_id
+        self.history: List[Dict[str, str]] = []
+        self._is_streaming = False
+        self._started = False
+        self.model_name = os.getenv("MODEL_NAME", "unknown")
+
+        try:
+            from ksadk import __version__
+            self.version = __version__
+        except ImportError:
+            self.version = "0.2.0"
+
+    def compose(self) -> ComposeResult:
+        """构建 UI 布局"""
+        with VerticalScroll(id="main-scroll"):
+            yield Static(f"─ KsADK v{self.version} ─", id="title-bar")
+
+            yield Container(
+                Static(
+                    f"[bold]Welcome![/]\n"
+                    f"🤖\n"
+                    f"[dim]{self.model_name} · Interactive Mode[/]\n"
+                    f"[dim]{self._short_path()}[/]",
+                    id="welcome-content",
+                ),
+                id="welcome-area",
+            )
+
+            with Vertical(id="chat-log"):
+                pass
+
+            yield Container(
+                ChatInput(cwd=self.project_dir, id="chat-input-widget"),
+                Static("Ctrl+C 退出", id="hint"),
+                id="input-area",
+            )
+
+    def _short_path(self) -> str:
+        home = Path.home()
+        try:
+            return "~/" + str(self.project_dir.relative_to(home))
+        except ValueError:
+            return str(self.project_dir)
+
+    def on_mount(self) -> None:
+        self.query_one("#chat-input-widget", ChatInput).focus_input()
+
+    @on(ChatInput.Submitted)
+    async def handle_input(self, event: ChatInput.Submitted) -> None:
+        """处理用户输入"""
+        user_input = event.value.strip()
+
+        if not user_input:
+            return
+
+        # 检查退出
+        if user_input.lower() in ("exit", "quit", "退出"):
+            self.exit()
+            return
+
+        # 隐藏欢迎区域
+        if not self._started:
+            self._started = True
+            self.add_class("started")
+
+        asyncio.create_task(self._stream_response(user_input))
+
+    async def _stream_response(self, user_input: str) -> None:
+        """流式获取 Agent 响应"""
+        chat_log = self.query_one("#chat-log", Vertical)
+        main_scroll = self.query_one("#main-scroll", VerticalScroll)
+
+        self._is_streaming = True
+
+        input_data = {
+            "input": user_input,
+            "session_id": self.session_id,
+            "history": self.history,
+        }
+
+        thinking_msg: Optional[ThinkingMessage] = None
+        assistant_msg: Optional[AssistantMessage] = None
+        full_response_text = ""
+
+        try:
+            await chat_log.mount(UserMessage(user_input))
+            main_scroll.scroll_end(animate=False)
+
+            async for chunk in self.runner.stream(input_data):
+                if not self._is_streaming:
+                    if thinking_msg:
+                        thinking_msg.stop()
+                    if assistant_msg:
+                        await assistant_msg.stop_stream()
+                    await chat_log.mount(SystemMessage("已中断", level="warning"))
+                    break
+
+                chunk_type = chunk.get("type", "text")
+
+                # 思考过程
+                if chunk_type == "thinking":
+                    delta = chunk.get("delta", "")
+                    if delta and self.show_thinking:
+                        if not thinking_msg:
+                            thinking_msg = ThinkingMessage()
+                            await chat_log.mount(thinking_msg)
+                            main_scroll.scroll_end(animate=False)
+                        await thinking_msg.append_content(delta)
+                    continue
+
+                if thinking_msg and thinking_msg.is_active:
+                    thinking_msg.stop()
+
+                # 中断/确认
+                if chunk_type == "interrupt":
+                    await self._handle_interrupt(chunk)
+                    return
+
+                # 工具调用 - 跳过不显示
+                if chunk_type == "tool_call":
+                    continue
+
+                # 文本响应
+                delta = chunk.get("output", "") or chunk.get("delta", "")
+                if delta:
+                    if not assistant_msg:
+                        assistant_msg = AssistantMessage()
+                        await chat_log.mount(assistant_msg)
+                        main_scroll.scroll_end(animate=False)
+                    await assistant_msg.append_content(delta)
+                    full_response_text += delta
+
+            if thinking_msg:
+                thinking_msg.stop()
+            if assistant_msg:
+                await assistant_msg.stop_stream()
+
+            cleaned_response = _clean_response(full_response_text)
+            if cleaned_response:
+                self.history.append({"role": "user", "content": user_input})
+                self.history.append({"role": "model", "content": cleaned_response})
+            elif self._is_streaming and not full_response_text:
+                result = await self.runner.invoke(input_data)
+                response_text = result.get("output", "")
+                cleaned_response = _clean_response(response_text)
+
+                if cleaned_response:
+                    assistant_msg = AssistantMessage()
+                    await chat_log.mount(assistant_msg)
+                    await assistant_msg.append_content(cleaned_response)
+                    await assistant_msg.stop_stream()
+                    self.history.append({"role": "user", "content": user_input})
+                    self.history.append({"role": "model", "content": cleaned_response})
+                else:
+                    await chat_log.mount(SystemMessage("(无响应)", level="warning"))
+
+        except asyncio.CancelledError:
+            await chat_log.mount(SystemMessage("已取消", level="warning"))
+        except Exception as e:
+            await chat_log.mount(SystemMessage(f"错误: {e}", level="error"))
+        finally:
+            self._is_streaming = False
+            main_scroll.scroll_end(animate=False)
+
+    async def _handle_interrupt(self, interrupt_chunk: Dict[str, Any]) -> None:
+        """处理敏感操作确认"""
+        interrupt_info = interrupt_chunk.get("interrupt_info", {})
+
+        if isinstance(interrupt_info, dict):
+            tool_name = interrupt_info.get("tool", "未知操作")
+            args = interrupt_info.get("args", {})
+        elif isinstance(interrupt_info, list) and interrupt_info:
+            first = interrupt_info[0]
+            tool_name = str(getattr(first, "value", first))
+            args = {}
+        else:
+            tool_name = str(interrupt_info)
+            args = {}
+
+        approved = await self.push_screen_wait(ApprovalScreen(tool_name, args))
+        chat_log = self.query_one("#chat-log", Vertical)
+
+        if approved:
+            await chat_log.mount(SystemMessage("✓ 已确认，继续执行...", level="success"))
+
+            resume_data = {
+                "input": "确认",
+                "session_id": interrupt_chunk.get("session_id", self.session_id),
+                "history": self.history,
+                "resume": True,
+            }
+
+            assistant_msg = AssistantMessage()
+            await chat_log.mount(assistant_msg)
+
+            try:
+                async for chunk in self.runner.stream(resume_data):
+                    delta = chunk.get("output", "") or chunk.get("delta", "")
+                    if delta:
+                        await assistant_msg.append_content(delta)
+                await assistant_msg.stop_stream()
+                if assistant_msg.content:
+                    self.history.append({"role": "model", "content": assistant_msg.content})
+            except Exception as e:
+                await chat_log.mount(SystemMessage(f"错误: {e}", level="error"))
+        else:
+            await chat_log.mount(SystemMessage("✗ 已取消操作", level="warning"))
+
+    def action_interrupt(self) -> None:
+        self._is_streaming = False
+
+    def action_quit_or_interrupt(self) -> None:
+        if self._is_streaming:
+            self.action_interrupt()
+        else:
+            self.exit()
+
+    def action_quit_app(self) -> None:
+        self.exit()
+
+    def on_mouse_up(self, event: MouseUp) -> None:
+        copy_selection_to_clipboard(self)
+
+
+def run_tui(
+    runner: "BaseRunner",
+    show_thinking: bool = False,
+    project_dir: str = ".",
+) -> None:
+    """启动 TUI 应用"""
+    app = AgentTUI(
+        runner=runner,
+        show_thinking=show_thinking,
+        project_dir=project_dir,
+    )
+    app.run()

ksadk/tui/clipboard.py

@@ -0,0 +1,100 @@
+"""剪贴板工具 - 支持鼠标选择复制"""
+
+from __future__ import annotations
+
+import base64
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from textual.app import App
+
+_PREVIEW_MAX_LENGTH = 40
+
+
+def _copy_osc52(text: str) -> None:
+    """使用 OSC 52 转义序列复制（支持 SSH/tmux）"""
+    encoded = base64.b64encode(text.encode("utf-8")).decode("ascii")
+    osc52_seq = f"\033]52;c;{encoded}\a"
+    if os.environ.get("TMUX"):
+        osc52_seq = f"\033Ptmux;\033{osc52_seq}\033\\"
+
+    try:
+        with open("/dev/tty", "w") as tty:
+            tty.write(osc52_seq)
+            tty.flush()
+    except Exception:
+        raise RuntimeError("OSC52 复制失败")
+
+
+def _shorten_preview(texts: list[str]) -> str:
+    """缩短文本预览"""
+    dense_text = "⏎".join(texts).replace("\n", "⏎")
+    if len(dense_text) > _PREVIEW_MAX_LENGTH:
+        return f"{dense_text[: _PREVIEW_MAX_LENGTH - 1]}…"
+    return dense_text
+
+
+def _clipboard_copy_methods(app: App):
+    copy_methods = []
+    if os.name != "nt":
+        copy_methods.append(_copy_osc52)
+
+    try:
+        import pyperclip
+        copy_methods.append(pyperclip.copy)
+    except ImportError:
+        pass
+
+    copy_methods.append(app.copy_to_clipboard)
+    return copy_methods
+
+
+def copy_selection_to_clipboard(app: App) -> None:
+    """复制选中文本到剪贴板
+    
+    遍历所有 widgets 获取选中文本并复制到系统剪贴板
+    """
+    selected_texts = []
+
+    for widget in app.query("*"):
+        if not hasattr(widget, "text_selection") or not widget.text_selection:
+            continue
+
+        selection = widget.text_selection
+
+        try:
+            result = widget.get_selection(selection)
+        except Exception:
+            continue
+
+        if not result:
+            continue
+
+        selected_text, _ = result
+        if selected_text.strip():
+            selected_texts.append(selected_text)
+
+    if not selected_texts:
+        return
+
+    combined_text = "\n".join(selected_texts)
+
+    for copy_fn in _clipboard_copy_methods(app):
+        try:
+            copy_fn(combined_text)
+            app.notify(
+                f'"{_shorten_preview(selected_texts)}" 已复制',
+                severity="information",
+                timeout=2,
+            )
+            return
+        except Exception:
+            continue
+
+    # 所有方式都失败
+    app.notify(
+        "复制失败 - 剪贴板不可用",
+        severity="warning",
+        timeout=3,
+    )

ksadk/tui/widgets/__init__.py

@@ -0,0 +1,22 @@
+"""
+TUI Widgets - 消息组件
+
+提供各类消息组件，用于 TUI 渲染。
+参考 deepagents-cli 的消息组件设计。
+"""
+
+from .base import MessageWidget
+from .user import UserMessage
+from .assistant import AssistantMessage
+from .thinking import ThinkingMessage
+from .tool_call import ToolCallMessage
+from .system import SystemMessage
+
+__all__ = [
+    "MessageWidget",
+    "UserMessage",
+    "AssistantMessage",
+    "ThinkingMessage",
+    "ToolCallMessage",
+    "SystemMessage",
+]