@zhin.js/adapter-sandbox 5.0.6 → 6.0.1

package/pages/index.tsx

@@ -0,0 +1,18 @@
+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).
+ * `pages/index.tsx` → `/sandbox` (plugin path; no `/p-` leaf).
+ * 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/schema.json

@@ -5,16 +5,36 @@
   "properties": {
     "endpoints": {
       "type": "array",
-      "default": [],
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
-        "additionalProperties": false,
+        "additionalProperties": true,
         "properties": {
-          "context": { "type": "string" },
-          "name": { "type": "string" },
-          "owner": { "type": "string" }
-        }
+          "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"
+  ]
 }

package/src/endpoint.ts

@@ -18,6 +18,51 @@ import {
 
 const logger = getLogger('sandbox');
 
+/**
+ * 多 sandbox endpoint 共用同一个 HttpHost 时，同 path 的所有 WS listener
+ * 都会被回调（入站重复、出站互窜）。按 endpoint 名隔离挂载路径：
+ * 首个占用 `/sandbox`（保持 Console 默认兼容），其余退到 `/sandbox/<name>`。
+ * 认领记录按 HttpHost 隔离，endpoint stop() 时必须 release。
+ */
+const claimedWsPaths = new WeakMap<HttpHost, Map<string, string>>();
+
+function claimSandboxWsPath(
+  http: HttpHost,
+  name: string,
+): { readonly path: string; readonly release: () => void } {
+  let claims = claimedWsPaths.get(http);
+  if (!claims) {
+    claims = new Map();
+    claimedWsPaths.set(http, claims);
+  }
+  const candidates = ['/sandbox', `/sandbox/${encodeURIComponent(name)}`];
+  let path = candidates.find(
+    (candidate) => !claims!.has(candidate) || claims!.get(candidate) === name,
+  );
+  if (!path) {
+    let index = 2;
+    path = `/sandbox/${encodeURIComponent(name)}-${index}`;
+    while (claims.has(path)) {
+      index += 1;
+      path = `/sandbox/${encodeURIComponent(name)}-${index}`;
+    }
+  }
+  claims.set(path, name);
+  const claimed = path;
+  const registry = claims;
+  return {
+    path: claimed,
+    release: () => {
+      if (registry.get(claimed) === name) registry.delete(claimed);
+    },
+  };
+}
+
+interface SandboxChannel {
+  readonly type: string;
+  readonly id: string;
+}
+
 interface SandboxConnection {
   readonly target: string;
   readonly owner: string;
@@ -25,6 +70,11 @@ interface SandboxConnection {
   readonly release: () => void;
   /** true = 占位连接（尚无真实 WS 客户端），send 命中时按 miss 处理。 */
   readonly placeholder?: boolean;
+  /**
+   * 最近一条入站频道（Console UI 按 type+id 过滤气泡）。
+   * 出站必须带回，否则回复石沉大海。
+   */
+  lastChannel?: SandboxChannel;
 }
 
 export interface SandboxEndpointOptions {
@@ -34,10 +84,16 @@ export interface SandboxEndpointOptions {
   readonly defaults: ResolvedSandboxBot;
 }
 
+/**
+ * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export class SandboxWsEndpoint implements EndpointInstance {
   readonly #options: SandboxEndpointOptions;
   readonly #connections = new Map<string, SandboxConnection>();
   #wsHandleRelease?: () => void;
+  #wsPathRelease?: () => void;
+  #wsPath = '/sandbox';
   #open = false;
   #started = false;
 
@@ -53,7 +109,11 @@ export class SandboxWsEndpoint implements EndpointInstance {
   start(): void {
     if (this.#started) return;
     this.#started = true;
-    const handle = this.#options.http.ws('/sandbox');
+    // 多 endpoint 同 path 会被全部回调（入站重复、出站互窜），按名隔离。
+    const claim = claimSandboxWsPath(this.#options.http, this.#options.defaults.name);
+    this.#wsPathRelease = claim.release;
+    this.#wsPath = claim.path;
+    const handle = this.#options.http.ws(claim.path);
     this.#wsHandleRelease = handle.onConnection((connection) => {
       this.#acceptConnection(connection);
     });
@@ -62,7 +122,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
     }
     logger.info(formatCompact({
       op: 'sandbox_ws_mounted',
-      path: '/sandbox',
+      path: claim.path,
       endpoint: this.#options.defaults.name,
     }));
   }
@@ -79,7 +139,18 @@ export class SandboxWsEndpoint implements EndpointInstance {
     this.#open = false;
     this.#wsHandleRelease?.();
     this.#wsHandleRelease = undefined;
-    for (const connection of this.#connections.values()) connection.release();
+    this.#wsPathRelease?.();
+    this.#wsPathRelease = undefined;
+    for (const connection of this.#connections.values()) {
+      connection.release();
+      if (!connection.placeholder) {
+        try {
+          connection.socket.close(1001, 'sandbox endpoint stopped');
+        } catch {
+          /* already closed */
+        }
+      }
+    }
     this.#connections.clear();
     this.#started = false;
     logger.debug(formatCompact({ op: 'sandbox_stopped' }));
