sycommon-python-lib 0.2.7a3__tar.gz → 0.2.7a5__tar.gz

{sycommon_python_lib-0.2.7a3 → sycommon_python_lib-0.2.7a5}/PKG-INFO

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

{sycommon_python_lib-0.2.7a3 → sycommon_python_lib-0.2.7a5}/pyproject.toml

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

{sycommon_python_lib-0.2.7a3 → sycommon_python_lib-0.2.7a5}/src/sycommon/agent/deep_agent.py

@@ -50,6 +50,7 @@ from langchain_core.tools import BaseTool, tool
 
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.tools.snowflake import Snowflake
+from sycommon.tools.env import check_env_flag
 from sycommon.llm.get_llm import get_llm
 from sycommon.agent.sandbox.http_sandbox_backend import HTTPSandboxBackend
 from sycommon.agent.sandbox.sandbox_recovery import SandboxRecoveryManager
@@ -59,6 +60,11 @@ from sycommon.middleware.tool_result_truncation import ToolResultTruncationMiddl
 from deepagents.middleware.summarization import create_summarization_tool_middleware  # noqa: F401 保留 re-export
 from sycommon.agent.summarization_utils import build_summarization_middleware
 
+# 流式逐 token 诊断日志开关（默认关）。开启后每个 chunk 都打印
+# chunk_type/content 等（仅供排障）。LLM 最终结果已由 LLMLogger.on_llm_end
+# 统一记录，正常无需打开此开关，避免流式日志刷屏。
+_STREAM_DEBUG = check_env_flag(['DEEP_AGENT_STREAM_DEBUG'], default='false')
+
 if TYPE_CHECKING:
     from deepagents.graph import CompiledStateGraph
     from langchain.agents.middleware.types import AgentState, ContextT, ModelRequest, ModelResponse, ResponseT
@@ -465,38 +471,27 @@ class DeepAgent:
             input_state = {"messages": [HumanMessage(content=message)]}
             if rubric:
                 input_state["rubric"] = rubric
-            print(
-                f"[DeepAgent] chat() starting stream, message={repr(message[:80])}", flush=True)
+            if _STREAM_DEBUG:
+                print(
+                    f"[DeepAgent] chat() starting stream, message={repr(message[:80])}", flush=True)
             async for chunk in self._astream_with_retry(
                 input_state,
                 max_retries=3,
                 base_delay=1.0,
             ):
