@zhin.js/adapter-lark 1.1.20 → 1.1.21

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @zhin.js/adapter-lark
 
+## 1.1.21
+
+### Patch Changes
+
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- 26fda97: Deliver validated final answers progressively through configured QQ C2C, Telegram drafts, Slack streams, Lark cards and Sandbox updates. Keep complete-message delivery for unsupported scenes, disabled adapters and outbound middleware that does not explicitly support revisions. Discord retains complete-message delivery.
+
+  Preserve source-account leases, media order and confirmed delivery facts across cancellation, capacity rollover and follow-up answer phases. Preview drafts and uncertain outcomes do not become sent history. Bound each reply's semantic snapshot to 1 MiB, retain confirmed prefixes on failure and avoid replaying published answers.
+
+  Project the latest confirmed message revision into paginated conversation history and synchronize Sandbox message updates across connections. Existing adapter implementations and complete-send callers remain compatible.
+
+- 976886c: Preserve confirmed progressive reply content, routing and delivery evidence across cancellation, rollover and closing failures without replaying published text. Keep error dispositions and actual message references, and abort the owning provider request when its functional text consumer fails.
+
+  Enable native Sandbox Markdown through the real Core projection so Console updates retain formatting in one message. Preserve instance-level streaming opt-outs, recall tombstones and multi-page synchronization. The first safe content is immediate; later updates retain the configured pacing, including large valid intervals.
+
+  Keep Slack and Lark Markdown streaming within the current physical message. When continuation formatting cannot be verified, stop and retain confirmed content instead of replaying or silently changing it to plain text. Plain-text continuations retain their original reply route.
+
+  Use rebuildable revision metadata and indexes in the existing conversation event table for bounded SQL history reads. Original event JSON and retention remain unchanged; older writers and models keep their compatible read path. Supported adapter streaming remains enabled by default, with complete-message fallback for disabled settings or outbound middleware without incremental: true.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/host-http@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/skill@1.1.12
+
 ## 1.1.20
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,18 @@ Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP W
 - canonical `markdown` 段编码为 `interactive` JSON 2.0 卡片中的 `markdown`
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
+## 渐进式回复
+
+`streaming` 默认 `true`，可在插件或单个 endpoint 配置中设为 `false`，恢复普通完整发送。正文和 Markdown 使用 CardKit JSON 2.0 流式卡片：先创建实体并发送卡片引用，随后以累计正文更新同一组件，结束时关闭 `streaming_mode`。内容更新与收尾共用严格递增的 `sequence`。
+
+需要应用具有 CardKit 创建与更新卡片及当前会话发送权限。引用目标和 @ 前缀保持不变；资源创建成功不等于聊天消息已经送达，消息发送或更新结果未知时不重新创建或发布。媒体和按钮继续经统一发送链按原始顺序处理。
+
+`streamingIntervalMs` 默认 `1000` 毫秒，用于后续回复更新间隔；首段立即发送，中间更新由统一回复控制器合并。
+
+平台明确拒绝已有卡片的更新并报告流式超时或容量超限时，纯文字回复保留已确认正文，再用新卡片继续未发送部分。首条内容自身超限时明确报错，不重复创建或截断原文。卡片流式模式在开启 10 分钟后自动关闭，详见[流式更新卡片](https://open.feishu.cn/document/cardkit-v1/streaming-updates-openapi-overview)。
+
+纯文字可以在已确认的容量或时限边界续条。Markdown 保留单容器内的流式发送；已确认的 Markdown 卡片需要续容器时，无法恢复其渲染状态，会停止并保留已确认部分，不降级为纯文本。关闭流式模式失败时，正文的确认记录会保留，关闭结果仍明确记录为失败或未知。
+
 ## 安装
 
 ```bash

package/lib/adapter.js

@@ -7,7 +7,7 @@ export class LarkAdapter extends Adapter {
     #context;
     constructor(context) { super(); this.#context = context; }
     get configurationIdentityFields() { return ['id', 'appId', 'isFeishu']; }
-    get configurationUpdateFields() { return ['appSecret', 'encryptKey', 'verificationToken', 'mode', 'webhookPath', 'apiBaseUrl', 'webApiProxy', 'streamProxy']; }
+    get configurationUpdateFields() { return ['appSecret', 'encryptKey', 'verificationToken', 'mode', 'webhookPath', 'apiBaseUrl', 'webApiProxy', 'streamProxy', 'streaming', 'streamingIntervalMs']; }
     get configurationIdentityProbeFields() { return ['appSecret', 'apiBaseUrl']; }
     async identifyConfiguration(input, signal, _changed) {
         const config = resolveLarkConfig(input), client = new LarkClient({ id: this.descriptor.id, config, signal });

package/lib/client.d.ts

@@ -53,6 +53,7 @@ export declare class LarkClient extends SdkClient {
      */
     protected readonly endpointManagement: EndpointManagement;
     protected readonly endpointControl: EndpointControl;
+    protected get endpointStreaming(): import('zhin.js/adapter').EndpointStreaming | undefined;
     protected configName(): string;
     /** Native protocol work runs here; Endpoint attaches the framework receipt without replacing SDK APIs. */
     protected receiveInboundCallback<T>(receive: () => T | Promise<T>): Promise<T>;

package/lib/client.js

@@ -14,6 +14,7 @@ import { formatInboundContent, formatOutboundBody, generateMessageId, larkInboun
 import { normalizeLarkSenderForPermit } from './platform-permit.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 import { createLarkLongConnection } from './long-connection.js';
+import { openLarkReplyStream, supportsLarkReplyStream } from './reply-stream.js';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
 /** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
@@ -48,6 +49,13 @@ export class LarkClient extends SdkClient {
         listGroupMembers: ({ groupId, signal }) => this.#listAllPages(`/im/v1/chats/${encodeURIComponent(groupId)}/members`, { params: { member_id_type: 'open_id' }, signal }),
     });
     endpointControl = createRecallEndpointControl((id, signal) => this.recallMessage(id, { signal }));
+    get endpointStreaming() {
+        return this.config.streaming !== false ? { mode: 'card',
+            minIntervalMs: this.config.streamingIntervalMs ?? 1000,
+            supports: supportsLarkReplyStream,
+            open: request => openLarkReplyStream(request, (path, options) => this.#request(path, options)),
+        } : undefined;
+    }
     #routeReleases = [];
     #open = false;
     #started = false;

package/lib/console-spec.js

@@ -6,6 +6,8 @@ export const larkConsoleSpec = {
         { key: 'appSecret', required: true, env: true, description: '飞书 App Secret', descriptionI18n: { en: 'Lark app secret' } },
         { key: 'encryptKey', env: true, description: '事件加密 key', descriptionI18n: { en: 'Event encryption key' } },
         { key: 'verificationToken', env: true, description: '事件验证 token', descriptionI18n: { en: 'Event verification token' } },
+        { key: 'streaming', type: 'boolean', description: '生成时逐步显示回复', descriptionI18n: { en: 'Show replies progressively while generating' } },
+        { key: 'streamingIntervalMs', type: 'number', description: '回复更新间隔（毫秒）', descriptionI18n: { en: 'Reply update interval in milliseconds' } },
     ],
     docsUrl: 'https://zhin.js.org/adapters/lark',
     readPermission: 'lark:read',

package/lib/endpoint.js

@@ -1,5 +1,6 @@
 import { createEndpointSpecification, endpointSpec } from 'zhin.js/adapter';
 import { LarkClient } from './client.js';
+import { createLarkSelfProfile } from './self-profile.js';
 /** Actual protocol Client; framework lifecycle and admission stay in their symbol namespace. */
 export class LarkEndpoint extends LarkClient {
     [endpointSpec] = this.#createSpecification();
@@ -12,6 +13,8 @@ export class LarkEndpoint extends LarkClient {
             name: this.configName(),
             control: this.endpointControl,
             management: this.endpointManagement,
+            streaming: this.endpointStreaming,
+            profile: createLarkSelfProfile({ client: this, reportAccount: id => this[endpointSpec].reportSelfUserId(id) }),
         };
         Object.defineProperty(hooks, 'transportState', { get: () => this.transportState });
         return createEndpointSpecification(this, hooks);

package/lib/i18n.d.ts

@@ -1 +1 @@
-export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "openLink" | "link" | "message", values?: import("zhin.js").MessageValues) => string;
+export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "link" | "openLink" | "message", values?: import("zhin.js").MessageValues) => string;

package/lib/protocol.d.ts

@@ -1,8 +1,12 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 import type { Locale } from 'zhin.js/i18n';
 import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface LarkEndpointConfig {
+export interface LarkEndpointConfig extends EndpointProfileConfiguration {
+    /** Native streaming cards are enabled unless explicitly disabled. */
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
     readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
     readonly id: string;
@@ -16,6 +20,8 @@ export interface LarkEndpointConfig {
     readonly isFeishu?: boolean;
 }
 export interface ResolvedLarkConfig {
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
     readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
     readonly context: 'lark';

package/lib/protocol.js

@@ -9,6 +9,10 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { formatLarkCard } from './cards.js';
 const logger = getLogger('lark');
 export function resolveLarkConfig(config) {
+    if (config.streaming !== undefined && typeof config.streaming !== 'boolean')
+        throw new TypeError('Lark streaming must be a boolean');
+    if (config.streamingIntervalMs !== undefined && (!Number.isSafeInteger(config.streamingIntervalMs) || config.streamingIntervalMs < 0))
+        throw new TypeError('Lark streamingIntervalMs must be a non-negative integer');
     if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
         || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName)))
         throw new TypeError('Invalid Lark streamProxy port/serverName');
@@ -34,6 +38,8 @@ export function resolveLarkConfig(config) {
         ...(config.webApiProxy ? { webApiProxy: config.webApiProxy } : {}),
         ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
         context: 'lark',
+        streaming: config.streaming !== false,
+        streamingIntervalMs: config.streamingIntervalMs ?? 1000,
         mode,
         id,
         appId,

package/lib/reply-stream.d.ts

@@ -0,0 +1,12 @@
+import type { EndpointMessageStream, EndpointStreamRequest } from 'zhin.js/adapter';
+import type { LarkApiResponse } from './protocol.js';
+export interface LarkStreamRequestOptions {
+    readonly method: 'POST' | 'PUT' | 'PATCH';
+    readonly body: Record<string, unknown>;
+    readonly signal?: AbortSignal;
+}
+type Request = (path: string, options: LarkStreamRequestOptions) => Promise<LarkApiResponse>;
+export declare function supportsLarkReplyStream(request: Pick<EndpointStreamRequest, 'conversation' | 'source'>): boolean;
+/** CardKit text updates use cumulative content and one sequence across content/settings. */
+export declare function openLarkReplyStream(request: EndpointStreamRequest, send: Request): EndpointMessageStream | undefined;
+export {};

package/lib/reply-stream.js

@@ -0,0 +1,142 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+export function supportsLarkReplyStream(request) {
+    return !request.conversation.threadId && !request.conversation.parent;
+}
+/** CardKit text updates use cumulative content and one sequence across content/settings. */
+export function openLarkReplyStream(request, send) {
+    // CardKit has no verified way to restore a previous card's Markdown renderer state.
+    if (request.format === 'markdown' && request.continuation)
+        return undefined;
+    const prefix = request.prefix ?? [];
+    if (prefix.some(segment => segment.type !== 'reply' && segment.type !== 'mention')
+        || !supportsLarkReplyStream(request))
+        return undefined;
+    const reply = prefix.find(segment => segment.type === 'reply');
+    const replyTo = (reply && 'message_id' in reply.data ? reply.data.message_id : undefined) ?? request.continuation?.replyTo;
+    const mentions = prefix.filter(segment => segment.type === 'mention').map(segment => {
+        const target = String('target' in segment.data ? segment.data.target : '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        return `<at id="${target}"></at>`;
+    }).join('');
+    let cardId;
+    let messageId;
+    let sequence = 0;
+    let acceptedText = '';
+    let cancelled = false;
+    let finished = false;
+    let exhausted = false;
+    let platformClosed = false;
+    let failure;
+    let lastAcknowledgement;
+    const acknowledge = () => lastAcknowledgement = Object.freeze({ status: messageId ? 'sent' : 'buffered',
+        ...(messageId ? { messageId } : {}), acceptedText, ...(exhausted ? { exhausted: true } : {}) });
+    const bodyText = (text) => request.format === 'markdown' ? text : text.replace(/[\\`*_{}[\]()#+.!|>~-]/g, '\\$&');
+    const assertActive = () => {
+        if (cancelled || request.signal?.aborted)
+            throw new EndpointDeliveryError('stream_cancelled', 'Lark stream was cancelled before submission', 'not_sent');
+    };
+    const call = (path, method, body) => {
+        assertActive();
+        return send(path, { method, body, signal: request.signal });
+    };
+    const write = async (text) => {
+        if (failure)
+            throw failure;
+        assertActive();
+        if (finished)
+            return acknowledge();
+        if (!text.startsWith(acceptedText))
+            throw new EndpointDeliveryError('stream_rewrite', 'A confirmed reply prefix cannot change', 'not_sent');
+        if (exhausted)
+            return acknowledge();
+        if (text === acceptedText)
+            return acknowledge();
+        if (!cardId) {
+            try {
+                const card = await call('/cardkit/v1/cards', 'POST', { type: 'card_json', data: JSON.stringify({
+                        schema: '2.0', config: { streaming_mode: true, update_multi: true },
+                        body: { elements: [
+                                ...(mentions ? [{ tag: 'markdown', element_id: 'zhin_prefix', content: mentions }] : []),
+                                { tag: 'markdown', element_id: 'zhin_reply', content: bodyText(text) },
+                            ] },
+                    }) });
+                cardId = typeof card.data?.card_id === 'string' && card.data.card_id ? card.data.card_id : undefined;
+                if (!cardId)
+                    throw new Error('CardKit returned no card ID');
+            }
+            catch (error) {
+                // A card resource may exist, but no chat-message request has been attempted.
+                failure = new EndpointDeliveryError('stream_resource_unavailable', 'Lark streaming card could not be prepared', 'not_sent', { cause: error });
+                throw failure;
+            }
+        }
+        try {
+            if (!messageId) {
+                const message = await call(typeof replyTo === 'string' && replyTo
+                    ? `/im/v1/messages/${encodeURIComponent(replyTo)}/reply` : '/im/v1/messages?receive_id_type=chat_id', 'POST', {
+                    ...(replyTo ? {} : { receive_id: request.conversation.id }),
+                    msg_type: 'interactive', content: JSON.stringify({ type: 'card', data: { card_id: cardId } }),
+                });
+                if (typeof message.data?.message_id !== 'string' || !message.data.message_id.trim()) {
+                    throw new EndpointDeliveryError('delivery_unconfirmed', 'Lark stream returned no message ID', 'unknown');
+                }
+                messageId = message.data.message_id;
+            }
+            else {
+                await call(`/cardkit/v1/cards/${encodeURIComponent(cardId)}/elements/zhin_reply/content`, 'PUT', {
+                    content: bodyText(text), sequence: ++sequence,
+                });
+            }
+            acceptedText = text;
+            return acknowledge();
+        }
+        catch (error) {
+            const code = rejectedPlatformCode(error);
+            if (messageId && acceptedText && (code === 200850 || code === 200860)) {
+                // The rejected update contributed no source. Timeout explicitly closes the
+                // prior card; capacity requires closing only its last confirmed contents.
+                exhausted = true;
+                platformClosed = code === 200850;
+                return acknowledge();
+            }
+            failure = streamFailure(error);
+            throw failure;
+        }
+    };
+    return {
+        get lastAcknowledgement() { return lastAcknowledgement; },
+        write,
+        async finish(text) {
+            if (finished)
+                return acknowledge();
+            await write(text);
+            if (cardId && messageId && !platformClosed) {
+                try {
+                    await call(`/cardkit/v1/cards/${encodeURIComponent(cardId)}/settings`, 'PATCH', {
+                        settings: JSON.stringify({ config: { streaming_mode: false } }), sequence: ++sequence,
+                    });
+                }
+                catch (error) {
+                    if (rejectedPlatformCode(error) === 200850) {
+                        platformClosed = true;
+                        exhausted = true;
+                    }
+                    else {
+                        failure = streamFailure(error);
+                        throw failure;
+                    }
+                }
+            }
+            finished = true;
+            return acknowledge();
+        },
+        cancel() { cancelled = true; },
+    };
+}
+function rejectedPlatformCode(error) {
+    return error instanceof EndpointDeliveryError && error.disposition === 'rejected' && 'platformCode' in error
+        && typeof error.platformCode === 'number' ? error.platformCode : undefined;
+}
+function streamFailure(error) {
+    return error instanceof EndpointDeliveryError ? error
+        : new EndpointDeliveryError('delivery_unconfirmed', 'Lark stream update outcome is unknown', 'unknown', { cause: error });
+}

