@zhin.js/adapter-sandbox 5.0.5 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @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
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/host-http@1.0.1
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+  - @zhin.js/page@1.0.1
+
 ## 5.0.5
 
 ### Patch Changes

package/README.md

@@ -18,32 +18,48 @@ pnpm add @zhin.js/adapter-sandbox
 
 ## 依赖
 
-Sandbox 适配器需要以下服务插件：
+### Plugin Runtime（新，`zhin runtime start`）
+
+- `@zhin.js/adapter` — 约定式 `adapters/sandbox.ts`
+- `@zhin.js/host-http` — Root 提供的 `httpHostToken`（WebSocket `/sandbox` + Console HTTP）
+- `@zhin.js/core` — `messageGatewayToken` / ImRuntime 入站出站
+- `@zhin.js/page` + `pages/sandbox.tsx` — ADR 0046 约定页（`definePage`）
+
+Root 在 `zhin runtime start` 时装载 `@zhin.js/host-http`、`ConsoleRuntime` 与
+`ClientBuildModuleRuntime`。打开 `http://<host>:<port>/console` 可浏览页面；Sandbox 页
+（路由形如 `/…/p-sandbox`）内置 WebSocket `/sandbox` 聊天壳。
+
+旧 `client/`（`register(api)` / `pageManager.addEntry`）仅保留给 legacy Host 栈参考，
+**不是** Plugin Runtime 生产入口。
+
+### 旧 Host 栈（`zhin dev` / full-bot）
 
 - `@zhin.js/host-router` — HTTP 服务（提供 Router 和 WebSocket）
 - `@zhin.js/host-api` — Host 侧 Console API（`addEntry` 注册 Sandbox 扩展）
 - `@zhin.js/client` — Remote Console 客户端 SDK（UI 在 zhin-console 仓库）
 
+出站 wire 只做 JSON 封装；旧 `segment-mapper`（canonical segments）归一化上移到 gateway/core 渲染链。
+
 ## 配置
 
-**推荐（与 [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/adapters/sandbox.ts

@@ -0,0 +1,26 @@
+/**
+ * Convention entry: discover `adapters/sandbox.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { SandboxWsEndpoint } from '../src/endpoint.js';
+import {
+  resolveSandboxEndpoint,
+  type SandboxAdapterConfig,
+} from '../src/protocol.js';
+
+export { SandboxWsEndpoint } from '../src/endpoint.js';
+export type { SandboxEndpointOptions } from '../src/endpoint.js';
+
+export default defineAdapter<SandboxAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new SandboxWsEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      http: context.use(httpHostToken),
+      defaults: resolveSandboxEndpoint(context.config),
+    });
+  },
+});

package/lib/endpoint.d.ts

@@ -0,0 +1,25 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type ResolvedSandboxBot } from './protocol.js';
+export interface SandboxEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly defaults: ResolvedSandboxBot;
+}
+export declare class SandboxWsEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: SandboxEndpointOptions);
+    /** Live endpoint name (config `name`) — Console endpoint.list/resolve uses it. */
+    get name(): string;
+    start(): void;
+    open(): void;
+    close(): void;
+    stop(): void;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): unknown;
+}

package/lib/endpoint.js

