@zhin.js/core 1.1.33 → 1.1.35

package/lib/adapter.js

@@ -1,8 +1,16 @@
+import { assertOutbound, DEFAULT_ENDPOINT_CAPABILITIES, hasInbound, } from "./endpoint-capabilities.js";
+import { endpointControlOf } from "@zhin.js/adapter";
+import { connectEndpointInstance, disconnectEndpointInstance } from "./built/connect-endpoint-instance.js";
 import { EventEmitter } from "node:events";
 import { getOutboundReplyStore } from "./built/dispatcher.js";
+import { DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY, resolveRichSegments, } from "./built/rich-segments/index.js";
+import { DEFAULT_INTERACTIVE_POLICY, collectKeyboardFallbackMaps, keyboardFallbackStore, resolveKeyboardSegments, } from "./built/interactive-segments/index.js";
+import { DEFAULT_AI_OUTBOUND_CAPABILITIES, } from "./built/ai-outbound/index.js";
+import { createRichSegmentRenderContext } from "./built/rich-segments/capabilities.js";
+import { collectOutboundMediaKinds } from "./built/outbound-media-utils.js";
 import { segment } from "./utils.js";
-import { runInboundMessage } from "./built/inbound-runner.js";
-import { formatCompact, truncatePreview } from '@zhin.js/logger';
+import { InboundMessagePipeline } from "./built/inbound-pipeline.js";
+import { formatCompact, truncatePreview, formatContentChainLog, CONTENT_CHAIN_STAGE } from '@zhin.js/logger';
 /**
  * Adapter类：适配器抽象，管理多平台Bot实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
@@ -13,8 +21,21 @@ export class Adapter extends EventEmitter {
     plugin;
     name;
     config;
-    /** 当前适配器下所有Bot实例，key为bot名称 */
-    bots = new Map();
+    endpoints = new Map();
+    recallMessageHandler;
+    /** Adapter 支持的能力上限（子类覆盖） */
+    static capabilities = DEFAULT_ENDPOINT_CAPABILITIES;
+    /** 出站富媒体段渲染策略（子类 override static） */
+    static outboundRichSegmentPolicy = DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY;
+    /** 交互段出站策略：native 保留按钮段，text 降级为编号文本 */
+    static interactivePolicy = DEFAULT_INTERACTIVE_POLICY;
+    /** AI 结构化出站能力声明（mentions / richSegments / interactive） */
+    static aiOutboundCapabilities = DEFAULT_AI_OUTBOUND_CAPABILITIES;
+    /** 平台特有 extensions schema + 解析（对齐各 SDK 文档子集） */
+    static aiOutboundExtensions;
+    getInteractivePolicy() {
+        return this.constructor.interactivePolicy;
+    }
     /** 入站消息并发计数 */
     #pendingMessages = 0;
     /** 并发上限，0 表示不限制（默认） */
