@m1heng-clawd/feishu 0.1.14 → 0.1.16

package/src/media-duration.ts

@@ -0,0 +1,190 @@
+/**
+ * Media duration parsers for Feishu file upload.
+ *
+ * Feishu's im.file.create API requires a `duration` (in ms) for audio and video
+ * so that the player shows the correct length and enables seeking.
+ *
+ * Supported containers:
+ *   - OGG  (Opus / Vorbis)  — used by Feishu voice messages and most AI TTS output
+ *   - MP4  (ISO base media) — MP4, MOV, QuickTime, M4A, M4V, 3GP share this format
+ *   - WAV  (RIFF PCM)       — uncompressed audio
+ *
+ * Formats intentionally skipped (complex frame-level parsing, rare in practice):
+ *   - MP3 (VBR makes byte-count estimation unreliable without scanning all frames)
+ *   - Raw AAC / ADTS
+ */
+
+/**
+ * Parse duration from an OGG container (Opus or Vorbis).
+ * Reads the granule position from the last OGG page and divides by sample rate.
+ * Returns duration in milliseconds, or undefined if not OGG or parsing fails.
+ */
+export function parseOggDurationMs(buffer: Buffer): number | undefined {
+  if (buffer.length < 27) return undefined;
+  // Verify OGG capture pattern "OggS"
+  if (buffer[0] !== 0x4f || buffer[1] !== 0x67 || buffer[2] !== 0x67 || buffer[3] !== 0x53) {
+    return undefined;
+  }
+
+  // Detect codec and sample rate from identification header (scan first 4 KB)
+  let sampleRate = 0;
+  const searchLen = Math.min(buffer.length, 4096);
+  for (let i = 0; i < searchLen - 8; i++) {
+    // "OpusHead" — Opus always uses 48000 Hz for granule positions
+    if (
+      buffer[i] === 0x4f && buffer[i + 1] === 0x70 && buffer[i + 2] === 0x75 &&
+      buffer[i + 3] === 0x73 && buffer[i + 4] === 0x48 && buffer[i + 5] === 0x65 &&
+      buffer[i + 6] === 0x61 && buffer[i + 7] === 0x64
+    ) {
+      sampleRate = 48000;
+      break;
+    }
+    // "\x01vorbis" — sample rate is uint32LE at +12 from start of tag
+    if (
+      buffer[i] === 0x01 && buffer[i + 1] === 0x76 && buffer[i + 2] === 0x6f &&
+      buffer[i + 3] === 0x72 && buffer[i + 4] === 0x62 && buffer[i + 5] === 0x69 &&
+      buffer[i + 6] === 0x73
+    ) {
+      if (i + 16 <= buffer.length) sampleRate = buffer.readUInt32LE(i + 12);
+      break;
+    }
+  }
+  if (sampleRate === 0) return undefined;
+
+  // Scan all OGG pages to find the highest valid granule position
+  let lastGranule = 0;
+  let offset = 0;
+  while (offset + 27 <= buffer.length) {
+    if (
+      buffer[offset] !== 0x4f || buffer[offset + 1] !== 0x67 ||
+      buffer[offset + 2] !== 0x67 || buffer[offset + 3] !== 0x53
+    ) break;
+    // Granule position: 8 bytes LE at offset+6; 0xFFFFFFFFFFFFFFFF means "no position"
+    const lo = buffer.readUInt32LE(offset + 6);
+    const hi = buffer.readUInt32LE(offset + 10);
+    if (lo !== 0xffffffff || hi !== 0xffffffff) {
+      const granule = hi * 0x100000000 + lo;
+      if (granule > lastGranule) lastGranule = granule;
+    }
+    const numSegments = buffer.readUInt8(offset + 26);
+    if (offset + 27 + numSegments > buffer.length) break;
+    let pageDataSize = 0;
+    for (let i = 0; i < numSegments; i++) pageDataSize += buffer.readUInt8(offset + 27 + i);
+    offset += 27 + numSegments + pageDataSize;
+  }
+
+  if (lastGranule <= 0) return undefined;
+  return Math.round((lastGranule / sampleRate) * 1000);
+}
+
+/**
+ * Parse duration from an ISO base media file format container (MP4 / MOV / M4A / QuickTime / 3GP).
+ * Reads the `mvhd` (movie header) box inside `moov`.
+ * Returns duration in milliseconds, or undefined if the box is not found.
+ */
+export function parseMp4DurationMs(buffer: Buffer): number | undefined {
+  // Find 'moov' box at the top level
+  let offset = 0;
+  let moovStart = -1;
+  let moovEnd = -1;
+  while (offset + 8 <= buffer.length) {
+    const boxSize = buffer.readUInt32BE(offset);
+    if (boxSize < 8) break;
+    if (buffer.toString("ascii", offset + 4, offset + 8) === "moov") {
+      moovStart = offset;
+      moovEnd = Math.min(offset + boxSize, buffer.length);
+      break;
+    }
+    offset += boxSize;
+  }
+  if (moovStart < 0) return undefined;
+
+  // Find 'mvhd' inside 'moov'
+  let inner = moovStart + 8;
+  while (inner + 8 <= moovEnd) {
+    const boxSize = buffer.readUInt32BE(inner);
+    if (boxSize < 8) break;
+    if (buffer.toString("ascii", inner + 4, inner + 8) === "mvhd") {
+      const version = buffer.readUInt8(inner + 8);
+      if (version === 0) {
+        // creation(4) + modification(4) + timescale(4) + duration(4)
+        if (inner + 28 > buffer.length) return undefined;
+        const timeScale = buffer.readUInt32BE(inner + 20);
+        const duration = buffer.readUInt32BE(inner + 24);
+        if (timeScale === 0) return undefined;
+        return Math.round((duration / timeScale) * 1000);
+      } else if (version === 1) {
+        // creation(8) + modification(8) + timescale(4) + duration(8)
+        if (inner + 40 > buffer.length) return undefined;
+        const timeScale = buffer.readUInt32BE(inner + 28);
+        const durationHi = buffer.readUInt32BE(inner + 32);
+        const durationLo = buffer.readUInt32BE(inner + 36);
+        const duration = durationHi * 0x100000000 + durationLo;
+        if (timeScale === 0) return undefined;
+        return Math.round((duration / timeScale) * 1000);
+      }
+      return undefined;
+    }
+    inner += boxSize;
+  }
+  return undefined;
+}
+
+/**
+ * Parse duration from a WAV (RIFF PCM) file.
+ * Computes duration from the `data` chunk size and the byte rate in the `fmt ` chunk.
+ * Returns duration in milliseconds, or undefined if not WAV or parsing fails.
+ */
+export function parseWavDurationMs(buffer: Buffer): number | undefined {
+  if (buffer.length < 44) return undefined;
+  if (buffer.toString("ascii", 0, 4) !== "RIFF") return undefined;
+  if (buffer.toString("ascii", 8, 12) !== "WAVE") return undefined;
+
+  let offset = 12;
+  let byteRate = 0;
+  let dataSize = 0;
+
+  while (offset + 8 <= buffer.length) {
+    const chunkId = buffer.toString("ascii", offset, offset + 4);
+    const chunkSize = buffer.readUInt32LE(offset + 4);
+    if (chunkId === "fmt ") {
+      // fmt chunk layout (from chunk start):
+      //   +0  chunk id "fmt " (4)
+      //   +4  chunk size (4)
+      //   +8  audio format (2)
+      //   +10 num channels (2)
+      //   +12 sample rate (4)
+      //   +16 byte rate (4)  ← what we need
+      if (offset + 20 > buffer.length) return undefined;
+      byteRate = buffer.readUInt32LE(offset + 16);
+    } else if (chunkId === "data") {
+      dataSize = chunkSize;
+      break;
+    }
+    // Advance to next chunk; RIFF chunks are aligned to even byte boundaries
+    offset += 8 + chunkSize + (chunkSize % 2);
+  }
+
+  if (byteRate === 0 || dataSize === 0) return undefined;
+  return Math.round((dataSize / byteRate) * 1000);
+}
+
+/**
+ * Parse duration from a media buffer for Feishu upload.
+ *
+ * Routes to the appropriate parser based on Feishu's file type:
+ *   - "mp4"  → MP4/MOV/QuickTime container parser
+ *   - "opus" → OGG parser, then MP4 container (covers M4A), then WAV
+ *
+ * Returns duration in milliseconds, or undefined if not determinable.
+ */
+export function parseFeishuMediaDurationMs(
+  buffer: Buffer,
+  fileType: "opus" | "mp4",
+): number | undefined {
+  if (fileType === "mp4") {
+    return parseMp4DurationMs(buffer);
+  }
+  // fileType === "opus": try each container format in likelihood order
+  return parseOggDurationMs(buffer) ?? parseMp4DurationMs(buffer) ?? parseWavDurationMs(buffer);
+}

