xg-cli 1.0__py3-none-any.whl

xg/llm/factory.py

@@ -0,0 +1,40 @@
+"""LlmClient 工厂：按解析后的 api_base / key / model 组装客户端。
+
+URL 与 Key 的解析（环境变量、配置合并）由 ConfigManager 负责，
+工厂只负责组装客户端，是后续 provider 差异化（能力、协议）的扩展点。
+"""
+
+from __future__ import annotations
+
+from xg.llm.client import LlmClient
+from xg.llm.openai_compat import OpenAICompatClient
+
+DEFAULT_TIMEOUT = 120.0
+
+
+def create_client(
+    api_base: str,
+    api_key: str,
+    model: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    retry_enabled: bool = True,
+    max_retries: int = 2,
+    retry_base_delay: float = 1.0,
+    retry_max_delay: float = 8.0,
+    retry_jitter: float = 0.25,
+    retry_total_timeout: float = 30.0,
+    respect_retry_after: bool = True,
+) -> LlmClient:
+    return OpenAICompatClient(
+        api_base=api_base,
+        api_key=api_key,
+        model=model,
+        timeout=timeout,
+        retry_enabled=retry_enabled,
+        max_retries=max_retries,
+        retry_base_delay=retry_base_delay,
+        retry_max_delay=retry_max_delay,
+        retry_jitter=retry_jitter,
+        retry_total_timeout=retry_total_timeout,
+        respect_retry_after=respect_retry_after,
+    )

xg/llm/openai_compat.py