@@ -34,61 +55,54 @@ export class Adapter extends EventEmitter {
         return this.#pendingMessages;
     }
     /**
-     * 构造函数
+     * 创建一个适配器运行实例。
+     * @param plugin 拥有该适配器的插件实例
      * @param name 适配器名称（如 'process'、'qq' 等）
-     * @param botFactory Bot工厂函数或构造器
+     * @param config Endpoint 配置列表
      */
     constructor(plugin, name, config) {
         super();
         this.plugin = plugin;
         this.name = name;
         this.config = config;
-        this.on('call.recallMessage', async (bot_id, id) => {
-            const bot = this.bots.get(bot_id);
-            if (!bot)
-                throw new Error(`Bot ${bot_id} not found`);
-            this.logger.debug(formatCompact({ recall: id, bot: bot_id }));
-            await bot.$recallMessage(id);
+        this.recallMessageHandler = (endpoint_id, id) => this.recallEndpointMessage(endpoint_id, id);
+        this.on('call.recallMessage', this.recallMessageHandler);
+        this.inboundPipeline = new InboundMessagePipeline({
+            getPlugin: () => this.plugin,
+            logger: this.logger,
+            getMaxConcurrentMessages: () => this.maxConcurrentMessages,
+            getPendingMessages: () => this.#pendingMessages,
+            decrementPending: () => {
+                // stop() may zero the counter while in-flight receives still finish;
+                // never let the budget go negative.
+                this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+            },
         });
     }
+    /** 入站消息管线（替代 emit override 的隐式管线） */
+    inboundPipeline;
     /**
-     * 重写 emit：拦截 message.receive 事件，按架构规定的入站流程处理
-     * 入站消息链：adapter.emit → dispatcher.dispatch → plugin.dispatch('message.receive') → adapter observers
-     *
-     * 以属性 + `EventEmitter.prototype.emit` 调用满足 Node @types 25 对泛型 `emit` 的可赋值检查。
+     * 重写 emit：拦截 message.receive/notice.receive/request.receive 事件，
+     * 将入站处理委托给 InboundMessagePipeline。
      */
     emit = ((event, ...args) => {
+        if (event === 'notice.receive' || event === 'request.receive') {
+            return this.inboundPipeline.bridgeNoticeOrRequest(event, args, () => EventEmitter.prototype.emit.call(this, event, ...args));
+        }
         if (event !== 'message.receive') {
             return EventEmitter.prototype.emit.call(this, event, ...args);
         }
         const message = args[0];
-        this.logger.info(formatCompact({
-            recv: `${message.$channel.type}(${message.$channel.id})`,
-            bot: message.$bot,
-            preview: truncatePreview(segment.raw(message.$content)),
-            ...(message.$quote_id ? { quote_id: message.$quote_id } : {}),
-        }));
-        // 背压控制：limit > 0 时启用，超出并发上限丢弃消息并告警
-        const limit = this.maxConcurrentMessages;
-        if (limit > 0 && this.#pendingMessages >= limit) {
-            this.logger.warn(formatCompact({ drop: 'concurrency', limit }));
+        // 背压控制：同步返回 false 表示丢弃
+        if (this.inboundPipeline.shouldDropDueToBackpressure()) {
+            this.logger.warn(formatCompact({ op: 'backpressure_drop', limit: this.maxConcurrentMessages }));
             return false;
         }
+        // 同步计数，保证背压判断的准确性
         this.#pendingMessages++;
-        // 异步执行入站消息处理链
-        const processing = async () => {
-            await runInboundMessage({
-                plugin: this.plugin,
-                message,
-                emitAdapterObservers: () => {
-                    EventEmitter.prototype.emit.call(this, event, ...args);
-                },
-            });
-        };
-        processing().catch((e) => {
-            this.logger.warn(`message.receive handling error: ${e instanceof Error ? e.message : String(e)}`);
-        }).finally(() => {
-            this.#pendingMessages--;
+        // 异步入站管线（middleware → dispatcher → 生命周期 → 观察者）
+        this.inboundPipeline.receive(message, () => {
+            EventEmitter.prototype.emit.call(this, event, ...args);
         });
         return true;
     });
@@ -100,6 +114,28 @@ export class Adapter extends EventEmitter {
     binding(plugin) {
         this.plugin = plugin;
     }
+    /**
+     * 同步等待入站管线结束（middleware → dispatcher → 生命周期 → 观察者）。
+     * 用于 QQ 等需在被动回复完成后再 ack 交互的平台事件。
+     */
+    async receiveMessageAwait(message) {
+        if (this.inboundPipeline.shouldDropDueToBackpressure()) {
+            this.logger.warn(formatCompact({ drop: 'concurrency', limit: this.maxConcurrentMessages }));
+            return false;
+        }
+        this.#pendingMessages++;
+        try {
+            await this.inboundPipeline.receive(message, () => {
+                EventEmitter.prototype.emit.call(this, 'message.receive', message);
+            });
+            return true;
+        }
+        finally {
+            // Inbound pipeline errors must not leak the concurrency budget; the
+            // non-await path uses InboundMessagePipeline.decrementPending in finally.
+            this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+        }
+    }
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
      */
@@ -112,7 +148,52 @@ export class Adapter extends EventEmitter {
             maxAttachmentBytes: 26_214_400,
         };
     }
+    getOutboundRichSegmentPolicy() {
+        return this.constructor.outboundRichSegmentPolicy;
+    }
+    /**
+     * 出站两阶段：
+     * 1. resolveRichSegments — 语义段 → 标准 IM 段（image/audio/text）
+     * 2. Endpoint materializeOutboundMedia — base64/本地路径 → 平台 URL（各 adapter 可选）
+     * @see docs/essentials/rich-segment-adapters.md
+     */
     async renderSendMessage(options) {
+        if (options.content != null) {
+            options = {
+                ...options,
+                content: await resolveRichSegments(options.content, this.getOutboundRichSegmentPolicy(), createRichSegmentRenderContext({
+                    getConfig: () => {
+                        const cfg = this.plugin.root.inject('config')?.getPrimary();
+                        return cfg;
+                    },
+                    warn: (msg) => this.logger.warn(msg),
+                    logContentChain: (fields) => {
+                        this.logger.debug(formatContentChainLog({ ...fields, adapter: this.name }));
+                    },
+                })),
+            };
+            // 'text' 策略端点：keyboard 即将降级为编号文本，先把有效 fallback
+            // 映射写入中央存储（频道键与入站回跳解析一致），供数字回跳路由。
+            if (this.getInteractivePolicy() === 'text') {
+                const channelKey = `${this.name}-${options.endpoint}-${options.type}:${options.id}`;
+                for (const map of collectKeyboardFallbackMaps(options.content)) {
+                    keyboardFallbackStore.remember(channelKey, map);
+                }
+            }
+            options = {
+                ...options,
+                content: resolveKeyboardSegments(options.content, this.getInteractivePolicy()),
+            };
+            const mediaKinds = collectOutboundMediaKinds(options.content);
+            if (mediaKinds.length > 0) {
+                this.logger.debug(formatContentChainLog({
+                    stage: CONTENT_CHAIN_STAGE.OUTBOUND,
+                    adapter: this.name,
+                    endpoint: options.endpoint,
+                    media: mediaKinds.join(','),
+                }));
+            }
+        }
         const fns = this.plugin.root.listeners('before.sendMessage');
         for (const fn of fns) {
             const result = await fn(options);
@@ -123,15 +204,16 @@ export class Adapter extends EventEmitter {
     }
     async sendMessage(options) {
         options = await this.renderSendMessage(options);
-        const bot = this.bots.get(options.bot);
-        if (!bot)
-            throw new Error(`Bot ${options.bot} not found`);
-        this.logger.info(formatCompact({
+        const endpoint = this.endpoints.get(options.endpoint);
+        if (!endpoint)
+            throw new Error(`Endpoint ${options.endpoint} not found`);
+        assertOutbound(endpoint);
+        this.logger.debug(formatCompact({
             send: `${options.type}(${options.id})`,
-            bot: options.bot,
+            endpoint: options.endpoint,
             preview: truncatePreview(segment.raw(options.content)),
         }));
-        const messageId = await bot.$sendMessage(options);
+        const messageId = await endpoint.$sendMessage(options);
         const replyStore = getOutboundReplyStore();
         this.plugin.root.dispatch('message.send', {
             adapter: this.name,
@@ -142,7 +224,81 @@ export class Adapter extends EventEmitter {
         });
         return messageId;
     }
+    /**
+     * `call.recallMessage` 事件链（prompt.ts 超时撤回等）的统一出口：
+     * 经 canonical `EndpointControl` 端口撤回。
+     */
+    async recallEndpointMessage(endpointKey, messageId) {
+        const endpoint = this.endpoints.get(endpointKey);
+        if (!endpoint)
+            throw new Error(`Endpoint ${endpointKey} not found`);
+        assertOutbound(endpoint);
+        const control = endpointControlOf(endpoint);
+        if (!control?.recall) {
+            throw new Error(`Endpoint ${endpointKey} does not support recall`);
+        }
+        this.logger.debug(formatCompact({ op: 'recall_message', msgId: messageId, endpoint: endpointKey }));
+        await control.recall({
+            conversation: {
+                endpoint: { id: endpointKey, adapter: String(this.name) },
+                kind: 'private',
+                id: endpointKey,
+            },
+            id: messageId,
+        });
+    }
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 的 control 端口实现了 edit，调用平台编辑 API
+     * - 否则 fallback 到发送新消息
+     * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
+     */
+    async editMessage(options) {
+        const endpoint = this.endpoints.get(options.endpoint);
+        if (!endpoint)
+            throw new Error(`Endpoint ${options.endpoint} not found`);
+        assertOutbound(endpoint);
+        const control = endpointControlOf(endpoint);
+        if (control?.edit) {
+            const rendered = await this.renderSendMessage({
+                context: options.context,
+                endpoint: options.endpoint,
+                id: options.id,
+                type: options.type,
+                content: options.content,
+            });
+            await control.edit({
+                conversation: {
+                    endpoint: { id: options.endpoint, adapter: String(this.name) },
+                    kind: options.type === 'group' ? 'group' : 'private',
+                    id: options.id,
+                },
+                id: options.messageId,
+            }, rendered.content);
+            this.logger.debug(formatCompact({
+                edit: `${options.type}(${options.id})`,
+                endpoint: options.endpoint,
+                messageId: options.messageId,
+            }));
+            return options.messageId;
+        }
+        this.logger.debug(formatCompact({
+            editFallback: 'sendMessage',
+            endpoint: options.endpoint,
+            reason: 'control.edit not implemented',
+        }));
+        return this.sendMessage({
+            context: options.context,
+            endpoint: options.endpoint,
+            id: options.id,
+            type: options.type,
+            content: options.content,
+        });
+    }
     async start() {
+        if (this.endpoints.size > 0) {
+            await this.stop();
+        }
         const rootAdapters = this.plugin.root.adapters;
         if (!rootAdapters.some((n) => String(n) === String(this.name))) {
             rootAdapters.push(this.name);
@@ -150,31 +306,38 @@ export class Adapter extends EventEmitter {
         if (!this.config?.length)
             return;
         for (const config of this.config) {
-            const bot = this.createBot(config);
-            await bot.$connect();
-            this.logger.debug(formatCompact({ connect: bot.$id, adapter: this.name }));
-            this.bots.set(bot.$id, bot);
+            const endpoint = await connectEndpointInstance({
+                plugin: this.plugin,
+                adapter: this,
+                config: config,
+            });
+            this.logger.debug(formatCompact({ connect: endpoint.$id, adapter: this.name }));
+            this.endpoints.set(endpoint.$id, endpoint);
         }
         this.logger.debug(formatCompact({ adapter: this.name }));
     }
     /**
-     * 停止适配器，断开并移除所有Bot实例
-     * @param plugin 所属插件实例
+     * 停止适配器，断开并移除所有 Endpoint 实例
      */
     async stop() {
         const errors = [];
-        for (const [id, bot] of this.bots) {
+        for (const [id, endpoint] of this.endpoints) {
             try {
-                await bot.$disconnect();
+                if (hasInbound(endpoint)) {
+                    await disconnectEndpointInstance(this.plugin, this, endpoint);
+                }
                 this.logger.debug(formatCompact({ disconnect: id, adapter: this.name }));
             }
             catch (error) {
                 errors.push(error instanceof Error ? error : new Error(String(error)));
-                this.logger.error(`bot ${id} of adapter ${this.name} disconnect failed:`, error);
+                this.logger.error(`endpoint ${id} of adapter ${this.name} disconnect failed:`, error);
             }
         }
         // 无论是否有错误，始终完成清理
-        this.bots.clear();
+        this.endpoints.clear();
+        // Drop in-flight concurrency counter so a subsequent start() does not
+        // inherit a stale backpressure budget from the previous generation.
+        this.#pendingMessages = 0;
         // 从 adapters 数组中移除（可能因重复 start 出现多条同名，需全部删掉）
         const rootAdapters = this.plugin.root.adapters;
         for (let i = rootAdapters.length - 1; i >= 0; i--) {
@@ -183,9 +346,11 @@ export class Adapter extends EventEmitter {
         }
         // 移除所有事件监听器
         this.removeAllListeners();
+        this.recallMessageHandler = (endpoint_id, id) => this.recallEndpointMessage(endpoint_id, id);
+        this.on('call.recallMessage', this.recallMessageHandler);
         this.logger.debug(formatCompact({ stop: this.name }));
         if (errors.length) {
-            throw new AggregateError(errors, `adapter ${this.name}: ${errors.length} bot(s) failed to disconnect`);
+            throw new AggregateError(errors, `adapter ${this.name}: ${errors.length} endpoint(s) failed to disconnect`);
         }
     }
 }
@@ -210,4 +375,3 @@ export class Adapter extends EventEmitter {
     }
     Adapter.register = register;
 })(Adapter || (Adapter = {}));
-//# sourceMappingURL=adapter.js.map

package/lib/built/adapter-process.d.ts

@@ -1,5 +1,10 @@
-import { Adapter, Plugin, Bot, SendOptions, Message } from "@zhin.js/core";
-export declare class ProcessBot implements Bot<{
+import { Adapter } from "../adapter.js";
+import { Plugin } from "../plugin.js";
+import { Endpoint } from "../endpoint.js";
+import { Message } from "../message.js";
+import type { SendOptions } from "../types.js";
+import type { OutboundRichSegmentPolicy } from "./rich-segments/types.js";
+export declare class ProcessEndpoint implements Endpoint<{
     owner?: string;
 }, {
     content: string;
@@ -26,18 +31,28 @@ export declare class ProcessBot implements Bot<{
         content: string;
         ts: number;
     }>;
+    get control(): {
+        recall: (message: {
+            id: string;
+        }) => Promise<void>;
+    };
     $recallMessage(id: string): Promise<void>;
     $sendMessage(options: SendOptions): Promise<string>;
     $connect(): Promise<void>;
     $disconnect(): Promise<void>;
 }
-export declare class ProcessAdapter extends Adapter<ProcessBot> {
+export declare class ProcessAdapter extends Adapter<ProcessEndpoint> {
+    static readonly capabilities: readonly ["inbound", "outbound"];
+    static outboundRichSegmentPolicy: OutboundRichSegmentPolicy;
     constructor(plugin: Plugin);
-    createBot(config: Adapter.BotConfig<ProcessBot>): ProcessBot;
+    /**
+     * process 出站由 $sendMessage 写入 stdout；父类 INFO preview 会与终端输出重复，故仅 debug 元数据。
+     */
+    sendMessage(options: SendOptions): Promise<string>;
+    createEndpoint(config: Adapter.EndpointConfig<ProcessEndpoint>): ProcessEndpoint;
 }
 declare module '../adapter.js' {
     interface Adapters {
         process: ProcessAdapter;
     }
 }
-//# sourceMappingURL=adapter-process.d.ts.map

package/lib/built/adapter-process.js

@@ -1,6 +1,12 @@
-import { Adapter, Message } from "@zhin.js/core";
+import { formatCompact } from "@zhin.js/logger";
+import { Adapter } from "../adapter.js";
+import { Message } from "../message.js";
+import { segment } from "../utils.js";
+import { assertOutbound } from "../endpoint-capabilities.js";
+import { getOutboundReplyStore } from "./dispatcher.js";
 import { bindStdin, runtimePid, runtimeUser } from "./runtime-io.js";
-export class ProcessBot {
+import { interpretOriginQrcodeForProcess } from "./rich-segments/qrcode-segment.js";
+export class ProcessEndpoint {
     adapter;
     $config;
     $id = runtimePid();
@@ -28,7 +34,7 @@ export class ProcessBot {
         const base = {
             $id: `${event.ts}`,
             $adapter: 'process',
-            $bot: runtimePid(),
+            $endpoint: runtimePid(),
             $sender: {
                 id: runtimeUser(),
                 name: runtimeUser(),
@@ -47,7 +53,7 @@ export class ProcessBot {
             $reply: async (content) => {
                 return await this.adapter.sendMessage({
                     context: 'process',
-                    bot: base.$bot,
+                    endpoint: base.$endpoint,
                     content,
                     id: base.$sender.id,
                     type: base.$channel.type,
@@ -56,9 +62,21 @@ export class ProcessBot {
         };
         return Message.from(event, base);
     }
+    get control() {
+        return {
+            recall: async (message) => this.$recallMessage(message.id),
+        };
+    }
     async $recallMessage(id) {
     }
     async $sendMessage(options) {
+        const content = await interpretOriginQrcodeForProcess(options.content ?? '');
+        if (content != null) {
+            const preview = segment.raw(content);
+            if (preview) {
+                process.stdout.write(`${preview}\n`);
+            }
+        }
         return `${Date.now()}`;
     }
     async $connect() {
@@ -71,11 +89,40 @@ export class ProcessBot {
     }
 }
 export class ProcessAdapter extends Adapter {
+    static capabilities = ['inbound', 'outbound'];
+    static outboundRichSegmentPolicy = {
+        qrcode: 'origin',
+        html: 'text',
+        markdown: 'text',
+    };
     constructor(plugin) {
         super(plugin, 'process', [{ owner: runtimePid() }]);
     }
-    createBot(config) {
-        return new ProcessBot(this, config);
+    /**
+     * process 出站由 $sendMessage 写入 stdout；父类 INFO preview 会与终端输出重复，故仅 debug 元数据。
+     */
+    async sendMessage(options) {
+        options = await this.renderSendMessage(options);
+        const endpoint = this.endpoints.get(options.endpoint);
+        if (!endpoint)
+            throw new Error(`Endpoint ${options.endpoint} not found`);
+        assertOutbound(endpoint);
+        this.logger.debug(formatCompact({
+            send: `${options.type}(${options.id})`,
+            endpoint: options.endpoint,
+        }));
+        const messageId = await endpoint.$sendMessage(options);
+        const replyStore = getOutboundReplyStore();
+        this.plugin.root.dispatch('message.send', {
+            adapter: this.name,
+            options,
+            messageId,
+            replySource: replyStore?.source,
+            replyMessage: replyStore?.message,
+        });
+        return messageId;
+    }
+    createEndpoint(config) {
+        return new ProcessEndpoint(this, config);
     }
 }
-//# sourceMappingURL=adapter-process.js.map

package/lib/built/agent-preset.d.ts

@@ -48,7 +48,7 @@ declare module '../plugin.js' {
 export declare class AgentPresetFeature extends Feature<AgentPreset> {
     #private;
     readonly name: "agentPreset";
-    readonly icon = "Bot";
+    readonly icon = "Endpoint";
     readonly desc = "Agent \u9884\u8BBE";
     readonly byName: Map<string, AgentPreset>;
     add(preset: AgentPreset, pluginName: string): () => void;
@@ -62,4 +62,3 @@ export declare class AgentPresetFeature extends Feature<AgentPreset> {
     }): AgentPreset[];
     toJSON(pluginName?: string): FeatureJSON;
 }
-//# sourceMappingURL=agent-preset.d.ts.map

package/lib/built/agent-preset.js

@@ -12,7 +12,7 @@
 import { Feature } from '@zhin.js/kernel';
 export class AgentPresetFeature extends Feature {
     name = 'agentPreset';
-    icon = 'Bot';
+    icon = 'Endpoint';
     desc = 'Agent 预设';
     byName = new Map();
     add(preset, pluginName) {
@@ -77,4 +77,3 @@ export class AgentPresetFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=agent-preset.js.map

package/lib/built/ai-access.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AI Access Gate — 控制 LLM 回复路径是否对当前会话开放（平台 AIGC 合规等）
+ */
+import type { Message } from '../message.js';
+export type AIAccessMode = 'open' | 'closed' | 'whitelist';
+/** Endpoint 或全局 ai.access 配置块 */
+export interface AIAccessScopeConfig {
+    mode?: AIAccessMode;
+    /** 允许触发 AI 的 sender.id */
+    users?: string[];
+    /** 允许触发 AI 的 group/channel id */
+    groups?: string[];
+    /** 私聊拒绝时的回复文案 */
+    denyMessage?: string;
+}
+/** 全局 ai.access 配置（与 AIAccessScopeConfig 同形） */
+export type AIAccessConfig = AIAccessScopeConfig;
+export interface ResolvedAIAccessConfig {
+    mode: AIAccessMode;
+    users: string[];
+    groups: string[];
+    denyMessage: string;
+}
+export interface AIAccessResult {
+    allowed: boolean;
+    reason: string;
+    /** 私聊拒绝时返回；群/频道拒绝为 undefined（静默） */
+    replyMessage?: string;
+}
+export declare const DEFAULT_AI_ACCESS_DENY_MESSAGE = "\u5F53\u524D\u4F1A\u8BDD\u672A\u5F00\u653E AI \u529F\u80FD\u3002";
+export declare function resolveAIAccessConfig(global: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): ResolvedAIAccessConfig;
+/**
+ * 判定当前消息是否允许进入 AI Handler（LLM 回复路径）。
+ * 不影响命令、游戏等其它 Dispatcher 分支。
+ */
+export declare function checkAIAccess(message: Message<any>, globalConfig: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): AIAccessResult;

package/lib/built/ai-access.js

@@ -0,0 +1,46 @@
+export const DEFAULT_AI_ACCESS_DENY_MESSAGE = '当前会话未开放 AI 功能。';
+const DEFAULT_MODE = 'open';
+export function resolveAIAccessConfig(global, endpointScope) {
+    const base = global ?? {};
+    const endpoint = endpointScope ?? {};
+    return {
+        mode: endpoint.mode ?? base.mode ?? DEFAULT_MODE,
+        users: endpoint.users ?? base.users ?? [],
+        groups: endpoint.groups ?? base.groups ?? [],
+        denyMessage: endpoint.denyMessage ?? base.denyMessage ?? DEFAULT_AI_ACCESS_DENY_MESSAGE,
+    };
+}
+function isWhitelisted(message, config) {
+    const userId = String(message.$sender?.id ?? '');
+    if (userId && config.users.includes(userId))
+        return true;
+    const scope = message.$channel?.type;
+    if (scope === 'group' || scope === 'channel') {
+        const channelId = String(message.$channel?.id ?? '');
+        if (channelId && config.groups.includes(channelId))
+            return true;
+    }
+    return false;
+}
+function denyResult(message, config, reason) {
+    const scope = message.$channel?.type;
+    const replyMessage = scope === 'private' ? config.denyMessage : undefined;
+    return { allowed: false, reason, replyMessage };
+}
+/**
+ * 判定当前消息是否允许进入 AI Handler（LLM 回复路径）。
+ * 不影响命令、游戏等其它 Dispatcher 分支。
+ */
+export function checkAIAccess(message, globalConfig, endpointScope) {
+    const config = resolveAIAccessConfig(globalConfig, endpointScope);
+    if (config.mode === 'open') {
+        return { allowed: true, reason: 'mode: open' };
+    }
+    if (config.mode === 'closed') {
+        return denyResult(message, config, 'mode: closed');
+    }
+    if (isWhitelisted(message, config)) {
+        return { allowed: true, reason: 'whitelist: matched' };
+    }
+    return denyResult(message, config, 'whitelist: not matched');
+}

package/lib/built/ai-outbound/adapter-access.d.ts

@@ -0,0 +1,3 @@
+import { type AiOutboundCapabilities, type AiOutboundExtensionDefinition } from './types.js';
+export declare function getAdapterAiOutboundCapabilities(adapterInstance: object): AiOutboundCapabilities;
+export declare function getAdapterAiOutboundExtensions(adapterInstance: object): readonly AiOutboundExtensionDefinition[];

package/lib/built/ai-outbound/adapter-access.js

@@ -0,0 +1,9 @@
+import { DEFAULT_AI_OUTBOUND_CAPABILITIES, } from './types.js';
+export function getAdapterAiOutboundCapabilities(adapterInstance) {
+    const ctor = adapterInstance.constructor;
+    return ctor.aiOutboundCapabilities ?? DEFAULT_AI_OUTBOUND_CAPABILITIES;
+}
+export function getAdapterAiOutboundExtensions(adapterInstance) {
+    const ctor = adapterInstance.constructor;
+    return ctor.aiOutboundExtensions ?? [];
+}

package/lib/built/ai-outbound/extensions/onebot-keyboard.d.ts

@@ -0,0 +1,2 @@
+import type { AiOutboundExtensionDefinition } from '../types.js';
+export declare const ONEBOT_KEYBOARD_AI_OUTBOUND_EXTENSION: AiOutboundExtensionDefinition;