@larksuite/openclaw-lark 2026.3.12 → 2026.3.17-beta.0

package/bin/openclaw-lark.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+
+// --tools-version <ver> lets the user pin a specific version
+const args = process.argv.slice(2);
+let version = "latest";
+
+const vIdx = args.indexOf("--tools-version");
+if (vIdx !== -1) {
+  version = args[vIdx + 1];
+  // Remove --tools-version <ver> from forwarded args
+  args.splice(vIdx, 2);
+}
+
+const allArgs = ["--yes", `@larksuite/openclaw-lark-tools@${version}`, ...args];
+
+try {
+  if (process.platform === "win32") {
+    // On Windows, npx is a .cmd shim that can be broken or trigger
+    // DEP0190. Bypass it entirely: run node with the npx-cli.js
+    // script located next to the running node binary.
+    const npxCli = join(
+      dirname(process.execPath),
+      "node_modules",
+      "npm",
+      "bin",
+      "npx-cli.js",
+    );
+    execFileSync(process.execPath, [npxCli, ...allArgs], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        NODE_OPTIONS: [
+          process.env.NODE_OPTIONS,
+          "--disable-warning=DEP0190",
+        ]
+          .filter(Boolean)
+          .join(" "),
+      },
+    });
+  } else {
+    execFileSync("npx", allArgs, { stdio: "inherit" });
+  }
+} catch (error) {
+  process.exit(error.status ?? 1);
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@larksuite/openclaw-lark",
-  "version": "2026.3.12",
+  "version": "2026.3.17-beta.0",
   "description": "OpenClaw Lark/Feishu channel plugin",
   "type": "module",
+  "bin": {
+    "openclaw-lark": "bin/openclaw-lark.js"
+  },
   "files": [
     "**/*"
   ],

package/src/card/builder.d.ts

@@ -28,6 +28,7 @@ export interface FeishuCard {
     config: {
         wide_screen_mode: boolean;
         update_multi?: boolean;
+        locales?: string[];
         summary?: {
             content: string;
         };
@@ -36,6 +37,7 @@ export interface FeishuCard {
         title: {
             tag: 'plain_text';
             content: string;
+            i18n_content?: Record<string, string>;
         };
         template: string;
     };
@@ -66,10 +68,13 @@ export declare function splitReasoningText(text?: string): {
  */
 export declare function stripReasoningTags(text: string): string;
 /**
- * Format reasoning duration into a human-readable string.
- * e.g. "Thought for 3.2s" or "Thought for 1m 15s"
+ * Format reasoning duration into a human-readable i18n pair.
+ * e.g. { zh: "思考了 3.2s", en: "Thought for 3.2s" }
  */
-export declare function formatReasoningDuration(ms: number): string;
+export declare function formatReasoningDuration(ms: number): {
+    zh: string;
+    en: string;
+};
 /**
  * Format milliseconds into a human-readable duration string.
  */

package/src/card/builder.js

@@ -107,11 +107,12 @@ function cleanReasoningPrefix(text) {
     return cleaned.trim();
 }
 /**
- * Format reasoning duration into a human-readable string.
- * e.g. "Thought for 3.2s" or "Thought for 1m 15s"
+ * Format reasoning duration into a human-readable i18n pair.
+ * e.g. { zh: "思考了 3.2s", en: "Thought for 3.2s" }
  */
 export function formatReasoningDuration(ms) {
-    return `Thought for ${formatElapsed(ms)}`;
+    const d = formatElapsed(ms);
+    return { zh: `思考了 ${d}`, en: `Thought for ${d}` };
 }
 /**
  * Format milliseconds into a human-readable duration string.
@@ -121,12 +122,18 @@ export function formatElapsed(ms) {
     return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
 }
 /**
- * Build footer meta-info: hr separator + notation-sized text.
+ * Build footer meta-info: notation-sized text with i18n support.
  * Error text is rendered in red; normal text uses default grey (notation).
  */
-function buildFooter(text, isError) {
-    const content = isError ? `<font color='red'>${text}</font>` : text;
-    return [{ tag: 'markdown', content, text_size: 'notation' }];
+function buildFooter(zhText, enText, isError) {
+    const zhContent = isError ? `<font color='red'>${zhText}</font>` : zhText;
+    const enContent = isError ? `<font color='red'>${enText}</font>` : enText;
+    return [{
+            tag: 'markdown',
+            content: enContent,
+            i18n_content: { zh_cn: zhContent, en_us: enContent },
+            text_size: 'notation',
+        }];
 }
 // ---------------------------------------------------------------------------
 // buildCardContent
@@ -163,11 +170,12 @@ export function buildCardContent(state, data = {}) {
 // ---------------------------------------------------------------------------
 function buildThinkingCard() {
     return {
-        config: { wide_screen_mode: true, update_multi: true },
+        config: { wide_screen_mode: true, update_multi: true, locales: ['zh_cn', 'en_us'] },
         elements: [
             {
                 tag: 'markdown',
-                content: '思考中...',
+                content: 'Thinking...',
+                i18n_content: { zh_cn: '思考中...', en_us: 'Thinking...' },
             },
         ],
     };
@@ -179,6 +187,10 @@ function buildStreamingCard(partialText, toolCalls, reasoningText) {
         elements.push({
             tag: 'markdown',
             content: `💭 **Thinking...**\n\n${reasoningText}`,
+            i18n_content: {
+                zh_cn: `💭 **思考中...**\n\n${reasoningText}`,
+                en_us: `💭 **Thinking...**\n\n${reasoningText}`,
+            },
             text_size: 'notation',
         });
     }
@@ -202,7 +214,7 @@ function buildStreamingCard(partialText, toolCalls, reasoningText) {
         });
     }
     return {
-        config: { wide_screen_mode: true, update_multi: true },
+        config: { wide_screen_mode: true, update_multi: true, locales: ['zh_cn', 'en_us'] },
         elements,
     };
 }
@@ -211,14 +223,20 @@ function buildCompleteCard(params) {
     const elements = [];
     // Collapsible reasoning panel (before main content)
     if (reasoningText) {
-        const durationLabel = reasoningElapsedMs ? formatReasoningDuration(reasoningElapsedMs) : 'Thought';
+        const dur = reasoningElapsedMs ? formatReasoningDuration(reasoningElapsedMs) : null;
+        const zhLabel = dur ? dur.zh : '思考';
+        const enLabel = dur ? dur.en : 'Thought';
         elements.push({
             tag: 'collapsible_panel',
             expanded: false,
             header: {
                 title: {
                     tag: 'markdown',
-                    content: `💭 ${durationLabel}`,
+                    content: `💭 ${enLabel}`,
+                    i18n_content: {
+                        zh_cn: `💭 ${zhLabel}`,
+                        en_us: `💭 ${enLabel}`,
+                    },
                 },
                 vertical_align: 'center',
                 icon: {
@@ -260,31 +278,36 @@ function buildCompleteCard(params) {
     }
     // Footer meta-info: each metadata item is independently controlled via
     // the `footer` config. Both status and elapsed default to hidden.
-    const parts = [];
+    const zhParts = [];
+    const enParts = [];
     if (footer?.status) {
         if (isError) {
-            parts.push('出错');
+            zhParts.push('出错');
+            enParts.push('Error');
         }
         else if (isAborted) {
-            parts.push('已停止');
+            zhParts.push('已停止');
+            enParts.push('Stopped');
         }
         else {
-            parts.push('已完成');
+            zhParts.push('已完成');
+            enParts.push('Completed');
         }
     }
     if (footer?.elapsed && elapsedMs != null) {
-        parts.push(`耗时 ${formatElapsed(elapsedMs)}`);
+        const d = formatElapsed(elapsedMs);
+        zhParts.push(`耗时 ${d}`);
+        enParts.push(`Elapsed ${d}`);
     }
-    if (parts.length > 0) {
-        const footerText = parts.join(' · ');
-        elements.push(...buildFooter(footerText, isError));
+    if (zhParts.length > 0) {
+        elements.push(...buildFooter(zhParts.join(' · '), enParts.join(' · '), isError));
     }
     // Use the answer text (not reasoning) as the feed preview summary.
     // Strip markdown syntax so the preview reads as plain text.
     const summaryText = text.replace(/[*_`#>\[\]()~]/g, '').trim();
     const summary = summaryText ? { content: summaryText.slice(0, 120) } : undefined;
     return {
-        config: { wide_screen_mode: true, update_multi: true, summary },
+        config: { wide_screen_mode: true, update_multi: true, locales: ['zh_cn', 'en_us'], summary },
         elements,
     };
 }

package/src/card/image-resolver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ImageResolver — converts image URLs in markdown to Feishu image keys.
+ *
+ * Used by StreamingCardController to asynchronously download and upload
+ * images referenced via `![alt](https://...)` in model-generated markdown,
+ * replacing them with `![alt](img_xxx)` that Feishu cards can render.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+export interface ImageResolverOptions {
+    cfg: ClawdbotConfig;
+    accountId: string | undefined;
+    /** Called when a previously-pending image upload completes. */
+    onImageResolved: () => void;
+}
+export declare class ImageResolver {
+    /** URL → imageKey for successfully uploaded images. */
+    private readonly resolved;
+    /** URL → upload Promise for in-flight uploads (dedup). */
+    private readonly pending;
+    /** URLs that have already failed — skip retries. */
+    private readonly failed;
+    private readonly cfg;
+    private readonly accountId;
+    private readonly onImageResolved;
+    constructor(opts: ImageResolverOptions);
+    /**
+     * Synchronously resolve image URLs in markdown text.
+     *
+     * - `img_xxx` references are kept as-is.
+     * - URLs with a cached imageKey are replaced inline.
+     * - URLs with an in-flight upload are stripped (will appear after re-flush).
+     * - New URLs trigger an async upload and are stripped for now.
+     */
+    resolveImages(text: string): string;
+    /**
+     * Resolve all image URLs in text synchronously: trigger uploads for new
+     * URLs, wait for all pending uploads, then return text with image keys.
+     */
+    resolveImagesAwait(text: string, timeoutMs: number): Promise<string>;
+    private startUpload;
+    private doUpload;
+}

package/src/card/image-resolver.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ImageResolver — converts image URLs in markdown to Feishu image keys.
+ *
+ * Used by StreamingCardController to asynchronously download and upload
+ * images referenced via `![alt](https://...)` in model-generated markdown,
+ * replacing them with `![alt](img_xxx)` that Feishu cards can render.
+ */
+import { fetchRemoteImageBuffer, uploadImageLark } from '../messaging/outbound/media';
+import { larkLogger } from '../core/lark-logger';
+const log = larkLogger('card/image-resolver');
+/** Matches complete markdown image syntax: `![alt](value)` */
+const IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)\)/g;
+export class ImageResolver {
+    /** URL → imageKey for successfully uploaded images. */
+    resolved = new Map();
+    /** URL → upload Promise for in-flight uploads (dedup). */
+    pending = new Map();
+    /** URLs that have already failed — skip retries. */
+    failed = new Set();
+    cfg;
+    accountId;
+    onImageResolved;
+    constructor(opts) {
+        this.cfg = opts.cfg;
+        this.accountId = opts.accountId;
+        this.onImageResolved = opts.onImageResolved;
+    }
+    /**
+     * Synchronously resolve image URLs in markdown text.
+     *
+     * - `img_xxx` references are kept as-is.
+     * - URLs with a cached imageKey are replaced inline.
+     * - URLs with an in-flight upload are stripped (will appear after re-flush).
+     * - New URLs trigger an async upload and are stripped for now.
+     */
+    resolveImages(text) {
+        if (!text.includes('!['))
+            return text;
+        return text.replace(IMAGE_RE, (fullMatch, alt, value) => {
+            // Already a Feishu image key — keep.
+            if (value.startsWith('img_'))
+                return fullMatch;
+            // Not a remote URL — strip (local paths, data URIs, etc.).
+            if (!value.startsWith('http://') && !value.startsWith('https://'))
+                return '';
+            // Cached — replace with image key.
+            const cached = this.resolved.get(value);
+            if (cached)
+                return `![${alt}](${cached})`;
+            // Already failed — don't retry, strip.
+            if (this.failed.has(value))
+                return '';
+            // Upload in progress — strip for now.
+            if (this.pending.has(value))
+                return '';
+            // New URL — kick off async upload, strip for now.
+            this.startUpload(value);
+            return '';
+        });
+    }
+    /**
+     * Resolve all image URLs in text synchronously: trigger uploads for new
+     * URLs, wait for all pending uploads, then return text with image keys.
+     */
+    async resolveImagesAwait(text, timeoutMs) {
+        // First pass: trigger uploads for any new URLs
+        this.resolveImages(text);
+        if (this.pending.size > 0) {
+            log.info('resolveImagesAwait: waiting for uploads', { count: this.pending.size, timeoutMs });
+            const allUploads = Promise.all(this.pending.values());
+            const timeout = new Promise((resolve) => setTimeout(resolve, timeoutMs));
+            await Promise.race([allUploads, timeout]);
+            if (this.pending.size > 0) {
+                log.warn('resolveImagesAwait: timed out with pending uploads', {
+                    remaining: this.pending.size,
+                });
+            }
+        }
+        // Second pass: replace URLs with resolved image keys
+        return this.resolveImages(text);
+    }
+    startUpload(url) {
+        const uploadPromise = this.doUpload(url);
+        this.pending.set(url, uploadPromise);
+    }
+    async doUpload(url) {
+        try {
+            log.info('uploading image', { url });
+            const buffer = await fetchRemoteImageBuffer(url);
+            const { imageKey } = await uploadImageLark({
+                cfg: this.cfg,
+                image: buffer,
+                imageType: 'message',
+                accountId: this.accountId,
+            });
+            log.info('image uploaded', { url, imageKey });
+            this.resolved.set(url, imageKey);
+            this.pending.delete(url);
+            this.onImageResolved();
+            return imageKey;
+        }
+        catch (err) {
+            log.warn('image upload failed', { url, error: String(err) });
+            this.pending.delete(url);
+            this.failed.add(url);
+            return null;
+        }
+    }
+}

package/src/card/markdown-style.js

@@ -81,7 +81,11 @@ function _optimizeMarkdownStyle(text, cardVersion = 2) {
 const IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)\)/g;
 /**
  * Strip `![alt](value)` where value is not a valid Feishu image key
- * (`img_xxx`) or remote URL. Prevents CardKit error 200570.
+ * (`img_xxx`). Prevents CardKit error 200570.
+ *
+ * HTTP URLs are stripped as well — ImageResolver should have already
+ * replaced them with `img_xxx` keys before this point. This serves
+ * as a safety net for any unresolved URLs.
  */
 function stripInvalidImageKeys(text) {
     if (!text.includes('!['))
@@ -89,10 +93,6 @@ function stripInvalidImageKeys(text) {
     return text.replace(IMAGE_RE, (fullMatch, _alt, value) => {
         if (value.startsWith('img_'))
             return fullMatch;
-        if (value.startsWith('http://'))
-            return fullMatch;
-        if (value.startsWith('https://'))
-            return fullMatch;
-        return value;
+        return ''; // strip all non-img_ image references (URLs, local paths, etc.)
     });
 }

package/src/card/streaming-card-controller.d.ts

@@ -19,6 +19,7 @@ export declare class StreamingCardController {
     private reasoning;
     private readonly flush;
     private readonly guard;
+    private readonly imageResolver;
     private createEpoch;
     private _terminalReason;
     private dispatchFullyComplete;

package/src/card/streaming-card-controller.js

@@ -18,6 +18,7 @@ import { sendCardFeishu, updateCardFeishu } from '../messaging/outbound/send';
 import { createCardEntity, sendCardByCardId, streamCardContent, updateCardKitCard, setCardStreamingMode, } from './cardkit';
 import { buildCardContent, splitReasoningText, stripReasoningTags, STREAMING_ELEMENT_ID, toCardKit2 } from './builder';
 import { optimizeMarkdownStyle } from './markdown-style';
+import { ImageResolver } from './image-resolver';
 import { registerShutdownHook } from '../core/shutdown-hooks';
 import { FlushController } from './flush-controller';
 import { UnavailableGuard } from './unavailable-guard';
@@ -30,7 +31,11 @@ const STREAMING_THINKING_CARD = {
     schema: '2.0',
     config: {
         streaming_mode: true,
-        summary: { content: '思考中...' },
+        locales: ['zh_cn', 'en_us'],
+        summary: {
+            content: 'Thinking...',
+            i18n_content: { zh_cn: '思考中...', en_us: 'Thinking...' },
+        },
     },
     body: {
         elements: [
@@ -83,6 +88,7 @@ export class StreamingCardController {
     // ---- Sub-controllers ----
     flush;
     guard;
+    imageResolver;
     // ---- Lifecycle ----
     createEpoch = 0;
     _terminalReason = null;
@@ -105,6 +111,15 @@ export class StreamingCardController {
             },
         });
         this.flush = new FlushController(() => this.performFlush());
+        this.imageResolver = new ImageResolver({
+            cfg: deps.cfg,
+            accountId: deps.accountId,
+            onImageResolved: () => {
+                if (!this.isTerminalPhase && this.cardKit.cardMessageId) {
+                    void this.throttledCardUpdate();
+                }
+            },
+        });
     }
     // ------------------------------------------------------------------
     // Public accessors
@@ -300,9 +315,10 @@ export class StreamingCardController {
         const errorEffectiveCardId = this.cardKit.cardKitCardId ?? this.cardKit.originalCardKitCardId;
         if (this.cardKit.cardMessageId) {
             try {
-                const errorText = this.text.accumulatedText
+                const rawErrorText = this.text.accumulatedText
                     ? `${this.text.accumulatedText}\n\n---\n**Error**: An error occurred while generating the response.`
                     : '**Error**: An error occurred while generating the response.';
+                const errorText = this.imageResolver.resolveImages(rawErrorText);
                 const errorCard = buildCardContent('complete', {
                     text: errorText,
                     reasoningText: this.reasoning.accumulatedReasoningText || undefined,
@@ -365,8 +381,9 @@ export class StreamingCardController {
                 if (!this.text.completedText && !this.text.accumulatedText) {
                     log.warn('reply completed without visible text, using empty-reply fallback');
                 }
+                const resolvedDisplayText = await this.imageResolver.resolveImagesAwait(displayText, 15_000);
                 const completeCard = buildCardContent('complete', {
-                    text: displayText,
+                    text: resolvedDisplayText,
                     reasoningText: this.reasoning.accumulatedReasoningText || undefined,
                     reasoningElapsedMs: this.reasoning.reasoningElapsedMs || undefined,
                     elapsedMs: this.elapsed(),
@@ -427,7 +444,7 @@ export class StreamingCardController {
             const effectiveCardId = this.cardKit.cardKitCardId ?? this.cardKit.originalCardKitCardId;
             if (effectiveCardId) {
                 const elapsedMs = Date.now() - this.dispatchStartTime;
-                const abortText = this.text.accumulatedText || 'Aborted.';
+                const abortText = this.imageResolver.resolveImages(this.text.accumulatedText || 'Aborted.');
                 const abortCardContent = buildCardContent('complete', {
                     text: abortText,
                     reasoningText: this.reasoning.accumulatedReasoningText || undefined,
@@ -442,7 +459,7 @@ export class StreamingCardController {
             else if (this.cardKit.cardMessageId) {
                 // IM fallback: 卡片不是通过 CardKit 发的，用 im.message.patch 更新
                 const elapsedMs = Date.now() - this.dispatchStartTime;
-                const abortText = this.text.accumulatedText || 'Aborted.';
+                const abortText = this.imageResolver.resolveImages(this.text.accumulatedText || 'Aborted.');
                 const abortCard = buildCardContent('complete', {
                     text: abortText,
                     reasoningText: this.reasoning.accumulatedReasoningText || undefined,
@@ -602,6 +619,7 @@ export class StreamingCardController {
         });
         try {
             const displayText = this.buildDisplayText();
+            const resolvedText = this.imageResolver.resolveImages(displayText);
             if (this.cardKit.cardKitCardId) {
                 // CardKit streaming — typewriter effect
                 const prevSeq = this.cardKit.cardKitSequence;
@@ -614,7 +632,7 @@ export class StreamingCardController {
                     cfg: this.deps.cfg,
                     cardId: this.cardKit.cardKitCardId,
                     elementId: STREAMING_ELEMENT_ID,
-                    content: optimizeMarkdownStyle(displayText),
+                    content: optimizeMarkdownStyle(resolvedText),
                     sequence: this.cardKit.cardKitSequence,
                     accountId: this.deps.accountId,
                 });
@@ -622,7 +640,7 @@ export class StreamingCardController {
             else {
                 log.debug('flushCardUpdate: IM patch fallback');
                 const card = buildCardContent('streaming', {
-                    text: this.reasoning.isReasoningPhase ? '' : displayText,
+                    text: this.reasoning.isReasoningPhase ? '' : resolvedText,
                     reasoningText: this.reasoning.isReasoningPhase ? this.reasoning.accumulatedReasoningText : undefined,
                 });
                 await updateCardFeishu({

package/src/commands/auth.d.ts

@@ -8,8 +8,14 @@
  * 注意：此命令仅限应用 owner 执行（与 onboarding 逻辑一致）
  */
 import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import type { FeishuLocale } from './locale';
 /**
  * 执行飞书用户权限批量授权命令
  * 直接调用 triggerOnboarding()，包含 owner 检查
  */
-export declare function runFeishuAuth(config: OpenClawConfig): Promise<string>;
+export declare function runFeishuAuth(config: OpenClawConfig, locale?: FeishuLocale): Promise<string>;
+/**
+ * 运行飞书授权命令，同时生成中英双语结果。
+ * 副作用（triggerOnboarding）只执行一次，结果格式化为双语文本。
+ */
+export declare function runFeishuAuthI18n(config: OpenClawConfig): Promise<Record<FeishuLocale, string>>;