@@ -0,0 +1,275 @@
+"""OpenAI-compatible Chat Completions 实现（httpx SSE 流式 + tool calling 增量聚合）。
+
+所有 provider（GLM / DeepSeek / Kimi / OpenAI 兼容）共享此模板。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, AsyncIterator
+
+import httpx
+
+from xg.llm.client import LlmClient, LlmError
+from xg.llm.types import Message, StreamEvent, ToolCall, Usage
+
+DEFAULT_TIMEOUT = 120.0
+
+
+def _looks_like_html_error(content_type: str = "", body: str = "") -> bool:
+    """Identify gateway/proxy error pages, which often use HTTP 400 generically."""
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    prefix = body.lstrip()[:512].lower()
+    return media_type == "text/html" or prefix.startswith(("<!doctype html", "<html", "<head", "<body"))
+
+
+def _status_retry_policy(
+    status_code: int,
+    *,
+    content_type: str = "",
+    body: str = "",
+) -> tuple[bool, str]:
+    if status_code == 408:
+        return True, "transient_api_error"
+    if status_code == 429:
+        return True, "rate_limited"
+    if status_code == 503:
+        return True, "service_unavailable"
+    if status_code == 504:
+        return True, "gateway_timeout"
+    if 500 <= status_code < 600:
+        return True, "transient_api_error"
+    if status_code in {400, 422}:
+        if _looks_like_html_error(content_type, body):
+            return True, "proxy_bad_request"
+        return False, "invalid_request"
+    if status_code == 401:
+        return False, "authentication_error"
+    if status_code == 403:
+        return False, "permission_error"
+    if status_code == 404:
+        return False, "endpoint_not_found"
+    if status_code == 413:
+        return False, "request_too_large"
+    return False, "api_error"
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value.strip()))
+    except ValueError:
+        try:
+            parsed = parsedate_to_datetime(value)
+            return max(0.0, parsed.timestamp() - time.time())
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+
+class OpenAICompatClient(LlmClient):
+    def __init__(
+        self,
+        api_base: str,
+        api_key: str,
+        model: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry_enabled: bool = True,
+        max_retries: int = 2,
+        retry_base_delay: float = 1.0,
+        retry_max_delay: float = 8.0,
+        retry_jitter: float = 0.25,
+        retry_total_timeout: float = 30.0,
+        respect_retry_after: bool = True,
+    ) -> None:
+        # F5：允许以空配置构造（启动不阻断），真正调用时再拦截并给出引导。
+        self.api_base = (api_base or "").rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+        self.retry_enabled = retry_enabled
+        self.max_retries = max(0, max_retries)
+        self.retry_base_delay = max(0.0, retry_base_delay)
+        self.retry_max_delay = max(0.0, retry_max_delay)
+        self.retry_jitter = max(0.0, min(1.0, retry_jitter))
+        self.retry_total_timeout = max(0.0, retry_total_timeout)
+        self.respect_retry_after = respect_retry_after
+
+    def stream_chat(
+        self, messages: list[Message], tools: list[dict] | None = None
+    ) -> AsyncIterator[StreamEvent]:
+        return self._stream_with_retry(messages, tools)
+
+    async def _stream_with_retry(
+        self, messages: list[Message], tools: list[dict] | None
+    ) -> AsyncIterator[StreamEvent]:
+        started_at = time.monotonic()
+        max_attempts = 1 + (self.max_retries if self.retry_enabled else 0)
+        for attempt in range(1, max_attempts + 1):
+            semantic_event_seen = False
+            try:
+                async for event in self._stream_once(messages, tools):
+                    if event.kind in {"content", "thinking", "tool_call"}:
+                        semantic_event_seen = True
+                    yield event
+                return
+            except LlmError as error:
+                error.response_started = error.response_started or semantic_event_seen
+                error.attempt = attempt
+                error.max_attempts = max_attempts
+                if (
+                    not self.retry_enabled
+                    or attempt >= max_attempts
+                    or not error.retryable
+                    or error.response_started
+                ):
+                    raise
+                delay = self._retry_delay(error, attempt)
+                elapsed = time.monotonic() - started_at
+                if elapsed + delay > self.retry_total_timeout:
+                    error.category = f"{error.category}_retry_timeout"
+                    raise
+                yield StreamEvent(
+                    kind="retrying",
+                    text="API 临时故障，正在重试",
+                    attempt=attempt + 1,
+                    max_attempts=max_attempts,
+                    retry_after=delay,
+                )
+                await asyncio.sleep(delay)
+
+    def _retry_delay(self, error: LlmError, attempt: int) -> float:
+        delay = min(self.retry_max_delay, self.retry_base_delay * (2 ** (attempt - 1)))
+        if self.respect_retry_after and error.retry_after is not None:
+            delay = max(delay, error.retry_after)
+        if self.retry_jitter:
+            delay *= random.uniform(1.0 - self.retry_jitter, 1.0 + self.retry_jitter)
+        return max(0.0, min(delay, self.retry_max_delay))
+
+    async def _stream_once(
+        self, messages: list[Message], tools: list[dict] | None
+    ) -> AsyncIterator[StreamEvent]:
+        if not self.api_base or not self.api_key or not self.model:
+            # F5：仅调用 LLM 时拦截，提示在会话内配置即可用，无需重启。
+            raise LlmError(
+                "缺少可用的 base provider / API Key。请在会话内用 /provider 配置，"
+                "例如 /provider add <name> <api_base> --model M --key K --set-base。"
+            )
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": [m.to_api() for m in messages],
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if tools:
+            payload["tools"] = [
+                {"type": "function", "function": t} for t in tools
+            ]
+
+        url = f"{self.api_base}/chat/completions"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                async with client.stream("POST", url, json=payload, headers=headers) as resp:
+                    if resp.status_code != 200:
+                        body = (await resp.aread()).decode("utf-8", errors="replace")
+                        status = resp.status_code
+                        retryable, category = _status_retry_policy(
+                            status,
+                            content_type=resp.headers.get("Content-Type", ""),
+                            body=body,
+                        )
+                        raise LlmError(
+                            f"API 返回 {status}: {body[:500]}",
+                            status_code=status,
+                            category=category,
+                            retryable=retryable,
+                            retry_after=_parse_retry_after(resp.headers.get("Retry-After")),
+                            request_id=resp.headers.get("x-request-id", ""),
+                        )
+                    async for event in self._parse_sse(resp):
+                        yield event
+        except httpx.TimeoutException as e:
+            raise LlmError(
+                f"请求超时（{self.timeout}s）: {e}",
+                category="network_timeout", retryable=True,
+            ) from e
+        except httpx.HTTPError as e:
+            raise LlmError(
+                f"网络错误: {e}", category="network_error", retryable=True,
+            ) from e
+
+    async def _parse_sse(self, resp: httpx.Response) -> AsyncIterator[StreamEvent]:
+        """解析 SSE 流，聚合 content 与 tool_call 增量分片。"""
+        # 按 index 聚合中的 tool_call 分片
+        pending: dict[int, dict[str, str]] = {}
+        finish_reason = ""
+        usage: Usage | None = None
+
+        async for line in resp.aiter_lines():
+            line = line.strip()
+            if not line.startswith("data:"):
+                continue
+            data = line[len("data:") :].strip()
+            if data == "[DONE]":
+                break
+            try:
+                chunk = json.loads(data)
+            except json.JSONDecodeError:
+                continue
+
+            if chunk.get("usage"):
+                u = chunk["usage"]
+                usage = Usage(
+                    prompt_tokens=u.get("prompt_tokens", 0),
+                    completion_tokens=u.get("completion_tokens", 0),
+                    total_tokens=u.get("total_tokens", 0),
+                )
+
+            for choice in chunk.get("choices", []):
+                delta = choice.get("delta") or {}
+                # 不同 OpenAI-compatible provider 对显式 reasoning 的字段名
+                # 不统一；在 LLM 边界归一化，UI 不读取 provider 私有字段。
+                reasoning = delta.get("reasoning_content") or delta.get("reasoning")
+                if reasoning:
+                    yield StreamEvent(kind="thinking", text=str(reasoning))
+                if delta.get("content"):
+                    yield StreamEvent(kind="content", text=delta["content"])
+
+                for tc in delta.get("tool_calls") or []:
+                    idx = tc.get("index", 0)
+                    frag = pending.setdefault(idx, {"id": "", "name": "", "arguments": ""})
+                    if tc.get("id"):
+                        frag["id"] = tc["id"]
+                    fn = tc.get("function") or {}
+                    if fn.get("name"):
+                        frag["name"] = frag["name"] + fn["name"]
+                    if fn.get("arguments"):
+                        frag["arguments"] = frag["arguments"] + fn["arguments"]
+
+                if choice.get("finish_reason"):
+                    finish_reason = choice["finish_reason"]
+
+        # 流结束：统一发出聚合后的 tool_call，再发 done
+        for idx in sorted(pending):
+            frag = pending[idx]
+            if not frag["name"] and not frag["arguments"]:
+                continue
+            yield StreamEvent(
+                kind="tool_call",
+                tool_call=ToolCall(
+                    id=frag["id"] or f"call_{idx}",
+                    name=frag["name"],
+                    arguments=frag["arguments"],
+                ),
+            )
+        yield StreamEvent(kind="done", finish_reason=finish_reason, usage=usage)

xg/llm/types.py

@@ -0,0 +1,98 @@
+"""LLM 层通用类型：消息、工具调用、流式事件。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class ToolCall:
+    """一次工具调用请求（模型侧发起）。"""
+
+    id: str
+    name: str
+    arguments: str  # JSON 字符串
+
+    def parsed_arguments(self) -> dict[str, Any]:
+        import json
+
+        if not self.arguments:
+            return {}
+        try:
+            return json.loads(self.arguments)
+        except json.JSONDecodeError:
+            return {"_raw": self.arguments}
+
+
+@dataclass
+class ToolResult:
+    """一次工具执行结果（工具侧返回，回灌给模型）。"""
+
+    tool_call_id: str
+    name: str
+    ok: bool
+    output: str = ""
+    error: str = ""
+
+    def to_message_content(self) -> str:
+        if self.ok:
+            return self.output or "(no output)"
+        return f"ERROR: {self.error or 'unknown error'}"
+
+
+@dataclass
+class Message:
+    """对话消息。role ∈ system / user / assistant / tool。"""
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str = ""  # role=tool 时对应的调用 id
+
+    def to_api(self) -> dict[str, Any]:
+        """转为 OpenAI Chat Completions API 格式。"""
+        msg: dict[str, Any] = {"role": self.role}
+        if self.role == "assistant" and self.tool_calls:
+            msg["content"] = self.content or None
+            msg["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {"name": tc.name, "arguments": tc.arguments},
+                }
+                for tc in self.tool_calls
+            ]
+        elif self.role == "tool":
+            msg["content"] = self.content
+            msg["tool_call_id"] = self.tool_call_id
+        else:
+            msg["content"] = self.content
+        return msg
+
+
+@dataclass
+class Usage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+@dataclass
+class StreamEvent:
+    """流式事件。
+
+    - kind="content": text 为普通/最终回答增量文本
+    - kind="thinking": text 为 Provider 明确返回的思考增量文本
+    - kind="tool_call": tool_call 为本轮聚合完成的 ToolCall（一次性发出，不再分片）
+    - kind="done": 结束，含 finish_reason 与 usage
+    """
+
+    kind: Literal["content", "thinking", "tool_call", "done", "retrying"]
+    text: str = ""
+    tool_call: ToolCall | None = None
+    finish_reason: str = ""
+    usage: Usage | None = None
+    attempt: int = 0
+    max_attempts: int = 0
+    retry_after: float | None = None

