@zhin.js/adapter-discord 5.0.3 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @zhin.js/adapter-discord
 
+## 6.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 6.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 5.0.3
 
 ### Patch Changes

package/README.md

@@ -42,7 +42,7 @@ pnpm add @zhin.js/adapter-discord discord.js
 | **Gateway（默认）** | 本地/生产均可；discord.js 连接 Gateway，无需公网 HTTPS |
 | **host-http** | Gateway **不需要**；Interactions webhook 延期至下一棒 |
 
-必填字段：`token`。
+必填字段（`endpoints[i]`）：`name`、`token`。
 
 ## 最小配置
 
@@ -50,9 +50,10 @@ pnpm add @zhin.js/adapter-discord discord.js
 # zhin.config.yml（Plugin Runtime）
 plugins:
   discord:
-    name: my-discord-bot
-    token: ${DISCORD_BOT_TOKEN}
     # connection: gateway   # 默认
+    endpoints:
+      - name: my-discord-bot
+        token: ${DISCORD_BOT_TOKEN}
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-discord`（`instanceKey: discord`）。

package/adapters/discord.ts

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

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.remove;

package/lib/discord-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const discordEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/discord-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `discord endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * 注：applicationId / publicKey 为顶层共享字段（slash commands / interactions 用），
+ * endpoints[i] 仅需 name + token（见 schema.json），故 add 只录入 token。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { discordRuntimeStateToken } from './discord-runtime-state.js';
+export const discordEndpointCommands = createEndpointCommands({
+    adapterKey: 'discord',
+    adapterDisplayName: 'Discord',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Discord bot token' },
+    ],
+    running: (use) => use(discordRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/lib/discord-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const discordRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/discord-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 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,8 +1,8 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } 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';
-import { type CreateDiscordClient } from './gateway.js';
+import { type CreateDiscordClient, type DiscordClientTransport } from './gateway.js';
 import { type DiscordButtonInbound, type DiscordInboundMessage, type ResolvedDiscordGatewayConfig, type ResolvedDiscordInteractionsConfig } from './protocol.js';
 export type { CreateDiscordClient, DiscordClientTransport, } from './gateway.js';
 export interface DiscordEndpointOptions {
@@ -13,6 +13,7 @@ export interface DiscordEndpointOptions {
 }
 export declare class DiscordGatewayEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: DiscordEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -69,3 +70,11 @@ export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     }): Promise<string>;
     admit(msg: DiscordInboundMessage): void;
 }
+/**
+ * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
+ * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ */
+export declare function createDiscordEndpointManagement(endpoint: {
+    getClient(): DiscordClientTransport;
+    getMembers(guildId: string): Promise<unknown[]>;
+}): EndpointManagement;

package/lib/endpoint.js

