@keyou007/agent-bot 0.1.14 → 0.1.15-alpha.1

package/src/feishu/FeishuMessageClient.ts

@@ -7,6 +7,14 @@ import type { AppConfig } from "../config/schema.js";
 import { normalizeFeishuMarkdown } from "./FeishuMarkdown.js";
 import { LOCAL_CARD_IMAGE_PATH } from "./LocalCardImage.js";
 import { renderMarkdownWithLocalImages } from "./LocalImageMarkdown.js";
+import { splitFinalResponseBranding } from "./FinalResponseBranding.js";
+import {
+  renderMergedForwardPrompt,
+  renderReferencedMessage,
+  type MergedForwardContent,
+  type MergedForwardMessageItem,
+  type ReferencedMessageContent,
+} from "./MergedForwardMessage.js";
 import type {
   CreatedGroup,
   CreateGroupInput,
@@ -79,15 +87,26 @@ interface DownloadImageErrorResponse {
   error?: unknown;
 }
 
+interface GetMessageResponse {
+  code: number;
+  msg: string;
+  data?: {
+    items?: MergedForwardMessageItem[];
+  };
+  error?: unknown;
+}
+
 export class FeishuMessageClient implements FeishuOutbound {
   private token?: {
     value: string;
     expiresAt: number;
   };
   private readonly sendQueues = new Map<string, Promise<void>>();
+  private readonly cardUpdateQueues = new Map<string, Promise<void>>();
   private readonly lastSendAt = new Map<string, number>();
   private readonly imageUploads = new Map<string, { mtimeMs: number; upload: Promise<string> }>();
   private readonly imageDownloads = new Map<string, Promise<string>>();
+  private readonly fileDownloads = new Map<string, Promise<string>>();
   private readonly minSendIntervalMs = 1200;
 
   constructor(
@@ -215,6 +234,51 @@ export class FeishuMessageClient implements FeishuOutbound {
     return download;
   }
 
+  async downloadFile(messageId: string, fileKey: string, fileName: string): Promise<string> {
+    const cacheKey = `${messageId}:${fileKey}`;
+    const cached = this.fileDownloads.get(cacheKey);
+    if (cached) return cached;
+    const download = this.downloadFileNow(messageId, fileKey, fileName).catch((error: unknown) => {
+      if (this.fileDownloads.get(cacheKey) === download) this.fileDownloads.delete(cacheKey);
+      throw error;
+    });
+    this.fileDownloads.set(cacheKey, download);
+    return download;
+  }
+
+  async readMergedForward(messageId: string): Promise<MergedForwardContent> {
+    const items = await this.readMessageItems(messageId, "read merged forward");
+    return renderMergedForwardPrompt(messageId, items);
+  }
+
+  async readReferencedMessage(messageId: string): Promise<ReferencedMessageContent> {
+    const items = await this.readMessageItems(messageId, "read referenced message");
+    return renderReferencedMessage(messageId, items);
+  }
+
+  private async readMessageItems(messageId: string, operation: string): Promise<MergedForwardMessageItem[]> {
+    try {
+      const token = await this.getTenantAccessToken();
+      const response = await fetch(
+        `https://open.feishu.cn/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`,
+        { headers: { Authorization: `Bearer ${token}` } },
+      );
+      const payload = (await response.json()) as GetMessageResponse;
+      if (!response.ok || payload.code !== 0) {
+        throw new FeishuApiError(
+          payload.msg || response.statusText,
+          payload.code,
+          payload,
+          operation,
+          response.status,
+        );
+      }
+      return payload.data?.items ?? [];
+    } catch (error) {
+      throw normalizeTransportError(error, operation);
+    }
+  }
+
   async sendText(contextKey: string, text: string): Promise<string | undefined> {
     return this.sendMessage(contextKey, "text", { text });
   }
@@ -226,11 +290,7 @@ export class FeishuMessageClient implements FeishuOutbound {
 
   async sendMarkdown(contextKey: string, markdown: string, idempotencyKey?: string): Promise<string | undefined> {
     const normalizedMarkdown = normalizeFeishuMarkdown(markdown);
-    const elements = await renderMarkdownWithLocalImages(
-      normalizedMarkdown,
-      (filePath) => this.uploadImageCached(filePath),
-      (error, filePath) => this.logger.warn({ error, filePath }, "Failed to upload local image to Feishu."),
-    );
+    const elements = await this.renderFinalAnswerElements(normalizedMarkdown);
     return this.sendMessage(
       contextKey,
       "interactive",
@@ -272,11 +332,7 @@ export class FeishuMessageClient implements FeishuOutbound {
     idempotencyKey?: string,
   ): Promise<string | undefined> {
     const normalizedMarkdown = normalizeFeishuMarkdown(markdown);
-    const elements = await renderMarkdownWithLocalImages(
-      normalizedMarkdown,
-      (filePath) => this.uploadImageCached(filePath),
-      (error, filePath) => this.logger.warn({ error, filePath }, "Failed to upload local image to Feishu."),
-    );
+    const elements = await this.renderFinalAnswerElements(normalizedMarkdown);
     return this.replyMessage(
       contextKey,
       target,
@@ -302,9 +358,28 @@ export class FeishuMessageClient implements FeishuOutbound {
     );
   }
 
+  private async renderFinalAnswerElements(markdown: string): Promise<Array<Record<string, unknown>>> {
+    const { content, branding } = splitFinalResponseBranding(markdown);
+    const elements = content
+      ? await renderMarkdownWithLocalImages(
+        content,
+        (filePath) => this.uploadImageCached(filePath),
+        (error, filePath) => this.logger.warn({ error, filePath }, "Failed to upload local image to Feishu."),
+      )
+      : [];
+    if (!branding) return elements;
+    return [
+      ...elements,
+      { tag: "hr" },
+      { tag: "markdown", content: branding, text_size: "notation" },
+    ];
+  }
+
   async updateInteractiveCard(messageId: string, card: Record<string, unknown>): Promise<void> {
-    const preparedCard = await this.prepareInteractiveCard(card);
-    await this.updateInteractiveCardNow(messageId, preparedCard);
+    await this.enqueueCardUpdate(messageId, async () => {
+      const preparedCard = await this.prepareInteractiveCard(card);
+      await this.updateInteractiveCardNow(messageId, preparedCard);
+    });
   }
 
   private async updateInteractiveCardNow(
@@ -564,6 +639,22 @@ export class FeishuMessageClient implements FeishuOutbound {
     return queued;
   }
 
+  private enqueueCardUpdate(messageId: string, task: () => Promise<void>): Promise<void> {
+    const previous = this.cardUpdateQueues.get(messageId) ?? Promise.resolve();
+    const queued = previous.catch(() => undefined).then(task);
+    const stored = queued.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.cardUpdateQueues.set(messageId, stored);
+    stored.finally(() => {
+      if (this.cardUpdateQueues.get(messageId) === stored) {
+        this.cardUpdateQueues.delete(messageId);
+      }
+    });
+    return queued;
+  }
+
   private async getTenantAccessToken(): Promise<string> {
     const now = Date.now();
     if (this.token && this.token.expiresAt > now + 60_000) {
@@ -711,6 +802,42 @@ export class FeishuMessageClient implements FeishuOutbound {
     }
   }
 
+  private async downloadFileNow(messageId: string, fileKey: string, fileName: string): Promise<string> {
+    try {
+      const token = await this.getTenantAccessToken();
+      const response = await fetch(
+        `https://open.feishu.cn/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/resources/${encodeURIComponent(fileKey)}?type=file`,
+        { headers: { Authorization: `Bearer ${token}` } },
+      );
+      if (!response.ok) {
+        const payload = await response.json().catch(() => ({
+          code: response.status,
+          msg: response.statusText,
+        })) as DownloadImageErrorResponse;
+        throw new FeishuApiError(
+          payload.msg || response.statusText,
+          payload.code,
+          payload,
+          "download file",
+          response.status,
+        );
+      }
+
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (bytes.byteLength === 0) throw new Error("Feishu returned an empty file.");
+      const sqlitePath = this.config.storage?.sqlitePath ?? defaultSqlitePath();
+      const directory = path.join(path.dirname(sqlitePath), "inbound-files");
+      await mkdir(directory, { recursive: true });
+      const digest = createHash("sha256").update(`${messageId}:${fileKey}`).digest("hex").slice(0, 16);
+      const safeName = safeInboundFileName(fileName);
+      const filePath = path.join(directory, `${digest}-${safeName}`);
+      await writeFile(filePath, bytes);
+      return filePath;
+    } catch (error) {
+      throw normalizeTransportError(error, "download file");
+    }
+  }
+
   private async uploadImageCached(filePath: string): Promise<string> {
     const cacheKey = path.resolve(filePath);
     const mtimeMs = (await stat(cacheKey)).mtimeMs;
@@ -794,6 +921,18 @@ function imageExtension(contentType: string): string {
   }
 }
 
+function safeInboundFileName(value: string): string {
+  const baseName = path.basename(value.trim() || "file");
+  const sanitized = baseName
+    .replace(/[<>:"/\\|?*\u0000-\u001f]/gu, "_")
+    .replace(/[. ]+$/gu, "")
+    .slice(0, 180)
+    || "file";
+  return /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(sanitized)
+    ? `_${sanitized}`
+    : sanitized;
+}
+
 function normalizeTransportError(error: unknown, operation: string): FeishuApiError {
   if (error instanceof FeishuApiError) return error;
   const message = error instanceof Error ? error.message : String(error);

package/src/feishu/FeishuTurnPresenter.ts

@@ -8,7 +8,11 @@ import { splitMarkdown } from "../presentation/splitMarkdown.js";
 import type { TurnViewState } from "../presentation/turnViewTypes.js";
 import { CardRenderer } from "./CardRenderer.js";
 import { CardUpdateScheduler } from "./CardUpdateScheduler.js";
+import { normalizeFeishuMarkdown } from "./FeishuMarkdown.js";
 import type { FeishuOutbound, MessageReplyTarget } from "./types.js";
+import {
+  FINAL_RESPONSE_BRANDING_BLOCK,
+} from "./FinalResponseBranding.js";
 import { createId } from "../utils/id.js";
 import { createHash } from "node:crypto";
 
@@ -50,6 +54,7 @@ export interface FeishuTurnPresenterOptions {
 
 const MAX_FINAL_TABLES_PER_CARD = 5;
 const DEFAULT_ELAPSED_UPDATE_INTERVAL_MS = 3_000;
+const FINAL_RESPONSE_BRANDING_MIN_LENGTH = 1_000;
 
 interface TurnEntry {
   contextKey: string;
@@ -532,10 +537,10 @@ export class FeishuTurnPresenter {
   private async deliverFinal(contextKey: string, state: TurnViewState): Promise<void> {
     const delivery = this.store.getTurnDelivery(state.turnId);
     if (delivery?.finalDelivered || !state.finalResponse) return;
-    const chunks = splitMarkdown(
-      state.finalResponse,
-      this.options.finalChunkLength ?? 4_000,
-      MAX_FINAL_TABLES_PER_CARD,
+    const finalChunkLength = this.options.finalChunkLength ?? 4_000;
+    const chunks = brandedFinalChunks(
+      normalizeFeishuMarkdown(state.finalResponse, state.projectCwd),
+      finalChunkLength,
     );
     const messageIds = [...(delivery?.finalMessageIds ?? [])];
     for (let index = messageIds.length; index < chunks.length; index += 1) {
@@ -574,6 +579,25 @@ export class FeishuTurnPresenter {
   }
 }
 
+function brandedFinalChunks(response: string, maxLength: number): string[] {
+  const chunks = splitMarkdown(response, maxLength, MAX_FINAL_TABLES_PER_CARD);
+  if (chunks.length <= 1 && response.length < FINAL_RESPONSE_BRANDING_MIN_LENGTH) return chunks;
+
+  const last = chunks.pop();
+  if (last === undefined) return chunks;
+  const reservedLength = FINAL_RESPONSE_BRANDING_BLOCK.length + 2;
+  const brandedContentLimit = maxLength - reservedLength;
+  if (brandedContentLimit < 32) return [...chunks, last, FINAL_RESPONSE_BRANDING_BLOCK];
+
+  const lastParts = splitMarkdown(last, brandedContentLimit, MAX_FINAL_TABLES_PER_CARD);
+  const lastContent = lastParts.pop();
+  if (lastContent === undefined || lastContent.length > brandedContentLimit) {
+    return [...chunks, ...lastParts, lastContent ?? last, FINAL_RESPONSE_BRANDING_BLOCK];
+  }
+  const separator = lastContent.endsWith("\n\n") ? "" : lastContent.endsWith("\n") ? "\n" : "\n\n";
+  return [...chunks, ...lastParts, `${lastContent}${separator}${FINAL_RESPONSE_BRANDING_BLOCK}`];
+}
+
 function eventPriority(event: AgentEvent): "normal" | "critical" {
   if (event.type === "turn_started" || event.type === "approval_requested" || event.type === "approval_resolved" || event.type === "tool_started") {
     return "critical";

package/src/feishu/FinalResponseBranding.ts

@@ -0,0 +1,18 @@
+export const FINAL_RESPONSE_BRANDING = "> Powered by [AgentBot](https://github.com/keyou/agent-bot)";
+export const FINAL_RESPONSE_BRANDING_BLOCK = `----\n\n${FINAL_RESPONSE_BRANDING}`;
+
+export function splitFinalResponseBranding(markdown: string): {
+  content: string;
+  branding?: string;
+} {
+  if (markdown === FINAL_RESPONSE_BRANDING_BLOCK) {
+    return { content: "", branding: FINAL_RESPONSE_BRANDING };
+  }
+
+  const suffix = `\n\n${FINAL_RESPONSE_BRANDING_BLOCK}`;
+  if (!markdown.endsWith(suffix)) return { content: markdown };
+  return {
+    content: markdown.slice(0, -suffix.length),
+    branding: FINAL_RESPONSE_BRANDING,
+  };
+}

package/src/feishu/InboundText.ts

@@ -0,0 +1,12 @@
+export function normalizeFeishuPostText(value: string): string {
+  return value
+    .replace(/<br\s*\/?>/giu, "\n")
+    .replace(/<\/p\s*>/giu, "\n")
+    .replace(/<p(?:\s[^>]*)?>/giu, "")
+    .replace(/&nbsp;/giu, " ")
+    .replace(/&lt;/giu, "<")
+    .replace(/&gt;/giu, ">")
+    .replace(/&amp;/giu, "&")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+}

package/src/feishu/MergedForwardMessage.ts

@@ -0,0 +1,372 @@
+import { normalizeFeishuPostText } from "./InboundText.js";
+
+export const MAX_MERGED_FORWARD_PROMPT_CHARS = 48_000;
+
+export interface MergedForwardMessageItem {
+  message_id?: string;
+  msg_type?: string;
+  create_time?: string;
+  deleted?: boolean;
+  sender?: {
+    id?: string;
+    sender_type?: string;
+  };
+  body?: {
+    content?: string;
+  };
+  mentions?: Array<{
+    key?: string;
+    id?: string;
+    name?: string;
+  }>;
+  upper_message_id?: string;
+}
+
+export interface MergedForwardContent {
+  text: string;
+  messageCount: number;
+  truncated: boolean;
+  images: MergedForwardImageReference[];
+  files: MergedForwardFileReference[];
+}
+
+export interface MergedForwardImageReference {
+  messageId: string;
+  imageKey: string;
+}
+
+export interface MergedForwardFileReference {
+  messageId: string;
+  fileKey: string;
+  fileName: string;
+}
+
+export interface ReferencedMessageContent {
+  text: string;
+  messageType: string;
+  images: MergedForwardImageReference[];
+  files: MergedForwardFileReference[];
+}
+
+export function renderReferencedMessage(
+  messageId: string,
+  items: MergedForwardMessageItem[],
+): ReferencedMessageContent {
+  const item = items.find((candidate) => candidate.message_id === messageId)
+    ?? items.find((candidate) => !candidate.upper_message_id)
+    ?? items[0];
+  if (!item) throw new Error("引用消息不存在或已无法访问。");
+
+  if (item.msg_type === "merge_forward") {
+    const merged = renderMergedForwardPrompt(messageId, items);
+    return {
+      text: `[消息类型：合并转发]\n${merged.text}`,
+      messageType: "merge_forward",
+      images: merged.images,
+      files: merged.files,
+    };
+  }
+
+  const images: MergedForwardImageReference[] = [];
+  const files: MergedForwardFileReference[] = [];
+  const imageNumbers = new Map<string, number>();
+  const content = renderMessageContent(item, (imageKey) => {
+    if (!imageKey) return "[图片]";
+    let imageNumber = imageNumbers.get(imageKey);
+    if (!imageNumber) {
+      imageNumber = images.length + 1;
+      imageNumbers.set(imageKey, imageNumber);
+      images.push({ messageId, imageKey });
+    }
+    return `[图片 ${imageNumber}]`;
+  }, (fileKey, fileName) => {
+    if (!fileKey) return namedPlaceholder("文件", fileName);
+    const fileNumber = files.length + 1;
+    const resolvedName = fileName || `file-${fileNumber}`;
+    files.push({ messageId, fileKey, fileName: resolvedName });
+    return `[文件 ${fileNumber}：${resolvedName}]`;
+  });
+  const messageType = item.msg_type?.trim() || "unknown";
+  return {
+    text: `[消息类型：${messageTypeLabel(messageType)}]\n${content}`,
+    messageType,
+    images,
+    files,
+  };
+}
+
+export function renderMergedForwardPrompt(
+  parentMessageId: string,
+  items: MergedForwardMessageItem[],
+  maxChars = MAX_MERGED_FORWARD_PROMPT_CHARS,
+): MergedForwardContent {
+  const children = items.filter((item) => item.upper_message_id === parentMessageId);
+  if (children.length === 0) throw new Error("合并转发消息中没有可读取的子消息。");
+
+  const senderLabels = new Map<string, string>();
+  const imageNumbers = new Map<string, number>();
+  const images: MergedForwardImageReference[] = [];
+  const files: MergedForwardFileReference[] = [];
+  let userIndex = 0;
+  let appIndex = 0;
+  const blocks = children.map((item, index) => {
+    const sender = item.sender?.id?.trim();
+    let senderLabel = "未知发送者";
+    if (sender) {
+      const senderType = item.sender?.sender_type === "app" ? "app" : "user";
+      const senderKey = `${senderType}:${sender}`;
+      const existing = senderLabels.get(senderKey);
+      if (existing) {
+        senderLabel = existing;
+      } else {
+        senderLabel = senderType === "app" ? `应用 ${++appIndex}` : `成员 ${++userIndex}`;
+        senderLabels.set(senderKey, senderLabel);
+      }
+    }
+    const time = formatMessageTime(item.create_time);
+    const heading = [`消息 ${index + 1}`, senderLabel, time].filter(Boolean).join(" · ");
+    return `[${heading}]\n${renderMessageContent(item, (imageKey) => {
+      const messageId = item.message_id?.trim();
+      if (!messageId || !imageKey) return "[图片]";
+      const referenceKey = `${messageId}:${imageKey}`;
+      let imageNumber = imageNumbers.get(referenceKey);
+      if (!imageNumber) {
+        imageNumber = images.length + 1;
+        imageNumbers.set(referenceKey, imageNumber);
+        images.push({ messageId, imageKey });
+      }
+      return `[图片 ${imageNumber}]`;
+    }, (fileKey, fileName) => {
+      const messageId = item.message_id?.trim();
+      if (!messageId || !fileKey) return namedPlaceholder("文件", fileName);
+      const fileNumber = files.length + 1;
+      files.push({ messageId, fileKey, fileName: fileName || `file-${fileNumber}` });
+      return `[文件 ${fileNumber}：${fileName || `file-${fileNumber}`}]`;
+    })}`;
+  });
+  const prompt = [
+    `用户转发了一组聊天记录（共 ${children.length} 条）。以下内容是引用的聊天记录，请结合这些内容回应用户。`,
+    ...blocks,
+  ].join("\n\n");
+  const truncated = truncateMiddle(prompt, maxChars);
+  return {
+    text: truncated.text,
+    messageCount: children.length,
+    truncated: truncated.truncated,
+    images,
+    files,
+  };
+}
+
+function renderMessageContent(
+  item: MergedForwardMessageItem,
+  imageLabel: (imageKey: string) => string,
+  fileLabel: (fileKey: string, fileName: string) => string,
+): string {
+  if (item.deleted) return "[消息已撤回]";
+  const messageType = item.msg_type?.trim() || "unknown";
+  const content = parseJsonObject(item.body?.content);
+  switch (messageType) {
+    case "text":
+      return replaceMentions(textValue(content.text), item.mentions) || "[空文本消息]";
+    case "post":
+      return renderPost(content, item.mentions, imageLabel) || "[空富文本消息]";
+    case "image":
+      return imageLabel(textValue(content.image_key));
+    case "file":
+      return fileLabel(
+        textValue(content.file_key),
+        textValue(content.file_name ?? content.name),
+      );
+    case "folder":
+      return namedPlaceholder("文件夹", content.title ?? content.name);
+    case "audio":
+      return "[语音]";
+    case "media":
+      return namedPlaceholder("视频", content.file_name ?? content.name);
+    case "sticker":
+      return "[表情包]";
+    case "interactive":
+      return renderInteractiveCard(content) || "[消息卡片]";
+    case "share_chat":
+      return "[群名片]";
+    case "share_user":
+      return "[个人名片]";
+    case "location": {
+      const detail = [textValue(content.name), textValue(content.address)].filter(Boolean).join(" · ");
+      return detail ? `[位置] ${detail}` : "[位置]";
+    }
+    case "todo": {
+      const summary = isRecord(content.summary) ? renderPost(content.summary, item.mentions, imageLabel) : "";
+      return summary ? `[任务] ${summary}` : "[任务]";
+    }
+    case "vote": {
+      const topic = textValue(content.topic);
+      const options = Array.isArray(content.options)
+        ? content.options.map(textValue).filter(Boolean).join(" / ")
+        : "";
+      return [`[投票]${topic ? ` ${topic}` : ""}`, options].filter(Boolean).join("\n");
+    }
+    case "system":
+      return "[系统消息]";
+    default:
+      return `[暂不支持的消息类型：${messageType}]`;
+  }
+}
+
+function messageTypeLabel(messageType: string): string {
+  switch (messageType) {
+    case "text": return "文本";
+    case "post": return "富文本";
+    case "image": return "图片";
+    case "file": return "文件";
+    case "folder": return "文件夹";
+    case "audio": return "语音";
+    case "media": return "视频";
+    case "sticker": return "表情包";
+    case "interactive": return "卡片";
+    case "share_chat": return "群名片";
+    case "share_user": return "个人名片";
+    case "location": return "位置";
+    case "todo": return "任务";
+    case "vote": return "投票";
+    case "system": return "系统消息";
+    default: return messageType;
+  }
+}
+
+function renderInteractiveCard(content: Record<string, unknown>): string {
+  const values: string[] = [];
+  collectCardText(content, undefined, values);
+  return [...new Set(values.map((value) => normalizeFeishuPostText(value)).filter(Boolean))].join("\n");
+}
+
+function collectCardText(value: unknown, key: string | undefined, output: string[]): void {
+  if (typeof value === "string") {
+    if (key === "content" || key === "text" || key === "title" || key === "subtitle") output.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectCardText(item, key, output);
+    return;
+  }
+  if (!isRecord(value)) return;
+  for (const [childKey, childValue] of Object.entries(value)) {
+    collectCardText(childValue, childKey, output);
+  }
+}
+
+function renderPost(
+  content: Record<string, unknown>,
+  mentions: MergedForwardMessageItem["mentions"],
+  imageLabel: (imageKey: string) => string,
+): string {
+  const locale = selectPostLocale(content);
+  if (!locale) return "";
+  const paragraphs: string[] = [];
+  const title = normalizeFeishuPostText(textValue(locale.title));
+  if (title) paragraphs.push(title);
+  if (!Array.isArray(locale.content)) return paragraphs.join("\n");
+  for (const row of locale.content) {
+    if (!Array.isArray(row)) continue;
+    let rowText = "";
+    for (const rawElement of row) {
+      if (!isRecord(rawElement)) continue;
+      const tag = textValue(rawElement.tag);
+      if (tag === "text" || tag === "a") {
+        rowText += textValue(rawElement.text);
+      } else if (tag === "at") {
+        rowText += renderMention(rawElement, mentions);
+      } else if (tag === "img") {
+        rowText += imageLabel(textValue(rawElement.image_key));
+      } else if (tag === "media") {
+        rowText += "[媒体]";
+      }
+    }
+    const normalized = normalizeFeishuPostText(rowText);
+    if (normalized) paragraphs.push(normalized);
+  }
+  return paragraphs.join("\n");
+}
+
+function renderMention(
+  element: Record<string, unknown>,
+  mentions: MergedForwardMessageItem["mentions"],
+): string {
+  const explicitName = textValue(element.user_name ?? element.name);
+  if (explicitName) return `@${explicitName}`;
+  const userId = textValue(element.user_id ?? element.open_id);
+  const resolved = mentions?.find((mention) => mention.id === userId)?.name;
+  return resolved ? `@${resolved}` : "@成员";
+}
+
+function replaceMentions(text: string, mentions: MergedForwardMessageItem["mentions"]): string {
+  let output = text;
+  for (const mention of mentions ?? []) {
+    if (!mention.key || !mention.name) continue;
+    output = output.split(mention.key).join(`@${mention.name}`);
+  }
+  return output.trim();
+}
+
+function selectPostLocale(content: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (Array.isArray(content.content)) return content;
+  for (const locale of ["zh_cn", "en_us", "ja_jp"]) {
+    if (isRecord(content[locale])) return content[locale];
+  }
+  return Object.values(content).find(isRecord);
+}
+
+function parseJsonObject(value: unknown): Record<string, unknown> {
+  if (isRecord(value)) return value;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function namedPlaceholder(kind: string, value: unknown): string {
+  const name = textValue(value).trim();
+  return name ? `[${kind}：${name}]` : `[${kind}]`;
+}
+
+function formatMessageTime(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const timestamp = Number(value);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.getTime())) return undefined;
+  return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/u, " UTC");
+}
+
+function truncateMiddle(value: string, maxChars: number): { text: string; truncated: boolean } {
+  const limit = Math.max(0, Math.floor(maxChars));
+  const characters = Array.from(value);
+  if (characters.length <= limit) return { text: value, truncated: false };
+  const marker = Array.from("\n\n... [合并转发内容过长，中间部分已截断] ...\n\n");
+  if (limit <= marker.length) {
+    return { text: marker.slice(0, limit).join(""), truncated: true };
+  }
+  const available = limit - marker.length;
+  const headLength = Math.ceil(available * 0.45);
+  const tailLength = available - headLength;
+  return {
+    text: [
+      ...characters.slice(0, headLength),
+      ...marker,
+      ...(tailLength > 0 ? characters.slice(-tailLength) : []),
+    ].join(""),
+    truncated: true,
+  };
+}
+
+function textValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}