@zhin.js/core 1.1.34 → 1.1.35

package/lib/built/dispatcher.js

@@ -27,7 +27,7 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { getPlugin } from '../plugin.js';
+import { isActionMessage } from './interactive-segments/action.js';
 /** Dispatcher 管理的「会话回复」异步上下文，供 `before.sendMessage` 内读取（与 Adapter.renderSendMessage 同链） */
 const outboundReplyAls = new AsyncLocalStorage();
 export function getOutboundReplyStore() {
@@ -52,6 +52,7 @@ export function createMessageDispatcher(options) {
     const guardrails = [];
     /** mounted 前注册的润色，在 mounted 时挂到 root.before.sendMessage */
     const pendingOutboundPolish = [];
+    const flushedOutboundPolish = new Map();
     let aiHandler = null;
     let aiTriggerMatcher = null;
     let groupPassiveContextHandler = null;
@@ -193,18 +194,34 @@ export function createMessageDispatcher(options) {
         for (const mw of pendingOutboundPolish) {
             const fn = wrapPolishAsBeforeSend(mw);
             root.on('before.sendMessage', fn);
+            flushedOutboundPolish.set(mw, fn);
         }
         pendingOutboundPolish.length = 0;
     }
     async function replyWithPolishInternal(message, source, content, options) {
         const quote = options?.quote;
+        if (!message.$reply) {
+            throw new Error(`Cannot reply: endpoint ${message.$endpoint} on adapter ${String(message.$adapter)} has no outbound capability`);
+        }
         if (!rootPlugin) {
             return quote ? message.$reply(content, quote) : message.$reply(content);
         }
-        return outboundReplyAls.run({ message, source }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+        return outboundReplyAls.run({
+            message,
+            source,
+            trigger: 'inbound',
+        }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+    }
+    async function runWithOutboundPolish(store, fn) {
+        return outboundReplyAls.run({
+            message: store.message,
+            source: store.source ?? 'proactive',
+            trigger: store.trigger,
+            proactiveSource: store.proactiveSource,
+        }, fn);
     }
     async function maybeRecordGroupPassiveContext(message) {
-        if (!groupPassiveContextHandler)
+        if (!groupPassiveContextHandler || isActionMessage(message))
             return;
         const scope = message.$channel?.type;
         if (scope !== 'group' && scope !== 'channel')
@@ -222,7 +239,7 @@ export function createMessageDispatcher(options) {
         const commandService = rootPlugin.inject('command');
         if (!commandService)
             return;
-        const response = await commandService.handle(message, rootPlugin);
+        const response = await commandService.handle(message, options?.permissionHost ?? null);
         if (response !== undefined && response !== null) {
             await replyWithPolishInternal(message, 'command', response);
         }
@@ -321,11 +338,19 @@ export function createMessageDispatcher(options) {
                 const i = pendingOutboundPolish.indexOf(handler);
                 if (i !== -1)
                     pendingOutboundPolish.splice(i, 1);
+                const flushed = flushedOutboundPolish.get(handler);
+                if (flushed && rootPlugin) {
+                    rootPlugin.root.off('before.sendMessage', flushed);
+                    flushedOutboundPolish.delete(handler);
+                }
             };
         },
         replyWithPolish(message, source, content, options) {
             return replyWithPolishInternal(message, source, content, options);
         },
+        runWithOutboundPolish(store, fn) {
+            return runWithOutboundPolish(store, fn);
+        },
         matchCommand(message) {
             return matchCommandInternal(message);
         },
@@ -344,18 +369,15 @@ export function createMessageDispatcher(options) {
         },
         extensions: {
             addGuardrail(guardrail) {
-                const plugin = getPlugin();
                 const dispose = service.addGuardrail(guardrail);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
             addOutboundPolish(handler) {
-                const plugin = getPlugin();
                 const dispose = service.addOutboundPolish(handler);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
         },
     };
 }
-//# sourceMappingURL=dispatcher.js.map

package/lib/built/endpoint-commands.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFeature } from './command.js';
+import type { Plugin } from '../plugin.js';
+export declare function registerEndpointManagementCommands(plugin: Plugin, commandService: CommandFeature): () => void;

package/lib/built/endpoint-commands.js

@@ -0,0 +1,99 @@
+/**
+ * IM Endpoint 管理与 /endpoints 内省命令（@zhin.js/core）
+ */
+import { Adapter } from '../adapter.js';
+import { MessageCommand } from '../command.js';
+import { MANAGEMENT_OPERATOR_PERMIT } from './management-command-guard.js';
+import { createEndpointLifecycleService } from './endpoint-lifecycle-service.js';
+import { endpointHelpText, formatEndpointsList } from './introspection-format.js';
+function collectRuntimeEndpoints(root) {
+    const rows = [];
+    for (const adapterName of root.adapters) {
+        const adapter = root.inject(adapterName);
+        if (!(adapter instanceof Adapter))
+            continue;
+        for (const [endpointKey, endpoint] of adapter.endpoints.entries()) {
+            rows.push({
+                adapter: String(adapterName),
+                name: endpointKey,
+                online: !!endpoint.$connected,
+            });
+        }
+    }
+    return rows;
+}
+export function registerEndpointManagementCommands(plugin, commandService) {
+    const root = plugin.root;
+    const disposers = [];
+    const service = () => createEndpointLifecycleService(root);
+    const register = (pattern, desc, handler) => {
+        const cmd = new MessageCommand(pattern)
+            .desc(desc)
+            .permit(MANAGEMENT_OPERATOR_PERMIT)
+            .action(async (message, match) => {
+            try {
+                return await handler(message, match);
+            }
+            catch (err) {
+                return `❌ ${err instanceof Error ? err.message : String(err)}`;
+            }
+        });
+        commandService.add(cmd, plugin.name);
+        disposers.push(() => commandService.remove(cmd));
+    };
+    register('/endpoint help', 'Endpoint 管理帮助', () => endpointHelpText());
+    register('/endpoint add [adapter:word]', '添加 Endpoint', async (message, match) => {
+        const adapterKey = typeof match?.params?.adapter === 'string' ? match.params.adapter.trim() : '';
+        if (!adapterKey) {
+            const list = service().listProvisionableAdapters();
+            if (list.length === 0) {
+                return '当前没有支持运行时添加的适配器（需 EndpointManager 或 endpointConfigSchema）。';
+            }
+            return [
+                '可用适配器：',
+                ...list.map((a) => `  • ${a}  — /endpoint add ${a}`),
+            ].join('\n');
+        }
+        const result = await service().add(adapterKey, message);
+        return result.message;
+    });
+    register('/endpoint remove <adapter:word> <name:word>', '从配置移除 Endpoint', async (_message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().remove(adapterKey, name);
+        return result.message;
+    });
+    register('/endpoint edit <adapter:word> <name:word>', '编辑 Endpoint 配置', async (message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().edit(adapterKey, name, message);
+        return result.message;
+    });
+    register('/endpoint start <adapter:word> <name:word>', '连接 Endpoint', async (message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().start(adapterKey, name, message);
+        return result.message;
+    });
+    register('/endpoint stop <adapter:word> <name:word>', '断开 Endpoint（保留配置）', async (_message, match) => {
+        const adapterKey = String(match?.params?.adapter ?? '');
+        const name = String(match?.params?.name ?? '');
+        const result = await service().stop(adapterKey, name);
+        return result.message;
+    });
+    register('/endpoint cancel', '取消进行中的 Endpoint 添加/绑定', () => {
+        if (!service().cancelProvision()) {
+            return '当前没有进行中的 Endpoint 绑定流程。';
+        }
+        return '已取消 Endpoint 绑定流程。';
+    });
+    register('/endpoint sync', '将内存中的 endpoint 配置写回 zhin.config', async () => {
+        const result = await service().syncToDisk();
+        return result.message;
+    });
+    register('/endpoints', '列出各适配器下的 Endpoint 及在线状态', () => formatEndpointsList(collectRuntimeEndpoints(root)));
+    return () => {
+        for (const d of disposers)
+            d();
+    };
+}

package/lib/built/endpoint-lifecycle-service.d.ts

@@ -0,0 +1,28 @@
+import { Adapter } from '../adapter.js';
+import type { Endpoint } from '../endpoint.js';
+import type { Message } from '../message.js';
+import type { Plugin } from '../plugin.js';
+import type { EndpointConfigRecord, EndpointManager } from './endpoint-manager.js';
+export interface EndpointLifecycleResult {
+    message: string;
+    config?: EndpointConfigRecord;
+}
+export declare class EndpointLifecycleService {
+    private readonly root;
+    constructor(root: Plugin);
+    resolveAdapter(adapterKey: string): Adapter;
+    resolveManager(adapterKey: string): EndpointManager;
+    listProvisionableAdapters(): string[];
+    persistEndpoints(endpoints: EndpointConfigRecord[]): Promise<void>;
+    /** 将内存中的 endpoints 写回 zhin.config（修复运行时与磁盘不一致） */
+    syncToDisk(): Promise<EndpointLifecycleResult>;
+    connectConfig(adapter: Adapter, config: EndpointConfigRecord): Promise<Endpoint>;
+    disconnectRuntime(adapter: Adapter, name: string): Promise<boolean>;
+    add(adapterKey: string, message: Message, initialReply?: string): Promise<EndpointLifecycleResult>;
+    edit(adapterKey: string, name: string, message: Message): Promise<EndpointLifecycleResult>;
+    remove(adapterKey: string, name: string): Promise<EndpointLifecycleResult>;
+    start(adapterKey: string, name: string, message: Message): Promise<EndpointLifecycleResult>;
+    stop(adapterKey: string, name: string): Promise<EndpointLifecycleResult>;
+    cancelProvision(): boolean;
+}
+export declare function createEndpointLifecycleService(root: Plugin): EndpointLifecycleService;

package/lib/built/endpoint-lifecycle-service.js

@@ -0,0 +1,242 @@
+import { formatDisplayPath } from '@zhin.js/logger';
+import { Adapter } from '../adapter.js';
+import { segment } from '../utils.js';
+import { connectEndpointInstance, disconnectEndpointInstance } from './connect-endpoint-instance.js';
+import { adapterSupportsProvision, resolveEndpointManager } from './schema-endpoint-manager.js';
+function getConfigService(root) {
+    const configService = root.inject('config');
+    if (!configService?.primaryFile) {
+        throw new Error('配置服务不可用');
+    }
+    const loader = configService.configs.get(configService.primaryFile);
+    if (!loader) {
+        throw new Error('配置文件未加载');
+    }
+    return configService;
+}
+function readAllEndpoints(root) {
+    const configService = getConfigService(root);
+    const raw = configService.getRaw(configService.primaryFile);
+    return [...(raw?.endpoints ?? [])];
+}
+function assertUniqueName(endpoints, context, name, replaceIndex) {
+    const conflict = endpoints.findIndex((e) => e.context === context && e.id === name);
+    if (conflict >= 0 && conflict !== replaceIndex) {
+        throw new Error(`zhin.config 中已存在 ${context}/${name}`);
+    }
+}
+function buildProvisionContext(root, message) {
+    return {
+        message,
+        root,
+        onStatusUpdate: async (status, extra) => {
+            if (message.$reply) {
+                let content = status;
+                if (extra?.qrcode && typeof extra.qrcode === 'string') {
+                    content = [segment.qrcode(extra.qrcode), segment.text(status)];
+                }
+                await message.$reply(content);
+            }
+        },
+    };
+}
+export class EndpointLifecycleService {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    resolveAdapter(adapterKey) {
+        const adapter = this.root.inject(adapterKey);
+        if (!(adapter instanceof Adapter)) {
+            throw new Error(`适配器 ${adapterKey} 未安装或未就绪`);
+        }
+        return adapter;
+    }
+    resolveManager(adapterKey) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = resolveEndpointManager(adapter);
+        if (!manager) {
+            throw new Error(`适配器 ${adapterKey} 不支持运行时 Endpoint 管理（无 EndpointManager 且未声明 endpointConfigSchema）`);
+        }
+        return manager;
+    }
+    listProvisionableAdapters() {
+        return this.root.adapters.filter((name) => {
+            try {
+                const adapter = this.resolveAdapter(String(name));
+                return adapterSupportsProvision(adapter);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    async persistEndpoints(endpoints) {
+        const configService = getConfigService(this.root);
+        const loader = configService.configs.get(configService.primaryFile);
+        loader.patchKey('endpoints', endpoints);
+    }
+    /** 将内存中的 endpoints 写回 zhin.config（修复运行时与磁盘不一致） */
+    async syncToDisk() {
+        const configService = getConfigService(this.root);
+        const loader = configService.configs.get(configService.primaryFile);
+        const endpoints = readAllEndpoints(this.root);
+        await this.persistEndpoints(endpoints);
+        const configPath = formatDisplayPath(loader.resolvedPath);
+        const names = endpoints.map((e) => `${e.context}/${e.id}`).join(', ') || '（无）';
+        return {
+            message: `✅ 已将 ${endpoints.length} 个 endpoint 写入 \`${configPath}\`：${names}`,
+        };
+    }
+    async connectConfig(adapter, config) {
+        const name = config.id;
+        if (adapter.endpoints.has(name)) {
+            throw new Error(`Endpoint ${name} 已在线，请先 /endpoint stop ${String(adapter.name)} ${name}`);
+        }
+        const endpoint = await connectEndpointInstance({
+            plugin: this.root,
+            adapter,
+            config: config,
+        });
+        adapter.endpoints.set(endpoint.$id, endpoint);
+        return endpoint;
+    }
+    async disconnectRuntime(adapter, name) {
+        const endpoint = adapter.endpoints.get(name);
+        if (!endpoint)
+            return false;
+        if (endpoint.$connected) {
+            await disconnectEndpointInstance(this.root, adapter, endpoint);
+        }
+        adapter.endpoints.delete(name);
+        return true;
+    }
+    async add(adapterKey, message, initialReply) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const ctx = buildProvisionContext(this.root, message);
+        const config = await manager.addEndpoint(ctx);
+        if (!config.context)
+            config.context = adapterKey;
+        if (!config.id?.trim()) {
+            throw new Error('Endpoint id 不能为空');
+        }
+        const endpoints = readAllEndpoints(this.root);
+        try {
+            assertUniqueName(endpoints, config.context, config.id);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes('已存在')) {
+                const online = adapter.endpoints.has(config.id);
+                const hint = online
+                    ? '该 Endpoint 已在运行时注册，无需重复扫码；可发 /endpoints 确认。若 zhin.config.yml 未更新，请 /endpoint sync。'
+                    : '可用 /endpoint start 重试连接，或 /endpoint remove 后重新添加。';
+                throw new Error(`${err.message}。${hint}`);
+            }
+            throw err;
+        }
+        endpoints.push(config);
+        await this.persistEndpoints(endpoints);
+        try {
+            await this.connectConfig(adapter, config);
+        }
+        catch (err) {
+            const needsRestart = adapter.getEndpointNeedsRestart?.() ??
+                adapter.constructor.endpointNeedsRestart;
+            const hint = needsRestart
+                ? '配置已写入，请重启进程后连接。'
+                : `配置已写入，可用 /endpoint start ${adapterKey} ${config.id} 重试。`;
+            throw new Error(`${err instanceof Error ? err.message : String(err)}（${hint}）`);
+        }
+        const prefix = initialReply ? `${initialReply}\n` : '';
+        return {
+            message: `${prefix}✅ 已添加并连接 endpoint \`${config.id}\`（${adapterKey}），已写入 zhin.config。`,
+            config,
+        };
+    }
+    async edit(adapterKey, name, message) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const endpoints = readAllEndpoints(this.root);
+        const index = endpoints.findIndex((e) => e.context === adapterKey && e.id === name);
+        if (index < 0) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        if (adapter.endpoints.has(name)) {
+            await this.disconnectRuntime(adapter, name);
+        }
+        const ctx = buildProvisionContext(this.root, message);
+        const updated = await manager.editEndpoint(name, ctx);
+        updated.context = adapterKey;
+        updated.id = name;
+        endpoints[index] = updated;
+        await this.persistEndpoints(endpoints);
+        try {
+            await this.connectConfig(adapter, updated);
+        }
+        catch (err) {
+            throw new Error(`配置已更新，但连接失败：${err instanceof Error ? err.message : String(err)}。` +
+                `可用 /endpoint start ${adapterKey} ${name} 重试。`);
+        }
+        return {
+            message: `✅ 已更新并连接 endpoint \`${name}\`（${adapterKey}）。`,
+            config: updated,
+        };
+    }
+    async remove(adapterKey, name) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        await this.stop(adapterKey, name);
+        const ok = await manager.removeEndpoint(name);
+        if (!ok) {
+            throw new Error(`无法移除 ${adapterKey}/${name}`);
+        }
+        const endpoints = readAllEndpoints(this.root);
+        const next = endpoints.filter((e) => !(e.context === adapterKey && e.id === name));
+        if (next.length === endpoints.length) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        await this.persistEndpoints(next);
+        return { message: `✅ 已从配置移除 endpoint \`${name}\`（${adapterKey}）。` };
+    }
+    async start(adapterKey, name, message) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const endpoints = readAllEndpoints(this.root);
+        const config = endpoints.find((e) => e.context === adapterKey && e.id === name);
+        if (!config) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        if (adapter.endpoints.has(name)) {
+            return { message: `Endpoint ${adapterKey}/${name} 已在线。` };
+        }
+        const ctx = buildProvisionContext(this.root, message);
+        await manager.startEndpoint(name, ctx);
+        await this.connectConfig(adapter, config);
+        return { message: `✅ 已连接 endpoint \`${name}\`（${adapterKey}）。`, config };
+    }
+    async stop(adapterKey, name) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const stopped = await this.disconnectRuntime(adapter, name);
+        await manager.stopEndpoint(name);
+        if (!stopped) {
+            return { message: `Endpoint ${adapterKey}/${name} 当前未在线。` };
+        }
+        return { message: `✅ 已断开 endpoint \`${name}\`（${adapterKey}），配置仍保留。` };
+    }
+    cancelProvision() {
+        for (const adapterName of this.root.adapters) {
+            const adapter = this.root.inject(adapterName);
+            if (!(adapter instanceof Adapter))
+                continue;
+            const manager = resolveEndpointManager(adapter);
+            if (manager?.cancelProvision?.())
+                return true;
+        }
+        return false;
+    }
+}
+export function createEndpointLifecycleService(root) {
+    return new EndpointLifecycleService(root);
+}

package/lib/built/endpoint-lifecycle.d.ts

@@ -0,0 +1,27 @@
+import type { Adapter } from '../adapter.js';
+import type { Endpoint } from '../endpoint.js';
+import type { Plugin } from '../plugin.js';
+export type EndpointLifecycleKind = 'connect' | 'disconnect' | 'error';
+export interface EndpointLifecyclePayload {
+    adapter: string;
+    endpointKey: string;
+    endpoint: Endpoint;
+    kind: EndpointLifecycleKind;
+    error?: string;
+    phase?: string;
+    detail?: Record<string, unknown>;
+}
+/** 可 JSON 序列化的生命周期载荷（不含 endpoint 实例引用） */
+export declare function serializeEndpointLifecyclePayload(payload: Pick<EndpointLifecyclePayload, 'adapter' | 'endpointKey' | 'kind' | 'error' | 'phase' | 'detail'>): {
+    adapter: string;
+    endpointKey: string;
+    kind: EndpointLifecycleKind;
+    error: string | undefined;
+    phase: string | undefined;
+    detail: Record<string, unknown> | undefined;
+};
+export declare function emitEndpointLifecycle(plugin: Plugin, adapter: Adapter, endpoint: Endpoint, kind: EndpointLifecycleKind, detail?: {
+    error?: string;
+    phase?: string;
+    detail?: Record<string, unknown>;
+}): Promise<void>;

package/lib/built/endpoint-lifecycle.js

@@ -0,0 +1,36 @@
+import { Notice } from '../notice.js';
+/** 可 JSON 序列化的生命周期载荷（不含 endpoint 实例引用） */
+export function serializeEndpointLifecyclePayload(payload) {
+    return {
+        adapter: payload.adapter,
+        endpointKey: payload.endpointKey,
+        kind: payload.kind,
+        error: payload.error,
+        phase: payload.phase,
+        detail: payload.detail,
+    };
+}
+export async function emitEndpointLifecycle(plugin, adapter, endpoint, kind, detail) {
+    const payload = {
+        adapter: String(adapter.name),
+        endpointKey: endpoint.$id,
+        endpoint,
+        kind,
+        ...detail,
+    };
+    const eventName = kind === 'connect' ? 'endpoint.connect' : kind === 'disconnect' ? 'endpoint.disconnect' : 'endpoint.error';
+    await plugin.root.dispatch(eventName, payload);
+    const notice = Notice.from({
+        $raw: JSON.stringify(serializeEndpointLifecyclePayload(payload)),
+    }, {
+        $id: `endpoint-lifecycle:${endpoint.$id}:${kind}:${Date.now()}`,
+        $adapter: adapter.name,
+        $endpoint: endpoint.$id,
+        $type: 'notice',
+        $scene_id: endpoint.$id,
+        $scene_type: 'endpoint',
+        $sub_type: kind,
+        $timestamp: Date.now(),
+    });
+    adapter.emit('notice.receive', notice);
+}

package/lib/built/endpoint-manager.d.ts

@@ -0,0 +1,34 @@
+import type { Schema } from '@zhin.js/schema';
+import type { Message } from '../message.js';
+import type { Plugin } from '../plugin.js';
+/** zhin.config.endpoints[] 单条记录 */
+export type EndpointConfigRecord = Record<string, unknown> & {
+    context: string;
+    id: string;
+};
+export type EndpointStatusExtra = Record<string, unknown>;
+export interface ProvisionContext {
+    message: Message;
+    root: Plugin;
+    /** 长连接 / 扫码 / 登录进度回调（由 core 转发到 message.$reply） */
+    onStatusUpdate: (status: string, extra?: EndpointStatusExtra) => void | Promise<void>;
+}
+export interface EndpointManager {
+    /** 是否支持运行时 add（含 schema 通用或自定义） */
+    supportsProvision(): boolean;
+    listEndpoints(): EndpointConfigRecord[];
+    addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    removeEndpoint(name: string): Promise<boolean>;
+    startEndpoint(name: string, ctx: ProvisionContext): Promise<void>;
+    stopEndpoint(name: string): Promise<boolean>;
+    /** 取消进行中的 add/edit 交互（如 QQ 扫码）；无则返回 false */
+    cancelProvision?(): boolean;
+}
+export interface EndpointManagerClass {
+    new (adapter: import('../adapter.js').Adapter): EndpointManager;
+    /** 热连接失败时是否建议重启进程 */
+    readonly needsRestart?: boolean;
+    /** 通用 schema 驱动 add/edit 时使用 */
+    readonly endpointConfigSchema?: Schema;
+}

package/lib/built/endpoint-manager.js

@@ -0,0 +1 @@
+export {};

package/lib/built/generated-qrcode.d.ts

@@ -0,0 +1,24 @@
+export interface GenerateQrCodeOptions {
+    width?: number;
+    margin?: number;
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+}
+export interface PrintQrCodeTerminalOptions {
+    small?: boolean;
+}
+/** 二维码实例：一次 generate，多种输出 */
+export declare class GeneratedQrCode {
+    #private;
+    private constructor();
+    static generate(text: string, options?: GenerateQrCodeOptions): Promise<GeneratedQrCode>;
+    /** data URL，含 `data:image/png;base64,...` 前缀 */
+    toDataUrl(): string;
+    /**
+     * encoding === 'base64' → 纯 base64 载荷（无 data: 前缀）
+     */
+    toString(encoding: 'base64'): string;
+    /** 输出 ASCII 二维码到 process.stdout */
+    printToTerminal(options?: PrintQrCodeTerminalOptions): Promise<void>;
+}
+/** 便捷别名 */
+export declare const generateQrCode: typeof GeneratedQrCode.generate;

package/lib/built/generated-qrcode.js

@@ -0,0 +1,45 @@
+import QRCode from 'qrcode';
+/** 二维码实例：一次 generate，多种输出 */
+export class GeneratedQrCode {
+    #text;
+    #dataUrl;
+    constructor(text, dataUrl) {
+        this.#text = text;
+        this.#dataUrl = dataUrl;
+    }
+    static async generate(text, options = {}) {
+        const dataUrl = await QRCode.toDataURL(text, {
+            width: options.width ?? 280,
+            margin: options.margin ?? 2,
+            errorCorrectionLevel: options.errorCorrectionLevel ?? 'M',
+        });
+        return new GeneratedQrCode(text, dataUrl);
+    }
+    /** data URL，含 `data:image/png;base64,...` 前缀 */
+    toDataUrl() {
+        return this.#dataUrl;
+    }
+    /**
+     * encoding === 'base64' → 纯 base64 载荷（无 data: 前缀）
+     */
+    toString(encoding) {
+        if (encoding !== 'base64') {
+            throw new Error(`GeneratedQrCode.toString: unsupported encoding "${encoding}"`);
+        }
+        const prefix = 'data:image/png;base64,';
+        if (!this.#dataUrl.startsWith(prefix)) {
+            throw new Error('GeneratedQrCode.toString: unexpected data URL format');
+        }
+        return this.#dataUrl.slice(prefix.length);
+    }
+    /** 输出 ASCII 二维码到 process.stdout */
+    async printToTerminal(options = {}) {
+        const terminalText = await QRCode.toString(this.#text, {
+            type: 'terminal',
+            small: options.small ?? true,
+        });
+        process.stdout.write(`${terminalText}\n`);
+    }
+}
+/** 便捷别名 */
+export const generateQrCode = GeneratedQrCode.generate.bind(GeneratedQrCode);

package/lib/built/generic-segment-mapper.d.ts

@@ -0,0 +1,4 @@
+import type { MessageElement } from '../types.js';
+import type { Segment } from './segment-contract/types.js';
+/** wire 段数组 → canonical Segment[]（包括所有媒体的 `data.media` 归一）。 */
+export declare function toCanonicalSegments(content: readonly MessageElement[] | readonly unknown[]): Segment[];