sycommon-python-lib 0.2.7a40__tar.gz → 0.2.7a42__tar.gz

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.7a40
+Version: 0.2.7a42
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.7a40"
+version = "0.2.7a42"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/src/sycommon/agent/deep_agent.py

@@ -62,12 +62,18 @@ from sycommon.agent.middleware.sandbox_path_guard import SandboxPathGuardMiddlew
 from sycommon.agent.middleware.sensitive_guard import SensitiveGuardMiddleware
 from deepagents.middleware.summarization import create_summarization_tool_middleware  # noqa: F401 保留 re-export
 from sycommon.agent.summarization_utils import build_summarization_middleware
+from sycommon.agent.resume_compactor import maybe_compact_before_resume
 
 # 流式逐 token 诊断日志开关（默认关）。开启后每个 chunk 都打印
 # chunk_type/content 等（仅供排障）。LLM 最终结果已由 LLMLogger.on_llm_end
 # 统一记录，正常无需打开此开关，避免流式日志刷屏。
 _STREAM_DEBUG = check_env_flag(['DEEP_AGENT_STREAM_DEBUG'], default='false')
 
+# 流式 tool_call args buffer 上限（OOM 兜底，env 可调）。
+# 模型生成的超大单 tool_call args（如 base64 大文件内容）会逐段累积到 _args_buffer，
+# 无上限可涨到几十 MB。超限停止追加（只影响前端 tool_call 进度展示，工具实际执行不受影响）。
+MAX_ARGS_BUFFER_BYTES = int(os.environ.get("DEEP_AGENT_MAX_ARGS_BUFFER", 1024 * 1024))
+
 if TYPE_CHECKING:
     from deepagents.graph import CompiledStateGraph
     from langchain.agents.middleware.types import AgentState, ContextT, ModelRequest, ModelResponse, ResponseT
@@ -460,6 +466,7 @@ class DeepAgent:
         recovery_manager: Optional[SandboxRecoveryManager] = None,
         rubric_eval_collector: Optional[_RubricEvalCollector] = None,
         sensitive_guard: Optional[SensitiveGuardMiddleware] = None,
+        raw_model: Any = None,
     ):
         self.user_id = user_id
         self.agent = agent
@@ -468,14 +475,32 @@ class DeepAgent:
         self.recovery_manager = recovery_manager
         self.rubric_eval_collector = rubric_eval_collector
         self.sensitive_guard = sensitive_guard
+        # 🔑 存 raw_model 引用，供 cleanup 关 LLM client（root_async_client）。
+        # model 被埋进 graph 内部节点闭包，表层拿不到，必须 create 时显式传入。
+        self._raw_model = raw_model
 
     async def cleanup(self):
-        """清理资源"""
+        """清理资源（沙箱连接 + 敏感检测 client）。
+
+        🔑 不关 LLM client：root_async_client 底层的 httpx.AsyncClient 是 langchain
+        `_cached_async_httpx_client` 的 @lru_cache 共享实例（多个 ChatOpenAI 复用同一个），
+        close 它会让所有共享该 client 的后续请求报 "Cannot send a request, as the client
+        has been closed"。底层连接池由 langchain lru_cache 管理，进程退出时统一回收。
+        """
         if self.sandbox_backend:
             try:
                 await self.sandbox_backend.acleanup()
             except Exception:
                 pass