package/lib/self-profile.d.ts

@@ -0,0 +1,9 @@
+import { type EndpointProfile } from 'zhin.js/adapter';
+import type { LarkClient } from './client.js';
+interface LarkSelfProfileOptions {
+    readonly client: Pick<LarkClient, 'request' | 'config'>;
+    readonly reportAccount: (id: string) => void;
+}
+/** Same bot-info endpoint used for read-only credential identity verification. */
+export declare function createLarkSelfProfile({ client, reportAccount }: LarkSelfProfileOptions): EndpointProfile;
+export {};

package/lib/self-profile.js

@@ -0,0 +1,15 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+/** Same bot-info endpoint used for read-only credential identity verification. */
+export function createLarkSelfProfile({ client, reportAccount }) {
+    return Object.freeze({
+        writableFields: Object.freeze([]),
+        async read({ signal }) {
+            const response = await createEndpointOperation({ signal }).prepare(() => client.request({ url: `${client.config.apiBaseUrl}/bot/v3/info`, method: 'GET' }));
+            if (response.code !== 0 || !response.bot?.open_id)
+                throw new Error('Lark returned no bot profile');
+            reportAccount(response.bot.open_id);
+            return { ...(typeof response.bot.app_name === 'string' ? { nickname: response.bot.app_name } : {}),
+                ...(typeof response.bot.avatar_url === 'string' ? { avatar: response.bot.avatar_url } : {}) };
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "1.1.20",
+  "version": "1.1.21",
   "description": "Zhin.js Lark/Feishu adapter (HTTP webhook and WebSocket long connection)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,27 +35,27 @@
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.67.0",
     "undici": "6.29.1",
-    "@zhin.js/adapter": "1.1.26",
-    "@zhin.js/agent-feature": "1.1.11",
-    "@zhin.js/client": "1.1.22",
+    "@zhin.js/adapter": "1.1.27",
+    "@zhin.js/agent-feature": "1.1.12",
+    "@zhin.js/client": "1.1.23",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.54",
-    "@zhin.js/feature-kit": "1.1.10",
-    "@zhin.js/host-http": "1.1.12",
-    "@zhin.js/im-contract": "1.1.9",
+    "@zhin.js/core": "1.1.55",
+    "@zhin.js/feature-kit": "1.1.11",
+    "@zhin.js/host-http": "1.1.13",
+    "@zhin.js/im-contract": "1.1.10",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.12",
-    "@zhin.js/skill": "1.1.11",
-    "@zhin.js/tool": "1.1.13"
+    "@zhin.js/page": "1.1.13",
+    "@zhin.js/skill": "1.1.12",
+    "@zhin.js/tool": "1.1.14"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.26",
-    "@zhin.js/command": "^1.1.12",
-    "@zhin.js/core": "^1.1.54",
-    "@zhin.js/host-http": "^1.1.12",
-    "@zhin.js/permission": "^1.1.10",
-    "zhin.js": "^1.1.19"
+    "@zhin.js/adapter": "^1.1.27",
+    "@zhin.js/command": "^1.1.13",
+    "@zhin.js/core": "^1.1.55",
+    "@zhin.js/host-http": "^1.1.13",
+    "@zhin.js/permission": "^1.1.11",
+    "zhin.js": "^1.1.20"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -73,7 +73,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.19"
+    "zhin.js": "1.1.20"
   },
   "files": [
     "adapters",
@@ -105,7 +105,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^2.0.0"
+        "api": "^2.1.0"
       },
       {
         "package": "@zhin.js/command",
@@ -113,7 +113,7 @@
       },
       {
         "package": "@zhin.js/tool",
-        "api": "^1.0.0"
+        "api": "^1.1.0"
       },
       {
         "package": "@zhin.js/skill",

package/schema.json

@@ -163,6 +163,36 @@
                 "description": "Disabled by default. Loopback TLS fault proxy for Feishu outbound APIs only; preserves the official Host, SNI and certificate validation. Independent of streamProxy."
               }
             }
+          },
+          "streaming": {
+            "type": "boolean",
+            "description": "Use native streaming cards for progressive replies."
+          },
+          "streamingIntervalMs": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Reply stream update interval in milliseconds."
+          },
+          "nickname": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "账号昵称兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account nickname"
+              }
+            }
+          },
+          "profile": {
+            "$ref": "#/$defs/selfProfileFallback",
+            "description": "账号资料兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account profile"
+              }
+            }
           }
         },
         "required": [
@@ -214,9 +244,104 @@
           "description": "Disabled by default. Loopback TLS fault proxy for Feishu outbound APIs only; preserves the official Host, SNI and certificate validation. Independent of streamProxy."
         }
       }
