@zhin.js/core 1.3.1 → 1.3.3

package/README.md

@@ -13,7 +13,7 @@ Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、Message
 ```typescript
 import { usePlugin, MessageCommand } from '@zhin.js/core'
 
-const { addCommand, addTool, addCron, onMounted, onDispose } = usePlugin()
+const { addCommand, addTool, addSchedule, onMounted, onDispose } = usePlugin()
 
 onMounted(() => console.log('插件已挂载'))
 onDispose(() => console.log('插件已卸载'))
@@ -55,7 +55,7 @@ Feature (抽象基类)
 ├── CommandFeature    — 消息命令       addCommand()
 ├── ToolFeature       — AI 可调用工具   addTool()
 ├── SkillFeature      — 技能记录       Agent 从 SKILL.md 注入
-├── CronFeature       — 定时任务       addCron()
+├── ScheduleFeature   — 调度任务       addSchedule()
 ├── DatabaseFeature   — 数据模型       defineModel()
 ├── ComponentFeature  — 消息组件       addComponent()
 ├── ConfigFeature     — 插件配置       addConfig()
@@ -90,11 +90,56 @@ return segment.html({
   backgroundColor: '#d8dce3',
   fileName: 'card.png',
 })
+
+// Markdown 段（QQ 等平台 policy 为 origin 时透传）
+return segment.markdown('# Title\n\nBody')
+```
+
+出站富媒体段（`qrcode` / `html` / `markdown`）在 **`Adapter.renderSendMessage` 首步** 按各 Adapter 的 **`outboundRichSegmentPolicy`** 统一渲染为 `image` / `text` / `origin`：
+
+| 渲染模式 | 含义 |
+|---------|------|
+| `image` | 转为 `image` 段（qrcode 生成 PNG；html/markdown 经 `@zhin.js/html-renderer` 动态转图，未安装则降级 text） |
+| `text` | 剥离为纯文本段 |
+| `origin` | 原样透传，由 Endpoint 解释（如 QQ markdown、process 终端二维码） |
+
+默认策略：`qrcode: image`，`html: text`，`markdown: text`。QQ / KOOK 等适配器 override static policy。
+
+- 安装 **`@zhin.js/html-renderer`** 且 policy 为 `html: 'image'` 时，core 在首步动态 import 并转 PNG。
+- policy 为 `html: 'text'` 时等价于 **`coerceHtmlSegmentsToText`** / **`htmlToFallbackText`**。
+- 日志预览：`[html-card]`、`[qrcode]`、`[markdown]` + 摘要（前 80 字）。
+
+#### 扩展新 Rich Segment（长期方案）
+
+内置 kind 通过 **`richSegmentRegistry`** 注册；optional 能力通过 **`registerRichSegmentCapabilityLoader`** 注入（与 `@zhin.js/html-renderer` 同模式）。
+
+```typescript
+import {
+  RichSegment,
+  registerRichSegmentKind,
+  registerRichSegmentCapabilityLoader,
+  RICH_SEGMENT_MODE,
+  segment,
+} from '@zhin.js/core';
+
+// 1. 内置 capability：speech（@zhin.js/speech）已注册，tts kind 已内置
+// 可选：注册 ffmpeg 等
+registerRichSegmentCapabilityLoader('media-pipeline', async (opts) => {
+  const { createMediaPipeline } = await import('@zhin.js/media-pipeline');
+  return createMediaPipeline(opts.getConfig?.());
+});
+
+// 2. 使用内置 segment.tts（Adapter policy 决定 audio/text/origin）
+// segment.tts({ text: '你好' })
+class MyAdapter extends Adapter {
+  static override outboundRichSegmentPolicy = {
+    tts: 'audio',
+    qrcode: 'image', // 其余 kind 用 registry 默认值
+  };
+}
 ```
 
