zero-agent-core 0.2.0__py3-none-any.whl

agent_core/compaction/region.py

@@ -0,0 +1,145 @@
+"""压缩范围选择：尾部保留预算 + 工具配对平衡边界（纯函数，无 IO）。
+
+这一层是整个压缩策略里最需要正确性的部分：一旦切点落在
+"assistant 发了 tool_call，但它的 tool 结果还在切点之后"的位置，
+被压头部就会留下没有结果的 tool_call、尾部会以孤儿 tool 消息开头，
+两者都会让模型接口直接返回 400。因此这里用纯函数把边界算法固定下来，
+不依赖网络即可充分单测。
+"""
+
+from __future__ import annotations
+
+import json
+
+from agent_core.compaction.types import (
+    SUMMARY_CLOSE,
+    SUMMARY_OPEN,
+    SUMMARY_SOURCE,
+)
+from agent_core.protocol.messages import Message
+
+# checkpoint 消息的固定前言：明确告诉模型这是既定背景，继续任务、不要回应
+CHECKPOINT_PREAMBLE = (
+    "这是系统自动生成的早期对话检查点，用于释放上下文空间。"
+    "请把它当作既定背景直接使用，从其后的消息继续任务，"
+    "不要重述、不要回应、也不要提及本检查点。"
+)
+
+
+def estimate_message_tokens(message: Message, *, chars_per_token: int = 4) -> int:
+    """按字符粗估单条消息的 token 数（含工具调用参数）。"""
+    chars = len(message.content or "")
+    for call in message.tool_calls:
+        chars += len(json.dumps(call, ensure_ascii=False))
+    return max(chars // chars_per_token, 1)
+
+
+def estimate_tokens(messages: list[Message], *, chars_per_token: int = 4) -> int:
+    """按字符粗估一组消息的 token 数（用于尾部预算与"是否变小"判断）。"""
+    return sum(estimate_message_tokens(m, chars_per_token=chars_per_token) for m in messages)
+
+
+def balanced_cut(messages: list[Message], proposed_cut: int) -> int:
+    """把初步切点前移到最近的"工具配对平衡边界"。
+
+    平衡的含义：该位置之前所有 assistant 发起的 tool_call，都已经在该
+    位置之前拿到对应 tool 结果（在途调用计数为 0）。这样切出的头部不会
+    遗留无结果的 tool_call，尾部也不会以孤儿 tool 消息开头。
+
+    Args:
+        messages: 完整消息列表。
+        proposed_cut: 按尾部保留预算算出的初步切点（头部条数）。
+
+    Returns:
+        修正后的切点，只可能前移、不会超过 proposed_cut；
+        因此尾部保留量只会 ≥ 预算，不会多压。
+    """
+    limit = max(0, min(proposed_cut, len(messages)))
+    in_flight = 0
+    last_balanced = 0
+    for index, message in enumerate(messages):
+        if message.role == "assistant":
+            in_flight += len(message.tool_calls)
+        elif message.role == "tool":
+            in_flight = max(0, in_flight - 1)
+
+        # index + 1 表示"第 index+1 条之前"这个切口；计数归零即此处平衡
+        if in_flight == 0:
+            last_balanced = index + 1
+        if index + 1 >= limit:
+            break
+
+    return min(last_balanced, limit)
+
+
+def select_cut(
+    messages: list[Message],
+    *,
+    retain_tokens: int,
+    chars_per_token: int = 4,
+) -> int:
+    """从尾部倒序累加 token，返回可压缩头部的条数（切点）。
+
+    Args:
+        messages: 完整消息列表。
+        retain_tokens: 尾部原文保留预算（窗口 × retain_ratio）。
+        chars_per_token: 字符/token 估算比例。
+
+    Returns:
+        初步切点：messages[cut:] 逐字保留，messages[:cut] 待压成摘要。
+        若整段历史都在保留预算内，返回 0（表示没有可压缩的头部）。
+    """
+    retained = 0
+    for index in range(len(messages) - 1, -1, -1):
+        retained += estimate_message_tokens(messages[index], chars_per_token=chars_per_token)
+        if retained >= retain_tokens:
+            return index
+    return 0
+
+
+def extract_previous_summary(messages: list[Message], cut: int) -> str | None:
+    """抽取被压头部里已有的摘要正文（滚动合并的基线）。
+
+    程序靠 ``<compacted-summary>`` 标签认出"上一轮的旧摘要"：它本身就是
+    压缩产物，既不该被当成普通对话再压一遍，也不能拿来跟新摘要比大小。
+
+    Args:
+        messages: 完整消息列表。
+        cut: 压缩边界，只在 messages[:cut] 里找旧摘要。
+
+    Returns:
+        旧摘要正文；头部没有旧摘要（首次压缩）时返回 None。
+    """
+    for message in messages[:cut]:
+        text = message.content or ""
+        start = text.find(SUMMARY_OPEN)
+        end = text.find(SUMMARY_CLOSE)
+        if start >= 0 and end > start:
+            body = text[start + len(SUMMARY_OPEN) : end].strip()
+            if body:
+                return body
+    return None
+
+
+def build_checkpoint(summary_text: str) -> Message:
+    """把摘要正文包装成可写回历史的 checkpoint 消息。
+
+    用 user 角色而非 system：既满足"system 永远只有首条"的约束，
+    又能借前言让模型把摘要当作既定背景而不是新任务。
+    """
+    return Message(
+        role="user",
+        name=SUMMARY_SOURCE,
+        content=f"{CHECKPOINT_PREAMBLE}\n\n{SUMMARY_OPEN}\n{summary_text}\n{SUMMARY_CLOSE}",
+    )
+
+
+def rebuild(
+    messages: list[Message],
+    cut: int,
+    checkpoint: Message,
+) -> list[Message]:
+    """用 checkpoint 替换头部：system + checkpoint + 尾部原文。"""
+    system_messages = [m for m in messages if m.role == "system"]
+    tail = [m for m in messages[cut:] if m.role != "system"]
+    return [*system_messages, checkpoint, *tail]

agent_core/compaction/spill.py

@@ -0,0 +1,81 @@
+"""外置存档（spill）：把被瘦身的完整工具输出存到进程内 KV 存。
+
+瘦身只保留头尾，中间内容被截断。如果模型后续需要完整内容（例如用户
+追问"刚才那个航线列表的第三条详情"），可以通过 ``read_spilled_content``
+工具按 spill_id 回读全文，而不是重新调一次业务接口。
+
+存储是进程内的、按会话隔离的；进程重启后 spill 数据丢失——这在低空
+Agent 场景下可接受：工具输出本就是实时数据，过期后重查比回读旧快照
+更可靠。如果将来需要持久化，把 ``_store`` 换成 Redis / SQLite 即可，
+接口不变。
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import OrderedDict
+from threading import Lock
+
+
+class SpillStore:
+    """线程安全的进程内 spill 存储（LRU 淘汰，防无界增长）。
+
+    用法:
+        store = SpillStore()
+        spill_id = store.put(big_json_string)
+        # … pruner 把 spill_id 写进瘦身标记 …
+        content = store.get(spill_id)   # 模型通过工具回读
+    """
+
+    def __init__(self, *, max_entries: int = 256, max_chars_per_entry: int = 512 * 1024) -> None:
+        """Args:
+        max_entries: 最多保存多少条 spill；超出 LRU 淘汰最旧的。
+        max_chars_per_entry: 单条 spill 上限（字符），防止一条巨型
+            输出吃掉所有内存；超限的条目不存、只截断标记里不出现 ID。
+        """
+        if max_entries <= 0:
+            raise ValueError("max_entries 必须为正整数")
+        if max_chars_per_entry <= 0:
+            raise ValueError("max_chars_per_entry 必须为正整数")
+        self._store: OrderedDict[str, str] = OrderedDict()
+        self._lock = Lock()
+        self._max_entries = max_entries
+        self._max_chars = max_chars_per_entry
+
+    def put(self, content: str) -> str | None:
+        """存入完整内容，返回 spill_id；内容超限时返回 None（不存）。
+
+        Args:
+            content: 被瘦身的完整工具输出原文。
+
+        Returns:
+            可用于回读的 spill_id；若内容超过 ``max_chars_per_entry``
+            则返回 None，调用方应回退到纯截断标记。
+        """
+        if not content or len(content) > self._max_chars:
+            return None
+        spill_id = f"spill-{uuid.uuid4().hex[:12]}"
+        with self._lock:
+            # LRU：已满则弹出最旧条目
+            while len(self._store) >= self._max_entries:
+                self._store.popitem(last=False)
+            self._store[spill_id] = content
+        return spill_id
+
+    def get(self, spill_id: str) -> str | None:
+        """按 spill_id 回读完整内容；不存在时返回 None。"""
+        with self._lock:
+            content = self._store.get(spill_id)
+            if content is not None:
+                # 命中后移到末尾（LRU 最近使用）
+                self._store.move_to_end(spill_id)
+            return content
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._store)
+
+    def clear(self) -> None:
+        """清空所有 spill 条目。"""
+        with self._lock:
+            self._store.clear()

agent_core/compaction/spill_tool.py

@@ -0,0 +1,42 @@
+"""让 Agent 回读被上下文瘦身截断的完整工具输出。"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agent_core.compaction.spill import SpillStore
+
+logger = logging.getLogger(__name__)
+
+
+def build_spill_tool(spill_store: SpillStore) -> list[dict[str, Any]]:
+    """构造与 ``ToolRegistry`` 兼容的 spill 回读工具定义。"""
+
+    async def read_spilled_content(spill_id: str) -> str:
+        content = spill_store.get(spill_id)
+        if content is None:
+            return f"存档 {spill_id} 不存在或已过期。"
+        logger.info("[Spill] 回读存档 %s（%d 字符）", spill_id, len(content))
+        return content
+
+    return [
+        {
+            "name": "read_spilled_content",
+            "func": read_spilled_content,
+            "description": "回读被瘦身截断的完整工具输出。消息中存在 spill_id 时可调用。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "spill_id": {
+                        "type": "string",
+                        "description": "瘦身标记中的 spill 存档 ID",
+                    }
+                },
+                "required": ["spill_id"],
+            },
+        }
+    ]
+
+
+__all__ = ["build_spill_tool"]

