@zhin.js/adapter-kook 5.0.1 → 5.0.3

package/agent/tools/blacklist.ts

@@ -0,0 +1,33 @@
+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 defineAgentTool<{ endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
+  description: 'KOOK 服务器黑名单管理：添加/移除',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+    action: z.enum(['add', 'remove']).describe('add|remove'),
+    user_id: z.string().describe('用户 ID'),
+    remark: z.string().optional().describe('备注（add 可选）'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  permissions: [platformPermit('guild_admin')],
+  async execute({ endpoint_id, guild_id, action, user_id, remark }: { endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    switch (action) {
+      case 'add': {
+        const success = await endpoint.addToBlacklist(guild_id, user_id, remark);
+        return { success, message: success ? `已将 ${user_id} 加入黑名单` : '操作失败' };
+      }
+      case 'remove': {
+        const success = await endpoint.removeFromBlacklist(guild_id, user_id);
+        return { success, message: success ? `已将 ${user_id} 从黑名单移除` : '操作失败' };
+      }
+      default:
+        return { success: false, message: `未知操作: ${action}` };
+    }
+  },
+});

package/agent/tools/create_role.ts

@@ -0,0 +1,25 @@
+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 defineAgentTool<{ endpoint_id: string; guild_id: string; name: string }>({
+  description: '在 KOOK 服务器中创建新角色',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+    name: z.string().describe('角色名称'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  permissions: [platformPermit('guild_owner')],
+  async execute({ endpoint_id, guild_id, name  }: { endpoint_id: string; guild_id: string; name: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    const role = await endpoint.createRole(guild_id, name);
+    return {
+      success: true,
+      message: `已创建角色 "${name}"`,
+      role: { id: role.role_id, name: role.name },
+    };
+  },
+});

package/agent/tools/delete_role.ts

@@ -0,0 +1,21 @@
+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 defineAgentTool<{ endpoint_id: string; guild_id: string; role_id: string }>({
+  description: '删除 KOOK 服务器中的角色',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  permissions: [platformPermit('guild_owner')],
+  async execute({ endpoint_id, guild_id, role_id  }: { endpoint_id: string; guild_id: string; role_id: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    const success = await endpoint.deleteRole(guild_id, role_id);
+    return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
+  },
+});

package/agent/tools/grant_role.ts

@@ -0,0 +1,22 @@
+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 defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+  description: '给用户授予 KOOK 服务器角色',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  permissions: [platformPermit('manage_roles')],
+  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    const success = await endpoint.grantRole(guild_id, user_id, role_id);
+    return { success, message: success ? `已授予用户 ${user_id} 角色 ${role_id}` : '授予角色失败' };
+  },
+});

package/agent/tools/list_roles.ts

@@ -0,0 +1,27 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+  description: '获取 KOOK 服务器的角色列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  async execute({ endpoint_id, guild_id  }: { endpoint_id: string; guild_id: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    const roles = await endpoint.getRoleList(guild_id);
+    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,22 @@
+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 defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+  description: '撤销用户的 KOOK 服务器角色',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  platforms: ['kook'],
+  tags: ['kook'],
+  permissions: [platformPermit('manage_roles')],
+  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
+    const endpoint = getKookAgentDeps().getEndpoint(endpoint_id);
+    const success = await endpoint.revokeRole(guild_id, user_id, role_id);
+    return { success, message: success ? `已撤销用户 ${user_id} 的角色 ${role_id}` : '撤销角色失败' };
+  },
+});

package/lib/endpoint.d.ts