-- 安装 **`@zhin.js/plugin-html-renderer`** 时，`before.sendMessage` 自动将 `html` 转为 PNG。
-- 未安装或转图失败时，`Adapter.renderSendMessage` 链尾调用 **`coerceHtmlSegmentsToText`**，用 **`htmlToFallbackText`** 剥离纯文本。
-- 日志预览为 `[html-card]` + 自动剥离摘要（前 80 字），不 dump 完整 HTML。
+**分工**：Rich Segment 负责「语义段 → 标准 IM 段」；Endpoint `materializeOutboundMedia` 负责「已有 audio/video/file → 平台上传」。
 
 ### Adapter（适配器）
 
@@ -105,9 +150,9 @@ return segment.html({
 Adapter.register('my-platform', MyAdapter)
 ```
 
-每个适配器可以通过 `addTool()` 注册平台特有工具，标准群管操作通过覆写 `IGroupManagement` 方法自动注册。
+每个适配器可以通过 `addTool()` 注册平台特有工具，标准群管操作通过覆写 `ISceneManagement` 方法自动注册。
 
-**群管理能力自动检测：** 适配器基类声明了 `IGroupManagement` 接口中的可选方法（`kickMember`、`muteMember`、`banMember` 等），子类只需覆写自己平台支持的方法，`start()` 会自动检测哪些方法已实现，生成对应的 Tool 并注册为"群聊管理"Skill。目前所有 9 个 IM 适配器（ICQQ、OneBot11、QQ 官方、Telegram、Discord、KOOK、Slack、钉钉、飞书）均已采用此模式：
+**群管理能力自动检测：** 适配器基类声明了 `ISceneManagement` 接口中的可选方法（`kickMember`、`muteMember`、`banMember` 等），子类只需覆写自己平台支持的方法，`start()` 会自动检测哪些方法已实现，生成对应的 Tool 并注册为"群聊管理"Skill。目前所有 9 个 IM 适配器（ICQQ、OneBot11、QQ 官方、Telegram、Discord、KOOK、Slack、钉钉、飞书）均已采用此模式：
 
 ```typescript
 class IcqqAdapter extends Adapter<IcqqEndpoint> {
@@ -152,7 +197,7 @@ Core **不包含** ZhinAgent 实现。IM 侧的 AI 对话、工具收集、执
 |------|----------|
 | Provider | `OpenAIProvider`、`OllamaProvider`、`AnthropicProvider` 等 |
 | Agent 原语 | `Agent`、`createAgent`、`ModelRegistry` |
-| 会话 / 上下文 | `SessionManager`（遗留）、`ContextRepository`、`ImTranscriptStore`、`ContextManager`、`ConversationMemory` |
+| 会话 / 上下文 | `ContextRepository`、`ImTranscriptStore`、`ContextManager`、`ConversationMemory` |
 | 压缩 / 限流 / 输出 | `compactSession`、`RateLimiter`、`parseOutput`、`CostTracker` |
 
 完整 Agent 能力与配置见 [`@zhin.js/agent`](../agent/README.md) 与 [AI 模块](https://zhin.js.org/advanced/ai)。
@@ -167,7 +212,7 @@ export { Plugin, usePlugin, getPlugin, definePlugin } from './plugin.js'
 
 // Feature 体系（Cron / Scheduler 来自 @zhin.js/kernel）
 export { Feature, Cron, Scheduler } from '@zhin.js/kernel'
-export { CommandFeature, ToolFeature, SkillFeature, CronFeature, DatabaseFeature, ... } from './built/*.js'
+export { CommandFeature, ToolFeature, SkillFeature, ScheduleFeature, DatabaseFeature, ... } from './built/*.js'
 
 // 消息路由
 export { createMessageDispatcher } from './built/dispatcher.js'
@@ -175,13 +220,23 @@ export { createMessageDispatcher } from './built/dispatcher.js'
 // 适配器与消息
 export { Adapter, Message, MessageCommand, Endpoint, segment, ... } from './'
 
-// HTML 出站回退
+// 富媒体出站段
+export {
+  resolveRichSegments,
+  DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY,
+  QrcodeSegment,
+  HtmlSegment,
+  MarkdownSegment,
+} from './built/rich-segments/index.js'
+export type { RichSegmentKind, RichRenderMode, OutboundRichSegmentPolicy } from './built/rich-segments/types.js'
+
+// HTML 出站回退（legacy；policy html:'text' 时等价）
 export { htmlToFallbackText, coerceHtmlSegmentsToText, registerHtmlSegmentFallback } from './built/*.js'
 
 // AI 原语（来自 @zhin.js/ai，非 ZhinAgent）
 export {
   OpenAIProvider, OllamaProvider, Agent, createAgent, ModelRegistry,
-  SessionManager, ContextManager, ConversationMemory, compactSession, ...
+  ContextRepository, ContextManager, ConversationMemory, compactSession, ...
 } from '@zhin.js/ai'
 ```
 

package/lib/adapter.d.ts

@@ -1,11 +1,16 @@
 import { Endpoint } from "./endpoint.js";
 import { DEFAULT_ENDPOINT_CAPABILITIES, type EndpointCapability } from "./endpoint-capabilities.js";
+import type { EndpointManager } from "./built/endpoint-manager.js";
 import { Plugin } from "./plugin.js";
 import { EventEmitter } from "node:events";
 import { Message } from "./message.js";
 import { Notice } from "./notice.js";
 import { Request } from "./request.js";
-import { SendOptions } from "./types.js";
+import { EditMessageOptions, SendOptions } from "./types.js";
+import { type OutboundRichSegmentPolicy } from "./built/rich-segments/index.js";
+import { type InteractivePolicy } from "./built/interactive-segments/index.js";
+import { type AiOutboundCapabilities, type AiOutboundExtensionDefinition } from "./built/ai-outbound/index.js";
+import type { Schema } from '@zhin.js/schema';
 /**
  * Adapter类：适配器抽象，管理多平台Bot实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
@@ -21,6 +26,15 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     private recallMessageHandler;
     /** Adapter 支持的能力上限（子类覆盖） */
     static readonly capabilities: readonly EndpointCapability[];
+    /** 出站富媒体段渲染策略（子类 override static） */
+    static outboundRichSegmentPolicy: OutboundRichSegmentPolicy;
+    /** 交互段出站策略：native 保留按钮段，text 降级为编号文本 */
+    static interactivePolicy: InteractivePolicy;
+    /** AI 结构化出站能力声明（mentions / richSegments / interactive） */
+    static aiOutboundCapabilities: AiOutboundCapabilities;
+    /** 平台特有 extensions schema + 解析（对齐各 SDK 文档子集） */
+    static aiOutboundExtensions?: readonly AiOutboundExtensionDefinition[];
+    protected getInteractivePolicy(): InteractivePolicy;
     /** 并发上限，0 表示不限制（默认） */
     static DEFAULT_MAX_CONCURRENT_MESSAGES: number;
     get maxConcurrentMessages(): number;
@@ -42,6 +56,17 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
     abstract createEndpoint(config: Adapter.EndpointConfig<R>): R;
     get logger(): import("@zhin.js/logger").Logger;
     binding(plugin: Plugin): void;
+    /**
+     * 同步等待入站管线结束（middleware → dispatcher → 生命周期 → 观察者）。
+     * 用于 QQ 等需在被动回复完成后再 ack 交互的平台事件。
+     */
+    receiveMessageAwait(message: Message): Promise<boolean>;
+    /** 运行时 Endpoint 管理（add/remove/edit/start/stop）；未实现则 core 尝试 endpointConfigSchema 通用向导 */
+    getEndpointManager?(): EndpointManager | null;
+    /** 通用 schema 驱动 add/edit 时的字段定义 */
+    getEndpointConfigSchema?(): Schema | undefined;
+    /** 热连接失败时是否建议重启进程 */
+    getEndpointNeedsRestart?(): boolean;
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
      */
@@ -52,8 +77,22 @@ export declare abstract class Adapter<R extends Endpoint = Endpoint, const Caps
         file?: boolean;
         maxAttachmentBytes?: number;
     };
-    private renderSendMessage;
+    protected getOutboundRichSegmentPolicy(): OutboundRichSegmentPolicy;
+    /**
+     * 出站两阶段：
+     * 1. resolveRichSegments — 语义段 → 标准 IM 段（image/audio/text）
+     * 2. Endpoint materializeOutboundMedia — base64/本地路径 → 平台 URL（各 adapter 可选）
+     * @see docs/essentials/rich-segment-adapters.md
+     */
+    protected renderSendMessage(options: SendOptions): Promise<SendOptions>;
     sendMessage(options: SendOptions): Promise<string>;
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 API
+     * - 否则 fallback 到发送新消息
+     * @returns 消息 ID（编辑时返回原 ID，fallback 时返回新消息 ID）
+     */
+    editMessage(options: EditMessageOptions): Promise<string>;
     start(): Promise<void>;
     /**
      * 停止适配器，断开并移除所有 Endpoint 实例
@@ -95,4 +134,3 @@ export declare namespace Adapter {
      */
     function register(name: string, factory: Factory): void;
 }
-//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.js

@@ -2,10 +2,14 @@ import { assertOutbound, DEFAULT_ENDPOINT_CAPABILITIES, hasInbound, } from "./en
 import { connectEndpointInstance, disconnectEndpointInstance } from "./built/connect-endpoint-instance.js";
 import { EventEmitter } from "node:events";
 import { getOutboundReplyStore } from "./built/dispatcher.js";
-import { coerceHtmlSegmentsToText } from "./built/html-segment-fallback.js";
+import { DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY, resolveRichSegments, } from "./built/rich-segments/index.js";
+import { DEFAULT_INTERACTIVE_POLICY, resolveInteractiveSegments, } 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 { InboundMessagePipeline } from "./built/inbound-pipeline.js";
-import { formatCompact, truncatePreview } from '@zhin.js/logger';
+import { formatCompact, truncatePreview, formatContentChainLog, CONTENT_CHAIN_STAGE } from '@zhin.js/logger';
 /**
  * Adapter类：适配器抽象，管理多平台Bot实例。
  * 负责根据配置启动/关闭各平台机器人，统一异常处理。
@@ -20,6 +24,17 @@ export class Adapter extends EventEmitter {
     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 表示不限制（默认） */
@@ -100,6 +115,21 @@ 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++;
+        await this.inboundPipeline.receive(message, () => {
+            EventEmitter.prototype.emit.call(this, 'message.receive', message);
+        });
+        return true;
+    }
     /**
      * 出站富媒体能力（Publisher 按此过滤/降级；各 adapter 可覆盖）。
      */
@@ -112,16 +142,50 @@ 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 }));
+                    },
+                })),
+            };
+            options = {
+                ...options,
+                content: resolveInteractiveSegments(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);
             if (result)
                 options = result;
         }
-        if (options.content != null) {
-            options = { ...options, content: coerceHtmlSegmentsToText(options.content) };
-        }
         return options;
     }
     async sendMessage(options) {
@@ -146,6 +210,47 @@ export class Adapter extends EventEmitter {
         });
         return messageId;
     }
+    /**
+     * 编辑已发送的消息。
+     * - 如果 Endpoint 实现了 $editMessage，调用平台编辑 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 editable = endpoint;
+        if (editable.$editMessage) {
+            const rendered = await this.renderSendMessage({
+                context: options.context,
+                endpoint: options.endpoint,
+                id: options.id,
+                type: options.type,
+                content: options.content,
+            });
+            await editable.$editMessage({ ...options, content: rendered.content });
+            this.logger.info(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: '$editMessage 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();
@@ -230,4 +335,3 @@ export class Adapter extends EventEmitter {
     }
     Adapter.register = register;
 })(Adapter || (Adapter = {}));
-//# sourceMappingURL=adapter.js.map

package/lib/agent-prompt.d.ts

@@ -38,4 +38,3 @@ export interface AgentPromptContributor {
     /** Non-null replaces default TF-IDF deferred tool selection. */
     selectDeferredTools?(query: string, goal: string, catalog: DeferredToolCatalogItem[], maxTools: number): DeferredToolCatalogItem[] | null;
 }
-//# sourceMappingURL=agent-prompt.d.ts.map

package/lib/agent-prompt.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=agent-prompt.js.map

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

@@ -1,4 +1,9 @@
-import { Adapter, Plugin, Endpoint, SendOptions, Message } from "@zhin.js/core";
+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;
 }, {
@@ -33,7 +38,12 @@ export declare class ProcessEndpoint implements Endpoint<{
 }
 export declare class ProcessAdapter extends Adapter<ProcessEndpoint> {
     static readonly capabilities: readonly ["inbound", "outbound"];
+    static outboundRichSegmentPolicy: OutboundRichSegmentPolicy;
     constructor(plugin: Plugin);
+    /**
+     * process 出站由 $sendMessage 写入 stdout；父类 INFO preview 会与终端输出重复，故仅 debug 元数据。
+     */
+    sendMessage(options: SendOptions): Promise<string>;
     createEndpoint(config: Adapter.EndpointConfig<ProcessEndpoint>): ProcessEndpoint;
 }
 declare module '../adapter.js' {
@@ -41,4 +51,3 @@ declare module '../adapter.js' {
         process: ProcessAdapter;
     }
 }
-//# sourceMappingURL=adapter-process.d.ts.map

package/lib/built/adapter-process.js

@@ -1,5 +1,11 @@
-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";
+import { interpretOriginQrcodeForProcess } from "./rich-segments/qrcode-segment.js";
 export class ProcessEndpoint {
     adapter;
     $config;
@@ -59,6 +65,13 @@ export class ProcessEndpoint {
     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() {
@@ -72,11 +85,39 @@ export class ProcessEndpoint {
 }
 export class ProcessAdapter extends Adapter {
     static capabilities = ['inbound', 'outbound'];
+    static outboundRichSegmentPolicy = {
+        qrcode: 'origin',
+        html: 'text',
+        markdown: 'text',
+    };
     constructor(plugin) {
         super(plugin, 'process', [{ owner: runtimePid() }]);
     }
+    /**
+     * 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

@@ -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

@@ -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;

package/lib/built/ai-outbound/extensions/onebot-keyboard.js

@@ -0,0 +1,67 @@
+import { KeyboardSegment } from '../../interactive-segments/keyboard-segment.js';
+const ONEBOT_KEYBOARD_SCHEMA = {
+    type: 'object',
+    properties: {
+        rows: {
+            type: 'array',
+            items: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string' },
+                        payload: { type: 'string' },
+                        id: { type: 'string' },
+                    },
+                    required: ['label', 'payload'],
+                },
+            },
+        },
+    },
+    required: ['rows'],
+};
+function toKeyboardSegment(ext) {
+    if (!ext || typeof ext !== 'object')
+        return null;
+    const obj = ext;
+    const rowsRaw = obj.rows;
+    if (!Array.isArray(rowsRaw))
+        return null;
+    const rows = [];
+    for (const row of rowsRaw) {
+        if (!Array.isArray(row))
+            continue;
+        const buttons = [];
+        for (const btn of row) {
+            if (!btn || typeof btn !== 'object')
+                continue;
+            const b = btn;
+            const label = typeof b.label === 'string' ? b.label : '';
+            const payload = typeof b.payload === 'string' ? b.payload : '';
+            if (!label || !payload)
+                continue;
+            buttons.push({
+                id: typeof b.id === 'string' ? b.id : payload,
+                label,
+                payload,
+                disabled: b.disabled === true,
+            });
+        }
+        if (buttons.length)
+            rows.push(buttons);
+    }
+    if (!rows.length)
+        return null;
+    return new KeyboardSegment({ rows }).toElement();
+}
+export const ONEBOT_KEYBOARD_AI_OUTBOUND_EXTENSION = {
+    key: 'onebot.keyboard',
+    schema: ONEBOT_KEYBOARD_SCHEMA,
+    examples: [
+        '{"extensions":{"onebot.keyboard":{"rows":[[{"label":"确认","payload":"ok","id":"ok"}]]}}}',
+    ],
+    toMessageElements(ext, _ctx) {
+        const seg = toKeyboardSegment(ext);
+        return seg ? [seg] : [];
+    },
+};