@zhin.js/adapter-discord 6.0.5 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @zhin.js/adapter-discord
 
+## 7.0.0
+
+### Patch Changes
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - @zhin.js/agent@1.1.0
+  - zhin.js@6.0.0
+
+## 6.0.6
+
+### Patch Changes
+
+- d52f3c5: fix: QQ 适配器群聊误识别为私聊、game-kit 启动崩溃、全面补齐 recallMessage
+
+  - fix(cli): `resolveChannelType` 增加 `metadata.channelKind` 检查，修复 QQ/Discord/KOOK 群聊消息被误分类为私聊
+  - fix(game-kit): `createHostGameDb` 改用延迟代理模型，避免数据库启动前解析模型导致崩溃
+  - feat(qq): 实现 `recallMessage`，解析复合 messageId 路由到对应 SDK 撤回方法；`normalizeQqMessage` 增加 `message_type` 缺失时的回退检测
+  - feat(slack): 实现 `recallMessage`，利用已有 compound ref 和 `chat.delete` API
+  - feat(onebot11): 两个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(onebot12): 两个 endpoint 类实现 `recallMessage`（`delete_message`）
+  - feat(napcat): 三个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(discord): 两个 endpoint 类实现 `recallMessage`；`send()` 改为返回 `channelId:snowflake` 复合 ID
+  - feat(telegram): 实现 `recallMessage`（`deleteMessage`）；`send()` 改为返回 `chatId:messageId` 复合 ID
+  - feat(kook): 两个 endpoint 类实现 `recallMessage`，利用 kook-client `recallMsg` API
+  - feat(lark): 实现 `recallMessage`（`DELETE /im/v1/messages/{id}`）
+  - feat(wecom): 实现 `recallMessage`（`POST /cgi-bin/message/recall`）
+
 ## 6.0.5
 
 ### Patch Changes

package/adapters/discord.js