+        # 🔑 关敏感检测懒加载的两个独立 ChatOpenAI（detector + internal_raw）。
+        # 注意：同样不能 close 底层共享 httpx，aclose 内部已按此处理（只清引用）。
+        if self.sensitive_guard is not None:
+            try:
+                aclose = getattr(self.sensitive_guard, "aclose", None)
+                if aclose is not None:
+                    await aclose()
+            except Exception:
+                pass
 
     async def chat(
         self,
@@ -512,6 +537,14 @@ class DeepAgent:
         _trace_token = SYLogger.set_trace_id(_chat_trace_id)
 
         try:
+            # 🔑 恢复前主动压缩：若该 thread 的 checkpoint 已超过阈值，先在存储侧压缩历史再恢复，
+            # 避免每次会话都把全量 messages 反序列化进内存（单会话恢复峰值 0.5-1GB）。
+            # 日常会话（未超阈值）零开销。任何异常仅 warning，绝不阻断 chat。
+            try:
+                await maybe_compact_before_resume(self)
+            except Exception as _e:
+                SYLogger.warning(f"[ResumeCompact] 恢复前压缩失败(不阻断 chat): {_e}")
+
             input_state = {"messages": [HumanMessage(content=message)]}
             if rubric:
                 input_state["rubric"] = rubric
@@ -805,9 +838,18 @@ class DeepAgent:
                                 existing_tc = None
 
                             if existing_tc:
-                                # 追加 args 字符串片段
+                                # 追加 args 字符串片段（🔑 上限防 OOM：模型生成的超大单 tool_call args
+                                # 如 base64 大文件内容，无上限会涨到几十 MB。超限停止追加，
+                                # args 保持 {} —— 只影响前端 tool_call 进度展示，工具实际执行不受影响）。
                                 if tcc_args_str:
-                                    existing_tc["_args_buffer"] += tcc_args_str
+                                    buf_len = len(existing_tc.get("_args_buffer", ""))
+                                    if buf_len < MAX_ARGS_BUFFER_BYTES:
+                                        existing_tc["_args_buffer"] += tcc_args_str
+                                    elif not existing_tc.get("_args_truncated"):
+                                        existing_tc["_args_truncated"] = True
+                                        SYLogger.warning(
+                                            f"[DeepAgent] tool_call args buffer 超上限({MAX_ARGS_BUFFER_BYTES}B)，"
+                                            f"截断: {existing_tc.get('name')}")
                                 if tcc_name:
                                     existing_tc["name"] = tcc_name
                             else:
@@ -1371,6 +1413,7 @@ async def create_deep_agent(
         recovery_manager=recovery_manager,
         rubric_eval_collector=rubric_eval_collector,
         sensitive_guard=guard,
+        raw_model=raw_model,
     )
 
 

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/src/sycommon/agent/middleware/sensitive_guard.py

@@ -13,6 +13,7 @@ agent 本就是内部模型（model_tier="internal"）时短路放行，不检
 检测失败 fail-open（视为不敏感，放行）。
 """
 import asyncio
+import os
 from typing import Any, Awaitable, Callable, List, Optional
 
 from langchain.agents.middleware.types import (
@@ -113,9 +114,17 @@ DEFAULT_DETECT_PROMPT = """你是数据脱敏分类器。判断以下「即将
 
 
 def _messages_to_text(messages: List[BaseMessage]) -> str:
-    """把 messages 列表拼成检测用文本（[Role] content）。"""
+    """把 messages 列表拼成检测用文本（[Role] content）。
+
+    🔑 OOM 兜底：整段上下文（含历史 + 工具结果）拼成单字符串送检测，
+    长对话会涨到几十 MB（join + replace + HumanMessage 3× 放大）。
+    超 MAX_DETECT_CONTENT_BYTES 即截断 + 尾注，只截断送检文本，不影响实际对话历史。
+    """
+    MAX_BYTES = int(os.environ.get("SENSITIVE_DETECT_MAX_BYTES", 512 * 1024))
     parts = []
-    for m in messages:
+    total = 0
+    truncated_at = -1
+    for i, m in enumerate(messages):
         role = type(m).__name__
         content = m.content
         if isinstance(content, list):
@@ -124,8 +133,17 @@ def _messages_to_text(messages: List[BaseMessage]) -> str:
                 str(c.get("text", "")) if isinstance(c, dict) else str(c)
                 for c in content
             )
-        parts.append(f"[{role}] {content}")
-    return "\n".join(parts)
+        part = f"[{role}] {content}"
+        plen = len(part)
+        if total + plen > MAX_BYTES:
+            truncated_at = i
+            break
+        parts.append(part)
+        total += plen
+    text = "\n".join(parts)
+    if truncated_at >= 0:
+        text += f"\n...[检测内容已截断,共{len(messages)}条,仅取前{truncated_at}条,上限{MAX_BYTES}B]"
+    return text
 
 
 def _parse_detect_json(text: str) -> Optional[SensitiveCheck]:
@@ -390,6 +408,18 @@ class SensitiveGuardMiddleware(AgentMiddleware):
                     self._internal_raw = getattr(llm, "llm", llm)
         return self._internal_raw
 
