@zhin.js/adapter-lark 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @zhin.js/adapter-lark
 
+## 1.1.6
+
+### Patch Changes
+
+- Updated dependencies [badcc1f]
+  - @zhin.js/core@1.1.41
+  - @zhin.js/feature-kit@1.1.3
+  - @zhin.js/adapter@1.1.17
+  - @zhin.js/agent-feature@1.1.4
+  - @zhin.js/skill@1.1.4
+  - @zhin.js/tool@1.1.4
+  - @zhin.js/host-http@1.1.4
+
+## 1.1.5
+
+### Patch Changes
+
+- b8c0f46: Keep native TypeScript process supervision at the CLI entry point so programmatic runtime startup does not respawn its caller. Pair the Lark proxy dispatcher with its Undici fetch implementation to support newer Node versions while retaining TLS verification and delivery uncertainty handling.
+- b9b3953: Stop synthesizing message IDs after outbound API calls. Missing real platform IDs now report an unknown delivery outcome and must not be retried automatically. DingTalk webhook success responses without a message ID therefore remain unconfirmed under the current receipt contract.
+
+  LINE reply and push use their actual sentMessages IDs. Reply HTTP 400 errors no longer trigger automatic push fallback: rejected or partially successful replies could otherwise duplicate a message. Locally expired cached reply tokens still select push before a reply request is made.
+
+- b9b3953: 新增飞书 WebSocket 长连接模式，保留默认 HTTP webhook。使用官方 SDK 处理协议帧与 ACK，共享端点生命周期管理重连和停止；等待实际握手、观测 SDK 连接状态，增加消息重推去重及启动缓冲。
+
+  发送失败仅记录数值 HTTP status 和平台 code；明确 4xx/业务拒绝保留 rejected，网络与服务端不确定响应保留 unknown，不再把权限拒绝统一包装成未知，也不输出原始响应体。
+
+  将 canonical reply 映射到原消息回复接口，修复字面量 [reply]。图片上传拒绝不再静默降级并确认丢失媒体的消息；保留实际错误分类及安全诊断。
+
+  图文复合消息及多图片使用原生 post 保留文本和图片顺序，修复只发送首图导致文本丢失的问题。
+
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
 ## 1.1.4
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP W
 - URL 验证挑战（`url_verification`）
 - Tenant Access Token 自动刷新
 - 支持飞书与 Lark 国际版 API 基址
-- canonical `markdown` 段编码为 `interactive` 卡片中的 `lark_md`
+- canonical `markdown` 段编码为 `interactive` JSON 2.0 卡片中的 `markdown`
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
@@ -70,7 +70,7 @@ plugins:
 | 飞书类型 | 入站 content（文本摘要） | 出站 wire |
 |----------|--------------------------|-----------|
 | text | 原文 | text |
-| markdown | 原文 | interactive（`lark_md`） |
+| markdown | 原文 | interactive（JSON 2.0 `markdown`） |
 | image | `[image]` | image（需 `file_key`） |
 | file | `[file: name]` | file |
 | audio / video / sticker | `[audio]` / `[video]` / `[sticker]` | — |
@@ -99,3 +99,59 @@ pnpm --filter @zhin.js/adapter-lark test
 | Tenant Token 获取失败 | 检查 `appId`、`appSecret` 与应用版本是否已发布 |
 | 群里 @机器人不触发 AI | 当前无法可靠判定 bot open_id；使用显式 AI 前缀 |
 | 能收不能发 | 检查机器人消息权限、可见范围与应用是否已加入群聊 |