agent_core/compaction/summarizer.py

@@ -0,0 +1,95 @@
+"""压缩摘要调用和结构校验。"""
+
+from __future__ import annotations
+
+import logging
+
+from agent_core.compaction.prompts import (
+    DEFAULT_COMPACTION_INSTRUCTION,
+    DEFAULT_SUMMARY_SECTIONS,
+)
+from agent_core.compaction.types import CompactionError
+from agent_core.model import ModelAdapter
+from agent_core.protocol.messages import Message, user_message
+
+logger = logging.getLogger(__name__)
+
+
+def build_summarization_messages(
+    messages: list[Message],
+    *,
+    cut: int,
+    instruction: str = DEFAULT_COMPACTION_INSTRUCTION,
+) -> list[Message]:
+    """构造摘要调用的输入：原 system + 被压头部 + 末尾压缩指令。
+
+    Args:
+        messages: 压缩前的完整消息列表。
+        cut: 压缩边界，messages[:cut] 为待压缩的头部。
+
+    Returns:
+        用于摘要模型的完整消息列表（system 仍在首位）。
+    """
+    head = messages[:cut]
+    system_messages = [m for m in head if m.role == "system"]
+    body = [m for m in head if m.role != "system"]
+    return [*system_messages, *body, user_message(instruction)]
+
+
+def normalize_summary(
+    text: str,
+    *,
+    sections: tuple[str, ...] = DEFAULT_SUMMARY_SECTIONS,
+) -> str:
+    """校验并规整摘要结构。
+
+    - 一个固定小节都没有 → 返回空串（调用方按失败处理，避免写入无效检查点）；
+    - 只缺部分小节 → 用 (none) 补齐，保证后续轮次的滚动合并有稳定结构。
+    """
+    body = (text or "").strip()
+    if not body:
+        return ""
+
+    present = [name for name in sections if f"## {name}" in body]
+    if not present:
+        return ""
+
+    missing = [name for name in sections if name not in present]
+    if missing:
+        body += "\n\n" + "\n\n".join(f"## {name}\n(none)" for name in missing)
+    return body
+
+
+async def summarize(
+    model: ModelAdapter,
+    messages: list[Message],
+    *,
+    cut: int,
+    max_tokens: int,
+    instruction: str = DEFAULT_COMPACTION_INSTRUCTION,
+    sections: tuple[str, ...] = DEFAULT_SUMMARY_SECTIONS,
+) -> str:
+    """调用摘要模型，把头部旧消息压成结构化检查点文本。
+
+    Args:
+        model: 摘要模型（默认复用主模型，也可换成更便宜的小模型）。
+        messages: 压缩前的完整消息列表。
+        cut: 压缩边界。
+        max_tokens: 摘要生成本身的输出上限。
+
+    Returns:
+        结构化摘要正文（不含 checkpoint 包装）。
+
+    Raises:
+        CompactionError: 调用失败或输出不符合结构要求。
+    """
+    prompt = build_summarization_messages(messages, cut=cut, instruction=instruction)
+    try:
+        response = await model.chat(prompt, max_tokens=max_tokens)
+    except Exception as exc:
+        raise CompactionError(f"摘要模型调用失败：{exc}") from exc
+
+    summary = normalize_summary(response.content or "", sections=sections)
+    if not summary:
+        raise CompactionError("摘要输出不符合结构化要求")
+    return summary