@@ -0,0 +1,218 @@
+/**
+ * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway bridge for /sandbox.
+ */
+import { randomUUID } from 'node:crypto';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { bindSandboxWsSocket, formatSandboxOutbound, parseSandboxWsPayload, whenWsOpen, } from './protocol.js';
+const logger = getLogger('sandbox');
+export class SandboxWsEndpoint {
+    #options;
+    #connections = new Map();
+    #wsHandleRelease;
+    #open = false;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Live endpoint name (config `name`) — Console endpoint.list/resolve uses it. */
+    get name() {
+        return this.#options.defaults.name;
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const handle = this.#options.http.ws('/sandbox');
+        this.#wsHandleRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        if (!this.#options.defaults.randomNamePerConnection) {
+            this.#ensurePlaceholder(this.#options.defaults.name, this.#options.defaults.owner);
+        }
+        logger.info(formatCompact({
+            op: 'sandbox_ws_mounted',
+            path: '/sandbox',
+            endpoint: this.#options.defaults.name,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    stop() {
+        this.#open = false;
+        this.#wsHandleRelease?.();
+        this.#wsHandleRelease = 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' }));
+    }
+    send({ target, payload }) {
+        if (!this.#open)
+            return undefined;
+        // 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;
+        }
+        if (connection.placeholder) {
+            logger.debug(formatCompact({ op: 'sandbox_send_placeholder', target }));
+            return undefined;
+        }
+        // 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;
+        // 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) => {
+                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,
+                    content: parsed.text,
+                    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 } : {}),
+                    }),
+                }).catch((err) => {
+                    logger.warn(formatCompact({
+                        op: 'sandbox_gateway_receive_failed',
+                        target,
+                        error: err instanceof Error ? err.message : String(err),
+                    }));
+                });
+            },
+            onClose: () => {
+                // 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({
+                    op: 'sandbox_ws_error',
+                    target,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            },
+        });
+        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({
+                type: 'ready',
+                id: owner,
+                endpoint: target,
+                content: [{
+                        type: 'text',
+                        data: {
+                            text: [
+                                `已连接 Sandbox「${target}」`,
+                                '与 Node Host 控制台沙盒协议一致（/sandbox）',
+                                '命令: help · ping · zt · status',
+                            ].join('\n'),
+                        },
+                    }],
+                timestamp: Date.now(),
+            });
+            whenWsOpen(socket, () => socket.send(readyPayload));
+        }
+    }
+    #ensurePlaceholder(name, owner) {
+        if (this.#connections.has(name))
+            return;
+        this.#connections.set(name, {
+            target: name,
+            owner,
+            socket: { send: () => undefined, close: () => undefined },
+            release: () => undefined,
+            placeholder: true,
+        });
+    }
+}

package/lib/index.d.ts

@@ -1,22 +1,2 @@
-import { usePlugin } from "zhin.js";
-import { SandboxWsHostAdapter } from "./sandbox-ws.js";
-type SandboxRouter = {
-    ws: (path: string) => NonNullable<SandboxAdapter["wss"]>;
-};
-declare module "zhin.js" {
-    interface Adapters {
-        sandbox: SandboxAdapter;
-    }
-}
-/** Node：`Router.ws` */
-export declare class SandboxAdapter extends SandboxWsHostAdapter {
-    wss?: {
-        on: (ev: string, fn: (...args: unknown[]) => void) => void;
-        close: () => void;
-    };
-    constructor(plugin: ReturnType<typeof usePlugin>);
-    start(): Promise<void>;
-    setupWebSocket(router: SandboxRouter): Promise<void>;
-}
-export { SandboxWsEndpoint, SandboxWsHostAdapter, resolveSandboxEndpoint, bindSandboxWsSocket, parseSandboxWsPayload, type ResolvedSandboxBot, type SandboxWsConfig, type SandboxWsSocket, } from "./sandbox-ws.js";
-//# sourceMappingURL=index.d.ts.map
+export { bindSandboxWsSocket, formatSandboxOutbound, parseSandboxWsPayload, resolveSandboxEndpoint, whenWsOpen, type MessageElement, type MessageType, type ResolvedSandboxBot, type SandboxAdapterConfig, type SandboxWsSocket, } from './protocol.js';
+export { SandboxWsEndpoint, type SandboxEndpointOptions, } from './endpoint.js';

package/lib/index.js

