@zhin.js/adapter-kook 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zhin.js/adapter-kook
 
+## 6.0.1
+
+### Patch Changes
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
 ## 6.0.0
 
 ### Patch Changes

package/adapters/kook.ts

@@ -13,6 +13,7 @@ import {
   resolveKookConfig,
   type KookAdapterConfig,
 } from '../src/protocol.js';
+import { kookRuntimeStateToken } from '../src/kook-runtime-state.js';
 
 export {
   KookWebhookEndpoint,
@@ -26,9 +27,19 @@ export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
 
 export default defineAdapter<KookAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // KOOK 图片消息消费远程 URL；无按钮交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveKookConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（kook endpoint list 的"运行中"数据源）
+    context.use(kookRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.connection,
+    });
     if (config.connection === 'webhook') {
       return new KookWebhookEndpoint({
         id: context.id,

package/commands/endpoint/add/[name:string].ts

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

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/[name:string].ts

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

package/lib/endpoint.d.ts

@@ -1,9 +1,9 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } 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';
+import { type CreateKookClient, type KookClientTransport } from './ws.js';
 export interface KookEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
@@ -12,6 +12,7 @@ export interface KookEndpointOptions {
 }
 export declare class KookWebsocketEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: KookEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -49,6 +50,7 @@ export interface KookWebhookEndpointOptions {
 }
 export declare class KookWebhookEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: KookWebhookEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
@@ -82,3 +84,9 @@ export declare class KookWebhookEndpoint implements EndpointInstance {
     addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
     removeFromBlacklist(guildId: string, userId: string): Promise<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

@@ -11,6 +11,7 @@ export class KookWebsocketEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createKookEndpointManagement(() => this.#requireClient());
     constructor(options) {
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
@@ -150,6 +151,7 @@ export class KookWebhookEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createKookEndpointManagement(() => this.#requireClient());
     constructor(options) {
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateWebhookClient;
@@ -297,3 +299,66 @@ export class KookWebhookEndpoint {
         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/kook-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const kookEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/kook-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `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/lib/kook-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const kookRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/kook-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * 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/lib/ws.d.ts

@@ -33,7 +33,20 @@ export interface KookClientTransport {
         revoke(roleId: string): Promise<boolean>;
         setNickname(nickname: string): Promise<boolean>;
     };
-    getGuildUserList?(guildId: string, channelId?: string): Promise<unknown[]>;
+    /** GET /api/v3/guild/list（kook-client 内部分页聚合）。 */
+    getGuildList(): Promise<Array<{
+        id: string | number;
+        name?: string;
+    }>>;
+    /** GET /api/v3/channel/list（type: 1=文字 2=语音；is_category 为分组）。 */
+    getChannelList(guildId: string): Promise<Array<{
+        id: string | number;
+        name?: string;
+        type?: string | number;
+        is_category?: boolean;
+    }>>;
+    /** GET /api/v3/guild/user-list。 */
+    getGuildUserList(guildId: string, channelId?: string): Promise<unknown[]>;
     self_id?: string | number;
 }
 export type CreateKookClient = (config: ResolvedKookConfig) => KookClientTransport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,19 +34,20 @@
   },
   "dependencies": {
     "kook-client": "^1.0.4",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -64,12 +65,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/host-http": "1.0.2",
-    "zhin.js": "5.0.0"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -95,6 +97,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerKookPlatformPermitChecker } from './src/platform-permit.js';
+import { kookRuntimeStateToken } from './src/kook-runtime-state.js';
 
 export default definePlugin({
   name: 'kook',
   metadata: {
     displayName: 'KOOK WebSocket Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（kook endpoint list 的"运行中"数据源）
+    context.resources.provide(kookRuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：guild_owner / guild_admin / channel_admin 等（agent 工具 platformPermit）
     return registerKookPlatformPermitChecker();
   },

package/src/endpoint.ts

@@ -2,7 +2,12 @@
  * KookEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
 import { Client } from 'kook-client';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type {
+  EndpointChannel,
+  EndpointGroup,
+  EndpointInstance,
+  EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -44,6 +49,7 @@ export class KookWebsocketEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
 
   constructor(options: KookEndpointOptions) {
     this.#options = options;
@@ -202,6 +208,7 @@ export class KookWebhookEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createKookEndpointManagement(() => this.#requireClient());
 
   constructor(options: KookWebhookEndpointOptions) {
     this.#options = options;
@@ -359,3 +366,66 @@ export class KookWebhookEndpoint implements EndpointInstance {
     return this.#client;
   }
 }
+
+/**
+ * KOOK guild/channel/user id 是字符串形式的雪花号，超出
+ * Number.MAX_SAFE_INTEGER，Number() 会丢精度。Console 社交面只把 group_id
+ * 当 JSON 值透传、并以字符串回传给 listGroupMembers，因此保留原始字符串
+ * （仅按契约类型声明强转）是全链路最不丢信息的方案。
+ */
+function toGroupId(id: string): number {
+  return id as unknown as number;
+}
+
+/** KOOK 文字频道标记：HTTP API type=1（2=语音），kook-client 消息侧用 'GROUP'。 */
+function isKookTextChannelType(type: string | number | undefined): boolean {
+  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: () => KookClientTransport,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const guilds = await requireClient().getGuildList();
+      const groups: EndpointGroup[] = [];
+      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(): Promise<readonly EndpointChannel[]> {
+      const client = requireClient();
+      const channels: EndpointChannel[] = [];
+      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: string): Promise<readonly unknown[]> {
+      // 平台形状（User.Info[]）原样返回
+      return requireClient().getGuildUserList(groupId);
+    },
+  });
+}

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/ws.ts

@@ -43,7 +43,17 @@ export interface KookClientTransport {
     revoke(roleId: string): Promise<boolean>;
     setNickname(nickname: string): Promise<boolean>;
   };
-  getGuildUserList?(guildId: string, channelId?: string): Promise<unknown[]>;
+  /** GET /api/v3/guild/list（kook-client 内部分页聚合）。 */
+  getGuildList(): Promise<Array<{ id: string | number; name?: string }>>;
+  /** GET /api/v3/channel/list（type: 1=文字 2=语音；is_category 为分组）。 */
+  getChannelList(guildId: string): Promise<Array<{
+    id: string | number;
+    name?: string;
+    type?: string | number;
+    is_category?: boolean;
+  }>>;
+  /** GET /api/v3/guild/user-list。 */
+  getGuildUserList(guildId: string, channelId?: string): Promise<unknown[]>;
   self_id?: string | number;
 }