@@ -5,9 +5,11 @@ import { ChannelType } from 'discord.js';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
-import { formatButtonContent, formatInboundContent, formatOutboundBody, senderDisplayName, } from './protocol.js';
+import { formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
 const DISCORD_API = 'https://discord.com/api/v10';
+/** 出站 HTTP 调用统一 30s 超时。 */
+const OUTBOUND_TIMEOUT_MS = 30_000;
 const logger = getLogger('discord');
 export class DiscordGatewayEndpoint {
     #options;
@@ -16,7 +18,10 @@ export class DiscordGatewayEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
-    #messageChannelMap = new Map();
+    management = createDiscordEndpointManagement({
+        getClient: () => this.#requireClient(),
+        getMembers: (guildId) => this.getMembers(guildId),
+    });
     constructor(options) {
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
@@ -74,7 +79,6 @@ export class DiscordGatewayEndpoint {
     async send({ target, payload }) {
         const body = formatOutboundBody(payload);
         const messageId = await this.#sendBody(target, body);
-        this.#messageChannelMap.set(messageId, target);
         logger.debug(formatCompact({
             op: 'discord_send',
             endpoint: this.#options.config.name,
@@ -89,11 +93,11 @@ export class DiscordGatewayEndpoint {
             return;
         if (msg.authorBot)
             return;
-        this.#messageChannelMap.set(msg.id, msg.channelId);
         void this.#options.gateway.receive({
             adapter: this.#options.id,
             target: msg.channelId,
             content: formatInboundContent(msg),
+            segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg),
             id: msg.id,
             metadata: Object.freeze({
@@ -121,6 +125,7 @@ export class DiscordGatewayEndpoint {
             adapter: this.#options.id,
             target: interaction.channelId,
             content: formatButtonContent(interaction),
+            segments: formatButtonSegments(interaction),
             sender: interaction.userName,
             id: interaction.id,
             metadata: Object.freeze({
@@ -320,6 +325,7 @@ export class DiscordInteractionsEndpoint {
                 'Content-Type': 'application/json',
             },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
         });
         const text = await response.text();
         if (!response.ok) {
@@ -335,6 +341,7 @@ export class DiscordInteractionsEndpoint {
             adapter: this.#options.id,
             target: msg.channelId,
             content: formatInboundContent(msg),
+            segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg),
             id: msg.id,
             metadata: Object.freeze({
@@ -353,3 +360,56 @@ export class DiscordInteractionsEndpoint {
         });
     }
 }
+/**
+ * Discord snowflake 是 64 位整数的字符串形式，超出 Number.MAX_SAFE_INTEGER，
+ * Number() 转换会丢精度。Console 社交面只把 group_id 当 JSON 值透传、
+ * 并以字符串回传给 listGroupMembers，因此这里保留原始字符串（仅按契约
+ * 类型声明强转），是全链路最不丢信息的方案。
+ */
+function toGroupId(id) {
+    return id;
+}
+/**
+ * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
+ * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ */
+export function createDiscordEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listGroups() {
+            const groups = [];
+            for (const guild of endpoint.getClient().guilds.cache.values()) {
+                if (!guild?.id)
+                    continue;
+                groups.push({
+                    group_id: toGroupId(String(guild.id)),
+                    name: String(guild.name ?? guild.id),
+                });
+            }
+            return groups;
+        },
+        async listChannels() {
+            const channels = [];
+            for (const guild of endpoint.getClient().guilds.cache.values()) {
+                if (!guild?.id)
+                    continue;
+                const guildId = String(guild.id);
+                const guildName = String(guild.name ?? guildId);
+                for (const channel of guild.channels?.cache?.values() ?? []) {
+                    if (!channel?.id)
+                        continue;
+                    if (channel.type !== ChannelType.GuildText)
+                        continue;
+                    channels.push({
+                        id: String(channel.id),
+                        name: channel.name ? String(channel.name) : undefined,
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+        async listGroupMembers(groupId) {
+            return endpoint.getMembers(groupId);
+        },
+    });
+}

package/lib/gateway.d.ts

@@ -106,6 +106,16 @@ export interface DiscordClientTransport {
         cache: {
             values(): IterableIterator<{
                 id: string;
+                name: string;
+                channels: {
+                    cache: {
+                        values(): IterableIterator<{
+                            id: string;
+                            name?: string;
+                            type: number;
+                        }>;
+                    };
+                };
             }>;
         };
     };

package/lib/gateway.js

@@ -140,7 +140,7 @@ export async function toMessageCreateOptions(body) {
     }
     return options;
 }
-async function registerSlashCommands(config, applicationId) {
+async function registerSlashCommands(config, applicationId, guildIds = []) {
     if (!config.slashCommands?.length)
         return;
     const rest = new REST({ version: '10' }).setToken(config.token);
@@ -149,7 +149,23 @@ async function registerSlashCommands(config, applicationId) {
             body: config.slashCommands,
         });
         logger.info(formatCompact({ op: 'slash_commands', scope: 'global' }));
+        return;
+    }
+    // globalCommands=false 时按 guild 注册，否则 enableSlashCommands 会是静默 no-op
+    if (guildIds.length === 0) {
+        logger.warn(formatCompact({
+            op: 'slash_commands',
+            ok: false,
+            error: 'enableSlashCommands=true but globalCommands=false and no guilds cached; slash commands not registered',
+        }));
+        return;
     }
+    for (const guildId of guildIds) {
+        await rest.put(Routes.applicationGuildCommands(applicationId, guildId), {
+            body: config.slashCommands,
+        });
+    }
+    logger.info(formatCompact({ op: 'slash_commands', scope: 'guild', guilds: guildIds.length }));
 }
 async function fileExists(filePath) {
     try {
@@ -200,7 +216,8 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
                         });
                     }
                     if (config.enableSlashCommands && config.slashCommands?.length && client.user) {
-                        await registerSlashCommands(config, client.user.id);
+                        const guildIds = [...client.guilds.cache.values()].map((guild) => guild.id);
+                        await registerSlashCommands(config, client.user.id, guildIds);
                     }
                     if (!settled) {
                         settled = true;
@@ -228,7 +245,11 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
         client.login(config.token).catch((error) => {
             if (!settled) {
                 settled = true;
-                reject(error instanceof Error ? error : new Error(String(error)));
+                const raw = error instanceof Error ? error.message : String(error);
+                const tokenShapeHint = config.token.split('.').length === 3
+                    ? ''
+                    : '；当前 token 不是标准三段式 Bot Token 格式，请到 Discord Developer Portal → Bot → Reset Token 重新获取（勿用 Client Secret）';
+                reject(new Error(`Discord 连接失败：请检查 token 是否为 Bot Token 且未过期、Bot 是否已开启所需 Intents${tokenShapeHint}（原始错误：${raw}）`, { cause: error instanceof Error ? error : undefined }));
             }
         });
     });

package/lib/platform-permit.js

@@ -38,7 +38,7 @@ export function checkDiscordPlatformPermit(perm, message) {
         case 'guild_owner':
             return role === 'owner' || has('guild_owner');
         case 'moderate_members':
-            return role === 'owner' || has('ADMINISTRATOR') || has('MODERATE_MEMBERS');
+            return role === 'owner' || role === 'admin' || has('ADMINISTRATOR') || has('MODERATE_MEMBERS');
         case 'manage_roles':
             return role === 'owner' || has('ADMINISTRATOR') || has('MANAGE_ROLES');
         case 'manage_channels':

package/lib/protocol.d.ts

@@ -2,6 +2,7 @@
  * Discord Gateway protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import type { Segment } from '@zhin.js/core/runtime';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DiscordAdapterConfig {
     readonly name?: string;
@@ -124,12 +125,26 @@ export declare function senderDisplayName(msg: DiscordInboundMessage): string;
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: DiscordInboundMessage): string;
 export declare function formatButtonContent(interaction: DiscordButtonInbound): string;
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
+ * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
+ */
+export declare function formatInboundSegments(msg: DiscordInboundMessage): Segment[];
+/**
+ * button interaction → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatButtonContent / metadata.payload 同源。
+ */
+export declare function formatButtonSegments(interaction: DiscordButtonInbound): Segment[];
 /**
  * Wire-encode an already-rendered outbound payload into Discord message body.
  * Segment canonicalization is intentionally not done here.
  */
 export declare function formatOutboundBody(payload: unknown): DiscordOutboundBody;
 export declare function activityTypeCode(type: NonNullable<DiscordAdapterConfig['defaultActivity']>['type']): number;
-export declare function verifyDiscordInteractionSignature(publicKeyHex: string, body: string, signature: string, timestamp: string): boolean;
+/** interactions 验签时间戳时效窗口（防重放）。 */
+export declare const DISCORD_SIGNATURE_MAX_AGE_MS: number;
+export declare function verifyDiscordInteractionSignature(publicKeyHex: string, body: string, signature: string, timestamp: string, nowMs?: number): boolean;
 export declare function formatSlashCommandContent(interaction: Record<string, unknown>): string;
 export declare function interactionToInboundMessage(interaction: Record<string, unknown>): DiscordInboundMessage;

package/lib/protocol.js

@@ -89,6 +89,67 @@ export function formatInboundContent(msg) {
 export function formatButtonContent(interaction) {
     return `[action: ${interaction.customId}]`;
 }
+function attachmentMediaKind(contentType) {
+    if (contentType?.startsWith('image/'))
+        return 'image';
+    if (contentType?.startsWith('audio/'))
+        return 'audio';
+    if (contentType?.startsWith('video/'))
+        return 'video';
+    return 'file';
+}
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
+ * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
+ */
+export function formatInboundSegments(msg) {
+    const out = [];
+    if (msg.replyToId) {
+        out.push({ type: 'reply', data: { message_id: msg.replyToId } });
+    }
+    const text = msg.content?.trim();
+    if (text)
+        out.push({ type: 'text', data: { text } });
+    for (const attachment of msg.attachments ?? []) {
+        if (!attachment.url)
+            continue;
+        const kind = attachmentMediaKind(attachment.contentType);
+        out.push({
+            type: kind,
+            data: {
+                media: {
+                    kind: 'url',
+                    value: attachment.url,
+                    ...(attachment.contentType ? { mime_type: attachment.contentType } : {}),
+                },
+                ...(attachment.name
+                    ? kind === 'image'
+                        ? { alt: attachment.name }
+                        : { name: attachment.name }
+                    : {}),
+            },
+        });
+    }
+    return out;
+}
+/**
+ * button interaction → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatButtonContent / metadata.payload 同源。
+ */
+export function formatButtonSegments(interaction) {
+    return [{
+            type: 'action',
+            data: {
+                id: interaction.id,
+                payload: interaction.customId,
+                ...(interaction.sourceMessageId
+                    ? { sourceMessageId: interaction.sourceMessageId }
+                    : {}),
+            },
+        }];
+}
 /**
  * Wire-encode an already-rendered outbound payload into Discord message body.
  * Segment canonicalization is intentionally not done here.
@@ -192,10 +253,17 @@ export function activityTypeCode(type) {
     };
     return map[type] ?? 0;
 }
-export function verifyDiscordInteractionSignature(publicKeyHex, body, signature, timestamp) {
+/** interactions 验签时间戳时效窗口（防重放）。 */
+export const DISCORD_SIGNATURE_MAX_AGE_MS = 5 * 60_000;
+export function verifyDiscordInteractionSignature(publicKeyHex, body, signature, timestamp, nowMs = Date.now()) {
     if (!publicKeyHex || !signature || !timestamp)
         return false;
     try {
+        // 时效窗口 ±5min，超出直接拒绝（timestamp 为秒）
+        const ts = Number(timestamp);
+        if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > DISCORD_SIGNATURE_MAX_AGE_MS) {
+            return false;
+        }
         const key = createPublicKey({
             key: Buffer.concat([
                 Buffer.from('302a300506032b6570032100', 'hex'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "5.0.3",
+  "version": "6.0.1",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,19 +33,20 @@
   },
   "dependencies": {
     "discord.js": "^14.26.4",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -63,12 +64,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/host-http": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -94,6 +96,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerDiscordPlatformPermitChecker } from './src/platform-permit.js';
+import { discordRuntimeStateToken } from './src/discord-runtime-state.js';
 
 export default definePlugin({
   name: 'discord',
   metadata: {
     displayName: 'Discord Gateway Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（discord endpoint list 的"运行中"数据源）
+    context.resources.provide(discordRuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：guild_owner / moderate_members 等（agent 工具 platformPermit）
     return registerDiscordPlatformPermitChecker();
   },

package/schema.json

@@ -3,22 +3,20 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "discord-bot"
-    },
-    "token": {
-      "type": "string"
-    },
     "connection": {
       "type": "string",
-      "enum": ["gateway", "interactions"],
+      "enum": [
+        "gateway",
+        "interactions"
+      ],
       "default": "gateway",
       "description": "Gateway WebSocket (default). interactions uses httpHostToken POST + Ed25519 verify."
     },
     "intents": {
       "type": "array",
-      "items": { "type": "number" }
+      "items": {
+        "type": "number"
+      }
     },
     "enableSlashCommands": {
       "type": "boolean",
@@ -32,18 +30,33 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "name": { "type": "string" },
+        "name": {
+          "type": "string"
+        },
         "type": {
           "type": "string",
-          "enum": ["PLAYING", "STREAMING", "LISTENING", "WATCHING", "COMPETING"]
+          "enum": [
+            "PLAYING",
+            "STREAMING",
+            "LISTENING",
+            "WATCHING",
+            "COMPETING"
+          ]
         },
-        "url": { "type": "string" }
+        "url": {
+          "type": "string"
+        }
       },
-      "required": ["name", "type"]
+      "required": [
+        "name",
+        "type"
+      ]
     },
     "slashCommands": {
       "type": "array",
-      "items": { "type": "object" }
+      "items": {
+        "type": "object"
+      }
     },
     "applicationId": {
       "type": "string",
@@ -57,7 +70,36 @@
       "type": "string",
       "default": "/discord/interactions",
       "description": "POST path on httpHostToken when connection is interactions."
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Discord bot name"
+          },
+          "token": {
+            "type": "string",
+            "description": "Discord bot token"
+          }
+        },
+        "required": [
+          "name",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["token"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/discord-endpoint-commands.ts

@@ -0,0 +1,19 @@
+/**
+ * `discord endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * 注：applicationId / publicKey 为顶层共享字段（slash commands / interactions 用），
+ * endpoints[i] 仅需 name + token（见 schema.json），故 add 只录入 token。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { discordRuntimeStateToken } from './discord-runtime-state.js';
+
+export const discordEndpointCommands = createEndpointCommands({
+  adapterKey: 'discord',
+  adapterDisplayName: 'Discord',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'Discord bot token' },
+  ],
+  running: (use) => use(discordRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/src/discord-runtime-state.ts

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

package/src/endpoint.ts

@@ -2,7 +2,12 @@
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type {
+  EndpointChannel,
+  EndpointGroup,
+  EndpointInstance,
+  EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -19,7 +24,9 @@ import {
 } from './gateway.js';
 import {
   formatButtonContent,
+  formatButtonSegments,
   formatInboundContent,
+  formatInboundSegments,
   formatOutboundBody,
   senderDisplayName,
   type DiscordButtonInbound,
@@ -31,6 +38,8 @@ import {
 import { registerDiscordInteractionRoutes } from './webhook.js';
 
 const DISCORD_API = 'https://discord.com/api/v10';
+/** 出站 HTTP 调用统一 30s 超时。 */
+const OUTBOUND_TIMEOUT_MS = 30_000;
 const logger = getLogger('discord');
 
 export type {
@@ -52,7 +61,10 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
-  readonly #messageChannelMap = new Map<string, string>();
+  readonly management: EndpointManagement = createDiscordEndpointManagement({
+    getClient: () => this.#requireClient(),
+    getMembers: (guildId) => this.getMembers(guildId),
+  });
 
   constructor(options: DiscordEndpointOptions) {
     this.#options = options;
@@ -113,7 +125,6 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
     const body = formatOutboundBody(payload);
     const messageId = await this.#sendBody(target, body);
-    this.#messageChannelMap.set(messageId, target);
     logger.debug(formatCompact({
       op: 'discord_send',
       endpoint: this.#options.config.name,
@@ -127,11 +138,11 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   admit(msg: DiscordInboundMessage): void {
     if (!this.#open) return;
     if (msg.authorBot) return;
-    this.#messageChannelMap.set(msg.id, msg.channelId);
     void this.#options.gateway.receive({
       adapter: this.#options.id,
       target: msg.channelId,
       content: formatInboundContent(msg),
+      segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg),
       id: msg.id,
       metadata: Object.freeze({
@@ -159,6 +170,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target: interaction.channelId,
       content: formatButtonContent(interaction),
+      segments: formatButtonSegments(interaction),
       sender: interaction.userName,
       id: interaction.id,
       metadata: Object.freeze({
@@ -422,6 +434,7 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
         'Content-Type': 'application/json',
       },
       body: JSON.stringify(body),
+      signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
     });
     const text = await response.text();
     if (!response.ok) {
@@ -437,6 +450,7 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target: msg.channelId,
       content: formatInboundContent(msg),
+      segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg),
       id: msg.id,
       metadata: Object.freeze({
@@ -455,3 +469,57 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     });
   }
 }
+
+/**
+ * Discord snowflake 是 64 位整数的字符串形式，超出 Number.MAX_SAFE_INTEGER，
+ * Number() 转换会丢精度。Console 社交面只把 group_id 当 JSON 值透传、
+ * 并以字符串回传给 listGroupMembers，因此这里保留原始字符串（仅按契约
+ * 类型声明强转），是全链路最不丢信息的方案。
+ */
+function toGroupId(id: string): number {
+  return id as unknown as number;
+}
+
+/**
+ * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
+ * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ */
+export function createDiscordEndpointManagement(endpoint: {
+  getClient(): DiscordClientTransport;
+  getMembers(guildId: string): Promise<unknown[]>;
+}): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const groups: EndpointGroup[] = [];
+      for (const guild of endpoint.getClient().guilds.cache.values()) {
+        if (!guild?.id) continue;
+        groups.push({
+          group_id: toGroupId(String(guild.id)),
+          name: String(guild.name ?? guild.id),
+        });
+      }
+      return groups;
+    },
+    async listChannels(): Promise<readonly EndpointChannel[]> {
+      const channels: EndpointChannel[] = [];
+      for (const guild of endpoint.getClient().guilds.cache.values()) {
+        if (!guild?.id) continue;
+        const guildId = String(guild.id);
+        const guildName = String(guild.name ?? guildId);
+        for (const channel of guild.channels?.cache?.values() ?? []) {
+          if (!channel?.id) continue;
+          if (channel.type !== ChannelType.GuildText) continue;
+          channels.push({
+            id: String(channel.id),
+            name: channel.name ? String(channel.name) : undefined,
+            parent: { type: 'guild', id: guildId, name: guildName },
+          });
+        }
+      }
+      return channels;
+    },
+    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
+      return endpoint.getMembers(groupId);
+    },
+  });
+}

package/src/gateway.ts

@@ -98,7 +98,13 @@ export interface DiscordClientTransport {
         unban(userId: string, reason?: string): Promise<unknown>;
       };
     }>;
-    cache: { values(): IterableIterator<{ id: string }> };
+    cache: { values(): IterableIterator<{
+      id: string;
+      name: string;
+      channels: {
+        cache: { values(): IterableIterator<{ id: string; name?: string; type: number }> };
+      };
+    }> };
   };
 }
 
@@ -223,6 +229,7 @@ export async function toMessageCreateOptions(body: DiscordOutboundBody): Promise
 async function registerSlashCommands(
   config: ResolvedDiscordGatewayConfig,
   applicationId: string,
+  guildIds: readonly string[] = [],
 ): Promise<void> {
   if (!config.slashCommands?.length) return;
   const rest = new REST({ version: '10' }).setToken(config.token);
@@ -231,7 +238,23 @@ async function registerSlashCommands(
       body: config.slashCommands,
     });
     logger.info(formatCompact({ op: 'slash_commands', scope: 'global' }));
+    return;
+  }
+  // globalCommands=false 时按 guild 注册，否则 enableSlashCommands 会是静默 no-op
+  if (guildIds.length === 0) {
+    logger.warn(formatCompact({
+      op: 'slash_commands',
+      ok: false,
+      error: 'enableSlashCommands=true but globalCommands=false and no guilds cached; slash commands not registered',
+    }));
+    return;
   }
+  for (const guildId of guildIds) {
+    await rest.put(Routes.applicationGuildCommands(applicationId, guildId), {
+      body: config.slashCommands,
+    });
+  }
+  logger.info(formatCompact({ op: 'slash_commands', scope: 'guild', guilds: guildIds.length }));
 }
 
 async function fileExists(filePath: string): Promise<boolean> {
@@ -300,7 +323,8 @@ export async function connectDiscordGatewayClient(
             });
           }
           if (config.enableSlashCommands && config.slashCommands?.length && client.user) {
-            await registerSlashCommands(config, client.user.id);
+            const guildIds = [...client.guilds.cache.values()].map((guild) => guild.id);
+            await registerSlashCommands(config, client.user.id, guildIds);
           }
           if (!settled) {
             settled = true;
@@ -330,7 +354,16 @@ export async function connectDiscordGatewayClient(
     client.login(config.token).catch((error) => {
       if (!settled) {
         settled = true;
-        reject(error instanceof Error ? error : new Error(String(error)));
+        const raw = error instanceof Error ? error.message : String(error);
+        const tokenShapeHint = config.token.split('.').length === 3
+          ? ''
+          : '；当前 token 不是标准三段式 Bot Token 格式，请到 Discord Developer Portal → Bot → Reset Token 重新获取（勿用 Client Secret）';
+        reject(
+          new Error(
+            `Discord 连接失败：请检查 token 是否为 Bot Token 且未过期、Bot 是否已开启所需 Intents${tokenShapeHint}（原始错误：${raw}）`,
+            { cause: error instanceof Error ? error : undefined },
+          ),
+        );
       }
     });
   });

package/src/platform-permit.ts

@@ -49,7 +49,7 @@ export function checkDiscordPlatformPermit(perm: string, message: Message<any>):
     case 'guild_owner':
       return role === 'owner' || has('guild_owner');
     case 'moderate_members':
-      return role === 'owner' || has('ADMINISTRATOR') || has('MODERATE_MEMBERS');
+      return role === 'owner' || role === 'admin' || has('ADMINISTRATOR') || has('MODERATE_MEMBERS');
     case 'manage_roles':
       return role === 'owner' || has('ADMINISTRATOR') || has('MANAGE_ROLES');
     case 'manage_channels':

package/src/protocol.ts

@@ -4,6 +4,7 @@
  */
 
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import type { Segment } from '@zhin.js/core/runtime';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DiscordAdapterConfig {
@@ -227,6 +228,65 @@ export function formatButtonContent(interaction: DiscordButtonInbound): string {
   return `[action: ${interaction.customId}]`;
 }
 
+function attachmentMediaKind(contentType: string | undefined): 'image' | 'audio' | 'video' | 'file' {
+  if (contentType?.startsWith('image/')) return 'image';
+  if (contentType?.startsWith('audio/')) return 'audio';
+  if (contentType?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 附件 url 是 Discord CDN 真实 http(s) 地址，MediaRef kind=url；
+ * embeds / stickers 仅留在纯文本视图，不进段（最小侵入）。
+ */
+export function formatInboundSegments(msg: DiscordInboundMessage): Segment[] {
+  const out: Segment[] = [];
+  if (msg.replyToId) {
+    out.push({ type: 'reply', data: { message_id: msg.replyToId } });
+  }
+  const text = msg.content?.trim();
+  if (text) out.push({ type: 'text', data: { text } });
+  for (const attachment of msg.attachments ?? []) {
+    if (!attachment.url) continue;
+    const kind = attachmentMediaKind(attachment.contentType);
+    out.push({
+      type: kind,
+      data: {
+        media: {
+          kind: 'url',
+          value: attachment.url,
+          ...(attachment.contentType ? { mime_type: attachment.contentType } : {}),
+        },
+        ...(attachment.name
+          ? kind === 'image'
+            ? { alt: attachment.name }
+            : { name: attachment.name }
+          : {}),
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * button interaction → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatButtonContent / metadata.payload 同源。
+ */
+export function formatButtonSegments(interaction: DiscordButtonInbound): Segment[] {
+  return [{
+    type: 'action',
+    data: {
+      id: interaction.id,
+      payload: interaction.customId,
+      ...(interaction.sourceMessageId
+        ? { sourceMessageId: interaction.sourceMessageId }
+        : {}),
+    },
+  }];
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Discord message body.
  * Segment canonicalization is intentionally not done here.
@@ -342,14 +402,23 @@ export function activityTypeCode(
   return map[type] ?? 0;
 }
 
+/** interactions 验签时间戳时效窗口（防重放）。 */
+export const DISCORD_SIGNATURE_MAX_AGE_MS = 5 * 60_000;
+
 export function verifyDiscordInteractionSignature(
   publicKeyHex: string,
   body: string,
   signature: string,
   timestamp: string,
+  nowMs: number = Date.now(),
 ): boolean {
   if (!publicKeyHex || !signature || !timestamp) return false;
   try {
+    // 时效窗口 ±5min，超出直接拒绝（timestamp 为秒）
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > DISCORD_SIGNATURE_MAX_AGE_MS) {
+      return false;
+    }
     const key = createPublicKey({
       key: Buffer.concat([
         Buffer.from('302a300506032b6570032100', 'hex'),