@zhin.js/adapter-discord 1.1.26 → 1.1.27

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @zhin.js/adapter-discord
 
+## 1.1.27
+
+### Patch Changes
+
+- ae4c8ae: fix(adapter-discord): `listChannels` 默认过滤 Discord 混淆频道（`flags` 含 `CHANNEL_OBFUSCATED` = `1 << 17`）。自 2026-11-16 起，机器人缺少 `VIEW_CHANNEL` 的频道会以 `___hidden___` 名称经 Gateway 下发，而 HTTP `GET /guilds/{id}/channels` 不再返回它们。Console 频道列表不再显示机器人无权查看的频道，与 Discord HTTP 列表一致。在 Discord 开发者后台 Overview > Bot 打开 Private Channel Obfuscation，可以让 Gateway 提前下发这些混淆频道（该开关是临时测试；HTTP 列表没有对应的提前开关）。
+
 ## 1.1.26
 
 ### Patch Changes

package/README.md

@@ -7,6 +7,7 @@ Zhin.js Discord 适配器（Plugin Runtime），默认通过 **Gateway WebSocket
 - Gateway WebSocket 入站（默认；无需公网 HTTPS / host）
 - 解析 text / mention / attachment / embed / sticker / button
 - 支持私聊、群组与服务器频道
+- `listChannels` 会过滤带 `CHANNEL_OBFUSCATED`（`1 << 17`）的混淆频道：自 2026-11-16 起，机器人缺少 `VIEW_CHANNEL` 时 Gateway 仍会下发这些频道（名字常为 `___hidden___`），HTTP 频道列表则不会返回它们。
 - 出站 `send({ conversation, payload })` → Discord channel message（Markdown content / media / embed / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Interactions HTTP webhook（需 `httpHostToken`），支持验签、PING 与 slash command

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;

package/lib/endpoint.js

@@ -1,5 +1,6 @@
 import { createDiscordSelfProfile, createDiscordRestSelfProfile } from './self-profile.js';
 import { DiscordRestRequestError } from './rest-request-error.js';
+import { isDiscordChannelObfuscated } from './channel-visibility.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
@@ -515,6 +516,7 @@ async function resolveDiscordContent(fetch, token, reference, context) {
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ * listChannels 会过滤带 CHANNEL_OBFUSCATED flag 的混淆频道（见 channel-visibility.ts）。
  */
 export function createDiscordEndpointManagement(requireClient) {
     return Object.freeze({
@@ -545,6 +547,9 @@ export function createDiscordEndpointManagement(requireClient) {
                             continue;
                         if (channel.type !== ChannelType.GuildText)
                             continue;
+                        // 机器人无 VIEW_CHANNEL 的频道会被 Gateway 混淆下发（HTTP 列表已不返回），默认过滤以保持两条路径一致。
+                        if (isDiscordChannelObfuscated(channel))
+                            continue;
                         channels.push({
                             id: String(channel.id),
                             name: channel.name ? String(channel.name) : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -36,24 +36,24 @@
     "discord.js": "^14.27.0",
     "undici": "6.29.1",
     "@zhin.js/adapter": "1.1.32",
-    "@zhin.js/agent-feature": "1.1.16",
     "@zhin.js/console-contract": "1.1.5",
-    "@zhin.js/core": "1.1.60",
     "@zhin.js/feature-kit": "1.1.15",
+    "@zhin.js/core": "1.1.60",
     "@zhin.js/host-http": "1.1.17",
     "@zhin.js/im-contract": "1.1.13",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.17",
-    "@zhin.js/permission": "1.1.15",
     "@zhin.js/skill": "1.1.16",
-    "@zhin.js/tool": "1.1.18"
+    "@zhin.js/agent-feature": "1.1.16",
+    "@zhin.js/permission": "1.1.15",
+    "@zhin.js/tool": "1.1.18",
+    "@zhin.js/page": "1.1.17"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.32",
     "@zhin.js/command": "^1.1.17",
-    "@zhin.js/core": "^1.1.60",
-    "zhin.js": "^1.1.25"
+    "zhin.js": "^1.1.25",
+    "@zhin.js/adapter": "^1.1.32",
+    "@zhin.js/core": "^1.1.60"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/src/channel-visibility.ts

@@ -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(): number {
+  return ChannelFlagsBitField.Flags.ChannelObfuscated ?? (1 << 17);
+}
+
+export const DISCORD_CHANNEL_FLAG_OBFUSCATED = obfuscatedFlagBit();
+
+type ChannelFlagsLike = number | bigint | { readonly bitfield?: number | bigint } | null | undefined;
+
+function readFlagBits(flags: ChannelFlagsLike): number {
+  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: { readonly flags?: ChannelFlagsLike } | null | undefined): boolean {
+  if (!channel) return false;
+  return (readFlagBits(channel.flags) & obfuscatedFlagBit()) !== 0;
+}

package/src/endpoint.ts

@@ -1,6 +1,7 @@
 import { createDiscordRestApiAgent } from './rest-api-proxy.js';
 import { createDiscordSelfProfile, createDiscordRestSelfProfile } from './self-profile.js';
 import { DiscordRestRequestError } from './rest-request-error.js';
+import { isDiscordChannelObfuscated } from './channel-visibility.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
@@ -606,6 +607,7 @@ async function resolveDiscordContent(
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
+ * listChannels 会过滤带 CHANNEL_OBFUSCATED flag 的混淆频道（见 channel-visibility.ts）。
  */
 export function createDiscordEndpointManagement(
   requireClient: () => DiscordClientTransport,
@@ -634,6 +636,8 @@ export function createDiscordEndpointManagement(
           for (const channel of guild.channels?.cache?.values() ?? []) {
             if (!channel?.id) continue;
             if (channel.type !== ChannelType.GuildText) continue;
+            // 机器人无 VIEW_CHANNEL 的频道会被 Gateway 混淆下发（HTTP 列表已不返回），默认过滤以保持两条路径一致。
+            if (isDiscordChannelObfuscated(channel)) continue;
             channels.push({
               id: String(channel.id),
               name: channel.name ? String(channel.name) : undefined,