@zhin.js/adapter-kook 5.0.2 → 6.0.0

package/agent/tools/create_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; name: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; name: string }>({
   description: '在 KOOK 服务器中创建新角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/delete_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; role_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; role_id: string }>({
   description: '删除 KOOK 服务器中的角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/grant_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
   description: '给用户授予 KOOK 服务器角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/list_roles.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
   description: '获取 KOOK 服务器的角色列表',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/revoke_role.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
   description: '撤销用户的 KOOK 服务器角色',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/lib/endpoint.d.ts

@@ -0,0 +1,84 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type KookInboundMessage, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
+import { type CreateKookClient } from './ws.js';
+export interface KookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: ResolvedKookWebsocketConfig;
+    readonly createClient?: CreateKookClient;
+}
+export declare class KookWebsocketEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: KookEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a message when open. */
+    admit(msg: KookInboundMessage): void;
+    getRoleList(guildId: string): Promise<{
+        role_id: string | number;
+        name: string;
+        color?: number;
+        position?: number;
+        permissions?: unknown;
+    }[]>;
+    createRole(guildId: string, name: string): Promise<{
+        role_id: string | number;
+        name: string;
+    }>;
+    deleteRole(guildId: string, roleId: string): Promise<boolean>;
+    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
+    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
+}
+export interface KookWebhookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedKookWebhookConfig;
+    readonly createClient?: CreateKookClient;
+}
+export declare class KookWebhookEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: KookWebhookEndpointOptions);
+    /** 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({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a message when open. */
+    admit(msg: KookInboundMessage): void;
+    checkAndRememberSn(sn: number): boolean;
+    getRoleList(guildId: string): Promise<{
+        role_id: string | number;
+        name: string;
+        color?: number;
+        position?: number;
+        permissions?: unknown;
+    }[]>;
+    createRole(guildId: string, name: string): Promise<{
+        role_id: string | number;
+        name: string;
+    }>;
+    deleteRole(guildId: string, roleId: string): Promise<boolean>;
+    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
+    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
+}

package/lib/endpoint.js

