@zhin.js/adapter-discord 7.0.13 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @zhin.js/adapter-discord
 
+## 8.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
+## 7.0.14
+
+### Patch Changes
+
+- 5969c5b: Remove legacy compound-string message targets and Endpoint control probing. Endpoint control and outbound Host operations now carry structured `MessageRef` identities. Endpoint send has one exact result contract (a platform message id), which IM Runtime projects into `DeliveryReceipt.message`; arbitrary result guessing is removed.
+- 9a64283: Add canonical scoped Discord message resolution with structured attachment media references.
+- 974772e: Replace the user-facing `Prompt` vocabulary with the `UserInteraction` authoring surface for input, confirmation, and selection. Commands and handlers now expose `interaction`; IM Runtime exposes `createInteraction`; schema-driven endpoint collection is named `SchemaInteraction`. The old prompt-named interaction types and properties are removed rather than aliased. User interactions render through one canonical Markdown and keyboard/list presentation module shared by commands and Agent `ask_user` turns.
+
+  Extract the transport-neutral interaction contract into `@zhin.js/interaction`. A discriminated `ask()` API supports text, number, confirmation, single-select, multi-select, and typed lists with structured `title`, `description`, and `tip` content. Typed `sequence()` interactions return one result object keyed by step id, render progress, and retry invalid replies without leaking invalid values to callers.
+
+  Preserve AI Markdown and card command actions through outbound publishing. QQ delivers Markdown with native command buttons; KOOK, Discord, Telegram, DingTalk, and Lark/Feishu now declare and encode their native Markdown dialects while retaining each adapter's interaction policy. Correct QQ callback button action encoding and button style mapping.
+
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
 ## 7.0.13
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js Discord 适配器（Plugin Runtime），默认通过 **Gateway WebSocket
 - Gateway WebSocket 入站（默认；无需公网 HTTPS / host）
 - 解析 text / mention / attachment / embed / sticker / button
 - 支持私聊、群组与服务器频道
-- 出站 `send({ conversation, payload })` → Discord channel message（text / media / embed / keyboard）
+- 出站 `send({ conversation, payload })` → Discord channel message（Markdown content / media / embed / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Interactions HTTP webhook 延期（需 `httpHostToken`）；配置 `connection: interactions` 会明确报错
 

package/adapters/discord.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/discord.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
 import { resolveDiscordConfig, } from "../lib/protocol.js";
