@openclaw/feishu 2026.3.12 → 2026.5.1-beta.1

package/src/send.ts

@@ -1,21 +1,43 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
-import { resolveFeishuAccount } from "./accounts.js";
+import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/markdown-table-runtime";
+import {
+  convertMarkdownTables,
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+} from "openclaw/plugin-sdk/text-runtime";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
-import type { MentionTarget } from "./mention.js";
-import { buildMentionedMessage, buildMentionedCardContent } from "./mention.js";
+import type { MentionTarget } from "./mention-target.types.js";
+import { buildMentionedCardContent, buildMentionedMessage } from "./mention.js";
 import { parsePostContent } from "./post.js";
-import { getFeishuRuntime } from "./runtime.js";
 import { assertFeishuMessageApiSuccess, toFeishuSendResult } from "./send-result.js";
 import { resolveFeishuSendTarget } from "./send-target.js";
 import type { FeishuChatType, FeishuMessageInfo, FeishuSendResult } from "./types.js";
 
 const WITHDRAWN_REPLY_ERROR_CODES = new Set([230011, 231003]);
+const INTERACTIVE_CARD_FALLBACK_TEXT = "[Interactive Card]";
+const POST_FALLBACK_TEXT = "[Rich text message]";
+const FEISHU_CARD_TEMPLATES = new Set([
+  "blue",
+  "green",
+  "red",
+  "orange",
+  "purple",
+  "indigo",
+  "wathet",
+  "turquoise",
+  "yellow",
+  "grey",
+  "carmine",
+  "violet",
+  "lime",
+]);
 
 function shouldFallbackFromReplyTarget(response: { code?: number; msg?: string }): boolean {
   if (response.code !== undefined && WITHDRAWN_REPLY_ERROR_CODES.has(response.code)) {
     return true;
   }
-  const msg = response.msg?.toLowerCase() ?? "";
+  const msg = normalizeLowercaseStringOrEmpty(response.msg);
   return msg.includes("withdrawn") || msg.includes("not found");
 }
 
