agstack 2.2.0__tar.gz → 2.3.0__tar.gz

{agstack-2.2.0 → agstack-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 2.2.0
+Version: 2.3.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-2.2.0 → agstack-2.3.0}/agstack/llm/client.py

@@ -14,6 +14,7 @@ from openai.types.chat import ChatCompletionMessageParam
 
 from ..contexts import get_request_id
 from ..exceptions import AppException
+from .hooks import CallMeta, StreamSummary, has_llm_hooks, run_after_call, run_before_call
 
 
 if TYPE_CHECKING:
@@ -207,12 +208,24 @@ class LLMClient:
         model_name = model
         # 内部调用类型标记（vision 经由 chat 转发时传入，不透传给推理后端）
         usage_kind = kwargs.pop("usage_kind", "chat")
+        # 调用方附带给 LLM 钩子的上下文（Agent 传 agent / turn / retry / context），不透传给推理后端
+        hook_extra: dict[str, Any] = kwargs.pop("hook_meta", None) or {}
+        stream_kind = "chat_stream" if usage_kind == "chat" else usage_kind
+        meta = CallMeta(
+            model=model_name,
+            kind=stream_kind if stream else usage_kind,
+            stream=stream,
+            request_id=get_request_id(),
+            extra=hook_extra,
+        )
+        # F6 before 链：请求发出前改写消息；钩子异常即失败（fail closed），不包进 LLMError 以保留原异常类型
+        if has_llm_hooks():
+            messages = await run_before_call(messages, kwargs.get("tools"), meta)
 
         try:
             if stream:
-                stream_kind = "chat_stream" if usage_kind == "chat" else usage_kind
                 return self._chat_stream(
-                    messages, model_name, temperature, max_tokens, start, usage_kind=stream_kind, **kwargs
+                    messages, model_name, temperature, max_tokens, start, usage_kind=stream_kind, meta=meta, **kwargs
                 )
 
             @autoretry(
@@ -242,6 +255,8 @@ class LLMClient:
             else:
                 logger.info(f"LLM: model={model_name}, duration={duration_ms}ms")
             _emit_usage(model_name, usage_kind, usage, duration_ms)
+            if has_llm_hooks():
+                await run_after_call(response, meta)
 
             return response
 
@@ -324,10 +339,12 @@ class LLMClient:
         max_tokens: int | None,
         start_time: float,
         usage_kind: str = "chat_stream",
+        meta: CallMeta | None = None,
         **kwargs: Any,
     ) -> AsyncIterator["ChatCompletionChunk"]:
         """流式响应"""
         final_usage = None
+        finish_reason: str | None = None
 
         try:
             # noinspection PyTypeChecker
@@ -346,6 +363,8 @@ class LLMClient:
                 # 收集 token 统计（usage 通常在末尾 chunk 返回）
                 if chunk.usage:
                     final_usage = chunk.usage
+                if chunk.choices and chunk.choices[0].finish_reason:
+                    finish_reason = chunk.choices[0].finish_reason
 
                 yield chunk
 
@@ -354,6 +373,8 @@ class LLMClient:
             total_tokens = final_usage.total_tokens if final_usage else 0
             logger.info(f"LLM stream: model={model}, tokens={total_tokens}, duration={duration_ms}ms")
             _emit_usage(model, usage_kind, final_usage, duration_ms)
+            if meta is not None and has_llm_hooks():
+                await run_after_call(StreamSummary(usage=final_usage, finish_reason=finish_reason), meta)
 
         except APITimeoutError as e:
             logger.error(f"LLM stream timeout: {e}")

{agstack-2.2.0 → agstack-2.3.0}/agstack/llm/flow/agent.py

@@ -322,6 +322,8 @@ class Agent:
                         kwargs["tool_choice"] = self.tool_choice
 
                     self._apply_overrides(kwargs, self.request_overrides(context, turn, retry=attempt > 0) or {})
+                    # F6 LLM 钩子的调用方上下文（client 弹出，不透传给推理后端）
+                    kwargs["hook_meta"] = {"agent": self.name, "turn": turn, "retry": attempt > 0, "context": context}
 
                     stream = await client.chat(stream=True, **kwargs)
 

{agstack-2.2.0 → agstack-2.3.0}/agstack/llm/flow/registry.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import copy
 from typing import Any, cast
 
