@zhin.js/adapter-kook 1.1.25 → 1.1.27

package/src/console-spec.ts

@@ -7,19 +7,154 @@ export const kookConsoleSpec = {
   adapterKey: 'kook',
   adapterDisplayName: 'KOOK',
   fields: [
-    { key: 'token', required: true, env: true, description: 'KOOK bot token' },
-    { key: 'encrypt_key', env: true, description: 'webhook 加密密钥（connection: webhook）', descriptionI18n: { en: 'Webhook encryption secret' } },
-    { key: 'verify_token', env: true, description: 'webhook 验证 token（connection: webhook）', descriptionI18n: { en: 'Webhook verification token' } },
-    { key: 'connection', description: 'websocket or webhook' },
-    { key: 'webhookPath', description: 'Local webhook route' },
-    { key: 'data_dir', description: 'SDK data directory' },
-    { key: 'timeout', type: 'number', description: 'SDK request timeout' },
-    { key: 'max_retry', type: 'number', description: 'SDK configured retry count' },
-    { key: 'ignore', description: 'SDK inbound ignore setting: bot or self' },
-    { key: 'logLevel', description: 'SDK log level' },
-    { key: 'apiProxy.port', type: 'number', description: 'Configured API loopback proxy port' },
-    { key: 'streamProxy.port', type: 'number', description: 'Configured Gateway loopback proxy port' },
-    { key: 'streamProxy.serverName', description: 'Expected Gateway TLS hostname' },
+    {
+      key: 'token',
+      required: true,
+      env: true,
+      label: 'Bot Token (机器人令牌)',
+      labelI18n: { en: 'Bot Token' },
+      group: '基础认证',
+      groupI18n: { en: 'Basic Auth' },
+      placeholder: '1/MTIzNDU=/...',
+      description: 'KOOK 开发者中心获取的 Bot Token',
+      descriptionI18n: { en: 'KOOK bot token' },
+    },
+    {
+      key: 'connection',
+      label: '连接模式',
+      labelI18n: { en: 'Connection Mode' },
+      group: '连接与回调',
+      groupI18n: { en: 'Connection & Webhook' },
+      placeholder: 'websocket',
+      description: 'websocket（默认长连接）或 webhook',
+      descriptionI18n: { en: 'websocket or webhook' },
+      options: [
+        { value: 'websocket', label: 'WebSocket 长连接（推荐）', labelI18n: { en: 'WebSocket (Recommended)' } },
+        { value: 'webhook', label: 'Webhook 回调', labelI18n: { en: 'Webhook' } },
+      ],
+    },
+    {
+      key: 'encrypt_key',
+      env: true,
+      label: 'Webhook Encrypt Key',
+      labelI18n: { en: 'Webhook Encrypt Key' },
+      group: '连接与回调',
+      groupI18n: { en: 'Connection & Webhook' },
+      placeholder: 'Webhook 模式下的 Encrypt Key',
+      placeholderI18n: { en: 'Encrypt key for webhook mode' },
+      description: 'webhook 加密密钥（connection: webhook）',
+      descriptionI18n: { en: 'Webhook encryption secret' },
+    },
+    {
+      key: 'verify_token',
+      env: true,
+      label: 'Webhook Verify Token',
+      labelI18n: { en: 'Webhook Verify Token' },
+      group: '连接与回调',
+      groupI18n: { en: 'Connection & Webhook' },
+      placeholder: 'Webhook 模式下的 Verify Token',
+      placeholderI18n: { en: 'Verify token for webhook mode' },
+      description: 'webhook 验证 token（connection: webhook）',
+      descriptionI18n: { en: 'Webhook verification token' },
+    },
+    {
+      key: 'webhookPath',
+      label: 'Webhook 本地路由',
+      labelI18n: { en: 'Webhook Local Path' },
+      group: '连接与回调',
+      groupI18n: { en: 'Connection & Webhook' },
+      placeholder: '/kook/webhook',
+      description: '本地监听的 Webhook 路径',
+      descriptionI18n: { en: 'Local webhook route' },
+    },
+    {
+      key: 'ignore',
+      label: '消息忽略策略',
+      labelI18n: { en: 'Ignore Policy' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: 'bot',
+      description: '忽略消息来源：bot（所有机器人）或 self（仅自身）',
+      descriptionI18n: { en: 'SDK inbound ignore setting: bot or self' },
+      options: [
+        { value: 'bot', label: '忽略所有机器人 (bot)', labelI18n: { en: 'Ignore all bots (bot)' } },
+        { value: 'self', label: '仅忽略自身 (self)', labelI18n: { en: 'Ignore self only (self)' } },
+      ],
+    },
+    {
+      key: 'timeout',
+      type: 'number',
+      label: '请求超时 (ms)',
+      labelI18n: { en: 'Request Timeout (ms)' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: '10000',
+      description: 'API 请求超时时间（毫秒）',
+      descriptionI18n: { en: 'SDK request timeout' },
+    },
+    {
+      key: 'max_retry',
+      type: 'number',
+      label: '最大重试次数',
+      labelI18n: { en: 'Max Retries' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: '3',
+      description: 'SDK 请求失败最大重试次数',
+      descriptionI18n: { en: 'SDK configured retry count' },
+    },
+    {
+      key: 'data_dir',
+      label: 'SDK 数据目录',
+      labelI18n: { en: 'SDK Data Directory' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: './data/kook',
+      description: 'KOOK SDK 本地缓存目录（可选）',
+      descriptionI18n: { en: 'SDK data directory' },
+    },
+    {
+      key: 'logLevel',
+      label: 'SDK 日志级别',
+      labelI18n: { en: 'SDK Log Level' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: 'info',
+      description: 'KOOK SDK 日志级别（info / warn / error / debug）',
+      descriptionI18n: { en: 'SDK log level' },
+    },
+    {
+      key: 'apiProxy.port',
+      type: 'number',
+      label: 'API 代理端口',
+      labelI18n: { en: 'API Proxy Port' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: '例如 7890',
+      description: '本地回环 API 代理端口（可选）',
+      descriptionI18n: { en: 'Configured API loopback proxy port' },
+    },
+    {
+      key: 'streamProxy.port',
+      type: 'number',
+      label: '网关代理端口',
+      labelI18n: { en: 'Gateway Proxy Port' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: '例如 7890',
+      description: '本地回环 Gateway 代理端口（可选）',
+      descriptionI18n: { en: 'Configured Gateway loopback proxy port' },
+    },
+    {
+      key: 'streamProxy.serverName',
+      label: '网关 TLS 主机名',
+      labelI18n: { en: 'Gateway TLS Server Name' },
+      group: '流式体验与代理',
+      groupI18n: { en: 'Streaming & Proxy' },
+      placeholder: 'gateway.kookapp.cn',
+      description: '代理校验的 Gateway TLS 主机名（可选）',
+      descriptionI18n: { en: 'Expected Gateway TLS hostname' },
+    },
   ] as readonly AdapterConsoleField[],
   docsUrl: 'https://zhin.js.org/adapters/kook',
   readPermission: 'kook:read',

package/src/endpoint.ts

@@ -1,4 +1,4 @@
-import { EndpointDeliveryError, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, type ConversationRef, type PlatformStanding, type SelfStandingRequest } from '@zhin.js/im-contract';
 /**
  * KookEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
@@ -40,7 +40,7 @@ import {
   type KookClientTransport,
 } from './ws.js';
 import { recallKookMessage, sendKookOutbound } from './outbound.js';
-import { KookSenderRoleResolver, type KookSenderRoleProjection } from './sender-roles.js';
+import { KookSenderRoleResolver } from './sender-roles.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
 import { createKookSelfProfile } from './self-profile.js';
 
@@ -49,12 +49,12 @@ export interface KookEndpointOptions {
   readonly config: ResolvedKookWebsocketConfig;
 }
 
-/** 入站 message.receive 载荷：规范角色 owner/admin 进 roles，原始角色 id 进 permissions。 */
+/** 入站 message.receive 载荷：发送者平台身份进 `sender.platform`（ADR 0056 §1）。 */
 function kookInboundPayload(
   endpointId: string,
   conversation: ConversationRef,
   msg: KookInboundMessage,
-  projection: KookSenderRoleProjection,
+  platform: PlatformStanding | undefined,
   selfId: string | undefined,
 ) {
   return {
@@ -66,8 +66,7 @@ function kookInboundPayload(
     sender: {
       id: msg.authorId,
       name: senderDisplayName(msg) || undefined,
-      ...(projection.role ? { roles: [projection.role] } : {}),
-      ...(projection.permissions.length ? { permissions: [...projection.permissions] } : {}),
+      ...(platform ? { platform } : {}),
     },
     endpointId,
     ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
@@ -76,7 +75,6 @@ function kookInboundPayload(
       userId: msg.authorId,
       guildId: msg.guildId,
       authorRoleIds: msg.authorRoles,
-      ...(projection.role ? { senderRole: projection.role } : {}),
     }),
   };
 }
@@ -91,7 +89,7 @@ export class KookWebsocketEndpoint extends RuntimeKookClient implements Endpoint
   #open = false;
   #executionSignal?: AbortSignal;
   #started = false;
-  readonly #management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
+  readonly #management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient(), this.#roles);
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
     recall: request => recallKookMessage(this.#requireClient(), request),
   });
@@ -172,10 +170,10 @@ export class KookWebsocketEndpoint extends RuntimeKookClient implements Endpoint
       if (msg.authorBot) return;
       const conversation = kookInboundConversation(String(this.#options.id), msg);
       const selfId = this.self_id != null ? String(this.self_id) : undefined;
-      return this.#roles.resolve(msg).then((projection) => {
+      return this.#roles.resolve(msg).then((platform) => {
         this.#executionSignal?.throwIfAborted();
         return this[endpointSpec].events.emit('message.receive',
-          kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+          kookInboundPayload(this.#options.config.id, conversation, msg, platform, selfId));
       }).catch((err) => {
         this.#logger.warn(formatCompact({
           op: 'kook_gateway_receive_failed',
@@ -255,7 +253,7 @@ export class KookWebhookEndpoint extends RuntimeKookClient implements Endpoint {
   #open = false;
   #executionSignal?: AbortSignal;
   #started = false;
-  readonly #management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
+  readonly #management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient(), this.#roles);
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
     recall: request => recallKookMessage(this.#requireClient(), request),
   });
@@ -374,10 +372,10 @@ export class KookWebhookEndpoint extends RuntimeKookClient implements Endpoint {
       if (msg.authorBot) return;
       const conversation = kookInboundConversation(String(this.#options.id), msg);
       const selfId = this.self_id != null ? String(this.self_id) : undefined;
-      return this.#roles.resolve(msg).then((projection) => {
+      return this.#roles.resolve(msg).then((platform) => {
         this.#executionSignal?.throwIfAborted();
         return this[endpointSpec].events.emit('message.receive',
-          kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+          kookInboundPayload(this.#options.config.id, conversation, msg, platform, selfId));
       }).catch((err) => {
         this.#logger.warn(formatCompact({
           op: 'kook_gateway_receive_failed',
@@ -438,8 +436,24 @@ function isKookTextChannelType(type: string | number | undefined): boolean {
  */
 export function createKookEndpointManagement(
   requireClient: () => KookClientTransport,
+  roles: KookSenderRoleResolver = new KookSenderRoleResolver(requireClient),
 ): EndpointManagement {
   return Object.freeze<EndpointManagement>({
+    /**
+     * ADR 0056 §1: the Bot's own standing in the channel's guild (`/v3/user/view` self → its role
+     * ids, then the same guild owner / role-permission resolution as senders).
+     */
+    async inspectSelfStanding({ conversation, signal }: SelfStandingRequest): Promise<PlatformStanding | undefined> {
+      const guildId = conversation.kind === 'channel' ? conversation.parent?.id : undefined;
+      if (!guildId) return undefined;
+      const operation = createEndpointOperation({ signal });
+      const client = requireClient();
+      const selfId = client.self_id != null ? String(client.self_id) : undefined;
+      if (!selfId) return undefined;
+      const { data } = await operation.run(() => client.request.get('/v3/user/view', { params: { user_id: selfId, guild_id: guildId } }));
+      const held = Array.isArray((data as { roles?: unknown })?.roles) ? (data as { roles: unknown[] }).roles.map(Number).filter(Number.isFinite) : [];
+      return roles.resolve({ guildId, authorId: selfId, authorRoles: held });
+    },
     async listGroups(request: EndpointManagementRequest = {}): Promise<readonly EndpointGroup[]> {
       const operation = createEndpointOperation(request);
       const guilds = await operation.run(() => requireClient().getGuildList());

package/src/index.ts

@@ -36,10 +36,4 @@ export {
 export { type KookClientEventMap } from './client.js';
 export { KookAdapter } from './adapter.js';
 
-export {
-  checkKookPlatformPermit,
-  kookGroupPermitResolver,
-  normalizeKookSenderForPermit,
-  platformPermit,
-  type KookSenderInfo,
-} from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,75 +1,10 @@
 /**
- * KOOK platform permit — guild / channel 差异化门禁
+ * KOOK platform permit helper（ADR 0056 §5）。
+ *
+ * 平台身份由适配器上报到 `sender.platform`（见 `sender-roles.ts`），permit 由内置评估器
+ * （`@zhin.js/permission`）判断；适配器不再导出自有的 permit 解析器或检查函数。
  */
-import type { PermissionSubject } from '@zhin.js/permission';
-import { KookPermission } from './protocol.js';
-
-const ADAPTER = 'kook';
 
 export function platformPermit(perm: string): string {
-  return `platform(${ADAPTER},${perm})`;
-}
-
-const FACTORY_PERM_MAP: Record<string, string> = {
-  scene_admin: 'guild_admin',
-  scene_owner: 'guild_owner',
-};
-
-export function kookGroupPermitResolver(logicalPerm: string): string {
-  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+  return `platform-permission:${perm}`;
 }
-
-export interface KookSenderInfo {
-  id: string;
-  name: string;
-  permission?: KookPermission;
-  roles?: number[];
-  isGuildOwner?: boolean;
-  isAdmin?: boolean;
-  role?: string;
-  permissions?: string[];
-}
-
-export function normalizeKookSenderForPermit(
-  info: KookSenderInfo,
-  isChannel: boolean,
-): { role?: string; permissions?: string[] } {
-  const permissions: string[] = [];
-  if (info.roles?.length) {
-    permissions.push(...info.roles.map((r) => `role:${r}`));
-  }
-
-  if (info.isGuildOwner || info.permission === KookPermission.Owner) {
-    permissions.push('guild_owner', 'guild_admin');
-    return { role: 'owner', permissions };
-  }
-  if (info.permission === KookPermission.ChannelAdmin && isChannel) {
-    permissions.push('channel_admin', 'guild_admin');
-    return { role: 'channel_admin', permissions };
-  }
-  if (info.isAdmin || info.permission === KookPermission.Admin) {
-    permissions.push('guild_admin');
-    return { role: 'admin', permissions };
-  }
-  return { role: 'member', permissions };
-}
-
-export function checkKookPlatformPermit(perm: string, subject: PermissionSubject): boolean {
-  const role = subject.sender?.role?.[0];
-  const permissions = subject.sender?.permissions ?? [];
-  const has = (t: string) => permissions.includes(t);
-
-  switch (perm) {
-    case 'guild_owner':
-      return role === 'owner' || has('guild_owner');
-    case 'guild_admin':
-      return role === 'owner' || role === 'admin' || role === 'channel_admin' || has('guild_admin') || has('channel_admin');
-    case 'channel_admin':
-      return role === 'owner' || role === 'admin' || role === 'channel_admin' || has('channel_admin') || has('guild_admin');
-    case 'manage_roles':
-      return role === 'owner' || role === 'admin' || has('guild_owner') || has('guild_admin');
-    default:
-      return false;
-  }
-}
-

package/src/protocol.ts

@@ -3,7 +3,7 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
-import type { IncomingMessage } from 'node:http';
+import { readBodyBytes } from '@zhin.js/host-http';
 import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { Locale } from 'zhin.js/i18n';
@@ -329,42 +329,13 @@ export function normalizeWebhookPath(path: string): string {
   return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
 
-export async function readTextBody(
-  request: IncomingMessage,
-  options: { readonly limit?: number } = {},
-): Promise<string> {
-  const limit = options.limit ?? 1_048_576;
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > limit) {
-      request.destroy();
-      throw new Error(`Request body exceeds ${limit} bytes`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}
 
 export async function readRequestBody(
-  request: IncomingMessage,
+  request: Request,
   options: { readonly limit?: number } = {},
 ): Promise<Buffer> {
-  const limit = options.limit ?? 1_048_576;
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > limit) {
-      request.destroy();
-      throw new Error(`Request body exceeds ${limit} bytes`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks);
+  // Oversize bodies throw (the webhook answers its generic OK), as before.
+  return Buffer.from(await readBodyBytes(request, { limit: options.limit ?? 1_048_576 }));
 }
 
 export function padKookEncryptKey(key: string): Buffer {

package/src/sender-roles.ts

@@ -1,27 +1,48 @@
 /**
- * KOOK 入站发送者角色投影。
+ * KOOK 入站发送者平台身份（ADR 0056 §1）。
  *
  * 事件只携带数字角色 id，无法直接判断群主 / 管理员；这里按服务器缓存
- * guild.view（群主 id）与 guild-role.list（角色权限位），把发送者投影为
- * 跨平台规范角色 owner / admin。原始角色 id 以 `role:<id>` 形式放入 permissions，
- * 不进入 `sender.roles`。
+ * guild.view（群主 id）与 guild-role.list（角色名与权限位），把发送者归一为
+ * `sender.platform`：
+ * - `standing`：服务器主 → `owner`；持有带「管理员」权限位的角色 → `admin`；否则 `member`。
+ *   查询失败、无法判断时不上报（不猜）。
+ * - `roles`：发送者持有的服务器角色（id + 名称）。
+ * - `permissions`：「全体成员」角色（role_id 0，每个成员都持有、事件里不列出）与这些角色权限位的并集，
+ *   按 KOOK 权限名（snake_case）上报；服务器主与持有「管理员」位的成员拥有全部权限，展开为全部权限名。
+ *   机器人自身身份（`inspectSelfStanding`）走同一套规则。
  */
 import { TtlLookupCache } from 'zhin.js/adapter';
+import type { PlatformStanding } from '@zhin.js/im-contract';
 import type { KookClientTransport } from './ws.js';
 
-/** KOOK 角色权限位：0x1 = 管理员。 */
-const KOOK_ROLE_ADMIN_BIT = 1;
 const CACHE_TTL_MS = 60_000;
+/** 「全体成员」：每个成员都持有的基础角色。 */
+const EVERYONE_ROLE_ID = '0';
 
-export interface KookSenderRoleProjection {
-  /** 规范角色：owner / admin；普通成员为 undefined。 */
-  readonly role?: 'owner' | 'admin';
-  readonly permissions: readonly string[];
+/** KOOK 角色权限位（按位序，见 KOOK 开发者文档「权限说明」）。 */
+export const KOOK_ROLE_PERMISSIONS: readonly string[] = Object.freeze([
+  'administrator', 'manage_guild', 'view_audit_log', 'create_invite', 'manage_invite', 'manage_channels',
+  'kick_members', 'ban_members', 'manage_emojis', 'change_nickname', 'manage_roles', 'view_channels',
+  'send_messages', 'manage_messages', 'attach_files', 'connect_voice', 'manage_voice', 'mention_everyone',
+  'add_reaction', 'follow_reaction', 'passive_connect_voice', 'push_to_talk_only', 'free_voice_speak', 'speak',
+  'deafen_members', 'mute_members', 'manage_nicknames', 'play_music',
+]);
+
+/** KOOK 权限位 → 权限名；未知位丢弃。 */
+export function kookPermissionNames(bits: number): string[] {
+  if (!Number.isFinite(bits) || bits <= 0) return [];
+  return KOOK_ROLE_PERMISSIONS.filter((_, index) => Math.floor(bits / 2 ** index) % 2 === 1);
+}
+
+interface GuildRole {
+  readonly name?: string;
+  readonly permissions: number;
 }
 
 interface GuildSnapshot {
   readonly ownerId?: string;
-  readonly adminRoleIds: ReadonlySet<string>;
+  /** `undefined` when the role list lookup failed. */
+  readonly roles?: ReadonlyMap<string, GuildRole>;
 }
 
 export class KookSenderRoleResolver {
@@ -33,19 +54,28 @@ export class KookSenderRoleResolver {
     readonly guildId?: string;
     readonly authorId: string;
     readonly authorRoles?: readonly number[];
-  }): Promise<KookSenderRoleProjection> {
-    const roleIds = (input.authorRoles ?? []).map(String);
-    const permissions = roleIds.map((id) => `role:${id}`);
-    if (!input.guildId) return { permissions };
-
+  }): Promise<PlatformStanding | undefined> {
+    if (!input.guildId) return undefined;
+    const roleIds = [...new Set((input.authorRoles ?? []).map(String))];
     const snapshot = await this.#snapshot(input.guildId);
-    if (snapshot?.ownerId !== undefined && snapshot.ownerId === input.authorId) {
-      return { role: 'owner', permissions: [...permissions, 'guild_owner', 'guild_admin'] };
-    }
-    if (snapshot && roleIds.some((id) => snapshot.adminRoleIds.has(id))) {
-      return { role: 'admin', permissions: [...permissions, 'guild_admin'] };
-    }
-    return { permissions };
+    if (!snapshot) return undefined;
+    const held = roleIds.filter((id) => id !== EVERYONE_ROLE_ID).map((id) => ({ id, role: snapshot.roles?.get(id) }));
+    const everyone = snapshot.roles?.get(EVERYONE_ROLE_ID)?.permissions ?? 0;
+    const bits = held.reduce((sum, { role }) => sum | (role?.permissions ?? 0), everyone);
+    const roles = held.map(({ id, role }) => (role?.name ? { id, name: role.name } : { id }));
+    const isOwner = snapshot.ownerId !== undefined && snapshot.ownerId === input.authorId;
+    const isAdmin = kookPermissionNames(bits).includes('administrator');
+    // The server owner and administrators hold every permission (KOOK ignores per-bit grants for them).
+    const permissions = isOwner || isAdmin ? [...KOOK_ROLE_PERMISSIONS] : kookPermissionNames(bits);
+    // Without the owner id or the role list the standing cannot be decided; an admin role still proves admin.
+    const standing = isOwner ? 'owner' : isAdmin ? 'admin'
+      : snapshot.ownerId !== undefined && snapshot.roles ? 'member' : undefined;
+    if (!standing) return undefined;
+    return {
+      standing,
+      ...(roles.length ? { roles } : {}),
+      ...(permissions.length ? { permissions } : {}),
+    };
   }
 
   async #snapshot(guildId: string): Promise<GuildSnapshot | undefined> {
@@ -58,16 +88,18 @@ export class KookSenderRoleResolver {
     const client = this.getClient();
     if (!client) return undefined;
     let ownerId: string | undefined;
-    const adminRoleIds = new Set<string>();
+    let roles: Map<string, GuildRole> | undefined;
     try {
       const info = await client.getGuildInfo?.(guildId);
       if (info?.user_id != null && String(info.user_id)) ownerId = String(info.user_id);
     } catch { /* 保守：视为无群主信息 */ }
     try {
+      roles = new Map();
       for (const role of await client.pickGuild(guildId).getRoleList()) {
-        if ((Number(role.permissions) & KOOK_ROLE_ADMIN_BIT) !== 0) adminRoleIds.add(String(role.role_id));
+        const name = typeof (role as { name?: unknown }).name === 'string' ? (role as { name: string }).name : undefined;
+        roles.set(String(role.role_id), { ...(name ? { name } : {}), permissions: Number(role.permissions) || 0 });
       }
-    } catch { /* 保守：视为无管理员角色 */ }
-    return { ...(ownerId ? { ownerId } : {}), adminRoleIds };
+    } catch { roles = undefined; /* 保守：视为无角色信息 */ }
+    return { ...(ownerId ? { ownerId } : {}), ...(roles ? { roles } : {}) };
   }
 }