@zhin.js/adapter-kook 7.0.12 → 7.0.14

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @zhin.js/adapter-kook
 
+## 7.0.14
+
+### Patch Changes
+
+- 974772e: Replace the user-facing `Prompt` vocabulary with the `UserInteraction` authoring surface for input, confirmation, and selection. Commands and handlers now expose `interaction`; IM Runtime exposes `createInteraction`; schema-driven endpoint collection is named `SchemaInteraction`. The old prompt-named interaction types and properties are removed rather than aliased. User interactions render through one canonical Markdown and keyboard/list presentation module shared by commands and Agent `ask_user` turns.
+
+  Extract the transport-neutral interaction contract into `@zhin.js/interaction`. A discriminated `ask()` API supports text, number, confirmation, single-select, multi-select, and typed lists with structured `title`, `description`, and `tip` content. Typed `sequence()` interactions return one result object keyed by step id, render progress, and retry invalid replies without leaking invalid values to callers.
+
+  Preserve AI Markdown and card command actions through outbound publishing. QQ delivers Markdown with native command buttons; KOOK, Discord, Telegram, DingTalk, and Lark/Feishu now declare and encode their native Markdown dialects while retaining each adapter's interaction policy. Correct QQ callback button action encoding and button style mapping.
+
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
+## 7.0.13
+
+### Patch Changes
+
+- @zhin.js/core@1.5.11
+- @zhin.js/agent@1.1.13
+- zhin.js@6.0.11
+
 ## 7.0.12
 
 ### Patch Changes

package/README.md

@@ -8,6 +8,7 @@ Zhin.js KOOK（开黑啦）适配器（Plugin Runtime），默认通过 **WebSoc
 - Webhook 入站（`connection: webhook` + `httpHostToken` + `verify_token`）
 - 解析频道与私聊文本消息
 - 出站 `send({ conversation, payload })` → KOOK KMarkdown（`kind: 'channel' | 'private'`）