xg/mcp/__init__.py

@@ -0,0 +1,4 @@
+"""MCP client runtime: transports, discovery, tools and resources."""
+
+# Keep package initialization dependency-free.  The configuration layer uses
+# xg.mcp.models and must not recursively import the runtime manager.

xg/mcp/http.py

@@ -0,0 +1,192 @@
+"""MCP Streamable HTTP transport using httpx."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from contextlib import suppress
+from typing import AsyncIterator
+
+import httpx
+
+from xg.mcp.models import McpServerConfig
+from xg.mcp.protocol import McpProtocolError, McpRequestError, McpUnavailableError, notification_message, request_message
+from xg.mcp.transport import McpTransport
+from xg.safety.audit import redact_text
+
+
+class StreamableHttpTransport(McpTransport):
+    def __init__(self, config: McpServerConfig, client: httpx.AsyncClient | None = None) -> None:
+        super().__init__(log_lines=config.log_lines)
+        self.config = config
+        self._external_client = client is not None
+        self.client = client
+        self.session_id: str | None = None
+        self._next_id = 1
+        self._notification_task: asyncio.Task | None = None
+        self._closed = False
+
+    async def connect(self) -> None:
+        if self.client is None:
+            self.client = httpx.AsyncClient(
+                timeout=httpx.Timeout(self.config.request_timeout),
+                follow_redirects=True,
+                max_redirects=5,
+            )
+        self._closed = False
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            **dict(self.config.headers),
+        }
+        if self.session_id:
+            headers["Mcp-Session-Id"] = self.session_id
+        if self.protocol_version:
+            headers["MCP-Protocol-Version"] = self.protocol_version
+        return headers
+
+    async def request(self, method: str, params: dict | None = None) -> dict:
+        if self.client is None or self._closed or not self.config.url:
+            raise McpUnavailableError("MCP HTTP Server 未连接")
+        request_id = self._next_id
+        self._next_id += 1
+        response = await self._post(request_message(request_id, method, params))
+        messages = await self._messages(response)
+        for message in messages:
+            if message.get("id") == request_id:
+                error = message.get("error")
+                if isinstance(error, dict):
+                    raise McpRequestError(error.get("code", -32000), str(error.get("message", "unknown error")), error.get("data"))
+                result = message.get("result", {})
+                if result is None:
+                    return {}
+                if not isinstance(result, dict):
+                    raise McpProtocolError("JSON-RPC result 必须是对象")
+                return result
+            await self._dispatch_unsolicited(message)
+        raise McpProtocolError(f"MCP HTTP 响应缺少 request id {request_id}")
+
+    async def notify(self, method: str, params: dict | None = None) -> None:
+        response = await self._post(notification_message(method, params))
+        if response.status_code not in (200, 202, 204):
+            raise McpUnavailableError(f"MCP HTTP notification 失败: HTTP {response.status_code}")
+        if response.content:
+            for message in await self._messages(response):
+                await self._dispatch_unsolicited(message)
+
+    async def _post(self, payload: dict) -> httpx.Response:
+        assert self.client is not None and self.config.url
+        encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        if len(encoded) > self.config.max_message_bytes:
+            raise McpProtocolError("JSON-RPC 请求超过消息上限")
+        try:
+            response = await self.client.post(self.config.url, headers=self._headers(), content=encoded)
+        except httpx.TimeoutException as exc:
+            raise McpUnavailableError("MCP HTTP 请求超时") from exc
+        except httpx.HTTPError as exc:
+            raise McpUnavailableError(f"MCP HTTP 连接失败: {exc}") from exc
+        if response.status_code >= 400:
+            preview = redact_text(response.text[:300].replace("\n", " "))
+            raise McpUnavailableError(f"MCP HTTP {response.status_code}: {preview}")
+        session_id = response.headers.get("mcp-session-id")
+        if session_id:
+            self.session_id = session_id
+        if len(response.content) > self.config.max_message_bytes:
+            raise McpProtocolError("MCP HTTP 响应超过消息上限")
+        return response
+
+    async def _messages(self, response: httpx.Response) -> list[dict]:
+        if not response.content:
+            return []
+        content_type = response.headers.get("content-type", "").lower()
+        raw_messages: list[object]
+        if "text/event-stream" in content_type:
+            raw_messages = []
+            data_lines: list[str] = []
+            for line in response.text.splitlines():
+                if line.startswith("data:"):
+                    data_lines.append(line[5:].lstrip())
+                elif not line and data_lines:
+                    raw_messages.append(json.loads("\n".join(data_lines)))
+                    data_lines = []
+            if data_lines:
+                raw_messages.append(json.loads("\n".join(data_lines)))
+        else:
+            try:
+                parsed = response.json()
+            except (ValueError, json.JSONDecodeError) as exc:
+                raise McpProtocolError(f"MCP HTTP 返回非法 JSON: {exc}") from exc
+            raw_messages = parsed if isinstance(parsed, list) else [parsed]
+        messages: list[dict] = []
+        for item in raw_messages:
+            if not isinstance(item, dict) or item.get("jsonrpc") != "2.0":
+                raise McpProtocolError("MCP HTTP 返回非法 JSON-RPC envelope")
+            messages.append(item)
+        return messages
+
+    async def _dispatch_unsolicited(self, message: dict) -> None:
+        method = message.get("method")
+        if isinstance(method, str) and "id" not in message:
+            await self.dispatch_notification(method, message.get("params"))
+        elif isinstance(method, str) and "id" in message:
+            response = (
+                {"jsonrpc": "2.0", "id": message["id"], "result": {}}
+                if method == "ping"
+                else {
+                    "jsonrpc": "2.0",
+                    "id": message["id"],
+                    "error": {"code": -32601, "message": "Method not found"},
+                }
+            )
+            await self._post(response)
+
+    async def start_notifications(self) -> None:
+        if self._notification_task is None and self.client is not None and self.session_id:
+            self._notification_task = asyncio.create_task(
+                self._listen_notifications(), name=f"mcp-{self.config.name}-http-events"
+            )
+
+    async def _listen_notifications(self) -> None:
+        assert self.client is not None and self.config.url
+        try:
+            async with self.client.stream("GET", self.config.url, headers=self._headers()) as response:
+                if response.status_code in (405, 404):
+                    return
+                response.raise_for_status()
+                data_lines: list[str] = []
+                async for line in response.aiter_lines():
+                    if line.startswith("data:"):
+                        data_lines.append(line[5:].lstrip())
+                    elif not line and data_lines:
+                        raw = "\n".join(data_lines)
+                        data_lines = []
+                        if len(raw.encode("utf-8")) > self.config.max_message_bytes:
+                            self.log("notification message exceeds limit")
+                            continue
+                        message = json.loads(raw)
+                        if isinstance(message, dict):
+                            await self._dispatch_unsolicited(message)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            if not self._closed:
+                self.log(f"notification stream closed: {type(exc).__name__}: {exc}")
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        task = self._notification_task
+        if task is not None and not task.done():
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+        if self.client is not None and self.config.url and self.session_id:
+            with suppress(httpx.HTTPError):
+                await self.client.delete(self.config.url, headers=self._headers())
+        self.session_id = None
+        if self.client is not None and not self._external_client:
+            await self.client.aclose()
+            self.client = None