@@ -11,6 +11,7 @@ import { discordRuntimeStateToken } from "../lib/discord-runtime-state.js";
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
     segments: {
         outboundMedia: ['url', 'upload'],
@@ -19,7 +20,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveDiscordConfig(context.config);
         const gateway = context.use(messageGatewayToken);
-        // 注册到插件运行时状态（discord endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
         context.use(discordRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.connection,

package/adapters/discord.ts

@@ -27,6 +27,7 @@ export type {
 
 export default defineAdapter<DiscordAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
   segments: {
     outboundMedia: ['url', 'upload'],
@@ -35,7 +36,7 @@ export default defineAdapter<DiscordAdapterConfig>({
   create(context) {
     const config = resolveDiscordConfig(context.config);
     const gateway = context.use(messageGatewayToken);
-    // 注册到插件运行时状态（discord endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
     context.use(discordRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.connection,

package/lib/discord-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `discord endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `discord.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  * 注：applicationId / publicKey 为顶层共享字段（slash commands / interactions 用），
  * endpoints[i] 仅需 name + token（见 schema.json），故 add 只录入 token。

package/lib/discord-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `discord endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `discord.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 export const discordRuntimeStateToken = defineEndpointRuntimeStateToken('discord');

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -14,15 +14,14 @@ export interface DiscordEndpointOptions {
 export declare class DiscordGatewayEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: DiscordEndpointOptions);
     start(): Promise<void>;
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: DiscordInboundMessage): void;
     /** Test / internal: admit a button interaction when open. */
@@ -57,6 +56,7 @@ export interface DiscordInteractionsEndpointOptions {
 }
 export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     #private;
+    readonly control: EndpointControl;
     constructor(options: DiscordInteractionsEndpointOptions);
     get isOpen(): boolean;
     get config(): ResolvedDiscordInteractionsConfig;
@@ -64,10 +64,8 @@ export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     admit(msg: DiscordInboundMessage): void;
 }
 /**

package/lib/endpoint.js

@@ -2,6 +2,7 @@
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
+import { formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
@@ -22,6 +23,19 @@ export class DiscordGatewayEndpoint {
         getClient: () => this.#requireClient(),
         getMembers: (guildId) => this.getMembers(guildId),
     });
+    control = Object.freeze({
+        recall: (messageId) => this.recallMessage(messageId),
+        addReaction: async (messageId, emoji, hint) => {
+            const reference = parseLegacyMessageReference(messageId);
+            const channelId = hint?.channelId
+                ?? (reference ? nativeConversationId(reference.target) : undefined);
+            const nativeMessageId = reference?.messageId ?? messageId;
+            if (!channelId || !nativeMessageId)
+                return null;
+            await this.addReaction(channelId, nativeMessageId, emoji);
+            return emoji;
+        },
+    });
     constructor(options) {
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
@@ -76,9 +90,11 @@ export class DiscordGatewayEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ target, conversation, payload }) {
         const body = formatOutboundBody(payload);
-        const messageId = await this.#sendBody(target, body);
+        const channelId = nativeConversationId(target, conversation);
+        const snowflake = await this.#sendBody(channelId, body);
+        const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
         logger.debug(formatCompact({
             op: 'discord_send',
             endpoint: this.#options.config.name,
@@ -87,6 +103,20 @@ export class DiscordGatewayEndpoint {
         }));
         return messageId;
     }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        const reference = parseLegacyMessageReference(messageId);
+        if (!reference)
+            return;
+        const channelId = nativeConversationId(reference.target);
+        const snowflake = reference.messageId;
+        const channel = await this.#requireClient().channels.fetch(channelId);
+        if (!channel?.isTextBased() || !channel.messages)
+            return;
+        const msg = await channel.messages.fetch(snowflake);
+        await msg.delete();
+    }
     /** Test / internal: admit a message when open. */
     admit(msg) {
         if (!this.#open)
@@ -281,6 +311,9 @@ export class DiscordInteractionsEndpoint {
     #routeReleases = [];
     #open = false;
     #started = false;
+    control = Object.freeze({
+        recall: (messageId) => this.recallMessage(messageId),
+    });
     constructor(options) {
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
@@ -316,9 +349,10 @@ export class DiscordInteractionsEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ target, conversation, payload }) {
         const body = formatOutboundBody(payload);
-        const response = await this.#fetch(`${DISCORD_API}/channels/${target}/messages`, {
+        const channelId = nativeConversationId(target, conversation);
+        const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
             method: 'POST',
             headers: {
                 Authorization: `Bot ${this.#options.config.token}`,
@@ -332,7 +366,26 @@ export class DiscordInteractionsEndpoint {
             throw new Error(`Discord send failed (${response.status}): ${text.slice(0, 200)}`);
         }
         const data = JSON.parse(text);
-        return data.id ?? '';
+        const snowflake = data.id ?? '';
+        return snowflake ? formatLegacyMessageReference({ target, messageId: snowflake }) : '';
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        const reference = parseLegacyMessageReference(messageId);
+        if (!reference)
+            return;
+        const channelId = nativeConversationId(reference.target);
+        const snowflake = reference.messageId;
+        const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages/${snowflake}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bot ${this.#options.config.token}` },
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
+        });
+        if (!response.ok && response.status !== 404) {
+            const text = await response.text();
+            throw new Error(`Discord recall failed (${response.status}): ${text.slice(0, 200)}`);
+        }
     }
     admit(msg) {
         if (!this.#open)

package/lib/gateway.d.ts

@@ -26,6 +26,7 @@ export interface DiscordClientTransport {
             }>;
             messages?: {
                 fetch(id: string): Promise<{
+                    delete(): Promise<unknown>;
                     react(emoji: string): Promise<unknown>;
                     reactions: {
                         resolve(emoji: unknown): {

package/lib/gateway.js

@@ -111,7 +111,12 @@ export async function toMessageCreateOptions(body) {
     if (body.files?.length) {
         const files = [];
         for (const file of body.files) {
-            if (file.file && await fileExists(file.file)) {
+            if (file.base64) {
+                files.push(new AttachmentBuilder(decodeBase64(file.base64), {
+                    name: file.name || 'attachment',
+                }));
+            }
+            else if (file.file && await fileExists(file.file)) {
                 files.push(new AttachmentBuilder(createReadStream(file.file), {
                     name: file.name || path.basename(file.file),
                 }));
@@ -119,6 +124,13 @@ export async function toMessageCreateOptions(body) {
             else if (file.url) {
                 files.push(new AttachmentBuilder(file.url, { name: file.name || 'attachment' }));
             }
+            else {
+                logger.warn(formatCompact({
+                    op: 'discord_outbound_media_dropped',
+                    reason: 'missing_source',
+                    name: file.name,
+                }));
+            }
         }
         if (files.length)
             options.files = files;
@@ -176,6 +188,12 @@ async function fileExists(filePath) {
         return false;
     }
 }
+/** base64:// / data:*;base64, 前缀归一，Buffer.from 只接受纯 base64。 */
+function decodeBase64(value) {
+    const stripped = value.startsWith('base64://') ? value.slice('base64://'.length) : value;
+    const comma = stripped.startsWith('data:') ? stripped.indexOf(',') : -1;
+    return Buffer.from(comma >= 0 ? stripped.slice(comma + 1) : stripped, 'base64');
+}
 export async function connectDiscordGatewayClient(client, config, handlers) {
     return new Promise((resolve, reject) => {
         let settled = false;

package/lib/protocol.d.ts

@@ -116,6 +116,7 @@ export interface DiscordOutboundBody {
         name: string;
         url?: string;
         file?: string;
+        base64?: string;
     }>;
     readonly components?: ReadonlyArray<DiscordOutboundActionRow>;
 }

package/lib/protocol.js

@@ -3,6 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('discord');
 export function resolveDiscordConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'discord' || !item.context);
     const token = (typeof config.token === 'string' && config.token)
@@ -204,12 +207,35 @@ export function formatOutboundBody(payload) {
             case 'audio':
             case 'video':
             case 'file': {
-                const name = String(data.name || data.filename || item.type);
-                if (typeof data.file === 'string' && data.file) {
-                    files.push({ name, file: data.file });
+                // canonical MediaRef 唯一媒体来源（中央 normalizeOutboundPayload 已保证形状）
+                const media = data.media;
+                if (!isMediaRef(media)) {
+                    logger.warn(formatCompact({
+                        op: 'discord_outbound_media_dropped',
+                        type: item.type,
+                        reason: 'missing_media_ref',
+                    }));
+                    break;
                 }
-                else if (typeof data.url === 'string' && data.url) {
-                    files.push({ name, url: data.url });
+                const name = media.file_name
+                    ?? (typeof data.name === 'string' && data.name ? data.name : item.type);
+                if (media.kind === 'url') {
+                    files.push({ name, url: media.value });
+                }
+                else if (media.kind === 'base64') {
+                    files.push({ name, base64: media.value });
+                }
+                else if (media.kind === 'path') {
+                    files.push({ name, file: media.value });
+                }
+                else {
+                    // kind=file：Discord 无平台不透明文件引用，无法投递
+                    logger.warn(formatCompact({
+                        op: 'discord_outbound_media_dropped',
+                        type: item.type,
+                        reason: 'unsupported_media_kind',
+                        kind: media.kind,
+                    }));
                 }
                 break;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "6.0.5",
+  "version": "7.0.0",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,20 +33,21 @@
   },
   "dependencies": {
     "discord.js": "^14.27.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
+    "@zhin.js/im-contract": "1.0.0",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -64,9 +65,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
+    "@zhin.js/agent": "1.1.0",
     "@zhin.js/host-http": "1.0.4",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'Discord Gateway Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（discord endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（discord.endpoint list 的"运行中"数据源）
         context.resources.provide(discordRuntimeStateToken, createEndpointRuntimeState());
         // 平台权限门禁：guild_owner / moderate_members 等（agent 工具 platformPermit）
         return registerDiscordPlatformPermitChecker();

package/src/discord-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `discord endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `discord.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  * 注：applicationId / publicKey 为顶层共享字段（slash commands / interactions 用），
  * endpoints[i] 仅需 name + token（见 schema.json），故 add 只录入 token。

package/src/discord-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `discord endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `discord.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 

package/src/endpoint.ts

@@ -4,12 +4,19 @@
 import { ChannelType } from 'discord.js';
 import type {
   EndpointChannel,
+  EndpointControl,
   EndpointGroup,
   EndpointInstance,
   EndpointManagement,
+  EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import {
+  formatLegacyMessageReference,
+  nativeConversationId,
+  parseLegacyMessageReference,
+} from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
@@ -65,6 +72,22 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     getClient: () => this.#requireClient(),
     getMembers: (guildId) => this.getMembers(guildId),
   });
+  readonly control: EndpointControl = Object.freeze({
+    recall: (messageId: string) => this.recallMessage(messageId),
+    addReaction: async (
+      messageId: string,
+      emoji: string,
+      hint?: { readonly sceneType?: string; readonly channelId?: string },
+    ) => {
+      const reference = parseLegacyMessageReference(messageId);
+      const channelId = hint?.channelId
+        ?? (reference ? nativeConversationId(reference.target) : undefined);
+      const nativeMessageId = reference?.messageId ?? messageId;
+      if (!channelId || !nativeMessageId) return null;
+      await this.addReaction(channelId, nativeMessageId, emoji);
+      return emoji;
+    },
+  });
 
   constructor(options: DiscordEndpointOptions) {
     this.#options = options;
@@ -122,9 +145,11 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundBody(payload);
-    const messageId = await this.#sendBody(target, body);
+    const channelId = nativeConversationId(target, conversation);
+    const snowflake = await this.#sendBody(channelId, body);
+    const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
     logger.debug(formatCompact({
       op: 'discord_send',
       endpoint: this.#options.config.name,
@@ -134,6 +159,18 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    const reference = parseLegacyMessageReference(messageId);
+    if (!reference) return;
+    const channelId = nativeConversationId(reference.target);
+    const snowflake = reference.messageId;
+    const channel = await this.#requireClient().channels.fetch(channelId);
+    if (!channel?.isTextBased() || !channel.messages) return;
+    const msg = await channel.messages.fetch(snowflake);
+    await msg.delete();
+  }
+
   /** Test / internal: admit a message when open. */
   admit(msg: DiscordInboundMessage): void {
     if (!this.#open) return;
@@ -384,6 +421,9 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
+  readonly control: EndpointControl = Object.freeze({
+    recall: (messageId: string) => this.recallMessage(messageId),
+  });
 
   constructor(options: DiscordInteractionsEndpointOptions) {
     this.#options = options;
@@ -425,9 +465,10 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundBody(payload);
-    const response = await this.#fetch(`${DISCORD_API}/channels/${target}/messages`, {
+    const channelId = nativeConversationId(target, conversation);
+    const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
       method: 'POST',
       headers: {
         Authorization: `Bot ${this.#options.config.token}`,
@@ -441,7 +482,25 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
       throw new Error(`Discord send failed (${response.status}): ${text.slice(0, 200)}`);
     }
     const data = JSON.parse(text) as { id?: string };
-    return data.id ?? '';
+    const snowflake = data.id ?? '';
+    return snowflake ? formatLegacyMessageReference({ target, messageId: snowflake }) : '';
+  }
+
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    const reference = parseLegacyMessageReference(messageId);
+    if (!reference) return;
+    const channelId = nativeConversationId(reference.target);
+    const snowflake = reference.messageId;
+    const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages/${snowflake}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bot ${this.#options.config.token}` },
+      signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
+    });
+    if (!response.ok && response.status !== 404) {
+      const text = await response.text();
+      throw new Error(`Discord recall failed (${response.status}): ${text.slice(0, 200)}`);
+    }
   }
 
   admit(msg: DiscordInboundMessage): void {

package/src/gateway.ts

@@ -55,6 +55,7 @@ export interface DiscordClientTransport {
       send?(options: MessageCreateOptions): Promise<{ id: string }>;
       messages?: {
         fetch(id: string): Promise<{
+          delete(): Promise<unknown>;
           react(emoji: string): Promise<unknown>;
           reactions: {
             resolve(emoji: unknown): { users: { remove(userId: string): Promise<unknown> } } | null;
@@ -197,12 +198,22 @@ export async function toMessageCreateOptions(body: DiscordOutboundBody): Promise
   if (body.files?.length) {
     const files: AttachmentBuilder[] = [];
     for (const file of body.files) {
-      if (file.file && await fileExists(file.file)) {
+      if (file.base64) {
+        files.push(new AttachmentBuilder(decodeBase64(file.base64), {
+          name: file.name || 'attachment',
+        }));
+      } else if (file.file && await fileExists(file.file)) {
         files.push(new AttachmentBuilder(createReadStream(file.file), {
           name: file.name || path.basename(file.file),
         }));
       } else if (file.url) {
         files.push(new AttachmentBuilder(file.url, { name: file.name || 'attachment' }));
+      } else {
+        logger.warn(formatCompact({
+          op: 'discord_outbound_media_dropped',
+          reason: 'missing_source',
+          name: file.name,
+        }));
       }
     }
     if (files.length) options.files = files;
@@ -266,6 +277,13 @@ async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
+/** base64:// / data:*;base64, 前缀归一，Buffer.from 只接受纯 base64。 */
+function decodeBase64(value: string): Buffer {
+  const stripped = value.startsWith('base64://') ? value.slice('base64://'.length) : value;
+  const comma = stripped.startsWith('data:') ? stripped.indexOf(',') : -1;
+  return Buffer.from(comma >= 0 ? stripped.slice(comma + 1) : stripped, 'base64');
+}
+
 export interface DiscordGatewayConnectHandlers {
   onMessage(msg: DiscordInboundMessage): void;
   onButton(interaction: DiscordButtonInbound): void;

package/src/protocol.ts

@@ -4,7 +4,11 @@
  */
 
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('discord');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DiscordAdapterConfig {
@@ -131,6 +135,7 @@ export interface DiscordOutboundBody {
     name: string;
     url?: string;
     file?: string;
+    base64?: string;
   }>;
   readonly components?: ReadonlyArray<DiscordOutboundActionRow>;
 }
@@ -314,7 +319,7 @@ export function formatOutboundBody(payload: unknown): DiscordOutboundBody {
 
   let content = '';
   const embeds: Record<string, unknown>[] = [];
-  const files: Array<{ name: string; url?: string; file?: string }> = [];
+  const files: Array<{ name: string; url?: string; file?: string; base64?: string }> = [];
   let components: DiscordOutboundBody['components'];
 
   for (const item of segments) {
@@ -345,11 +350,32 @@ export function formatOutboundBody(payload: unknown): DiscordOutboundBody {
       case 'audio':
       case 'video':
       case 'file': {
-        const name = String(data.name || data.filename || item.type);
-        if (typeof data.file === 'string' && data.file) {
-          files.push({ name, file: data.file });
-        } else if (typeof data.url === 'string' && data.url) {
-          files.push({ name, url: data.url });
+        // canonical MediaRef 唯一媒体来源（中央 normalizeOutboundPayload 已保证形状）
+        const media = data.media;
+        if (!isMediaRef(media)) {
+          logger.warn(formatCompact({
+            op: 'discord_outbound_media_dropped',
+            type: item.type,
+            reason: 'missing_media_ref',
+          }));
+          break;
+        }
+        const name = media.file_name
+          ?? (typeof data.name === 'string' && data.name ? data.name : item.type);
+        if (media.kind === 'url') {
+          files.push({ name, url: media.value });
+        } else if (media.kind === 'base64') {
+          files.push({ name, base64: media.value });
+        } else if (media.kind === 'path') {
+          files.push({ name, file: media.value });
+        } else {
+          // kind=file：Discord 无平台不透明文件引用，无法投递
+          logger.warn(formatCompact({
+            op: 'discord_outbound_media_dropped',
+            type: item.type,
+            reason: 'unsupported_media_kind',
+            kind: media.kind,
+          }));
         }
         break;
       }