-                # 🔑 详细打印 chunk 内容
-                _chunk_len = len(chunk) if isinstance(chunk, tuple) else '?'
-                if isinstance(chunk, tuple) and _chunk_len == 2:
-                    # 2-tuple: either (namespace, (msg, meta)) or (msg, meta)
-                    if isinstance(chunk[1], tuple) and len(chunk[1]) == 2:
-                        _ns = repr(chunk[0])[:30]
-                        _msg = chunk[1][0]
-                        _meta = chunk[1][1]
-                    else:
-                        _ns = '()'
-                        _msg = chunk[0]
-                        _meta = chunk[1]
-                    _msg_type = type(_msg).__name__
-                    _content = repr(str(getattr(_msg, 'content', ''))[:80])
-                    _node = _meta.get('langgraph_node', '?') if isinstance(
-                        _meta, dict) else '?'
-                    _step = _meta.get('langgraph_step', '?') if isinstance(
-                        _meta, dict) else '?'
-                    print(
-                        f"[DeepAgent] 2tuple: ns={_ns} msg={_msg_type} node={_node} step={_step} content={_content}", flush=True)
-                elif isinstance(chunk, tuple) and _chunk_len == 3:
-                    namespace_p, _tag_p, payload_p = chunk
-                    if isinstance(payload_p, tuple) and len(payload_p) == 2:
-                        _msg = payload_p[0]
-                        _meta = payload_p[1]
+                # 🔑 逐 token 诊断日志：仅在 DEEP_AGENT_STREAM_DEBUG=true 时打印
+                if _STREAM_DEBUG:
+                    _chunk_len = len(chunk) if isinstance(chunk, tuple) else '?'
+                    if isinstance(chunk, tuple) and _chunk_len == 2:
+                        # 2-tuple: either (namespace, (msg, meta)) or (msg, meta)
+                        if isinstance(chunk[1], tuple) and len(chunk[1]) == 2:
+                            _ns = repr(chunk[0])[:30]
+                            _msg = chunk[1][0]
+                            _meta = chunk[1][1]
+                        else:
+                            _ns = '()'
+                            _msg = chunk[0]
+                            _meta = chunk[1]
                         _msg_type = type(_msg).__name__
                         _content = repr(str(getattr(_msg, 'content', ''))[:80])
                         _node = _meta.get('langgraph_node', '?') if isinstance(
@@ -504,13 +499,26 @@ class DeepAgent:
                         _step = _meta.get('langgraph_step', '?') if isinstance(
                             _meta, dict) else '?'
                         print(
-                            f"[DeepAgent] 3tuple: ns={repr(namespace_p)[:30]} msg={_msg_type} node={_node} step={_step} content={_content}", flush=True)
+                            f"[DeepAgent] 2tuple: ns={_ns} msg={_msg_type} node={_node} step={_step} content={_content}", flush=True)
+                    elif isinstance(chunk, tuple) and _chunk_len == 3:
+                        namespace_p, _tag_p, payload_p = chunk
+                        if isinstance(payload_p, tuple) and len(payload_p) == 2:
+                            _msg = payload_p[0]
+                            _meta = payload_p[1]
+                            _msg_type = type(_msg).__name__
+                            _content = repr(str(getattr(_msg, 'content', ''))[:80])
+                            _node = _meta.get('langgraph_node', '?') if isinstance(
+                                _meta, dict) else '?'
+                            _step = _meta.get('langgraph_step', '?') if isinstance(
+                                _meta, dict) else '?'
+                            print(
+                                f"[DeepAgent] 3tuple: ns={repr(namespace_p)[:30]} msg={_msg_type} node={_node} step={_step} content={_content}", flush=True)
+                        else:
+                            print(
+                                f"[DeepAgent] 3tuple: payload_type={type(payload_p).__name__}", flush=True)
                     else:
                         print(
-                            f"[DeepAgent] 3tuple: payload_type={type(payload_p).__name__}", flush=True)
-                else:
-                    print(
-                        f"[DeepAgent] chunk: type={type(chunk).__name__}", flush=True)
+                            f"[DeepAgent] chunk: type={type(chunk).__name__}", flush=True)
                 # 检查取消
                 if cancel_event and cancel_event.is_set():
                     event = ChatEventBuilder.cancelled("任务已取消")
@@ -541,22 +549,23 @@ class DeepAgent:
 
                 stream_step += 1
 
-                # ===== 🔑 诊断日志：详细记录每个 chunk =====
-                _chunk_type = type(chunk).__name__
-                _msg_type = getattr(
-                    msg, '__class__.__name__', '?') if msg else 'None'
-                _ns = namespace if namespace else '()'
-                _node = metadata.get(
-                    "langgraph_node", "?") if metadata else "?"
-                _step = metadata.get(
-                    "langgraph_step", "?") if metadata else "?"
-                _content_preview = ""
-                if isinstance(msg, BaseMessage):
-                    _c = msg.content or ""
-                    _content_preview = repr(_c[:80]) if _c else "(empty)"
-                SYLogger.info(
-                    f"[DeepAgent #{stream_step}] chunk_type={_chunk_type} msg_type={_msg_type} "
-                    f"ns={_ns} node={_node} step={_step} content={_content_preview}")
+                # ===== 逐 chunk 诊断日志：默认关闭，DEEP_AGENT_STREAM_DEBUG=true 时开启 =====
+                if _STREAM_DEBUG:
+                    _chunk_type = type(chunk).__name__
+                    _msg_type = getattr(
+                        msg, '__class__.__name__', '?') if msg else 'None'
+                    _ns = namespace if namespace else '()'
+                    _node = metadata.get(
+                        "langgraph_node", "?") if metadata else "?"
+                    _step = metadata.get(
+                        "langgraph_step", "?") if metadata else "?"
+                    _content_preview = ""
+                    if isinstance(msg, BaseMessage):
+                        _c = msg.content or ""
+                        _content_preview = repr(_c[:80]) if _c else "(empty)"
+                    SYLogger.info(
+                        f"[DeepAgent #{stream_step}] chunk_type={_chunk_type} msg_type={_msg_type} "
+                        f"ns={_ns} node={_node} step={_step} content={_content_preview}")
 
                 # ===== 日志（仅关键节点） =====
                 if isinstance(msg, BaseMessage):
