@zhin.js/adapter-discord 1.1.26 → 1.1.28

package/agents/discord/skills/discord/tools/send_embed/index.js

@@ -1,12 +1,11 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentConversation } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
 export default defineAgentTool({
-    description: '发送 Discord 富文本嵌入消息（Embed）',
+    description: '在当前 Discord 频道（或线程）发送富文本嵌入消息（Embed）',
     inputSchema: z.object({
-        channel_id: z.string().describe('频道 ID'),
         title: z.string().optional().describe('Embed 标题'),
         description: z.string().optional().describe('Embed 描述'),
         color: z.number().optional().describe('颜色值（十进制，如 0x00ff00 = 65280）'),
@@ -15,8 +14,7 @@ export default defineAgentTool({
     }),
     adapter: 'discord',
     tags: ['discord'],
-    async execute({ channel_id, title, description, color, url, fields }, context) {
-        const client = requireDiscordGatewayClient(context.$client);
+    async execute({ title, description, color, url, fields }, context) {
         const embedData = {};
         if (title)
             embedData.title = title;
@@ -34,11 +32,8 @@ export default defineAgentTool({
                 return { success: false, message: t(context.locale, 'invalidFields') };
             }
         }
-        const channel = await client.channels.fetch(channel_id);
-        if (!channel?.isSendable()) {
-            throw new Error(t(context.locale, 'notTextChannel', { p0: channel_id }));
-        }
-        const msg = await channel.send({ embeds: [embedData] });
-        return { success: true, message_id: msg.id, message: t(context.locale, 'embedSent') };
+        // `discord:embed` is the Discord adapter's namespaced outbound segment (rendered by formatOutboundBody).
+        const result = await sendToCurrentConversation(context, { type: 'discord:embed', data: embedData });
+        return { ...result, message: t(context.locale, result.success ? 'embedSent' : 'operationFailed') };
     },
 });

package/agents/discord/skills/discord/tools/send_embed/index.ts

@@ -1,12 +1,11 @@
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentConversation } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
 
-export default defineAgentTool<{ channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }>({
-  description: '发送 Discord 富文本嵌入消息（Embed）',
+export default defineAgentTool<{ title?: string; description?: string; color?: number; url?: string; fields?: string }>({
+  description: '在当前 Discord 频道（或线程）发送富文本嵌入消息（Embed）',
   inputSchema: z.object({
-    channel_id: z.string().describe('频道 ID'),
     title: z.string().optional().describe('Embed 标题'),
     description: z.string().optional().describe('Embed 描述'),
     color: z.number().optional().describe('颜色值（十进制，如 0x00ff00 = 65280）'),
@@ -15,8 +14,7 @@ export default defineAgentTool<{ channel_id: string; title?: string; description
   }),
   adapter: 'discord',
   tags: ['discord'],
-  async execute({ channel_id, title, description, color, url, fields  }: { channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }, context) {
-    const client = requireDiscordGatewayClient(context.$client);
+  async execute({ title, description, color, url, fields }, context) {
     const embedData: Record<string, unknown> = {};
     if (title) embedData.title = title;
     if (description) embedData.description = description;
@@ -29,11 +27,8 @@ export default defineAgentTool<{ channel_id: string; title?: string; description
         return { success: false, message: t(context.locale, 'invalidFields') };
       }
     }
-    const channel = await client.channels.fetch(channel_id);
-    if (!channel?.isSendable()) {
-      throw new Error(t(context.locale, 'notTextChannel', { p0: channel_id }));
-    }
-    const msg = await channel.send({ embeds: [embedData] } as never);
-    return { success: true, message_id: msg.id, message: t(context.locale, 'embedSent') };
+    // `discord:embed` is the Discord adapter's namespaced outbound segment (rendered by formatOutboundBody).
+    const result = await sendToCurrentConversation(context, { type: 'discord:embed', data: embedData });
+    return { ...result, message: t(context.locale, result.success ? 'embedSent' : 'operationFailed') };
   },
 });

package/agents/discord/skills/discord-guild/tools/add_role/index.js

@@ -1,26 +1,28 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '给成员添加 Discord 角色',
+    description: '给当前 Discord 服务器的成员添加身份组（只能是低于你最高身份组的身份组）',
     inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
         user_id: z.string().describe('用户 ID'),
-        role_id: z.string().describe('角色 ID'),
+        role_id: z.string().describe('身份组 ID'),
     }),
     adapter: 'discord',
     scopes: ["channel"],
     tags: ['discord'],
-    permissions: [platformPermission('discord', 'manage_roles')],
-    async execute({ guild_id, user_id, role_id }, context) {
+    permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+    async execute({ user_id, role_id }, context) {
+        const { guildId } = currentGuildChannel(context);
         const client = requireDiscordGatewayClient(context.$client);
-        const guild = await client.guilds.fetch(guild_id);
+        const guild = await client.guilds.fetch(guildId);
+        const denied = await requireRoleBelowRequester(context, guild, role_id);
+        if (denied)
+            return { success: false, message: denied };
         const member = await guild.members.fetch(user_id);
         await member.roles.add(role_id);
-        const success = true;
-        return { success, message: success ? t(context.locale, 'memberRoleAdded', { p0: user_id }) : t(context.locale, 'operationFailed') };
+        return { success: true, message: t(context.locale, 'memberRoleAdded', { p0: user_id }) };
     },
 });

package/agents/discord/skills/discord-guild/tools/add_role/index.ts

@@ -1,28 +1,29 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
-  description: '给成员添加 Discord 角色',
+export default defineAgentTool<{ user_id: string; role_id: string }>({
+  description: '给当前 Discord 服务器的成员添加身份组（只能是低于你最高身份组的身份组）',
   inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
-    role_id: z.string().describe('角色 ID'),
+    role_id: z.string().describe('身份组 ID'),
   }),
   adapter: 'discord',
   scopes: ["channel"],
   tags: ['discord'],
-  permissions: [platformPermission('discord', 'manage_roles')],
-  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+  permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+  async execute({ user_id, role_id }, context) {
+    const { guildId } = currentGuildChannel(context);
     const client = requireDiscordGatewayClient(context.$client);
-    const guild = await client.guilds.fetch(guild_id);
+    const guild = await client.guilds.fetch(guildId);
+    const denied = await requireRoleBelowRequester(context, guild, role_id);
+    if (denied) return { success: false, message: denied };
     const member = await guild.members.fetch(user_id) as {
       roles: { add(id: string): Promise<unknown> };
     };
     await member.roles.add(role_id);
-    const success = true;
-    return { success, message: success ? t(context.locale, 'memberRoleAdded', { p0: user_id }) : t(context.locale, 'operationFailed') };
+    return { success: true, message: t(context.locale, 'memberRoleAdded', { p0: user_id }) };
   },
 });