@@ -1,67 +1,2 @@
-import path from "node:path";
-import { usePlugin } from "zhin.js";
-import { SandboxWsHostAdapter, resolveSandboxEndpoint, } from "./sandbox-ws.js";
-const plugin = usePlugin();
-const logger = plugin.logger;
-/** Node：`Router.ws` */
-export class SandboxAdapter extends SandboxWsHostAdapter {
-    wss;
-    constructor(plugin) {
-        const appConfig = (plugin.inject("config")?.getPrimary() ?? {});
-        super(plugin, resolveSandboxEndpoint(appConfig));
-    }
-    async start() {
-        await super.start();
-        this.registerConfiguredPlaceholder();
-        logger.debug(`Sandbox placeholder: ${this.defaults.name} (offline until /sandbox WS)`);
-    }
-    async setupWebSocket(router) {
-        if (this.wss)
-            return;
-        this.wss = router.ws("/sandbox");
-        this.wss.on("connection", (...args) => {
-            const ws = args[0];
-            const req = args[1];
-            logger.debug(`New sandbox connection from ${req.socket?.remoteAddress ?? "unknown"}`);
-            const endpoint = this.acceptWebSocket(ws);
-            ws.on("close", () => {
-                logger.debug(`Sandbox connection closed: ${endpoint.$config.name}`);
-                this.endpoints.delete(endpoint.$id);
-            });
-            ws.on("error", (error) => {
-                logger.error(`Sandbox WebSocket error for ${endpoint.$config.name}:`, error);
-            });
-        });
-        logger.debug("Sandbox WebSocket server started at /sandbox (Node Router.ws)");
-    }
-}
-const { provide } = usePlugin();
-provide({
-    name: "sandbox",
-    description: "Sandbox Adapter — Node Router.ws",
-    mounted: async (p) => {
-        const adapter = new SandboxAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        for (const endpoint of adapter.endpoints.values()) {
-            await endpoint.$disconnect();
-        }
-        adapter.wss?.close();
-        await adapter.stop();
-    },
-});
-plugin.useContext("router", 'sandbox', async (router, adapter) => {
-    await adapter.setupWebSocket(router);
-});
-plugin.useContext("web", (pageManager) => {
-    pageManager.addEntry({
-        id: "sandbox",
-        development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-        production: path.resolve(import.meta.dirname, "../dist/index.js"),
-        meta: { name: "Sandbox" },
-    });
-});
-export { SandboxWsEndpoint, SandboxWsHostAdapter, resolveSandboxEndpoint, bindSandboxWsSocket, parseSandboxWsPayload, } from "./sandbox-ws.js";
-//# sourceMappingURL=index.js.map
+export { bindSandboxWsSocket, formatSandboxOutbound, parseSandboxWsPayload, resolveSandboxEndpoint, whenWsOpen, } from './protocol.js';
+export { SandboxWsEndpoint, } from './endpoint.js';

package/lib/protocol.d.ts

@@ -0,0 +1,58 @@
+/** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
+export type MessageType = 'private' | 'group' | 'guild' | 'direct' | 'channel';
+export interface MessageElement {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface SandboxWsSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on?(event: 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+    off?(event: 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+    addEventListener?(type: 'message' | 'close' | 'error', listener: (ev: Event | MessageEvent | CloseEvent) => void): void;
+    removeEventListener?(type: 'message' | 'close' | 'error', listener: (ev: Event | MessageEvent | CloseEvent) => void): void;
+}
+export type ResolvedSandboxBot = {
+    readonly context: 'sandbox';
+    readonly name: string;
+    readonly owner: string;
+    readonly randomNamePerConnection: boolean;
+};
+export interface SandboxAdapterConfig {
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly name?: string;
+        readonly owner?: string;
+    }>;
+}
+export declare function resolveSandboxEndpoint(appConfig: SandboxAdapterConfig): ResolvedSandboxBot;
+export declare function bindSandboxWsSocket(ws: SandboxWsSocket, handlers: {
+    onMessage: (raw: string) => void;
+    onClose: () => void;
+    onError?: (err: unknown) => void;
+}): () => void;
+export declare function parseSandboxWsPayload(raw: string): {
+    type: MessageType;
+    id: string;
+    content: MessageElement[];
+    timestamp: number;
+    text: string;
+    action?: {
+        id: 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.
+ * Stamps `channel` so Console SandboxChat can filter by type+id (otherwise
+ * replies look like they disappeared).
+ */
+export declare function formatSandboxOutbound(payload: unknown, channel?: SandboxOutboundChannel): string;
+export declare function whenWsOpen(ws: SandboxWsSocket, fn: () => void): void;