@@ -653,12 +662,14 @@ class DeepAgent:
                         await on_event(event)
                     yield event
 
-                print(
-                    f"[DeepAgent] post-yield: msg_type={type(msg).__name__}, is_BaseMessage={isinstance(msg, BaseMessage)}", flush=True)
+                if _STREAM_DEBUG:
+                    print(
+                        f"[DeepAgent] post-yield: msg_type={type(msg).__name__}, is_BaseMessage={isinstance(msg, BaseMessage)}", flush=True)
 
                 if not isinstance(msg, BaseMessage):
-                    print(
-                        f"[DeepAgent] SKIPPING non-BaseMessage: {type(msg).__name__}", flush=True)
+                    if _STREAM_DEBUG:
+                        print(
+                            f"[DeepAgent] SKIPPING non-BaseMessage: {type(msg).__name__}", flush=True)
                     continue
 
                 msg_type = msg.__class__.__name__
@@ -899,8 +910,9 @@ class DeepAgent:
                 SYLogger.debug(
                     f"[DeepAgent] AI chunk done | {repr(ai_chunk_buffer[:100])}...")
 
-            print(
-                f"[DeepAgent] FOR LOOP ENDED. stream_step={stream_step}, ai_text_content={repr(ai_text_content[:100])}, tool_calls={len(current_tool_calls)}", flush=True)
+            if _STREAM_DEBUG:
+                print(
+                    f"[DeepAgent] FOR LOOP ENDED. stream_step={stream_step}, ai_text_content={repr(ai_text_content[:100])}, tool_calls={len(current_tool_calls)}", flush=True)
 
             # 空响应检测：模型被调用但没有产出任何文本
             if not ai_text_content and not ai_chunk_buffer:
@@ -1000,8 +1012,9 @@ class DeepAgent:
             while True:
                 for attempt in range(max_retries):
                     try:
-                        print(
-                            f"[DeepAgent] _astream_with_retry: attempt={attempt}, starting astream...", flush=True)
+                        if _STREAM_DEBUG:
+                            print(
+                                f"[DeepAgent] _astream_with_retry: attempt={attempt}, starting astream...", flush=True)
                         chunk_count = 0
                         async for chunk in self.agent.astream(
                             input_data,
@@ -1010,13 +1023,16 @@ class DeepAgent:
                             subgraphs=True
                         ):
                             chunk_count += 1
-                            print(
-                                f"[DeepAgent] _astream yielding chunk #{chunk_count}", flush=True)
+                            if _STREAM_DEBUG:
+                                print(
+                                    f"[DeepAgent] _astream yielding chunk #{chunk_count}", flush=True)
                             yield chunk
+                            if _STREAM_DEBUG:
+                                print(
+                                    f"[DeepAgent] _astream yield returned, consumer processed chunk #{chunk_count}", flush=True)
+                        if _STREAM_DEBUG:
                             print(
-                                f"[DeepAgent] _astream yield returned, consumer processed chunk #{chunk_count}", flush=True)
-                        print(
-                            f"[DeepAgent] _astream_with_retry: stream ended normally, total_chunks={chunk_count}", flush=True)
+                                f"[DeepAgent] _astream_with_retry: stream ended normally, total_chunks={chunk_count}", flush=True)
                         return
                     except BadRequestError as e:
                         # BadRequestError（含 ContextOverflowError）不重试：
@@ -1191,6 +1207,16 @@ async def create_deep_agent(
             on_evaluation=rubric_eval_collector.on_evaluation,
         ))
 