+    async def aclose(self):
+        """清理敏感检测懒加载的两个独立 ChatOpenAI 引用（连接池泄漏兜底）。
+
+        _detector / _internal_raw 是 per-middleware 实例，命中敏感才懒加载。
+        🔑 只清引用，不 close 底层 httpx——root_async_client 底层是 langchain
+        `_cached_async_httpx_client` 的 @lru_cache 共享实例，close 会让共享该 client 的
+        后续请求报 "client has been closed"。底层连接池由 langchain lru_cache 管理。
+        供 DeepAgent.cleanup / MultiAgentTeam.cleanup 调用。
+        """
+        self._detector = None
+        self._internal_raw = None
+
     async def _detect(self, messages: List[BaseMessage]) -> SensitiveCheck:
         """一次检测：命中即返回 SensitiveCheck。fail-open（识别不出来→视为不敏感放行）。
 

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/src/sycommon/agent/multi_agent_team.py

@@ -51,6 +51,7 @@ from sycommon.agent.middleware.sensitive_guard import (
 )
 from deepagents.middleware.summarization import create_summarization_tool_middleware  # noqa: F401 保留 re-export
 from sycommon.agent.summarization_utils import build_summarization_middleware
+from sycommon.agent.resume_compactor import maybe_compact_before_resume
 
 if TYPE_CHECKING:
     from deepagents.graph import CompiledStateGraph
@@ -200,6 +201,7 @@ class MultiAgentTeam:
         recovery_manager: Optional[SandboxRecoveryManager] = None,
         downgrade_state: Optional[DowngradeState] = None,
         sensitive_guard: Optional["SensitiveGuardMiddleware"] = None,
+        raw_model: Any = None,
     ):
         self.user_id = user_id
         self.agent = agent
@@ -214,6 +216,8 @@ class MultiAgentTeam:
         # （is_downgraded / last_notice_source / set_file_turn_degrade 等），
         # 让单 agent 与 multi-agent 的应用层代码统一走 `getattr(agent, "sensitive_guard", None)`。
         self.sensitive_guard = sensitive_guard
+        # 🔑 存协调者 raw_model 引用，供 cleanup 关 LLM client
+        self._raw_model = raw_model
 
     @property
     def is_downgraded(self) -> bool:
@@ -221,12 +225,24 @@ class MultiAgentTeam:
         return bool(self.downgrade_state and self.downgrade_state.is_downgraded)
 
     async def cleanup(self):
-        """清理资源"""
+        """清理资源（沙箱连接 + 敏感检测 client）。
+
+        🔑 不关 LLM client：root_async_client 底层 httpx 是 langchain lru_cache 共享实例，
+        close 会让共享该 client 的后续请求报 "client has been closed"。底层由 lru_cache 管理。
+        """
         if self.sandbox_backend:
             try:
                 await self.sandbox_backend.acleanup()
             except Exception:
                 pass
+        # 🔑 关敏感检测懒加载的两个独立 ChatOpenAI（aclose 内部只清引用，不 close 共享 httpx）
+        if self.sensitive_guard is not None:
+            try:
+                aclose = getattr(self.sensitive_guard, "aclose", None)
+                if aclose is not None:
+                    await aclose()
+            except Exception:
+                pass
 
     async def chat(
         self,
@@ -257,6 +273,12 @@ class MultiAgentTeam:
         _trace_token = SYLogger.set_trace_id(_chat_trace_id)
 
         try:
+            # 🔑 恢复前主动压缩：thread 超阈值先在存储侧压缩历史再恢复，防全量加载 OOM。
+            try:
+                await maybe_compact_before_resume(self)
+            except Exception as _e:
+                SYLogger.warning(f"[ResumeCompact] 恢复前压缩失败(不阻断 chat): {_e}")
+
             async for chunk in self._astream_with_retry(
                 {"messages": [HumanMessage(content=message)]},
                 max_retries=3,
@@ -595,6 +617,9 @@ async def create_multi_agent_team(
         thinking=config.model_thinking,
         wrap_structured=False,
     )
+    # 🔑 提取 raw_model（LLMWithTokenTracking 包装的底层 ChatOpenAI），
+    # 供 MultiAgentTeam.cleanup 关 root_async_client（LLM client 连接池泄漏兜底）。
+    raw_model = getattr(model, 'llm', model)
 
     # 创建 checkpointer
     if checkpointer is None:
@@ -731,6 +756,7 @@ async def create_multi_agent_team(
         recovery_manager=recovery_manager,
         downgrade_state=shared_downgrade_state,
         sensitive_guard=coord_guard,
+        raw_model=raw_model,
     )
 
 

sycommon_python_lib-0.2.7a42/src/sycommon/agent/resume_compactor.py

@@ -0,0 +1,165 @@
+"""恢复前主动压缩（resume-time compaction）—— 防 PG checkpoint 全量加载 OOM。
+
+根因：LangGraph 恢复会话时 `PregelLoop.__aenter__` → `aget_tuple` 用 `array_agg`
+把整个 thread 的所有 messages blob 一次性反序列化进内存（DeltaChannel ancestor
+replay）。单会话 0.5-1GB，多用户并发 N×。现有 SummarizationMiddleware 阈值是
+model-call-time reactive（在下一次 LLM 调用前判断），对「恢复加载时的内存峰值」无效。
+
+本模块在 `DeepAgent.chat()` / `MultiAgentTeam.chat()` 入口调用：
+1. 先跑轻量 SQL（绕开 langgraph SELECT_SQL）探测该 thread 的 checkpoint 体量；
+2. 未超阈值 → 直接返回（日常会话零开销）；
+3. 超阈值 → 用 langgraph 公开 API `aupdate_state` 复用 deepagents 的压缩链
+   （`_determine_cutoff_index`/`_partition_messages`/`_acreate_summary`/`_build_new_messages_with_path`）
+   主动压缩一次历史再恢复。这与 reactive summarization 用完全相同的 cutoff 逻辑，
+   只是触发时机提前到「恢复之前」，避免丢历史（cutoff 算错才会丢，这里逻辑等价）。
+
+只对根 thread（checkpoint_ns=''）做；MultiAgentTeam 的子 agent 不挂 checkpointer，
+chat 入口的 thread_id 永远是根。不动 ResilientPostgresSaver（PoolClosed 自愈逻辑很微妙）。
+
+阈值用环境变量可调。任何异常只 warning，绝不阻断 chat（恢复失败就走原全量加载路径）。
+"""
+
+import os
+from typing import Any, Optional
+
+from langchain_core.messages import RemoveMessage
+
+from sycommon.logging.kafka_log import SYLogger
+
+# 阈值（env 可调）。超过才触发主动压缩；日常会话远低于此，零开销。
+MAX_CHECKPOINT_BYTES = int(os.environ.get("CHECKPOINT_MAX_RESUME_BYTES", 50 * 1024 * 1024))
+MAX_CHECKPOINT_WRITES = int(os.environ.get("CHECKPOINT_MAX_RESUME_WRITES", 1000))
+
+
+async def _probe_thread_size(thread_id: str) -> tuple[int, int]:
+    """探测 thread 的 checkpoint 体量（绕开 langgraph，自定义轻量 SQL）。
+
+    Returns:
+        (n_writes, total_bytes)。探测失败返回 (0, 0)（当作未超阈值）。
+    """
+    try:
+        from sycommon.database.pg_checkpoint_service import PgCheckpointService
+        if not PgCheckpointService.is_initialized() or not PgCheckpointService._pool:
+            return (0, 0)
+        pool = PgCheckpointService._pool
+        async with pool.connection() as conn:
+            cur = await conn.execute(
+                """
+                SELECT count(*) AS n, coalesce(sum(octet_length(blob)), 0) AS bytes
+                FROM checkpoint_writes
+                WHERE thread_id = %s AND checkpoint_ns = ''
+                """,
+                (thread_id,),
+            )
+            row = await cur.fetchone()
+            if not row:
+                return (0, 0)
+            return (int(row[0] or 0), int(row[1] or 0))
+    except Exception as e:
+        SYLogger.warning(f"[ResumeCompact] 探测 thread 大小失败(不压缩): thread={thread_id}, err={e}")
+        return (0, 0)
+
+
+def _find_summarization_middleware(agent: Any) -> Optional[Any]:
+    """在 agent 的 middleware 列表里找 deepagents SummarizationMiddleware 实例。
+
+    CompiledStateGraph 不直接暴露 middleware 列表，但 deepagents 创建时把 middleware
+    挂在 graph 的 nodes 或 metadata 里。这里用 hasattr 兜底：
+    - 优先 agent._middleware_list / agent.middleware（若 deepagents 暴露）
+    - 否则按属性类型识别（有 _determine_cutoff_index/_partition_messages/_acreate_summary）
+    """
+    candidates = []
+    for attr in ("middleware", "_middleware_list", "_middlewares", "middleware_list"):
+        lst = getattr(agent, attr, None)
+        if lst and isinstance(lst, (list, tuple)):
+            candidates.extend(lst)
+    # 兜底：把整个 graph 的可迭代属性也扫一遍
+    if not candidates:
+        for attr in dir(agent):
+            if attr.startswith("_"):
+                continue
+            try:
+                v = getattr(agent, attr, None)
+            except Exception:
+                continue
+            if hasattr(v, "_determine_cutoff_index") and hasattr(v, "_acreate_summary"):
+                candidates.append(v)
+                break
+    for mw in candidates:
+        if hasattr(mw, "_determine_cutoff_index") and hasattr(mw, "_acreate_summary"):
+            return mw
+    return None
+
+
+async def _compact_thread(agent_holder: Any, thread_id: str) -> bool:
+    """对超阈值 thread 执行主动压缩。返回 True=已压缩，False=跳过/失败。"""
+    from langgraph.graph.state import CompiledStateGraph
+
+    graph = getattr(agent_holder, "agent", None)
+    if graph is None:
+        return False
+    if not isinstance(graph, CompiledStateGraph):
+        # 非 CompiledStateGraph（如直接 graph）也支持 aget_state/aupdate_state，继续
+        pass
+
+    config = agent_holder.config
+    # 1. 拿当前 state（这一步仍会触发大加载，但仅一次且只在本会话首条）
+    try:
+        state = await graph.aget_state(config)
+        messages = list(getattr(state, "values", {}).get("messages", []) or [])
+    except Exception as e:
+        SYLogger.warning(f"[ResumeCompact] 获取 state 失败(不压缩): thread={thread_id}, err={e}")
+        return False
+
+    if len(messages) < 10:
+        return False  # 历史太短，没必要压缩
+
+    # 2. 找 summarization middleware 复用压缩链
+    mw = _find_summarization_middleware(graph)
+    if mw is None:
+        SYLogger.warning(f"[ResumeCompact] 找不到 SummarizationMiddleware(不压缩): thread={thread_id}")
+        return False
+
+    try:
+        cutoff = mw._determine_cutoff_index(messages)
+        to_summarize, preserve = mw._partition_messages(messages, cutoff)
+        if not to_summarize:
+            return False
+        summary = await mw._acreate_summary(to_summarize)
+        new_msgs = mw._build_new_messages_with_path(summary, None)
+        removed = [RemoveMessage(id=m.id) for m in to_summarize if getattr(m, "id", None)]
+
+        # 3. 用 langgraph 公开 API 写回（等价于把 to_summarize 替换为 new_msgs）
+        await graph.aupdate_state(config, {"messages": removed + new_msgs})
+        SYLogger.info(
+            f"[ResumeCompact] 恢复前压缩完成: thread={thread_id}, "
+            f"压缩 {len(to_summarize)} 条→1 条摘要, 保留 {len(preserve)} 条")
+        return True
+    except Exception as e:
+        SYLogger.warning(f"[ResumeCompact] 压缩执行失败(不阻断): thread={thread_id}, err={e}")
+        return False
+
+
+async def maybe_compact_before_resume(agent_holder: Any) -> None:
+    """chat 入口调用：若 thread checkpoint 超阈值，先主动压缩历史再恢复。
+
+    agent_holder 需有 .agent (CompiledStateGraph) 和 .config 属性（DeepAgent/MultiAgentTeam）。
+    任何异常只 warning，绝不阻断 chat。
+    """
+    try:
+        thread_id = (agent_holder.config or {}).get("configurable", {}).get("thread_id")
+        if not thread_id:
+            return
+        n, total_bytes = await _probe_thread_size(thread_id)
+        if n < MAX_CHECKPOINT_WRITES and total_bytes < MAX_CHECKPOINT_BYTES:
+            SYLogger.debug(
+                f"[ResumeCompact] 未超阈值,跳过压缩: thread={thread_id}, "
+                f"writes={n}, bytes={total_bytes}")
+            return
+        SYLogger.info(
+            f"[ResumeCompact] 超阈值,触发恢复前压缩: thread={thread_id}, "
+            f"writes={n}, bytes={total_bytes}, "
+            f"阈值(writes={MAX_CHECKPOINT_WRITES}, bytes={MAX_CHECKPOINT_BYTES})")
+        await _compact_thread(agent_holder, thread_id)
+    except Exception as e:
+        SYLogger.warning(f"[ResumeCompact] 恢复前压缩异常(不阻断 chat): {e}")

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/src/sycommon/agent/sandbox/file_ops.py

@@ -16,6 +16,7 @@
 
 import asyncio
 import base64
+import os
 from dataclasses import dataclass
 from typing import Optional, TYPE_CHECKING
 
@@ -40,6 +41,13 @@ if TYPE_CHECKING:
 # 沙箱 API 路径前缀
 SANDBOX_API_PREFIX = "/v1/sandbox"
 
+# 下载/读取的文件大小预检上限（OOM 兜底，env 可调）。
+# adownload_files 整包读 + base64 解码，agent 调 download 工具读大文件会把全量拉进内存；
+# aread 有行数 limit 但无字节上限。下载/读取前先 astat 拿 size，超限返回 error 让 agent
+# 改用 head/grep/offset+limit 读。astat 异常 fail-open（warning 后继续，避免额外 RPC 失败阻断）。
+MAX_DOWNLOAD_BYTES = int(os.environ.get("SANDBOX_DOWNLOAD_MAX_BYTES", 100 * 1024 * 1024))
+MAX_READ_BYTES = int(os.environ.get("SANDBOX_READ_MAX_BYTES", 10 * 1024 * 1024))
+
 
 # 服务端 /edit 返回的自由格式错误串 -> deepagents 标准错误码归一化。
 # 对齐 deepagents 0.6.11 BaseSandbox._map_edit_error 的错误码集合，使
@@ -404,13 +412,31 @@ class FileOperationsMixin:
                 await self._lazy_sync_skill_from_path(file_path)
 
             await self._ensure_synced_async()
+
+            # 🔑 OOM 兜底：astat 拿 size（只查 size 不读内容），超字节上限直接返回 error，
+            # 让 agent 改用 head/grep/offset+limit 读，避免整文件拉进内存。astat 异常 fail-open。
+            try:
+                st = await self.astat(path=file_path)
+                if st and not getattr(st, "error", None) and getattr(st, "exists", False):
+                    fsize = getattr(st, "size", 0) or 0
+                    if fsize > MAX_READ_BYTES:
+                        cap_mb = MAX_READ_BYTES // (1024 * 1024)
+                        SYLogger.warning(f"[Sandbox] 文件过大拒绝读取: {file_path}, size={fsize}")
+                        return ReadResult(
+                            error=f"File '{file_path}': 文件过大（{fsize // (1024*1024)}MB > {cap_mb}MB），请用 offset+limit 分页读取或 grep/head 过滤")
+            except Exception as se:
+                SYLogger.warning(f"[Sandbox] astat 预检失败(继续读取): {se}")
+
+            # limit=None 时强制限到 2000 行（防御 agent 传无限 limit）
+            effective_limit = limit if limit is not None else 2000
+
             SYLogger.info(
-                f"[Sandbox] 异步读取文件: {file_path} (offset={offset}, limit={limit})")
+                f"[Sandbox] 异步读取文件: {file_path} (offset={offset}, limit={effective_limit})")
             result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/read", {
                 "file_path": file_path,
                 "user_id": self.user_id,
                 "offset": offset,
-                "limit": limit
+                "limit": effective_limit
             }, timeout=timeout)
             # 错误前缀对齐 BaseSandbox._parse_read_output：
             # "File '<path>': <reason>"，统一上层错误语义。

{sycommon_python_lib-0.2.7a40 → sycommon_python_lib-0.2.7a42}/src/sycommon/agent/sandbox/http_sandbox_backend.py

@@ -467,11 +467,18 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                         import asyncio
                         loop = asyncio.new_event_loop()
                         try:
-                            restored = loop.run_until_complete(
-                                minio.restore_from_minio(self, self._user_id))
-                            workspace_restored = restored > 0
-                            SYLogger.info(
-                                f"[Sandbox] MinIO 恢复完成: {restored} 个文件")
+                            try:
+                                # 🔑 restore 任何异常（含 MINIO_RESTORE_MAX_BYTES 字节上限提前结束）
+                                # 都绝不阻断故障转移切换——这里吞掉异常只记日志，
+                                # 会话末尾的全量扫描会兜底补齐缺失文件。
+                                restored = loop.run_until_complete(
+                                    minio.restore_from_minio(self, self._user_id))
+                                workspace_restored = restored > 0
+                                SYLogger.info(
+                                    f"[Sandbox] MinIO 恢复完成: {restored} 个文件")
+                            except Exception as re:
+                                SYLogger.warning(
+                                    f"[Sandbox] MinIO 恢复异常(不阻断切换): {re}")
                         finally:
                             # restore_from_minio 复用了共享 backend self，内部经
                             # aupload_files -> _get_async_session() 的 loop 不匹配逻辑，
@@ -494,7 +501,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                             loop.close()
                 except Exception as e:
                     SYLogger.warning(
-                        f"[Sandbox] MinIO 恢复失败: {e}")
+                        f"[Sandbox] MinIO 恢复失败(不阻断切换): {e}")
 
                 if not workspace_restored:
                     SYLogger.info(
@@ -544,13 +551,13 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
         last_exc: Optional[Exception] = None
 
         url = f"{self._base_url}{endpoint}"
-        SYLogger.info(
+        SYLogger.debug(
             f"[Sandbox] POST 请求开始: {url}, timeout={http_timeout}s, command_timeout={actual_timeout}s")
 
         skip_in_place = False
         for attempt in range(max_retries):
             try:
-                SYLogger.info(
+                SYLogger.debug(
                     f"[Sandbox] POST 尝试 {attempt + 1}/{max_retries}: {url}")
                 resp = requests.post(
                     url,
@@ -558,13 +565,13 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                     headers=headers if headers else None,
                     timeout=http_timeout
                 )
-                SYLogger.info(f"[Sandbox] POST 响应状态码: {resp.status_code}")
+                SYLogger.debug(f"[Sandbox] POST 响应状态码: {resp.status_code}")
                 if resp.status_code >= 400:
                     SYLogger.error(
                         f"[Sandbox] HTTP 错误 {resp.status_code}: {resp.text}")
                     resp.raise_for_status()
                 result = resp.json()
-                SYLogger.info(f"[Sandbox] POST 成功: {url}")
+                SYLogger.debug(f"[Sandbox] POST 成功: {url}")
                 return result
 
             except (requests.exceptions.RequestException, requests.exceptions.HTTPError) as e:
@@ -626,13 +633,13 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
         headers = self._build_headers()
 
         url = f"{self._base_url}{endpoint}"
-        SYLogger.info(
+        SYLogger.debug(
             f"[Sandbox] Async POST 请求开始: {url}, timeout={http_timeout}s")
 
         timeout_obj = aiohttp.ClientTimeout(total=http_timeout)
         session = await self._get_async_session()
         async with session.post(url, json=data, headers=headers, timeout=timeout_obj) as resp:
-            SYLogger.info(f"[Sandbox] Async POST 响应状态码: {resp.status}")
+            SYLogger.debug(f"[Sandbox] Async POST 响应状态码: {resp.status}")
             if resp.status >= 500:
                 text = await resp.text()
                 SYLogger.error(f"[Sandbox] 服务端错误 {resp.status}: {text}")
@@ -644,7 +651,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                 SYLogger.error(f"[Sandbox] HTTP 错误 {resp.status}: {text}")
                 resp.raise_for_status()
             result = await resp.json()
-            SYLogger.info(f"[Sandbox] Async POST 成功: {url}")
+            SYLogger.debug(f"[Sandbox] Async POST 成功: {url}")
             return result
 
     async def _post_async_with_failover(self, endpoint: str, data: dict, timeout: int = None) -> dict:
@@ -806,9 +813,9 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
     def execute(self, command: str, *, timeout: int = None) -> ExecuteResponse:
         """执行 shell 命令（服务端负责路径隔离和目录初始化）"""
         command = self._inject_env(command)
-        SYLogger.info(f"[Sandbox] execute 开始: command={command}")
+        SYLogger.debug(f"[Sandbox] execute 开始: command={command}")
         self._ensure_synced_sync()
-        SYLogger.info(f"[Sandbox] _ensure_synced_sync 完成，开始执行命令: {command}")
+        SYLogger.debug(f"[Sandbox] _ensure_synced_sync 完成，开始执行命令: {command}")
         try:
             result = self._post_sync(f"{SANDBOX_API_PREFIX}/execute", {
                 "command": command.strip(),
@@ -820,7 +827,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                 exit_code=result["exit_code"],
                 truncated=result.get("truncated", False)
             )
-            SYLogger.info(
+            SYLogger.debug(
                 f"[Sandbox] 执行完成: exit_code={response.exit_code}, output={response.output[:500] if response.output else 'None'}...")
             return response
         except Exception as e:
@@ -841,14 +848,14 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
         避免删前先传、比对前先传的往返浪费）。
         """
         command = self._inject_env(command)
