@zhin.js/adapter-sandbox 5.0.5 → 6.0.0

package/lib/protocol.js

@@ -0,0 +1,164 @@
+/** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
+export function resolveSandboxEndpoint(appConfig) {
+    const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
+    const fixedName = typeof entry?.name === 'string' ? entry.name : undefined;
+    const name = fixedName || process.env.SANDBOX_BOT_NAME || 'sandbox-bot';
+    const owner = (typeof entry?.owner === 'string' && entry.owner)
+        || process.env.SANDBOX_BOT_OWNER
+        || 'sandbox-user';
+    return {
+        context: 'sandbox',
+        name,
+        owner,
+        randomNamePerConnection: !fixedName,
+    };
+}
+export function bindSandboxWsSocket(ws, handlers) {
+    if (typeof ws.on === 'function') {
+        const onMessage = (...args) => {
+            const data = args[0];
+            const raw = typeof data === 'string'
+                ? data
+                : data instanceof ArrayBuffer
+                    ? new TextDecoder().decode(data)
+                    : Buffer.isBuffer(data)
+                        ? data.toString()
+                        : String(data ?? '');
+            handlers.onMessage(raw);
+        };
+        ws.on('message', onMessage);
+        ws.on('close', handlers.onClose);
+        if (handlers.onError)
+            ws.on('error', handlers.onError);
+        return () => {
+            ws.off?.('message', onMessage);
+            ws.off?.('close', handlers.onClose);
+            if (handlers.onError)
+                ws.off?.('error', handlers.onError);
+        };
+    }
+    const onMessage = (ev) => {
+        const data = ev.data;
+        handlers.onMessage(typeof data === 'string' ? data : '');
+    };
+    const onClose = () => handlers.onClose();
+    const onError = handlers.onError
+        ? () => handlers.onError?.(new Error('WebSocket error'))
+        : undefined;
+    ws.addEventListener('message', onMessage);
+    ws.addEventListener('close', onClose);
+    if (onError)
+        ws.addEventListener('error', onError);
+    return () => {
+        ws.removeEventListener('message', onMessage);
+        ws.removeEventListener('close', onClose);
+        if (onError)
+            ws.removeEventListener('error', onError);
+    };
+}
+export function parseSandboxWsPayload(raw) {
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        payload = { text: raw };
+    }
+    const type = payload.type ?? 'private';
+    const id = payload.id ?? 'sandbox-user';
+    const content = typeof payload.content === 'string'
+        ? [{ type: 'text', data: { text: payload.content } }]
+        : Array.isArray(payload.content)
+            ? payload.content
+            : [{ type: 'text', data: { text: payload.text ?? raw } }];
+    const actionSegment = content.find((segment) => segment.type === 'action');
+    let action;
+    if (actionSegment?.data) {
+        const actionPayload = typeof actionSegment.data.payload === 'string'
+            ? actionSegment.data.payload
+            : typeof actionSegment.data.id === 'string'
+                ? actionSegment.data.id
+                : '';
+        const actionId = typeof actionSegment.data.id === 'string'
+            ? actionSegment.data.id
+            : actionPayload;
+        if (actionId || actionPayload) {
+            action = { id: actionId || actionPayload, payload: actionPayload || actionId };
+        }
+    }
+    let text = content
+        .flatMap((segment) => (segment.type === 'text' && typeof segment.data?.text === 'string'
+        ? [segment.data.text]
+        : []))
+        .join('\n');
+    if (!text.trim()) {
+        text = (typeof payload.text === 'string' && payload.text.trim())
+            ? payload.text
+            : action?.payload ?? raw;
+    }
+    return { type, id, content, timestamp: payload.timestamp ?? Date.now(), text, action };
+}
+/**
+ * Wire-encode an already-rendered outbound payload.
+ * Stamps `channel` so Console SandboxChat can filter by type+id (otherwise
+ * replies look like they disappeared).
+ */
+export function formatSandboxOutbound(payload, channel = {}) {
+    const stamp = {};
+    if (channel.type)
+        stamp.type = channel.type;
+    if (channel.id)
+        stamp.id = channel.id;
+    if (channel.bot)
+        stamp.bot = channel.bot;
+    if (channel.endpoint)
+        stamp.endpoint = channel.endpoint;
+    if (channel.messageId)
+        stamp.messageId = channel.messageId;
+    if (typeof payload === 'string') {
+        return JSON.stringify({
+            ...stamp,
+            content: [{ type: 'text', data: { text: payload } }],
+            timestamp: Date.now(),
+        });
+    }
+    if (Array.isArray(payload)) {
+        return JSON.stringify({
+            ...stamp,
+            content: payload,
+            timestamp: Date.now(),
+        });
+    }
+    // Already a wire envelope ({ content, type, … }) — pass through so the
+    // Console UI can read `content` / `type` without an extra nesting layer.
+    // Bare segment objects ({ type: 'text', data: … }) still need wrapping.
+    if (payload
+        && typeof payload === 'object'
+        && !Array.isArray(payload)
+        && ('content' in payload
+            || 'type' in payload && 'timestamp' in payload)) {
+        const envelope = payload;
+        return JSON.stringify({
+            ...stamp,
+            ...envelope,
+            type: envelope.type ?? stamp.type,
+            id: envelope.id ?? stamp.id,
+            timestamp: typeof envelope.timestamp === 'number' ? envelope.timestamp : Date.now(),
+        });
+    }
+    return JSON.stringify({ ...stamp, content: payload, timestamp: Date.now() });
+}
+/** WebSocket.OPEN 常量值；Node <22 无全局 WebSocket，不能用 WebSocket.OPEN。 */
+const WS_OPEN = 1;
+export function whenWsOpen(ws, fn) {
+    const std = ws;
+    if (typeof std.readyState === 'number') {
+        if (std.readyState === WS_OPEN) {
+            fn();
+            return;
+        }
+        std.addEventListener('open', fn, { once: true });
+        return;
+    }
+    fn();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "5.0.5",
-  "description": "Zhin.js adapter for local testing and development",
+  "version": "6.0.0",
+  "description": "Zhin.js Sandbox adapter for Plugin Runtime (WebSocket /sandbox)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,9 +13,12 @@
     }
   },
   "files": [
+    "adapters",
+    "pages",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
     "dist",
     "agent",
     "README.md",
@@ -43,32 +46,38 @@
     "directory": "plugins/adapters/sandbox"
   },
   "dependencies": {
-    "lucide-react": "^1.22.0"
+    "lucide-react": "^0.525.0",
+    "react": "^19.1.0",
+    "@zhin.js/client": "2.1.0",
+    "@zhin.js/console-contract": "1.0.0",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/page": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.1.8",
+    "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.93",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/contract": "1.0.3",
-    "@zhin.js/core": "1.3.4",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2"
+    "vitest": "^4.1.10",
+    "ws": "^8.21.0",
+    "@zhin.js/pagemanager": "2.0.5",
+    "@zhin.js/runtime": "1.0.2"
   },
   "peerDependencies": {
-    "@zhin.js/core": "1.3.4",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/host-router": "2.0.3",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/contract": "1.0.3"
+    "react": "^19.0.0",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/client": "2.1.0",
+    "@zhin.js/console-contract": "1.0.0",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/page": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
-      "optional": true
-    },
-    "@zhin.js/host-api": {
+    "react": {
       "optional": true
     },
     "@zhin.js/client": {
@@ -82,8 +91,27 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/sandbox/tests"
   }
 }