+    # SkillApiWhitelistMiddleware：按子技能注入接口白名单（拦 execute 工具，
+    # export SKILL_API_WHITELIST + 推送 sitecustomize 到沙箱做 path 级校验）
+    if sandbox_backend:
+        try:
+            from sycommon.agent.middleware.skill_api_whitelist import (
+                SkillApiWhitelistMiddleware)
+            middleware_list.append(SkillApiWhitelistMiddleware(sandbox_backend))
+        except Exception as _wl_err:
+            SYLogger.warning(f"[DeepAgent] 技能接口白名单中间件加载失败(忽略): {_wl_err}")
+
     agent_kwargs = {
         "model": raw_model,
         "tools": config.tools or [get_current_date],

sycommon_python_lib-0.2.7a5/src/sycommon/agent/middleware/sitecustomize.py

@@ -0,0 +1,146 @@
+"""技能接口白名单客户端注入脚本（部署到沙箱 site-packages）。
+
+Python 解释器启动时（未传 -S）自动 import 本模块。它负责 Python HTTP 库的
+请求拦截：
+
+  1. 读环境变量 SKILL_API_WHITELIST（JSON）。无此 env → 不管控（全放行，fail-open）。
+  2. monkeypatch urllib / httpx / requests / aiohttp，发请求前做 path 级前缀匹配，
+     未命中抛 PermissionError（LLM 能看到清晰错误）。
+
+  ⚠️ shell 命令（curl/wget 等）的拦截【不】在本文件处理——sitecustomize 只在
+     `python` 启动时执行，纯 shell 命令不会触发它。shell 拦截由主进程中间件把
+     curl/wget 包装函数【内联】到每条 execute 命令前缀实现（见 skill_api_whitelist.py）。
+
+URL 匹配核心逻辑复用同目录 skill_wl_check.py。
+
+注意：本模块在沙箱子进程里运行，不依赖主进程内存。白名单数据全部来自环境变量。
+"""
+
+import json
+import os
+import sys
+
+# SKILL_API_WHITELIST 存在即「启用管控」；allowlist 为空时「全拦截」。
+_ENABLED = "SKILL_API_WHITELIST" in os.environ
+
+# 把沙箱 site-packages 里存放本模块的目录加入 sys.path，以便 import skill_wl_check。
+_HERE = os.path.dirname(os.path.abspath(__file__))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+
+def _load_check():
+    """加载同目录 skill_wl_check，返回其 match 函数；失败返回 None。"""
+    try:
+        import skill_wl_check  # type: ignore
+        return skill_wl_check
+    except Exception as e:  # pragma: no cover
+        sys.stderr.write("[sitecustomize] 加载 skill_wl_check 失败，白名单禁用: %s\n" % e)
+        return None
+
+
+def _patch_urllib(match):
+    import urllib.request
+
+    _orig = urllib.request.urlopen
+
+    def _urlopen(url, *args, **kwargs):
+        actual = url.full_url if isinstance(url, urllib.request.Request) else url
+        if actual and not match(str(actual)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (urlopen, %s)" % actual)
+        return _orig(url, *args, **kwargs)
+
+    urllib.request.urlopen = _urlopen
+
+
+def _patch_httpx(match):
+    try:
+        import httpx
+    except ImportError:
+        return
+
+    _orig_sync = httpx.Client.send
+
+    def _send(self, request, **kwargs):
+        if not match(str(request.url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (httpx, %s)" % request.url)
+        return _orig_sync(self, request, **kwargs)
+
+    httpx.Client.send = _send
+
+    if hasattr(httpx, "AsyncClient"):
+        _orig_async = httpx.AsyncClient.send
+
+        async def _asend(self, request, **kwargs):
+            if not match(str(request.url)):
+                raise PermissionError(
+                    "[SkillApiWhitelist] 拦截: URL 不在白名单内 (httpx.async, %s)" % request.url)
+            return await _orig_async(self, request, **kwargs)
+
+        httpx.AsyncClient.send = _asend
+
+
+def _patch_requests(match):
+    try:
+        import requests
+    except ImportError:
+        return
+
+    _orig = requests.Session.request
+
+    def _request(self, method, url, *args, **kwargs):
+        if not match(str(url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (requests %s, %s)"
+                % (method.upper(), url))
+        return _orig(self, method, url, *args, **kwargs)
+
+    requests.Session.request = _request
+
+
+def _patch_aiohttp(match):
+    try:
+        import aiohttp
+    except ImportError:
+        return
+    if not hasattr(aiohttp.ClientSession, "_request"):
+        return
+
+    _orig = aiohttp.ClientSession._request
+
+    async def _request(self, method, str_or_url, **kwargs):
+        if not match(str(str_or_url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (aiohttp %s, %s)"
+                % (method, str_or_url))
+        return await _orig(self, method, str_or_url, **kwargs)
+
+    aiohttp.ClientSession._request = _request
+
+
+def _install():
+    if not _ENABLED:
+        return
+    check = _load_check()
+    if check is None:
+        return
+    # allowlist 为空（明确禁止）时也走校验——match 必然 False，从而全拦截。
+    match = check.match
+    _patch_urllib(match)
+    _patch_httpx(match)
+    _patch_requests(match)
+    _patch_aiohttp(match)
+
+
+# 保留解析结果（供排查）
+try:
+    _WHITELIST_RAW = json.loads(os.environ.get("SKILL_API_WHITELIST", "{}"))
+except Exception:
+    _WHITELIST_RAW = {}
+
+try:
+    _install()
+except Exception as _e:  # 任何 patch 失败都不能阻断进程启动
+    sys.stderr.write("[sitecustomize] 白名单安装失败（fail-open）: %s\n" % _e)

sycommon_python_lib-0.2.7a5/src/sycommon/agent/middleware/skill_api_whitelist.py

@@ -0,0 +1,253 @@
+"""技能接口白名单中间件。
+
+拦截 `execute` 工具（FilesystemMiddleware 注册的 shell 执行工具），做两件事：
+
+1. 从命令路径推断子技能名（skills/<域>/<子技能>/scripts/ → <子技能>），
+   查 SkillApiWhitelist 配置得到该子技能的白名单，把占位符 ${VAR} 在主进程
+   解析成完整 URL，序列化成 JSON 后以 `export SKILL_API_WHITELIST='<json>'`
+   前缀注入命令——供沙箱内 sitecustomize.py 读取并 monkeypatch urllib/
+   httpx/requests/aiohttp。
+
+2. 命令前缀内联 curl/wget 的 shell 函数包装：纯 shell 命令（不走 Python）
+   不会触发 sitecustomize，故用 shell 函数在执行 curl/wget 前调
+   `python -m skill_wl_check <url>` 做校验，未命中则 return 1 拦截。
+
+3. 首次惰性把 sitecustomize.py + skill_wl_check.py 推进沙箱 site-packages，
+   使 Python 启动时自动 import sitecustomize。
+
+语义：子技能未配置 / enabled:false → 不注入（全放行，向后兼容）；
+allowlist:[] 空数组 → 注入空白名单（全拦截）。
+"""
+
+import json
+import os
+import re
+import shlex
+from typing import Optional
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langgraph.prebuilt.tool_node import ToolCallRequest
+
+from sycommon.logging.kafka_log import SYLogger
+
+# 命令路径形如  skills/sy-oa-skill/workflow-todo/scripts/x.py
+#               skills/sy-syt-skill/shengye-platform-zhongdeng/SKILL.md
+#               skills/sy-syt-skill/generate-plan/...     （有/无 scripts/ 都识别）
+# 取「skills/<域>/<子技能>/」的第二段作子技能名，不限 scripts/，覆盖文档目录型子技能。
+# 用 (?:/|$) 锚定第二段结尾，避免误吞后续路径段。
+_SKILL_NESTED_RE = re.compile(r'skills/[A-Za-z0-9_\-]+/([A-Za-z0-9_\-]+)(?:/|$)')
+_SKILL_FLAT_RE = re.compile(r'/skills/([A-Za-z0-9_\-]+)(?:/|$)')
+
+# BASE_URL 占位符 ${VAR}
+_PLACEHOLDER_RE = re.compile(r'\$\{([A-Z_][A-Z0-9_]*)\}')
+
+# 推送到沙箱 workspace 内的 .wl 目录（沙箱强制路径隔离，绝对路径会被映射进 workspace，
+# 故用相对 POSIX 路径，落地为 {workspace}/.wl/，再 export PYTHONPATH 让 Python 自动 import）
+_PUSH_FILES = [
+    ("sitecustomize.py", ".wl/sitecustomize.py"),
+    ("skill_wl_check.py", ".wl/skill_wl_check.py"),
+]
+# workspace 内白名单目录的 shell 形式（init_script 已 export $_SANDBOX_WORKSPACE，运行期展开）
+_WL_DIR = "$_SANDBOX_WORKSPACE/.wl"
+
+
+def _resolve_placeholders(pattern: str, env_lookup) -> Optional[str]:
+    """把 ${VAR} 替换为解析后的值。任一 VAR 不存在返回 None（配置错误）。
+
+    env_lookup: callable(var_name) -> str|None。中间件传入「先查主进程 os.environ，
+    再查 sandbox env 字典（含 SYT_BASE_URL 等运行时算出/从 Nacos 读出的值）」的查找器。
+    """
+    missing = []
+
+    def _sub(m):
+        val = env_lookup(m.group(1))
+        if val is None:
+            missing.append(m.group(1))
+            return ""
+        return str(val).rstrip("/")
+
+    expanded = _PLACEHOLDER_RE.sub(_sub, pattern)
+    if missing:
+        SYLogger.warning(
+            "[Whitelist] 占位符未定义 %s，丢弃规则 %s", missing, pattern)
+        return None
+    return expanded
+
+
+def _load_resource_bytes(filename: str) -> bytes:
+    """从本包读取注入脚本源码（package_data）。"""
+    try:
+        from importlib.resources import files
+        return (files("sycommon.agent.middleware").joinpath(filename).read_bytes())
+    except Exception as e:
+        raise RuntimeError(
+            f"读取注入脚本 {filename} 失败，请确认已随包安装(package_data): {e}") from e
+
+
+def _build_shell_guard() -> str:
+    """生成内联到命令前缀的 curl/wget 包装函数（shell）。
+
+    在 SKILL_API_WHITELIST 已 export 的命令里生效：调用 curl/wget 前先抽取
+    参数里首个 http(s) URL，用沙箱 python3 调 skill_wl_check.match 校验，
+    未命中则 return 1 拦截。skill_wl_check 与 sitecustomize 同处 site-packages，
+    python3 启动时 sitecustomize 会 import 它并把该目录加入 sys.path。
+
+    覆盖 curl / wget；其它 shell 出网方式(nc/裸 /dev/tcp 等)不覆盖。
+    """
+    check_cmd = (
+        'python3 -c \'import skill_wl_check,sys; '
+        'sys.exit(0 if skill_wl_check.match(sys.argv[1]) else 1)\' "$_u"'
+    )
+    # 单个命令的函数体模板：抽取 URL → 校验 → 通过则 command <CMD> "$@"
+    body = (
+        '() { local _u; for _a in "$@"; do '
+        'case "$_a" in http://*|https://*) _u="$_a";; esac; done; '
+        f'if [ -n "$_u" ] && ! {check_cmd}; then '
+        'echo "[SkillApiWhitelist] 拦截 shell 请求: $_u" 1>&2; return 1; fi; '
+        'command {CMD} "$@"; };'
+    )
+    guard = "curl" + body.replace("{CMD}", "curl") + " wget" + body.replace("{CMD}", "wget")
+    return guard.rstrip(";")  # 末尾不带分号：由调用方按需拼接分隔符
+
+
+class SkillApiWhitelistMiddleware(AgentMiddleware):
+    """按子技能动态注入接口白名单环境变量 + shell 包装。
+
+    AgentMiddleware 协议钩子：实现 `awrap_tool_call`（异步版本），在 execute
+    工具真正执行前注入白名单。框架对工具调用走 astream/ainvoke 异步链路，故
+    只需实现异步钩子（与现有 TokenTrackingMiddleware/ToolResultTruncationMiddleware 一致）。
+    """
+
+    def __init__(self, sandbox_backend):
+        self._backend = sandbox_backend
+        self._pushed: bool = False  # 注入脚本是否已推送（每 backend 实例一次）
+
+    def _env_lookup(self):
+        """构造占位符查找器：先查主进程 os.environ，再查 sandbox env 字典。
+
+        SYT_BASE_URL / XINGHAN_BASE_URL / YEALINK_BASE_URL 等不在主进程 os.environ 里，
+        而是放在传给 sandbox backend 的 env 字典中（tools/config.py.build_sandbox_env 构造）。
+        MultiSandboxRouter/HTTPSandboxBackend 都暴露 `_env`，这里统一兜底取值。
+        """
+        sandbox_env = {}
+        b = self._backend
+        for attr in ("_env",):
+            v = getattr(b, attr, None)
+            if isinstance(v, dict):
+                sandbox_env.update(v)
+            else:
+                # RoutingBackend 等代理对象：尝试 default/local/remote 子 backend
+                pass
+        # 再尝试 default backend（MultiSandboxRouter._default._env）
+        default = getattr(b, "_default", None)
+        if default is not None:
+            v = getattr(default, "_env", None)
+            if isinstance(v, dict):
+                sandbox_env.update(v)
+
+        def lookup(var):
+            val = os.environ.get(var)
+            if val is None:
+                val = sandbox_env.get(var)
+            return val
+
+        return lookup
+
+    # ---- 懒加载:把注入脚本推进沙箱 workspace/.wl ----
+    async def _ensure_sitecustomize(self) -> bool:
+        """把 sitecustomize.py + skill_wl_check.py 推到沙箱 workspace 内的 .wl 目录。
+
+        沙箱强制路径隔离：任何绝对路径都会被 resolve_sandbox_path 映射进用户 workspace，
+        真实 site-packages 无法写入。故改用「推到 workspace/.wl/ + export PYTHONPATH」
+        的方案：Python 启动时若 .wl 在 PYTHONPATH 上，会自动 import sitecustomize。
+
+        幂等：每个 backend 实例只推一次（_pushed 标记）。失败 fail-open（不阻塞业务）。
+        """
+        if self._pushed:
+            return True
+        backend = self._backend
+        if backend is None:
+            return False
+        try:
+            files = []
+            for src, dst in _PUSH_FILES:
+                content = _load_resource_bytes(src)
+                files.append((dst, content))
+            await backend.aupload_files(files)
+            self._pushed = True
+            SYLogger.info("[Whitelist] 注入脚本已推送至沙箱 %s", _WL_DIR)
+            return True
+        except Exception as e:
+            SYLogger.error("[Whitelist] 推送 sitecustomize 失败(fail-open): %s", e)
+            return False
+
+    # ---- 子技能名提取 ----
+    def _extract_skill_name(self, command: str) -> Optional[str]:
+        m = _SKILL_NESTED_RE.search(command)
+        if m:
+            return m.group(1)
+        m = _SKILL_FLAT_RE.search(command)
+        if m:
+            return m.group(1)
+        return None
+
+    # ---- 主入口（AgentMiddleware 异步钩子）----
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler,
+    ):
+        tc = request.tool_call
+        if tc.get("name") != "execute":
+            return await handler(request)
+
+        args = tc.get("args", {}) or {}
+        command = args.get("command", "") if isinstance(args, dict) else ""
+        if not command:
+            return await handler(request)
+
+        skill_name = self._extract_skill_name(command)
+        if skill_name is None:
+            # 非技能命令（无 skills/.../scripts/）→ 不管控
+            return await handler(request)
+
+        # 延迟导入避免模块加载期循环依赖
+        from sycommon.config.SkillApiWhitelistConfig import SkillApiWhitelistConfig
+        cfg = SkillApiWhitelistConfig.from_config(skill_name)
+        if cfg is None or not cfg.enabled:
+            # 未配置 / 禁用 → 全放行（向后兼容）
+            return await handler(request)
+
+        # 主进程解析占位符 ${VAR}（数据源：os.environ + sandbox env 字典）
+        env_lookup = self._env_lookup()
+        resolved = []
+        for pat in cfg.allowlist:
+            if "${" in pat:
+                expanded = _resolve_placeholders(pat, env_lookup)
+                if expanded:
+                    resolved.append(expanded)
+            else:
+                resolved.append(pat)
+
+        # 推送注入脚本（惰性，每后端实例一次）
+        await self._ensure_sitecustomize()
+
+        # 序列化白名单 + PYTHONPATH(shell 启动 python 时自动 import sitecustomize)
+        # + shell guard(curl/wget 拦截) + export SKILL_API_WHITELIST
+        payload = json.dumps({"skill": skill_name, "allowlist": resolved},
+                             ensure_ascii=False)
+        guard = _build_shell_guard()
+        prefix_parts = [
+            f"export SKILL_API_WHITELIST={shlex.quote(payload)}",
+            f'export PYTHONPATH="{_WL_DIR}:$PYTHONPATH"',
+            guard,
+        ]
+        # 每个 part 之间用 '; ' 分隔（而非空格）—— export 语句之间、函数定义与后续命令
+        # 之间都需要语句分隔符；末尾留一个 ';' 与原命令隔开。
+        prefix = "; ".join(prefix_parts) + "; "
+
+        new_command = prefix + command
+        new_args = {**args, "command": new_command} if isinstance(args, dict) else args
+        new_tc = {**tc, "args": new_args}
+        SYLogger.info("[Whitelist] 注入子技能 %s 白名单(%d 条)", skill_name, len(resolved))
+        return await handler(request.override(tool_call=new_tc))