@@ -0,0 +1,299 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerKookAgentEndpoint } from './kook-agent-deps.js';
+import { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, isKookBotMentioned, parseSendTarget, senderDisplayName, } from './protocol.js';
+import { registerKookWebhookRoutes } from './webhook.js';
+import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+const logger = getLogger('kook');
+export class KookWebsocketEndpoint {
+    #options;
+    #createClient;
+    #client = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateClient;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            this.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.name, this);
+            this.#client = this.#createClient(this.#options.config);
+            this.#bindClient(this.#client);
+            await this.#client.connect();
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'websocket',
+                self_id: this.#client.self_id != null ? String(this.#client.self_id) : undefined,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            logger.error('Failed to connect KOOK websocket:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#client = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const parsed = parseSendTarget(target);
+        const client = this.#requireClient();
+        const result = parsed.kind === 'private'
+            ? await client.sendPrivateMsg(parsed.id, body)
+            : await client.sendChannelMsg(parsed.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        if (msg.authorBot)
+            return;
+        const target = formatInboundTarget(msg);
+        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+                ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    // ── Agent tool surface ──────────────────────────────────────────────
+    async getRoleList(guildId) {
+        return this.#requireClient().pickGuild(guildId).getRoleList();
+    }
+    async createRole(guildId, name) {
+        return this.#requireClient().pickGuild(guildId).createRole(name);
+    }
+    async deleteRole(guildId, roleId) {
+        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
+    }
+    async grantRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
+    }
+    async revokeRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
+    }
+    async addToBlacklist(guildId, userId, remark) {
+        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
+    }
+    async removeFromBlacklist(guildId, userId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
+    }
+    #bindClient(client) {
+        client.on('message', (raw) => {
+            const msg = normalizeKookMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not connected');
+        return this.#client;
+    }
+}
+export class KookWebhookEndpoint {
+    #options;
+    #createClient;
+    #client = null;
+    #routeReleases = [];
+    #processedSn = new Set();
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateWebhookClient;
+    }
+    /** 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.#unregisterAgent = registerKookAgentEndpoint(this.#options.config.name, this);
+            this.#client = this.#createClient(this.#options.config);
+            await this.#client.init();
+            this.#routeReleases.push(...registerKookWebhookRoutes(this.#options.http, this));
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                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();
+            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.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#processedSn.clear();
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#client = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundKmarkdown(payload);
+        const parsed = parseSendTarget(target);
+        const client = this.#requireClient();
+        const result = parsed.kind === 'private'
+            ? await client.sendPrivateMsg(parsed.id, body)
+            : await client.sendChannelMsg(parsed.id, body);
+        const messageId = result?.msg_id != null ? String(result.msg_id) : '';
+        logger.debug(formatCompact({
+            op: 'kook_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        if (msg.authorBot)
+            return;
+        const target = formatInboundTarget(msg);
+        const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+                ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'kook_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    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;
+    }
+    async getRoleList(guildId) {
+        return this.#requireClient().pickGuild(guildId).getRoleList();
+    }
+    async createRole(guildId, name) {
+        return this.#requireClient().pickGuild(guildId).createRole(name);
+    }
+    async deleteRole(guildId, roleId) {
+        return this.#requireClient().pickGuild(guildId).deleteRole(roleId);
+    }
+    async grantRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).grant(roleId);
+    }
+    async revokeRole(guildId, userId, roleId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).revoke(roleId);
+    }
+    async addToBlacklist(guildId, userId, remark) {
+        return this.#requireClient().pickGuildMember(guildId, userId).addToBlackList(remark);
+    }
+    async removeFromBlacklist(guildId, userId) {
+        return this.#requireClient().pickGuildMember(guildId, userId).removeFromBlackList();
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('KOOK client not initialized');
+        return this.#client;
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ParsedSendTarget, 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 { getKookAgentDeps, registerKookAgentEndpoint, setKookAgentDeps, type KookAgentDeps, type KookAgentEndpoint, } from './kook-agent-deps.js';
+export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, registerKookPlatformPermitChecker, type KookSenderInfo, } from './platform-permit.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, } from './protocol.js';
+export { KookWebhookEndpoint, KookWebsocketEndpoint, } from './endpoint.js';
+export { registerKookWebhookRoutes, handleKookWebhookRequest, } from './webhook.js';
+export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+export { getKookAgentDeps, registerKookAgentEndpoint, setKookAgentDeps, } from './kook-agent-deps.js';
+export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, registerKookPlatformPermitChecker, } from './platform-permit.js';

package/lib/kook-agent-deps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent tool deps for kook.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface KookAgentEndpoint {
+    getRoleList(guildId: string): Promise<Array<{
+        role_id: string | number;
+        name: string;
+        color?: number;
+        position?: number;
+        permissions?: unknown;
+    }>>;
+    createRole(guildId: string, name: string): Promise<{
+        role_id: string | number;
+        name: string;
+    }>;
+    deleteRole(guildId: string, roleId: string): Promise<boolean>;
+    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
+    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
+}
+export interface KookAgentDeps {
+    getEndpoint: (endpointId: string) => KookAgentEndpoint;
+}
+export declare function registerKookAgentEndpoint(endpointId: string, endpoint: KookAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setKookAgentDeps(deps: KookAgentDeps | null): void;
+export declare function getKookAgentDeps(): KookAgentDeps;

package/lib/kook-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for kook.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerKookAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setKookAgentDeps(deps) {
+    override = deps;
+}
+export function getKookAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const registered = endpoints.get(endpointId);
+            if (!registered)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return registered;
+        },
+    };
+}

package/lib/platform-permit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * KOOK platform permit — guild / channel 差异化门禁
+ */
+import { type Message } from '@zhin.js/core';
+import { KookPermission } from './protocol.js';
+export declare function platformPermit(perm: string): string;
+export declare function kookGroupPermitResolver(logicalPerm: string): string;
+export interface KookSenderInfo {
+    id: string;
+    name: string;
+    permission?: KookPermission;
+    roles?: number[];
+    isGuildOwner?: boolean;
+    isAdmin?: boolean;
+    role?: string;
+    permissions?: string[];
+}
+export declare function normalizeKookSenderForPermit(info: KookSenderInfo, isChannel: boolean): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkKookPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerKookPlatformPermitChecker(): () => void;

package/lib/{src/platform-permit.js → platform-permit.js}

@@ -1,8 +1,8 @@
 /**
  * KOOK platform permit — guild / channel 差异化门禁
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
-import { KookPermission } from './types.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
+import { KookPermission } from './protocol.js';
 const ADAPTER = 'kook';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -63,4 +63,3 @@ export function checkKookPlatformPermit(perm, message) {
 export function registerKookPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkKookPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map