package/agents/discord/skills/discord-guild/tools/create_thread/index.js

@@ -1,14 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 import { ThreadAutoArchiveDuration } from 'discord.js';
 export default defineAgentTool({
-    description: '在 Discord 频道中创建帖子/子线程',
+    description: '在当前 Discord 频道中创建帖子/子线程',
     inputSchema: z.object({
-        channel_id: z.string().describe('频道 ID'),
         name: z.string().describe('帖子标题'),
         message_id: z.string().optional().describe('基于某条消息创建（可选）'),
         auto_archive_duration: z.number().optional().describe('自动归档时间（分钟：60/1440/4320/10080）'),
@@ -16,8 +15,9 @@ export default defineAgentTool({
     adapter: 'discord',
     scopes: ["channel"],
     tags: ['discord'],
-    permissions: [platformPermission('discord', 'manage_channels')],
-    async execute({ channel_id, name, message_id, auto_archive_duration }, context) {
+    permissions: ['platform-permission:manage_channels', 'bot-permission:create_public_threads'],
+    async execute({ name, message_id, auto_archive_duration }, context) {
+        const { channelId: channel_id } = currentGuildChannel(context);
         const client = requireDiscordGatewayClient(context.$client);
         const channel = await client.channels.fetch(channel_id);
         if (!channel || !('threads' in channel) || channel.isThreadOnly())

package/agents/discord/skills/discord-guild/tools/create_thread/index.ts

@@ -1,14 +1,13 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 import { ThreadAutoArchiveDuration } from 'discord.js';
 
-export default defineAgentTool<{ channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }>({
-  description: '在 Discord 频道中创建帖子/子线程',
+export default defineAgentTool<{ name: string; message_id?: string; auto_archive_duration?: number }>({
+  description: '在当前 Discord 频道中创建帖子/子线程',
   inputSchema: z.object({
-    channel_id: z.string().describe('频道 ID'),
     name: z.string().describe('帖子标题'),
     message_id: z.string().optional().describe('基于某条消息创建（可选）'),
     auto_archive_duration: z.number().optional().describe('自动归档时间（分钟：60/1440/4320/10080）'),
@@ -16,8 +15,9 @@ export default defineAgentTool<{ channel_id: string; name: string; message_id?:
   adapter: 'discord',
   scopes: ["channel"],
   tags: ['discord'],
-  permissions: [platformPermission('discord', 'manage_channels')],
-  async execute({ channel_id, name, message_id, auto_archive_duration  }: { channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }, context) {
+  permissions: ['platform-permission:manage_channels', 'bot-permission:create_public_threads'],
+  async execute({ name, message_id, auto_archive_duration }, context) {
+    const { channelId: channel_id } = currentGuildChannel(context);
     const client = requireDiscordGatewayClient(context.$client);
     const channel = await client.channels.fetch(channel_id);
     if (!channel || !('threads' in channel) || channel.isThreadOnly()) throw new Error(t(context.locale, 'threadsUnsupported', { p0: channel_id }));

package/agents/discord/skills/discord-guild/tools/forum_post/index.js

@@ -1,13 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChannel } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
 import { ChannelType } from 'discord.js';
 export default defineAgentTool({
-    description: '在 Discord 论坛频道中创建帖子',
+    description: '在当前 Discord 论坛频道中创建帖子（需在该论坛的帖子里发起）',
     inputSchema: z.object({
-        channel_id: z.string().describe('论坛频道 ID'),
         name: z.string().describe('帖子标题'),
         content: z.string().describe('帖子内容'),
         tags: z.string().optional().describe('标签名，逗号分隔（可选）'),
@@ -15,7 +15,11 @@ export default defineAgentTool({
     adapter: 'discord',
     scopes: ["channel"],
     tags: ['discord'],
-    async execute({ channel_id, name, content, tags }, context) {
+    async execute({ name, content, tags }, context) {
+        // A forum post reports the forum as its conversation id and the post as `threadId`.
+        const { conversationChannelId: channel_id, guildId } = currentChannel(context);
+        if (!guildId)
+            throw new Error(t(context.locale, 'guildChannelRequired'));
         const client = requireDiscordGatewayClient(context.$client);
         const tagList = tags ? tags.split(',').map((t) => t.trim()) : undefined;
         const channel = await client.channels.fetch(channel_id);

package/agents/discord/skills/discord-guild/tools/forum_post/index.ts

@@ -1,13 +1,13 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChannel } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
 import { ChannelType } from 'discord.js';
 
-export default defineAgentTool<{ channel_id: string; name: string; content: string; tags?: string }>({
-  description: '在 Discord 论坛频道中创建帖子',
+export default defineAgentTool<{ name: string; content: string; tags?: string }>({
+  description: '在当前 Discord 论坛频道中创建帖子（需在该论坛的帖子里发起）',
   inputSchema: z.object({
-    channel_id: z.string().describe('论坛频道 ID'),
     name: z.string().describe('帖子标题'),
     content: z.string().describe('帖子内容'),
     tags: z.string().optional().describe('标签名，逗号分隔（可选）'),
@@ -15,7 +15,10 @@ export default defineAgentTool<{ channel_id: string; name: string; content: stri
   adapter: 'discord',
   scopes: ["channel"],
   tags: ['discord'],
-  async execute({ channel_id, name, content, tags  }: { channel_id: string; name: string; content: string; tags?: string }, context) {
+  async execute({ name, content, tags }, context) {
+    // A forum post reports the forum as its conversation id and the post as `threadId`.
+    const { conversationChannelId: channel_id, guildId } = currentChannel(context);
+    if (!guildId) throw new Error(t(context.locale, 'guildChannelRequired'));
     const client = requireDiscordGatewayClient(context.$client);
     const tagList = tags ? tags.split(',').map((t: string) => t.trim()) : undefined;
     const channel = await client.channels.fetch(channel_id);

package/agents/discord/skills/discord-guild/tools/list_roles/index.js

@@ -1,20 +1,19 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { currentGuildChannel } from '../../../../conversation.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '获取 Discord 服务器角色列表',
-    inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
-    }),
+    description: '获取当前 Discord 服务器的身份组列表',
+    inputSchema: z.object({}),
     adapter: 'discord',
     scopes: ["channel"],
     tags: ['discord'],
-    permissions: [platformPermission('discord', 'manage_roles')],
-    async execute({ guild_id }, context) {
+    permissions: ['platform-permission:manage_roles'],
+    async execute(_args, context) {
+        const { guildId } = currentGuildChannel(context);
         const client = requireDiscordGatewayClient(context.$client);
-        const guild = await client.guilds.fetch(guild_id);
+        const guild = await client.guilds.fetch(guildId);
         await guild.roles.fetch();
         const cache = guild.roles.cache;
         const roles = [...cache.values()].map((role) => ({

package/agents/discord/skills/discord-guild/tools/list_roles/index.ts

@@ -1,20 +1,19 @@
+import { currentGuildChannel } from '../../../../conversation.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string }>({
-  description: '获取 Discord 服务器角色列表',
-  inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
-  }),
+export default defineAgentTool<Record<string, never>>({
+  description: '获取当前 Discord 服务器的身份组列表',
+  inputSchema: z.object({}),
   adapter: 'discord',
   scopes: ["channel"],
   tags: ['discord'],
-  permissions: [platformPermission('discord', 'manage_roles')],
-  async execute({ guild_id  }: { guild_id: string }, context) {
+  permissions: ['platform-permission:manage_roles'],
+  async execute(_args, context) {
+    const { guildId } = currentGuildChannel(context);
     const client = requireDiscordGatewayClient(context.$client);
-    const guild = await client.guilds.fetch(guild_id);
+    const guild = await client.guilds.fetch(guildId);
     await guild.roles.fetch();
     const cache = guild.roles.cache as Map<string, {
       id: string;

package/agents/discord/skills/discord-guild/tools/remove_role/index.js

@@ -1,26 +1,28 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '移除成员的 Discord 角色',
+    description: '移除当前 Discord 服务器成员的身份组（只能是低于你最高身份组的身份组）',
     inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
         user_id: z.string().describe('用户 ID'),
-        role_id: z.string().describe('角色 ID'),
+        role_id: z.string().describe('身份组 ID'),
     }),
     adapter: 'discord',
     scopes: ["channel"],
     tags: ['discord'],
-    permissions: [platformPermission('discord', 'manage_roles')],
-    async execute({ guild_id, user_id, role_id }, context) {
+    permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+    async execute({ user_id, role_id }, context) {
+        const { guildId } = currentGuildChannel(context);
         const client = requireDiscordGatewayClient(context.$client);
-        const guild = await client.guilds.fetch(guild_id);
+        const guild = await client.guilds.fetch(guildId);
+        const denied = await requireRoleBelowRequester(context, guild, role_id);
+        if (denied)
+            return { success: false, message: denied };
         const member = await guild.members.fetch(user_id);
         await member.roles.remove(role_id);
-        const success = true;
-        return { success, message: success ? t(context.locale, 'memberRoleRemoved', { p0: user_id }) : t(context.locale, 'operationFailed') };
+        return { success: true, message: t(context.locale, 'memberRoleRemoved', { p0: user_id }) };
     },
 });

package/agents/discord/skills/discord-guild/tools/remove_role/index.ts

@@ -1,28 +1,29 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuildChannel, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
-  description: '移除成员的 Discord 角色',
+export default defineAgentTool<{ user_id: string; role_id: string }>({
+  description: '移除当前 Discord 服务器成员的身份组（只能是低于你最高身份组的身份组）',
   inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
-    role_id: z.string().describe('角色 ID'),
+    role_id: z.string().describe('身份组 ID'),
   }),
   adapter: 'discord',
   scopes: ["channel"],
   tags: ['discord'],
-  permissions: [platformPermission('discord', 'manage_roles')],
-  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+  permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+  async execute({ user_id, role_id }, context) {
+    const { guildId } = currentGuildChannel(context);
     const client = requireDiscordGatewayClient(context.$client);
-    const guild = await client.guilds.fetch(guild_id);
+    const guild = await client.guilds.fetch(guildId);
+    const denied = await requireRoleBelowRequester(context, guild, role_id);
+    if (denied) return { success: false, message: denied };
     const member = await guild.members.fetch(user_id) as {
       roles: { remove(id: string): Promise<unknown> };
     };
     await member.roles.remove(role_id);
-    const success = true;
-    return { success, message: success ? t(context.locale, 'memberRoleRemoved', { p0: user_id }) : t(context.locale, 'operationFailed') };
+    return { success: true, message: t(context.locale, 'memberRoleRemoved', { p0: user_id }) };
   },
 });

package/lib/channel-visibility.d.ts

@@ -0,0 +1,9 @@
+export declare const DISCORD_CHANNEL_FLAG_OBFUSCATED: number;
+type ChannelFlagsLike = number | bigint | {
+    readonly bitfield?: number | bigint;
+} | null | undefined;
+/** 频道是否被 Discord 混淆（机器人无 `VIEW_CHANNEL`）。兼容 discord.js 的 `ChannelFlagsBitField` 与原始 `flags` 数值。 */
+export declare function isDiscordChannelObfuscated(channel: {
+    readonly flags?: ChannelFlagsLike;
+} | null | undefined): boolean;
+export {};

package/lib/channel-visibility.js

@@ -0,0 +1,44 @@
+import { ChannelFlagsBitField } from 'discord.js';
+/**
+ * Discord 频道混淆（Channel Obfuscation）判定。
+ *
+ * 自 2026-11-16 起，Gateway 会继续下发机器人缺少 `VIEW_CHANNEL` 的频道，但其元数据被混淆：
+ * `name` 变为 `"___hidden___"`，并在 `flags` 上置 `CHANNEL_OBFUSCATED`；HTTP 的
+ * `GET /guilds/{guild.id}/channels` 则直接不返回这些频道。
+ *
+ * 出处：
+ * - https://docs.discord.com/developers/resources/channel#channel-object-channel-flags
+ *   （Channel Flags 表：`CHANNEL_OBFUSCATED` = `1 << 17`）
+ * - https://docs.discord.com/developers/resources/channel#channel-object-obfuscated-channels
+ * - https://docs.discord.com/developers/change-log （2026-08-12 "Channel Obfuscation for Users and Bots"）
+ * - discord-api-types `ChannelFlags.ChannelObfuscated`（0.38.54 起，值为 `131072`）。
+ *   discord.js 14.27.0 把它声明为 dependencies `^0.38.49`，并通过
+ *   `ChannelFlagsBitField.Flags` 暴露同一枚举。0.38.49–0.38.53 上该枚举是 `undefined`，
+ *   因此这里用 `?? (1 << 17)` 兜底，避免过滤悄悄失效。
+ *
+ * 官方要求以 flag 判定，不要依赖 `name` 等被混淆字段。
+ */
+function obfuscatedFlagBit() {
+    return ChannelFlagsBitField.Flags.ChannelObfuscated ?? (1 << 17);
+}
+export const DISCORD_CHANNEL_FLAG_OBFUSCATED = obfuscatedFlagBit();
+function readFlagBits(flags) {
+    if (flags == null)
+        return 0;
+    if (typeof flags === 'number')
+        return flags;
+    if (typeof flags === 'bigint')
+        return Number(flags & 0xffffffffn);
+    const bitfield = flags.bitfield;
+    if (typeof bitfield === 'number')
+        return bitfield;
+    if (typeof bitfield === 'bigint')
+        return Number(bitfield & 0xffffffffn);
+    return 0;
+}
+/** 频道是否被 Discord 混淆（机器人无 `VIEW_CHANNEL`）。兼容 discord.js 的 `ChannelFlagsBitField` 与原始 `flags` 数值。 */
+export function isDiscordChannelObfuscated(channel) {
+    if (!channel)
+        return false;
+    return (readFlagBits(channel.flags) & obfuscatedFlagBit()) !== 0;
+}

package/lib/endpoint.d.ts

@@ -74,5 +74,6 @@ export declare class DiscordInteractionsEndpoint extends DiscordRestClient imple
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ * listChannels 会过滤带 CHANNEL_OBFUSCATED flag 的混淆频道（见 channel-visibility.ts）。
  */
 export declare function createDiscordEndpointManagement(requireClient: () => DiscordClientTransport): EndpointManagement;