@zhin.js/adapter-lark 6.0.13 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @zhin.js/adapter-lark
 
+## 7.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
+## 6.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
+
 ## 6.0.13
 
 ### Patch Changes

package/README.md

@@ -8,6 +8,7 @@ Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP W
 - URL 验证挑战（`url_verification`）
 - Tenant Access Token 自动刷新
 - 支持飞书与 Lark 国际版 API 基址
+- canonical `markdown` 段编码为 `interactive` 卡片中的 `lark_md`
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
@@ -70,6 +71,7 @@ plugins:
 | 飞书类型 | 入站 content（文本摘要） | 出站 wire |
 |----------|--------------------------|-----------|
 | text | 原文 | text |
+| markdown | 原文 | interactive（`lark_md`） |
 | image | `[image]` | image（需 `file_key`） |
 | file | `[file: name]` | file |
 | audio / video / sticker | `[audio]` / `[video]` / `[sticker]` | — |

package/adapters/lark.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/lark.ts` → defineAdapter.
  */
 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 { LarkEndpoint } from "../lib/endpoint.js";
 import { resolveLarkConfig, } from "../lib/protocol.js";
@@ -11,12 +11,15 @@ import { larkRuntimeStateToken } from "../lib/lark-runtime-state.js";
 export { LarkEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
     // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+    // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
     // 卡片交互未接入出站通道，交互段降级纯文本。
     segments: {
         outboundMedia: ['url', 'upload'],
         interactive: 'text',
+        markdown: 'native',
     },
     create(context) {
         const config = resolveLarkConfig(context.config);
@@ -28,6 +31,7 @@ export default defineAdapter({
         return new LarkEndpoint({
             id: context.id,
             gateway: context.use(messageGatewayToken),
+            sideEvents: context.use(sideEventGatewayToken),
             http: context.use(httpHostToken),
             config,
         });

package/adapters/lark.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/lark.ts` → defineAdapter.
  */
 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 { LarkEndpoint } from '../src/endpoint.js';
 import {
@@ -16,12 +16,15 @@ export type { LarkEndpointOptions, LarkFetch } from '../src/endpoint.js';
 
 export default defineAdapter<LarkAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
   // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+  // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
   // 卡片交互未接入出站通道，交互段降级纯文本。
   segments: {
     outboundMedia: ['url', 'upload'],
     interactive: 'text',
+    markdown: 'native',
   },
   create(context) {
     const config = resolveLarkConfig(context.config);
@@ -33,6 +36,7 @@ export default defineAdapter<LarkAdapterConfig>({
     return new LarkEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
+      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       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 EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { resolveMediaBinary } from './media-upload.js';
@@ -18,6 +18,7 @@ export type LarkFetch = (url: string, init?: {
 export interface LarkEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedLarkConfig;
     readonly fetch?: LarkFetch;
@@ -32,6 +33,7 @@ export declare class LarkEndpoint implements EndpointInstance {
      * listChannels（无频道/guild 概念）、写操作（审批/踢人/禁言等本轮不在范围内）。
      */
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: LarkEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;

package/lib/endpoint.js

@@ -3,6 +3,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
 import { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
@@ -38,6 +39,7 @@ export class LarkEndpoint {
         },
         listGroupMembers: (groupId) => this.#listAllPages(`/im/v1/chats/${encodeURIComponent(groupId)}/members`, { member_id_type: 'open_id' }),
     });
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #routeReleases = [];
     #accessToken = { token: '', expires_in: 0, timestamp: 0 };
     #refreshPromise = null;

package/lib/protocol.js

@@ -153,6 +153,7 @@ export function formatOutboundBody(payload) {
         : payload && typeof payload === 'object' && 'type' in payload
             ? [payload]
             : [];
+    const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
     if (items.length === 0) {
         const text = payload == null
             ? ''
@@ -176,6 +177,9 @@ export function formatOutboundBody(payload) {
             case 'text':
                 textParts.push(String(data.content ?? data.text ?? ''));
                 break;
+            case 'markdown':
+                textParts.push(String(data.content ?? data.text ?? ''));
+                break;
             case 'at':
                 textParts.push(`<at user_id="${String(data.id ?? '')}">${String(data.name || data.id || '')}</at>`);
                 break;
@@ -230,6 +234,17 @@ export function formatOutboundBody(payload) {
     }
     if (media)
         return media;
+    if (hasMarkdown) {
+        return {
+            msg_type: 'interactive',
+            content: JSON.stringify({
+                elements: [{
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: textParts.join('') },
+                    }],
+            }),
+        };
+    }
     return {
         msg_type: 'text',
         content: JSON.stringify({ text: textParts.join('') }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "6.0.13",
+  "version": "7.0.0",
   "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/permission": "1.0.2",
-    "zhin.js": "6.0.11"
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/permission": "1.0.3",
+    "zhin.js": "6.0.13"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -69,8 +69,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.13",
-    "zhin.js": "6.0.11"
+    "@zhin.js/agent": "1.1.15",
+    "zhin.js": "6.0.13"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -3,8 +3,15 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import type { EndpointGroup, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointGroup,
+  type EndpointInstance,
+  type EndpointManagement,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+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';
@@ -49,6 +56,7 @@ export type LarkFetch = (
 export interface LarkEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedLarkConfig;
   readonly fetch?: LarkFetch;
@@ -85,6 +93,7 @@ export class LarkEndpoint implements EndpointInstance {
       { member_id_type: 'open_id' },
     ),
   });
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
   #routeReleases: HttpRouteRegistration[] = [];
   #accessToken: AccessToken = { token: '', expires_in: 0, timestamp: 0 };
   #refreshPromise: Promise<string> | null = null;

package/src/protocol.ts

@@ -272,6 +272,7 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
     : payload && typeof payload === 'object' && 'type' in (payload as object)
       ? [payload as LarkWireSegment]
       : [];
+  const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
 
   if (items.length === 0) {
     const text = payload == null
@@ -298,6 +299,9 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
       case 'text':
         textParts.push(String(data.content ?? data.text ?? ''));
         break;
+      case 'markdown':
+        textParts.push(String(data.content ?? data.text ?? ''));
+        break;
       case 'at':
         textParts.push(
           `<at user_id="${String(data.id ?? '')}">${String(data.name || data.id || '')}</at>`,
@@ -352,6 +356,17 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
   }
 
   if (media) return media;
+  if (hasMarkdown) {
+    return {
+      msg_type: 'interactive',
+      content: JSON.stringify({
+        elements: [{
+          tag: 'div',
+          text: { tag: 'lark_md', content: textParts.join('') },
+        }],
+      }),
+    };
+  }
   return {
     msg_type: 'text',
     content: JSON.stringify({ text: textParts.join('') }),