@@ -87,7 +158,9 @@ export class SandboxWsEndpoint implements EndpointInstance {
 
   send({ target, payload }: { readonly target: string; readonly payload: unknown }): unknown {
     if (!this.#open) return undefined;
-    const connection = this.#connections.get(target);
+    // Reply target is the connection key (bot name / sandbox-uuid), not private:channelId.
+    const connection = this.#connections.get(target)
+      ?? this.#findLiveConnection();
     if (!connection) {
       logger.debug(formatCompact({ op: 'sandbox_send_miss', target }));
       return undefined;
@@ -96,31 +169,75 @@ export class SandboxWsEndpoint implements EndpointInstance {
       logger.debug(formatCompact({ op: 'sandbox_send_placeholder', target }));
       return undefined;
     }
-    connection.socket.send(formatSandboxOutbound(payload));
-    logger.debug(formatCompact({ op: 'sandbox_send', target }));
+    // Console UI filters by type+id; stamp last inbound channel onto outbound wire.
+    const channel = connection.lastChannel ?? {
+      type: 'private',
+      id: connection.owner,
+    };
+    connection.socket.send(formatSandboxOutbound(payload, {
+      type: channel.type,
+      id: channel.id,
+      bot: this.#options.defaults.name,
+      endpoint: connection.target,
+    }));
+    logger.debug(formatCompact({
+      op: 'sandbox_send',
+      target: connection.target,
+      channelType: channel.type,
+      channelId: channel.id,
+    }));
     return payload;
   }
 
+  /** Prefer a real (non-placeholder) socket when reply target key is wrong/stale. */
+  #findLiveConnection(): SandboxConnection | undefined {
+    for (const connection of this.#connections.values()) {
+      if (!connection.placeholder) return connection;
+    }
+    return undefined;
+  }
+
   #acceptConnection(connection: WsConnection): void {
     const target = this.#options.defaults.randomNamePerConnection
       ? `sandbox-${randomUUID().slice(0, 8)}`
       : this.#options.defaults.name;
     const owner = this.#options.defaults.owner;
     const socket = connection.socket as SandboxWsSocket;
-    if (this.#connections.has(target)) {
-      this.#connections.get(target)?.release();
+    // Fixed-name mode reuses `target`; dropping the prior entry without
+    // closing its socket leaves a zombie browser tab that still looks
+    // connected but never receives outbound traffic.
+    const previous = this.#connections.get(target);
+    if (previous) {
+      previous.release();
+      if (!previous.placeholder) {
+        try {
+          previous.socket.close(4000, 'replaced by new sandbox client');
+        } catch {
+          /* already closed */
+        }
+      }
       this.#connections.delete(target);
     }
     const release = bindSandboxWsSocket(socket, {
       onMessage: (raw) => {
-        if (!this.#open) return;
         const parsed = parseSandboxWsPayload(raw);
+        const conn = this.#connections.get(target);
+        if (conn && !conn.placeholder) {
+          conn.lastChannel = {
+            type: parsed.type,
+            id: parsed.id || owner,
+          };
+        }
         logger.debug(formatCompact({
           op: 'sandbox_recv',
           target,
           sender: parsed.id || owner,
+          channelType: parsed.type,
+          channelId: parsed.id || owner,
           text: parsed.text.slice(0, 80),
         }));
+        // Don't gate on #open — inbound must always reach the gateway so
+        // Command/AI dispatch and outbound replies work.
         void this.#options.gateway.receive({
           adapter: this.#options.id,
           target,
@@ -128,6 +245,9 @@ export class SandboxWsEndpoint implements EndpointInstance {
           sender: parsed.id || owner,
           metadata: Object.freeze({
             type: parsed.type,
+            channelType: parsed.type,
+            channelId: parsed.id || owner,
+            endpoint: target,
             elements: parsed.content,
             timestamp: parsed.timestamp,
             ...(parsed.action ? { action: parsed.action } : {}),
@@ -141,8 +261,13 @@ export class SandboxWsEndpoint implements EndpointInstance {
         });
       },
       onClose: () => {
-        this.#connections.delete(target);
-        logger.debug(formatCompact({ op: 'sandbox_ws_closed', target }));
+        // Only drop the map entry if we still own this socket — a replace
+        // may have already swapped in a newer connection for the same target.
+        const current = this.#connections.get(target);
+        if (current && current.socket === socket) {
+          this.#connections.delete(target);
+          logger.debug(formatCompact({ op: 'sandbox_ws_closed', target }));
+        }
       },
       onError: (err) => {
         logger.warn(formatCompact({
@@ -152,7 +277,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
         }));
       },
     });
-    this.#connections.set(target, Object.freeze({ target, owner, socket, release }));
+    this.#connections.set(target, { target, owner, socket, release });
     logger.debug(formatCompact({ op: 'sandbox_ws_connected', target, owner }));
     if (!this.#options.defaults.randomNamePerConnection) {
       const readyPayload = JSON.stringify({
@@ -164,7 +289,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
           data: {
             text: [
               `已连接 Sandbox「${target}」`,
-              '与 Node Host 控制台沙盒协议一致（/sandbox）',
+              `与 Node Host 控制台沙盒协议一致（${this.#wsPath}）`,
               '命令: help · ping · zt · status',
             ].join('\n'),
           },
@@ -177,12 +302,12 @@ export class SandboxWsEndpoint implements EndpointInstance {
 
   #ensurePlaceholder(name: string, owner: string): void {
     if (this.#connections.has(name)) return;
-    this.#connections.set(name, Object.freeze({
+    this.#connections.set(name, {
       target: name,
       owner,
       socket: { send: () => undefined, close: () => undefined },
       release: () => undefined,
       placeholder: true,
-    }));
+    });
   }
 }

package/src/protocol.ts

@@ -33,6 +33,11 @@ export type ResolvedSandboxBot = {
 };
 
 export interface SandboxAdapterConfig {
+  /** Runtime expands `endpoints[i]` onto the top level — prefer these. */
+  readonly context?: string;
+  readonly name?: string;
+  readonly owner?: string;
+  /** Legacy shape: endpoint entries nested under `endpoints[]`. */
   readonly endpoints?: ReadonlyArray<{
     readonly context?: string;
     readonly name?: string;
@@ -44,9 +49,14 @@ export function resolveSandboxEndpoint(
   appConfig: SandboxAdapterConfig,
 ): ResolvedSandboxBot {
   const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
-  const fixedName = typeof entry?.name === 'string' ? entry.name : undefined;
+  const fixedName = typeof appConfig.name === 'string' && appConfig.name
+    ? appConfig.name
+    : typeof entry?.name === 'string' && entry.name
+      ? entry.name
+      : undefined;
   const name = fixedName || process.env.SANDBOX_BOT_NAME || 'sandbox-bot';
-  const owner = (typeof entry?.owner === 'string' && entry.owner)
+  const owner = (typeof appConfig.owner === 'string' && appConfig.owner)
+    || (typeof entry?.owner === 'string' && entry.owner)
     || process.env.SANDBOX_BOT_OWNER
     || 'sandbox-user';
   return {
@@ -161,26 +171,66 @@ export function parseSandboxWsPayload(raw: string): {
   return { type, id, content, timestamp: payload.timestamp ?? Date.now(), text, action };
 }
 
+export type SandboxOutboundChannel = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly bot?: string;
+  readonly endpoint?: string;
+  readonly messageId?: string;
+};
+
 /**
  * Wire-encode an already-rendered outbound payload.
- * Canonical segment mapping (old `segment-mapper` re-export of `to/fromCanonicalSegments`
- * from legacy `zhin.js`) is intentionally not done here — the gateway/core render path
- * owns that before `endpoint.send`.
+ * Stamps `channel` so Console SandboxChat can filter by type+id (otherwise
+ * replies look like they disappeared).
  */
-export function formatSandboxOutbound(payload: unknown): string {
+export function formatSandboxOutbound(
+  payload: unknown,
+  channel: SandboxOutboundChannel = {},
+): string {
+  const stamp: Record<string, unknown> = {};
+  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(),
     });
   }
-  return JSON.stringify({ 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 as object)
+      || 'type' in (payload as object) && 'timestamp' in (payload as object)
+    )
+  ) {
+    const envelope = payload as Record<string, unknown>;
+    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。 */

package/pages/sandbox.tsx

@@ -1,95 +0,0 @@
-import { definePage } from '@zhin.js/console-contract';
-import { useEffect, useRef, useState, type FormEvent } from 'react';
-
-export const meta = definePage({
-  title: 'Sandbox',
-  icon: 'Box',
-  order: 10,
-});
-
-/**
- * Convention page (ADR 0046). Plugin Runtime Host also serves a vanilla WS shell
- * for this localName so local smoke does not depend on a CDN React graph.
- */
-export default function SandboxPage() {
-  const [connected, setConnected] = useState(false);
-  const [input, setInput] = useState('');
-  const [lines, setLines] = useState<readonly { readonly kind: 'in' | 'out'; readonly text: string }[]>([]);
-  const wsRef = useRef<WebSocket | null>(null);
-
-  useEffect(() => {
-    const url = new URL('/sandbox', window.location.href);
-    url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-    const ws = new WebSocket(url);
-    wsRef.current = ws;
-    ws.addEventListener('open', () => setConnected(true));
-    ws.addEventListener('close', () => setConnected(false));
-    ws.addEventListener('message', (event) => {
-      let text = String(event.data);
-      try {
-        const data = JSON.parse(text) as {
-          content?: Array<{ data?: { text?: string } }> | string;
-        };
-        text = Array.isArray(data.content)
-          ? data.content.map((segment) => segment?.data?.text ?? '').filter(Boolean).join('\n')
-          : typeof data.content === 'string'
-            ? data.content
-            : text;
-      } catch {
-        /* keep raw */
-      }
-      setLines((previous) => [...previous, { kind: 'in', text }]);
-    });
-    return () => {
-      ws.close();
-      wsRef.current = null;
-    };
-  }, []);
-
-  const onSubmit = (event: FormEvent) => {
-    event.preventDefault();
-    const text = input.trim();
-    const ws = wsRef.current;
-    if (!text || !ws || ws.readyState !== WebSocket.OPEN) return;
-    ws.send(JSON.stringify({ text, timestamp: Date.now() }));
-    setLines((previous) => [...previous, { kind: 'out', text }]);
-    setInput('');
-  };
-
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', height: 'calc(100vh - 3rem)', maxWidth: 720, margin: '0 auto' }}>
-      <p style={{ padding: '0.75rem 1rem', margin: 0, color: '#71717a' }}>
-        {connected ? 'WebSocket /sandbox connected' : 'connecting…'}
-      </p>
-      <div style={{ flex: 1, overflow: 'auto', padding: '1rem', display: 'flex', flexDirection: 'column', gap: 8 }}>
-        {lines.map((line, index) => (
-          <div
-            key={`${line.kind}-${index}-${line.text.slice(0, 12)}`}
-            style={{
-              alignSelf: line.kind === 'out' ? 'flex-end' : 'flex-start',
-              background: line.kind === 'out' ? '#ccfbf1' : '#fff',
-              border: '1px solid #e4e4e7',
-              borderRadius: 10,
-              padding: '0.6rem 0.8rem',
-              maxWidth: '85%',
-              whiteSpace: 'pre-wrap',
-            }}
-          >
-            {line.text}
-          </div>
-        ))}
-      </div>
-      <form onSubmit={onSubmit} style={{ display: 'flex', gap: 8, padding: 12, borderTop: '1px solid #e4e4e7' }}>
-        <input
-          value={input}
-          onChange={(event) => setInput(event.target.value)}
-          placeholder="发送到 /sandbox …"
-          style={{ flex: 1, padding: '0.55rem 0.75rem', borderRadius: 8, border: '1px solid #d4d4d8' }}
-        />
-        <button type="submit" style={{ padding: '0.55rem 0.9rem', border: 0, borderRadius: 8, background: '#0f766e', color: '#fff' }}>
-          发送
-        </button>
-      </form>
-    </div>
-  );
-}