@zhin.js/adapter-kook 1.0.83 → 1.1.0

package/agent/tools/grant_role.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
+  description: '给用户授予 KOOK 服务器角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermit('manage_roles')],
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuildMember(guild_id, user_id).grant(role_id);
+    return { success, message: success ? `已授予用户 ${user_id} 角色 ${role_id}` : '授予角色失败' };
+  },
+});

package/agent/tools/list_roles.ts

@@ -0,0 +1,25 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 KOOK 服务器的角色列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const roles = await client.pickGuild(guild_id).getRoleList();
+    return {
+      roles: roles.map((r) => ({
+        id: String(r.role_id),
+        name: r.name,
+        color: r.color,
+        position: r.position,
+        permissions: r.permissions,
+      })),
+      count: roles.length,
+    };
+  },
+});

package/agent/tools/revoke_role.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
+  description: '撤销用户的 KOOK 服务器角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermit('manage_roles')],
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuildMember(guild_id, user_id).revoke(role_id);
+    return { success, message: success ? `已撤销用户 ${user_id} 的角色 ${role_id}` : '撤销角色失败' };
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { kookEndpointCommands } from "../../../lib/kook-endpoint-commands.js";
+export default kookEndpointCommands.add;

package/commands/endpoint/add/[id].ts

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

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { kookEndpointCommands } from "../../lib/kook-endpoint-commands.js";
+export default kookEndpointCommands.list;

package/commands/endpoint/list.ts

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

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { kookEndpointCommands } from "../../../lib/kook-endpoint-commands.js";
+export default kookEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

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

package/lib/client.d.ts

@@ -0,0 +1,11 @@
+import type { KookClientTransport } from './ws.js';
+export type KookClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly kook: {
+            readonly client: KookClientTransport;
+            readonly events: KookClientEventMap;
+        };
+    }
+}
+export declare const kookClient: import("@zhin.js/adapter").EndpointClientToken<KookClientTransport, KookClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const kookClient = defineEndpointClient('kook');

package/lib/endpoint.d.ts

@@ -0,0 +1,59 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type KookInboundMessage, type KookWebhookEventData, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
+import { type CreateKookClient, type KookClientTransport } from './ws.js';
+export interface KookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly config: ResolvedKookWebsocketConfig;
+    readonly createClient?: CreateKookClient;
+}
+export declare class KookWebsocketEndpoint extends Endpoint<KookClientTransport> {
+    #private;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    constructor(options: KookEndpointOptions);
+    get client(): KookClientTransport;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a normalized message when open. */
+    admit(msg: KookInboundMessage): void;
+    recallMessage(messageId: string): Promise<void>;
+}
+export interface KookWebhookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedKookWebhookConfig;
+    readonly createClient?: CreateKookClient;
+}
+export declare class KookWebhookEndpoint extends Endpoint<KookClientTransport> {
+    #private;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    constructor(options: KookWebhookEndpointOptions);
+    get client(): KookClientTransport;
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedKookWebhookConfig;
+    get selfId(): string | undefined;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    admitEvent(event: KookWebhookEventData): void;
+    /** Test / internal: admit a message when open. */
+    admit(msg: KookInboundMessage): void;
+    recallMessage(messageId: string): Promise<void>;
+    checkAndRememberSn(sn: number): boolean;
+}
+/**
+ * KOOK endpoint 的 EndpointManagement 语义端口（websocket / webhook 共用）。
+ * 数据走 kook-client 的 HTTP API 封装：/api/v3/guild/list、
+ * /api/v3/channel/list、/api/v3/guild/user-list（SDK 内部已做分页聚合）。
+ */
+export declare function createKookEndpointManagement(requireClient: () => KookClientTransport): EndpointManagement;

package/lib/endpoint.js

