vox-code 2.0.0__py3-none-any.whl

voxcli/llm/openai_compatible.py

@@ -0,0 +1,249 @@
+"""OpenAI 兼容 API 客户端（支持 SSE 流式）"""
+
+import base64
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+from ..chat import SUPPORTED_IMAGE_MIME_TYPES
+from .base import (
+    LlmClient, Message, ChatResponse, ToolCall, ToolDef,
+    StreamListener, STREAM_LISTENER_NOOP,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAiCompatibleClient(LlmClient):
+    def __init__(self, api_key: str, model: str, base_url: str, provider_name: str,
+                 timeout: float = 300.0):
+        self._api_key = api_key
+        self._model = model
+        self._base_url = base_url
+        self._provider_name = provider_name
+        # Use certifi if available for better SSL compat (macOS system Python)
+        try:
+            import certifi
+            verify = certifi.where()
+        except ImportError:
+            verify = True
+        self._http = httpx.Client(timeout=httpx.Timeout(timeout, connect=60.0), verify=verify)
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    @property
+    def provider_name(self) -> str:
+        return self._provider_name
+
+    @property
+    def supports_image_inputs(self) -> bool:
+        return True
+
+    def _encode_image_attachment(self, attachment) -> dict:
+        file_path = Path(attachment.file_path)
+        if attachment.mime_type not in SUPPORTED_IMAGE_MIME_TYPES:
+            raise ValueError(
+                f"仅支持 png/jpg/jpeg/webp 图片，当前文件不受支持: {attachment.display_name}"
+            )
+        if not file_path.exists():
+            raise FileNotFoundError(f"图片不存在: {file_path}")
+        if not file_path.is_file():
+            raise ValueError(f"不是有效的图片文件: {file_path}")
+        try:
+            data = file_path.read_bytes()
+        except OSError as exc:
+            raise RuntimeError(f"读取图片失败: {attachment.display_name}: {exc}") from exc
+        try:
+            encoded = base64.b64encode(data).decode("ascii")
+        except Exception as exc:
+            raise RuntimeError(f"图片编码失败: {attachment.display_name}: {exc}") from exc
+        return {
+            "type": "image_url",
+            "image_url": {
+                "url": f"data:{attachment.mime_type};base64,{encoded}",
+            },
+        }
+
+    def _build_message_content(self, message: Message):
+        if not message.attachments:
+            return message.content
+
+        blocks: list[dict] = []
+        text = message.content or ""
+        if text:
+            blocks.append({"type": "text", "text": text})
+        for attachment in message.attachments:
+            blocks.append(self._encode_image_attachment(attachment))
+        return blocks
+
+    def _build_request(self, messages: list[Message],
+                       tools: Optional[list[ToolDef]] = None) -> dict:
+        body = {
+            "model": self._model,
+            "stream": True,
+            "messages": [],
+        }
+        allow_reasoning_content = self._provider_name not in {"deepseek", "qwen"}
+        for msg in messages:
+            m: dict = {"role": msg.role}
+            content = self._build_message_content(msg)
+            if content is not None:
+                m["content"] = content
+            if allow_reasoning_content and msg.reasoning_content:
+                m["reasoning_content"] = msg.reasoning_content
+            if msg.tool_calls:
+                m["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {"name": tc.name, "arguments": tc.arguments},
+                    }
+                    for tc in msg.tool_calls
+                ]
+            if msg.tool_call_id:
+                m["tool_call_id"] = msg.tool_call_id
+            if msg.role == "assistant" and msg.tool_calls and "content" not in m:
+                m["content"] = ""
+            if msg.role == "tool" and "content" not in m:
+                m["content"] = ""
+            body["messages"].append(m)
+
+        if tools:
+            body["tools"] = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.parameters,
+                    },
+                }
+                for t in tools
+            ]
+        return body
+
+    @staticmethod
+    def _merge_tool_calls(acc: dict[int, dict], tool_calls_delta: list[dict]):
+        for tc in tool_calls_delta:
+            idx = tc.get("index", len(acc))
+            if idx not in acc:
+                acc[idx] = {"id": "", "name": "", "arguments": ""}
+            if tc.get("id"):
+                acc[idx]["id"] = tc["id"]
+            fn = tc.get("function", {})
+            if fn.get("name"):
+                acc[idx]["name"] = fn["name"]
+            if fn.get("arguments"):
+                acc[idx]["arguments"] += fn["arguments"]
+
+    @staticmethod
+    def _build_tool_calls(acc: dict[int, dict]) -> list[ToolCall]:
+        if not acc:
+            return []
+        result = []
+        for idx in sorted(acc.keys()):
+            entry = acc[idx]
+            if not entry["id"]:
+                continue
+            result.append(ToolCall(
+                id=entry["id"],
+                name=entry["name"],
+                arguments=entry["arguments"],
+            ))
+        return result
+
+    def chat(self, messages: list[Message], tools: Optional[list[ToolDef]] = None,
+             listener: StreamListener = STREAM_LISTENER_NOOP) -> ChatResponse:
+        body = self._build_request(messages, tools)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+        }
+
+        def clean(obj):
+            if isinstance(obj, str):
+                return obj.encode("utf-8", "surrogatepass").decode("utf-8", "ignore")
+            elif isinstance(obj, dict):
+                return {k: clean(v) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [clean(i) for i in obj]
+            return obj
+
+        body = clean(body)
+
+        json_data = json.dumps(body, ensure_ascii=False).encode("utf-8", "ignore")
+
+        response = self._http.post(
+            self._base_url,
+            content=json_data,
+            headers=headers
+        )
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = response.text.strip()
+            if detail:
+                raise RuntimeError(
+                    f"{self._provider_name} 接口报错 {response.status_code}: {detail}"
+                ) from exc
+            raise
+
+        content_parts: list[str] = []
+        reasoning_parts: list[str] = []
+        tool_calls_acc: dict[int, dict] = {}
+        input_tokens = output_tokens = 0
+
+        for line in response.iter_lines():
+            line = line.strip()
+            if not line or not line.startswith("data:"):
+                continue
+            payload = line[5:].strip()
+            if not payload or payload == "[DONE]":
+                break
+
+            try:
+                chunk = json.loads(payload)
+            except json.JSONDecodeError:
+                continue
+
+            usage = chunk.get("usage")
+            if usage:
+                input_tokens = usage.get("prompt_tokens", input_tokens)
+                output_tokens = usage.get("completion_tokens", output_tokens)
+
+            choices = chunk.get("choices", [])
+            if not choices:
+                continue
+            delta = choices[0].get("delta", {})
+
+            rdelta = delta.get("reasoning_content", "")
+            if rdelta:
+                reasoning_parts.append(rdelta)
+                listener.on_reasoning_delta(rdelta)
+
+            cdelta = delta.get("content", "")
+            if cdelta:
+                content_parts.append(cdelta)
+                listener.on_content_delta(cdelta)
+
+            tool_calls_delta = delta.get("tool_calls")
+            if tool_calls_delta:
+                self._merge_tool_calls(tool_calls_acc, tool_calls_delta)
+
+        tool_calls = self._build_tool_calls(tool_calls_acc)
+
+        return ChatResponse(
+            role="assistant",
+            content="".join(content_parts) or None,
+            reasoning_content="".join(reasoning_parts) or None,
+            tool_calls=tool_calls or None,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+        )

voxcli/memory/base.py

@@ -0,0 +1,16 @@
+"""记忆接口"""
+
+from typing import List, Optional, Protocol
+
+from .entry import MemoryEntry
+
+
+class Memory(Protocol):
+    def store(self, entry: MemoryEntry): ...
+    def retrieve(self, id: str) -> Optional[MemoryEntry]: ...
+    def search(self, query: str, limit: int) -> List[MemoryEntry]: ...
+    def get_all(self) -> List[MemoryEntry]: ...
+    def delete(self, id: str) -> bool: ...
+    def clear(self): ...
+    def token_count(self) -> int: ...
+    def size(self) -> int: ...

voxcli/memory/budget.py

@@ -0,0 +1,53 @@
+"""Token 预算管理器"""
+
+from typing import List
+
+from .entry import estimate_tokens
+from .short_term import ConversationMemory
+from ..llm.base import Message
+
+
+class TokenBudget:
+    def __init__(self, context_window: int = 200000,
+                 reserved_for_system: int = 500,
+                 reserved_for_tools: int = 800,
+                 reserved_for_response: int = 2000):
+        self._context_window = context_window
+        self._reserved_for_system = reserved_for_system
+        self._reserved_for_tools = reserved_for_tools
+        self._reserved_for_response = reserved_for_response
+        self._total_input = 0
+        self._total_output = 0
+        self._call_count = 0
+
+    @property
+    def available_for_conversation(self) -> int:
+        return self._context_window - self._reserved_for_system - self._reserved_for_tools - self._reserved_for_response
+
+    def needs_compression(self, memory: ConversationMemory) -> bool:
+        compression_budget = min(memory.max_tokens, self.available_for_conversation)
+        return memory.token_count() >= compression_budget * 0.8
+
+    def record_usage(self, input_tokens: int, output_tokens: int):
+        self._total_input += input_tokens
+        self._total_output += output_tokens
+        self._call_count += 1
+
+    @property
+    def usage_report(self) -> str:
+        avg = self._total_input / self._call_count if self._call_count > 0 else 0
+        return (f"Token 统计: 调用 {self._call_count} 次 | "
+                f"总输入: {self._total_input} | 总输出: {self._total_output} | "
+                f"平均输入: {avg:.0f} | 预算: {self._context_window}")
+
+    @staticmethod
+    def estimate_messages_tokens(messages: List[Message]) -> int:
+        total = 0
+        for msg in messages:
+            if msg.content:
+                total += estimate_tokens(msg.content)
+            if msg.tool_calls:
+                for tc in msg.tool_calls:
+                    total += estimate_tokens(tc.arguments)
+        total += len(messages) * 4
+        return total

voxcli/memory/compressor.py

@@ -0,0 +1,198 @@
+"""上下文压缩器"""
+
+import logging
+import uuid
+from typing import List, Optional
+
+from .entry import MemoryEntry, MemoryType, estimate_tokens
+from .short_term import ConversationMemory
+from .long_term import LongTermMemory
+from ..llm.base import LlmClient, Message
+
+logger = logging.getLogger(__name__)
+
+_MAP_PROMPT = """请将以下对话片段压缩成一段简洁的摘要，保留关键信息：
+- 用户的需求和意图
+- 已执行的操作和结果
+- 做出的决策和结论
+- 重要的技术细节
+
+对话片段：
+%s
+
+请用中文输出摘要，控制在200字以内。"""
+
+_REDUCE_PROMPT = """请将以下多个摘要合并成一个整体摘要，保留所有关键信息。
+
+各片段摘要：
+%s
+
+请用中文输出合并摘要，控制在300字以内。"""
+
+_EXTRACT_FACTS_PROMPT = """请从以下对话中提取"跨会话仍然成立、未来复用仍有价值"的稳定事实，格式为每行一条：
+- 用户偏好和习惯
+- 项目信息（名称、路径、技术栈）
+- 重要决策和约定
+
+只保留用户明确说明、或工具/代码库可验证的信息。
+绝对不要提取以下内容：
+- 当前这一轮让你执行的临时任务、步骤、todo
+- 一次性的文件名、目录名、输出要求
+- 模型自己的猜测、纠错、提醒、推断
+- "用户想要/需要/让我/请你..." 这类请求句
+
+对话内容：
+%s
+
+请每行一条事实，不要多余解释。"""
+
+_EPHEMERAL_PREFIXES = ["用户想", "用户要", "用户需要", "用户请求", "帮我", "让我",
+                        "新建", "创建", "删除", "修改", "生成", "补充要求", "当前这一轮", "本次任务"]
+_SPECULATION_CUES = ["可能", "应该", "猜测", "推测", "笔误", "提醒"]
+_DURABLE_HINTS = ["用户偏好", "用户习惯", "喜欢", "倾向", "项目", "仓库", "路径", "技术栈",
+                   "版本", "模型", "接口", "配置", "环境变量", "命令", "约定", "规则", "默认"]
+
+
+class ContextCompressor:
+    def __init__(self, llm_client: LlmClient, retain_recent_rounds: int = 3):
+        self._llm = llm_client
+        self._retain = retain_recent_rounds
+
+    def set_llm_client(self, llm_client: LlmClient):
+        self._llm = llm_client
+
+    def compress(self, memory: ConversationMemory) -> Optional[str]:
+        all_entries = memory.get_all()
+        if len(all_entries) <= self._retain:
+            return None
+
+        split = len(all_entries) - self._retain
+        old = list(all_entries[:split])
+        recent = list(all_entries[split:])
+
+        chunk_summaries = self._map_phase(old)
+        if not chunk_summaries:
+            return None
+
+        final_summary = (chunk_summaries[0] if len(chunk_summaries) == 1
+                         else self._reduce_phase(chunk_summaries))
+
+        memory.clear()
+        summary_entry = MemoryEntry(
+            id=f"summary-{uuid.uuid4().hex[:8]}",
+            content=f"[历史对话摘要] {final_summary}",
+            type=MemoryType.SUMMARY,
+        )
+        memory.store(summary_entry)
+        for entry in recent:
+            memory.store(entry)
+
+        return final_summary
+
+    def extract_facts(self, entries: List[MemoryEntry],
+                      long_term: LongTermMemory) -> List[str]:
+        if not entries:
+            return []
+
+        conversation = "\n".join(
+            f"{self._resolve_source(e)}({e.type.value}): {e.content}"
+            for e in entries
+        )
+
+        try:
+            prompt = _EXTRACT_FACTS_PROMPT % conversation
+            resp = self._llm.chat([
+                Message.system("你是一个信息提取助手，只输出关键事实，不输出其他内容。"),
+                Message.user(prompt),
+            ])
+            facts_text = resp.content or ""
+
+            facts = []
+            for line in facts_text.split("\n"):
+                fact = self._normalize_fact(line)
+                if self._is_persistent_fact(fact):
+                    facts.append(fact)
+                    entry = MemoryEntry(
+                        id=f"fact-{uuid.uuid4().hex[:8]}",
+                        content=fact,
+                        type=MemoryType.FACT,
+                        metadata={"source": "fact_extractor"},
+                    )
+                    long_term.store(entry)
+            return facts
+        except Exception as e:
+            logger.warning("事实提取失败: %s", e)
+            return []
+
+    def _map_phase(self, entries: List[MemoryEntry]) -> List[str]:
+        summaries = []
+        chunk_size = 5
+        for i in range(0, len(entries), chunk_size):
+            chunk = entries[i:i + chunk_size]
+            chunk_text = "\n".join(
+                f"{e.type.value}: {e.content}" for e in chunk
+            )
+            try:
+                prompt = _MAP_PROMPT % chunk_text
+                resp = self._llm.chat([
+                    Message.system("你是一个对话摘要助手。"),
+                    Message.user(prompt),
+                ])
+                summaries.append(resp.content or "")
+            except Exception as e:
+                logger.warning("摘要生成失败: %s", e)
+                summaries.append(f"[压缩] {chunk_text[:200]}")
+        return summaries
+
+    def _reduce_phase(self, summaries: List[str]) -> str:
+        joined = "\n\n---\n\n".join(summaries)
+        try:
+            prompt = _REDUCE_PROMPT % joined
+            resp = self._llm.chat([
+                Message.system("你是一个摘要合并助手。"),
+                Message.user(prompt),
+            ])
+            return resp.content or "；".join(summaries)
+        except Exception as e:
+            logger.warning("摘要合并失败: %s", e)
+            return "；".join(summaries)
+
+    @staticmethod
+    def _resolve_source(entry: MemoryEntry) -> str:
+        src = entry.metadata.get("source", "")
+        if src:
+            return src
+        if entry.id.startswith("user-"):
+            return "user"
+        if entry.id.startswith("assistant-"):
+            return "assistant"
+        if entry.id.startswith("tool-"):
+            return "tool"
+        return "unknown"
+
+    @staticmethod
+    def _normalize_fact(line: str) -> str:
+        fact = (line or "").strip()
+        if fact.startswith("- "):
+            fact = fact[2:]
+        elif fact.startswith("• "):
+            fact = fact[2:]
+        return fact.strip()
+
+    @staticmethod
+    def _is_persistent_fact(fact: str) -> bool:
+        if not fact or len(fact) <= 5:
+            return False
+        normalized = fact.lower()
+        for p in _EPHEMERAL_PREFIXES:
+            if normalized.startswith(p.lower()):
+                return False
+        for c in _SPECULATION_CUES:
+            if c in normalized:
+                return False
+        if "：" in fact or ":" in fact:
+            return True
+        for h in _DURABLE_HINTS:
+            if h in normalized:
+                return True
+        return False

voxcli/memory/entry.py

@@ -0,0 +1,36 @@
+"""记忆条目"""
+
+import math
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class MemoryType(Enum):
+    CONVERSATION = "conversation"
+    FACT = "fact"
+    SUMMARY = "summary"
+    TOOL_RESULT = "tool_result"
+
+
+@dataclass
+class MemoryEntry:
+    id: str
+    content: str
+    type: MemoryType
+    metadata: dict = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+    token_count: int = 0
+
+    def __post_init__(self):
+        if self.token_count <= 0 and self.content:
+            self.token_count = estimate_tokens(self.content)
+
+
+def estimate_tokens(text: Optional[str]) -> int:
+    if not text:
+        return 0
+    chinese = sum(1 for c in text if '一' <= c <= '鿿')
+    other = len(text) - chinese
+    return math.ceil(chinese / 1.5 + other / 4.0)

voxcli/memory/long_term.py

@@ -0,0 +1,126 @@
+"""长期记忆 - 跨对话持久化的关键信息"""
+
+import json
+import os
+from pathlib import Path
+from typing import List, Optional
+
+from .base import Memory
+from .entry import MemoryEntry, MemoryType
+from .tokenizer import matches, tokenize
+
+
+_STORAGE_FILE = "long_term_memory.json"
+
+
+def _storage_dir() -> Path:
+    env_dir = os.environ.get("VOX_CODE_MEMORY_DIR", "")
+    if env_dir.strip():
+        return Path(env_dir.strip())
+    return Path.home() / ".vox-code" / "memory"
+
+
+class LongTermMemory(Memory):
+    def __init__(self):
+        self._entries: dict[str, MemoryEntry] = {}
+        self._token_counter = 0
+        self._storage_file = _storage_dir() / _STORAGE_FILE
+        self._load_from_disk()
+
+    def store(self, entry: MemoryEntry):
+        if any(e.content == entry.content for e in self._entries.values()):
+            return
+        self._entries[entry.id] = entry
+        self._token_counter += entry.token_count
+        self._save_to_disk()
+
+    def retrieve(self, id: str) -> Optional[MemoryEntry]:
+        return self._entries.get(id)
+
+    def search(self, query: str, limit: int) -> List[MemoryEntry]:
+        query_tokens = tokenize(query)
+        results = []
+        for entry in self._entries.values():
+            if matches(entry.content, query_tokens):
+                results.append(entry)
+            elif any(matches(v, query_tokens) for v in entry.metadata.values()):
+                results.append(entry)
+            if len(results) >= limit:
+                break
+        return results
+
+    def get_all(self) -> List[MemoryEntry]:
+        return list(self._entries.values())
+
+    def delete(self, id: str) -> bool:
+        entry = self._entries.pop(id, None)
+        if entry:
+            self._token_counter -= entry.token_count
+            self._save_to_disk()
+            return True
+        return False
+
+    def clear(self):
+        self._entries.clear()
+        self._token_counter = 0
+        self._save_to_disk()
+
+    def token_count(self) -> int:
+        return self._token_counter
+
+    def size(self) -> int:
+        return len(self._entries)
+
+    def get_by_type(self, type_: MemoryType) -> List[MemoryEntry]:
+        return [e for e in self._entries.values() if e.type == type_]
+
+    def status_summary(self) -> str:
+        type_counts = {}
+        for e in self._entries.values():
+            type_counts[e.type] = type_counts.get(e.type, 0) + 1
+        return (f"长期记忆: {self.size()}条 / {self._token_counter} tokens "
+                f"(事实: {type_counts.get(MemoryType.FACT, 0)}, "
+                f"摘要: {type_counts.get(MemoryType.SUMMARY, 0)}, "
+                f"工具结果: {type_counts.get(MemoryType.TOOL_RESULT, 0)})")
+
+    def _save_to_disk(self):
+        try:
+            self._storage_file.parent.mkdir(parents=True, exist_ok=True)
+            data = [
+                {
+                    "id": e.id, "content": e.content,
+                    "type": e.type.value,
+                    "timestamp": e.timestamp,
+                    "metadata": e.metadata,
+                    "tokenCount": e.token_count,
+                }
+                for e in self._entries.values()
+            ]
+            self._storage_file.write_text(
+                json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+        except OSError as e:
+            print(f"⚠️ 长期记忆持久化失败: {e}")
+
+    def _load_from_disk(self):
+        if not self._storage_file.exists():
+            return
+        try:
+            data = json.loads(self._storage_file.read_text(encoding="utf-8"))
+            for item in data:
+                entry = MemoryEntry(
+                    id=item["id"],
+                    content=item["content"],
+                    type=MemoryType(item["type"]),
+                    metadata=item.get("metadata", {}),
+                    timestamp=item.get("timestamp", 0),
+                    token_count=item.get("tokenCount", 0),
+                )
+                if entry.token_count <= 0:
+                    from .entry import estimate_tokens
+                    entry.token_count = estimate_tokens(entry.content)
+                self._entries[entry.id] = entry
+                self._token_counter += entry.token_count
+            print(f"📂 加载了 {len(self._entries)} 条长期记忆")
+        except Exception as e:
+            print(f"⚠️ 加载长期记忆失败: {e}")