agent_core/compaction/token_limit.py

@@ -0,0 +1,74 @@
+"""上下文长度兜底中间件。
+
+它负责最后一道硬截断；完整的摘要、spill 和恢复逻辑由
+``CompactionMiddleware`` 负责。两者都属于上下文压缩域，不属于基础中间件协议。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from agent_core.middleware.base import Middleware, MiddlewareAction, MiddlewareContext, MiddlewareResult
+from agent_core.protocol.messages import Message
+
+logger = logging.getLogger(__name__)
+
+
+class TokenLimitMiddleware(Middleware):
+    """防止消息历史超出 token 限制。"""
+
+    def __init__(
+        self,
+        max_tokens: int = 4000,
+        chars_per_token: int = 4,
+        keep_messages: int = 10,
+    ) -> None:
+        if max_tokens <= 0:
+            raise ValueError("max_tokens 必须大于 0")
+        if chars_per_token <= 0:
+            raise ValueError("chars_per_token 必须大于 0")
+        if keep_messages < 1:
+            raise ValueError("keep_messages 必须大于 0")
+        self._max_tokens = max_tokens
+        self._chars_per_token = chars_per_token
+        self._keep_messages = keep_messages
+
+    def _estimate_tokens(self, messages: list[Message]) -> int:
+        total = sum(len(message.content) for message in messages if message.content)
+        return total // self._chars_per_token
+
+    def _trim_messages(self, messages: list[Message]) -> list[Message]:
+        """保留 system 消息和最近消息，并避免留下孤儿 tool 结果。"""
+        system_messages = [message for message in messages if message.role == "system"]
+        other_messages = [message for message in messages if message.role != "system"]
+        if len(other_messages) <= self._keep_messages:
+            return system_messages + other_messages
+
+        start = len(other_messages) - self._keep_messages
+        # 工具结果必须和此前的 assistant tool_call 一起保留，否则提供商会拒绝请求。
+        while start > 0 and other_messages[start].role == "tool":
+            start -= 1
+        return system_messages + other_messages[start:]
+
+    async def before_model(self, ctx: MiddlewareContext) -> MiddlewareResult:
+        estimated = self._estimate_tokens(ctx.messages)
+        if estimated <= self._max_tokens:
+            return MiddlewareResult(action=MiddlewareAction.CONTINUE)
+
+        trimmed = self._trim_messages(ctx.messages)
+        new_estimated = self._estimate_tokens(trimmed)
+        logger.warning(
+            "[TokenLimit] 消息历史过长 (%d tokens)，裁剪：%d → %d 条，重新估算 %d tokens",
+            estimated,
+            len(ctx.messages),
+            len(trimmed),
+            new_estimated,
+        )
+        ctx.messages = trimmed
+        return MiddlewareResult(
+            action=MiddlewareAction.MODIFY,
+            data={"messages": trimmed, "trimmed_tokens": estimated - new_estimated},
+        )
+
+
+__all__ = ["TokenLimitMiddleware"]

agent_core/compaction/types.py

@@ -0,0 +1,93 @@
+"""上下文压缩的数据结构与常量。
+
+本模块只放"值对象"，不含任何算法与 IO，便于 region / summarizer /
+middleware 三层共享，也便于单测直接构造。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_core.protocol.messages import Message
+
+# ──────────────────────────────────────────────
+# 标签与来源标记
+# ──────────────────────────────────────────────
+
+# 摘要正文在 checkpoint 消息中的包裹标签；下一轮压缩时靠它识别"旧摘要"
+SUMMARY_OPEN = "<compacted-summary>"
+SUMMARY_CLOSE = "</compacted-summary>"
+
+# 写入 Message.name，便于日志、前端展示与排查时识别自动生成的检查点
+SUMMARY_SOURCE = "compaction_checkpoint"
+
+
+@dataclass(frozen=True)
+class CompactionConfig:
+    """上下文压缩配置。
+
+    Attributes:
+        threshold_ratio: 窗口占用达到该比例即触发压缩。
+        retain_ratio: 压缩后保留的尾部原文比例（占窗口，必须小于阈值）。
+        summary_max_tokens: 摘要生成本身的输出上限。
+        max_retries: 压完仍超阈值的额外压缩轮数（0 表示只压一轮）。
+        max_overflow_retries: 模型报"上下文超长"时的强制压缩重试上限
+            （0 表示不接管该错误，交给上层抛出）。
+        enabled: 总开关，关闭后中间件直接放行。
+        chars_per_token: 无精确计数时的字符/token 估算比例（用于尾部预算
+            与"摘要是否更小"的判断）。
+    """
+
+    threshold_ratio: float = 0.75
+    retain_ratio: float = 0.20
+    summary_max_tokens: int = 2048
+    max_retries: int = 1
+    max_overflow_retries: int = 1
+    enabled: bool = True
+    chars_per_token: int = 4
+
+    def __post_init__(self) -> None:
+        if not 0 < self.threshold_ratio <= 1:
+            raise ValueError(f"compaction threshold_ratio 必须在 (0, 1] 区间，当前 {self.threshold_ratio}")
+        if not 0 < self.retain_ratio < self.threshold_ratio:
+            raise ValueError(
+                "compaction retain_ratio 必须大于 0 且小于 threshold_ratio，"
+                f"当前 retain={self.retain_ratio}, threshold={self.threshold_ratio}"
+            )
+        if self.summary_max_tokens <= 0:
+            raise ValueError("compaction summary_max_tokens 必须为正整数")
+        if self.max_retries < 0:
+            raise ValueError("compaction max_retries 不能为负数")
+        if self.max_overflow_retries < 0:
+            raise ValueError("compaction max_overflow_retries 不能为负数")
+        if self.chars_per_token <= 0:
+            raise ValueError("compaction chars_per_token 必须为正整数")
+
+
+@dataclass
+class CompactionResult:
+    """一次压缩的产出。
+
+    Attributes:
+        compacted: 是否真的替换了消息（False 时 messages 为原列表）。
+        messages: 压缩后的消息列表。
+        before_tokens: 压缩前窗口占用（来自 Provider 的真实计数）。
+        after_tokens: 压缩后窗口占用（按字符估算的缩减量推算）。
+        cut: 被压成摘要的头部条数（压缩边界）。
+        reason: 未压缩或失败原因，供日志与降级事件使用。
+    """
+
+    compacted: bool
+    messages: list[Message]
+    before_tokens: int = 0
+    after_tokens: int = 0
+    cut: int = 0
+    reason: str = ""
+
+
+class CompactionError(RuntimeError):
+    """压缩过程中的可预期失败（摘要调用失败 / 结构不合规 / 未变小）。
+
+    中间件捕获它后返回 CONTINUE，把消息交给后续的硬截断中间件兜底，
+    因此不需要中断主流程。
+    """