@@ -1,155 +1,84 @@
-/**
- * KOOK Endpoint 实现
- */
-import { Client, User, Guild } from "kook-client";
-import { Endpoint, Message, SendOptions } from 'zhin.js';
-import type { KookEndpointConfig, KookRawMessage } from "./types.js";
-import type { KookAdapter } from "./adapter.js";
-import { type KookMsgRoute } from "./kook-msg-route.js";
-export declare class KookEndpoint extends Client implements Endpoint<KookEndpointConfig, KookRawMessage> {
-    $config: KookEndpointConfig;
-    $connected: boolean;
-    /** KOOK 平台 user_id，用于 @ 触发匹配（resolveEndpointAtIds） */
-    $platformUserId?: string;
-    adapter: KookAdapter;
-    private readonly inboundDeduper;
-    private readonly onGatewayEvent;
-    /** kook-client 构造函数注入的 process 监听器，disconnect 时需移除 */
-    private readonly _kookProcessListeners;
-    get $id(): string;
-    get pluginLogger(): import("zhin.js").Logger;
-    constructor(adapter: KookAdapter, $config: KookEndpointConfig);
-    /**
-     * 在 kook-client Receiver transform 之前拦截原始 gateway 事件（SDK 未实现 notice transform）
-     */
-    private hookGatewayReceiver;
-    private handleGatewayEvent;
-    private emitSideEvent;
-    /**
-     * 设置事件监听器
-     */
-    private setupEventListeners;
-    /**
-     * 将 KOOK 消息转换为标准消息格式
-     */
-    $formatMessage(msg: KookRawMessage): Message<KookRawMessage>;
-    /**
-     * 获取发送者的详细权限信息
-     */
-    private getSenderInfo;
-    /**
-     * 踢出用户
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     */
-    kickUser(guildId: string, userId: string): Promise<boolean>;
-    /**
-     * 将用户加入黑名单
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param remark 备注
-     * @param delMsgDays 删除消息天数（0-7）
-     */
-    addToBlacklist(guildId: string, userId: string, remark?: string, delMsgDays?: number): Promise<boolean>;
-    /**
-     * 将用户从黑名单移除
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     */
-    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
-    /**
-     * 给用户授予角色
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param roleId 角色ID
-     */
+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>;
-    /**
-     * 撤销用户角色
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param roleId 角色ID
-     */
     revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    /**
-     * 设置用户昵称
-     * @param guildId 服务器ID
-     * @param userId 用户ID
-     * @param nickname 新昵称
-     */
-    setNickname(guildId: string, userId: string, nickname: string): Promise<boolean>;
-    /**
-     * 获取服务器角色列表
-     * @param guildId 服务器ID
-     */
-    getRoleList(guildId: string): Promise<Guild.Role[]>;
-    /**
-     * 创建角色
-     * @param guildId 服务器ID
-     * @param name 角色名称
-     */
-    createRole(guildId: string, name: string): Promise<Guild.Role>;
-    /**
-     * 删除角色
-     * @param guildId 服务器ID
-     * @param roleId 角色ID
-     */
-    deleteRole(guildId: string, roleId: string): Promise<boolean>;
-    /**
-     * 获取服务器成员列表
-     * @param guildId 服务器ID
-     * @param channelId 可选的频道ID
-     */
-    getGuildMembers(guildId: string, channelId?: string): Promise<User.Info[]>;
-    private buildAtElement;
-    private resolveAtUserId;
-    private parseMarkdown;
-    /**
-     * 将 kook-client 的 MessageSegment[] 转换为 Zhin 的 MessageElement[]
-     */
-    private parseMessageContent;
-    /**
-     * 检查文本是否包含 KMarkdown 特殊语法
-     */
-    private hasKMarkdownSyntax;
-    /**
-     * 连接到 KOOK
-     */
-    $connect(): Promise<void>;
-    /**
-   * 断开连接
-   */
-    $disconnect(): Promise<void>;
-    /**
-     * 上传媒体（覆盖 kook-client：其 FormData.append 不接受 Node Buffer）
-     */
-    uploadMedia(data: string | Buffer): Promise<string>;
-    /**
-   * 发送消息
-   */
-    $sendMessage(options: SendOptions): Promise<string>;
-    /**
-     * 撤回消息。支持 `kook:channel:msgId` 出站 ref，或入站 plain msgId + route/sceneType 提示。
-     */
-    $recallMessage(messageIdOrRef: string, hint?: {
-        route?: KookMsgRoute;
-        sceneType?: 'private' | 'group' | 'channel';
-    }): Promise<void>;
-    private deleteKookMsg;
-    /**
-     * 为消息添加表情回应（TypingIndicator reaction 模式）
-     * @returns reactionId（含 channel/direct 路由），供 $removeReaction 使用
-     */
-    $addReaction(messageId: string, emoji: string, hint?: {
-        sceneType?: 'private' | 'group' | 'channel';
+    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>;
-    /** 移除本 Endpoint 在消息上的表情回应 */
-    $removeReaction(messageId: string, reactionId: string): Promise<void>;
-    private mutateMsgReaction;
-    /**
-   * 将消息段转换为 KOOK KMarkdown 格式
-   * 支持：文本、图片、@提及、表情、引用等
-   */
-    private convertToKookFormat;
+    /** 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>;
 }
-//# sourceMappingURL=endpoint.d.ts.map