@@ -0,0 +1,374 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, normalizeKookWebhookEvent, senderDisplayName, } from './protocol.js';
+import { registerKookWebhookRoutes } from './webhook.js';
+import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+import { receiveKookSideEvent } from './side-event-dispatch.js';
+export class KookWebsocketEndpoint extends Endpoint {
+    #logger;
+    #options;
+    #createClient;
+    #client = null;
+    #open = false;
+    #started = false;
+    management = createKookEndpointManagement(() => this.#requireClient());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('kook', options.config.id);
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateClient;
+    }
+    get client() {
+        return this.#requireClient();
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            this.#client = this.#createClient(this.#options.config);
+            this.#bindClient(this.#client);
+            await this.#client.connect();
+            this.#logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.id,
+                mode: 'websocket',
+                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            this.#logger.error('Failed to connect KOOK websocket:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#client = null;
+        }
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const client = this.#requireClient();
+        const result = conversation.kind === 'private'
+            ? await client.sendPrivateMsg(conversation.id, body)
+            : await client.sendChannelMsg(conversation.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        this.#logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a normalized message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        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) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.#requireClient().recallMsg?.(messageId);
+    }
+    #bindClient(client) {
+        client.on('message', (raw) => {
+            this.#emitPlatformEvent('message', raw);
+            const msg = normalizeKookMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
+        const receiver = client.receiver;
+        receiver?.on('event', (raw) => {
+            this.#emitPlatformEvent('event', raw);
+            receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not connected');
+        return this.#client;
+    }
+}
+export class KookWebhookEndpoint extends Endpoint {
+    #logger;
+    #options;
+    #createClient;
+    #client = null;
+    #routeReleases = [];
+    #processedSn = new Set();
+    #open = false;
+    #started = false;
+    management = createKookEndpointManagement(() => this.#requireClient());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('kook', options.config.id);
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateWebhookClient;
+    }
+    get client() {
+        return this.#requireClient();
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    get selfId() {
+        return this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            this.#client = this.#createClient(this.#options.config);
+            await this.#client.init();
+            this.#routeReleases.push(...registerKookWebhookRoutes(this.#options.http, this));
+            this.#logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.id,
+                mode: 'webhook',
+                path: this.#options.config.webhookPath,
+                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            this.#logger.error('Failed to connect KOOK webhook:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#processedSn.clear();
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#client = null;
+        }
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const client = this.#requireClient();
+        const result = conversation.kind === 'private'
+            ? await client.sendPrivateMsg(conversation.id, body)
+            : await client.sendChannelMsg(conversation.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        this.#logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    admitEvent(event) {
+        void this.emitPlatform(String(event.type ?? 'event'), event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_platform_event_failed',
+                event: String(event.type ?? 'event'),
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (receiveKookSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, event, this.#logger))
+            return;
+        const message = normalizeKookWebhookEvent(event, {
+            ignore: this.#options.config.ignore,
+            selfId: this.selfId,
+        });
+        if (message)
+            this.admit(message);
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        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) => {
+            this.#logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.#requireClient().recallMsg?.(messageId);
+    }
+    checkAndRememberSn(sn) {
+        if (this.#processedSn.has(sn))
+            return false;
+        this.#processedSn.add(sn);
+        if (this.#processedSn.size > 1024) {
+            const first = this.#processedSn.values().next().value;
+            if (first != null)
+                this.#processedSn.delete(first);
+        }
+        return true;
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not initialized');
+        return this.#client;
+    }
+}
+/**
+ * KOOK guild/channel/user id 是字符串形式的雪花号，超出
+ * Number.MAX_SAFE_INTEGER，Number() 会丢精度。Console 社交面只把 group_id
+ * 当 JSON 值透传、并以字符串回传给 listGroupMembers，因此保留原始字符串
+ * （仅按契约类型声明强转）是全链路最不丢信息的方案。
+ */
+function toGroupId(id) {
+    return id;
+}
+/** KOOK 文字频道标记：HTTP API type=1（2=语音），kook-client 消息侧用 'GROUP'。 */
+function isKookTextChannelType(type) {
+    return type === 1 || type === '1' || type === 'GROUP';
+}
+/**
+ * KOOK endpoint 的 EndpointManagement 语义端口（websocket / webhook 共用）。
+ * 数据走 kook-client 的 HTTP API 封装：/api/v3/guild/list、
+ * /api/v3/channel/list、/api/v3/guild/user-list（SDK 内部已做分页聚合）。
+ */
+export function createKookEndpointManagement(requireClient) {
+    return Object.freeze({
+        async listGroups() {
+            const guilds = await requireClient().getGuildList();
+            const groups = [];
+            for (const guild of guilds) {
+                if (guild?.id == null)
+                    continue;
+                groups.push({
+                    group_id: toGroupId(String(guild.id)),
+                    name: String(guild.name ?? guild.id),
+                });
+            }
+            return groups;
+        },
+        async listChannels() {
+            const client = requireClient();
+            const channels = [];
+            for (const guild of await client.getGuildList()) {
+                if (guild?.id == null)
+                    continue;
+                const guildId = String(guild.id);
+                const guildName = String(guild.name ?? guildId);
+                for (const channel of await client.getChannelList(guildId)) {
+                    if (channel?.id == null)
+                        continue;
+                    if (channel.is_category)
+                        continue;
+                    if (!isKookTextChannelType(channel.type))
+                        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) {
+            // 平台形状（User.Info[]）原样返回
+            return requireClient().getGuildUserList(groupId);
+        },
+    });
+}

package/lib/index.d.ts

@@ -1,18 +1,6 @@
-import { KookAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/console";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-        }
-    }
-}
-declare module "zhin.js" {
-    interface Adapters {
-        kook: KookAdapter;
-    }
-}
-export * from "./types.js";
-export { KookBot } from "./bot.js";
-export { KookAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
+export { KookWebhookEndpoint, KookWebsocketEndpoint, type KookEndpointOptions, type KookWebhookEndpointOptions, } from './endpoint.js';
+export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHandler, } from './webhook.js';
+export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, type CreateKookClient, type KookClientTransport, } from './ws.js';
+export { kookClient, type KookClientEventMap } from './client.js';
+export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, type KookSenderInfo, } from './platform-permit.js';