agent_core/docs.py

@@ -0,0 +1,15 @@
+"""启动本地文档站（MkDocs）。"""
+
+import subprocess
+import sys
+
+
+def main() -> None:
+    subprocess.run(
+        [sys.executable, "-m", "mkdocs", "serve"],
+        check=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

agent_core/documents/__init__.py

@@ -0,0 +1,23 @@
+"""文档值对象、加载器和文本切分器。"""
+
+from agent_core.documents.loaders import (
+    BlobParser,
+    DocumentLoader,
+    TextBlobParser,
+    TextLoader,
+)
+from agent_core.documents.splitters import RecursiveCharacterTextSplitter, TextSplitter
+from agent_core.documents.types import Blob, Document, DocumentChunk, DocumentLocator
+
+__all__ = [
+    "Blob",
+    "BlobParser",
+    "Document",
+    "DocumentChunk",
+    "DocumentLoader",
+    "DocumentLocator",
+    "RecursiveCharacterTextSplitter",
+    "TextBlobParser",
+    "TextLoader",
+    "TextSplitter",
+]

agent_core/documents/loaders.py

@@ -0,0 +1,79 @@
+"""文档加载和 Blob 解析协议，以及零依赖文本实现。"""
+
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import uuid
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from agent_core.documents.types import Blob, Document, DocumentLocator
+
+
+@runtime_checkable
+class DocumentLoader(Protocol):
+    """把外部资源加载为 Document。"""
+
+    async def load(self) -> list[Document]: ...
+
+    def lazy_load(self) -> AsyncIterator[Document]: ...
+
+
+@runtime_checkable
+class BlobParser(Protocol):
+    """把原始 Blob 解析为一个或多个 Document。"""
+
+    async def parse(self, blob: Blob) -> list[Document]: ...
+
+
+class TextBlobParser:
+    """按指定字符集解析纯文本 Blob。"""
+
+    def __init__(self, encoding: str = "utf-8") -> None:
+        self._encoding = encoding
+
+    async def parse(self, blob: Blob) -> list[Document]:
+        content = blob.data.decode(self._encoding)
+        source_key = blob.source or f"blob:{blob.checksum}"
+        return [
+            Document(
+                document_id=str(uuid.uuid5(uuid.NAMESPACE_URL, f"{source_key}:{blob.checksum}")),
+                content=content,
+                source=blob.source,
+                mime_type=blob.mime_type or "text/plain",
+                metadata={**blob.metadata, "source_checksum": blob.checksum},
+                locator=DocumentLocator(uri=blob.source) if blob.source else None,
+            )
+        ]
+
+
+class TextLoader:
+    """从本地文件加载 UTF 文本，不引入第三方解析库。"""
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        encoding: str = "utf-8",
+        metadata: dict[str, object] | None = None,
+    ) -> None:
+        self._path = Path(path)
+        self._parser = TextBlobParser(encoding)
+        self._metadata = dict(metadata or {})
+
+    async def load(self) -> list[Document]:
+        data = await asyncio.to_thread(self._path.read_bytes)
+        mime_type, _ = mimetypes.guess_type(self._path.name)
+        blob = Blob(
+            data=data,
+            source=str(self._path.resolve()),
+            mime_type=mime_type or "text/plain",
+            metadata=self._metadata,
+        )
+        return await self._parser.parse(blob)
+
+    async def lazy_load(self) -> AsyncIterator[Document]:
+        for document in await self.load():
+            yield document