@m1heng-clawd/feishu 0.1.12 → 0.1.14

package/README.md

@@ -27,14 +27,33 @@ openclaw plugins install @m1heng-clawd/feishu
 > [!IMPORTANT]
 > **Windows Troubleshooting (`spawn npm ENOENT`)**
 >
-> If `openclaw plugins install` fails, install manually:
+> If `openclaw plugins install` fails, install manually with the latest tarball:
 >
 > ```bash
-> # 1. Download the package
-> curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
+> # Option A (recommended): download latest package tarball
+> npm pack @m1heng-clawd/feishu
+> openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz
+> ```
+>
+> ```bash
+> # Option B (keep curl flow): resolve latest tarball URL, then download/install
+> TARBALL_URL="$(npm view @m1heng-clawd/feishu dist.tarball)"
+> curl -L -o feishu-latest.tgz "$TARBALL_URL"
+> openclaw plugins install ./feishu-latest.tgz
+> ```
 >
-> # 2. Install from local file
-> openclaw plugins install ./feishu-0.1.3.tgz
+> ```powershell
+> # Windows PowerShell (Option B)
+> $tarball = npm view @m1heng-clawd/feishu dist.tarball
+> curl.exe -L $tarball -o feishu-latest.tgz
+> openclaw plugins install .\feishu-latest.tgz
+> ```
+>
+> ```bash
+> # Option C (no npm command): use URL template with latest version from npm Versions tab
+> # https://www.npmjs.com/package/@m1heng-clawd/feishu?activeTab=versions
+> curl -L -o feishu-latest.tgz https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-<version>.tgz
+> openclaw plugins install ./feishu-latest.tgz
 > ```
 
 ### Upgrade
@@ -43,6 +62,12 @@ openclaw plugins install @m1heng-clawd/feishu
 openclaw plugins update feishu
 ```
 
+Check installed version:
+
+```bash
+openclaw plugins list | rg -i feishu
+```
+
 ### Configuration
 
 1. Create a self-built app on [Feishu Open Platform](https://open.feishu.cn)
@@ -478,14 +503,33 @@ openclaw plugins install @m1heng-clawd/feishu
 > [!IMPORTANT]
 > **Windows 排错（`spawn npm ENOENT`）**
 >
-> 如果 `openclaw plugins install` 失败，可以手动安装：
+> 如果 `openclaw plugins install` 失败，可通过最新 tarball 手动安装：
 >
 > ```bash
-> # 1. 下载插件包
-> curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
+> # 方案 A（推荐）：下载最新插件 tarball
+> npm pack @m1heng-clawd/feishu
+> openclaw plugins install ./m1heng-clawd-feishu-<version>.tgz
+> ```
+>
+> ```bash
+> # 方案 B（保留 curl 路径）：先解析最新 tarball 地址，再下载安装
+> TARBALL_URL="$(npm view @m1heng-clawd/feishu dist.tarball)"
+> curl -L -o feishu-latest.tgz "$TARBALL_URL"
+> openclaw plugins install ./feishu-latest.tgz
+> ```
 >
-> # 2. 从本地安装
-> openclaw plugins install ./feishu-0.1.3.tgz
+> ```powershell
+> # Windows PowerShell（方案 B）
+> $tarball = npm view @m1heng-clawd/feishu dist.tarball
+> curl.exe -L $tarball -o feishu-latest.tgz
+> openclaw plugins install .\feishu-latest.tgz
+> ```
+>
+> ```bash
+> # 方案 C（无 npm 命令）：先在 npm Versions 页查到最新版本号，再套用 URL 模板
+> # https://www.npmjs.com/package/@m1heng-clawd/feishu?activeTab=versions
+> curl -L -o feishu-latest.tgz https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-<version>.tgz
+> openclaw plugins install ./feishu-latest.tgz
 > ```
 
 ### 升级
@@ -494,6 +538,12 @@ openclaw plugins install @m1heng-clawd/feishu
 openclaw plugins update feishu
 ```
 