+from ..hooks import LLMCallHook, clear_llm_hooks, register_llm_hook
 from .agent import Agent
 from .tool import Tool, ToolHook, clear_tool_hooks, register_tool_hook
 
@@ -58,6 +59,17 @@ class FlowRegistry:
         """清空全局工具钩子（测试隔离用）"""
         clear_tool_hooks()
 
+    def register_llm_hook(self, hook: LLMCallHook, *, prepend: bool = False) -> None:
+        """注册全局 LLM 调用钩子（F6）：before_call 按注册顺序改写消息，after_call 逆序观察
+
+        钩子链存于 ``llm.hooks``（保持 registry → hooks 单向导入），此处仅转发注册。
+        """
+        register_llm_hook(hook, prepend=prepend)
+
+    def clear_llm_hooks(self) -> None:
+        """清空全局 LLM 调用钩子（测试隔离用）"""
+        clear_llm_hooks()
+
     def register_agent(
         self, name: str, agent_class: type[Agent], *, label: str | None = None, echo: bool = False
     ) -> None:

{agstack-2.2.0 → agstack-2.3.0}/agstack/llm/flow/tool.py

@@ -5,7 +5,7 @@
 import json
 import logging
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable
 
 
@@ -26,6 +26,8 @@ class ToolResult:
     error: str | None = None
     content: str | None = None
     summary: str | None = None
+    #: 钩子 / 工具附带的结构化信息（如 spill 落盘引用），不喂给模型
+    metadata: dict[str, Any] = field(default_factory=dict)
 
 
 class Deny:
@@ -61,6 +63,10 @@ class ToolHook:
         execution_records 三个出口同时生效。抛异常记日志并放行原结果
         （fail open：审计钩子的 bug 不毁掉主流程）。
         Deny 产生的失败结果同样穿过 post 链（审计要看到被拒绝的调用）。
+
+        进入 post 链时 ``result.content``（喂给模型的字符串）已按 result_formatter 算好：
+        钩子可直接改写 content（spill / 截断）；钩子若换掉 ``result.result`` 而未动 content，
+        Tool 会按新 result 重算 content（2.3 起；2.1 的「改 result 即改 content」语义保留）。
         """
         return result
 
@@ -161,9 +167,13 @@ class Tool:
         if result is None:
             result = await self._execute(context, args)
 
+        # 先算 LLM 消费内容，post 钩子据此判定 / 改写（spill、截断看到的是模型将看到的字符串）
+        result.content = self._render_content(result)
+
         # post 钩子链（逆序）：可改写结果；抛异常＝放行原结果（fail open）。
         # Deny 的失败结果同样穿过 post 链，审计钩子能看到被拒绝的调用。
         for hook in reversed(_TOOL_HOOKS):
+            before_result, before_content = result.result, result.content
             try:
                 revised = await hook.post_execute(context, self, result)
             except Exception as e:
@@ -173,26 +183,16 @@ class Tool:
                 result = revised
             else:
                 logger.warning("Tool hook post_execute for %s returned %r, ignored", self.name, type(revised))
+                continue
+            # 钩子换了 result 却没给新 content（None 或原样）：按新 result 重算
+            # （保持 2.1「改 result 即改模型所见」语义）
+            if result.result is not before_result and (result.content is None or result.content == before_content):
+                result.content = self._render_content(result)
+        if result.content is None:
+            result.content = self._render_content(result)
 
         _duration_ms = int((time.perf_counter() - _t0) * 1000)
 
-        # 计算 LLM 消费内容
-        if self.result_formatter:
-            try:
-                result.content = self.result_formatter(result)
-            except Exception:
-                result.content = (
-                    json.dumps(result.result, ensure_ascii=False)
-                    if result.success
-                    else json.dumps({"error": result.error}, ensure_ascii=False)
-                )
-        else:
-            result.content = (
-                json.dumps(result.result, ensure_ascii=False)
-                if result.success
-                else json.dumps({"error": result.error}, ensure_ascii=False)
-            )
-
         # 生成面向用户的摘要
         if self.summary_fn:
             try:
@@ -215,6 +215,20 @@ class Tool:
 
         return result
 
+    def _render_content(self, result: ToolResult) -> str:
+        """按 result_formatter（失败回退 JSON）算喂给模型的内容"""
+        fallback = (
+            json.dumps(result.result, ensure_ascii=False)
+            if result.success
+            else json.dumps({"error": result.error}, ensure_ascii=False)
+        )
+        if not self.result_formatter:
+            return fallback
+        try:
+            return self.result_formatter(result)
+        except Exception:
+            return fallback
+
     async def _execute(self, context: "FlowContext", inputs: dict[str, Any]) -> ToolResult:
         """实际执行逻辑，子类应覆写此方法"""
         try:

agstack-2.3.0/agstack/llm/harness/__init__.py

@@ -0,0 +1,51 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""agstack.llm.harness——模型无关、表无关、产品无关的运行时部件
+
+- :mod:`.ports`：存储端口声明（SessionLog / SpillStore / UsageSink / KVStore）与 ``register_ports``，
+  由应用实现并在进程入口注册；
+- :mod:`.truncation`：工具结果截断设施（保头尾截断、按相关度整条丢弃），策略数值由调用方给；
+- :mod:`.spill`：超长工具结果落盘的 ToolHook（prepend 链头、按内联 token 上限判定、头尾保留 + 固定格式通知、
+  存储失败保留内联）。
+
+2.3 只收这三块零状态模块与端口声明；events / projection / tokens / AgentGuards 排 2.4，context / overflow 排 3.0。
+"""
+
+from .ports import (
+    KVStore,
+    LogEvent,
+    Ports,
+    SessionLog,
+    SpillOwner,
+    SpillRef,
+    SpillSource,
+    SpillStore,
+    TokenAnchor,
+    UsageSink,
+    clear_ports,
+    get_ports,
+    register_ports,
+)
+from .spill import SpillHook, SpillPolicy
+from .truncation import clamp_results, truncate_middle
+
+
+__all__ = [
+    "KVStore",
+    "LogEvent",
+    "Ports",
+    "SessionLog",
+    "SpillHook",
+    "SpillOwner",
+    "SpillPolicy",
+    "SpillRef",
+    "SpillSource",
+    "SpillStore",
+    "TokenAnchor",
+    "UsageSink",
+    "clamp_results",
+    "clear_ports",
+    "get_ports",
+    "register_ports",
+    "truncate_middle",
+]