+
+## 飞书长连接接收
+
+`endpoints[].mode` 支持 `webhook`（兼容默认）和 `websocket`。长连接适用于企业自建飞书应用；开发者后台「事件与回调」选择「使用长连接接收事件」，订阅 `im.message.receive_v1`，启用机器人并发布到测试范围。
+
+```yaml
+mode: websocket
+endpoints:
+  - id: feishu-bot
+    appId: ${LARK_APP_ID}
+    appSecret: ${LARK_APP_SECRET}
+```
+
+长连接不注册 HTTP 路由，也不需要公网域名、`verificationToken` 或 `encryptKey`。出站仍走 OpenAPI。SDK 处理协议 ACK 和心跳；共享 `createEndpointLifecycle` 负责停止与重连，SDK 内建重连关闭。连接启动只在 SDK `onReady` 握手完成后成功，30 秒未完成则失败；运行中每秒读取 SDK 连接状态。每个 endpoint 对消息 ID 做 5 分钟去重（最多 10,000 项）；这是进程内平台重推防护，跨重启业务去重由应用自己的持久化记录负责。
+
+启动到 generation 开放之间最多缓存 100 条消息，停止清空；超过上限会明确告警。事件处理不等待下游回复，保证 SDK ACK 不被回复链路阻塞。同应用多客户端是集群分发，不能用于验证两个 Bot 的账号隔离，应使用不同应用。
+
+官方说明：[Node SDK 长连接](https://github.com/larksuite/node-sdk#long-connection)。长连接实现及发布 SDK 合同有本地回归；实机接收、断线恢复与平台权限仍需实际应用验收。
+
+出站 canonical `reply` 段使用飞书原消息 `message_id` 调用正式回复接口，引用标记不作为正文发送。图片需授予 `im:resource:upload`（或平台兼容的 `im:resource`）并完成发布。上传被拒绝或缺失真实 `image_key` 时整次发送失败，不发送文字替代品以冒充图片成功；诊断仅输出数值 status/code。撤回仍走 DELETE message API，平台权限或业务拒绝会向调用方透传。
+
+文本与图片混排、多图片使用原生 `post`，保留文本和图片的原始顺序；单图片仍使用原生图片消息。回复元数据可与 post 组合。
+
+### 原生 Markdown、分享与按钮
+
+Canonical `markdown` 使用飞书 `interactive` JSON 2.0 消息中的 `markdown` 组件；普通文字保留为 `plain_text`，图片上传后可放入同一张卡片。`share` 映射为标题、描述和打开 URL 的原生卡片按钮，不声称提供平台网页预览抓取。Canonical `keyboard` 按行映射为原生 action/button，回传 `value.zhin_payload`。
+
+应用后台须启用 **card.action.trigger** 卡片回调，与消息接收使用同样的长连接或 HTTP 回调入口。适配器立即返回 ACK，不等待业务回复。回调映射真实 operator.open_id、context.open_chat_id 和 sourceMessageId，且只关联当前端点近 5 分钟内成功发送的卡片，保留原会话/线程信息。重启后未关联的旧卡片点击会丢弃；重复回调去重。仅本地 SDK/HTTP 合同与回归已验证，实机点击和权限配置仍需验收。
+
+参考：[飞书卡片回调结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)、[按钮组件](https://open.feishu.cn/document/common-capabilities/message-card/add-card-interaction/interactive-components/button)。
+
+Markdown 单独卡片使用 JSON 2.0，以支持行内代码；v1 `lark_md` 的反引号实机显示为字面量，不能作为完整 Markdown 通过证据。当前 Markdown 与 share/keyboard 混排明确 unsupported，避免退回 v1 丢失代码样式。JSON2 行内代码仍须新的客户端实机验收，不因本地结构回归算通过。
+# 长连接 TCP 故障验收
+
+可选 `streamProxy: { port: 18443, serverName: "实际网关域名" }` 仅将 WSS TCP 路由到 `127.0.0.1`；已安装 SDK 的 WSClient `agent` 只传给 WebSocket，discovery/OpenAPI 不使用它。HTTP Host、私有 URL/query、TLS SNI 和证书链/域名校验仍为真实平台，不关闭验证；域名变化明确拒绝且只输出安全 hostname，不回退直连。Agent 随连接关闭销毁，重连仍由统一 Endpoint lifecycle 管理。
+
+验收 example 支持进程覆盖 `LARK_STREAM_PROXY_PORT` / `LARK_STREAM_PROXY_SERVER_NAME`，需同时填写，留空正常直连。先用占位域名获取拒绝日志中的实际 gateway hostname，再启动 `scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host 实际网关域名 --upstream-port 443 --port 18443 --control-port 18444` 并将 serverName 同步为此域名。保留已有 `.env`，只在启动命令临时覆盖变量。
+
+确认正常入站后 POST 代理 `/cut`，观察 WSS 关闭及 transportState 进入重连；POST `/recover` 后等待重新 open，再发送唯一新 probe并确认入站/可见回包。切断的仅 WSS，OpenAPI出站仍直连，不足以证明所有网络恢复、发送重试或离线消息无损。网关变化应停止并更新固定上游；完成后停止代理、移除临时覆盖。实机结果单独记录，本地 SDK/TLS 回归不当作平台通过。
+
+### 出站 HTTP 故障边界
+
+本地真实 HTTP 服务回归覆盖服务器收到请求后断连接、500、408、429、403 与成功 HTTP 中明确平台拒绝；每个样本只有一个消息 POST。408/5xx/丢失结果保持 unknown，平台拒绝为 rejected；不自动重发。现有 Stream 代理只用于 WSS，不能证明 API 故障。`apiBaseUrl` 能用于本地无凭据 HTTP fixture，但把真实 HTTPS 换成本地 HTTP 会改变 TLS 身份，不应这样做实机验收；保留真实身份的 API 专用 TLS 路由入口仍需独立实现。
+
+### 飞书出站 API 受控故障代理（默认关闭）
+
+可选 `webApiProxy: { port: 18094 }` 仅改变出站 API 的 TCP 连接地址为 `127.0.0.1`。API URL、HTTP Host 和 TLS SNI 仍为 `open.feishu.cn`，始终验证证书链与该域名；不支持配置 hostname、CA 或关闭 TLS 校验。仅允许官方 `https://open.feishu.cn/open-apis`，不改变 `apiBaseUrl`，不兼容 Larksuite origin。与长连接 `streamProxy` 独立。Endpoint 停止会销毁自身 dispatcher/连接，重启可建立新连接；没有自动发送重试。
+
+隔离验收启动方式（不改 `.env`）：
+
+```sh
+node scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host open.feishu.cn --upstream-port 443 --port 18094 --control-port 18095
+LARK_WEB_API_PROXY_PORT=18094 pnpm --filter platform-acceptance-bot start:lark
+```
+
+控制端使用工具指南的 cut/recover。恢复后发送新 probe；断线发生在 POST 接收后时结果保持 unknown，不自动重投旧样本。此入口适用于专用测试实例，不能用本地 TLS fixture 冒充真实飞书恢复。默认未配置时仍使用原有 global fetch 直连。代理使用同一依赖版本的 [undici fetch](https://github.com/nodejs/undici/blob/v6.28.0/docs/docs/api/Fetch.md) 与 dispatcher，避免 Node 内置版本的 handler 合同差异；采用 [undici 6.x Agent connect 合同](https://github.com/nodejs/undici/blob/v6.28.0/docs/docs/api/Agent.md)。

package/adapters/lark/index.js

@@ -17,7 +17,7 @@ export default defineAdapter({
     // 卡片交互未接入出站通道，交互段降级纯文本。
     segments: {
         outboundMedia: ['url', 'upload'],
-        interactive: 'text',
+        interactive: 'native',
         markdown: 'native',
     },
     create(context) {
@@ -25,11 +25,11 @@ export default defineAdapter({
         // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
         context.use(larkRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
-            mode: 'webhook',
+            mode: config.mode,
         });
         return new LarkEndpoint({
             id: context.id,
-            http: context.use(httpHostToken),
+            ...(config.mode === 'webhook' ? { http: context.use(httpHostToken) } : {}),
             config,
         });
     },

package/adapters/lark/index.ts

@@ -22,7 +22,7 @@ export default defineAdapter<LarkEndpointConfig>({
   // 卡片交互未接入出站通道，交互段降级纯文本。
   segments: {
     outboundMedia: ['url', 'upload'],
-    interactive: 'text',
+    interactive: 'native',
     markdown: 'native',
   },
   create(context) {
@@ -30,11 +30,11 @@ export default defineAdapter<LarkEndpointConfig>({
     // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
     context.use(larkRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
-      mode: 'webhook',
+      mode: config.mode,
     });
     return new LarkEndpoint({
       id: context.id,
-      http: context.use(httpHostToken),
+      ...(config.mode === 'webhook' ? { http: context.use(httpHostToken) } : {}),
       config,
     });
   },

package/lib/cards.d.ts

@@ -0,0 +1,23 @@
+import type { LarkSendBody, LarkWireSegment } from './protocol.js';
+/** Feishu JSON card v1: ordered native rich text, link and button components. */
+export declare function formatLarkCard(items: Array<string | LarkWireSegment>): LarkSendBody;
+export interface LarkCardAction {
+    readonly token?: string;
+    readonly context?: {
+        readonly open_message_id?: string;
+        readonly open_chat_id?: string;
+    };
+    readonly open_message_id?: string;
+    readonly open_chat_id?: string;
+    readonly operator?: {
+        readonly open_id?: string;
+        readonly user_id?: string;
+    };
+    readonly action?: {
+        readonly tag?: string;
+        readonly value?: {
+            readonly zhin_payload?: unknown;
+            readonly zhin_button_id?: unknown;
+        };
+    };
+}

package/lib/cards.js

@@ -0,0 +1,77 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Feishu JSON card v1: ordered native rich text, link and button components. */
+export function formatLarkCard(items) {
+    const elements = [];
+    let replyTo;
+    for (const item of items) {
+        if (typeof item === 'string') {
+            elements.push({ tag: 'div', text: { tag: 'plain_text', content: item } });
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'reply':
+                replyTo = String(data.message_id ?? '') || undefined;
+                break;
+            case 'text':
+                elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.text ?? data.content ?? '') } });
+                break;
+            case 'markdown':
+                elements.push({ tag: 'div', text: { tag: 'lark_md', content: String(data.content ?? data.text ?? '') } });
+                break;
+            case 'image': {
+                const media = data.media;
+                if (media?.kind !== 'file' || !media.value)
+                    throw unsupported();
+                elements.push({ tag: 'img', img_key: media.value, alt: { tag: 'plain_text', content: 'Image' } });
+                break;
+            }
+            case 'share': {
+                const url = String(data.url ?? '');
+                if (!/^https?:\/\//.test(url))
+                    throw unsupported();
+                elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.title ?? url) } });
+                if (data.description)
+                    elements.push({ tag: 'div', text: { tag: 'plain_text', content: String(data.description) } });
+                elements.push({ tag: 'action', actions: [{ tag: 'button', text: { tag: 'plain_text', content: '打开链接' }, url }] });
+                break;
+            }
+            case 'keyboard': {
+                const rows = data.rows;
+                if (!Array.isArray(rows) || rows.length === 0)
+                    throw unsupported();
+                for (const row of rows) {
+                    if (!Array.isArray(row) || !row.length || row.length > 5)
+                        throw unsupported();
+                    const actions = row.map(button => {
+                        if (!button.label || (!button.payload && !button.url))
+                            throw unsupported();
+                        return { tag: 'button', text: { tag: 'plain_text', content: button.label },
+                            ...(button.url ? { url: button.url } : { value: { zhin_payload: button.payload, zhin_button_id: button.id } }) };
+                    });
+                    elements.push({ tag: 'action', actions });
+                }
+                break;
+            }
+            default: throw unsupported();
+        }
+    }
+    // JSON 1.0 lark_md does not render inline code. Use the SDK's JSON 2.0
+    // markdown component for Markdown cards; keep validated v1 action cards.
+    const hasMarkdown = items.some(item => typeof item !== 'string' && item.type === 'markdown');
+    const hasActions = items.some(item => typeof item !== 'string' && ['share', 'keyboard'].includes(item.type));
+    if (hasMarkdown && hasActions)
+        throw new EndpointDeliveryError('unsupported_operation', 'Mixed Markdown and action cards require JSON 2.0 action support', 'not_sent');
+    if (hasMarkdown) {
+        const bodyElements = elements.map(element => {
+            const row = element;
+            if (row.tag !== 'div')
+                return element;
+            const text = row.text;
+            return { tag: 'markdown', content: text.tag === 'lark_md' ? text.content : text.content.replace(/[\\`*_{}[\]()#+.!|>~-]/g, '\\$&') };
+        });
+        return { msg_type: 'interactive', content: JSON.stringify({ schema: '2.0', body: { elements: bodyElements } }), ...(replyTo ? { replyTo } : {}) };
+    }
+    return { msg_type: 'interactive', content: JSON.stringify({ config: { wide_screen_mode: true }, elements }), ...(replyTo ? { replyTo } : {}) };
+}
+function unsupported() { return new EndpointDeliveryError('unsupported_operation', 'Unsupported or malformed Lark card segment', 'not_sent'); }

package/lib/endpoint.d.ts

@@ -1,9 +1,10 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { LarkCardAction } from './cards.js';
+import { Endpoint, type EndpointTransportState, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { resolveMediaBinary } from './media-upload.js';
 import { type LarkMessage, type ResolvedLarkConfig } from './protocol.js';
+import { type LarkLongConnectionFactory } from './long-connection.js';
 export type LarkFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
@@ -17,7 +18,8 @@ export type LarkFetch = (url: string, init?: {
 }>;
 export interface LarkEndpointOptions {
     readonly id: CapabilityId;
-    readonly http: HttpHost;
+    readonly http?: HttpHost;
+    readonly longConnectionFactory?: LarkLongConnectionFactory;
     readonly config: ResolvedLarkConfig;
     readonly fetch?: LarkFetch;
 }
@@ -72,16 +74,19 @@ export declare class LarkEndpoint extends Endpoint<LarkClient> {
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedLarkConfig;
+    get transportState(): EndpointTransportState | undefined;
     start(): Promise<void>;
     open(): void;
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
-    /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
-    uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null>;
+    /** Upload must succeed before issuing a message; dropped media is never confirmed. */
+    uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: LarkMessage): void;
+    /** Only correlate callbacks to a card actually sent by this endpoint. */
+    admitCardAction(event: LarkCardAction): void;
     admitPlatform(name: string, event: unknown): void;
     getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
     getChatInfo(chatId: string): Promise<unknown>;