-        SYLogger.info(f"[Sandbox] aexecute 开始: command={command}")
+        SYLogger.debug(f"[Sandbox] aexecute 开始: command={command}")
 
         # 按需懒同步：检测命令中是否引用了 skill 资源
         if not _skip_lazy_sync:
             await self._lazy_sync_skill_from_path(command)
 
         await self._ensure_synced_async()
-        SYLogger.info(f"[Sandbox] _ensure_synced_async 完成，开始执行命令: {command}")
+        SYLogger.debug(f"[Sandbox] _ensure_synced_async 完成，开始执行命令: {command}")
         try:
             result = await self._post_async_with_failover(f"{SANDBOX_API_PREFIX}/execute", {
                 "command": command.strip(),
@@ -860,7 +867,7 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
                 exit_code=result["exit_code"],
                 truncated=result.get("truncated", False)
             )
-            SYLogger.info(f"[Sandbox] 异步执行完成: exit_code={response.exit_code}")
+            SYLogger.debug(f"[Sandbox] 异步执行完成: exit_code={response.exit_code}")
             return response
         except Exception as e:
             SYLogger.error(f"[Sandbox] 异步执行异常: {e}")
@@ -1190,10 +1197,31 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
         return results
 
     async def adownload_files(self, paths: List[str], *, timeout: int = None) -> List[FileDownloadResponse]:
-        """异步下载多个文件（真正的异步实现）"""
+        """异步下载多个文件（真正的异步实现）
+
+        🔑 OOM 兜底：每个文件下载前先 astat 拿 size（只查 size 不读内容），
+        超 MAX_DOWNLOAD_BYTES 直接返回 error，避免整包读 + base64 解码把全量拉进内存。
+        astat 异常 fail-open（warning 后继续下载）。
+        """
+        from sycommon.agent.sandbox.file_ops import MAX_DOWNLOAD_BYTES
         results = []
         for path in paths:
             try:
+                # 大小预检：超限直接拒绝，不下载
+                try:
+                    st = await self.astat(path=path)
+                    if st and not getattr(st, "error", None) and getattr(st, "exists", False):
+                        fsize = getattr(st, "size", 0) or 0
+                        if fsize > MAX_DOWNLOAD_BYTES:
+                            cap_mb = MAX_DOWNLOAD_BYTES // (1024 * 1024)
+                            SYLogger.warning(f"[Sandbox] 文件过大拒绝下载: {path}, size={fsize}")
+                            results.append(FileDownloadResponse(
+                                path=path,
+                                error=f"file too large ({fsize // (1024*1024)}MB > {cap_mb}MB)"))
+                            continue
+                except Exception as se:
+                    SYLogger.warning(f"[Sandbox] astat 预检失败(继续下载): {se}")
+
                 result = await self._post_async_with_failover(
                     f"{SANDBOX_API_PREFIX}/download",
                     {"path": path, "user_id": self._user_id},