agstack-2.3.0/agstack/llm/harness/ports.py

@@ -0,0 +1,198 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""存储端口（SPI）：库与应用之间的分层缝，唯一实现、由应用在进程入口注册
+
+agstack 只声明 Protocol 与数据类型，不含任何存储实现；应用（如 MetaMatrix 的 ``common.harness``）用自己的表 /
+文件系统实现后经 :func:`register_ports` 注入。端口刻意少：会话日志（追加 / 读取 / 遮蔽 / 锚点）、落盘（spill）、
+用量汇、可选 KV。
+
+``LogEvent`` 借「仅追加日志 + 投影」思路但不做事件溯源：``kind`` 取值见 :data:`LOG_KINDS`；被重试 / 溢出恢复 / 折叠
+取代的行不删，由 ``shadowed_by`` 指向取代它的事件序号，投影只消费 ``shadowed_by is None`` 的行。
+"""
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+from uuid import UUID
+
+from ..client import UsageEvent, set_usage_callback
+
+
+#: 日志事件类型
+LOG_KINDS = frozenset(
+    {"message", "event", "tool_call", "tool_result", "summary", "fold", "attempt", "system_snapshot", "phase_marker"}
+)
+
+#: 遮蔽原因
+SHADOW_KINDS = frozenset({"retry", "overflow_recovery", "fold"})
+
+
+@dataclass(slots=True)
+class LogEvent:
+    """会话日志的一条事件
+
+    :param kind: 事件类型（:data:`LOG_KINDS`）
+    :param role: 可投影为模型消息时的角色（system / user / assistant / tool / event），否则 None
+    :param content: 正文（消息文本 / 工具结果 / 摘要）
+    :param metadata: 结构化附带（tool_calls、tool_call_id、来源、锚点等）
+    :param seq: 会话内单调序号，append 时由实现分配
+    :param shadowed_by: 遮蔽它的事件序号（None 为有效行）
+    """
+
+    kind: str
+    role: str | None = None
+    content: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    seq: int | None = None
+    shadowed_by: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TokenAnchor:
+    """上一次真实请求的 token 锚点：历史主体用锚点值，只对锚点之后的新增内容做估算"""
+
+    seq: int
+    prompt_tokens: int
+    model: str
+
+
+@dataclass(frozen=True, slots=True)
+class SpillOwner:
+    """落盘内容的归属（权限与密级由实现按此判定）"""
+
+    user_id: UUID | None
+    session_id: str | None = None
+    task_id: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class SpillSource:
+    """落盘内容的来源（哪个工具、哪次调用）"""
+
+    tool: str
+    call_id: str | None = None
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class SpillRef:
+    """落盘结果的引用：locator 对模型不透明，读取经实现的权限检查"""
+
+    locator: str
+    chars: int
+    tokens: int
+    name: str
+
+
+@runtime_checkable
+class SessionLog(Protocol):
+    """会话日志端口"""
+
+    async def append(self, session_id: UUID, events: Sequence[LogEvent]) -> int:
+        """追加事件，返回末 seq"""
+        ...
+
+    async def read(self, session_id: UUID, *, after_seq: int = 0, limit: int | None = None) -> Sequence[LogEvent]:
+        """按 seq 升序读取（含被遮蔽行，投影方自行过滤）"""
+        ...
+
+    async def shadow(self, session_id: UUID, target_seqs: Sequence[int], by_seq: int, kind: str) -> None:
+        """把 target_seqs 标为被 by_seq 遮蔽；kind ∈ SHADOW_KINDS"""
+        ...
+
+    async def latest_anchor(self, session_id: UUID) -> TokenAnchor | None:
+        """最近一次 token 锚点"""
+        ...
+
+
+@runtime_checkable
+class SpillStore(Protocol):
+    """落盘端口"""
+
+    async def save_text(
+        self, owner: SpillOwner, source: SpillSource, suggested_name: str, content: str
+    ) -> SpillRef: ...
+
+    async def read_text(self, locator: str, *, offset: int = 0, limit: int | None = None) -> str: ...
+
+
+#: 用量汇：与 client.set_usage_callback 同一回调类型，纳入同一注册面
+UsageSink = Callable[[UsageEvent], None]
+
+
+@runtime_checkable
+class KVStore(Protocol):
+    """可选 KV 端口（投影缓存、守卫状态）"""
+
+    async def get(self, scope: str, key: str) -> Any | None: ...
+
+    async def put(self, scope: str, key: str, value: Any) -> None: ...
+
+
+@dataclass(slots=True)
+class Ports:
+    """已注册的端口集合"""
+
+    session_log: SessionLog | None = None
+    spill: SpillStore | None = None
+    usage: UsageSink | None = None
+    kv: KVStore | None = None
+
+
+_PORTS = Ports()
+
+
+def register_ports(
+    *,
+    session_log: SessionLog | None = None,
+    spill: SpillStore | None = None,
+    usage: UsageSink | None = None,
+    kv: KVStore | None = None,
+) -> None:
+    """注册端口实现（进程级单例；只覆盖传入的项，传 None 的项保持不变）
+
+    ``usage`` 同时写入 :func:`agstack.llm.client.set_usage_callback`，两处始终一致。
+    """
+    if session_log is not None:
+        _PORTS.session_log = session_log
+    if spill is not None:
+        _PORTS.spill = spill
+    if usage is not None:
+        _PORTS.usage = usage
+        set_usage_callback(usage)
+    if kv is not None:
+        _PORTS.kv = kv
+
+
+def get_ports() -> Ports:
+    """当前端口集合（未注册的项为 None，消费方自行降级）"""
+    return _PORTS
+
+
+def clear_ports() -> None:
+    """清空全部端口（测试隔离用），usage 回调同步注销"""
+    _PORTS.session_log = None
+    _PORTS.spill = None
+    _PORTS.usage = None
+    _PORTS.kv = None
+    set_usage_callback(None)
+
+
+__all__ = [
+    "LOG_KINDS",
+    "SHADOW_KINDS",
+    "KVStore",
+    "LogEvent",
+    "Ports",
+    "SessionLog",
+    "SpillOwner",
+    "SpillRef",
+    "SpillSource",
+    "SpillStore",
+    "TokenAnchor",
+    "UsageSink",
+    "clear_ports",
+    "get_ports",
+    "register_ports",
+]

agstack-2.3.0/agstack/llm/harness/spill.py

@@ -0,0 +1,104 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""超长工具结果落盘（spill）：ToolHook post 钩子
+
+纪律（借 dsh spill-policy）：``prepend`` 挂链头使其成为最外层 post；按 ``max_inline_tokens`` 判定；全文经
+:class:`~.ports.SpillStore` 落盘；上下文保头尾 + 固定格式通知（含 locator，模型可用应用提供的读取工具回读）；
+read 类工具排除（回读结果再落盘会死循环）；**存储失败只 warn 保留内联**（可用性优先于预算）。
+
+与截断的关系：clamp 是「丢弃」，spill 是「移位」，两者并存——先 spill 保全文，再 clamp 决定内联多少。
+钩子作用于 ``ToolResult.content``（喂给模型的字符串，Tool 在 post 链前已算好），不改 ``result.result`` 的形状；
+落盘引用写进 ``ToolResult.metadata["spill"]``。
+"""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ..flow.tool import ToolHook, ToolResult
+from .ports import SpillOwner, SpillRef, SpillSource, get_ports
+from .truncation import TokenCounter
+
+
+if TYPE_CHECKING:
+    from ..flow.context import FlowContext
+    from ..flow.tool import Tool
+
+logger = logging.getLogger(__name__)
+
+#: 通知模板；{tokens} / {chars} 原文规模，{locator} 回读定位符，{name} 建议文件名
+DEFAULT_NOTICE = (
+    "\n[... 工具结果约 {tokens} tokens / {chars} 字符，超出内联上限，全文已存为 {name}（locator={locator}）；"
+    "此处只保留开头与结尾，需要细节时按 locator 分段读取 ...]\n"
+)
+
+
+@dataclass(slots=True)
+class SpillPolicy:
+    """落盘策略（数值与名单由应用给）
+
+    :param max_inline_tokens: 内联上限；``content`` 超过即落盘
+    :param exclude_tools: 不落盘的工具名（read 类回读工具必须在列）
+    :param head_chars / tail_chars: 内联保留的头尾字符数
+    :param count_tokens: token 计数函数（应用按模型绑定）
+    :param owner_of: 从 FlowContext 解析归属（用户 / 会话 / 任务），实现据此定目录与密级
+    :param model_of: 从 FlowContext 解析模型名（仅供日志）
+    :param notice: 通知模板
+    """
+
+    max_inline_tokens: int
+    count_tokens: TokenCounter
+    owner_of: Callable[["FlowContext"], SpillOwner]
+    exclude_tools: frozenset[str] = field(default_factory=frozenset)
+    head_chars: int = 1200
+    tail_chars: int = 400
+    notice: str = DEFAULT_NOTICE
+
+
+class SpillHook(ToolHook):
+    """post 钩子：content 超内联上限时经 SpillStore 落盘并替换为头尾 + 通知；未注册 SpillStore 时为空操作"""
+
+    def __init__(self, policy: SpillPolicy):
+        self.policy = policy
+
+    async def post_execute(self, context: "FlowContext", tool: "Tool", result: ToolResult) -> ToolResult:
+        policy = self.policy
+        if tool.name in policy.exclude_tools or not result.success:
+            return result
+        content = result.content
+        if not content:
+            return result
+        store = get_ports().spill
+        if store is None:
+            return result
+        tokens = policy.count_tokens(content)
+        if tokens <= policy.max_inline_tokens:
+            return result
+        if len(content) <= policy.head_chars + policy.tail_chars:
+            return result
+        name = f"{tool.name}-{context.get_variable('_agent_call_id') or context.context_id[:8]}.txt"
+        try:
+            ref = await store.save_text(
+                policy.owner_of(context),
+                SpillSource(tool=tool.name, call_id=context.get_variable("_agent_call_id"), arguments=result.arguments),
+                name,
+                content,
+            )
+        except Exception as e:  # 存储失败只 warn，保留内联
+            logger.warning("spill store failed for tool %s, keeping inline content: %s", tool.name, e, exc_info=True)
+            return result
+        result.content = render_spilled(content, ref, policy)
+        result.metadata["spill"] = {"locator": ref.locator, "chars": ref.chars, "tokens": ref.tokens, "name": ref.name}
+        return result
+
+
+def render_spilled(content: str, ref: SpillRef, policy: SpillPolicy) -> str:
+    """头尾保留 + 固定格式通知"""
+    head = content[: policy.head_chars]
+    tail = content[len(content) - policy.tail_chars :]
+    notice = policy.notice.format(tokens=ref.tokens, chars=ref.chars, locator=ref.locator, name=ref.name)
+    return head + notice + tail
+
+
+__all__ = ["DEFAULT_NOTICE", "SpillHook", "SpillPolicy", "render_spilled"]

