@zhin.js/adapter-kook 5.0.3 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @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
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 5.0.3
 
 ### Patch Changes

package/README.md

@@ -38,7 +38,7 @@ pnpm add @zhin.js/adapter-kook
 | **Webhook** | 需公网 HTTPS + Host `httpHostToken`；与 WebSocket 互斥 |
 | **host-http** | 仅 Webhook 模式需要 |
 
-必填字段：`token`。
+必填字段（`endpoints[i]`）：`name`、`token`。
 
 ## 最小配置
 
@@ -46,9 +46,10 @@ pnpm add @zhin.js/adapter-kook
 # zhin.config.yml（Plugin Runtime）
 plugins:
   kook:
-    name: my-kook-bot
-    token: ${KOOK_TOKEN}
     # connection: websocket   # 默认
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-kook`（`instanceKey: kook`）。
@@ -70,12 +71,13 @@ plugins:
 ```yaml
 plugins:
   kook:
-    name: my-kook-bot
-    token: ${KOOK_TOKEN}
     connection: webhook
-    verify_token: ${KOOK_VERIFY_TOKEN}
     webhookPath: /kook/webhook
-    # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
+        verify_token: ${KOOK_VERIFY_TOKEN}
+        # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
 ```
 
 Host 需注入 `httpHostToken`。Challenge（`type: 255`）会校验 `verify_token` 并回显 `challenge`；普通事件经 `gateway.receive` 入站，出站仍走 KOOK HTTP API。

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": "5.0.3",
+  "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.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@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.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@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.4",
-    "@zhin.js/host-http": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@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/schema.json

@@ -3,16 +3,12 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "kook-bot"
-    },
-    "token": {
-      "type": "string"
-    },
     "connection": {
       "type": "string",
-      "enum": ["websocket", "webhook"],
+      "enum": [
+        "websocket",
+        "webhook"
+      ],
       "default": "websocket",
       "description": "WebSocket gateway (default). webhook requires httpHostToken, verify_token, and a public HTTPS callback URL."
     },
@@ -21,14 +17,6 @@
       "default": "/kook/webhook",
       "description": "POST path registered via httpHostToken when connection is webhook."
     },
-    "verify_token": {
-      "type": "string",
-      "description": "KOOK developer console verify token (required for webhook mode)."
-    },
-    "encrypt_key": {
-      "type": "string",
-      "description": "Optional Encrypt Key when message encryption is enabled in KOOK console."
-    },
     "data_dir": {
       "type": "string"
     },
@@ -42,14 +30,63 @@
     },
     "ignore": {
       "type": "string",
-      "enum": ["bot", "self"],
+      "enum": [
+        "bot",
+        "self"
+      ],
       "default": "bot"
     },
     "logLevel": {
       "type": "string",
-      "enum": ["trace", "debug", "info", "warn", "error", "fatal", "mark", "off"],
+      "enum": [
+        "trace",
+        "debug",
+        "info",
+        "warn",
+        "error",
+        "fatal",
+        "mark",
+        "off"
+      ],
       "default": "info"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "KOOK bot name"
+          },
+          "token": {
+            "type": "string",
+            "description": "KOOK bot token"
+          },
+          "verify_token": {
+            "type": "string",
+            "description": "KOOK developer console verify token (required for webhook mode)."
+          },
+          "encrypt_key": {
+            "type": "string",
+            "description": "Optional Encrypt Key when message encryption is enabled in KOOK console."
+          }
+        },
+        "required": [
+          "name",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["token"]
+  "required": [
+    "endpoints"
+  ]
 }

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;
 }