fix(pipelines): show the actual sandbox scope restriction

src/langbot/pkg/platform/sources/espl.py

@@ -1,587 +0,0 @@
-"""ESPL V3 adapter — WebSocket server for E-SP-Line2's Adapter Gateway (接入器).
-
-LangBot acts as a server-mode WebSocket endpoint. E-SP-Line2's adapter (接入器)
-in **client mode** connects to this endpoint (or a reverse proxy forwards it)
-and exchanges e-commerce messages:
-
-* **Inbound**  — E-SP-Line2 broadcasts ``message.received`` envelopes to every
-  connected adapter client. This adapter converts each envelope into a LangBot
-  ``FriendMessage`` / ``GroupMessage`` event (the ``conversation_id`` maps to
-  the LangBot launcher/session id) and fires it into the normal pipeline.
-* **Outbound** — every ``reply_message`` / ``reply_message_chunk`` the pipeline
-  emits is converted into an ESPL v3 outbound ``message`` frame
-  (``command_type: send_text``) and sent back over the WebSocket that carries
-  the matching conversation.
-
-Design notes:
-
-* Listens on ``ws://<host>:<port>/ws`` (default ``ws://127.0.0.1:8000/ws``).
-  In E-SP-Line2 create a **client-mode** 接入器 with ``ws_url`` pointing here.
-* Supports multiple simultaneous E-SP-Line2 connections. Each connection is
-  identified by its ``adapter_id`` (from the ``key``/path) so outbound replies
-  route back to the correct connection.
-* Heartbeats: responds to ``ping`` frames with ``pong``; the E-SP-Line2
-  gateway also sends server pings that we answer automatically via the
-  websockets library.
-* The ``conversation_id`` from the inbound envelope is used as the LangBot
-  launcher id so each e-commerce conversation maps 1:1 to an isolated LangBot
-  session. Replies are routed back to the same ``conversation_id``.
-* ``instance_id`` is captured from the inbound envelope and stashed on the
-  event's ``source_platform_object``.
-
-See docs/user-guide/adapter-gateway.md in the E-SP-Line2 repo for the full
-ESPL v3 protocol reference.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-import time
-import typing
-import uuid
-from datetime import datetime
-
-import pydantic
-import websockets
-
-import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platform_adapter
-import langbot_plugin.api.entities.builtin.platform.message as platform_message
-import langbot_plugin.api.entities.builtin.platform.events as platform_events
-import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
-import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
-
-logger = logging.getLogger(__name__)
-
-# Default listen host / port (E-SP-Line2 client-mode 接入器 connects here).
-_DEFAULT_HOST = '127.0.0.1'
-_DEFAULT_PORT = 8000
-# Default heartbeat ping interval (seconds).
-_DEFAULT_HEARTBEAT_INTERVAL = 30
-# Max inbound frame size (1MB, matches E-SP-Line2 gateway).
-_MAX_MESSAGE_SIZE = 1 * 1024 * 1024
-
-
-class _EsplConnection:
-    """A single connected E-SP-Line2 adapter gateway client.
-
-    Holds the WebSocket plus the routing info needed to reply.
-    """
-
-    def __init__(self, ws, adapter_id: str = ''):
-        self.ws = ws
-        self.adapter_id = adapter_id
-        self.send_lock = asyncio.Lock()
-
-    async def send_frame(self, frame: dict) -> None:
-        async with self.send_lock:
-            await self.ws.send(json.dumps(frame, ensure_ascii=False))
-
-
-class EsplAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
-    """ESPL V3 WebSocket server adapter (LangBot is the server)."""
-
-    bot_uuid: str = pydantic.Field(default='', exclude=True)
-
-    listeners: dict[
-        typing.Type[platform_events.Event],
-        typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
-    ] = pydantic.Field(default_factory=dict, exclude=True)
-
-    # WebSocket server state (excluded from pydantic serialization).
-    server: typing.Any = pydantic.Field(default=None, exclude=True)
-    running: bool = pydantic.Field(default=False, exclude=True)
-    connections: dict[str, '_EsplConnection'] = pydantic.Field(default_factory=dict, exclude=True)
-    inbound_tasks: set[asyncio.Task] = pydantic.Field(default_factory=set, exclude=True)
-    heartbeat_task: asyncio.Task | None = pydantic.Field(default=None, exclude=True)
-
-    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
-
-    def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger, **kwargs):
-        super().__init__(config=config, logger=logger, **kwargs)
-        self.bot_account_id = 'espl'
-        self.listeners = {}
-        self.server = None
-        self.running = False
-        self.connections = {}
-        self.inbound_tasks = set()
-        self.heartbeat_task = None
-
-    # -- framework hooks ------------------------------------------------------
-
-    def set_bot_uuid(self, bot_uuid: str) -> None:
-        """Called by the bot manager so the adapter knows its own bot uuid."""
-        object.__setattr__(self, 'bot_uuid', bot_uuid)
-
-    def get_launcher_id(self, event: platform_events.MessageEvent) -> str:
-        """Map an inbound event to a LangBot launcher id.
-
-        We use the e-commerce ``conversation_id`` (stashed on the sender id at
-        inbound time) so each conversation maps 1:1 to an isolated LangBot
-        session.
-        """
-        if isinstance(event, platform_events.GroupMessage):
-            return str(event.sender.group.id)
-        return str(event.sender.id)
-
-    def register_listener(
-        self,
-        event_type: typing.Type[platform_events.Event],
-        func: typing.Callable[
-            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], typing.Awaitable[None]
-        ],
-    ):
-        self.listeners[event_type] = func
-
-    def unregister_listener(
-        self,
-        event_type: typing.Type[platform_events.Event],
-        func: typing.Callable[
-            [platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], typing.Awaitable[None]
-        ],
-    ):
-        self.listeners.pop(event_type, None)
-
-    async def is_muted(self, group_id: int) -> bool:
-        return False
-
-    async def is_stream_output_supported(self) -> bool:
-        return False
-
-    # -- server lifecycle -----------------------------------------------------
-
-    async def run_async(self):
-        """Start the WebSocket server and serve forever."""
-        host = str(self.config.get('host', _DEFAULT_HOST))
-        port = int(self.config.get('port', _DEFAULT_PORT))
-        self.running = True
-
-        self.server = await websockets.serve(
-            self._handle_connection,
-            host,
-            port,
-            ping_interval=None,  # we manage heartbeats ourselves
-            max_size=_MAX_MESSAGE_SIZE,
-        )
-        await self.logger.info(f'ESPL adapter listening on ws://{host}:{port}/ws')
-
-        self.heartbeat_task = asyncio.create_task(self._heartbeat_loop())
-
-        try:
-            # Serve forever; run_async is expected to stay alive.
-            while self.running:
-                await asyncio.sleep(3600)
-        except asyncio.CancelledError:
-            raise
-        finally:
-            if self.server is not None:
-                self.server.close()
-                await self.server.wait_closed()
-                self.server = None
-
-    async def kill(self) -> bool:
-        """Stop the server and close all connections."""
-        self.running = False
-        if self.heartbeat_task is not None and not self.heartbeat_task.done():
-            self.heartbeat_task.cancel()
-            self.heartbeat_task = None
-        for task in list(self.inbound_tasks):
-            if not task.done():
-                task.cancel()
-        self.inbound_tasks.clear()
-        for conn in list(self.connections.values()):
-            try:
-                await conn.ws.close()
-            except Exception:
-                pass
-        self.connections.clear()
-        return True
-
-    # -- connection handler ---------------------------------------------------
-
-    async def _handle_connection(self, ws):
-        """Handle a new WebSocket connection from an E-SP-Line2 gateway client.
-
-        The E-SP-Line2 client-mode adapter connects with ``?key=<KEY>`` in the
-        query string.  If the adapter has been configured with a non-empty
-        ``key``, this method **rejects** connections that do not present a
-        matching key (close code 1008 — policy violation).
-
-        Note: websockets >= 14 removed the ``path`` / ``query_string``
-        attributes from the connection object.  The request path (including
-        the query string) is available via ``ws.request.path``.
-        """
-        # In websockets >= 14 the request path (with query string) lives on
-        # ``ws.request.path`` (e.g. ``/ws?key=abc``).  Fall back to the legacy
-        # ``ws.path`` / ``ws.query_string`` attributes for older versions.
-        request = getattr(ws, 'request', None)
-        if request is not None:
-            raw_path = str(getattr(request, 'path', '') or '')
-        else:
-            raw_path = str(getattr(ws, 'path', '') or '')
-        path, _, query = raw_path.partition('?')
-
-        # ── Key authentication ──────────────────────────────────────────
-        expected_key = str(self.config.get('key') or '')
-        provided_key = self._extract_key(query)
-        if expected_key:
-            if not provided_key:
-                await self.logger.warning(
-                    f'ESPL adapter key missing; closing connection from {raw_path}'
-                )
-                await ws.close(1008, 'Unauthorized: key missing')
-                return
-            if provided_key != expected_key:
-                await self.logger.warning(
-                    f'ESPL adapter key mismatch; closing connection from {raw_path}'
-                )
-                await ws.close(1008, 'Unauthorized: invalid key')
-                return
-
-        # ── Identify the connection for routing ─────────────────────────
-        adapter_id = self._extract_adapter_id(path, query)
-
-        conn = _EsplConnection(ws, adapter_id=adapter_id)
-        conn_key = adapter_id or ('conn_' + uuid.uuid4().hex)
-        self.connections[conn_key] = conn
-
-        await self.logger.info(
-            f'ESPL adapter client connected: adapter_id={adapter_id or "(client-mode, no adapter-id in path)"} '
-            f'path={raw_path}'
-        )
-
-        # ── Send the connected handshake ────────────────────────────────
-        try:
-            await conn.send_frame(
-                {
-                    'type': 'connected',
-                    'id': uuid.uuid4().hex,
-                    'timestamp': int(time.time() * 1000),
-                    'adapter_id': adapter_id or '',
-                    'gateway_version': 'v3',
-                    'session_id': conn_key,
-                    'adapter_name': self.config.get('name', 'ESPL'),
-                    'platform': self.config.get('platform', ''),
-                }
-            )
-        except Exception as e:
-            await self.logger.warning(f'ESPL adapter handshake failed: {e}')
-            self.connections.pop(conn_key, None)
-            return
-
-        # ── Read loop ───────────────────────────────────────────────────
-        try:
-            async for raw in ws:
-                try:
-                    frame = json.loads(raw)
-                except (json.JSONDecodeError, ValueError):
-                    await self.logger.warning(f'ESPL adapter received non-JSON frame: {raw[:200]}')
-                    continue
-                await self._handle_frame(conn, frame)
-        except websockets.exceptions.ConnectionClosed as e:
-            await self.logger.info(f'ESPL adapter client disconnected: {e.code} {e.reason}')
-        except asyncio.CancelledError:
-            raise
-        except Exception as e:
-            await self.logger.warning(f'ESPL adapter connection error: {e}')
-        finally:
-            self.connections.pop(conn_key, None)
-
-    @staticmethod
-    def _extract_adapter_id(path: str, query: str) -> str:
-        """Extract the adapter id from the connection path.
-
-        E-SP-Line2 client mode may connect to /ws/adapter-gateway/<id>?key=...
-        or a custom path /custom?key=... The adapter id is extracted from the
-        path segment, NOT from the key query parameter.
-        """
-        path_part = path.split('?', 1)[0]
-        if '/ws/adapter-gateway/' in path_part:
-            maybe_id = path_part.rsplit('/', 1)[-1]
-            if maybe_id and maybe_id not in ('ws', 'adapter-gateway'):
-                return maybe_id
-        # No adapter id in the path; return empty string (anonymous connection).
-        return ''
-
-    @staticmethod
-    def _extract_key(query: str) -> str:
-        """Extract the ``key`` query parameter from the WebSocket query string.
-
-        E-SP-Line2 client-mode adapter passes the access key as
-        ``?key=<KEY>`` in the WebSocket URL (see ``client_connector.go``
-        line 172-177).
-        """
-        for pair in query.split('&'):
-            if '=' in pair:
-                k, v = pair.split('=', 1)
-                if k == 'key':
-                    return v
-        return ''
-
-    async def _handle_frame(self, conn: _EsplConnection, frame: dict) -> None:
-        """Handle a single inbound frame from an E-SP-Line2 gateway client."""
-        msg_type = frame.get('type', '')
-        if msg_type == 'ping':
-            await conn.send_frame({'type': 'pong', 'timestamp': int(time.time() * 1000)})
-            return
-        if msg_type == 'pong':
-            return
-        if msg_type == 'ack':
-            return
-        if msg_type == 'error':
-            await self.logger.warning(f'ESPL adapter gateway error: {frame.get("code")} {frame.get("message")}')
-            return
-
-        # Inbound message envelope (message.received).
-        if frame.get('event_type') == 'message.received':
-            await self._handle_inbound_message(conn, frame)
-            return
-
-        await self.logger.debug(f'ESPL adapter unhandled frame type: {msg_type}')
-
-    def _start_inbound_task(self, coro) -> asyncio.Task | None:
-        self.inbound_tasks = {task for task in self.inbound_tasks if not task.done()}
-        task = asyncio.create_task(coro)
-        self.inbound_tasks.add(task)
-
-        def task_done(done_task: asyncio.Task) -> None:
-            self.inbound_tasks.discard(done_task)
-            if not done_task.cancelled():
-                done_task.exception()
-
-        task.add_done_callback(task_done)
-        return task
-
-    async def _handle_inbound_message(self, conn: _EsplConnection, envelope: dict) -> None:
-        """Convert a message.received envelope into a LangBot event and fire it."""
-        payload = envelope.get('payload') or {}
-        if not isinstance(payload, dict):
-            await self.logger.warning('ESPL adapter inbound payload is not an object')
-            return
-
-        conversation_id = str(payload.get('conversation_id') or '')
-        sender_id = str(payload.get('sender_id') or '')
-        sender_name = str(payload.get('sender_name') or 'User')
-        message_content = str(payload.get('message_content') or '')
-        instance_id = str(payload.get('instance') or payload.get('instance_id') or '')
-        platform = str(payload.get('platform_id') or envelope.get('platform') or '')
-
-        if not conversation_id:
-            await self.logger.warning('ESPL adapter inbound message missing conversation_id')
-            return
-
-        chain = self._build_message_chain(payload.get('message_chain'), message_content)
-
-        # Stash routing context (instance_id, conversation_id, conn_key) on the
-        # event so outbound replies route back to the correct connection.
-        source_platform_object = {
-            'instance_id': instance_id,
-            'conversation_id': conversation_id,
-            'platform': platform,
-            'sender_id': sender_id,
-            '_conn': conn,
-        }
-
-        session_type = str(payload.get('session_type') or 'person')
-        if session_type == 'group':
-            group = platform_entities.Group(
-                id=conversation_id,
-                name=str(payload.get('group_name') or conversation_id),
-                permission=platform_entities.Permission.Member,
-            )
-            sender = platform_entities.GroupMember(
-                id=sender_id or conversation_id,
-                member_name=sender_name,
-                group=group,
-                permission=platform_entities.Permission.Member,
-            )
-            event = platform_events.GroupMessage(
-                sender=sender,
-                message_chain=chain,
-                time=datetime.now().timestamp(),
-                source_platform_object=source_platform_object,
-            )
-        else:
-            sender = platform_entities.Friend(
-                id=conversation_id,
-                nickname=sender_name,
-                remark=sender_name,
-            )
-            event = platform_events.FriendMessage(
-                sender=sender,
-                message_chain=chain,
-                time=datetime.now().timestamp(),
-                source_platform_object=source_platform_object,
-            )
-
-        listener = self.listeners.get(type(event))
-        if listener is None:
-            await self.logger.warning(f'ESPL adapter no listener for {type(event).__name__}')
-            return
-
-        await self.logger.info(
-            f'ESPL adapter inbound: conversation={conversation_id} sender={sender_name} '
-            f'content={message_content[:100]}'
-        )
-        self._start_inbound_task(listener(event, self))
-
-    def _build_message_chain(
-        self,
-        message_chain: typing.Any,
-        fallback_text: str,
-    ) -> platform_message.MessageChain:
-        """Convert an ESPL message_chain into a LangBot MessageChain."""
-        components: list[platform_message.MessageComponent] = []
-        if isinstance(message_chain, list):
-            for elem in message_chain:
-                if not isinstance(elem, dict):
-                    continue
-                elem_type = elem.get('type', '')
-                content = elem.get('content')
-                if elem_type == 'text':
-                    text = ''
-                    if isinstance(content, dict):
-                        text = str(content.get('text', ''))
-                    elif isinstance(content, str):
-                        text = content
-                    else:
-                        text = str(elem.get('text', ''))
-                    if text:
-                        components.append(platform_message.Plain(text=text))
-                elif elem_type == 'image':
-                    url = ''
-                    if isinstance(content, dict):
-                        url = str(content.get('url', ''))
-                    elif isinstance(content, str):
-                        url = content
-                    else:
-                        url = str(elem.get('url', ''))
-                    if url:
-                        components.append(platform_message.Image(url=url))
-                elif elem_type in ('item', 'product', 'goods'):
-                    # E-commerce product card (e.g. 闲鱼 itemInfo).
-                    # Render as a plain-text description so the product info
-                    # (title/price) is not dropped downstream.
-                    title = ''
-                    price = ''
-                    if isinstance(content, dict):
-                        title = str(content.get('title') or '')
-                        price = str(content.get('price') or '')
-                    elif isinstance(content, str):
-                        title = content
-                    else:
-                        title = str(elem.get('title') or '')
-                        price = str(elem.get('price') or '')
-                    product_text = title
-                    if price:
-                        product_text = f'{title} [价格: {price}]' if title else f'价格: {price}'
-                    if product_text:
-                        components.append(platform_message.Plain(text=product_text))
-        if not components and fallback_text:
-            components.append(platform_message.Plain(text=fallback_text))
-        return platform_message.MessageChain(components)
-
-    # -- outbound -------------------------------------------------------------
-
-    async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain) -> dict:
-        """Proactively push a message to a conversation (target_id == conversation_id)."""
-        return await self._emit_outbound(target_id, message)
-
-    async def reply_message(
-        self,
-        message_source: platform_events.MessageEvent,
-        message: platform_message.MessageChain,
-        quote_origin: bool = False,
-    ) -> dict:
-        return await self._emit_outbound_from_event(message_source, message)
-
-    async def reply_message_chunk(
-        self,
-        message_source: platform_events.MessageEvent,
-        bot_message,
-        message: platform_message.MessageChain,
-        quote_origin: bool = False,
-        is_final: bool = False,
-    ) -> dict:
-        # ESPL v3 has no streaming; send the whole chunk as a final message.
-        return await self._emit_outbound_from_event(message_source, message)
-
-    async def _emit_outbound_from_event(
-        self,
-        message_source: platform_events.MessageEvent,
-        message: platform_message.MessageChain,
-    ) -> dict:
-        """Send a reply, routing back to the connection captured at inbound."""
-        source = getattr(message_source, 'source_platform_object', None) or {}
-        conn = source.get('_conn')
-        conversation_id = str(source.get('conversation_id') or '')
-        instance_id = str(source.get('instance_id') or '')
-        sender_id = str(source.get('sender_id') or '')
-        if not conversation_id:
-            conversation_id = str(self.get_launcher_id(message_source))
-        return await self._emit_outbound(
-            conversation_id,
-            message,
-            instance_id=instance_id,
-            sender_id=sender_id,
-            conn=conn,
-        )
-
-    async def _emit_outbound(
-        self,
-        conversation_id: str,
-        message: platform_message.MessageChain,
-        instance_id: str = '',
-        sender_id: str = '',
-        conn: _EsplConnection | None = None,
-    ) -> dict:
-        """Build and send an ESPL v3 outbound message frame."""
-        if conn is None:
-            # Try to find a connection for this conversation by scanning.
-            if not self.connections:
-                await self.logger.warning('ESPL adapter no connections; dropping outbound message')
-                return {}
-            conn = next(iter(self.connections.values()))
-
-        # Convert the LangBot message chain to ESPL chain elements.
-        chain = []
-        for component in message:
-            if isinstance(component, platform_message.Plain):
-                chain.append({'type': 'text', 'content': {'text': component.text}})
-            elif isinstance(component, platform_message.Image):
-                chain.append({'type': 'image', 'content': {'url': component.url or ''}})
-
-        frame = {
-            'type': 'message',
-            'id': 'out_' + uuid.uuid4().hex,
-            'timestamp': int(time.time() * 1000),
-            'payload': {
-                'instance_id': instance_id,
-                'command_type': 'send_text',
-                'conversation_id': conversation_id,
-                'target_id': sender_id or conversation_id,
-                'sender_id': sender_id,
-                'message_chain': chain,
-            },
-        }
-        try:
-            await conn.send_frame(frame)
-        except Exception as e:
-            await self.logger.error(f'ESPL adapter failed to send outbound: {e}')
-            return {}
-        await self.logger.info(f'ESPL adapter outbound: conversation={conversation_id} chain={chain}')
-        return frame
-
-    # -- heartbeat ------------------------------------------------------------
-
-    async def _heartbeat_loop(self) -> None:
-        """Periodically ping all connected clients to keep connections alive."""
-        interval = int(self.config.get('heartbeat_interval', _DEFAULT_HEARTBEAT_INTERVAL))
-        while self.running:
-            await asyncio.sleep(interval)
-            for conn in list(self.connections.values()):
-                try:
-                    await conn.send_frame({'type': 'ping', 'timestamp': int(time.time() * 1000)})
-                except Exception as e:
-                    await self.logger.warning(f'ESPL adapter heartbeat to client failed: {e}')

src/langbot/pkg/platform/sources/espl.yaml

@@ -1,83 +0,0 @@
-apiVersion: v1
-kind: MessagePlatformAdapter
-metadata:
-  name: espl
-  label:
-    en_US: ESPL V3
-    zh_Hans: ESPL V3
-    zh_Hant: ESPL V3
-    ja_JP: ESPL V3
-  description:
-    en_US: "LangBot acts as a WebSocket server. E-SP-Line2 creates a client-mode adapter (接入器) pointing its ws_url to this endpoint. Receives e-commerce messages (Taobao / Xianyu) as inbound events and sends AI replies back to the platform."
-    zh_Hans: "LangBot 作为 WebSocket 服务端。在 E-SP-Line2 中创建客户端模式接入器，将 ws_url 指向本端点即可接入。接收电商平台（淘宝/闲鱼）消息作为入站事件，并将 AI 回复发回平台。"
-    zh_Hant: "LangBot 作為 WebSocket 服務端。在 E-SP-Line2 中建立用戶端模式接入器，將 ws_url 指向本端點即可接入。接收電商平台（淘寶/閒魚）訊息作為入站事件，並將 AI 回覆發回平台。"
-    ja_JP: "LangBot が WebSocket サーバーとして動作します。E-SP-Line2 でクライアントモードのアダプター（接入器）を作成し、ws_url をこのエンドポイントに向けます。EC プラットフォーム（Taobao / Xianyu）のメッセージをインバウンドイベントとして受信し、AI 返信をプラットフォームに送り返します。"
-  icon: espl.png
-spec:
-  categories:
-    - global
-  help_links:
-    zh: https://docs.langbot.app/zh/platforms/espl
-    en: https://docs.langbot.app/en/platforms/espl
-    ja: https://docs.langbot.app/ja/platforms/espl
-  config:
-    - name: host
-      label:
-        en_US: Listen Host
-        zh_Hans: 监听主机
-        zh_Hant: 監聽主機
-        ja_JP: リッスンホスト
-      description:
-        en_US: "Host to bind the WebSocket server. Set 0.0.0.0 when E-SP-Line2 is on another machine."
-        zh_Hans: "WebSocket 服务端绑定的主机。E-SP-Line2 在其他机器时设为 0.0.0.0。"
-        zh_Hant: "WebSocket 服務端綁定的主機。E-SP-Line2 在其他機器時設為 0.0.0.0。"
-        ja_JP: "WebSocket サーバーをバインドするホスト。E-SP-Line2 が別マシンの場合は 0.0.0.0 を設定します。"
-      type: string
-      required: true
-      default: "127.0.0.1"
-    - name: port
-      label:
-        en_US: Listen Port
-        zh_Hans: 监听端口
-        zh_Hant: 監聽連接埠
-        ja_JP: リッスンポート
-      description:
-        en_US: "Port to bind the WebSocket server. E-SP-Line2 client-mode adapter connects to ws://<host>:<port>/ws."
-        zh_Hans: "WebSocket 服务端绑定的端口。E-SP-Line2 客户端模式接入器连接 ws://<host>:<port>/ws。"
-        zh_Hant: "WebSocket 服務端綁定的連接埠。E-SP-Line2 用戶端模式接入器連接 ws://<host>:<port>/ws。"
-        ja_JP: "WebSocket サーバーをバインドするポート。E-SP-Line2 クライアントモードアダプターは ws://<host>:<port>/ws に接続します。"
-      type: integer
-      required: false
-      default: 8000
-    - name: key
-      label:
-        en_US: Access Key
-        zh_Hans: 访问密钥
-        zh_Hant: 訪問密鑰
-        ja_JP: アクセスキー
-      description:
-        en_US: "Access key for authentication. E-SP-Line2 client-mode adapter passes this key as ?key=<KEY> in the WebSocket URL. Leave empty to disable key validation (not recommended)."
-        zh_Hans: "访问密钥用于认证。E-SP-Line2 客户端模式接入器在 WebSocket URL 中携带 ?key=<KEY> 传递此密钥。留空表示不验证密钥（不推荐）。"
-        zh_Hant: "訪問密鑰用於認證。E-SP-Line2 用戶端模式接入器在 WebSocket URL 中攜帶 ?key=<KEY> 傳遞此密鑰。留空表示不驗證密鑰（不推薦）。"
-        ja_JP: "認証用のアクセスキー。E-SP-Line2 クライアントモードアダプターは WebSocket URL に ?key=<KEY> としてこのキーを渡します。空の場合はキー検証を無効にします（非推奨）。"
-      type: string
-      required: false
-      default: ""
-    - name: heartbeat_interval
-      label:
-        en_US: Heartbeat Interval (seconds)
-        zh_Hans: 心跳间隔（秒）
-        zh_Hant: 心跳間隔（秒）
-        ja_JP: ハートビート間隔（秒）
-      description:
-        en_US: "How often to ping connected clients to keep the connection alive."
-        zh_Hans: "发送 ping 帧保持连接的间隔。"
-        zh_Hant: "發送 ping 幀保持連線的間隔。"
-        ja_JP: "接続を維持するためにクライアントに ping を送信する間隔。"
-      type: integer
-      required: false
-      default: 30
-execution:
-  python:
-    path: ./espl.py
-    attr: EsplAdapter

src/langbot/templates/metadata/pipeline/ai.yaml

@@ -143,18 +143,41 @@ stages:
           operator: eq
           value: false
         disabled_tooltip:
-          en_US: >-
-            Sandbox scope can't be changed: either the Box sandbox is disabled
-            or unavailable (enable it in config.yaml with box.enabled = true and
-            ensure the runtime is reachable), or this deployment pins all
-            pipelines to a fixed scope.
-          zh_Hans: "无法修改沙箱作用域：Box 沙箱已禁用或不可用（请在配置中启用 box.enabled = true 并确认运行时连接正常），或本部署已将所有流水线固定为统一作用域。"
-          zh_Hant: "無法修改沙箱作用域：Box 沙箱已停用或無法使用（請在設定中啟用 box.enabled = true 並確認執行時連線正常），或本部署已將所有流水線固定為統一作用域。"
-          ja_JP: "サンドボックススコープを変更できません：Box サンドボックスが無効/利用不可（設定で box.enabled = true にしてランタイム接続を確認）、またはこのデプロイがすべてのパイプラインを固定スコープに制限しています。"
-          vi_VN: "Không thể thay đổi phạm vi sandbox：Box sandbox bị tắt hoặc không khả dụng (bật box.enabled = true và đảm bảo runtime hoạt động), hoặc bản triển khai này cố định mọi pipeline về một phạm vi."
-          th_TH: "ไม่สามารถเปลี่ยนขอบเขต Sandbox：Box sandbox ถูกปิดหรือไม่พร้อมใช้งาน (เปิด box.enabled = true และตรวจสอบรันไทม์) หรือการ deploy นี้ล็อกทุก pipeline ไว้ที่ขอบเขตเดียว"
-          es_ES: "No se puede cambiar el alcance del sandbox: el sandbox de Box está desactivado o no disponible (actívelo con box.enabled = true y verifique el runtime), o este despliegue fija todas las pipelines a un alcance único."
-          ru_RU: "Невозможно изменить область песочницы: песочница Box отключена или недоступна (включите box.enabled = true и проверьте среду выполнения), либо это развёртывание фиксирует единую область для всех конвейеров."
+          en_US: "Sandbox is unavailable. Enable Box and check its connection before changing the scope."
+          zh_Hans: "沙箱未启用，请启用 Box 并确认连接正常后再修改作用域。"
+          zh_Hant: "沙箱未啟用，請啟用 Box 並確認連線正常後再修改作用域。"
+          ja_JP: "サンドボックスは利用できません。Box を有効にし、接続を確認してからスコープを変更してください。"
+          vi_VN: "Sandbox không khả dụng. Hãy bật Box và kiểm tra kết nối trước khi thay đổi phạm vi."
+          th_TH: "Sandbox ไม่พร้อมใช้งาน โปรดเปิดใช้งาน Box และตรวจสอบการเชื่อมต่อก่อนเปลี่ยนขอบเขต"
+          es_ES: "El sandbox no está disponible. Active Box y compruebe su conexión antes de cambiar el alcance."
+          ru_RU: "Песочница недоступна. Включите Box и проверьте подключение, прежде чем менять область."
+        disabled_tooltip_overrides:
+          - when:
+              field: __system.box_scope_forced_global
+              operator: eq
+              value: true
+            tooltip:
+              en_US: "A global sandbox is enforced; the scope cannot be changed."
+              zh_Hans: "已强制使用全局沙箱，无法修改作用域。"
+              zh_Hant: "已強制使用全域沙箱，無法修改作用域。"
+              ja_JP: "グローバルサンドボックスの使用が強制されているため、スコープを変更できません。"
+              vi_VN: "Bắt buộc sử dụng sandbox toàn cục; không thể thay đổi phạm vi."
+              th_TH: "ระบบบังคับใช้ Sandbox ส่วนกลาง จึงไม่สามารถเปลี่ยนขอบเขตได้"
+              es_ES: "Se impone un sandbox global; no se puede cambiar el alcance."
+              ru_RU: "Принудительно используется глобальная песочница; изменить область нельзя."
+          - when:
+              field: __system.box_scope_forced
+              operator: eq
+              value: true
+            tooltip:
+              en_US: "A fixed sandbox scope is enforced; the scope cannot be changed."
+              zh_Hans: "已强制使用固定沙箱作用域，无法修改作用域。"
+              zh_Hant: "已強制使用固定沙箱作用域，無法修改作用域。"
+              ja_JP: "固定のサンドボックススコープが強制されているため、スコープを変更できません。"
+              vi_VN: "Phạm vi sandbox đã được cố định bắt buộc; không thể thay đổi phạm vi."
+              th_TH: "ระบบบังคับใช้ขอบเขต Sandbox แบบตายตัว จึงไม่สามารถเปลี่ยนขอบเขตได้"
+              es_ES: "Se impone un alcance fijo del sandbox; no se puede cambiar el alcance."
+              ru_RU: "Принудительно задана фиксированная область песочницы; изменить её нельзя."
         type: select
         required: false
         default: "{launcher_type}_{launcher_id}"

web/src/app/home/components/dynamic-form/DynamicFormComponent.tsx

@@ -46,30 +46,10 @@ import {
 } from '@/components/ui/tooltip';
 import { systemInfo } from '@/app/infra/http';
 import { getAdapterDocUrl } from '@/app/infra/entities/adapter-docs';
-
-/**
- * Resolve the value referenced by a `show_if.field` string.
- *
- * Fields prefixed with `__system.` are looked up in the caller-supplied
- * `systemContext` dictionary (e.g. `__system.is_wizard` → `systemContext.is_wizard`).
- * All other field names are resolved from the live form values first, then
- * fall back to `externalDependentValues`.
- */
-function resolveShowIfValue(
-  field: string,
-  watchedValues: Record<string, unknown>,
-  externalDependentValues?: Record<string, unknown>,
-  systemContext?: Record<string, unknown>,
-): unknown {
-  if (field.startsWith(SYSTEM_FIELD_PREFIX)) {
-    const key = field.slice(SYSTEM_FIELD_PREFIX.length);
-    return systemContext?.[key];
-  }
-  if (watchedValues[field] !== undefined) {
-    return watchedValues[field];
-  }
-  return externalDependentValues?.[field];
-}
+import {
+  resolveDisabledState,
+  resolveShowIfValue,
+} from './DynamicFormConditions';
 
 type DynamicFormValueSpec = Pick<
   IDynamicFormItemSchema,
@@ -675,40 +655,19 @@ export default function DynamicFormComponent({
             }
           }
 
-          // ``disable_if`` mirrors ``show_if``'s evaluator but instead of
-          // hiding the field, leaves it visible and inert. Use it when the
-          // operator needs to see that the field exists yet cannot edit it
-          // under the current runtime state (e.g. sandbox-bound fields when
-          // Box is disabled).
-          let isDisabledByCondition = false;
-          if (config.disable_if) {
-            const dependValue = resolveShowIfValue(
-              config.disable_if.field,
+          // Keep locked fields visible and resolve only the applicable reason.
+          const { isDisabledByCondition, disabledTooltip: tooltip } =
+            resolveDisabledState(
+              config,
               watchedValues as Record<string, unknown>,
               externalDependentValues,
               systemContext,
             );
-            const cond = config.disable_if;
-            if (cond.operator === 'eq' && dependValue === cond.value) {
-              isDisabledByCondition = true;
-            } else if (cond.operator === 'neq' && dependValue !== cond.value) {
-              isDisabledByCondition = true;
-            } else if (
-              cond.operator === 'in' &&
-              Array.isArray(cond.value) &&
-              cond.value.includes(dependValue)
-            ) {
-              isDisabledByCondition = true;
-            }
-          }
 
           // All fields are disabled when editing (creation_settings are
           // immutable) or when ``disable_if`` matches.
           const isFieldDisabled = !!isEditing || isDisabledByCondition;
-          const disabledTooltip =
-            isDisabledByCondition && config.disabled_tooltip
-              ? extractI18nObject(config.disabled_tooltip)
-              : '';
+          const disabledTooltip = tooltip ? extractI18nObject(tooltip) : '';
           const renderDisabledTooltipIcon = () =>
             disabledTooltip ? (
               <DisabledTooltipIcon text={disabledTooltip} />

web/src/app/home/components/dynamic-form/DynamicFormConditions.ts

@@ -0,0 +1,71 @@
+import {
+  SYSTEM_FIELD_PREFIX,
+  type IDynamicFormItemSchema,
+  type IShowIfCondition,
+} from '@/app/infra/entities/form/dynamic';
+
+/** System references use caller context; other fields prefer live form values. */
+export function resolveShowIfValue(
+  field: string,
+  watchedValues: Record<string, unknown>,
+  externalDependentValues?: Record<string, unknown>,
+  systemContext?: Record<string, unknown>,
+): unknown {
+  if (field.startsWith(SYSTEM_FIELD_PREFIX)) {
+    return systemContext?.[field.slice(SYSTEM_FIELD_PREFIX.length)];
+  }
+  if (watchedValues[field] !== undefined) {
+    return watchedValues[field];
+  }
+  return externalDependentValues?.[field];
+}
+
+export function matchesFormCondition(
+  condition: IShowIfCondition,
+  watchedValues: Record<string, unknown>,
+  externalDependentValues?: Record<string, unknown>,
+  systemContext?: Record<string, unknown>,
+): boolean {
+  const value = resolveShowIfValue(
+    condition.field,
+    watchedValues,
+    externalDependentValues,
+    systemContext,
+  );
+  switch (condition.operator) {
+    case 'eq':
+      return value === condition.value;
+    case 'neq':
+      return value !== condition.value;
+    case 'in':
+      return Array.isArray(condition.value) && condition.value.includes(value);
+    default:
+      return false;
+  }
+}
+
+export function resolveDisabledState(
+  config: Pick<
+    IDynamicFormItemSchema,
+    'disable_if' | 'disabled_tooltip' | 'disabled_tooltip_overrides'
+  >,
+  watchedValues: Record<string, unknown>,
+  externalDependentValues?: Record<string, unknown>,
+  systemContext?: Record<string, unknown>,
+) {
+  const matches = (condition: IShowIfCondition) =>
+    matchesFormCondition(
+      condition,
+      watchedValues,
+      externalDependentValues,
+      systemContext,
+    );
+  const isDisabledByCondition =
+    !!config.disable_if && matches(config.disable_if);
+  const disabledTooltip = isDisabledByCondition
+    ? (config.disabled_tooltip_overrides?.find((override) =>
+        matches(override.when),
+      )?.tooltip ?? config.disabled_tooltip)
+    : undefined;
+  return { isDisabledByCondition, disabledTooltip };
+}

web/src/app/home/pipelines/components/pipeline-form/BoxScopeContext.ts

@@ -0,0 +1,14 @@
+/** Unavailability takes priority over the deployment's scope restriction. */
+export function getBoxScopeContext(
+  boxAvailable: boolean,
+  forcedTemplate?: string,
+) {
+  forcedTemplate = forcedTemplate?.trim();
+  return {
+    box_available: boxAvailable,
+    box_scope_editable: boxAvailable && !forcedTemplate,
+    // Only expose forced-scope reasons when the sandbox is available.
+    box_scope_forced: boxAvailable && !!forcedTemplate,
+    box_scope_forced_global: boxAvailable && forcedTemplate === '{global}',
+  };
+}

web/src/app/home/pipelines/components/pipeline-form/PipelineFormComponent.tsx

@@ -8,6 +8,7 @@ import {
 import DynamicFormComponent from '@/app/home/components/dynamic-form/DynamicFormComponent';
 import N8nAuthFormComponent from '@/app/home/components/dynamic-form/N8nAuthFormComponent';
 import { useBoxStatus } from '@/app/infra/hooks/useBoxStatus';
+import { getBoxScopeContext } from './BoxScopeContext';
 import { systemInfo } from '@/app/infra/http';
 import { Button } from '@/components/ui/button';
 import { useForm } from 'react-hook-form';
@@ -425,13 +426,12 @@ export default function PipelineFormComponent({
     //   2. the deployment pins all pipelines to a fixed scope via
     //      ``system.limitation.force_box_session_id_template`` (SaaS).
     const forcedBoxTemplate =
-      systemInfo.limitation?.force_box_session_id_template || '';
+      systemInfo.limitation?.force_box_session_id_template?.trim() || '';
     const boxScopeForced = !!forcedBoxTemplate;
     const isLocalAgentStage = formName === 'ai' && stage.name === 'local-agent';
     const stageSystemContext = isLocalAgentStage
       ? {
-          box_available: boxAvailable,
-          box_scope_editable: boxAvailable && !boxScopeForced,
+          ...getBoxScopeContext(boxAvailable, forcedBoxTemplate),
           pipeline_id: pipelineId,
         }
       : undefined;

web/src/app/infra/entities/form/dynamic.ts

@@ -39,6 +39,13 @@ export interface IDynamicFormItemSchema {
   disable_if?: IShowIfCondition;
   /** Tooltip shown next to the field label when ``disable_if`` is active. */
   disabled_tooltip?: I18nObject;
+  /** Optional overrides evaluated in order when ``disable_if`` matches.
+   *  The first matching ``when`` wins; otherwise use ``disabled_tooltip``.
+   *  Conditions use the same operators and value lookup as ``disable_if``. */
+  disabled_tooltip_overrides?: {
+    when: IShowIfCondition;
+    tooltip: I18nObject;
+  }[];
 
   /** when type is PLUGIN_SELECTOR, the scopes is the scopes of components(plugin contains), the default is all */
   scopes?: string[];

web/tests/e2e/sandbox-scope-tooltip.spec.ts

@@ -0,0 +1,232 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { expect, test, type Page } from '@playwright/test';
+import { installLangBotApiMocks } from './fixtures/langbot-api';
+
+// UI fixtures only: real app/components, intercepted APIs, no production Box.
+// Load the shipped metadata rather than reproducing its tooltip conditions.
+const requireFromTest = createRequire(__filename);
+const { load } = createRequire(requireFromTest.resolve('eslint'))(
+  'js-yaml',
+) as {
+  load: (source: string) => unknown;
+};
+const aiMetadata = load(
+  readFileSync(
+    resolve(
+      __dirname,
+      '../../../src/langbot/templates/metadata/pipeline/ai.yaml',
+    ),
+    'utf8',
+  ),
+);
+const unavailableHint = '沙箱未启用，请启用 Box 并确认连接正常后再修改作用域。';
+const forcedHint = '已强制使用全局沙箱，无法修改作用域。';
+
+interface BoxState {
+  enabled: boolean;
+  available: boolean;
+}
+
+async function openPipeline(page: Page, box: BoxState, forced = '') {
+  await installLangBotApiMocks(page, {
+    authenticated: true,
+    storage: { langbot_language: 'zh-Hans' },
+  });
+  await page.route('**/api/v1/system/info', (route) =>
+    route.fulfill({
+      json: {
+        code: 0,
+        data: {
+          debug: false,
+          version: 'sandbox-scope-ui-fixture',
+          edition: 'community',
+          cloud_service_url: 'https://space.langbot.app',
+          enable_marketplace: true,
+          allow_modify_login_info: true,
+          disable_models_service: false,
+          limitation: {
+            max_bots: -1,
+            max_pipelines: -1,
+            max_extensions: -1,
+            force_box_session_id_template: forced,
+          },
+          outbound_ips: [],
+          wizard_status: 'completed',
+          wizard_progress: null,
+        },
+      },
+    }),
+  );
+  await page.route('**/api/v1/box/status', (route) =>
+    route.fulfill({
+      json: {
+        code: 0,
+        data: {
+          ...box,
+          profile: 'UI fixture only',
+          recent_error_count: 0,
+          active_sessions: 0,
+          managed_processes: 0,
+          session_ttl_sec: 3600,
+          backend: { name: 'ui-fixture', available: box.available },
+        },
+      },
+    }),
+  );
+  await page.route(/\/api\/v1\/tools(?:\?.*)?$/, (route) =>
+    route.fulfill({ json: { code: 0, data: { tools: [] } } }),
+  );
+  await page.route('**/api/v1/pipelines/_/metadata', (route) =>
+    route.fulfill({ json: { code: 0, data: { configs: [aiMetadata] } } }),
+  );
+  await page.route('**/api/v1/pipelines/sandbox-scope-fixture', (route) =>
+    route.fulfill({
+      json: {
+        code: 0,
+        data: {
+          pipeline: {
+            uuid: 'sandbox-scope-fixture',
+            name: 'Sandbox scope — UI fixture only',
+            description: '',
+            emoji: '⚙️',
+            is_default: false,
+            config: {
+              ai: {
+                runner: { runner: 'local-agent' },
+                'local-agent': {
+                  'box-session-id-template': '{launcher_type}_{launcher_id}',
+                },
+              },
+              trigger: {},
+              safety: {},
+              output: {},
+            },
+          },
+        },
+      },
+    }),
+  );
+  await page.goto('/home/pipelines?id=sandbox-scope-fixture');
+  await page.getByRole('button', { name: 'AI 能力', exact: true }).click();
+  // DynamicForm gates this control through its wrapper's pointer-events,
+  // and its label targets that wrapper rather than the nested select.
+  const scope = page
+    .locator('[data-slot="form-item"]')
+    .filter({ has: page.getByText('沙箱作用域', { exact: true }) })
+    .getByRole('combobox');
+  await expect(scope).toBeVisible();
+  return scope;
+}
+
+async function expectWarning(page: Page, hint: string) {
+  const warning = page.getByRole('button', { name: hint, exact: true });
+  await expect(warning).toBeVisible();
+  await warning.hover();
+  await expect(page.getByRole('tooltip')).toHaveText(hint);
+}
+
+async function expectNoWarning(page: Page) {
+  await expect(page.getByRole('button', { name: unavailableHint })).toHaveCount(
+    0,
+  );
+  await expect(page.getByRole('button', { name: forcedHint })).toHaveCount(0);
+  await expect(page.getByRole('tooltip')).toHaveCount(0);
+}
+
+test.describe('sandbox scope disabled reason (UI fixtures only)', () => {
+  for (const scenario of [
+    { name: 'Box disabled', enabled: false, available: false, forced: '' },
+    { name: 'Box disconnected', enabled: true, available: false, forced: '' },
+    {
+      name: 'unavailable Box takes precedence over forced global',
+      enabled: true,
+      available: false,
+      forced: '{global}',
+    },
+  ]) {
+    test(scenario.name, async ({ page }) => {
+      const scope = await openPipeline(page, scenario, scenario.forced);
+      await expect(scope).toHaveCSS('pointer-events', 'none');
+      await expectWarning(page, unavailableHint);
+      await expect(page.getByRole('tooltip')).not.toContainText('强制');
+      await expect(page.getByRole('button', { name: forcedHint })).toHaveCount(
+        0,
+      );
+    });
+  }
+
+  for (const forced of ['{global}', ' {global} ']) {
+    test(`available Box with forced global explains the deployment restriction (${JSON.stringify(forced)})`, async ({
+      page,
+    }) => {
+      const scope = await openPipeline(
+        page,
+        { enabled: true, available: true },
+        forced,
+      );
+      await expect(scope).toHaveCSS('pointer-events', 'none');
+      await expect(scope).toHaveText('全局（所有人共享）');
+      await expectWarning(page, forcedHint);
+      await expect(
+        page.getByRole('button', { name: unavailableHint }),
+      ).toHaveCount(0);
+    });
+  }
+
+  for (const forced of ['', '   ']) {
+    test(`available and unforced Box is editable without a disabled warning (${JSON.stringify(forced)})`, async ({
+      page,
+    }) => {
+      const scope = await openPipeline(
+        page,
+        { enabled: true, available: true },
+        forced,
+      );
+      await expect(scope).toHaveCSS('pointer-events', 'auto');
+      await expect(scope).toHaveText('每个会话（推荐）');
+      await expectNoWarning(page);
+      await scope.click();
+      await page
+        .getByRole('option', { name: '全局（所有人共享）', exact: true })
+        .click();
+      await expect(scope).toHaveText('全局（所有人共享）');
+      await expectNoWarning(page);
+    });
+  }
+
+  for (const forced of ['', '{global}']) {
+    test(`Box status polls update the warning without remounting (${forced || 'unforced'})`, async ({
+      page,
+    }) => {
+      await page.clock.install();
+      const box = { enabled: true, available: false };
+      const scope = await openPipeline(page, box, forced);
+      await expect(scope).toHaveCSS('pointer-events', 'none');
+      await expectWarning(page, unavailableHint);
+      await page.mouse.move(0, 0);
+
+      const recovered = page.waitForResponse('**/api/v1/box/status');
+      box.available = true;
+      await page.clock.fastForward(31_000);
+      await recovered;
+      if (forced) {
+        await expect(scope).toHaveCSS('pointer-events', 'none');
+        await expectWarning(page, forcedHint);
+      } else {
+        await expect(scope).toHaveCSS('pointer-events', 'auto');
+        await expectNoWarning(page);
+      }
+      await page.mouse.move(0, 0);
+
+      const disconnected = page.waitForResponse('**/api/v1/box/status');
+      box.available = false;
+      await page.clock.fastForward(31_000);
+      await disconnected;
+      await expect(scope).toHaveCSS('pointer-events', 'none');
+      await expectWarning(page, unavailableHint);
+      await expect(page.getByRole('tooltip')).not.toContainText('强制');
+    });
+  }
+});

web/tests/unit/sandbox-scope-tooltip.test.mjs

@@ -0,0 +1,252 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import test from 'node:test';
+import ts from 'typescript';
+
+const require = createRequire(import.meta.url);
+const { load } = createRequire(require.resolve('eslint'))('js-yaml');
+const metadata = load(
+  fs.readFileSync(
+    new URL(
+      '../../../src/langbot/templates/metadata/pipeline/ai.yaml',
+      import.meta.url,
+    ),
+    'utf8',
+  ),
+);
+const scope = metadata.stages
+  .find((stage) => stage.name === 'local-agent')
+  .config.find((item) => item.name === 'box-session-id-template');
+const unavailable = '沙箱未启用，请启用 Box 并确认连接正常后再修改作用域。';
+const globalForced = '已强制使用全局沙箱，无法修改作用域。';
+const customForced = '已强制使用固定沙箱作用域，无法修改作用域。';
+
+function loadSource(relativePath) {
+  const filename = new URL(`../../src/${relativePath}`, import.meta.url);
+  assert.ok(fs.existsSync(filename), `Missing policy module: ${relativePath}`);
+  const compiled = ts.transpileModule(fs.readFileSync(filename, 'utf8'), {
+    compilerOptions: { module: ts.ModuleKind.CommonJS },
+  }).outputText;
+  const loaded = { exports: {} };
+  new Function('require', 'module', 'exports', compiled)(
+    (name) => {
+      if (name === '@/app/infra/entities/form/dynamic')
+        return loadSource('app/infra/entities/form/dynamic.ts');
+      throw new Error(`Unexpected runtime import: ${name}`);
+    },
+    loaded,
+    loaded.exports,
+  );
+  return loaded.exports;
+}
+
+function policies() {
+  return {
+    ...loadSource('app/home/components/dynamic-form/DynamicFormConditions.ts'),
+    ...loadSource(
+      'app/home/pipelines/components/pipeline-form/BoxScopeContext.ts',
+    ),
+  };
+}
+
+function scopeState(available, forcedTemplate) {
+  const { getBoxScopeContext, resolveDisabledState } = policies();
+  return resolveDisabledState(
+    scope,
+    {},
+    undefined,
+    getBoxScopeContext(available, forcedTemplate),
+  );
+}
+
+test('sandbox default tooltip explains only unavailability', () => {
+  assert.equal(scope.disabled_tooltip.zh_Hans, unavailable);
+});
+
+for (const [name, available, template, expected] of [
+  ['Box disabled', false, '', unavailable],
+  ['Box disconnected', false, undefined, unavailable],
+  [
+    'unavailable takes precedence over forced global',
+    false,
+    '{global}',
+    unavailable,
+  ],
+  [
+    'unavailable takes precedence over forced custom',
+    false,
+    '{pipeline_id}',
+    unavailable,
+  ],
+  ['available forced global', true, '{global}', globalForced],
+  ['available padded forced global', true, ' {global} ', globalForced],
+  ['available whitespace-only editable', true, '   ', undefined],
+  ['available forced custom', true, '{pipeline_id}', customForced],
+  ['available forced literal', true, 'tenant-sandbox', customForced],
+  ['available editable', true, '', undefined],
+  ['available without limitation', true, undefined, undefined],
+]) {
+  test(name, () => {
+    const state = scopeState(available, template);
+    assert.equal(state.isDisabledByCondition, expected !== undefined);
+    assert.equal(state.disabledTooltip?.zh_Hans, expected);
+  });
+}
+
+test('reason follows availability and forced-scope transitions without mutating metadata', () => {
+  const snapshot = structuredClone(scope);
+  for (const [available, template, expected] of [
+    [false, '{global}', unavailable],
+    [true, '{global}', globalForced],
+    [true, '{pipeline_id}', customForced],
+    [true, '', undefined],
+    [false, '', unavailable],
+    [true, '', undefined],
+  ]) {
+    assert.equal(
+      scopeState(available, template).disabledTooltip?.zh_Hans,
+      expected,
+    );
+  }
+  assert.deepEqual(scope, snapshot);
+});
+
+test('all sandbox reason variants preserve the eight metadata locales', () => {
+  const locales = [
+    'en_US',
+    'zh_Hans',
+    'zh_Hant',
+    'ja_JP',
+    'vi_VN',
+    'th_TH',
+    'es_ES',
+    'ru_RU',
+  ].sort();
+  assert.equal(scope.disabled_tooltip_overrides?.length, 2);
+  const messages = [
+    scope.disabled_tooltip,
+    ...scope.disabled_tooltip_overrides.map((entry) => entry.tooltip),
+  ];
+  for (const message of messages) {
+    assert.deepEqual(Object.keys(message).sort(), locales);
+    for (const locale of locales) assert.ok(message[locale].trim(), locale);
+  }
+  for (const locale of locales) {
+    assert.equal(
+      new Set(messages.map((message) => message[locale])).size,
+      3,
+      locale,
+    );
+    assert.equal(
+      scopeState(false, '{global}').disabledTooltip[locale],
+      messages[0][locale],
+    );
+    assert.equal(
+      scopeState(true, '{global}').disabledTooltip[locale],
+      messages[1][locale],
+    );
+    assert.equal(
+      scopeState(true, '{pipeline_id}').disabledTooltip[locale],
+      messages[2][locale],
+    );
+  }
+});
+
+test('ordinary static disabled tooltip remains compatible', () => {
+  const { resolveDisabledState } = policies();
+  const tooltip = { en_US: 'Read only' };
+  const config = {
+    disable_if: { field: 'locked', operator: 'eq', value: true },
+    disabled_tooltip: tooltip,
+  };
+  assert.deepEqual(resolveDisabledState(config, { locked: true }), {
+    isDisabledByCondition: true,
+    disabledTooltip: tooltip,
+  });
+  assert.deepEqual(resolveDisabledState(config, { locked: false }), {
+    isDisabledByCondition: false,
+    disabledTooltip: undefined,
+  });
+  assert.equal(
+    resolveDisabledState({ disabled_tooltip: tooltip }, {}).disabledTooltip,
+    undefined,
+  );
+  assert.equal(
+    resolveDisabledState({ disable_if: config.disable_if }, { locked: true })
+      .disabledTooltip,
+    undefined,
+  );
+});
+
+test('conditional overrides reuse eq, neq, in and live/external/system resolution', () => {
+  const { matchesFormCondition, resolveDisabledState } = policies();
+  const watched = { mode: 'live', empty: null, '__system.locked': false };
+  const external = { mode: 'external', fallback: 3, empty: 'external' };
+  const system = { locked: true };
+  for (const [condition, expected] of [
+    [{ field: 'mode', operator: 'eq', value: 'live' }, true],
+    [{ field: 'mode', operator: 'eq', value: 'external' }, false],
+    [{ field: 'fallback', operator: 'neq', value: 4 }, true],
+    [{ field: 'fallback', operator: 'in', value: [2, 3] }, true],
+    [{ field: 'fallback', operator: 'in', value: '3' }, false],
+    [{ field: 'fallback', operator: 'eq', value: '3' }, false],
+    [{ field: 'empty', operator: 'eq', value: null }, true],
+    [{ field: '__system.locked', operator: 'eq', value: true }, true],
+    [{ field: 'absent', operator: 'eq', value: true }, false],
+  ])
+    assert.equal(
+      matchesFormCondition(condition, watched, external, system),
+      expected,
+    );
+  const config = {
+    disable_if: { field: '__system.locked', operator: 'eq', value: true },
+    disabled_tooltip: { en_US: 'Default' },
+    disabled_tooltip_overrides: [
+      {
+        when: { field: 'mode', operator: 'eq', value: 'external' },
+        tooltip: { en_US: 'Wrong' },
+      },
+      {
+        when: { field: 'fallback', operator: 'in', value: [3] },
+        tooltip: { en_US: 'First match' },
+      },
+      {
+        when: { field: 'mode', operator: 'neq', value: 'external' },
+        tooltip: { en_US: 'Later match' },
+      },
+    ],
+  };
+  assert.equal(
+    resolveDisabledState(config, watched, external, system).disabledTooltip
+      .en_US,
+    'First match',
+  );
+  assert.equal(
+    resolveDisabledState(config, {}, {}, system).disabledTooltip.en_US,
+    'Later match',
+  );
+  assert.equal(
+    resolveDisabledState(config, watched, external, { locked: false })
+      .disabledTooltip,
+    undefined,
+  );
+  assert.equal(
+    resolveDisabledState(
+      { ...config, disabled_tooltip_overrides: [] },
+      watched,
+      external,
+      system,
+    ).disabledTooltip.en_US,
+    'Default',
+  );
+  const unmatched = {
+    ...config,
+    disabled_tooltip_overrides: [config.disabled_tooltip_overrides[0]],
+  };
+  assert.equal(
+    resolveDisabledState(unmatched, watched, external, system).disabledTooltip
+      .en_US,
+    'Default',
+  );
+});