@zhin.js/adapter-sandbox 3.0.1 → 3.0.3

package/lib/sandbox-ws.js

@@ -0,0 +1,337 @@
+/**
+ * Sandbox 传输 — Node WebSocket；Edge HTTP+SSE（见 sandbox-sse-hub / fetch-sse）。
+ */
+import { EventEmitter } from "node:events";
+import { broadcastSandboxSse, closeSandboxSseSession } from "./sandbox-sse-hub.js";
+import { Adapter, Message, segment, } from "zhin.js";
+/** 无 WS 时的占位 socket（仅用于 bot:list，不可收发） */
+export function createOfflineSandboxWs() {
+    return { send: () => { }, close: () => { } };
+}
+export function createSandboxSseTransport(sessionId, onClose) {
+    return {
+        sessionId,
+        send(data) {
+            broadcastSandboxSse(sessionId, data);
+        },
+        close() {
+            closeSandboxSseSession(sessionId);
+            onClose?.();
+        },
+    };
+}
+function envVar(key) {
+    const g = globalThis;
+    return g.Deno?.env.get(key) ?? g.process?.env[key];
+}
+export function resolveSandboxBot(appConfig) {
+    const bots = appConfig.bots;
+    const entry = bots?.find((b) => b.context === "sandbox");
+    const fixedName = typeof entry?.name === "string" ? entry.name : undefined;
+    const name = fixedName ||
+        envVar("SANDBOX_BOT_NAME") ||
+        "sandbox-bot";
+    const owner = (typeof entry?.owner === "string" && entry.owner) ||
+        envVar("SANDBOX_BOT_OWNER") ||
+        "sandbox-user";
+    const transportRaw = (typeof entry?.transport === "string" && entry.transport) ||
+        envVar("SANDBOX_TRANSPORT") ||
+        "websocket";
+    const transport = transportRaw === "http-sse" || transportRaw === "sse" ? "http-sse" : "websocket";
+    return {
+        context: "sandbox",
+        name,
+        owner,
+        randomNamePerConnection: !fixedName,
+        transport,
+    };
+}
+/** 标准 WebSocket 在 upgrade 后可能尚未 OPEN；Node `ws` 在 connection 回调里通常已可 send */
+function whenWsOpen(ws, fn) {
+    const std = ws;
+    if (typeof std.readyState === "number") {
+        if (std.readyState === WebSocket.OPEN) {
+            fn();
+            return;
+        }
+        std.addEventListener("open", fn, { once: true });
+        return;
+    }
+    fn();
+}
+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 } }];
+    return { type, id, content, timestamp: payload.timestamp ?? Date.now() };
+}
+export class SandboxWsBot extends EventEmitter {
+    adapter;
+    $config;
+    $connected = false;
+    #unbind = null;
+    get $id() {
+        return this.$config.name;
+    }
+    constructor(adapter, $config) {
+        super();
+        this.adapter = adapter;
+        this.$config = $config;
+    }
+    async $connect() {
+        if (this.$config.offline || !this.$config.ws)
+            return;
+        const ws = this.$config.ws;
+        if (typeof ws.on !== "function" && typeof ws.addEventListener !== "function") {
+            this.$connected = true;
+            return;
+        }
+        this.#unbind = bindSandboxWsSocket(ws, {
+            onMessage: (raw) => {
+                const { type, id, content, timestamp } = parseSandboxWsPayload(raw);
+                this.adapter.emit("message.receive", this.$formatMessage({ content, type, id, ts: timestamp }));
+            },
+            onClose: () => {
+                this.$connected = false;
+                if (!this.$config.offline) {
+                    this.adapter.bots.delete(this.$id);
+                }
+            },
+            onError: (err) => {
+                this.adapter.logger.warn(`sandbox ws error (${this.$config.name}): ${err instanceof Error ? err.message : String(err)}`);
+            },
+        });
+        this.$connected = true;
+    }
+    async $disconnect() {
+        this.#unbind?.();
+        this.#unbind = null;
+        this.$config.ws?.close();
+        this.$connected = false;
+    }
+    $formatMessage({ content, type, id, ts }) {
+        if (!this.$config.owner)
+            this.$config.owner = id;
+        const message = Message.from({ content, type, id, ts }, {
+            $id: `${ts}`,
+            $adapter: "sandbox",
+            $bot: this.$config.name,
+            $sender: { id, name: "mock" },
+            $channel: { id, type },
+            $content: content,
+            $raw: segment.raw(content),
+            $timestamp: ts,
+            $recall: async () => { },
+            $reply: async (replyContent, quote) => {
+                const normalized = Array.isArray(replyContent) ? replyContent : [replyContent];
+                if (quote) {
+                    normalized.unshift({
+                        type: "reply",
+                        data: {
+                            id: typeof quote === "boolean" ? message.$id : quote,
+                        },
+                    });
+                }
+                return await this.adapter.sendMessage({
+                    context: "sandbox",
+                    bot: this.$config.name,
+                    content: normalized,
+                    id,
+                    type,
+                });
+            },
+        });
+        return message;
+    }
+    async $sendMessage(options) {
+        if (!this.$connected)
+            return "";
+        const ws = this.$config.ws;
+        if (!ws)
+            return "";
+        ws.send(JSON.stringify({
+            ...options,
+            content: options.content,
+            timestamp: Date.now(),
+        }));
+        return "";
+    }
+    async $recallMessage(_id) { }
+}
+export class SandboxWsHostAdapter extends Adapter {
+    defaults;
+    #sseSessions = new Map();
+    constructor(plugin, defaults) {
+        super(plugin, "sandbox", []);
+        this.defaults = defaults;
+    }
+    get transport() {
+        return this.defaults.transport;
+    }
+    hasSseSession(sessionId) {
+        return this.#sseSessions.has(sessionId);
+    }
+    getBotBySseSession(sessionId) {
+        const name = this.#sseSessions.get(sessionId);
+        return name ? this.bots.get(name) : undefined;
+    }
+    createBot(config) {
+        const bot = new SandboxWsBot(this, config);
+        this.bots.set(bot.$id, bot);
+        return bot;
+    }
+    /** `zhin.config.yml` 中 `context: sandbox` + 固定 `name` 时，启动即出现在 bot:list（离线） */
+    registerConfiguredPlaceholder() {
+        if (this.defaults.randomNamePerConnection)
+            return;
+        if (this.bots.has(this.defaults.name))
+            return;
+        this.createBot({
+            context: "sandbox",
+            name: this.defaults.name,
+            owner: this.defaults.owner,
+            ws: createOfflineSandboxWs(),
+            offline: true,
+        });
+    }
+    /** Edge / 外部 upgrade：注入已建立的 WebSocket */
+    acceptWebSocket(ws, overrides) {
+        const name = overrides?.name ??
+            (this.defaults.randomNamePerConnection
+                ? `sandbox-${crypto.randomUUID().slice(0, 8)}`
+                : this.defaults.name);
+        const owner = overrides?.owner ?? this.defaults.owner;
+        const existing = this.bots.get(name);
+        if (existing) {
+            void existing.$disconnect();
+            this.bots.delete(name);
+        }
+        const bot = this.createBot({ context: "sandbox", ws, name, owner, offline: false });
+        void bot.$connect();
+        if (!this.defaults.randomNamePerConnection) {
+            const readyPayload = JSON.stringify({
+                type: "ready",
+                id: owner,
+                bot: name,
+                content: [
+                    {
+                        type: "text",
+                        data: {
+                            text: [
+                                `已连接 Sandbox「${name}」`,
+                                "与 Node Host 控制台沙盒协议一致（/sandbox）",
+                                "命令: help · ping · zt · status",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+                timestamp: Date.now(),
+            });
+            whenWsOpen(ws, () => ws.send(readyPayload));
+        }
+        return bot;
+    }
+    /** Edge SSE：建立会话并绑定固定 bot */
+    acceptSseSession(sessionId, overrides) {
+        const name = overrides?.name ?? this.defaults.name;
+        const owner = overrides?.owner ?? this.defaults.owner;
+        const existing = this.bots.get(name);
+        if (existing) {
+            void existing.$disconnect();
+            this.bots.delete(name);
+        }
+        const ws = createSandboxSseTransport(sessionId, () => {
+            this.#sseSessions.delete(sessionId);
+            this.bots.delete(name);
+        });
+        const bot = this.createBot({ context: "sandbox", ws, name, owner, offline: false });
+        this.#sseSessions.set(sessionId, name);
+        void bot.$connect();
+        if (!this.defaults.randomNamePerConnection) {
+            const readyPayload = JSON.stringify({
+                type: "ready",
+                id: owner,
+                bot: name,
+                content: [
+                    {
+                        type: "text",
+                        data: {
+                            text: [
+                                `已连接 Sandbox「${name}」`,
+                                "传输: HTTP + SSE（Edge）",
+                                "命令: help · ping · zt · status",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+                timestamp: Date.now(),
+            });
+            ws.send(readyPayload);
+        }
+        return bot;
+    }
+    /** POST /sandbox/message — 与 WebSocket 帧同格式的 JSON 字符串 */
+    ingestSseClientMessage(sessionId, raw) {
+        const bot = this.getBotBySseSession(sessionId);
+        if (!bot || !bot.$connected) {
+            throw new Error(`sandbox session not connected: ${sessionId}`);
+        }
+        const { type, id, content, timestamp } = parseSandboxWsPayload(raw);
+        this.emit("message.receive", bot.$formatMessage({ content, type, id, ts: timestamp }));
+    }
+}
+//# sourceMappingURL=sandbox-ws.js.map

package/lib/sandbox-ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-ws.js","sourceRoot":"","sources":["../src/sandbox-ws.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Zhin.js adapter for local testing and development",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,25 +43,30 @@
     "directory": "plugins/adapters/sandbox"
   },
   "devDependencies": {
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "radix-ui": "^1.4.3",
     "lucide-react": "^1.16.0",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.78",
-    "zhin.js": "1.0.82"
+    "@zhin.js/http-host": "0.1.3",
+    "@zhin.js/cli": "1.0.80",
+    "zhin.js": "1.0.84"
   },
   "peerDependencies": {
-    "@zhin.js/core": "1.1.24",
-    "@zhin.js/client": "1.1.1",
-    "@zhin.js/http": "1.0.75",
-    "@zhin.js/console": "3.0.1",
-    "zhin.js": "1.0.82"
+    "@zhin.js/core": "1.1.26",
+    "@zhin.js/client": "1.1.3",
+    "@zhin.js/http": "1.0.77",
+    "@zhin.js/http-host": "0.1.3",
+    "@zhin.js/console": "3.0.3",
+    "zhin.js": "1.0.84"
   },
   "peerDependenciesMeta": {
     "@zhin.js/http": {
       "optional": true
     },
+    "@zhin.js/http-host": {
+      "optional": true
+    },
     "@zhin.js/console": {
       "optional": true
     },

package/src/fetch-sse.ts

@@ -0,0 +1,87 @@
+import { registerFetchRoute, type RouteTable } from "@zhin.js/http-host/edge";
+import type { RouterContext } from "@zhin.js/http-host/edge";
+import type { SandboxWsHostAdapter } from "./sandbox-ws.js";
+import { subscribeSandboxSse } from "./sandbox-sse-hub.js";
+
+export type RegisterSandboxSseOptions = {
+  eventsPath?: string;
+  messagePath?: string;
+};
+
+function resolveSessionId(ctx: RouterContext): string | undefined {
+  const q = ctx.query.session?.trim();
+  if (q) return q;
+  const h = ctx.get("x-sandbox-session")?.trim();
+  if (h) return h;
+  const body = ctx.request.body as { session?: string } | undefined;
+  if (body && typeof body.session === "string" && body.session.trim()) {
+    return body.session.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Edge / Vercel 等：Sandbox 使用 HTTP POST 上行 + SSE 下行（无 WebSocket upgrade）。
+ */
+export function registerSandboxSseRoutes(
+  table: RouteTable,
+  getAdapter: () => SandboxWsHostAdapter,
+  options: RegisterSandboxSseOptions = {},
+): void {
+  const eventsPath = options.eventsPath ?? "/sandbox/events";
+  const messagePath = options.messagePath ?? "/sandbox/message";
+
+  registerFetchRoute(table, "GET", eventsPath, (ctx: RouterContext) => {
+    const sessionId = resolveSessionId(ctx);
+    if (!sessionId) {
+      ctx.status = 400;
+      ctx.body = { success: false, error: "Missing session (query ?session= or X-Sandbox-Session)" };
+      return;
+    }
+    const adapter = getAdapter();
+    if (!adapter.hasSseSession(sessionId)) {
+      adapter.acceptSseSession(sessionId);
+    }
+    const lastEventId = ctx.query["last-event-id"] ?? ctx.query.lastEventId;
+    const stream = subscribeSandboxSse(sessionId, lastEventId);
+    ctx.status = 200;
+    ctx.set("Content-Type", "text/event-stream; charset=utf-8");
+    ctx.set("Cache-Control", "no-cache, no-transform");
+    ctx.set("Connection", "keep-alive");
+    ctx.set("X-Accel-Buffering", "no");
+    ctx.body = stream;
+  });
+
+  registerFetchRoute(table, "POST", messagePath, async (ctx: RouterContext) => {
+    const sessionId = resolveSessionId(ctx);
+    if (!sessionId) {
+      ctx.status = 400;
+      ctx.body = { success: false, error: "Missing session (X-Sandbox-Session or body.session)" };
+      return;
+    }
+    const adapter = getAdapter();
+    if (!adapter.hasSseSession(sessionId)) {
+      ctx.status = 404;
+      ctx.body = { success: false, error: "No sandbox session; open GET /sandbox/events first" };
+      return;
+    }
+    const body = ctx.request.body;
+    const raw = typeof body === "string"
+      ? body
+      : body === undefined || body === null
+      ? ""
+      : JSON.stringify(body);
+    if (!raw) {
+      ctx.status = 400;
+      ctx.body = { success: false, error: "Empty message body" };
+      return;
+    }
+    try {
+      adapter.ingestSseClientMessage(sessionId, raw);
+      ctx.body = { success: true };
+    } catch (err) {
+      ctx.status = 500;
+      ctx.body = { success: false, error: (err as Error).message };
+    }
+  });
+}

package/src/fetch-ws.ts

@@ -0,0 +1,23 @@
+import { registerWebSocketRoute, type RouteTable } from "@zhin.js/http-host/edge";
+import type { SandboxWsHostAdapter, SandboxWsSocket } from "./sandbox-ws.js";
+
+export type RegisterSandboxWsOptions = {
+  /** 兼容旧路径，默认 `/ws` */
+  legacyPaths?: string[];
+};
+
+/**
+ * Deno / Edge：在 {@link RouteTable} 上注册 `/sandbox` WebSocket（http-host Fetch upgrade）。
+ */
+export function registerSandboxWebSocketRoutes(
+  table: RouteTable,
+  getAdapter: () => SandboxWsHostAdapter,
+  options: RegisterSandboxWsOptions = {},
+): void {
+  const paths = ["/sandbox", ...(options.legacyPaths ?? ["/ws"])];
+  for (const path of paths) {
+    registerWebSocketRoute(table, path, (ws: unknown) => {
+      getAdapter().acceptWebSocket(ws as SandboxWsSocket);
+    });
+  }
+}