+    },
+    "streaming": {
+      "type": "boolean",
+      "default": true,
+      "description": "Use native streaming cards for progressive replies."
+    },
+    "streamingIntervalMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Reply stream update interval in milliseconds.",
+      "default": 1000
+    },
+    "nickname": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "账号昵称兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account nickname"
+        }
+      }
+    },
+    "profile": {
+      "$ref": "#/$defs/selfProfileFallback",
+      "description": "账号资料兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account profile"
+        }
+      }
     }
   },
   "required": [
     "endpoints"
-  ]
+  ],
+  "$defs": {
+    "selfProfileFallback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gender": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "male",
+            "female",
+            "other",
+            "unknown",
+            null
+          ]
+        },
+        "age": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "birthday": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "avatar": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(https?://[^\\s/?#]+(?:[/?#].*)?|)$"
+        },
+        "interests": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "bio": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
 }

package/src/adapter.ts

@@ -8,7 +8,7 @@ export class LarkAdapter extends Adapter<LarkEndpoint, LarkEndpointConfig, LarkC
   readonly #context: AdapterContext<LarkEndpointConfig>;
   constructor(context: AdapterContext<LarkEndpointConfig>) { super(); this.#context = context; }
   override get configurationIdentityFields(): readonly string[] { return ['id', 'appId', 'isFeishu']; }
-  override get configurationUpdateFields(): readonly string[] { return ['appSecret', 'encryptKey', 'verificationToken', 'mode', 'webhookPath', 'apiBaseUrl', 'webApiProxy', 'streamProxy']; }
+  override get configurationUpdateFields(): readonly string[] { return ['appSecret', 'encryptKey', 'verificationToken', 'mode', 'webhookPath', 'apiBaseUrl', 'webApiProxy', 'streamProxy', 'streaming', 'streamingIntervalMs']; }
   override get configurationIdentityProbeFields(): readonly string[] { return ['appSecret', 'apiBaseUrl']; }
   protected override async identifyConfiguration(input: LarkEndpointConfig, signal: AbortSignal, _changed: readonly string[]): Promise<string | undefined> {
     const config = resolveLarkConfig(input), client = new LarkClient({ id: this.descriptor.id, config, signal });

package/src/client.ts

@@ -43,6 +43,7 @@ import {
 import { normalizeLarkSenderForPermit } from './platform-permit.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 import { createLarkLongConnection, type LarkLongConnectionFactory } from './long-connection.js';
+import { openLarkReplyStream, supportsLarkReplyStream } from './reply-stream.js';
 
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
@@ -123,6 +124,13 @@ export class LarkClient extends SdkClient {
     ),
   });
   protected readonly endpointControl: EndpointControl = createRecallEndpointControl((id, signal) => this.recallMessage(id, { signal }));
+  protected get endpointStreaming(): import('zhin.js/adapter').EndpointStreaming | undefined {
+    return this.config.streaming !== false ? { mode: 'card',
+      minIntervalMs: this.config.streamingIntervalMs ?? 1000,
+      supports: supportsLarkReplyStream,
+      open: request => openLarkReplyStream(request, (path, options) => this.#request(path, options)),
+    } : undefined;
+  }
   #routeReleases: HttpRouteRegistration[] = [];
 
   #open = false;
@@ -665,7 +673,7 @@ export class LarkClient extends SdkClient {
   async #request(
     path: string,
     options: {
-      method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+      method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
       params?: Record<string, string | number>;
       body?: Record<string, unknown>;
       signal?: AbortSignal;

package/src/console-spec.ts

@@ -11,6 +11,8 @@ export const larkConsoleSpec = {
     { key: 'appSecret', required: true, env: true, description: '飞书 App Secret', descriptionI18n: { en: 'Lark app secret' } },
     { key: 'encryptKey', env: true, description: '事件加密 key', descriptionI18n: { en: 'Event encryption key' } },
     { key: 'verificationToken', env: true, description: '事件验证 token', descriptionI18n: { en: 'Event verification token' } },
+    { key: 'streaming', type: 'boolean', description: '生成时逐步显示回复', descriptionI18n: { en: 'Show replies progressively while generating' } },
+    { key: 'streamingIntervalMs', type: 'number', description: '回复更新间隔（毫秒）', descriptionI18n: { en: 'Reply update interval in milliseconds' } },
   ] as readonly AdapterConsoleField[],
   docsUrl: 'https://zhin.js.org/adapters/lark',
   readPermission: 'lark:read',

package/src/endpoint.ts

@@ -1,5 +1,6 @@
 import { createEndpointSpecification, endpointSpec, type Endpoint } from 'zhin.js/adapter';
 import { LarkClient, type LarkEndpointOptions } from './client.js';
+import { createLarkSelfProfile } from './self-profile.js';
 export type { LarkEndpointOptions } from './client.js';
 export type { LarkFetch } from './client.js';
 
@@ -15,6 +16,8 @@ export class LarkEndpoint extends LarkClient implements Endpoint {
       name: this.configName(),
       control: this.endpointControl,
       management: this.endpointManagement,
+      streaming: this.endpointStreaming,
+      profile: createLarkSelfProfile({ client: this, reportAccount: id => this[endpointSpec].reportSelfUserId(id) }),
     };
     Object.defineProperty(hooks, 'transportState', { get: () => this.transportState });
     return createEndpointSpecification(this, hooks);

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 import type { Locale } from 'zhin.js/i18n';
 import { validateLarkWebApiProxy } from './web-api-proxy.js';
 /**
@@ -15,7 +16,10 @@ import { formatLarkCard } from './cards.js';
 const logger = getLogger('lark');
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface LarkEndpointConfig {
+export interface LarkEndpointConfig extends EndpointProfileConfiguration {
+  /** Native streaming cards are enabled unless explicitly disabled. */
+  readonly streaming?: boolean;
+  readonly streamingIntervalMs?: number;
   readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
   readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
   readonly id: string;
@@ -30,6 +34,8 @@ export interface LarkEndpointConfig {
 }
 
 export interface ResolvedLarkConfig {
+  readonly streaming?: boolean;
+  readonly streamingIntervalMs?: number;
   readonly webApiProxy?: import('./web-api-proxy.js').LarkWebApiProxy;
   readonly streamProxy?: import('./stream-proxy.js').LarkStreamProxy;
   readonly context: 'lark';
@@ -116,6 +122,8 @@ export interface LarkSendBody {
 }
 
 export function resolveLarkConfig(config: LarkEndpointConfig): ResolvedLarkConfig {
+  if (config.streaming !== undefined && typeof config.streaming !== 'boolean') throw new TypeError('Lark streaming must be a boolean');
+  if (config.streamingIntervalMs !== undefined && (!Number.isSafeInteger(config.streamingIntervalMs) || config.streamingIntervalMs < 0)) throw new TypeError('Lark streamingIntervalMs must be a non-negative integer');
   if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
     || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName))) throw new TypeError('Invalid Lark streamProxy port/serverName');
   if (config.webApiProxy) validateLarkWebApiProxy(config.webApiProxy);
@@ -139,6 +147,8 @@ export function resolveLarkConfig(config: LarkEndpointConfig): ResolvedLarkConfi
     ...(config.webApiProxy ? { webApiProxy: config.webApiProxy } : {}),
     ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
     context: 'lark',
+    streaming: config.streaming !== false,
+    streamingIntervalMs: config.streamingIntervalMs ?? 1000,
     mode,
     id,
     appId,

package/src/reply-stream.ts

@@ -0,0 +1,130 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { EndpointMessageStream, EndpointStreamRequest, EndpointStreamAcknowledgement } from 'zhin.js/adapter';
+import type { LarkApiResponse } from './protocol.js';
+
+export interface LarkStreamRequestOptions {
+  readonly method: 'POST' | 'PUT' | 'PATCH';
+  readonly body: Record<string, unknown>;
+  readonly signal?: AbortSignal;
+}
+type Request = (path: string, options: LarkStreamRequestOptions) => Promise<LarkApiResponse>;
+
+export function supportsLarkReplyStream(request: Pick<EndpointStreamRequest, 'conversation' | 'source'>): boolean {
+  return !request.conversation.threadId && !request.conversation.parent;
+}
+
+/** CardKit text updates use cumulative content and one sequence across content/settings. */
+export function openLarkReplyStream(request: EndpointStreamRequest, send: Request): EndpointMessageStream | undefined {
+  // CardKit has no verified way to restore a previous card's Markdown renderer state.
+  if (request.format === 'markdown' && request.continuation) return undefined;
+  const prefix = request.prefix ?? [];
+  if (prefix.some(segment => segment.type !== 'reply' && segment.type !== 'mention')
+    || !supportsLarkReplyStream(request)) return undefined;
+  const reply = prefix.find(segment => segment.type === 'reply');
+  const replyTo = (reply && 'message_id' in reply.data ? reply.data.message_id : undefined) ?? request.continuation?.replyTo;
+  const mentions = prefix.filter(segment => segment.type === 'mention').map(segment => {
+    const target = String('target' in segment.data ? segment.data.target : '').replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<at id="${target}"></at>`;
+  }).join('');
+  let cardId: string | undefined;
+  let messageId: string | undefined;
+  let sequence = 0;
+  let acceptedText = '';
+  let cancelled = false;
+  let finished = false;
+  let exhausted = false;
+  let platformClosed = false;
+  let failure: unknown;
+  let lastAcknowledgement: EndpointStreamAcknowledgement | undefined;
+  const acknowledge = (): EndpointStreamAcknowledgement => lastAcknowledgement = Object.freeze({ status: messageId ? 'sent' : 'buffered',
+    ...(messageId ? { messageId } : {}), acceptedText, ...(exhausted ? { exhausted: true } : {}) });
+  const bodyText = (text: string) => request.format === 'markdown' ? text : text.replace(/[\\`*_{}[\]()#+.!|>~-]/g, '\\$&');
+  const assertActive = () => {
+    if (cancelled || request.signal?.aborted) throw new EndpointDeliveryError('stream_cancelled', 'Lark stream was cancelled before submission', 'not_sent');
+  };
+  const call = (path: string, method: LarkStreamRequestOptions['method'], body: Record<string, unknown>) => {
+    assertActive();
+    return send(path, { method, body, signal: request.signal });
+  };
+  const write = async (text: string) => {
+    if (failure) throw failure;
+    assertActive();
+    if (finished) return acknowledge();
+    if (!text.startsWith(acceptedText)) throw new EndpointDeliveryError('stream_rewrite', 'A confirmed reply prefix cannot change', 'not_sent');
+    if (exhausted) return acknowledge();
+    if (text === acceptedText) return acknowledge();
+    if (!cardId) {
+      try {
+        const card = await call('/cardkit/v1/cards', 'POST', { type: 'card_json', data: JSON.stringify({
+          schema: '2.0', config: { streaming_mode: true, update_multi: true },
+          body: { elements: [
+            ...(mentions ? [{ tag: 'markdown', element_id: 'zhin_prefix', content: mentions }] : []),
+            { tag: 'markdown', element_id: 'zhin_reply', content: bodyText(text) },
+          ] },
+        }) });
+        cardId = typeof card.data?.card_id === 'string' && card.data.card_id ? card.data.card_id : undefined;
+        if (!cardId) throw new Error('CardKit returned no card ID');
+      } catch (error) {
+        // A card resource may exist, but no chat-message request has been attempted.
+        failure = new EndpointDeliveryError('stream_resource_unavailable', 'Lark streaming card could not be prepared', 'not_sent', { cause: error });
+        throw failure;
+      }
+    }
+    try {
+      if (!messageId) {
+        const message = await call(typeof replyTo === 'string' && replyTo
+          ? `/im/v1/messages/${encodeURIComponent(replyTo)}/reply` : '/im/v1/messages?receive_id_type=chat_id', 'POST', {
+          ...(replyTo ? {} : { receive_id: request.conversation.id }),
+          msg_type: 'interactive', content: JSON.stringify({ type: 'card', data: { card_id: cardId } }),
+        });
+        if (typeof message.data?.message_id !== 'string' || !message.data.message_id.trim()) {
+          throw new EndpointDeliveryError('delivery_unconfirmed', 'Lark stream returned no message ID', 'unknown');
+        }
+        messageId = message.data.message_id;
+      } else {
+        await call(`/cardkit/v1/cards/${encodeURIComponent(cardId)}/elements/zhin_reply/content`, 'PUT', {
+          content: bodyText(text), sequence: ++sequence,
+        });
+      }
+      acceptedText = text;
+      return acknowledge();
+    } catch (error) {
+      const code = rejectedPlatformCode(error);
+      if (messageId && acceptedText && (code === 200850 || code === 200860)) {
+        // The rejected update contributed no source. Timeout explicitly closes the
+        // prior card; capacity requires closing only its last confirmed contents.
+        exhausted = true; platformClosed = code === 200850;
+        return acknowledge();
+      }
+      failure = streamFailure(error); throw failure;
+    }
+  };
+  return {
+    get lastAcknowledgement() { return lastAcknowledgement; },
+    write,
+    async finish(text) {
+      if (finished) return acknowledge();
+      await write(text);
+      if (cardId && messageId && !platformClosed) {
+        try { await call(`/cardkit/v1/cards/${encodeURIComponent(cardId)}/settings`, 'PATCH', {
+          settings: JSON.stringify({ config: { streaming_mode: false } }), sequence: ++sequence,
+        }); } catch (error) {
+          if (rejectedPlatformCode(error) === 200850) { platformClosed = true; exhausted = true; }
+          else { failure = streamFailure(error); throw failure; }
+        }
+      }
+      finished = true; return acknowledge();
+    },
+    cancel() { cancelled = true; },
+  };
+}
+
+function rejectedPlatformCode(error: unknown): number | undefined {
+  return error instanceof EndpointDeliveryError && error.disposition === 'rejected' && 'platformCode' in error
+    && typeof error.platformCode === 'number' ? error.platformCode : undefined;
+}
+
+function streamFailure(error: unknown): EndpointDeliveryError {
+  return error instanceof EndpointDeliveryError ? error
+    : new EndpointDeliveryError('delivery_unconfirmed', 'Lark stream update outcome is unknown', 'unknown', { cause: error });
+}

package/src/self-profile.ts

@@ -0,0 +1,23 @@
+import { createEndpointOperation, type EndpointProfile } from 'zhin.js/adapter';
+import type { LarkClient } from './client.js';
+
+interface LarkSelfProfileOptions {
+  readonly client: Pick<LarkClient, 'request' | 'config'>;
+  readonly reportAccount: (id: string) => void;
+}
+
+/** Same bot-info endpoint used for read-only credential identity verification. */
+export function createLarkSelfProfile({ client, reportAccount }: LarkSelfProfileOptions): EndpointProfile {
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze([]),
+    async read({ signal }) {
+      const response = await createEndpointOperation({ signal }).prepare(() => client.request<{
+        code?: number; bot?: { open_id?: string; app_name?: string; avatar_url?: string };
+      }>({ url: `${client.config.apiBaseUrl}/bot/v3/info`, method: 'GET' }));
+      if (response.code !== 0 || !response.bot?.open_id) throw new Error('Lark returned no bot profile');
+      reportAccount(response.bot.open_id);
+      return { ...(typeof response.bot.app_name === 'string' ? { nickname: response.bot.app_name } : {}),
+        ...(typeof response.bot.avatar_url === 'string' ? { avatar: response.bot.avatar_url } : {}) };
+    },
+  });
+}