@zhin.js/adapter-sandbox 5.0.6 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @zhin.js/adapter-process
 
+## 6.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [5849336]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/client@2.1.0
+  - @zhin.js/host-http@1.0.2
+  - @zhin.js/page@1.0.2
+
 ## 5.0.6
 
 ### Patch Changes

package/README.md

@@ -42,24 +42,24 @@ Root 在 `zhin runtime start` 时装载 `@zhin.js/host-http`、`ConsoleRuntime`
 
 ## 配置
 
-**推荐（与 [minimal-bot](../../../examples/minimal-bot/) 一致）**：`endpoints: []`，在 Remote Console 打开「沙盒」页时经 `/sandbox` WebSocket **自动创建** bot（如 `sandbox-xxxx`），无需在 yaml 里写 `context: sandbox`。
+**推荐（与 [minimal-bot](../../../examples/minimal-bot/) 一致）**：`plugins.sandbox.endpoints: []`，在 Remote Console 打开「沙盒」页时经 `/sandbox` WebSocket **自动创建** bot（如 `sandbox-xxxx`），无需在 yaml 里写 `context: sandbox`。
 
 ```yaml
-# zhin.config.yml
-endpoints: []
-
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-sandbox"
-  - "@zhin.js/host-router"
-  - "@zhin.js/host-api"
+  sandbox:
+    endpoints: []
 ```
 
 可选：若需在启动时即在 bot 列表显示**固定名称**的离线占位 bot，可显式配置：
 
 ```yaml
-endpoints:
-  - context: sandbox
-    name: sandbox-bot
+plugins:
+  sandbox:
+    endpoints:
+      - name: sandbox-bot
+        context: sandbox
+        owner: sandbox-user
 ```
 
 ## 使用方式

package/lib/endpoint.js

@@ -45,8 +45,17 @@ export class SandboxWsEndpoint {
         this.#open = false;
         this.#wsHandleRelease?.();
         this.#wsHandleRelease = undefined;
-        for (const connection of this.#connections.values())
+        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' }));
@@ -54,7 +63,9 @@ export class SandboxWsEndpoint {
     send({ target, payload }) {
         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;
@@ -63,31 +74,75 @@ export class SandboxWsEndpoint {
             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() {
+        for (const connection of this.#connections.values()) {
+            if (!connection.placeholder)
+                return connection;
+        }
+        return undefined;
+    }
     #acceptConnection(connection) {
         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;
-        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,
@@ -95,6 +150,9 @@ export class SandboxWsEndpoint {
                     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 } : {}),
@@ -108,8 +166,13 @@ export class SandboxWsEndpoint {
                 });
             },
             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({
@@ -119,7 +182,7 @@ export class SandboxWsEndpoint {
                 }));
             },
         });
-        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({
@@ -144,12 +207,12 @@ export class SandboxWsEndpoint {
     #ensurePlaceholder(name, owner) {
         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/lib/protocol.d.ts

@@ -42,11 +42,17 @@ export declare function parseSandboxWsPayload(raw: string): {
         payload: string;
     };
 };
+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 declare function formatSandboxOutbound(payload: unknown): string;
+export declare function formatSandboxOutbound(payload: unknown, channel?: SandboxOutboundChannel): string;
 export declare function whenWsOpen(ws: SandboxWsSocket, fn: () => void): void;

package/lib/protocol.js

@@ -100,24 +100,53 @@ export function parseSandboxWsPayload(raw) {
 }
 /**
  * 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) {
+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(),
         });
     }
-    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
+            || '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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "5.0.6",
+  "version": "6.0.0",
   "description": "Zhin.js Sandbox adapter for Plugin Runtime (WebSocket /sandbox)",
   "type": "module",
   "main": "./lib/index.js",
@@ -46,35 +46,42 @@
     "directory": "plugins/adapters/sandbox"
   },
   "dependencies": {
+    "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.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@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.1",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/page": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "devDependencies": {
+    "@types/react": "^19.1.8",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "ws": "^8.21.0",
-    "@zhin.js/pagemanager": "2.0.4",
-    "@zhin.js/runtime": "1.0.1"
+    "@zhin.js/pagemanager": "2.0.5",
+    "@zhin.js/runtime": "1.0.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/client": "2.1.0",
     "@zhin.js/console-contract": "1.0.0",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
-    "@zhin.js/page": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@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": {
     "react": {
       "optional": true
+    },
+    "@zhin.js/client": {
+      "optional": true
     }
   },
   "publishConfig": {