+- canonical `markdown` 段原生保留为 [KMarkdown](https://developer.kookapp.cn/doc/kmarkdown-desc)
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
@@ -96,7 +97,7 @@ platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；Capa
 
 ## 迁移后出站能力变化
 
-迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染为文本后发送（`sendChannelMsg` / `sendPrivateMsg`，KMarkdown 文本）。旧 Adapter 的富媒体出站能力（图片 / 卡片消息 / 附件等多模态 segment 直发）暂未迁移，当前出站等价于纯文本（KMarkdown）。如需发送卡片或附件，可直接使用 endpoint 上的 KOOK OpenAPI 封装（`getRoleList` 等同款 client）作为逃生舱。
+迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染并由 endpoint 编码为 KMarkdown（`sendChannelMsg` / `sendPrivateMsg`）。canonical `markdown` 保留格式；图片、视频、音频和文件仅有远程 URL 时可表示为 KMarkdown 链接。卡片消息与附件上传仍未接入统一出站通道。
 
 ## 许可证
 

package/adapters/kook.js

@@ -4,7 +4,7 @@
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
 import { resolveKookConfig, } from "../lib/protocol.js";
@@ -12,14 +12,17 @@ import { kookRuntimeStateToken } from "../lib/kook-runtime-state.js";
 export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // KOOK 图片消息消费远程 URL；无按钮交互面，交互段降级纯文本。
+    // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
+    // 无按钮交互面，交互段降级纯文本。
     segments: {
         outboundMedia: ['url'],
         interactive: 'text',
+        markdown: 'native',
     },
     create(context) {
         const config = resolveKookConfig(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
         context.use(kookRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -29,6 +32,7 @@ export default defineAdapter({
             return new KookWebhookEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -36,6 +40,7 @@ export default defineAdapter({
         return new KookWebsocketEndpoint({
             id: context.id,
             gateway,
+            sideEvents,
             config,
         });
     },

package/adapters/kook.ts

@@ -3,7 +3,7 @@
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   KookWebhookEndpoint,
@@ -27,14 +27,17 @@ export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
 
 export default defineAdapter<KookAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // KOOK 图片消息消费远程 URL；无按钮交互面，交互段降级纯文本。
+  // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
+  // 无按钮交互面，交互段降级纯文本。
   segments: {
     outboundMedia: ['url'],
     interactive: 'text',
+    markdown: 'native',
   },
   create(context) {
     const config = resolveKookConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
     context.use(kookRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -44,6 +47,7 @@ export default defineAdapter<KookAdapterConfig>({
       return new KookWebhookEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -51,6 +55,7 @@ export default defineAdapter<KookAdapterConfig>({
     return new KookWebsocketEndpoint({
       id: context.id,
       gateway,
+      sideEvents,
       config,
     });
   },

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
 import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type KookInboundMessage, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
@@ -7,6 +7,7 @@ import { type CreateKookClient, type KookClientTransport } from './ws.js';
 export interface KookEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedKookWebsocketConfig;
     readonly createClient?: CreateKookClient;
 }
@@ -42,6 +43,7 @@ export declare class KookWebsocketEndpoint implements EndpointInstance {
 export interface KookWebhookEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedKookWebhookConfig;
     readonly createClient?: CreateKookClient;

package/lib/endpoint.js

@@ -3,6 +3,7 @@ import { registerKookAgentEndpoint } from './kook-agent-deps.js';
 import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, senderDisplayName, } from './protocol.js';
 import { registerKookWebhookRoutes } from './webhook.js';
 import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+import { receiveKookSideEvent } from './side-event-dispatch.js';
 export class KookWebsocketEndpoint {
     #logger;
     #options;
@@ -143,6 +144,10 @@ export class KookWebsocketEndpoint {
             if (msg)
                 this.admit(msg);
         });
+        const receiver = client.receiver;
+        receiver?.on('event', (raw) => {
+            receiveKookSideEvent(this.#options.sideEvents, this.#options.config.id, raw, this.#logger);
+        });
     }
     #requireClient() {
         if (!this.#client)

package/lib/protocol.js

@@ -146,6 +146,8 @@ export function formatOutboundKmarkdown(payload) {
         switch (item.type) {
             case 'text':
                 return String(data.text ?? data.content ?? '');
+            case 'markdown':
+                return String(data.content ?? data.text ?? '');
             case 'at': {
                 const id = String(data.user_id ?? data.qq ?? data.id ?? '');
                 return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+export declare function receiveKookSideEvent(sideEvents: SideEventGateway | undefined, configId: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): boolean;

package/lib/side-event-dispatch.js

@@ -0,0 +1,51 @@
+import { buildNotice, mapNoticeParts, senderFromId, KOOK_NOTICE_PARTS_MAP } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+function extractKookNoticeType(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const event = raw;
+    const extraType = event.extra?.type;
+    if (typeof extraType === 'string' && extraType)
+        return extraType;
+    if (event.channel_type === 'NOTICE' && event.type != null) {
+        return String(event.type);
+    }
+    return null;
+}
+export function receiveKookSideEvent(sideEvents, configId, raw, logger) {
+    if (!sideEvents)
+        return false;
+    const noticeType = extractKookNoticeType(raw);
+    if (!noticeType)
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(KOOK_NOTICE_PARTS_MAP, noticeType))
+        return false;
+    const event = raw;
+    const parts = mapNoticeParts('kook', noticeType);
+    const guildId = event.extra?.guild_id;
+    const userId = event.author_id ?? event.extra?.author?.id;
+    const sceneId = guildId != null
+        ? String(guildId)
+        : userId != null
+            ? String(userId)
+            : configId;
+    void sideEvents.receiveNotice(buildNotice(event, {
+        $id: `kook:${noticeType}:${event.msg_timestamp ?? Date.now()}:${sceneId}:${String(userId ?? '')}`,
+        $adapter: 'kook',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: sceneId,
+        $scene_type: parts.scene_type,
+        $sub_type: parts.sub_type,
+        $actor: senderFromId(userId, event.extra?.author?.username),
+        $timestamp: event.msg_timestamp ?? Date.now(),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'kook_side_event_failed',
+            endpoint: configId,
+            event: noticeType,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+    return true;
+}

package/lib/webhook.d.ts

@@ -3,11 +3,13 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
 import { type KookInboundMessage, type ResolvedKookWebhookConfig } from './protocol.js';
 export interface KookWebhookHandler {
     readonly config: ResolvedKookWebhookConfig;
     readonly isOpen: boolean;
     readonly selfId?: string;
+    readonly sideEvents?: SideEventGateway;
     admit(msg: KookInboundMessage): void;
     checkAndRememberSn(sn: number): boolean;
 }

package/lib/webhook.js

@@ -1,5 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { isKookWebhookChallenge, normalizeKookWebhookEvent, parseKookWebhookBody, readRequestBody, verifyKookWebhookToken, } from './protocol.js';
+import { receiveKookSideEvent } from './side-event-dispatch.js';
 const logger = getLogger('kook');
 export function registerKookWebhookRoutes(http, handler) {
     const path = handler.config.webhookPath;
@@ -67,6 +68,9 @@ export async function handleKookWebhookRequest(request, response, handler) {
     }
 }
 function handleKookWebhookEvent(event, handler) {
+    if (receiveKookSideEvent(handler.sideEvents, handler.config.id, event, logger)) {
+        return;
+    }
     const msg = normalizeKookWebhookEvent(event, {
         ignore: handler.config.ignore,
         selfId: handler.selfId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "7.0.12",
+  "version": "7.0.14",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,20 @@
   },
   "dependencies": {
     "kook-client": "^1.0.4",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.10",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.2"
+    "@zhin.js/permission": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.12",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.10",
-    "zhin.js": "6.0.10"
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -68,9 +68,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.12",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.10"
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/host-http": "1.0.11",
+    "zhin.js": "6.0.12"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -9,7 +9,7 @@ import type {
   EndpointManagement,
   EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -32,10 +32,12 @@ import {
   type CreateKookClient,
   type KookClientTransport,
 } from './ws.js';
+import { receiveKookSideEvent } from './side-event-dispatch.js';
 
 export interface KookEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedKookWebsocketConfig;
   readonly createClient?: CreateKookClient;
 }
@@ -191,6 +193,10 @@ export class KookWebsocketEndpoint implements EndpointInstance {
       const msg = normalizeKookMessage(raw);
       if (msg) this.admit(msg);
     });
+    const receiver = (client as { receiver?: { on(event: string, listener: (...args: unknown[]) => void): void } }).receiver;
+    receiver?.on('event', (raw) => {
+      receiveKookSideEvent(this.#options.sideEvents, this.#options.config.id, raw, this.#logger);
+    });
   }
 
   #requireClient(): KookClientTransport {
@@ -202,6 +208,7 @@ export class KookWebsocketEndpoint implements EndpointInstance {
 export interface KookWebhookEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedKookWebhookConfig;
   readonly createClient?: CreateKookClient;

package/src/protocol.ts

@@ -279,6 +279,8 @@ export function formatOutboundKmarkdown(payload: unknown): string {
       switch (item.type) {
         case 'text':
           return String(data.text ?? data.content ?? '');
+        case 'markdown':
+          return String(data.content ?? data.text ?? '');
         case 'at': {
           const id = String(data.user_id ?? data.qq ?? data.id ?? '');
           return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;

package/src/side-event-dispatch.ts

@@ -0,0 +1,55 @@
+import { buildNotice, mapNoticeParts, senderFromId, KOOK_NOTICE_PARTS_MAP } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import type { KookWebhookEventData } from './protocol.js';
+
+function extractKookNoticeType(raw: unknown): string | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const event = raw as KookWebhookEventData & { extra?: { type?: string } };
+  const extraType = event.extra?.type;
+  if (typeof extraType === 'string' && extraType) return extraType;
+  if (event.channel_type === 'NOTICE' && event.type != null) {
+    return String(event.type);
+  }
+  return null;
+}
+
+export function receiveKookSideEvent(
+  sideEvents: SideEventGateway | undefined,
+  configId: string,
+  raw: unknown,
+  logger: ReturnType<typeof getAdapterLogger>,
+): boolean {
+  if (!sideEvents) return false;
+  const noticeType = extractKookNoticeType(raw);
+  if (!noticeType) return false;
+  if (!Object.prototype.hasOwnProperty.call(KOOK_NOTICE_PARTS_MAP, noticeType)) return false;
+  const event = raw as KookWebhookEventData;
+  const parts = mapNoticeParts('kook', noticeType);
+  const guildId = event.extra?.guild_id;
+  const userId = event.author_id ?? event.extra?.author?.id;
+  const sceneId = guildId != null
+    ? String(guildId)
+    : userId != null
+      ? String(userId)
+      : configId;
+  void sideEvents.receiveNotice(buildNotice(event, {
+    $id: `kook:${noticeType}:${event.msg_timestamp ?? Date.now()}:${sceneId}:${String(userId ?? '')}`,
+    $adapter: 'kook' as never,
+    $endpoint: configId,
+    $type: 'notice',
+    $scene_id: sceneId,
+    $scene_type: parts.scene_type,
+    $sub_type: parts.sub_type,
+    $actor: senderFromId(userId, event.extra?.author?.username),
+    $timestamp: event.msg_timestamp ?? Date.now(),
+  })).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'kook_side_event_failed',
+      endpoint: configId,
+      event: noticeType,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+  return true;
+}

package/src/webhook.ts

@@ -3,6 +3,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
   isKookWebhookChallenge,
@@ -15,6 +16,7 @@ import {
   type KookWebhookFrame,
   type ResolvedKookWebhookConfig,
 } from './protocol.js';
+import { receiveKookSideEvent } from './side-event-dispatch.js';
 
 const logger = getLogger('kook');
 
@@ -22,6 +24,7 @@ export interface KookWebhookHandler {
   readonly config: ResolvedKookWebhookConfig;
   readonly isOpen: boolean;
   readonly selfId?: string;
+  readonly sideEvents?: SideEventGateway;
   admit(msg: KookInboundMessage): void;
   checkAndRememberSn(sn: number): boolean;
 }
@@ -108,6 +111,9 @@ function handleKookWebhookEvent(
   event: KookWebhookEventData,
   handler: KookWebhookHandler,
 ): void {
+  if (receiveKookSideEvent(handler.sideEvents, handler.config.id, event, logger)) {
+    return;
+  }
   const msg = normalizeKookWebhookEvent(event, {
     ignore: handler.config.ignore,
     selfId: handler.selfId,