package/src/media.ts

@@ -3,6 +3,7 @@ import { createFeishuClient } from "./client.js";
 import { resolveFeishuAccount } from "./accounts.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
+import { parseFeishuMediaDurationMs } from "./media-duration.js";
 import fs from "fs";
 import path from "path";
 import os from "os";
@@ -236,6 +237,7 @@ export async function uploadImageFeishu(params: {
   return { imageKey };
 }
 
+
 /**
  * Upload a file to Feishu and get a file_key for sending.
  * Max file size: 30MB
@@ -356,10 +358,12 @@ export async function sendFileFeishu(params: {
   fileKey: string;
   /** Use "audio" for audio, "media" for video, "file" for documents */
   msgType?: "file" | "audio" | "media";
+  /** Optional cover image key for video (msg_type "media") messages */
+  imageKey?: string;
   replyToMessageId?: string;
   accountId?: string;
 }): Promise<SendMediaResult> {
-  const { cfg, to, fileKey, replyToMessageId, accountId } = params;
+  const { cfg, to, fileKey, imageKey, replyToMessageId, accountId } = params;
   const msgType = params.msgType ?? "file";
   const account = resolveFeishuAccount({ cfg, accountId });
   if (!account.configured) {
@@ -373,7 +377,10 @@ export async function sendFileFeishu(params: {
   }
 
   const receiveIdType = resolveReceiveIdType(receiveId);
-  const content = JSON.stringify({ file_key: fileKey });
+  const content = JSON.stringify({
+    file_key: fileKey,
+    ...(imageKey && { image_key: imageKey }),
+  });
 
   if (replyToMessageId) {
     const response = await client.im.message.reply({
@@ -421,12 +428,27 @@ export function detectFileType(
 ): "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream" {
   const ext = path.extname(fileName).toLowerCase();
   switch (ext) {
+    // Audio formats → Feishu "opus" category
     case ".opus":
     case ".ogg":
+    case ".mp3":
+    case ".m4a":
+    case ".aac":
+    case ".wav":
+    case ".flac":
+    case ".wma":
+    case ".amr":
       return "opus";
+    // Video formats → Feishu "mp4" category
     case ".mp4":
     case ".mov":
     case ".avi":
+    case ".mkv":
+    case ".webm":
+    case ".flv":
+    case ".wmv":
+    case ".m4v":
+    case ".3gp":
       return "mp4";
     case ".pdf":
       return "pdf";
@@ -444,6 +466,7 @@ export function detectFileType(
   }
 }
 
+
 /**
  * Upload and send media (image or file) from URL, local path, or buffer
  */
@@ -454,9 +477,10 @@ export async function sendMediaFeishu(params: {
   mediaBuffer?: Buffer;
   fileName?: string;
   replyToMessageId?: string;
+  mediaLocalRoots?: readonly string[];
   accountId?: string;
 }): Promise<SendMediaResult> {
-  const { cfg, to, mediaUrl, mediaBuffer, fileName, replyToMessageId, accountId } = params;
+  const { cfg, to, mediaUrl, mediaBuffer, fileName, replyToMessageId, mediaLocalRoots, accountId } = params;
   const account = resolveFeishuAccount({ cfg, accountId });
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
@@ -465,37 +489,25 @@ export async function sendMediaFeishu(params: {
 
   let buffer: Buffer;
   let name: string;
+  let contentType: string | undefined;
 
   if (mediaBuffer) {
     buffer = mediaBuffer;
     name = fileName ?? "file";
   } else if (mediaUrl) {
-    const mediaLocalRoots = (account.config?.mediaLocalRoots ?? [])
+    const configLocalRoots = (account.config?.mediaLocalRoots ?? [])
       .map((root) => root.trim())
       .filter((root) => root.length > 0);
-    const loaded = await (async () => {
-      try {
-        return await getFeishuRuntime().media.loadWebMedia(mediaUrl, {
-          maxBytes: mediaMaxBytes,
-          optimizeImages: false,
-        });
-      } catch (err) {
-        const shouldRetryWithCustomRoots =
-          mediaLocalRoots.length > 0 &&
-          err instanceof Error &&
-          err.message.includes("Local media path is not under an allowed directory");
-        if (!shouldRetryWithCustomRoots) {
-          throw err;
-        }
-        return await getFeishuRuntime().media.loadWebMedia(mediaUrl, {
-          maxBytes: mediaMaxBytes,
-          optimizeImages: false,
-          localRoots: mediaLocalRoots,
-        });
-      }
-    })();
+    // Merge context-provided roots (includes agent workspace) with config roots.
+    const mergedLocalRoots = [...(mediaLocalRoots ?? []), ...configLocalRoots];
+    const loaded = await getFeishuRuntime().media.loadWebMedia(mediaUrl, {
+      maxBytes: mediaMaxBytes,
+      optimizeImages: false,
+      ...(mergedLocalRoots.length > 0 ? { localRoots: mergedLocalRoots } : {}),
+    });
     buffer = loaded.buffer;
     name = fileName ?? loaded.fileName ?? "file";
+    contentType = loaded.contentType;
   } else {
     throw new Error("Either mediaUrl or mediaBuffer must be provided");
   }
@@ -508,16 +520,27 @@ export async function sendMediaFeishu(params: {
     const { imageKey } = await uploadImageFeishu({ cfg, image: buffer, accountId });
     return sendImageFeishu({ cfg, to, imageKey, replyToMessageId, accountId });
   } else {
-    const fileType = detectFileType(name);
+    // Determine file type from extension; fall back to MIME type for files without
+    // a recognized extension (e.g. URLs with no filename, or buffers without fileName).
+    let fileType = detectFileType(name);
+    if (fileType === "stream" && contentType) {
+      if (contentType.startsWith("video/")) fileType = "mp4";
+      else if (contentType.startsWith("audio/")) fileType = "opus";
+    }
+    const msgType = fileType === "opus" ? "audio" : fileType === "mp4" ? "media" : "file";
+    const duration =
+      fileType === "opus" || fileType === "mp4"
+        ? parseFeishuMediaDurationMs(buffer, fileType)
+        : undefined;
     const { fileKey } = await uploadFileFeishu({
       cfg,
       file: buffer,
       fileName: name,
       fileType,
+      duration,
       accountId,
     });
     // Feishu requires msg_type "audio" for audio, "media" for video, "file" for documents
-    const msgType = fileType === "opus" ? "audio" : fileType === "mp4" ? "media" : "file";
     return sendFileFeishu({
       cfg,
       to,

package/src/mention.ts

@@ -45,7 +45,7 @@ export function isMentionForwardRequest(
   const mentions = event.message.mentions ?? [];
   if (mentions.length === 0) return false;
 
-  const isDirectMessage = event.message.chat_type === "p2p";
+  const isDirectMessage = event.message.chat_type !== "group";
   const hasOtherMention = mentions.some((m) => m.id.open_id !== botOpenId);
 
   if (isDirectMessage) {

package/src/monitor.ts

@@ -37,6 +37,26 @@ async function fetchBotOpenId(
   }
 }
 
+/**
+ * Per-chat serial queue that ensures messages from the same chat are processed
+ * in arrival order while allowing different chats to run concurrently.
+ * Uses .then(task, task) so a failure in one message never blocks the next.
+ */
+function createChatQueue() {
+  const queues = new Map<string, Promise<void>>();
+  return (chatId: string, task: () => Promise<void>): Promise<void> => {
+    const prev = queues.get(chatId) ?? Promise.resolve();
+    const next = prev.then(task, task);
+    queues.set(chatId, next);
+    void next.finally(() => {
+      if (queues.get(chatId) === next) {
+        queues.delete(chatId);
+      }
+    });
+    return next;
+  };
+}
+
 /**
  * Register common event handlers on an EventDispatcher.
  * When fireAndForget is true (webhook mode), message handling is not awaited
@@ -55,19 +75,23 @@ function registerEventHandlers(
   const { cfg, accountId, runtime, chatHistories, fireAndForget } = context;
   const log = runtime?.log ?? console.log;
   const error = runtime?.error ?? console.error;
+  const enqueue = createChatQueue();
 
   eventDispatcher.register({
     "im.message.receive_v1": async (data) => {
       try {
         const event = data as unknown as FeishuMessageEvent;
-        const promise = handleFeishuMessage({
-          cfg,
-          event,
-          botOpenId: botOpenIds.get(accountId),
-          runtime,
-          chatHistories,
-          accountId,
-        });
+        const chatId = event.message.chat_id?.trim() || "unknown";
+        const task = () =>
+          handleFeishuMessage({
+            cfg,
+            event,
+            botOpenId: botOpenIds.get(accountId),
+            runtime,
+            chatHistories,
+            accountId,
+          });
+        const promise = enqueue(chatId, task);
         if (fireAndForget) {
           promise.catch((err) => {
             error(`feishu[${accountId}]: error handling message: ${String(err)}`);

package/src/outbound.ts

@@ -12,7 +12,7 @@ export const feishuOutbound: ChannelOutboundAdapter = {
     const result = await sendMessageFeishu({ cfg, to, text, accountId });
     return { channel: "feishu", ...result };
   },
-  sendMedia: async ({ cfg, to, text, mediaUrl, accountId }) => {
+  sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId }) => {
     // Send text first if provided
     if (text?.trim()) {
       await sendMessageFeishu({ cfg, to, text, accountId });
@@ -21,7 +21,7 @@ export const feishuOutbound: ChannelOutboundAdapter = {
     // Upload and send media if URL provided
     if (mediaUrl) {
       try {
-        const result = await sendMediaFeishu({ cfg, to, mediaUrl, accountId });
+        const result = await sendMediaFeishu({ cfg, to, mediaUrl, mediaLocalRoots, accountId });
         return { channel: "feishu", ...result };
       } catch (err) {
         // Log the error for debugging

package/src/perm-tools/actions.ts

@@ -33,6 +33,13 @@ type MemberType =
   | "wikispaceid";
 type PermType = "view" | "edit" | "full_access";
 
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} is required`);
+  }
+  return value;
+}
+
 async function listMembers(client: PermClient, token: string, type: string) {
   const res = await runPermApiCall("drive.permissionMember.list", () =>
     client.drive.permissionMember.list({
@@ -100,11 +107,28 @@ async function removeMember(
 export async function runPermAction(client: PermClient, params: FeishuPermParams) {
   switch (params.action) {
     case "list":
-      return listMembers(client, params.token, params.type);
+      return listMembers(
+        client,
+        requireString(params.token, "token"),
+        requireString(params.type, "type"),
+      );
     case "add":
-      return addMember(client, params.token, params.type, params.member_type, params.member_id, params.perm);
+      return addMember(
+        client,
+        requireString(params.token, "token"),
+        requireString(params.type, "type"),
+        requireString(params.member_type, "member_type"),
+        requireString(params.member_id, "member_id"),
+        requireString(params.perm, "perm"),
+      );
     case "remove":
-      return removeMember(client, params.token, params.type, params.member_type, params.member_id);
+      return removeMember(
+        client,
+        requireString(params.token, "token"),
+        requireString(params.type, "type"),
+        requireString(params.member_type, "member_type"),
+        requireString(params.member_id, "member_id"),
+      );
     default:
       return { error: `Unknown action: ${(params as any).action}` };
   }

package/src/perm-tools/schemas.ts

@@ -1,52 +1,46 @@
 import { Type, type Static } from "@sinclair/typebox";
 
-const TokenType = Type.Union([
-  Type.Literal("doc"),
-  Type.Literal("docx"),
-  Type.Literal("sheet"),
-  Type.Literal("bitable"),
-  Type.Literal("folder"),
-  Type.Literal("file"),
-  Type.Literal("wiki"),
-  Type.Literal("mindnote"),
-]);
+function stringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string; default?: T[number] } = {},
+) {
+  return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
 
-const MemberType = Type.Union([
-  Type.Literal("email"),
-  Type.Literal("openid"),
-  Type.Literal("userid"),
-  Type.Literal("unionid"),
-  Type.Literal("openchat"),
-  Type.Literal("opendepartmentid"),
-]);
+const TOKEN_TYPE_VALUES = [
+  "doc",
+  "docx",
+  "sheet",
+  "bitable",
+  "folder",
+  "file",
+  "wiki",
+  "mindnote",
+] as const;
 
-const Permission = Type.Union([
-  Type.Literal("view"),
-  Type.Literal("edit"),
-  Type.Literal("full_access"),
-]);
+const MEMBER_TYPE_VALUES = [
+  "email",
+  "openid",
+  "userid",
+  "unionid",
+  "openchat",
+  "opendepartmentid",
+] as const;
 
-export const FeishuPermSchema = Type.Union([
-  Type.Object({
-    action: Type.Literal("list"),
-    token: Type.String({ description: "File token" }),
-    type: TokenType,
-  }),
-  Type.Object({
-    action: Type.Literal("add"),
-    token: Type.String({ description: "File token" }),
-    type: TokenType,
-    member_type: MemberType,
-    member_id: Type.String({ description: "Member ID (email, open_id, user_id, etc.)" }),
-    perm: Permission,
-  }),
-  Type.Object({
-    action: Type.Literal("remove"),
-    token: Type.String({ description: "File token" }),
-    type: TokenType,
-    member_type: MemberType,
-    member_id: Type.String({ description: "Member ID to remove" }),
-  }),
-]);
+const PERMISSION_VALUES = ["view", "edit", "full_access"] as const;
+const PERM_ACTION_VALUES = ["list", "add", "remove"] as const;
+
+export const FeishuPermSchema = Type.Object({
+  action: stringEnum(PERM_ACTION_VALUES, { description: "Permission action" }),
+  token: Type.Optional(Type.String({ description: "File token" })),
+  type: Type.Optional(stringEnum(TOKEN_TYPE_VALUES, { description: "File token type" })),
+  member_type: Type.Optional(
+    stringEnum(MEMBER_TYPE_VALUES, {
+      description: "Member ID type (email/openid/userid/unionid/openchat/opendepartmentid)",
+    }),
+  ),
+  member_id: Type.Optional(Type.String({ description: "Member ID" })),
+  perm: Type.Optional(stringEnum(PERMISSION_VALUES, { description: "Permission level" })),
+});
 
 export type FeishuPermParams = Static<typeof FeishuPermSchema>;

package/src/policy.ts

@@ -82,15 +82,19 @@ export function resolveFeishuReplyPolicy(params: {
   isDirectMessage: boolean;
   globalConfig?: FeishuConfig;
   groupConfig?: FeishuGroupConfig;
-}): { requireMention: boolean } {
+}): { requireMention: boolean; allowMentionlessInMultiBotGroup: boolean } {
   if (params.isDirectMessage) {
-    return { requireMention: false };
+    return { requireMention: false, allowMentionlessInMultiBotGroup: false };
   }
 
   const requireMention =
     params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true;
+  const allowMentionlessInMultiBotGroup =
+    params.groupConfig?.allowMentionlessInMultiBotGroup ??
+    params.globalConfig?.allowMentionlessInMultiBotGroup ??
+    false;
 
-  return { requireMention };
+  return { requireMention, allowMentionlessInMultiBotGroup };
 }
 
 export function resolveFeishuGroupCommandMentionBypass(params: {