@@ -11,15 +11,19 @@ import { discordRuntimeStateToken } from "../lib/discord-runtime-state.js";
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall'],
+    operations: (context) => context.config.connection === 'interactions'
+        ? ['recall']
+        : ['recall', 'reaction'],
     // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
     segments: {
         outboundMedia: ['url', 'upload'],
         interactive: 'native',
+        markdown: 'native',
     },
     create(context) {
         const config = resolveDiscordConfig(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
         context.use(discordRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -29,6 +33,7 @@ export default defineAdapter({
             return new DiscordInteractionsEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -36,6 +41,7 @@ export default defineAdapter({
         return new DiscordGatewayEndpoint({
             id: context.id,
             gateway,
+            sideEvents,
             config,
         });
     },

package/adapters/discord.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/discord.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   DiscordGatewayEndpoint,
@@ -27,15 +27,19 @@ export type {
 
 export default defineAdapter<DiscordAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall'],
+  operations: (context) => context.config.connection === 'interactions'
+    ? ['recall']
+    : ['recall', 'reaction'],
   // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
   segments: {
     outboundMedia: ['url', 'upload'],
     interactive: 'native',
+    markdown: 'native',
   },
   create(context) {
     const config = resolveDiscordConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
     context.use(discordRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -45,6 +49,7 @@ export default defineAdapter<DiscordAdapterConfig>({
       return new DiscordInteractionsEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -52,6 +57,7 @@ export default defineAdapter<DiscordAdapterConfig>({
     return new DiscordGatewayEndpoint({
       id: context.id,
       gateway,
+      sideEvents,
       config,
     });
   },

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
-import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { EndpointContentPort, EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { type MessageRef } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
@@ -9,13 +9,16 @@ export type { CreateDiscordClient, DiscordClientTransport, } from './gateway.js'
 export interface DiscordEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedDiscordGatewayConfig;
     readonly createClient?: CreateDiscordClient;
+    readonly fetch?: typeof globalThis.fetch;
 }
 export declare class DiscordGatewayEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
+    readonly content: EndpointContentPort;
     constructor(options: DiscordEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -51,6 +54,7 @@ export declare class DiscordGatewayEndpoint implements EndpointInstance {
 export interface DiscordInteractionsEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedDiscordInteractionsConfig;
     readonly fetch?: typeof globalThis.fetch;
@@ -58,6 +62,7 @@ export interface DiscordInteractionsEndpointOptions {
 export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     #private;
     readonly control: EndpointControl;
+    readonly content: EndpointContentPort;
     constructor(options: DiscordInteractionsEndpointOptions);
     get isOpen(): boolean;
     get config(): ResolvedDiscordInteractionsConfig;

package/lib/endpoint.js

@@ -7,6 +7,7 @@ import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
+import { receiveDiscordGuildMemberSideEvent } from './side-event-dispatch.js';
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
@@ -14,6 +15,7 @@ export class DiscordGatewayEndpoint {
     #logger;
     #options;
     #createClient;
+    #fetch;
     #client = null;
     #open = false;
     #started = false;
@@ -32,10 +34,14 @@ export class DiscordGatewayEndpoint {
             return emoji;
         },
     });
+    content = Object.freeze({
+        resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
+    });
     constructor(options) {
         this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
+        this.#fetch = options.fetch ?? globalThis.fetch;
     }
     async start() {
         if (this.#started)
@@ -50,6 +56,12 @@ export class DiscordGatewayEndpoint {
             await connectDiscordGatewayClient(this.#client, this.#options.config, {
                 onMessage: (msg) => this.admit(msg),
                 onButton: (interaction) => this.admitButton(interaction),
+                onGuildMemberAdd: (member) => {
+                    receiveDiscordGuildMemberSideEvent(this.#options.sideEvents, this.#options.config.id, 'member_increase', member, this.#logger);
+                },
+                onGuildMemberRemove: (member) => {
+                    receiveDiscordGuildMemberSideEvent(this.#options.sideEvents, this.#options.config.id, 'member_decrease', member, this.#logger);
+                },
             });
             this.#logger.info(formatCompact({
                 op: 'connect',
@@ -309,6 +321,9 @@ export class DiscordInteractionsEndpoint {
     control = Object.freeze({
         recall: (message) => this.recallMessage(message),
     });
+    content = Object.freeze({
+        resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
+    });
     constructor(options) {
         this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
@@ -408,6 +423,55 @@ export class DiscordInteractionsEndpoint {
         });
     }
 }
+async function resolveDiscordContent(fetch, token, reference, context) {
+    if (reference.kind === 'forward') {
+        return Object.freeze({ status: 'unsupported', code: 'discord_merged_forward_unavailable' });
+    }
+    if (reference.kind === 'media') {
+        return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported', code: 'discord_opaque_media_unavailable' })
+            : Object.freeze({ status: 'resolved', reference, value: reference.media });
+    }
+    try {
+        context.signal.throwIfAborted();
+        const response = await fetch(`${DISCORD_API}/channels/${reference.message.conversation.id}/messages/${reference.message.id}`, { headers: { Authorization: `Bot ${token}` }, signal: context.signal });
+        if (response.status === 404)
+            return Object.freeze({ status: 'not_found', code: 'discord_message_not_found' });
+        if (response.status === 403)
+            return Object.freeze({ status: 'forbidden', code: 'discord_message_forbidden' });
+        if (!response.ok)
+            return Object.freeze({ status: 'failed', code: 'discord_message_fetch_failed' });
+        const row = await response.json();
+        const author = row.author;
+        const attachments = Array.isArray(row.attachments) ? row.attachments : [];
+        const segments = [];
+        if (typeof row.content === 'string' && row.content.trim())
+            segments.push({ type: 'text', data: { text: row.content } });
+        for (const item of attachments.slice(0, context.maxEntries)) {
+            const attachment = item;
+            if (typeof attachment.url !== 'string')
+                continue;
+            const mime = typeof attachment.content_type === 'string' ? attachment.content_type : undefined;
+            const type = mime?.startsWith('image/') ? 'image' : mime?.startsWith('audio/') ? 'audio' : mime?.startsWith('video/') ? 'video' : 'file';
+            segments.push({ type, data: { media: { kind: 'url', value: attachment.url, ...(mime ? { mime_type: mime } : {}), ...(attachment.filename ? { file_name: String(attachment.filename) } : {}), ...(typeof attachment.size === 'number' ? { size: attachment.size } : {}) } } });
+        }
+        return Object.freeze({
+            status: 'resolved',
+            reference,
+            value: Object.freeze({
+                ref: reference.message,
+                ...(author?.id ? { actor: Object.freeze({ id: String(author.id), ...(author.global_name || author.username ? { displayName: String(author.global_name ?? author.username) } : {}) }) } : {}),
+                segments: Object.freeze(segments),
+                timestamp: typeof row.timestamp === 'string' ? Date.parse(row.timestamp) : Date.now(),
+            }),
+        });
+    }
+    catch (error) {
+        if (context.signal.aborted)
+            return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed', code: 'discord_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+    }
+}
 /**
  * Discord snowflake 是 64 位整数的字符串形式，超出 Number.MAX_SAFE_INTEGER，
  * Number() 转换会丢精度。Console 社交面只把 group_id 当 JSON 值透传、

package/lib/gateway.d.ts

@@ -129,5 +129,15 @@ export declare function toMessageCreateOptions(body: DiscordOutboundBody): Promi
 export interface DiscordGatewayConnectHandlers {
     onMessage(msg: DiscordInboundMessage): void;
     onButton(interaction: DiscordButtonInbound): void;
+    onGuildMemberAdd?(member: {
+        guildId: string;
+        userId: string;
+        userName?: string;
+    }): void;
+    onGuildMemberRemove?(member: {
+        guildId: string;
+        userId: string;
+        userName?: string;
+    }): void;
 }
 export declare function connectDiscordGatewayClient(client: DiscordClientTransport, config: ResolvedDiscordGatewayConfig, handlers: DiscordGatewayConnectHandlers): Promise<void>;

package/lib/gateway.js

@@ -224,6 +224,30 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
                 sourceMessageId: interaction.message?.id,
             });
         });
+        client.on('guildMemberAdd', (raw) => {
+            const member = raw;
+            const guildId = member.guild?.id;
+            const userId = member.user?.id;
+            if (!guildId || !userId)
+                return;
+            handlers.onGuildMemberAdd?.({
+                guildId,
+                userId,
+                userName: member.user?.username || member.user?.displayName,
+            });
+        });
+        client.on('guildMemberRemove', (raw) => {
+            const member = raw;
+            const guildId = member.guild?.id;
+            const userId = member.user?.id;
+            if (!guildId || !userId)
+                return;
+            handlers.onGuildMemberRemove?.({
+                guildId,
+                userId,
+                userName: member.user?.username || member.user?.displayName,
+            });
+        });
         client.once('clientReady', () => {
             void (async () => {
                 try {

package/lib/protocol.d.ts

@@ -138,7 +138,7 @@ export declare function senderDisplayName(msg: DiscordInboundMessage): string;
 export declare function formatInboundContent(msg: DiscordInboundMessage): string;
 export declare function formatButtonContent(interaction: DiscordButtonInbound): string;
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；引用与附件不重复编码进文本视图。
  * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
  * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
  */

package/lib/protocol.js

@@ -80,21 +80,8 @@ export function senderDisplayName(msg) {
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export function formatInboundContent(msg) {
     const parts = [];
-    if (msg.replyToId)
-        parts.push(`[reply:${msg.replyToId}]`);
     if (msg.content?.trim())
         parts.push(msg.content.trim());
-    for (const attachment of msg.attachments ?? []) {
-        const kind = attachment.contentType?.startsWith('image/')
-            ? 'image'
-            : attachment.contentType?.startsWith('audio/')
-                ? 'audio'
-                : attachment.contentType?.startsWith('video/')
-                    ? 'video'
-                    : 'file';
-        const name = attachment.name || attachment.url || 'attachment';
-        parts.push(`[${kind}: ${name}]`);
-    }
     for (const title of msg.embedTitles ?? []) {
         parts.push(`[embed: ${title}]`);
     }
@@ -102,7 +89,7 @@ export function formatInboundContent(msg) {
         parts.push(`[sticker: ${name}]`);
     }
     const text = parts.join('\n').trim();
-    return text || '(Empty message)';
+    return text;
 }
 export function formatButtonContent(interaction) {
     return `[action: ${interaction.customId}]`;
@@ -117,7 +104,7 @@ function attachmentMediaKind(contentType) {
     return 'file';
 }
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；引用与附件不重复编码进文本视图。
  * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
  * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
  */
@@ -204,6 +191,9 @@ export function formatOutboundBody(payload) {
             case 'text':
                 content += String(data.text ?? data.content ?? '');
                 break;
+            case 'markdown':
+                content += String(data.content ?? data.text ?? '');
+                break;
             case 'at':
                 content += `<@${String(data.id ?? '')}>`;
                 break;

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+export interface DiscordGuildMemberSideEvent {
+    readonly guildId: string;
+    readonly userId: string;
+    readonly userName?: string;
+}
+export declare function receiveDiscordGuildMemberSideEvent(sideEvents: SideEventGateway | undefined, configId: string, kind: 'member_increase' | 'member_decrease', event: DiscordGuildMemberSideEvent, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -0,0 +1,24 @@
+import { buildNotice, senderFromId } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+export function receiveDiscordGuildMemberSideEvent(sideEvents, configId, kind, event, logger) {
+    if (!sideEvents)
+        return;
+    void sideEvents.receiveNotice(buildNotice(event, {
+        $id: `discord:guild_member:${kind}:${event.guildId}:${event.userId}:${Date.now()}`,
+        $adapter: 'discord',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: event.guildId,
+        $scene_type: 'group',
+        $sub_type: kind,
+        $actor: senderFromId(event.userId, event.userName),
+        $timestamp: Date.now(),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'discord_side_event_failed',
+            endpoint: configId,
+            event: kind,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "7.0.13",
+  "version": "8.0.0",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,20 +33,20 @@
   },
   "dependencies": {
     "discord.js": "^14.27.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.2"
+    "@zhin.js/permission": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.11",
-    "zhin.js": "6.0.11"
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.13",
+    "zhin.js": "6.0.13"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -67,9 +67,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.11"
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/host-http": "1.0.12",
+    "zhin.js": "6.0.13"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -4,15 +4,19 @@
 import { ChannelType } from 'discord.js';
 import type {
   EndpointChannel,
+  EndpointContentPort,
+  EndpointContentResolveContext,
   EndpointControl,
   EndpointGroup,
   EndpointInstance,
   EndpointManagement,
   EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
+  type ConversationReference,
+  type ConversationResolution,
   type MessageRef,
 } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -42,6 +46,7 @@ import {
   type ResolvedDiscordInteractionsConfig,
 } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
+import { receiveDiscordGuildMemberSideEvent } from './side-event-dispatch.js';
 
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
@@ -54,8 +59,10 @@ export type {
 export interface DiscordEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedDiscordGatewayConfig;
   readonly createClient?: CreateDiscordClient;
+  readonly fetch?: typeof globalThis.fetch;
 }
 
 export class DiscordGatewayEndpoint implements EndpointInstance {
@@ -63,6 +70,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
 
   readonly #options: DiscordEndpointOptions;
   readonly #createClient: CreateDiscordClient;
+  readonly #fetch: typeof globalThis.fetch;
   #client: DiscordClientTransport | null = null;
   #open = false;
   #started = false;
@@ -84,11 +92,16 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
       return emoji;
     },
   });
+  readonly content: EndpointContentPort = Object.freeze({
+    resolve: (reference: ConversationReference, context: EndpointContentResolveContext) =>
+      resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
+  });
 
   constructor(options: DiscordEndpointOptions) {
     this.#logger = getAdapterLogger('discord', options.config.id);
     this.#options = options;
     this.#createClient = options.createClient ?? defaultCreateClient;
+    this.#fetch = options.fetch ?? globalThis.fetch;
   }
 
   async start(): Promise<void> {
@@ -103,6 +116,24 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
       await connectDiscordGatewayClient(this.#client, this.#options.config, {
         onMessage: (msg) => this.admit(msg),
         onButton: (interaction) => this.admitButton(interaction),
+        onGuildMemberAdd: (member) => {
+          receiveDiscordGuildMemberSideEvent(
+            this.#options.sideEvents,
+            this.#options.config.id,
+            'member_increase',
+            member,
+            this.#logger,
+          );
+        },
+        onGuildMemberRemove: (member) => {
+          receiveDiscordGuildMemberSideEvent(
+            this.#options.sideEvents,
+            this.#options.config.id,
+            'member_decrease',
+            member,
+            this.#logger,
+          );
+        },
       });
       this.#logger.info(formatCompact({
         op: 'connect',
@@ -405,6 +436,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
 export interface DiscordInteractionsEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedDiscordInteractionsConfig;
   readonly fetch?: typeof globalThis.fetch;
@@ -421,6 +453,10 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
   readonly control: EndpointControl = Object.freeze({
     recall: (message: MessageRef) => this.recallMessage(message),
   });
+  readonly content: EndpointContentPort = Object.freeze({
+    resolve: (reference: ConversationReference, context: EndpointContentResolveContext) =>
+      resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
+  });
 
   constructor(options: DiscordInteractionsEndpointOptions) {
     this.#logger = getAdapterLogger('discord', options.config.id);
@@ -527,6 +563,57 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
   }
 }
 
+async function resolveDiscordContent(
+  fetch: typeof globalThis.fetch,
+  token: string,
+  reference: ConversationReference,
+  context: EndpointContentResolveContext,
+): Promise<ConversationResolution> {
+  if (reference.kind === 'forward') {
+    return Object.freeze({ status: 'unsupported', code: 'discord_merged_forward_unavailable' });
+  }
+  if (reference.kind === 'media') {
+    return reference.media.kind === 'file'
+      ? Object.freeze({ status: 'unsupported', code: 'discord_opaque_media_unavailable' })
+      : Object.freeze({ status: 'resolved', reference, value: reference.media });
+  }
+  try {
+    context.signal.throwIfAborted();
+    const response = await fetch(
+      `${DISCORD_API}/channels/${reference.message.conversation.id}/messages/${reference.message.id}`,
+      { headers: { Authorization: `Bot ${token}` }, signal: context.signal },
+    );
+    if (response.status === 404) return Object.freeze({ status: 'not_found', code: 'discord_message_not_found' });
+    if (response.status === 403) return Object.freeze({ status: 'forbidden', code: 'discord_message_forbidden' });
+    if (!response.ok) return Object.freeze({ status: 'failed', code: 'discord_message_fetch_failed' });
+    const row = await response.json() as Record<string, unknown>;
+    const author = row.author as Record<string, unknown> | undefined;
+    const attachments = Array.isArray(row.attachments) ? row.attachments : [];
+    const segments: import('@zhin.js/im-contract').Segment[] = [];
+    if (typeof row.content === 'string' && row.content.trim()) segments.push({ type: 'text', data: { text: row.content } });
+    for (const item of attachments.slice(0, context.maxEntries)) {
+      const attachment = item as Record<string, unknown>;
+      if (typeof attachment.url !== 'string') continue;
+      const mime = typeof attachment.content_type === 'string' ? attachment.content_type : undefined;
+      const type = mime?.startsWith('image/') ? 'image' : mime?.startsWith('audio/') ? 'audio' : mime?.startsWith('video/') ? 'video' : 'file';
+      segments.push({ type, data: { media: { kind: 'url', value: attachment.url, ...(mime ? { mime_type: mime } : {}), ...(attachment.filename ? { file_name: String(attachment.filename) } : {}), ...(typeof attachment.size === 'number' ? { size: attachment.size } : {}) } } });
+    }
+    return Object.freeze({
+      status: 'resolved',
+      reference,
+      value: Object.freeze({
+        ref: reference.message,
+        ...(author?.id ? { actor: Object.freeze({ id: String(author.id), ...(author.global_name || author.username ? { displayName: String(author.global_name ?? author.username) } : {}) }) } : {}),
+        segments: Object.freeze(segments),
+        timestamp: typeof row.timestamp === 'string' ? Date.parse(row.timestamp) : Date.now(),
+      }),
+    });
+  } catch (error) {
+    if (context.signal.aborted) return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+    return Object.freeze({ status: 'failed', code: 'discord_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+  }
+}
+
 /**
  * Discord snowflake 是 64 位整数的字符串形式，超出 Number.MAX_SAFE_INTEGER，
  * Number() 转换会丢精度。Console 社交面只把 group_id 当 JSON 值透传、

package/src/gateway.ts

@@ -287,6 +287,8 @@ function decodeBase64(value: string): Buffer {
 export interface DiscordGatewayConnectHandlers {
   onMessage(msg: DiscordInboundMessage): void;
   onButton(interaction: DiscordButtonInbound): void;
+  onGuildMemberAdd?(member: { guildId: string; userId: string; userName?: string }): void;
+  onGuildMemberRemove?(member: { guildId: string; userId: string; userName?: string }): void;
 }
 
 export async function connectDiscordGatewayClient(
@@ -331,6 +333,36 @@ export async function connectDiscordGatewayClient(
       });
     });
 
+    client.on('guildMemberAdd', (raw) => {
+      const member = raw as {
+        guild?: { id?: string };
+        user?: { id?: string; username?: string; displayName?: string };
+      };
+      const guildId = member.guild?.id;
+      const userId = member.user?.id;
+      if (!guildId || !userId) return;
+      handlers.onGuildMemberAdd?.({
+        guildId,
+        userId,
+        userName: member.user?.username || member.user?.displayName,
+      });
+    });
+
+    client.on('guildMemberRemove', (raw) => {
+      const member = raw as {
+        guild?: { id?: string };
+        user?: { id?: string; username?: string; displayName?: string };
+      };
+      const guildId = member.guild?.id;
+      const userId = member.user?.id;
+      if (!guildId || !userId) return;
+      handlers.onGuildMemberRemove?.({
+        guildId,
+        userId,
+        userName: member.user?.username || member.user?.displayName,
+      });
+    });
+
     client.once('clientReady', () => {
       void (async () => {
         try {

package/src/protocol.ts

@@ -230,19 +230,7 @@ export function senderDisplayName(msg: DiscordInboundMessage): string {
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export function formatInboundContent(msg: DiscordInboundMessage): string {
   const parts: string[] = [];
-  if (msg.replyToId) parts.push(`[reply:${msg.replyToId}]`);
   if (msg.content?.trim()) parts.push(msg.content.trim());
-  for (const attachment of msg.attachments ?? []) {
-    const kind = attachment.contentType?.startsWith('image/')
-      ? 'image'
-      : attachment.contentType?.startsWith('audio/')
-        ? 'audio'
-        : attachment.contentType?.startsWith('video/')
-          ? 'video'
-          : 'file';
-    const name = attachment.name || attachment.url || 'attachment';
-    parts.push(`[${kind}: ${name}]`);
-  }
   for (const title of msg.embedTitles ?? []) {
     parts.push(`[embed: ${title}]`);
   }
@@ -250,7 +238,7 @@ export function formatInboundContent(msg: DiscordInboundMessage): string {
     parts.push(`[sticker: ${name}]`);
   }
   const text = parts.join('\n').trim();
-  return text || '(Empty message)';
+  return text;
 }
 
 export function formatButtonContent(interaction: DiscordButtonInbound): string {
@@ -265,7 +253,7 @@ function attachmentMediaKind(contentType: string | undefined): 'image' | 'audio'
 }
 
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；引用与附件不重复编码进文本视图。
  * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
  * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
  */
@@ -356,6 +344,9 @@ export function formatOutboundBody(payload: unknown): DiscordOutboundBody {
       case 'text':
         content += String(data.text ?? data.content ?? '');
         break;
+      case 'markdown':
+        content += String(data.content ?? data.text ?? '');
+        break;
       case 'at':
         content += `<@${String(data.id ?? '')}>`;
         break;

package/src/side-event-dispatch.ts

@@ -0,0 +1,37 @@
+import { buildNotice, senderFromId } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+
+export interface DiscordGuildMemberSideEvent {
+  readonly guildId: string;
+  readonly userId: string;
+  readonly userName?: string;
+}
+
+export function receiveDiscordGuildMemberSideEvent(
+  sideEvents: SideEventGateway | undefined,
+  configId: string,
+  kind: 'member_increase' | 'member_decrease',
+  event: DiscordGuildMemberSideEvent,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!sideEvents) return;
+  void sideEvents.receiveNotice(buildNotice(event, {
+    $id: `discord:guild_member:${kind}:${event.guildId}:${event.userId}:${Date.now()}`,
+    $adapter: 'discord' as never,
+    $endpoint: configId,
+    $type: 'notice',
+    $scene_id: event.guildId,
+    $scene_type: 'group',
+    $sub_type: kind,
+    $actor: senderFromId(event.userId, event.userName),
+    $timestamp: Date.now(),
+  })).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'discord_side_event_failed',
+      endpoint: configId,
+      event: kind,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}