+查看已安装版本：
+
+```bash
+openclaw plugins list | rg -i feishu
+```
+
 ### 配置
 
 1. 在 [飞书开放平台](https://open.feishu.cn) 创建自建应用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "scripts": {

package/src/bot.ts

@@ -99,6 +99,137 @@ type SenderNameResult = {
   permissionError?: PermissionError;
 };
 
+type FeishuPairingApiMode = "legacy" | "scoped";
+let detectedFeishuPairingApiMode: FeishuPairingApiMode | null = null;
+
+async function resolveFeishuPairingApiMode(params: {
+  readAllowFromStore: (...args: any[]) => Promise<Array<string | number>>;
+}): Promise<FeishuPairingApiMode> {
+  if (detectedFeishuPairingApiMode) return detectedFeishuPairingApiMode;
+
+  let channelObserved = false;
+  const probe = new Proxy<Record<PropertyKey, unknown>>(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === "channel") {
+          channelObserved = true;
+          return "__feishu_pairing_probe__";
+        }
+        if (prop === "accountId") return "__feishu_pairing_probe__";
+        if (prop === "env") return undefined;
+        if (prop === Symbol.toPrimitive) return () => "__feishu_pairing_probe__";
+        if (prop === "toString") return () => "__feishu_pairing_probe__";
+        return undefined;
+      },
+      has(_target, prop) {
+        if (prop === "channel") {
+          channelObserved = true;
+          return true;
+        }
+        return false;
+      },
+    },
+  );
+
+  try {
+    // Probe once to detect whether runtime reads object-style params (scoped API)
+    // or positional params (legacy API).
+    await params.readAllowFromStore(probe as any, undefined, "__feishu_pairing_probe__");
+  } catch {
+    // Ignore probe errors; fallback below still keeps behavior safe.
+  }
+
+  detectedFeishuPairingApiMode = channelObserved ? "scoped" : "legacy";
+  return detectedFeishuPairingApiMode;
+}
+
+async function readFeishuPairingAllowFrom(params: {
+  core: ReturnType<typeof getFeishuRuntime>;
+  accountId: string;
+}): Promise<Array<string | number>> {
+  const pairing = params.core.channel.pairing as {
+    readAllowFromStore: (...args: any[]) => Promise<Array<string | number>>;
+  };
+  const pairingMode = await resolveFeishuPairingApiMode({
+    readAllowFromStore: pairing.readAllowFromStore,
+  });
+
+  if (pairingMode === "scoped") {
+    try {
+      return await pairing.readAllowFromStore({
+        channel: "feishu",
+        accountId: params.accountId,
+      });
+    } catch {
+      // Compatibility fallback for older OpenClaw implementations.
+      return await pairing.readAllowFromStore("feishu", undefined, params.accountId);
+    }
+  }
+
+  try {
+    // OpenClaw <= 2026.2.19 signature: readAllowFromStore(channel, env?, accountId?)
+    return await pairing.readAllowFromStore("feishu", undefined, params.accountId);
+  } catch {
+    // Compatibility fallback for newer OpenClaw implementations.
+    return await pairing.readAllowFromStore({
+      channel: "feishu",
+      accountId: params.accountId,
+    });
+  }
+}
+
+async function upsertFeishuPairingRequest(params: {
+  core: ReturnType<typeof getFeishuRuntime>;
+  accountId: string;
+  senderId: string;
+  senderName?: string;
+}): Promise<{ code: string; created: boolean }> {
+  const pairing = params.core.channel.pairing as {
+    upsertPairingRequest: (...args: any[]) => Promise<{ code: string; created: boolean }>;
+  };
+  const meta = params.senderName ? { name: params.senderName } : undefined;
+  const pairingMode = await resolveFeishuPairingApiMode({
+    readAllowFromStore: params.core.channel.pairing.readAllowFromStore as (...args: any[]) => Promise<
+      Array<string | number>
+    >,
+  });
+
+  if (pairingMode === "scoped") {
+    try {
+      return await pairing.upsertPairingRequest({
+        channel: "feishu",
+        id: params.senderId,
+        accountId: params.accountId,
+        meta,
+      });
+    } catch {
+      // Compatibility fallback for older OpenClaw implementations.
+      return await pairing.upsertPairingRequest({
+        channel: "feishu",
+        id: params.senderId,
+        meta,
+      });
+    }
+  }
+
+  try {
+    return await pairing.upsertPairingRequest({
+      channel: "feishu",
+      id: params.senderId,
+      meta,
+    });
+  } catch {
+    // Compatibility fallback for newer OpenClaw implementations.
+    return await pairing.upsertPairingRequest({
+      channel: "feishu",
+      id: params.senderId,
+      accountId: params.accountId,
+      meta,
+    });
+  }
+}
+
 async function resolveFeishuSenderName(params: {
   account: ResolvedFeishuAccount;
   senderOpenId: string;
@@ -226,20 +357,48 @@ export type FeishuBotAddedEvent = {
 function parseMessageContent(content: string, messageType: string): string {
   try {
     const parsed = JSON.parse(content);
-    if (messageType === "text") {
+    const normalizedMessageType = normalizeFeishuInboundMessageType(messageType);
+    if (normalizedMessageType === "text") {
       return parsed.text || "";
     }
-    if (messageType === "post") {
+    if (normalizedMessageType === "post") {
       // Extract text content from rich text post
       const { textContent } = parsePostContent(content);
       return textContent;
     }
+    if (["image", "file", "audio", "video", "sticker"].includes(normalizedMessageType)) {
+      return inferPlaceholder(normalizedMessageType);
+    }
     return content;
   } catch {
     return content;
   }
 }
 
+/**
+ * Feishu may use "media" for inbound video messages.
+ * Normalize to "video" so downstream media handling is consistent.
+ */
+export function normalizeFeishuInboundMessageType(messageType: string): string {
+  return messageType === "media" ? "video" : messageType;
+}
+
+/**
+ * Select the correct resource key for messageResource download.
+ * - image message: prefer image_key
+ * - other media (video/audio/file/sticker): prefer file_key
+ */
+export function selectFeishuMessageResourceKey(
+  messageType: string,
+  keys: { imageKey?: string; fileKey?: string },
+): string | undefined {
+  const normalized = normalizeFeishuInboundMessageType(messageType);
+  if (normalized === "image") {
+    return keys.imageKey ?? keys.fileKey;
+  }
+  return keys.fileKey ?? keys.imageKey;
+}
+
 function checkBotMentioned(
   event: FeishuMessageEvent,
   botOpenId?: string,
@@ -288,6 +447,7 @@ function parseMediaKeys(
       case "audio":
         return { fileKey: parsed.file_key };
       case "video":
+      case "media":
         // Video has both file_key (video) and image_key (thumbnail)
         return { fileKey: parsed.file_key, imageKey: parsed.image_key };
       case "sticker":
@@ -363,6 +523,7 @@ function inferPlaceholder(messageType: string): string {
     case "audio":
       return "<media:audio>";
     case "video":
+    case "media":
       return "<media:video>";
     case "sticker":
       return "<media:sticker>";
@@ -385,10 +546,11 @@ async function resolveFeishuMediaList(params: {
   accountId?: string;
 }): Promise<FeishuMediaInfo[]> {
   const { cfg, messageId, messageType, content, maxBytes, log, accountId } = params;
+  const normalizedMessageType = normalizeFeishuInboundMessageType(messageType);
 
   // Only process media message types (including post for embedded images)
   const mediaTypes = ["image", "file", "audio", "video", "sticker", "post"];
-  if (!mediaTypes.includes(messageType)) {
+  if (!mediaTypes.includes(normalizedMessageType)) {
     return [];
   }
 
@@ -396,7 +558,7 @@ async function resolveFeishuMediaList(params: {
   const core = getFeishuRuntime();
 
   // Handle post (rich text) messages with embedded images
-  if (messageType === "post") {
+  if (normalizedMessageType === "post") {
     const { imageKeys } = parsePostContent(content);
     if (imageKeys.length === 0) {
       return [];
@@ -443,7 +605,7 @@ async function resolveFeishuMediaList(params: {
   }
 
   // Handle other media types
-  const mediaKeys = parseMediaKeys(content, messageType);
+  const mediaKeys = parseMediaKeys(content, normalizedMessageType);
   if (!mediaKeys.imageKey && !mediaKeys.fileKey) {
     return [];
   }
@@ -455,12 +617,12 @@ async function resolveFeishuMediaList(params: {
 
     // For message media, always use messageResource API
     // The image.get API is only for images uploaded via im/v1/images, not for message attachments
-    const fileKey = mediaKeys.imageKey || mediaKeys.fileKey;
+    const fileKey = selectFeishuMessageResourceKey(normalizedMessageType, mediaKeys);
     if (!fileKey) {
       return [];
     }
 
-    const resourceType = messageType === "image" ? "image" : "file";
+    const resourceType = normalizedMessageType === "image" ? "image" : "file";
     const result = await downloadMessageResourceFeishu({
       cfg,
       messageId,
@@ -489,12 +651,12 @@ async function resolveFeishuMediaList(params: {
     out.push({
       path: saved.path,
       contentType: saved.contentType,
-      placeholder: inferPlaceholder(messageType),
+      placeholder: inferPlaceholder(normalizedMessageType),
     });
 
-    log?.(`feishu: downloaded ${messageType} media, saved to ${saved.path}`);
+    log?.(`feishu: downloaded ${normalizedMessageType} media, saved to ${saved.path}`);
   } catch (err) {
-    log?.(`feishu: failed to download ${messageType} media: ${String(err)}`);
+    log?.(`feishu: failed to download ${normalizedMessageType} media: ${String(err)}`);
   }
 
   return out;
@@ -648,7 +810,10 @@ export async function handleFeishuMessage(params: {
     const hasControlCommand = core.channel.text.hasControlCommand(ctx.content, cfg);
     const storeAllowFrom =
       !isGroup && (dmPolicy !== "open" || shouldComputeCommandAuthorized)
-        ? await core.channel.pairing.readAllowFromStore("feishu").catch(() => [])
+        ? await readFeishuPairingAllowFrom({
+            core,
+            accountId: account.accountId,
+          }).catch(() => [])
         : [];
     const effectiveDmAllowFrom = [...configAllowFrom, ...storeAllowFrom];
     const dmAllowed = resolveFeishuAllowlistMatch({
@@ -659,10 +824,11 @@ export async function handleFeishuMessage(params: {
 
     if (!isGroup && dmPolicy !== "open" && !dmAllowed) {
       if (dmPolicy === "pairing") {
-        const { code, created } = await core.channel.pairing.upsertPairingRequest({
-          channel: "feishu",
-          id: ctx.senderOpenId,
-          meta: { name: ctx.senderName },
+        const { code, created } = await upsertFeishuPairingRequest({
+          core,
+          accountId: account.accountId,
+          senderId: ctx.senderOpenId,
+          senderName: ctx.senderName,
         });
         if (created) {
           log(`feishu[${account.accountId}]: pairing request sender=${ctx.senderOpenId}`);

package/src/channel.ts

@@ -97,6 +97,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
         textChunkLimit: { type: "integer", minimum: 1 },
         chunkMode: { type: "string", enum: ["length", "newline"] },
         mediaMaxMb: { type: "number", minimum: 0 },
+        mediaLocalRoots: { type: "array", items: { type: "string" } },
         renderMode: { type: "string", enum: ["auto", "raw", "card"] },
         accounts: {
           type: "object",
@@ -111,6 +112,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
               verificationToken: { type: "string" },
               domain: { type: "string", enum: ["feishu", "lark"] },
               connectionMode: { type: "string", enum: ["websocket", "webhook"] },
+              mediaLocalRoots: { type: "array", items: { type: "string" } },
               groupCommandMentionBypass: { type: "string", enum: ["never", "single_bot", "always"] },
             },
           },

package/src/config-schema.ts

@@ -148,6 +148,7 @@ export const FeishuAccountConfigSchema = z
     chunkMode: z.enum(["length", "newline"]).optional(),
     blockStreamingCoalesce: BlockStreamingCoalesceSchema,
     mediaMaxMb: z.number().positive().optional(),
+    mediaLocalRoots: z.array(z.string()).optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
     renderMode: RenderModeSchema,
     streaming: StreamingModeSchema,
@@ -185,6 +186,7 @@ export const FeishuConfigSchema = z
     chunkMode: z.enum(["length", "newline"]).optional(),
     blockStreamingCoalesce: BlockStreamingCoalesceSchema,
     mediaMaxMb: z.number().positive().optional(),
+    mediaLocalRoots: z.array(z.string()).optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
     renderMode: RenderModeSchema, // raw = plain text (default), card = interactive card with markdown
     streaming: StreamingModeSchema,

package/src/media.ts

@@ -470,10 +470,30 @@ export async function sendMediaFeishu(params: {
     buffer = mediaBuffer;
     name = fileName ?? "file";
   } else if (mediaUrl) {
-    const loaded = await getFeishuRuntime().media.loadWebMedia(mediaUrl, {
-      maxBytes: mediaMaxBytes,
-      optimizeImages: false,
-    });
+    const mediaLocalRoots = (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,
+        });
+      }
+    })();
     buffer = loaded.buffer;
     name = fileName ?? loaded.fileName ?? "file";
   } else {

package/src/reply-dispatcher.ts

@@ -103,7 +103,7 @@ export function createFeishuReplyDispatcher(params: CreateFeishuReplyDispatcherP
         params.runtime.log?.(`feishu[${account.accountId}] ${message}`),
       );
       try {
-        await streaming.start(chatId, resolveReceiveIdType(chatId));
+        await streaming.start(chatId, resolveReceiveIdType(chatId), replyToMessageId);
       } catch (error) {
         params.runtime.error?.(`feishu: streaming start failed: ${String(error)}`);
         streaming = null;

package/src/streaming-card.ts

@@ -72,6 +72,7 @@ export class FeishuStreamingSession {
   async start(
     receiveId: string,
     receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
+    replyToMessageId?: string,
   ): Promise<void> {
     if (this.state) {
       return;
@@ -108,14 +109,16 @@ export class FeishuStreamingSession {
     }
     const cardId = createData.data.card_id;
 
-    const sendRes = await this.client.im.message.create({
-      params: { receive_id_type: receiveIdType },
-      data: {
-        receive_id: receiveId,
-        msg_type: "interactive",
-        content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
-      },
-    });
+    const cardContent = JSON.stringify({ type: "card", data: { card_id: cardId } });
+    const sendRes = replyToMessageId
+      ? await this.client.im.message.reply({
+          path: { message_id: replyToMessageId },
+          data: { msg_type: "interactive", content: cardContent },
+        })
+      : await this.client.im.message.create({
+          params: { receive_id_type: receiveIdType },
+          data: { receive_id: receiveId, msg_type: "interactive", content: cardContent },
+        });
     if (sendRes.code !== 0 || !sendRes.data?.message_id) {
       throw new Error(`Send card failed: ${sendRes.msg}`);
     }

package/src/task-tools/actions.ts

@@ -553,13 +553,15 @@ export async function uploadTaskAttachment(
   let tempCleanup: (() => Promise<void>) | undefined;
   let filePath: string;
 
-  if ("file_path" in params) {
+  if (params.file_path) {
     filePath = params.file_path;
     await ensureUploadableLocalFile(filePath, maxBytes);
-  } else {
+  } else if (params.file_url) {
     const download = await downloadToTempFile(params.file_url, params.filename, maxBytes);
     filePath = download.tempPath;
     tempCleanup = download.cleanup;
+  } else {
+    throw new Error("Either file_path or file_url is required");
   }
 
   try {

package/src/task-tools/schemas.ts

@@ -156,18 +156,13 @@ export type DeleteTaskCommentParams = {
   comment_id: TaskCommentDeletePayload["path"]["comment_id"];
 };
 
-export type UploadTaskAttachmentParams =
-  | {
-      task_guid: string;
-      file_path: string;
-      user_id_type?: NonNullable<TaskAttachmentUploadPayload["params"]>["user_id_type"];
-    }
-  | {
-      task_guid: string;
-      file_url: string;
-      filename?: string;
-      user_id_type?: NonNullable<TaskAttachmentUploadPayload["params"]>["user_id_type"];
-    };
+export type UploadTaskAttachmentParams = {
+  task_guid: string;
+  file_path?: string;
+  file_url?: string;
+  filename?: string;
+  user_id_type?: NonNullable<TaskAttachmentUploadPayload["params"]>["user_id_type"];
+};
 
 export type ListTaskAttachmentsParams = {
   task_guid: NonNullable<TaskAttachmentListPayload["params"]>["resource_id"];
@@ -300,12 +295,10 @@ export const CreateTaskSchema = Type.Object({
   ),
 });
 
-export const CreateSubtaskSchema = Type.Intersect([
-  Type.Object({
-    task_guid: Type.String({ description: "Parent task GUID" }),
-  }),
-  CreateTaskSchema,
-]);
+export const CreateSubtaskSchema = Type.Object({
+  task_guid: Type.String({ description: "Parent task GUID" }),
+  ...CreateTaskSchema.properties,
+});
 
 export const DeleteTaskSchema = Type.Object({
   task_guid: Type.String({ description: "Task GUID to delete" }),
@@ -521,23 +514,19 @@ export const RemoveTasklistMembersSchema = Type.Object({
   ),
 });
 
-export const UploadTaskAttachmentSchema = Type.Union([
-  Type.Object({
-    task_guid: Type.String({ description: "Task GUID to upload attachment to" }),
-    file_path: Type.String({ description: "Local file path on the OpenClaw host" }),
-    user_id_type: Type.Optional(
-      Type.String({ description: "User ID type for returned uploader" }),
-    ),
-  }),
-  Type.Object({
-    task_guid: Type.String({ description: "Task GUID to upload attachment to" }),
-    file_url: Type.String({ description: "Remote file URL to download and upload" }),
-    filename: Type.Optional(Type.String({ description: "Override filename for uploaded attachment" })),
-    user_id_type: Type.Optional(
-      Type.String({ description: "User ID type for returned uploader" }),
-    ),
-  }),
-]);
+export const UploadTaskAttachmentSchema = Type.Object({
+  task_guid: Type.String({ description: "Task GUID to upload attachment to" }),
+  file_path: Type.Optional(
+    Type.String({ description: "Local file path on the OpenClaw host (provide either file_path or file_url)" }),
+  ),
+  file_url: Type.Optional(
+    Type.String({ description: "Remote file URL to download and upload (provide either file_path or file_url)" }),
+  ),
+  filename: Type.Optional(Type.String({ description: "Override filename for uploaded attachment (only with file_url)" })),
+  user_id_type: Type.Optional(
+    Type.String({ description: "User ID type for returned uploader" }),
+  ),
+});
 
 export const ListTaskAttachmentsSchema = Type.Object({
   task_guid: Type.String({ description: "Task GUID to list attachments for" }),