@zhin.js/adapter-kook 1.1.10 → 1.1.12

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @zhin.js/adapter-kook
 
+## 1.1.12
+
+### Patch Changes
+
+- e40899f: Adapters now project group owners and admins onto the canonical `sender.roles` names `owner` / `admin` (Telegram creator/administrator, KOOK guild owner and admin-permission roles, Lark chat owner/managers, QQ official guild owner/admin identities). KOOK numeric role ids moved from `roles` to `permissions` (`role:<id>`). `@zhin.js/command` exports `canManageConversation` ("private chat or owner/admin/master"), now shared by the Bilibili and earthquake subscription commands; Roulette lets owners and admins toggle the mute penalty and cancel a game.
+- 9e1d1a6: 飞书 / KOOK 查询群主与管理员时，缓存失效那一刻同一个群（服务器）的并发消息共用一次查询，不再各自调用一次接口。
+- fbfefb7: Share segments accept `data.platform` (the song's music service: qq, netease, kugou, kuwo, migu). icqq maps it to the matching music app id when `config.appid` is absent and offers it to the Agent; adapters that cannot render share app metadata reject it like `audio` and `config`.
+- Updated dependencies [1a11207]
+- Updated dependencies [9943df6]
+- Updated dependencies [5be09ae]
+- Updated dependencies [a3ab153]
+- Updated dependencies [e8f7309]
+- Updated dependencies [5afc18f]
+- Updated dependencies [d3563d9]
+- Updated dependencies [c618eb7]
+- Updated dependencies [fbfefb7]
+  - @zhin.js/tool@1.1.8
+  - @zhin.js/core@1.1.47
+  - @zhin.js/adapter@1.1.21
+  - @zhin.js/feature-kit@1.1.7
+  - @zhin.js/im-contract@1.1.5
+  - @zhin.js/agent-feature@1.1.8
+  - @zhin.js/skill@1.1.8
+  - @zhin.js/host-http@1.1.8
+
+## 1.1.11
+
+### Patch Changes
+
+- 9816c18: 将应用插件装配改为 configVersion: 2：主配置 plugins 映射实例名到包，disable_plugins 控制启停，业务配置使用顶层同名块。package.json 继续保留 features、entry、engine 等包契约，并支持静态 displayName/icon。
+
+  这是配置格式的破坏性更新：旧配置不能继续运行，请先停止 Bot，运行 `zhin migrate instances` 预览，再使用 `--apply` 转换；提供备份与中断继续/回滚，无法无损转换的嵌套、optional 和别名碰撞需人工迁移。Runtime、Console、CLI 与创建向导统一使用新声明。
+
+  保留框架顶层 `menuKeyword` / `menuStyle`，通过当前 generation 的 Root 配置视图供 Command Feature 消费；严格校验和配置修改不会丢失菜单设置，子实例配置保持隔离。
+
+- Updated dependencies [c407bd2]
+- Updated dependencies [064b06d]
+- Updated dependencies [2b4d6dc]
+- Updated dependencies [a50fc8a]
+- Updated dependencies [b58548a]
+- Updated dependencies [e914a93]
+- Updated dependencies [e914a93]
+- Updated dependencies [064b06d]
+  - @zhin.js/core@1.1.46
+  - @zhin.js/feature-kit@1.1.6
+  - @zhin.js/host-http@1.1.7
+  - @zhin.js/permission@1.1.7
+  - @zhin.js/adapter@1.1.20
+  - @zhin.js/agent-feature@1.1.7
+  - @zhin.js/skill@1.1.7
+  - @zhin.js/tool@1.1.7
+
 ## 1.1.10
 
 ### Patch Changes

package/README.md

@@ -23,7 +23,7 @@ pnpm add @zhin.js/adapter-kook
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `@zhin.js/host-http` — Webhook 模式 POST 路由（WebSocket 不需要）
 - `zhin.js` — `plugin.ts`（`definePlugin`）
-- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 - **WebSocket 路径无需** `@zhin.js/host-http` / `@zhin.js/host-router`
 
 入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef：`channel` 频道消息带 guild `parent`，`private` 私聊）  
@@ -44,16 +44,18 @@ pnpm add @zhin.js/adapter-kook
 ## 最小配置
 
 ```yaml
+configVersion: 2
 # zhin.config.yml（Plugin Runtime）
 plugins:
-  kook:
-    # connection: websocket   # 默认
-    endpoints:
-      - id: my-kook-bot
-        token: ${KOOK_TOKEN}
+  kook: "@zhin.js/adapter-kook"
+kook:
+  # connection: websocket   # 默认
+  endpoints:
+    - id: my-kook-bot
+      token: ${KOOK_TOKEN}
 ```
 
-根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-kook`（`instanceKey: kook`）。
+主配置 `plugins` 映射需引用 `@zhin.js/adapter-kook`（`instanceKey: kook`）。
 
 ## 环境变量
 
@@ -68,15 +70,17 @@ plugins:
 在 KOOK 开发者后台选择 **WebHook** 连接模式，Callback URL 指向 Host 暴露的公网地址（建议在 URL 加 `?compress=0` 便于调试）。
 
 ```yaml
+configVersion: 2
 plugins:
-  kook:
-    connection: webhook
-    webhookPath: /kook/webhook
-    endpoints:
-      - id: my-kook-bot
-        token: ${KOOK_TOKEN}
-        verify_token: ${KOOK_VERIFY_TOKEN}
-        # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
+  kook: "@zhin.js/adapter-kook"
+kook:
+  connection: webhook
+  webhookPath: /kook/webhook
+  endpoints:
+    - id: my-kook-bot
+      token: ${KOOK_TOKEN}
+      verify_token: ${KOOK_VERIFY_TOKEN}
+      # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
 ```
 
 Host 需注入 `httpHostToken`。Challenge（`type: 255`）会校验 `verify_token` 并回显 `challenge`；普通事件经 `gateway.receive` 入站，出站仍走 KOOK HTTP API。

package/lib/endpoint.js

@@ -5,13 +5,38 @@ import { formatInboundContent, isKookBotMentioned, kookInboundConversation, norm
 import { registerKookWebhookRoutes } from './webhook.js';
 import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
 import { recallKookMessage, sendKookOutbound } from './outbound.js';
+import { KookSenderRoleResolver } from './sender-roles.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
+/** 入站 message.receive 载荷：规范角色 owner/admin 进 roles，原始角色 id 进 permissions。 */
+function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
+    return {
+        conversation,
+        message: { conversation, id: msg.id },
+        content: formatInboundContent(msg),
+        sender: {
+            id: msg.authorId,
+            name: senderDisplayName(msg) || undefined,
+            ...(projection.role ? { roles: [projection.role] } : {}),
+            ...(projection.permissions.length ? { permissions: [...projection.permissions] } : {}),
+        },
+        endpointId,
+        ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+        metadata: Object.freeze({
+            channelKind: msg.channelKind,
+            userId: msg.authorId,
+            guildId: msg.guildId,
+            authorRoleIds: msg.authorRoles,
+            ...(projection.role ? { senderRole: projection.role } : {}),
+        }),
+    };
+}
 export class KookWebsocketEndpoint extends Endpoint {
     #sentConversations = new Map();
     #logger;
     #options;
     #createClient;
     #client = null;
+    #roles = new KookSenderRoleResolver(() => this.#client);
     #open = false;
     #started = false;
     management = createKookEndpointManagement(() => this.#requireClient());
@@ -94,24 +119,7 @@ export class KookWebsocketEndpoint extends Endpoint {
             return;
         const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.emit('message.receive', {
-            conversation,
-            message: { conversation, id: msg.id },
-            content: formatInboundContent(msg),
-            sender: {
-                id: msg.authorId,
-                name: senderDisplayName(msg) || undefined,
-                ...(msg.authorRoles?.length ? { roles: msg.authorRoles.map(String) } : {}),
-            },
-            endpointId: this.#options.config.id,
-            ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
-            metadata: Object.freeze({
-                channelKind: msg.channelKind,
-                userId: msg.authorId,
-                guildId: msg.guildId,
-                roles: msg.authorRoles,
-            }),
-        }).catch((err) => {
+        void this.#roles.resolve(msg).then((projection) => this.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId))).catch((err) => {
             this.#logger.warn(formatCompact({
                 op: 'kook_gateway_receive_failed',
                 target: `${conversation.kind}:${conversation.id}`,
@@ -172,6 +180,7 @@ export class KookWebhookEndpoint extends Endpoint {
     #options;
     #createClient;
     #client = null;
+    #roles = new KookSenderRoleResolver(() => this.#client);
     #routeReleases = [];
     #processedSn = new Set();
     #open = false;
@@ -289,24 +298,7 @@ export class KookWebhookEndpoint extends Endpoint {
             return;
         const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-        void this.emit('message.receive', {
-            conversation,
-            message: { conversation, id: msg.id },
-            content: formatInboundContent(msg),
-            sender: {
-                id: msg.authorId,
-                name: senderDisplayName(msg) || undefined,
-                ...(msg.authorRoles?.length ? { roles: msg.authorRoles.map(String) } : {}),
-            },
-            endpointId: this.#options.config.id,
-            ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
-            metadata: Object.freeze({
-                channelKind: msg.channelKind,
-                userId: msg.authorId,
-                guildId: msg.guildId,
-                roles: msg.authorRoles,
-            }),
-        }).catch((err) => {
+        void this.#roles.resolve(msg).then((projection) => this.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId))).catch((err) => {
             this.#logger.warn(formatCompact({
                 op: 'kook_gateway_receive_failed',
                 target: `${conversation.kind}:${conversation.id}`,

package/lib/outbound.js

@@ -46,7 +46,7 @@ export async function sendKookOutbound(client, { conversation, payload }) {
                 }
                 if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim())
                     throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires URL and title', 'not_sent');
-                if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined))
+                if (['image', 'audio', 'artist', 'duration', 'platform', 'config'].some(key => data[key] !== undefined))
                     throw new EndpointDeliveryError('unsupported_operation', 'KOOK share media/app metadata is not implemented', 'not_sent');
                 modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: data.title } });
                 for (const value of [data.description, data.content])

package/lib/sender-roles.d.ts

@@ -0,0 +1,24 @@
+/**
+ * KOOK 入站发送者角色投影。
+ *
+ * 事件只携带数字角色 id，无法直接判断群主 / 管理员；这里按服务器缓存
+ * guild.view（群主 id）与 guild-role.list（角色权限位），把发送者投影为
+ * 跨平台规范角色 owner / admin。原始角色 id 以 `role:<id>` 形式放入 permissions，
+ * 不进入 `sender.roles`。
+ */
+import type { KookClientTransport } from './ws.js';
+export interface KookSenderRoleProjection {
+    /** 规范角色：owner / admin；普通成员为 undefined。 */
+    readonly role?: 'owner' | 'admin';
+    readonly permissions: readonly string[];
+}
+export declare class KookSenderRoleResolver {
+    #private;
+    private readonly getClient;
+    constructor(getClient: () => KookClientTransport | null);
+    resolve(input: {
+        readonly guildId?: string;
+        readonly authorId: string;
+        readonly authorRoles?: readonly number[];
+    }): Promise<KookSenderRoleProjection>;
+}

package/lib/sender-roles.js

@@ -0,0 +1,61 @@
+/** KOOK 角色权限位：0x1 = 管理员。 */
+const KOOK_ROLE_ADMIN_BIT = 1;
+const CACHE_TTL_MS = 60_000;
+export class KookSenderRoleResolver {
+    getClient;
+    #guilds = new Map();
+    /** One lookup per guild at a time: concurrent messages on a cache miss share it. */
+    #lookups = new Map();
+    constructor(getClient) {
+        this.getClient = getClient;
+    }
+    async resolve(input) {
+        const roleIds = (input.authorRoles ?? []).map(String);
+        const permissions = roleIds.map((id) => `role:${id}`);
+        if (!input.guildId)
+            return { permissions };
+        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 };
+    }
+    async #snapshot(guildId) {
+        const cached = this.#guilds.get(guildId);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached;
+        let lookup = this.#lookups.get(guildId);
+        if (!lookup) {
+            lookup = this.#fetch(guildId).finally(() => this.#lookups.delete(guildId));
+            this.#lookups.set(guildId, lookup);
+        }
+        return lookup;
+    }
+    async #fetch(guildId) {
+        const now = Date.now();
+        const client = this.getClient();
+        if (!client)
+            return undefined;
+        let ownerId;
+        const adminRoleIds = new Set();
+        try {
+            const info = await client.getGuildInfo?.(guildId);
+            if (info?.user_id != null && String(info.user_id))
+                ownerId = String(info.user_id);
+        }
+        catch { /* 保守：视为无群主信息 */ }
+        try {
+            for (const role of await client.pickGuild(guildId).getRoleList()) {
+                if ((Number(role.permissions) & KOOK_ROLE_ADMIN_BIT) !== 0)
+                    adminRoleIds.add(String(role.role_id));
+            }
+        }
+        catch { /* 保守：视为无管理员角色 */ }
+        const snapshot = { at: now, ...(ownerId ? { ownerId } : {}), adminRoleIds };
+        this.#guilds.set(guildId, snapshot);
+        return snapshot;
+    }
+}

package/lib/ws.d.ts

@@ -22,6 +22,10 @@ export interface KookClientTransport {
     uploadMedia?(data: Buffer): Promise<string>;
     recallChannelMsg?(channelId: string, messageId: string): Promise<boolean>;
     recallPrivateMsg?(userId: string, messageId: string): Promise<boolean>;
+    /** GET /api/v3/guild/view（群主 id）。 */
+    getGuildInfo?(guildId: string): Promise<{
+        user_id?: string | number;
+    }>;
     pickGuild(guildId: string): {
         kick(userId: string): Promise<boolean>;
         getRoleList(): Promise<Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,23 +33,23 @@
   },
   "dependencies": {
     "kook-client": "^1.0.5",
-    "@zhin.js/adapter": "1.1.19",
-    "@zhin.js/agent-feature": "1.1.6",
-    "@zhin.js/core": "1.1.45",
-    "@zhin.js/feature-kit": "1.1.5",
-    "@zhin.js/host-http": "1.1.6",
-    "@zhin.js/im-contract": "1.1.4",
+    "@zhin.js/adapter": "1.1.21",
+    "@zhin.js/agent-feature": "1.1.8",
+    "@zhin.js/core": "1.1.47",
+    "@zhin.js/feature-kit": "1.1.7",
+    "@zhin.js/host-http": "1.1.8",
+    "@zhin.js/im-contract": "1.1.5",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.6",
-    "@zhin.js/skill": "1.1.6",
-    "@zhin.js/tool": "1.1.6"
+    "@zhin.js/permission": "1.1.7",
+    "@zhin.js/tool": "1.1.8",
+    "@zhin.js/skill": "1.1.8"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.19",
-    "@zhin.js/command": "^1.1.7",
-    "@zhin.js/core": "^1.1.45",
-    "zhin.js": "^1.1.10"
+    "@zhin.js/adapter": "^1.1.21",
+    "@zhin.js/command": "^1.1.9",
+    "@zhin.js/core": "^1.1.47",
+    "zhin.js": "^1.1.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -67,8 +67,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.6",
-    "zhin.js": "1.1.10"
+    "@zhin.js/host-http": "1.1.8",
+    "zhin.js": "1.1.12"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -37,6 +37,7 @@ import {
   type KookClientTransport,
 } from './ws.js';
 import { recallKookMessage, sendKookOutbound } from './outbound.js';
+import { KookSenderRoleResolver, type KookSenderRoleProjection } from './sender-roles.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
 
 export interface KookEndpointOptions {
@@ -45,6 +46,36 @@ export interface KookEndpointOptions {
   readonly createClient?: CreateKookClient;
 }
 
+/** 入站 message.receive 载荷：规范角色 owner/admin 进 roles，原始角色 id 进 permissions。 */
+function kookInboundPayload(
+  endpointId: string,
+  conversation: ConversationRef,
+  msg: KookInboundMessage,
+  projection: KookSenderRoleProjection,
+  selfId: string | undefined,
+) {
+  return {
+    conversation,
+    message: { conversation, id: msg.id },
+    content: formatInboundContent(msg),
+    sender: {
+      id: msg.authorId,
+      name: senderDisplayName(msg) || undefined,
+      ...(projection.role ? { roles: [projection.role] } : {}),
+      ...(projection.permissions.length ? { permissions: [...projection.permissions] } : {}),
+    },
+    endpointId,
+    ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+    metadata: Object.freeze({
+      channelKind: msg.channelKind,
+      userId: msg.authorId,
+      guildId: msg.guildId,
+      authorRoleIds: msg.authorRoles,
+      ...(projection.role ? { senderRole: projection.role } : {}),
+    }),
+  };
+}
+
 export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
   #sentConversations = new Map<string, ConversationRef>();
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
@@ -52,6 +83,7 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
   readonly #options: KookEndpointOptions;
   readonly #createClient: CreateKookClient;
   #client: KookClientTransport | null = null;
+  readonly #roles = new KookSenderRoleResolver(() => this.#client);
   #open = false;
   #started = false;
   readonly management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
@@ -137,24 +169,9 @@ export class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
     if (msg.authorBot) return;
     const conversation = kookInboundConversation(String(this.#options.id), msg);
     const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-    void this.emit('message.receive', {
-      conversation,
-      message: { conversation, id: msg.id },
-      content: formatInboundContent(msg),
-      sender: {
-        id: msg.authorId,
-        name: senderDisplayName(msg) || undefined,
-        ...(msg.authorRoles?.length ? { roles: msg.authorRoles.map(String) } : {}),
-      },
-      endpointId: this.#options.config.id,
-      ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
-      metadata: Object.freeze({
-        channelKind: msg.channelKind,
-        userId: msg.authorId,
-        guildId: msg.guildId,
-        roles: msg.authorRoles,
-      }),
-    }).catch((err) => {
+    void this.#roles.resolve(msg).then((projection) => this.emit('message.receive',
+      kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId),
+    )).catch((err) => {
       this.#logger.warn(formatCompact({
         op: 'kook_gateway_receive_failed',
         target: `${conversation.kind}:${conversation.id}`,
@@ -223,6 +240,7 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
   readonly #options: KookWebhookEndpointOptions;
   readonly #createClient: CreateKookClient;
   #client: KookClientTransport | null = null;
+  readonly #roles = new KookSenderRoleResolver(() => this.#client);
   #routeReleases: HttpRouteRegistration[] = [];
   #processedSn = new Set<number>();
   #open = false;
@@ -348,24 +366,9 @@ export class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
     if (msg.authorBot) return;
     const conversation = kookInboundConversation(String(this.#options.id), msg);
     const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
-    void this.emit('message.receive', {
-      conversation,
-      message: { conversation, id: msg.id },
-      content: formatInboundContent(msg),
-      sender: {
-        id: msg.authorId,
-        name: senderDisplayName(msg) || undefined,
-        ...(msg.authorRoles?.length ? { roles: msg.authorRoles.map(String) } : {}),
-      },
-      endpointId: this.#options.config.id,
-      ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
-      metadata: Object.freeze({
-        channelKind: msg.channelKind,
-        userId: msg.authorId,
-        guildId: msg.guildId,
-        roles: msg.authorRoles,
-      }),
-    }).catch((err) => {
+    void this.#roles.resolve(msg).then((projection) => this.emit('message.receive',
+      kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId),
+    )).catch((err) => {
       this.#logger.warn(formatCompact({
         op: 'kook_gateway_receive_failed',
         target: `${conversation.kind}:${conversation.id}`,

package/src/outbound.ts

@@ -37,7 +37,7 @@ export async function sendKookOutbound(client: KookClientTransport, { conversati
         let url: URL;
         try { url = new URL(data.url); } catch { throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires an HTTP(S) URL', 'not_sent'); }
         if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim()) throw new EndpointDeliveryError('invalid_payload', 'KOOK share requires URL and title', 'not_sent');
-        if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) throw new EndpointDeliveryError('unsupported_operation', 'KOOK share media/app metadata is not implemented', 'not_sent');
+        if (['image', 'audio', 'artist', 'duration', 'platform', 'config'].some(key => data[key] !== undefined)) throw new EndpointDeliveryError('unsupported_operation', 'KOOK share media/app metadata is not implemented', 'not_sent');
         modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: data.title } });
         for (const value of [data.description, data.content]) if (typeof value === 'string' && value) modules.push({ type: 'section', mode: 'left', text: { type: 'plain-text', content: value } });
         modules.push({ type: 'action-group', elements: [{ type: 'button', theme: 'secondary', click: 'link', value: url.href, text: { type: 'plain-text', content: '打开链接' } }] });

package/src/sender-roles.ts

@@ -0,0 +1,83 @@
+/**
+ * KOOK 入站发送者角色投影。
+ *
+ * 事件只携带数字角色 id，无法直接判断群主 / 管理员；这里按服务器缓存
+ * guild.view（群主 id）与 guild-role.list（角色权限位），把发送者投影为
+ * 跨平台规范角色 owner / admin。原始角色 id 以 `role:<id>` 形式放入 permissions，
+ * 不进入 `sender.roles`。
+ */
+import type { KookClientTransport } from './ws.js';
+
+/** KOOK 角色权限位：0x1 = 管理员。 */
+const KOOK_ROLE_ADMIN_BIT = 1;
+const CACHE_TTL_MS = 60_000;
+
+export interface KookSenderRoleProjection {
+  /** 规范角色：owner / admin；普通成员为 undefined。 */
+  readonly role?: 'owner' | 'admin';
+  readonly permissions: readonly string[];
+}
+
+interface GuildSnapshot {
+  readonly at: number;
+  readonly ownerId?: string;
+  readonly adminRoleIds: ReadonlySet<string>;
+}
+
+export class KookSenderRoleResolver {
+  readonly #guilds = new Map<string, GuildSnapshot>();
+  /** One lookup per guild at a time: concurrent messages on a cache miss share it. */
+  readonly #lookups = new Map<string, Promise<GuildSnapshot | undefined>>();
+
+  constructor(private readonly getClient: () => KookClientTransport | null) {}
+
+  async resolve(input: {
+    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 };
+
+    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 };
+  }
+
+  async #snapshot(guildId: string): Promise<GuildSnapshot | undefined> {
+    const cached = this.#guilds.get(guildId);
+    if (cached && Date.now() - cached.at < CACHE_TTL_MS) return cached;
+    let lookup = this.#lookups.get(guildId);
+    if (!lookup) {
+      lookup = this.#fetch(guildId).finally(() => this.#lookups.delete(guildId));
+      this.#lookups.set(guildId, lookup);
+    }
+    return lookup;
+  }
+
+  async #fetch(guildId: string): Promise<GuildSnapshot | undefined> {
+    const now = Date.now();
+    const client = this.getClient();
+    if (!client) return undefined;
+    let ownerId: string | undefined;
+    const adminRoleIds = new Set<string>();
+    try {
+      const info = await client.getGuildInfo?.(guildId);
+      if (info?.user_id != null && String(info.user_id)) ownerId = String(info.user_id);
+    } catch { /* 保守：视为无群主信息 */ }
+    try {
+      for (const role of await client.pickGuild(guildId).getRoleList()) {
+        if ((Number(role.permissions) & KOOK_ROLE_ADMIN_BIT) !== 0) adminRoleIds.add(String(role.role_id));
+      }
+    } catch { /* 保守：视为无管理员角色 */ }
+    const snapshot: GuildSnapshot = { at: now, ...(ownerId ? { ownerId } : {}), adminRoleIds };
+    this.#guilds.set(guildId, snapshot);
+    return snapshot;
+  }
+}

package/src/ws.ts

@@ -35,6 +35,8 @@ export interface KookClientTransport {
   uploadMedia?(data: Buffer): Promise<string>;
   recallChannelMsg?(channelId: string, messageId: string): Promise<boolean>;
   recallPrivateMsg?(userId: string, messageId: string): Promise<boolean>;
+  /** GET /api/v3/guild/view（群主 id）。 */
+  getGuildInfo?(guildId: string): Promise<{ user_id?: string | number }>;
   pickGuild(guildId: string): {
     kick(userId: string): Promise<boolean>;
     getRoleList(): Promise<Array<{