@@ -40,9 +62,17 @@ function isWithdrawnReplyError(err: unknown): boolean {
   return false;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
 type FeishuCreateMessageClient = {
   im: {
     message: {
+      reply: (opts: {
+        path: { message_id: string };
+        data: { content: string; msg_type: string; reply_in_thread?: true };
+      }) => Promise<{ code?: number; msg?: string; data?: { message_id?: string } }>;
       create: (opts: {
         params: { receive_id_type: "chat_id" | "email" | "open_id" | "union_id" | "user_id" };
         data: { receive_id: string; content: string; msg_type: string };
@@ -51,6 +81,31 @@ type FeishuCreateMessageClient = {
   };
 };
 
+type FeishuMessageSender = {
+  id?: string;
+  id_type?: string;
+  sender_type?: string;
+};
+
+type FeishuMessageGetItem = {
+  message_id?: string;
+  chat_id?: string;
+  chat_type?: FeishuChatType;
+  thread_id?: string;
+  msg_type?: string;
+  body?: { content?: string };
+  sender?: FeishuMessageSender;
+  create_time?: string;
+};
+
+type FeishuGetMessageResponse = {
+  code?: number;
+  msg?: string;
+  data?: FeishuMessageGetItem & {
+    items?: FeishuMessageGetItem[];
+  };
+};
+
 /** Send a direct message as a fallback when a reply target is unavailable. */
 async function sendFallbackDirect(
   client: FeishuCreateMessageClient,
@@ -74,38 +129,180 @@ async function sendFallbackDirect(
   return toFeishuSendResult(response, params.receiveId);
 }
 
-function parseInteractiveCardContent(parsed: unknown): string {
-  if (!parsed || typeof parsed !== "object") {
-    return "[Interactive Card]";
+async function sendReplyOrFallbackDirect(
+  client: FeishuCreateMessageClient,
+  params: {
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    content: string;
+    msgType: string;
+    directParams: {
+      receiveId: string;
+      receiveIdType: "chat_id" | "email" | "open_id" | "union_id" | "user_id";
+      content: string;
+      msgType: string;
+    };
+    directErrorPrefix: string;
+    replyErrorPrefix: string;
+  },
+): Promise<FeishuSendResult> {
+  if (!params.replyToMessageId) {
+    return sendFallbackDirect(client, params.directParams, params.directErrorPrefix);
   }
 
-  const candidate = parsed as { elements?: unknown };
-  if (!Array.isArray(candidate.elements)) {
-    return "[Interactive Card]";
+  const threadReplyFallbackError = params.replyInThread
+    ? new Error(
+        "Feishu thread reply failed: reply target is unavailable and cannot safely fall back to a top-level send.",
+      )
+    : null;
+
+  let response: { code?: number; msg?: string; data?: { message_id?: string } };
+  try {
+    response = await client.im.message.reply({
+      path: { message_id: params.replyToMessageId },
+      data: {
+        content: params.content,
+        msg_type: params.msgType,
+        ...(params.replyInThread ? { reply_in_thread: true } : {}),
+      },
+    });
+  } catch (err) {
+    if (!isWithdrawnReplyError(err)) {
+      throw err;
+    }
+    if (threadReplyFallbackError) {
+      throw threadReplyFallbackError;
+    }
+    return sendFallbackDirect(client, params.directParams, params.directErrorPrefix);
+  }
+  if (shouldFallbackFromReplyTarget(response)) {
+    if (threadReplyFallbackError) {
+      throw threadReplyFallbackError;
+    }
+    return sendFallbackDirect(client, params.directParams, params.directErrorPrefix);
   }
+  assertFeishuMessageApiSuccess(response, params.replyErrorPrefix);
+  return toFeishuSendResult(response, params.directParams.receiveId);
+}
 
-  const texts: string[] = [];
-  for (const element of candidate.elements) {
-    if (!element || typeof element !== "object") {
+function normalizeCardTemplateVariable(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return undefined;
+}
+
+function readCardTemplateVariables(parsed: Record<string, unknown>): Map<string, string> {
+  const variables = new Map<string, string>();
+  for (const source of [parsed.template_variable, parsed.template_variables]) {
+    if (!isRecord(source)) {
       continue;
     }
-    const item = element as {
-      tag?: string;
-      content?: string;
-      text?: { content?: string };
-    };
-    if (item.tag === "div" && typeof item.text?.content === "string") {
-      texts.push(item.text.content);
+    for (const [key, value] of Object.entries(source)) {
+      const normalized = normalizeCardTemplateVariable(value);
+      if (normalized !== undefined) {
+        variables.set(key, normalized);
+      }
+    }
+  }
+  return variables;
+}
+
+function applyCardTemplateVariables(text: string, variables: Map<string, string>): string {
+  if (variables.size === 0) {
+    return text;
+  }
+  return text.replace(/\$\{([A-Za-z0-9_.-]+)\}|\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (match, a, b) => {
+    const variableName = typeof a === "string" ? a : b;
+    return variables.get(variableName) ?? match;
+  });
+}
+
+function extractInteractiveElementText(
+  element: unknown,
+  variables: Map<string, string>,
+): string | undefined {
+  if (!isRecord(element)) {
+    return undefined;
+  }
+  const tag = typeof element.tag === "string" ? element.tag : "";
+  const text = isRecord(element.text) ? element.text : undefined;
+
+  if (tag === "div" && typeof text?.content === "string") {
+    return applyCardTemplateVariables(text.content, variables);
+  }
+  if ((tag === "markdown" || tag === "lark_md") && typeof element.content === "string") {
+    return applyCardTemplateVariables(element.content, variables);
+  }
+  if (tag === "plain_text" && typeof element.content === "string") {
+    return applyCardTemplateVariables(element.content, variables);
+  }
+  return undefined;
+}
+
+function extractInteractiveElementsText(
+  elements: unknown[],
+  variables: Map<string, string>,
+): string {
+  const texts: string[] = [];
+  for (const element of elements) {
+    const text = extractInteractiveElementText(element, variables);
+    if (text !== undefined) {
+      texts.push(text);
+    }
+  }
+  return texts.join("\n").trim();
+}
+
+function readInteractiveElementArrays(parsed: Record<string, unknown>): unknown[][] {
+  const body = isRecord(parsed.body) ? parsed.body : undefined;
+  const elementArrays: unknown[][] = [];
+
+  for (const candidate of [parsed.elements, body?.elements]) {
+    if (Array.isArray(candidate)) {
+      elementArrays.push(candidate);
+    }
+  }
+
+  for (const candidate of [parsed.i18n_elements, body?.i18n_elements]) {
+    if (!isRecord(candidate)) {
       continue;
     }
-    if (item.tag === "markdown" && typeof item.content === "string") {
-      texts.push(item.content);
+    for (const localeElements of Object.values(candidate)) {
+      if (Array.isArray(localeElements)) {
+        elementArrays.push(localeElements);
+      }
     }
   }
-  return texts.join("\n").trim() || "[Interactive Card]";
+
+  return elementArrays;
+}
+
+function parseInteractivePostFallback(parsed: unknown): string | undefined {
+  const textContent = parsePostContent(JSON.stringify(parsed)).textContent.trim();
+  return textContent && textContent !== POST_FALLBACK_TEXT ? textContent : undefined;
 }
 
-function parseQuotedMessageContent(rawContent: string, msgType: string): string {
+function parseInteractiveCardContent(parsed: unknown): string {
+  if (!isRecord(parsed)) {
+    return INTERACTIVE_CARD_FALLBACK_TEXT;
+  }
+
+  const variables = readCardTemplateVariables(parsed);
+  for (const elements of readInteractiveElementArrays(parsed)) {
+    const text = extractInteractiveElementsText(elements, variables);
+    if (text) {
+      return text;
+    }
+  }
+
+  return parseInteractivePostFallback(parsed) ?? INTERACTIVE_CARD_FALLBACK_TEXT;
+}
+
+function parseFeishuMessageContent(rawContent: string, msgType: string): string {
   if (!rawContent) {
     return "";
   }
@@ -146,6 +343,33 @@ function parseQuotedMessageContent(rawContent: string, msgType: string): string
   return `[${msgType || "unknown"} message]`;
 }
 
+function parseFeishuMessageItem(
+  item: FeishuMessageGetItem,
+  fallbackMessageId?: string,
+): FeishuMessageInfo {
+  const msgType = item.msg_type ?? "text";
+  const rawContent = item.body?.content ?? "";
+
+  return {
+    messageId: item.message_id ?? fallbackMessageId ?? "",
+    chatId: item.chat_id ?? "",
+    chatType:
+      item.chat_type === "group" ||
+      item.chat_type === "topic_group" ||
+      item.chat_type === "private" ||
+      item.chat_type === "p2p"
+        ? item.chat_type
+        : undefined,
+    senderId: item.sender?.id,
+    senderOpenId: item.sender?.id_type === "open_id" ? item.sender?.id : undefined,
+    senderType: item.sender?.sender_type,
+    content: parseFeishuMessageContent(rawContent, msgType),
+    contentType: msgType,
+    createTime: item.create_time ? Number.parseInt(item.create_time, 10) : undefined,
+    threadId: item.thread_id || undefined,
+  };
+}
+
 /**
  * Get a message by its ID.
  * Useful for fetching quoted/replied message content.
@@ -156,7 +380,7 @@ export async function getMessageFeishu(params: {
   accountId?: string;
 }): Promise<FeishuMessageInfo | null> {
   const { cfg, messageId, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
   }
@@ -166,36 +390,7 @@ export async function getMessageFeishu(params: {
   try {
     const response = (await client.im.message.get({
       path: { message_id: messageId },
-    })) as {
-      code?: number;
-      msg?: string;
-      data?: {
-        items?: Array<{
-          message_id?: string;
-          chat_id?: string;
-          chat_type?: FeishuChatType;
-          msg_type?: string;
-          body?: { content?: string };
-          sender?: {
-            id?: string;
-            id_type?: string;
-            sender_type?: string;
-          };
-          create_time?: string;
-        }>;
-        message_id?: string;
-        chat_id?: string;
-        chat_type?: FeishuChatType;
-        msg_type?: string;
-        body?: { content?: string };
-        sender?: {
-          id?: string;
-          id_type?: string;
-          sender_type?: string;
-        };
-        create_time?: string;
-      };
-    };
+    })) as FeishuGetMessageResponse;
 
     if (response.code !== 0) {
       return null;
@@ -212,29 +407,104 @@ export async function getMessageFeishu(params: {
       return null;
     }
 
-    const msgType = item.msg_type ?? "text";
-    const rawContent = item.body?.content ?? "";
-    const content = parseQuotedMessageContent(rawContent, msgType);
-
-    return {
-      messageId: item.message_id ?? messageId,
-      chatId: item.chat_id ?? "",
-      chatType:
-        item.chat_type === "group" || item.chat_type === "private" || item.chat_type === "p2p"
-          ? item.chat_type
-          : undefined,
-      senderId: item.sender?.id,
-      senderOpenId: item.sender?.id_type === "open_id" ? item.sender?.id : undefined,
-      senderType: item.sender?.sender_type,
-      content,
-      contentType: msgType,
-      createTime: item.create_time ? parseInt(String(item.create_time), 10) : undefined,
-    };
+    return parseFeishuMessageItem(item, messageId);
   } catch {
     return null;
   }
 }
 
+export type FeishuThreadMessageInfo = {
+  messageId: string;
+  senderId?: string;
+  senderType?: string;
+  content: string;
+  contentType: string;
+  createTime?: number;
+};
+
+/**
+ * List messages in a Feishu thread (topic).
+ * Uses container_id_type=thread to directly query thread messages,
+ * which includes both the root message and all replies (including bot replies).
+ */
+export async function listFeishuThreadMessages(params: {
+  cfg: ClawdbotConfig;
+  threadId: string;
+  currentMessageId?: string;
+  /** Exclude the root message (already provided separately as ThreadStarterBody). */
+  rootMessageId?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuThreadMessageInfo[]> {
+  const { cfg, threadId, currentMessageId, rootMessageId, limit = 20, accountId } = params;
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const client = createFeishuClient(account);
+
+  const response = (await client.im.message.list({
+    params: {
+      container_id_type: "thread",
+      container_id: threadId,
+      // Fetch newest messages first so long threads keep the most recent turns.
+      // Results are reversed below to restore chronological order.
+      sort_type: "ByCreateTimeDesc",
+      page_size: Math.min(limit + 1, 50),
+    },
+  })) as {
+    code?: number;
+    msg?: string;
+    data?: {
+      items?: Array<
+        {
+          message_id?: string;
+          root_id?: string;
+          parent_id?: string;
+        } & FeishuMessageGetItem
+      >;
+    };
+  };
+
+  if (response.code !== 0) {
+    throw new Error(
+      `Feishu thread list failed: code=${response.code} msg=${response.msg ?? "unknown"}`,
+    );
+  }
+
+  const items = response.data?.items ?? [];
+  const results: FeishuThreadMessageInfo[] = [];
+
+  for (const item of items) {
+    if (currentMessageId && item.message_id === currentMessageId) {
+      continue;
+    }
+    if (rootMessageId && item.message_id === rootMessageId) {
+      continue;
+    }
+
+    const parsed = parseFeishuMessageItem(item);
+
+    results.push({
+      messageId: parsed.messageId,
+      senderId: parsed.senderId,
+      senderType: parsed.senderType,
+      content: parsed.content,
+      contentType: parsed.contentType,
+      createTime: parsed.createTime,
+    });
+
+    if (results.length >= limit) {
+      break;
+    }
+  }
+
+  // Restore chronological order (oldest first) since we fetched newest-first.
+  results.reverse();
+  return results;
+}
+
 export type SendFeishuMessageParams = {
   cfg: ClawdbotConfig;
   to: string;
@@ -248,7 +518,7 @@ export type SendFeishuMessageParams = {
   accountId?: string;
 };
 
-function buildFeishuPostMessagePayload(params: { messageText: string }): {
+export function buildFeishuPostMessagePayload(params: { messageText: string }): {
   content: string;
   msgType: string;
 } {
@@ -275,7 +545,7 @@ export async function sendMessageFeishu(
 ): Promise<FeishuSendResult> {
   const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId } = params;
   const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({ cfg, to, accountId });
-  const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
+  const tableMode = resolveMarkdownTableMode({
     cfg,
     channel: "feishu",
   });
@@ -285,37 +555,20 @@ export async function sendMessageFeishu(
   if (mentions && mentions.length > 0) {
     rawText = buildMentionedMessage(mentions, rawText);
   }
-  const messageText = getFeishuRuntime().channel.text.convertMarkdownTables(rawText, tableMode);
+  const messageText = convertMarkdownTables(rawText, tableMode);
 
   const { content, msgType } = buildFeishuPostMessagePayload({ messageText });
 
   const directParams = { receiveId, receiveIdType, content, msgType };
-
-  if (replyToMessageId) {
-    let response: { code?: number; msg?: string; data?: { message_id?: string } };
-    try {
-      response = await client.im.message.reply({
-        path: { message_id: replyToMessageId },
-        data: {
-          content,
-          msg_type: msgType,
-          ...(replyInThread ? { reply_in_thread: true } : {}),
-        },
-      });
-    } catch (err) {
-      if (!isWithdrawnReplyError(err)) {
-        throw err;
-      }
-      return sendFallbackDirect(client, directParams, "Feishu send failed");
-    }
-    if (shouldFallbackFromReplyTarget(response)) {
-      return sendFallbackDirect(client, directParams, "Feishu send failed");
-    }
-    assertFeishuMessageApiSuccess(response, "Feishu reply failed");
-    return toFeishuSendResult(response, receiveId);
-  }
-
-  return sendFallbackDirect(client, directParams, "Feishu send failed");
+  return sendReplyOrFallbackDirect(client, {
+    replyToMessageId,
+    replyInThread,
+    content,
+    msgType,
+    directParams,
+    directErrorPrefix: "Feishu send failed",
+    replyErrorPrefix: "Feishu reply failed",
+  });
 }
 
 export type SendFeishuCardParams = {
@@ -334,32 +587,68 @@ export async function sendCardFeishu(params: SendFeishuCardParams): Promise<Feis
   const content = JSON.stringify(card);
 
   const directParams = { receiveId, receiveIdType, content, msgType: "interactive" };
+  return sendReplyOrFallbackDirect(client, {
+    replyToMessageId,
+    replyInThread,
+    content,
+    msgType: "interactive",
+    directParams,
+    directErrorPrefix: "Feishu card send failed",
+    replyErrorPrefix: "Feishu card reply failed",
+  });
+}
 
-  if (replyToMessageId) {
-    let response: { code?: number; msg?: string; data?: { message_id?: string } };
-    try {
-      response = await client.im.message.reply({
-        path: { message_id: replyToMessageId },
-        data: {
-          content,
-          msg_type: "interactive",
-          ...(replyInThread ? { reply_in_thread: true } : {}),
-        },
-      });
-    } catch (err) {
-      if (!isWithdrawnReplyError(err)) {
-        throw err;
-      }
-      return sendFallbackDirect(client, directParams, "Feishu card send failed");
-    }
-    if (shouldFallbackFromReplyTarget(response)) {
-      return sendFallbackDirect(client, directParams, "Feishu card send failed");
+export async function editMessageFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  text?: string;
+  card?: Record<string, unknown>;
+  accountId?: string;
+}): Promise<{ messageId: string; contentType: "post" | "interactive" }> {
+  const { cfg, messageId, text, card, accountId } = params;
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  const hasText = typeof text === "string" && text.trim().length > 0;
+  const hasCard = Boolean(card);
+  if (hasText === hasCard) {
+    throw new Error("Feishu edit requires exactly one of text or card.");
+  }
+
+  const client = createFeishuClient(account);
+
+  if (card) {
+    const content = JSON.stringify(card);
+    const response = await client.im.message.patch({
+      path: { message_id: messageId },
+      data: { content },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`Feishu message edit failed: ${response.msg || `code ${response.code}`}`);
     }
-    assertFeishuMessageApiSuccess(response, "Feishu card reply failed");
-    return toFeishuSendResult(response, receiveId);
+
+    return { messageId, contentType: "interactive" };
+  }
+
+  const tableMode = resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+  const messageText = convertMarkdownTables(text!, tableMode);
+  const payload = buildFeishuPostMessagePayload({ messageText });
+  const response = await client.im.message.patch({
+    path: { message_id: messageId },
+    data: { content: payload.content },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu message edit failed: ${response.msg || `code ${response.code}`}`);
   }
 
-  return sendFallbackDirect(client, directParams, "Feishu card send failed");
+  return { messageId, contentType: "post" };
 }
 
 export async function updateCardFeishu(params: {
@@ -369,7 +658,7 @@ export async function updateCardFeishu(params: {
   accountId?: string;
 }): Promise<void> {
   const { cfg, messageId, card, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
   }
@@ -396,7 +685,7 @@ export function buildMarkdownCard(text: string): Record<string, unknown> {
   return {
     schema: "2.0",
     config: {
-      wide_screen_mode: true,
+      width_mode: "fill",
     },
     body: {
       elements: [
@@ -409,64 +698,97 @@ export function buildMarkdownCard(text: string): Record<string, unknown> {
   };
 }
 
+/** Header configuration for structured Feishu cards. */
+export type CardHeaderConfig = {
+  /** Header title text, e.g. "💻 Coder" */
+  title: string;
+  /** Feishu header color template (blue, green, red, orange, purple, grey, etc.). Defaults to "blue". */
+  template?: string;
+};
+
+export function resolveFeishuCardTemplate(template?: string): string | undefined {
+  const normalized = normalizeOptionalLowercaseString(template);
+  if (!normalized || !FEISHU_CARD_TEMPLATES.has(normalized)) {
+    return undefined;
+  }
+  return normalized;
+}
+
 /**
- * Send a message as a markdown card (interactive message).
- * This renders markdown properly in Feishu (code blocks, tables, bold/italic, etc.)
+ * Build a Feishu interactive card with optional header and note footer.
+ * When header/note are omitted, behaves identically to buildMarkdownCard.
  */
-export async function sendMarkdownCardFeishu(params: {
+export function buildStructuredCard(
+  text: string,
+  options?: {
+    header?: CardHeaderConfig;
+    note?: string;
+  },
+): Record<string, unknown> {
+  const elements: Record<string, unknown>[] = [{ tag: "markdown", content: text }];
+  if (options?.note) {
+    elements.push({ tag: "hr" });
+    elements.push({ tag: "markdown", content: `<font color='grey'>${options.note}</font>` });
+  }
+  const card: Record<string, unknown> = {
+    schema: "2.0",
+    config: { width_mode: "fill" },
+    body: { elements },
+  };
+  if (options?.header) {
+    card.header = {
+      title: { tag: "plain_text", content: options.header.title },
+      template: resolveFeishuCardTemplate(options.header.template) ?? "blue",
+    };
+  }
+  return card;
+}
+
+/**
+ * Send a message as a structured card with optional header and note.
+ */
+export async function sendStructuredCardFeishu(params: {
   cfg: ClawdbotConfig;
   to: string;
   text: string;
   replyToMessageId?: string;
   /** When true, reply creates a Feishu topic thread instead of an inline reply */
   replyInThread?: boolean;
-  /** Mention target users */
   mentions?: MentionTarget[];
   accountId?: string;
+  header?: CardHeaderConfig;
+  note?: string;
 }): Promise<FeishuSendResult> {
-  const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId } = params;
+  const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId, header, note } =
+    params;
   let cardText = text;
   if (mentions && mentions.length > 0) {
     cardText = buildMentionedCardContent(mentions, text);
   }
-  const card = buildMarkdownCard(cardText);
+  const card = buildStructuredCard(cardText, { header, note });
   return sendCardFeishu({ cfg, to, card, replyToMessageId, replyInThread, accountId });
 }
 
 /**
- * Edit an existing text message.
- * Note: Feishu only allows editing messages within 24 hours.
+ * Send a message as a markdown card (interactive message).
+ * This renders markdown properly in Feishu (code blocks, tables, bold/italic, etc.)
  */
-export async function editMessageFeishu(params: {
+export async function sendMarkdownCardFeishu(params: {
   cfg: ClawdbotConfig;
-  messageId: string;
+  to: string;
   text: string;
+  replyToMessageId?: string;
+  /** When true, reply creates a Feishu topic thread instead of an inline reply */
+  replyInThread?: boolean;
+  /** Mention target users */
+  mentions?: MentionTarget[];
   accountId?: string;
-}): Promise<void> {
-  const { cfg, messageId, text, accountId } = params;
-  const account = resolveFeishuAccount({ cfg, accountId });
-  if (!account.configured) {
-    throw new Error(`Feishu account "${account.accountId}" not configured`);
-  }
-
-  const client = createFeishuClient(account);
-  const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
-    cfg,
-    channel: "feishu",
-  });
-  const messageText = getFeishuRuntime().channel.text.convertMarkdownTables(text ?? "", tableMode);
-
-  const { content, msgType } = buildFeishuPostMessagePayload({ messageText });
-
-  const response = await client.im.message.update({
-    path: { message_id: messageId },
-    data: {
-      msg_type: msgType,
-      content,
-    },
-  });
-
-  if (response.code !== 0) {
-    throw new Error(`Feishu message edit failed: ${response.msg || `code ${response.code}`}`);
+}): Promise<FeishuSendResult> {
+  const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId } = params;
+  let cardText = text;
+  if (mentions && mentions.length > 0) {
+    cardText = buildMentionedCardContent(mentions, text);
   }
+  const card = buildMarkdownCard(cardText);
+  return sendCardFeishu({ cfg, to, card, replyToMessageId, replyInThread, accountId });
 }