package/{client/Sandbox.tsx → pages/SandboxChat.tsx}

@@ -1,10 +1,17 @@
 import React, { useState, useEffect, useRef } from 'react';
-import { MessageSegment, cn, resolveMediaSrc, pickMediaRawUrl } from '@zhin.js/client';
 import {
-    buildSandboxWebSocketUrl,
-} from './sandboxTransport';
-import { User, Bot, Users, Trash2, Send, Hash, MessageSquare, Wifi, WifiOff, Smile, Image, X, Check, Info, Search, Endpoint, UserPlus, Bell, Video, Music } from 'lucide-react';
-import RichTextEditor, { RichTextEditorRef } from './RichTextEditor';
+  cn,
+  resolveMediaSrc,
+  pickMediaRawUrl,
+  type MessageSegment,
+} from '@zhin.js/client';
+import { buildSandboxWebSocketUrl } from './sandboxTransport';
+import {
+  User, Bot, Users, Trash2, Send, Hash, MessageSquare,
+  Wifi, WifiOff, Smile, Image, X, Check, Info, Search,
+  UserPlus, Bell, Video, Music,
+} from 'lucide-react';
+import RichTextEditor, { type RichTextEditorRef } from './RichTextEditor';
 
 interface Message {
     id: string; type: 'sent' | 'received'; channelType: 'private' | 'group' | 'channel';
@@ -99,16 +106,91 @@ export default function Sandbox() {
     }
 
     useEffect(() => {
-        const wsUrl = buildSandboxWebSocketUrl()
-        wsRef.current = new WebSocket(wsUrl)
-        wsRef.current.onopen = () => setConnected(true)
-        wsRef.current.onmessage = (event) => {
-            try { handleInboundPayload(JSON.parse(event.data)) }
-            catch (err) { console.error('[Sandbox] Failed to parse message:', err) }
+        let closed = false
+        let retryTimer: ReturnType<typeof setTimeout> | undefined
+        let attempt = 0
+        /** Ignore close events from a socket we intentionally replaced (login/base change). */
+        let replaceInFlight = false
+
+        const connect = () => {
+            if (closed) return
+            if (retryTimer) {
+                clearTimeout(retryTimer)
+                retryTimer = undefined
+            }
+            const wsUrl = buildSandboxWebSocketUrl()
+            // Tear down previous socket before opening a new one so we don't
+            // leave two concurrent /sandbox sessions for fixed-name endpoints.
+            const previous = wsRef.current
+            if (previous) {
+                replaceInFlight = true
+                previous.onclose = null
+                previous.onerror = null
+                previous.onmessage = null
+                previous.onopen = null
+                try { previous.close() } catch { /* already closed */ }
+                replaceInFlight = false
+            }
+            const ws = new WebSocket(wsUrl)
+            wsRef.current = ws
+            ws.onopen = () => {
+                attempt = 0
+                setConnected(true)
+            }
+            ws.onmessage = (event) => {
+                try { handleInboundPayload(JSON.parse(String(event.data))) }
+                catch (err) { console.error('[Sandbox] Failed to parse message:', err) }
+            }
+            ws.onclose = () => {
+                if (wsRef.current !== ws) return
+                setConnected(false)
+                wsRef.current = null
+                if (closed || replaceInFlight) return
+                const delay = Math.min(8_000, 500 * 2 ** attempt)
+                attempt += 1
+                retryTimer = setTimeout(connect, delay)
+            }
+            ws.onerror = () => {
+                /* close handler reconnects */
+            }
         }
-        wsRef.current.onclose = () => setConnected(false)
 
+        const onAuthOrStorage = (event?: Event) => {
+            // storage fires for other tabs; same-tab login sets localStorage then
+            // dispatches zhin:auth-required / custom login events.
+            if (event && event.type === 'storage') {
+                const key = (event as StorageEvent).key
+                if (
+                    key != null
+                    && key !== 'zhin_api_token'
+                    && key !== 'zhin_api_base'
+                    && key !== 'HTTP_TOKEN'
+                    && key !== 'zhin_http_token'
+                ) {
+                    return
+                }
+            }
+            attempt = 0
+            connect()
+        }
+
+        connect()
+        if (typeof window !== 'undefined') {
+            window.addEventListener('storage', onAuthOrStorage)
+            window.addEventListener('zhin:auth-required', onAuthOrStorage)
+            // Remote Console may fire this after successful login (token written).
+            window.addEventListener('zhin:auth-changed', onAuthOrStorage)
+            window.addEventListener('zhin:api-base-changed', onAuthOrStorage)
+        }
         return () => {
+            closed = true
+            if (retryTimer) clearTimeout(retryTimer)
+            if (typeof window !== 'undefined') {
+                window.removeEventListener('storage', onAuthOrStorage)
+                window.removeEventListener('zhin:auth-required', onAuthOrStorage)
+                window.removeEventListener('zhin:auth-changed', onAuthOrStorage)
+                window.removeEventListener('zhin:api-base-changed', onAuthOrStorage)
+            }
             wsRef.current?.close()
             wsRef.current = null
             setConnected(false)
@@ -279,10 +361,12 @@ export default function Sandbox() {
         const newMessage: Message = { id: `msg_${Date.now()}`, type: 'sent', channelType: activeChannel.type, channelId: activeChannel.id, channelName: activeChannel.name, senderId: 'test_user', senderName: '测试用户', content: segments, timestamp: Date.now() }
         setMessages((prev) => [...prev, newMessage]); setInputText(''); setPreviewSegments([])
         editorRef.current?.clear()
+        // Stamp type+id so Host sandbox endpoint preserves channel context for outbound replies.
         const payload = JSON.stringify({ type: activeChannel.type, id: activeChannel.id, content: segments, timestamp: Date.now() })
         wsRef.current?.send(payload)
     }
 
+
     const clearMessages = () => { if (confirm('确定清空所有消息记录？')) setMessages([]) }
     const switchChannel = (channel: Channel) => { setViewMode('chat'); setActiveChannel(channel); setChannels((prev) => prev.map((c) => c.id === channel.id ? { ...c, unread: 0 } : c)); if (window.innerWidth < 768) setShowChannelList(false) }
     const addChannel = () => {

package/pages/sandbox.tsx

@@ -0,0 +1,17 @@
+import { definePage } from '@zhin.js/console-contract';
+import SandboxChat from './SandboxChat';
+
+export const meta = definePage({
+  title: '沙盒',
+  icon: 'Box',
+  order: 10,
+});
+
+/**
+ * Convention page entry (ADR 0046).
+ * Restores the pre-runtime-migration Sandbox console UI (channels + rich text + faces).
+ * WebSocket targets Host `/sandbox` via zhin_api_base + token (see sandboxTransport.ts).
+ */
+export default function SandboxPage() {
+  return <SandboxChat />;
+}

package/pages/sandboxTransport.ts

@@ -0,0 +1,45 @@
+/** Same storage keys as `@zhin.js/client` remoteApi. */
+
+export function getSandboxApiBase(): string {
+  if (typeof localStorage === 'undefined') {
+    return typeof window !== 'undefined' ? window.location.origin : '';
+  }
+  const stored = localStorage.getItem('zhin_api_base')?.trim();
+  if (stored) return stored.replace(/\/+$/u, '');
+  if (typeof window !== 'undefined') return window.location.origin;
+  return '';
+}
+
+export function getSandboxBearerToken(): string {
+  if (typeof window !== 'undefined') {
+    const runtime = (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN?.trim();
+    if (runtime) return runtime;
+  }
+  if (typeof localStorage === 'undefined') return '';
+  return (
+    localStorage.getItem('zhin_api_token')?.trim()
+    || localStorage.getItem('HTTP_TOKEN')?.trim()
+    || localStorage.getItem('zhin_http_token')?.trim()
+    || (typeof sessionStorage !== 'undefined' ? sessionStorage.getItem('zhin_api_token')?.trim() : '')
+    || ''
+  );
+}
+
+export function getSandboxAuthHeaders(): Record<string, string> {
+  const token = getSandboxBearerToken();
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/**
+ * Browser WebSocket cannot set Authorization reliably; pass token in query when needed.
+ * Uses stored Console API base so Remote Console (different origin) still hits the bot Host.
+ */
+export function buildSandboxWebSocketUrl(base?: string): string {
+  const apiBase = (base ?? getSandboxApiBase()).replace(/\/+$/u, '');
+  const origin = apiBase || (typeof window !== 'undefined' ? window.location.origin : 'http://localhost');
+  const wsUrl = new URL('/sandbox', `${origin}/`);
+  wsUrl.protocol = wsUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+  const token = getSandboxBearerToken();
+  if (token) wsUrl.searchParams.set('token', token);
+  return wsUrl.href;
+}

package/plugin.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+
+export default definePlugin({
+  name: 'sandbox',
+  metadata: {
+    displayName: 'Sandbox Adapter',
+  },
+});

package/schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Sandbox bot name"
+          },
+          "context": {
+            "type": "string",
+            "description": "Sandbox context identifier"
+          },
+          "owner": {
+            "type": "string",
+            "description": "Sandbox owner user ID"
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}