@zhin.js/core 1.1.33 → 1.1.35

package/lib/tool-zod.d.ts

@@ -10,8 +10,24 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-import type { Tool, ToolContext } from './types.js';
+import type { Tool, ToolParametersSchema } from './types.js';
+import type { Message } from './message.js';
 type MaybePromise<T> = T | Promise<T>;
+export type ToolSchemaParseResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export declare function toolInputSchemaToParameters(schema: unknown): ToolParametersSchema;
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export declare function parseToolInputSchema<T>(schema: unknown, input: unknown): ToolSchemaParseResult<T>;
 export interface CreateToolFromZodOptions {
     tags?: string[];
     keywords?: string[];
@@ -23,6 +39,5 @@ export interface CreateToolFromZodOptions {
  * 从 Zod 模式创建 Tool，便于类型安全与校验。
  * 需要安装 zod：pnpm add zod。传入的 schema 应为 z.object({ ... })。
  */
-export declare function createToolFromZod<T extends Record<string, any>>(name: string, description: string, schema: any, execute: (args: T, context?: ToolContext) => MaybePromise<any>, options?: CreateToolFromZodOptions): Tool;
+export declare function createToolFromZod<T extends Record<string, any>>(name: string, description: string, schema: any, execute: (args: T, message?: Message<any>) => MaybePromise<any>, options?: CreateToolFromZodOptions): Tool;
 export {};
-//# sourceMappingURL=tool-zod.d.ts.map

package/lib/tool-zod.js

@@ -10,62 +10,151 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-function zodFieldToJsonSchema(z) {
-    if (!z || !z._def)
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function getShape(schema) {
+    const shape = schema?.shape;
+    if (typeof shape === 'function') {
+        const value = shape();
+        return isRecord(value) ? value : undefined;
+    }
+    return isRecord(shape) ? shape : undefined;
+}
+function acceptsUndefined(schema) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse === 'function') {
+        try {
+            return candidate.safeParse(undefined).success;
+        }
+        catch {
+            // Fall through to structural compatibility for non-Zod lookalikes.
+        }
+    }
+    const def = candidate?._def;
+    const kind = def?.typeName ?? def?.type;
+    return kind === 'ZodOptional'
+        || kind === 'ZodDefault'
+        || kind === 'optional'
+        || kind === 'default';
+}
+function requiredFromShape(schema, fallback) {
+    const shape = getShape(schema);
+    if (!shape)
+        return fallback?.length ? [...fallback] : undefined;
+    const required = Object.entries(shape)
+        .filter(([, field]) => !acceptsUndefined(field))
+        .map(([key]) => key);
+    return required.length ? required : undefined;
+}
+function descriptionOf(schema, def) {
+    const description = schema?.description ?? def.description;
+    return typeof description === 'string' ? description : undefined;
+}
+function zodFieldToJsonSchema(schema) {
+    const candidate = schema;
+    const def = candidate?._def;
+    if (!isRecord(def))
         return { type: 'string' };
-    const def = z._def;
-    const typeName = def.typeName;
-    if (typeName === 'ZodOptional' || typeName === 'ZodDefault') {
-        const inner = def.innerType ?? def.type;
-        return zodFieldToJsonSchema(inner);
+    const kind = def.typeName ?? def.type;
+    if (kind === 'ZodOptional' || kind === 'ZodDefault' || kind === 'optional' || kind === 'default') {
+        return zodFieldToJsonSchema(def.innerType ?? def.type);
     }
-    if (typeName === 'ZodString') {
-        const out = { type: 'string' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    const description = descriptionOf(schema, def);
+    const withDescription = (type) => description
+        ? { type, description }
+        : { type };
+    if (kind === 'ZodString' || kind === 'string')
+        return withDescription('string');
+    if (kind === 'ZodNumber' || kind === 'number')
+        return withDescription('number');
+    if (kind === 'ZodBoolean' || kind === 'boolean')
+        return withDescription('boolean');
+    if (kind === 'ZodEnum' || kind === 'enum') {
+        const values = Array.isArray(def.values)
+            ? def.values
+            : isRecord(def.entries)
+                ? Object.values(def.entries)
+                : [];
+        return { ...withDescription('string'), enum: values };
     }
-    if (typeName === 'ZodNumber') {
-        const out = { type: 'number' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodArray' || kind === 'array') {
+        return {
+            ...withDescription('array'),
+            items: zodFieldToJsonSchema(def.element ?? def.type),
+        };
     }
-    if (typeName === 'ZodBoolean') {
-        const out = { type: 'boolean' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodObject' || kind === 'object') {
+        return toolInputSchemaToParameters(schema);
     }
-    if (typeName === 'ZodEnum') {
-        return { type: 'string', enum: def.values };
+    return withDescription('string');
+}
+function isJsonObjectSchema(schema) {
+    if (!isRecord(schema) || schema.type !== 'object')
+        return false;
+    return typeof schema.safeParse !== 'function';
+}
+function fromNativeJsonSchema(schema) {
+    const candidate = schema;
+    if (typeof candidate?.toJSONSchema !== 'function')
+        return undefined;
+    try {
+        const converted = candidate.toJSONSchema();
+        if (!isRecord(converted) || converted.type !== 'object')
+            return undefined;
+        return {
+            ...converted,
+            type: 'object',
+            properties: isRecord(converted.properties)
+                ? converted.properties
+                : {},
+            required: requiredFromShape(schema, Array.isArray(converted.required)
+                ? converted.required.filter((key) => typeof key === 'string')
+                : undefined),
+        };
     }
-    if (typeName === 'ZodArray') {
-        return { type: 'array', items: zodFieldToJsonSchema(def.type ?? def.element) };
+    catch {
+        return undefined;
     }
-    return { type: 'string' };
 }
-function zodToJsonSchema(schema) {
-    const result = {
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export function toolInputSchemaToParameters(schema) {
+    if (isJsonObjectSchema(schema))
+        return schema;
+    const native = fromNativeJsonSchema(schema);
+    if (native)
+        return native;
+    const shape = getShape(schema);
+    const properties = {};
+    if (shape) {
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodFieldToJsonSchema(value);
+        }
+    }
+    return {
         type: 'object',
-        properties: {},
-        required: [],
+        properties: properties,
+        required: requiredFromShape(schema),
     };
-    if (!schema || !schema.shape)
-        return result;
-    const shape = schema.shape;
-    const properties = result.properties;
-    const required = [];
-    for (const [key, value] of Object.entries(shape)) {
-        const zodValue = value;
-        properties[key] = zodFieldToJsonSchema(zodValue);
-        const typeName = zodValue?._def?.typeName;
-        if (typeName !== 'ZodOptional' && typeName !== 'ZodDefault') {
-            required.push(key);
-        }
+}
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export function parseToolInputSchema(schema, input) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse !== 'function') {
+        return { ok: true, data: input };
     }
-    result.required = required.length > 0 ? required : undefined;
-    return result;
+    const parsed = candidate.safeParse(input);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const issues = parsed.error?.issues ?? parsed.error?.errors ?? [];
+    const error = issues
+        .map((issue) => `${(issue.path ?? []).join('.') || 'root'}: ${issue.message ?? 'invalid'}`)
+        .join('; ');
+    return { ok: false, error: error || 'Invalid arguments' };
 }
 /**
  * 从 Zod 模式创建 Tool，便于类型安全与校验。
@@ -75,18 +164,16 @@ export function createToolFromZod(name, description, schema, execute, options) {
     if (!schema?.safeParse) {
         throw new Error('createToolFromZod: schema must be a Zod object schema (e.g. z.object({ ... })). Install zod: pnpm add zod');
     }
-    const parameters = zodToJsonSchema(schema);
+    const parameters = toolInputSchemaToParameters(schema);
     return {
         name,
         description,
         parameters,
-        execute: async (args, context) => {
-            const parsed = schema.safeParse(args);
-            if (!parsed.success) {
-                const msg = parsed.error.errors?.map((e) => `${e.path?.join('.') ?? 'root'}: ${e.message}`).join('; ') ?? 'Invalid arguments';
-                return `Error: ${msg}`;
-            }
-            return execute(parsed.data, context);
+        execute: async (args, message) => {
+            const parsed = parseToolInputSchema(schema, args);
+            if (!parsed.ok)
+                return `Error: ${parsed.error}`;
+            return execute(parsed.data, message);
         },
         tags: options?.tags,
         keywords: options?.keywords,
@@ -95,4 +182,3 @@ export function createToolFromZod(name, description, schema, execute, options) {
         kind: options?.kind,
     };
 }
-//# sourceMappingURL=tool-zod.js.map

package/lib/types.d.ts

@@ -1,12 +1,10 @@
-import { MessageChannel, Message } from "./message.js";
-import { Adapter, Adapters } from "./adapter.js";
-import { Bot } from "./bot.js";
-import { SystemLog } from "./models/system-log.js";
-import { User } from "./models/user.js";
-import { Databases, Registry } from "@zhin.js/database";
-import { MessageComponent } from "./message.js";
-import { ProcessAdapter } from "./built/adapter-process.js";
-import type { SenderRole } from "./built/roles.js";
+import type { MessageChannel, Message, MessageComponent } from './message.js';
+import { Adapter, Adapters } from './adapter.js';
+import { Endpoint } from './endpoint.js';
+import { SystemLog } from './models/system-log.js';
+import { User } from './models/user.js';
+import { Databases, Registry } from '@zhin.js/database';
+import { ProcessAdapter } from './built/adapter-process.js';
 export type { SenderRole } from "./built/roles.js";
 export type ArrayItem<T> = T extends Array<infer R> ? R : unknown;
 export interface Models extends Record<string, object> {
@@ -34,19 +32,19 @@ export type RegisteredAdapter = Extract<keyof RegisteredAdapters, string>;
 /**
  * 指定适配器的消息类型
  */
-export type AdapterMessage<T extends keyof RegisteredAdapters = keyof RegisteredAdapters> = RegisteredAdapters[T] extends Adapter<infer R> ? BotMessage<R> : {};
+export type AdapterMessage<T extends keyof RegisteredAdapters = keyof RegisteredAdapters> = RegisteredAdapters[T] extends Adapter<infer R> ? EndpointMessage<R> : {};
 /**
  * 指定适配器的配置类型
  */
-export type AdapterConfig<T extends keyof RegisteredAdapters = keyof RegisteredAdapters> = RegisteredAdapters[T] extends Adapter<infer R> ? PlatformConfig<R> : Bot.Config;
+export type AdapterConfig<T extends keyof RegisteredAdapters = keyof RegisteredAdapters> = RegisteredAdapters[T] extends Adapter<infer R> ? PlatformConfig<R> : Endpoint.Config;
 /**
  * Bot实例的配置类型
  */
-export type PlatformConfig<T> = T extends Bot<infer L, infer R> ? R : Bot.Config;
+export type PlatformConfig<T> = T extends Endpoint<infer L, infer R> ? R : Endpoint.Config;
 /**
  * Bot实例的消息类型
  */
-export type BotMessage<T extends Bot> = T extends Bot<infer R> ? R : {};
+export type EndpointMessage<T extends Endpoint> = T extends Endpoint<infer R> ? R : {};
 /**
  * 消息段结构，支持 text/image/at/face 等类型
  */
@@ -63,23 +61,24 @@ export type MaybeArray<T> = T | T[];
  * 消息发送内容类型
  */
 export type SendContent = MaybeArray<string | MessageElement>;
-/** $getMsg 返回的被引用消息载荷 */
-export interface QuotedMessagePayload {
+/** 可选：编辑已发送消息（交互式棋盘更新） */
+export interface EditMessageOptions {
     messageId: string;
-    sender?: {
-        id?: string;
-        name?: string;
-    };
-    content: MessageElement[] | string;
-    raw?: string;
-    time?: number;
+    context: string;
+    endpoint: string;
+    id: string;
+    type: 'private' | 'group' | 'channel';
+    content: SendContent;
 }
-/** 支持按 message_id 拉取历史消息的 Bot（可选实现） */
-export interface QuotableBot {
-    $getMsg(messageId: string): Promise<QuotedMessagePayload>;
+/** 出站回复来源（指令 / AI / proactive），仅当经 MessageDispatcher.replyWithPolish 或 runWithOutboundPolish 发出时由框架填入异步上下文 */
+export type OutboundReplySource = 'command' | 'ai' | 'proactive';
+export type OutboundReplyTrigger = 'inbound' | 'proactive';
+export interface OutboundReplyStore {
+    message: Message;
+    source: OutboundReplySource;
+    trigger: OutboundReplyTrigger;
+    proactiveSource?: string;
 }
-/** 出站回复来源（指令 / AI），仅当经 MessageDispatcher.replyWithPolish 发出时由框架填入异步上下文 */
-export type OutboundReplySource = 'command' | 'ai';
 /**
  * 出站润色上下文（`dispatcher.addOutboundPolish` 的 handler 签名的同构类型）。
  * 与 {@link Adapter.sendMessage} → `before.sendMessage` 同一管道；需 `message`/`source` 时见 `getOutboundReplyStore`（dispatcher 导出）。
@@ -98,13 +97,17 @@ export interface MessageSender {
     id: string;
     name?: string;
     permissions?: string[];
-    /** 平台侧角色标识（owner / admin / member 等） */
+    /** 平台群成员身份（owner / admin / member）— 仅供 platform checker */
     role?: string;
+    /** enrich 快照：endpoint 实例 master */
+    isMaster?: boolean;
+    /** enrich 快照：endpoint 实例 trusted */
+    isTrusted?: boolean;
 }
 /**
  * 通用字典类型
  */
-export type Dict<V = any, K extends string | symbol = string> = Record<K, V>;
+export type { Dict } from '@zhin.js/kernel';
 /**
  * 用户信息结构
  */
@@ -130,8 +133,10 @@ export type MessageMiddleware<P extends RegisteredAdapter = RegisteredAdapter> =
 export type DefineConfig<T> = T | ((env: Record<string, string>) => MaybePromise<T>);
 export interface SendOptions extends MessageChannel {
     context: string;
-    bot: string;
+    endpoint: string;
     content: SendContent;
+    quoteId?: string;
+    threadId?: string;
 }
 /** `Adapter.sendMessage` 成功发出后由 core 分发的载荷 */
 export interface MessageSendPayload {
@@ -156,8 +161,8 @@ export type BeforeSendHandler = (options: SendOptions) => MaybePromise<SendOptio
 /**
  * JSON Schema 定义，用于描述工具参数
  */
-/** ToolContext 中可自动注入的字段名 */
-export type ContextInjectableKey = 'platform' | 'botId' | 'sceneId' | 'senderId' | 'scope';
+/** Message 通讯上下文上可经 resolveContextKey 自动注入的字段名 */
+export type ContextInjectableKey = 'platform' | 'endpointKey' | 'sceneId' | 'senderId' | 'scope';
 export interface ToolJsonSchema {
     type: string;
     properties?: Record<string, ToolJsonSchema & {
@@ -170,9 +175,9 @@ export interface ToolJsonSchema {
     description?: string;
     default?: any;
     /**
-     * 自动从 ToolContext 注入的字段名。
+     * 自动从 Message 通讯上下文注入的字段名（经 resolveContextKey 映射 $ 字段）。
      * 设置后该参数对 AI 隐藏，执行时自动从上下文填充。
-     * 例如: contextKey: 'botId' → 执行时自动填入 context.botId
+     * 例如: contextKey: 'endpointKey' → 执行时自动填入 message.$endpoint
      */
     contextKey?: ContextInjectableKey;
     [key: string]: any;
@@ -190,7 +195,7 @@ export interface PropertySchema<T = any> extends ToolJsonSchema {
     default?: T;
     enum?: T extends string | number ? T[] : never;
     paramType?: 'text' | 'number' | 'boolean' | 'rest';
-    /** 自动从 ToolContext 注入的字段名（继承自 ToolJsonSchema） */
+    /** 自动从 Message 注入的字段名（继承自 ToolJsonSchema） */
     contextKey?: ContextInjectableKey;
 }
 /**
@@ -213,38 +218,6 @@ export interface ToolParametersSchema<TArgs extends Record<string, any> = Record
     /** 描述 */
     description?: string;
 }
-/**
- * 工具执行上下文
- * 包含消息来源、发送者等 IM 信息。
- * 通用（IM 无关）版本请使用 @zhin.js/ai 的 ToolContext。
- */
-export interface ToolContext {
-    /** 来源平台 */
-    platform?: string;
-    /** 来源 Bot */
-    botId?: string;
-    /** 消息 ID */
-    messageId?: string;
-    /** 场景 ID（群号/频道ID/私聊用户ID） */
-    sceneId?: string;
-    /** 发送者 ID */
-    senderId?: string;
-    /** 原始消息对象（如果从消息触发） */
-    message?: Message<any>;
-    /**
-     * 消息场景类型
-     * private: 私聊, group: 群聊, channel: 频道
-     */
-    scope?: ToolScope;
-    /** 发送者角色集合（群角色 + bot master/trusted 可并存） */
-    roles?: readonly SenderRole[];
-    /**
-     * 文件操作角色 — 用于文件工具的权限控制
-     */
-    fileRole?: FileRole;
-    /** 额外数据 */
-    extra?: Record<string, any>;
-}
 /**
  * 统一的 Tool 定义
  * 可同时用于：
@@ -334,10 +307,10 @@ export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
     /**
      * 工具执行函数
      * @param args 解析后的参数
-     * @param context 执行上下文（包含消息、发送者等信息）
+     * @param message 通讯上下文（入站 Message 或合成 Message）
      * @returns 执行结果
      */
-    execute: (args: TArgs, context?: ToolContext) => MaybePromise<ToolResult>;
+    execute: (args: TArgs, message?: Message<any>) => MaybePromise<ToolResult>;
     /** 工具来源标识（自动填充：adapter:xxx / plugin:xxx） */
     source?: string;
     /** 工具标签（用于分类和过滤） */
@@ -349,6 +322,8 @@ export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
      * 执行此工具需要的权限列表
      */
     permissions?: string[];
+    /** Per-tool approval policy; `on-risk` remains fail-closed at Agent boundaries. */
+    approval?: 'always' | 'once' | 'never' | 'on-risk';
     /**
      * 支持的平台列表
      * 例如：['qq', 'telegram', 'discord']
@@ -361,11 +336,6 @@ export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
      * 不填则支持所有场景
      */
     scopes?: ToolScope[];
-    /**
-     * 调用者需具备的角色之一（隐含升格见 roles.ts）
-     * 省略则仅需 user
-     */
-    requiredAnyRole?: readonly SenderRole[];
     /**
      * 是否隐藏
      * 隐藏的工具不会出现在帮助列表中，但仍可被调用
@@ -386,10 +356,6 @@ export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
      */
     command?: ToolCommandConfig | false;
 }
-/**
- * @deprecated 使用 `Tool<TArgs>` 替代。Tool 已原生支持泛型。
- */
-export type ToolDefinition<TArgs extends Record<string, any> = Record<string, any>> = Tool<TArgs>;
 export declare namespace Tool {
     /**
      * 参数信息
@@ -416,10 +382,3 @@ export interface PluginManifest {
 }
 /** @deprecated 使用 Tool 替代 */
 export type AITool = Tool;
-/**
- * IMToolContext — ToolContext 的显式 IM 别名。
- * 当同时使用 @zhin.js/ai (通用 ToolContext) 和 @zhin.js/core (IM ToolContext) 时，
- * 用此类型消除歧义。
- */
-export type IMToolContext = ToolContext;
-//# sourceMappingURL=types.d.ts.map

package/lib/types.js

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

package/lib/utils.d.ts

@@ -7,8 +7,19 @@
 export { evaluate, execute, clearEvalCache, getEvalCacheStats, getValueWithRuntime, compiler, remove, isEmpty, Time, supportedPluginExtensions, resolveEntry, sleep, } from '@zhin.js/kernel';
 import { AdapterMessage, MessageMiddleware, RegisteredAdapter, SendContent } from "./types.js";
 import { Message } from "./message.js";
+import { HtmlSegment } from "./built/rich-segments/html-segment.js";
+import { MarkdownSegment } from "./built/rich-segments/markdown-segment.js";
+import { QrcodeSegment } from "./built/rich-segments/qrcode-segment.js";
+import { TtsSegment } from "./built/rich-segments/tts-segment.js";
+import { KeyboardSegment } from "./built/interactive-segments/keyboard-segment.js";
+import { ButtonSpec, type KeyboardRowInput } from "./built/interactive-segments/button-spec.js";
+import type { ButtonData, KeyboardFallback, KeyboardSegmentData } from "./built/interactive-segments/types.js";
+import type { MediaRef } from "./built/segment-contract/types.js";
 /**
  * 组合中间件,洋葱模型
+ *
+ * 空中间件列表时必须仍调用 `next`——入站管线把 MessageDispatcher
+ * 作为 terminal next 传入；吞掉 next 会导致命令/AI 永远不跑。
  */
 export declare function compose<P extends RegisteredAdapter = RegisteredAdapter>(middlewares: MessageMiddleware<P>[]): (message: Message<AdapterMessage<P>>, next?: () => Promise<void>) => Promise<void>;
 export declare function segment<T extends object>(type: string, data: T): {
@@ -24,6 +35,26 @@ export declare namespace segment {
             text: string;
         };
     };
+    function mention(target: string, name?: string): {
+        type: string;
+        data: {
+            target: string;
+            name: string;
+        } | {
+            target: string;
+            name?: undefined;
+        };
+    };
+    function image(media: MediaRef, alt?: string): {
+        type: string;
+        data: {
+            media: MediaRef;
+            alt: string;
+        } | {
+            media: MediaRef;
+            alt?: undefined;
+        };
+    };
     function face(id: string, text?: string): {
         type: string;
         data: {
@@ -31,8 +62,44 @@ export declare namespace segment {
             text: string | undefined;
         };
     };
+    /** 出站 HTML 卡片段（Adapter policy 决定 image/text/origin） */
+    function htmlCard(options: {
+        html: string;
+        text?: string;
+        width?: number;
+        backgroundColor?: string;
+        fileName?: string;
+    }): HtmlSegment;
+    /** Short alias for {@link htmlCard}. */
+    const html: typeof htmlCard;
+    /** 出站 Markdown 段（Adapter policy 决定 image/text/origin） */
+    function markdown(content: string, options?: Omit<MarkdownSegment['data'], 'content'>): MarkdownSegment;
+    /** 二维码出站段（Adapter policy 决定 image/text/origin） */
+    function qrcode(text: string, options?: {
+        width?: number;
+        margin?: number;
+        errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+        small?: boolean;
+    }): QrcodeSegment;
+    /** TTS 出站段（Adapter policy 决定 audio/text/origin） */
+    function tts(options: {
+        text: string;
+        voice?: string;
+        provider?: string;
+    }): TtsSegment;
+    /** 键盘按钮单元（与 {@link keyboard} 组合布局） */
+    function button(data: ButtonData): ButtonSpec;
+    /** 键盘布局出站段（Adapter interactivePolicy 决定 native/text） */
+    function keyboard(rows: KeyboardRowInput[], options?: {
+        fallback?: KeyboardFallback;
+    }): KeyboardSegment;
+    /**
+     * @deprecated 使用 {@link keyboard} + {@link button}；文本请用 `segment.text` 单独发送
+     */
+    function interactive(data: KeyboardSegmentData & {
+        text?: SendContent;
+    }): KeyboardSegment;
     function from(content: SendContent): SendContent;
     function raw(content: SendContent): string;
     function toString(content: SendContent): string;
 }
-//# sourceMappingURL=utils.d.ts.map