@zhin.js/adapter-kook 1.0.84 → 1.1.2

package/agents/kook/skills/kook/tools/blacklist/index.ts

@@ -0,0 +1,31 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
+  description: 'KOOK 服务器黑名单管理：添加/移除',
+  inputSchema: z.object({
+    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 可选）'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermission('kook', 'guild_admin')],
+  async execute({ guild_id, action, user_id, remark }: { guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }, context) {
+    const member = context.$client.pickGuildMember(guild_id, user_id);
+    switch (action) {
+      case 'add': {
+        const success = await member.addToBlackList(remark);
+        return { success, message: success ? `已将 ${user_id} 加入黑名单` : '操作失败' };
+      }
+      case 'remove': {
+        const success = await member.removeFromBlackList();
+        return { success, message: success ? `已将 ${user_id} 从黑名单移除` : '操作失败' };
+      }
+      default:
+        return { success: false, message: `未知操作: ${action}` };
+    }
+  },
+});

package/agents/kook/skills/kook/tools/create_role/index.js

@@ -0,0 +1,23 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '在 KOOK 服务器中创建新角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        name: z.string().describe('角色名称'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'guild_owner')],
+    async execute({ guild_id, name }, context) {
+        const client = context.$client;
+        const role = await client.pickGuild(guild_id).createRole(name);
+        return {
+            success: true,
+            message: `已创建角色 "${name}"`,
+            role: { id: role.role_id, name: role.name },
+        };
+    },
+});

package/agents/kook/skills/kook/tools/create_role/index.ts

@@ -0,0 +1,23 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string; name: string }>({
+  description: '在 KOOK 服务器中创建新角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    name: z.string().describe('角色名称'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermission('kook', 'guild_owner')],
+  async execute({ guild_id, name  }: { guild_id: string; name: string }, context) {
+    const client = context.$client;
+    const role = await client.pickGuild(guild_id).createRole(name);
+    return {
+      success: true,
+      message: `已创建角色 "${name}"`,
+      role: { id: role.role_id, name: role.name },
+    };
+  },
+});

package/agents/kook/skills/kook/tools/delete_role/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '删除 KOOK 服务器中的角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        role_id: z.string().describe('角色 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'guild_owner')],
+    async execute({ guild_id, role_id }, context) {
+        const client = context.$client;
+        const success = await client.pickGuild(guild_id).deleteRole(role_id);
+        return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
+    },
+});

package/agents/kook/skills/kook/tools/delete_role/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string; role_id: string }>({
+  description: '删除 KOOK 服务器中的角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermission('kook', 'guild_owner')],
+  async execute({ guild_id, role_id  }: { guild_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuild(guild_id).deleteRole(role_id);
+    return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
+  },
+});

package/agents/kook/skills/kook/tools/grant_role/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    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: [platformPermission('kook', 'manage_roles')],
+    async execute({ guild_id, user_id, role_id }, 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/agents/kook/skills/kook/tools/grant_role/index.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+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: [platformPermission('kook', '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/agents/kook/skills/kook/tools/list_roles/index.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取 KOOK 服务器的角色列表',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    async execute({ guild_id }, 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/agents/kook/skills/kook/tools/list_roles/index.ts

@@ -0,0 +1,25 @@
+import { defineAgentTool } from '@zhin.js/tool';
+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/agents/kook/skills/kook/tools/revoke_role/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    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: [platformPermission('kook', 'manage_roles')],
+    async execute({ guild_id, user_id, role_id }, 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/agents/kook/skills/kook/tools/revoke_role/index.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+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: [platformPermission('kook', '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/agents/kook/system.md

@@ -0,0 +1,3 @@
+# KOOK Platform Agent
+
+You are the kook platform specialist. Interpret requests in the current kook conversation and load only the narrowest private Skill needed for the task.

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

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

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

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

package/commands/kook/endpoint/definition.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `kook endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/kook/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { kookRuntimeStateToken } from "../../../lib/kook-runtime-state.js";
+export const kookEndpointCommands = createEndpointCommands({
+    adapterKey: 'kook',
+    adapterDisplayName: 'KOOK',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'KOOK bot token' },
+        { key: 'encrypt_key', env: true, description: 'webhook 加密密钥（connection: webhook）' },
+        { key: 'verify_token', env: true, description: 'webhook 验证 token（connection: webhook）' },
+    ],
+    running: (use) => use(kookRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/commands/kook/endpoint/definition.ts

@@ -0,0 +1,19 @@
+/**
+ * `kook endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/kook/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { kookRuntimeStateToken } from '../../../src/kook-runtime-state.js';
+
+export const kookEndpointCommands = createEndpointCommands({
+  adapterKey: 'kook',
+  adapterDisplayName: 'KOOK',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'KOOK bot token' },
+    { key: 'encrypt_key', env: true, description: 'webhook 加密密钥（connection: webhook）' },
+    { key: 'verify_token', env: true, description: 'webhook 验证 token（connection: webhook）' },
+  ],
+  running: (use) => use(kookRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/commands/kook/endpoint/list/index.js

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

package/commands/kook/endpoint/list/index.ts

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

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

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

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

@@ -0,0 +1,3 @@
+import { kookEndpointCommands } from '../../definition.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;