agstack-2.3.0/agstack/llm/harness/truncation.py

@@ -0,0 +1,93 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""工具结果截断设施（写入侧防线；零状态、模型无关）
+
+截断的**设施**在此，**调用**留在各工具体内——结果列表按相关度丢弃并回写丢弃数、渲染串截断、单字段截断三种形态
+语义各异，且语义化截断依赖工具内知识，不适合做成盲 post 钩子。上限数值（单条 / 合计占窗口比例）由调用方给。
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+
+logger = logging.getLogger(__name__)
+
+#: token 计数函数：text -> tokens（调用方按模型绑定，如 functools.partial(count_tokens, model=...)）
+TokenCounter = Callable[[str], int]
+
+#: 截断标注模板；{tokens} / {lines} 为原文规模
+DEFAULT_MARKER = "\n[... 原文约 {tokens} tokens / {lines} 行，已截断中段；如需完整内容请缩小查询范围重试 ...]\n"
+
+
+def truncate_middle(text: str, max_tokens: int, count_tokens: TokenCounter, *, marker: str = DEFAULT_MARKER) -> str:
+    """超限文本保头尾截断，中间段替换为规模标注（截断绝不静默）；未超限原样返回"""
+    total = count_tokens(text)
+    if total <= max_tokens:
+        return text
+    lines = text.count("\n") + 1
+    # 按 token 比例折算保留字符数，留 10% 余量给标注与估算误差
+    keep_chars = max(int(len(text) * max_tokens / total * 0.9), 200)
+    head_chars = int(keep_chars * 0.7)
+    head = text[:head_chars]
+    tail = text[len(text) - (keep_chars - head_chars) :]
+    return head + marker.format(tokens=total, lines=lines) + tail
+
+
+def clamp_results(
+    results: list[Any],
+    *,
+    per_item_max: int,
+    total_max: int,
+    count_tokens: TokenCounter,
+    content_key: str = "content",
+    relevance_key: str = "relevance_score",
+    tool: str = "",
+) -> tuple[list[Any], int]:
+    """结果列表写入侧统一截断：单条 ``content`` 超 per_item_max 保头尾截断；合计超 total_max 从低相关度端整条丢弃
+
+    返回 ``(处理后的 results, 丢弃条数)``，丢弃数由调用方显式呈现给模型。
+    """
+    if not results:
+        return results, 0
+    clamped: list[Any] = []
+    tokens: list[int] = []
+    for item in results:
+        if isinstance(item, dict) and isinstance(item.get(content_key), str) and item[content_key]:
+            content = truncate_middle(item[content_key], per_item_max, count_tokens)
+            if content != item[content_key]:
+                item = {**item, content_key: content}
+            clamped.append(item)
+            tokens.append(count_tokens(item[content_key]))
+        else:
+            clamped.append(item)
+            tokens.append(0)
+
+    total = sum(tokens)
+    if total <= total_max:
+        return clamped, 0
+
+    def _relevance(i: int) -> float:
+        item = clamped[i]
+        if isinstance(item, dict):
+            score = item.get(relevance_key)
+            if isinstance(score, (int, float)):
+                return float(score)
+        return 0.0
+
+    dropped: set[int] = set()
+    for i in sorted(range(len(clamped)), key=_relevance):
+        if total <= total_max:
+            break
+        if tokens[i] == 0:
+            continue
+        dropped.add(i)
+        total -= tokens[i]
+    if dropped:
+        logger.warning(
+            "[%s] tool results exceed %d tokens, dropped %d low-relevance items", tool, total_max, len(dropped)
+        )
+    return [item for i, item in enumerate(clamped) if i not in dropped], len(dropped)
+
+
+__all__ = ["DEFAULT_MARKER", "TokenCounter", "clamp_results", "truncate_middle"]