@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/streaming-card.test.ts

@@ -1,5 +1,141 @@
-import { describe, expect, it } from "vitest";
-import { mergeStreamingText, resolveStreamingCardSendMode } from "./streaming-card.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const fetchWithSsrFGuardMock = vi.hoisted(() => vi.fn());
+
+vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({
+  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
+}));
+
+import {
+  FeishuStreamingSession,
+  mergeStreamingText,
+  resolveStreamingCardSendMode,
+} from "./streaming-card.js";
+
+type StreamingSessionState = {
+  cardId: string;
+  messageId: string;
+  sequence: number;
+  currentText: string;
+  hasNote: boolean;
+};
+
+function setStreamingSessionInternals(
+  session: FeishuStreamingSession,
+  values: {
+    state: StreamingSessionState;
+    lastUpdateTime?: number;
+  },
+) {
+  const internals = session as unknown as {
+    state: StreamingSessionState;
+    lastUpdateTime: number;
+  };
+  internals.state = values.state;
+  if (values.lastUpdateTime !== undefined) {
+    internals.lastUpdateTime = values.lastUpdateTime;
+  }
+}
+
+describe("FeishuStreamingSession", () => {
+  beforeEach(() => {
+    vi.useRealTimers();
+    fetchWithSsrFGuardMock.mockReset();
+  });
+
+  function mockFetches(updateBodies: string[]) {
+    fetchWithSsrFGuardMock.mockImplementation(
+      async ({ url, init }: { url: string; init?: { body?: string } }) => {
+        const release = vi.fn(async () => {});
+        if (url.includes("/auth/")) {
+          return {
+            response: {
+              ok: true,
+              json: async () => ({
+                code: 0,
+                msg: "ok",
+                tenant_access_token: "token",
+                expire: 7200,
+              }),
+            },
+            release,
+          };
+        }
+        if (url.includes("/elements/content/content")) {
+          updateBodies.push(init?.body ?? "");
+        }
+        return {
+          response: {
+            ok: true,
+            json: async () => ({ code: 0, msg: "ok" }),
+          },
+          release,
+        };
+      },
+    );
+  }
+
+  it("flushes throttled pending text after the throttle window", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const updateBodies: string[] = [];
+    mockFetches(updateBodies);
+
+    const session = new FeishuStreamingSession({} as never, {
+      appId: "app_pending_flush",
+      appSecret: "secret",
+    });
+    setStreamingSessionInternals(session, {
+      state: {
+        cardId: "card_1",
+        messageId: "om_1",
+        sequence: 1,
+        currentText: "hello",
+        hasNote: false,
+      },
+      lastUpdateTime: 1_000,
+    });
+
+    await session.update("hello small");
+    expect(updateBodies).toHaveLength(0);
+
+    await vi.advanceTimersByTimeAsync(160);
+
+    expect(updateBodies).toHaveLength(1);
+    expect(JSON.parse(updateBodies[0] ?? "{}")).toMatchObject({
+      content: "hello small",
+    });
+  });
+
+  it("pushes natural-boundary updates immediately inside the throttle window", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(2_000);
+    const updateBodies: string[] = [];
+    mockFetches(updateBodies);
+
+    const session = new FeishuStreamingSession({} as never, {
+      appId: "app_boundary_flush",
+      appSecret: "secret",
+    });
+    setStreamingSessionInternals(session, {
+      state: {
+        cardId: "card_2",
+        messageId: "om_2",
+        sequence: 1,
+        currentText: "hello",
+        hasNote: false,
+      },
+      lastUpdateTime: 2_000,
+    });
+
+    await session.update("hello!");
+
+    expect(updateBodies).toHaveLength(1);
+    expect(JSON.parse(updateBodies[0] ?? "{}")).toMatchObject({
+      content: "hello!",
+    });
+  });
+});
 
 describe("mergeStreamingText", () => {
   it("prefers the latest full text when it already includes prior text", () => {

package/src/streaming-card.ts

@@ -3,14 +3,30 @@
  */
 
 import type { Client } from "@larksuiteoapi/node-sdk";
-import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/feishu";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
+import { getFeishuUserAgent } from "./client.js";
+import { resolveFeishuCardTemplate, type CardHeaderConfig } from "./send.js";
 import type { FeishuDomain } from "./types.js";
 
 type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
-type CardState = { cardId: string; messageId: string; sequence: number; currentText: string };
+type CardState = {
+  cardId: string;
+  messageId: string;
+  sequence: number;
+  currentText: string;
+  hasNote: boolean;
+};
+
+/** Options for customising the initial streaming card appearance. */
+type StreamingCardOptions = {
+  /** Optional header with title and color template. */
+  header?: CardHeaderConfig;
+  /** Optional grey note footer text. */
+  note?: string;
+};
 
 /** Optional header for streaming cards (title bar with color template) */
-export type StreamingCardHeader = {
+type StreamingCardHeader = {
   title: string;
   /** Color template: blue, green, red, orange, purple, indigo, wathet, turquoise, yellow, grey, carmine, violet, lime */
   template?: string;
@@ -23,6 +39,9 @@ type StreamingStartOptions = {
   header?: StreamingCardHeader;
 };
 
+const STREAMING_UPDATE_THROTTLE_MS = 160;
+const STREAMING_SIGNIFICANT_DELTA_CHARS = 18;
+
 // Token cache (keyed by domain + appId)
 const tokenCache = new Map<string, { token: string; expiresAt: number }>();
 
@@ -61,7 +80,7 @@ async function getToken(creds: Credentials): Promise<string> {
     url: `${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`,
     init: {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": getFeishuUserAgent() },
       body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
     },
     policy: { allowedHostnames: resolveAllowedHostnames(creds.domain) },
@@ -96,6 +115,20 @@ function truncateSummary(text: string, max = 50): string {
   return clean.length <= max ? clean : clean.slice(0, max - 3) + "...";
 }
 
+function hasNaturalStreamingBoundary(text: string): boolean {
+  return /[\n。！？!?；;：:]$/.test(text);
+}
+
+function shouldPushStreamingUpdate(previousText: string, nextText: string): boolean {
+  if (!previousText) {
+    return true;
+  }
+  if (hasNaturalStreamingBoundary(nextText)) {
+    return true;
+  }
+  return nextText.length - previousText.length >= STREAMING_SIGNIFICANT_DELTA_CHARS;
+}
+
 export function mergeStreamingText(
   previousText: string | undefined,
   nextText: string | undefined,
@@ -152,7 +185,8 @@ export class FeishuStreamingSession {
   private log?: (msg: string) => void;
   private lastUpdateTime = 0;
   private pendingText: string | null = null;
-  private updateThrottleMs = 100; // Throttle updates to max 10/sec
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private updateThrottleMs = STREAMING_UPDATE_THROTTLE_MS;
 
   constructor(client: Client, creds: Credentials, log?: (msg: string) => void) {
     this.client = client;
@@ -163,13 +197,24 @@ export class FeishuStreamingSession {
   async start(
     receiveId: string,
     receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
-    options?: StreamingStartOptions,
+    options?: StreamingCardOptions & StreamingStartOptions,
   ): Promise<void> {
     if (this.state) {
       return;
     }
 
     const apiBase = resolveApiBase(this.creds.domain);
+    const elements: Record<string, unknown>[] = [
+      { tag: "markdown", content: "⏳ Thinking...", element_id: "content" },
+    ];
+    if (options?.note) {
+      elements.push({ tag: "hr" });
+      elements.push({
+        tag: "markdown",
+        content: `<font color='grey'>${options.note}</font>`,
+        element_id: "note",
+      });
+    }
     const cardJson: Record<string, unknown> = {
       schema: "2.0",
       config: {
@@ -177,14 +222,12 @@ export class FeishuStreamingSession {
         summary: { content: "[Generating...]" },
         streaming_config: { print_frequency_ms: { default: 50 }, print_step: { default: 1 } },
       },
-      body: {
-        elements: [{ tag: "markdown", content: "⏳ Thinking...", element_id: "content" }],
-      },
+      body: { elements },
     };
     if (options?.header) {
       cardJson.header = {
         title: { tag: "plain_text", content: options.header.title },
-        template: options.header.template ?? "blue",
+        template: resolveFeishuCardTemplate(options.header.template) ?? "blue",
       };
     }
 
@@ -196,6 +239,7 @@ export class FeishuStreamingSession {
         headers: {
           Authorization: `Bearer ${await getToken(this.creds)}`,
           "Content-Type": "application/json",
+          "User-Agent": getFeishuUserAgent(),
         },
         body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
       },
@@ -257,7 +301,13 @@ export class FeishuStreamingSession {
       throw new Error(`Send card failed: ${sendRes.msg}`);
     }
 
-    this.state = { cardId, messageId: sendRes.data.message_id, sequence: 1, currentText: "" };
+    this.state = {
+      cardId,
+      messageId: sendRes.data.message_id,
+      sequence: 1,
+      currentText: "",
+      hasNote: !!options?.note,
+    };
     this.log?.(`Started streaming: cardId=${cardId}, messageId=${sendRes.data.message_id}`);
   }
 
@@ -274,6 +324,7 @@ export class FeishuStreamingSession {
         headers: {
           Authorization: `Bearer ${await getToken(this.creds)}`,
           "Content-Type": "application/json",
+          "User-Agent": getFeishuUserAgent(),
         },
         body: JSON.stringify({
           content: text,
@@ -290,6 +341,28 @@ export class FeishuStreamingSession {
       .catch((error) => onError?.(error));
   }
 
+  private clearFlushTimer(): void {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  private schedulePendingFlush(): void {
+    if (this.flushTimer || !this.pendingText || this.closed) {
+      return;
+    }
+    const delayMs = Math.max(0, this.updateThrottleMs - (Date.now() - this.lastUpdateTime));
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      const pending = this.pendingText;
+      if (!pending || this.closed) {
+        return;
+      }
+      void this.update(pending);
+    }, delayMs);
+  }
+
   async update(text: string): Promise<void> {
     if (!this.state || this.closed) {
       return;
@@ -298,35 +371,69 @@ export class FeishuStreamingSession {
     if (!mergedInput || mergedInput === this.state.currentText) {
       return;
     }
+    this.pendingText = mergedInput;
+    this.clearFlushTimer();
 
-    // Throttle: skip if updated recently, but remember pending text
+    const shouldForceUpdate = shouldPushStreamingUpdate(this.state.currentText, mergedInput);
     const now = Date.now();
-    if (now - this.lastUpdateTime < this.updateThrottleMs) {
-      this.pendingText = mergedInput;
+    if (!shouldForceUpdate && now - this.lastUpdateTime < this.updateThrottleMs) {
+      this.schedulePendingFlush();
       return;
     }
-    this.pendingText = null;
     this.lastUpdateTime = now;
 
     this.queue = this.queue.then(async () => {
       if (!this.state || this.closed) {
         return;
       }
-      const mergedText = mergeStreamingText(this.state.currentText, mergedInput);
+      const nextText = this.pendingText ?? mergedInput;
+      const mergedText = mergeStreamingText(this.state.currentText, nextText);
       if (!mergedText || mergedText === this.state.currentText) {
         return;
       }
+      this.pendingText = null;
       this.state.currentText = mergedText;
       await this.updateCardContent(mergedText, (e) => this.log?.(`Update failed: ${String(e)}`));
     });
     await this.queue;
   }
 
-  async close(finalText?: string): Promise<void> {
+  private async updateNoteContent(note: string): Promise<void> {
+    if (!this.state || !this.state.hasNote) {
+      return;
+    }
+    const apiBase = resolveApiBase(this.creds.domain);
+    this.state.sequence += 1;
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/note/content`,
+      init: {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+          "User-Agent": getFeishuUserAgent(),
+        },
+        body: JSON.stringify({
+          content: `<font color='grey'>${note}</font>`,
+          sequence: this.state.sequence,
+          uuid: `n_${this.state.cardId}_${this.state.sequence}`,
+        }),
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.note-update",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((e) => this.log?.(`Note update failed: ${String(e)}`));
+  }
+
+  async close(finalText?: string, options?: { note?: string }): Promise<void> {
     if (!this.state || this.closed) {
       return;
     }
     this.closed = true;
+    this.clearFlushTimer();
     await this.queue;
 
     const pendingMerged = mergeStreamingText(this.state.currentText, this.pendingText ?? undefined);
@@ -339,6 +446,11 @@ export class FeishuStreamingSession {
       this.state.currentText = text;
     }
 
+    // Update note with final model/provider info
+    if (options?.note) {
+      await this.updateNoteContent(options.note);
+    }
+
     // Close streaming mode
     this.state.sequence += 1;
     await fetchWithSsrFGuard({
@@ -348,6 +460,7 @@ export class FeishuStreamingSession {
         headers: {
           Authorization: `Bearer ${await getToken(this.creds)}`,
           "Content-Type": "application/json; charset=utf-8",
+          "User-Agent": getFeishuUserAgent(),
         },
         body: JSON.stringify({
           settings: JSON.stringify({
@@ -364,8 +477,11 @@ export class FeishuStreamingSession {
         await release();
       })
       .catch((e) => this.log?.(`Close failed: ${String(e)}`));
+    const finalState = this.state;
+    this.state = null;
+    this.pendingText = null;
 
-    this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
+    this.log?.(`Closed streaming: cardId=${finalState.cardId}`);
   }
 
   isActive(): boolean {