@zhin.js/adapter-kook 1.0.84 → 1.1.0

package/src/index.ts

@@ -1,322 +1,45 @@
-/**
- * KOOK 适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, type Plugin, type IGroupManagement, createGroupManagementTools, type ToolFeature } from "zhin.js";
-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";
-
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-
-provide({
-  name: "kook",
-  description: "KOOK Adapter",
-  mounted: async (p: Plugin) => {
-    const adapter = new KookAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: KookAdapter) => {
-    await adapter.stop();
-  },
-});
-
-useContext('tool', 'kook', (toolService: ToolFeature, kook: KookAdapter) => {
-  const groupTools = createGroupManagementTools(
-    kook as unknown as IGroupManagement,
-    'kook',
-  );
-  const disposers: (() => void)[] = groupTools.map(t => toolService.addTool(t, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_grant_role',
-    description: '给用户授予 KOOK 服务器角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['bot', 'guild_id', 'user_id', 'role_id'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.grantRole(args.guild_id, args.user_id, args.role_id);
-      return { success, message: success ? `已授予用户 ${args.user_id} 角色 ${args.role_id}` : '授予角色失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_revoke_role',
-    description: '撤销用户的 KOOK 服务器角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['bot', 'guild_id', 'user_id', 'role_id'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.revokeRole(args.guild_id, args.user_id, args.role_id);
-      return { success, message: success ? `已撤销用户 ${args.user_id} 的角色 ${args.role_id}` : '撤销角色失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_list_roles',
-    description: '获取 KOOK 服务器的角色列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-      },
-      required: ['bot', 'guild_id'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const roles = await bot.getRoleList(args.guild_id);
-      return {
-        roles: roles.map((r: any) => ({
-          id: r.role_id,
-          name: r.name,
-          color: r.color,
-          position: r.position,
-          permissions: r.permissions,
-        })),
-        count: roles.length,
-      };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_create_role',
-    description: '在 KOOK 服务器中创建新角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-        name: { type: 'string', description: '角色名称' },
-      },
-      required: ['bot', 'guild_id', 'name'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const role = await bot.createRole(args.guild_id, args.name);
-      return {
-        success: true,
-        message: `已创建角色 "${args.name}"`,
-        role: { id: role.role_id, name: role.name },
-      };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_delete_role',
-    description: '删除 KOOK 服务器中的角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['bot', 'guild_id', 'role_id'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.deleteRole(args.guild_id, args.role_id);
-      return { success, message: success ? `已删除角色 ${args.role_id}` : '删除角色失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'kook_blacklist',
-    description: 'KOOK 服务器黑名单管理：添加/移除',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '服务器 ID' },
-        action: { type: 'string', description: 'add|remove', enum: ['add', 'remove'] },
-        user_id: { type: 'string', description: '用户 ID' },
-        remark: { type: 'string', description: '备注（add 可选）' },
-      },
-      required: ['bot', 'guild_id', 'action', 'user_id'],
-    },
-    platforms: ['kook'],
-    tags: ['kook'],
-    execute: async (args: Record<string, any>) => {
-      const bot = kook.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      switch (args.action) {
-        case 'add': {
-          const success = await bot.addToBlacklist(args.guild_id, args.user_id, args.remark);
-          return { success, message: success ? `已将 ${args.user_id} 加入黑名单` : '操作失败' };
-        }
-        case 'remove': {
-          const success = await bot.removeFromBlacklist(args.guild_id, args.user_id);
-          return { success, message: success ? `已将 ${args.user_id} 从黑名单移除` : '操作失败' };
-        }
-        default:
-          return { success: false, message: `未知操作: ${args.action}` };
-      }
-    },
-  }, plugin.name));
-
-  return () => disposers.forEach(d => d());
-});
-
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "kook",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "KOOK" },
-  });
-});
-
-useContext("router", "kook", (router: any, kook: KookAdapter) => {
-  router.get("/api/kook/bots", async (ctx: any) => {
-    try {
-      const bots = Array.from(kook.bots.values());
-      const result = bots.map((bot: any) => {
-        try {
-          return {
-            name: bot.$config.name,
-            connected: bot.$connected || false,
-            guildCount: bot.guilds?.size || 0,
-            status: bot.$connected ? "online" : "offline",
-          };
-        } catch {
-          return { name: bot.$config.name, connected: false, guildCount: 0, status: "error" };
-        }
-      });
-      ctx.body = { success: true, data: result };
-    } catch {
-      ctx.status = 500;
-      ctx.body = { success: false, error: "获取机器人数据失败" };
-    }
-  });
-
-  // Bot 连接/断开
-  router.post("/api/kook/bots/:name/connect", async (ctx: any) => {
-    try {
-      const bot = kook.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (bot.$connected) { ctx.body = { success: true, message: "已经在线" }; return; }
-      await bot.$connect();
-      ctx.body = { success: true, message: "连接成功" };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "连接失败" };
-    }
-  });
-
-  router.post("/api/kook/bots/:name/disconnect", async (ctx: any) => {
-    try {
-      const bot = kook.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.body = { success: true, message: "已经离线" }; return; }
-      await bot.$disconnect();
-      ctx.body = { success: true, message: "已断开" };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "断开失败" };
-    }
-  });
-
-  // 角色列表
-  router.get("/api/kook/bots/:name/guilds/:guildId/roles", async (ctx: any) => {
-    try {
-      const bot: any = kook.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const roles = await bot.getRoleList(ctx.params.guildId);
-      ctx.body = {
-        success: true,
-        data: roles.map((r: any) => ({
-          id: r.role_id,
-          name: r.name,
-          color: r.color,
-          position: r.position,
-        })),
-      };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "获取角色列表失败" };
-    }
-  });
-
-  // 创建角色
-  router.post("/api/kook/bots/:name/guilds/:guildId/roles", async (ctx: any) => {
-    try {
-      const bot: any = kook.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const { name } = ctx.request.body || {};
-      if (!name) { ctx.status = 400; ctx.body = { success: false, error: "缺少角色名称" }; return; }
-      const role = await bot.createRole(ctx.params.guildId, name);
-      ctx.body = { success: true, data: { id: role.role_id, name: role.name } };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "创建角色失败" };
-    }
-  });
-
-  // 删除角色
-  router.delete("/api/kook/bots/:name/guilds/:guildId/roles/:roleId", async (ctx: any) => {
-    try {
-      const bot: any = kook.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const success = await bot.deleteRole(ctx.params.guildId, ctx.params.roleId);
-      ctx.body = { success, message: success ? "角色已删除" : "删除失败" };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "删除角色失败" };
-    }
-  });
-});
+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';

package/src/kook-endpoint-commands.ts

@@ -0,0 +1,19 @@
+/**
+ * `kook.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { kookRuntimeStateToken } from './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/src/kook-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * KOOK 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `kook.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+
+export const kookRuntimeStateToken = defineEndpointRuntimeStateToken('kook');

package/src/platform-permit.ts

@@ -0,0 +1,75 @@
+/**
+ * KOOK platform permit — guild / channel 差异化门禁
+ */
+import type { PermissionSubject } from '@zhin.js/permission';
+import { KookPermission } from './protocol.js';
+
+const ADAPTER = 'kook';
+
+export function platformPermit(perm: string): string {
+  return `platform(${ADAPTER},${perm})`;
+}
+
+const FACTORY_PERM_MAP: Record<string, string> = {
+  scene_admin: 'guild_admin',
+  scene_owner: 'guild_owner',
+};
+
+export function kookGroupPermitResolver(logicalPerm: string): string {
+  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+
+export interface KookSenderInfo {
+  id: string;
+  name: string;
+  permission?: KookPermission;
+  roles?: number[];
+  isGuildOwner?: boolean;
+  isAdmin?: boolean;
+  role?: string;
+  permissions?: string[];
+}
+
+export function normalizeKookSenderForPermit(
+  info: KookSenderInfo,
+  isChannel: boolean,
+): { role?: string; permissions?: string[] } {
+  const permissions: string[] = [];
+  if (info.roles?.length) {
+    permissions.push(...info.roles.map((r) => `role:${r}`));
+  }
+
+  if (info.isGuildOwner || info.permission === KookPermission.Owner) {
+    permissions.push('guild_owner', 'guild_admin');
+    return { role: 'owner', permissions };
+  }
+  if (info.permission === KookPermission.ChannelAdmin && isChannel) {
+    permissions.push('channel_admin', 'guild_admin');
+    return { role: 'channel_admin', permissions };
+  }
+  if (info.isAdmin || info.permission === KookPermission.Admin) {
+    permissions.push('guild_admin');
+    return { role: 'admin', permissions };
+  }
+  return { role: 'member', permissions };
+}
+
+export function checkKookPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
+  const has = (t: string) => permissions.includes(t);
+
+  switch (perm) {
+    case 'guild_owner':
+      return role === 'owner' || has('guild_owner');
+    case 'guild_admin':
+      return role === 'owner' || role === 'admin' || role === 'channel_admin' || has('guild_admin') || has('channel_admin');
+    case 'channel_admin':
+      return role === 'owner' || role === 'admin' || role === 'channel_admin' || has('channel_admin') || has('guild_admin');
+    case 'manage_roles':
+      return role === 'owner' || role === 'admin' || has('guild_owner') || has('guild_admin');
+    default:
+      return false;
+  }
+}
+