@m1heng-clawd/feishu 0.1.15 → 0.1.17

package/README.md

@@ -16,6 +16,22 @@ Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/o
 
 ---
 
+## Sponsor
+
+![YouYun Zhisuan](./assets/sponsor-youyunzhisuan.png)
+
+Thanks to our sponsors for supporting the project.
+
+If you need an API key platform whose models can be used as an OpenClaw provider and work with Kimi, MiniMax, Claude Code, Codex, or direct API usage, YouYun Zhisuan is worth considering:
+
+> UCloud's YouYun Zhisuan is an AI cloud platform that provides stable and comprehensive domestic and international model APIs through a single API key. Its high-value Coding Plan offers both monthly and pay-as-you-go options, typically at 20% to 50% of official pricing. It supports Claude Code, Codex, and direct API integrations, as well as enterprise-grade high concurrency, 24/7 technical support, and self-service invoicing. Register through [this link](https://passport.compshare.cn/register?referral_code=5oWQU772rtSCeExpcLFxwy&ytag=GPU_YY_YX_git_clawdbot-feishu) to receive a free RMB 5 platform trial credit.
+
+感谢赞助方对本项目的支持。
+
+如果你需要一个可作为 OpenClaw 模型 provider，并适用于 Kimi、MiniMax、Claude Code、Codex 或直接 API 调用的稳定 API Key 平台，可以了解一下优云智算：
+
+> 优云智算是UCloud旗下AI云平台，提供稳定、全面的国内外模型API，仅一个key即可调用。主打包月、按量的高性价比 Coding Plan 套餐，基于官方2~5折优惠。支持接入 Claude Code、Codex 及 API 调用。支持企业高并发、7*24技术支持、自助开票。通过[此链接](https://passport.compshare.cn/register?referral_code=5oWQU772rtSCeExpcLFxwy&ytag=GPU_YY_YX_git_clawdbot-feishu)注册的用户，可得免费5元平台体验金！
+
 ## English
 
 ### Installation
@@ -113,6 +129,9 @@ openclaw plugins list | rg -i feishu
 | `task:attachment:read` | `feishu_task_attachment_list`, `feishu_task_attachment_get` | List/get task attachments |
 | `im:chat.announcement:read` | `feishu_chat` | Read group announcement |
 | `im:chat:readonly` | `feishu_chat` | Get chat info, check bot membership |
+| `im:message` or `im:message:readonly` | `feishu_message` | Read single/DM messages |
+| `im:message.group_at_msg:readonly` | `feishu_message` | Read all messages in group chats |
+| `im:message.reactions:read` | `feishu_reaction` | List reactions on messages |
 
 **Read-write** (optional, for create/edit/delete operations):
 
@@ -131,6 +150,7 @@ openclaw plugins list | rg -i feishu
 | `im:chat.announcement` | `feishu_chat` | Write/update group announcement |
 | `im:chat` | `feishu_chat` | Create and delete group chats |
 | `im:chat.members` | `feishu_chat` | Add members to group chats |
+| `im:message.reactions:write_only` | `feishu_reaction` | Add and remove reactions |
 
 > Task scope names may vary slightly in Feishu console UI. If needed, search for Task / Tasklist / Comment / Attachment-related permissions and grant read/write accordingly.
 
@@ -479,6 +499,8 @@ session:
 - **Task tools**: Create, get details, update, and delete tasks via Feishu Task v2 API
 - **Chat tools**: Read and write group announcements, create group chats, add members, check bot membership, delete chats (`feishu_chat`)
 - **Urgent notification tools**: Send buzz/urgent notifications (app, SMS, voice call) via `feishu_urgent`
+- **Message tools**: Read single messages or list recent chat history with time range and pagination (`feishu_message`)
+- **Reaction tools**: Add, remove, and list emoji reactions on messages (`feishu_reaction`)
 - **@mention forwarding**: When you @mention someone in your message, the bot's reply will automatically @mention them too
 - **Permission error notification**: When the bot encounters a Feishu API permission error, it automatically notifies the user with the permission grant URL
 - **Dynamic agent creation**: Each DM user can have their own isolated agent instance with dedicated workspace (optional)
@@ -629,6 +651,9 @@ openclaw plugins list | rg -i feishu
 | `task:attachment:read` | `feishu_task_attachment_list`, `feishu_task_attachment_get` | 列出/获取任务附件 |
 | `im:chat.announcement:read` | `feishu_chat` | 读取群公告 |
 | `im:chat:readonly` | `feishu_chat` | 获取群信息、检查机器人是否在群内 |
+| `im:message` 或 `im:message:readonly` | `feishu_message` | 读取单条/私聊消息 |
+| `im:message.group_at_msg:readonly` | `feishu_message` | 读取群聊中所有消息 |
+| `im:message.reactions:read` | `feishu_reaction` | 查看消息表情回复 |
 
 **读写权限**（可选，用于创建/编辑/删除操作）：
 
@@ -647,6 +672,7 @@ openclaw plugins list | rg -i feishu
 | `im:chat.announcement` | `feishu_chat` | 写入/更新群公告 |
 | `im:chat` | `feishu_chat` | 创建和删除群聊 |
 | `im:chat.members` | `feishu_chat` | 向群聊添加成员 |
+| `im:message.reactions:write_only` | `feishu_reaction` | 发送、删除消息表情回复 |
 
 > 飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 `task` / `tasklist` / `comment` / `attachment` 搜索并授予对应读写权限。
 
@@ -994,6 +1020,8 @@ session:
 - **任务工具**：基于 Task v2 API 支持任务创建、获取详情、更新和删除
 - **群聊工具**：读写群公告、创建群聊、添加成员、检查机器人是否在群内、删除群聊（`feishu_chat`）
 - **加急通知工具**：发送应用内加急（buzz）、短信、语音电话加急通知（`feishu_urgent`）
+- **消息工具**：读取单条消息或列出聊天历史记录，支持时间范围和分页（`feishu_message`）
+- **表情工具**：添加、删除、列出消息上的表情回复（`feishu_reaction`）
 - **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
 - **权限错误提示**：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
 - **动态 Agent 创建**：每个私聊用户可拥有独立的 agent 实例和专属 workspace（可选）

package/index.ts

@@ -9,6 +9,8 @@ import { registerFeishuPermTools } from "./src/perm-tools/index.js";
 import { registerFeishuTaskTools } from "./src/task-tools/index.js";
 import { registerFeishuChatTools } from "./src/chat-tools/index.js";
 import { registerFeishuUrgentTools } from "./src/urgent-tools/index.js";
+import { registerFeishuMessageTools } from "./src/message-tools/index.js";
+import { registerFeishuReactionTools } from "./src/reaction-tools/index.js";
 import { registerFeishuWikiTools } from "./src/wiki-tools/index.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
@@ -64,6 +66,8 @@ const plugin = {
     registerFeishuTaskTools(api);
     registerFeishuChatTools(api);
     registerFeishuUrgentTools(api);
+    registerFeishuMessageTools(api);
+    registerFeishuReactionTools(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "scripts": {
@@ -57,6 +57,7 @@
     "@larksuiteoapi/node-sdk": "^1.59.0",
     "@sinclair/typebox": "0.34.48",
     "https-proxy-agent": "^7.0.6",
+    "music-metadata": "^11.12.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/skills/feishu-message/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: feishu-message
+description: |
+  Feishu message reading. Activate when user mentions reading messages, chat history, message lookup, or finding previous messages.
+---
+
+# Feishu Message Tool
+
+Single tool `feishu_message` for reading Feishu messages — get a single message by ID or list recent messages in a chat.
+
+## Actions
+
+### Get Single Message
+
+```json
+{
+  "action": "get",
+  "message_id": "om_xxx"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "action": "get",
+  "found": true,
+  "message_id": "om_xxx",
+  "msg_type": "text",
+  "content": "Hello world",
+  "sender_id": "ou_xxx",
+  "sender_type": "user",
+  "chat_id": "oc_xxx",
+  "create_time": "1710000000000",
+  "update_time": "1710000000000",
+  "mentions": []
+}
+```
+
+### List Recent Messages
+
+List recent messages in a chat (DM or group), newest first by default.
+Omit `chat_id` to use the current conversation's chat:
+
+```json
+{
+  "action": "list"
+}
+```
+
+With custom page size, sort order, and time range:
+
+```json
+{
+  "action": "list",
+  "chat_id": "oc_xxx",
+  "page_size": 20,
+  "sort_type": "ByCreateTimeAsc",
+  "start_time": "1710000000",
+  "end_time": "1710086400"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "action": "list",
+  "chat_id": "oc_xxx",
+  "total": 10,
+  "messages": [
+    {
+      "message_id": "om_xxx",
+      "msg_type": "text",
+      "content_preview": "Hello world",
+      "sender_id": "ou_xxx",
+      "sender_type": "user",
+      "create_time": "1710000000000",
+      "chat_id": "oc_xxx"
+    }
+  ]
+}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | Yes | `get` or `list` |
+| `message_id` | get: Yes | Feishu message ID (e.g., `om_xxx`) |
+| `chat_id` | list: Optional | Chat ID (e.g., `oc_xxx`). Omit to use current chat. |
+| `page_size` | list: Optional | Number of messages (default: 10, max: 50) |
+| `sort_type` | list: Optional | `ByCreateTimeDesc` (default) or `ByCreateTimeAsc` |
+| `start_time` | list: Optional | Unix timestamp in seconds (e.g., `"1710000000"`). No lower bound if omitted. |
+| `end_time` | list: Optional | Unix timestamp in seconds (e.g., `"1710086400"`). No upper bound if omitted. |
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      message: true  # default: true
+```
+
+## Permissions
+
+- `im:message` or `im:message:readonly` — read single/DM messages
+- `im:message.group_at_msg:readonly` — read all messages in group chats (not just @bot messages)

package/skills/feishu-reaction/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: feishu-reaction
+description: |
+  Feishu message emoji reactions. Activate when user mentions emoji, reaction, thumbsup, like, or responding to messages with emoji.
+---
+
+# Feishu Reaction Tool
+
+Single tool `feishu_reaction` for adding, removing, and listing emoji reactions on Feishu messages.
+
+## Workflow: Reacting to Previous Messages
+
+To react to a message other than the current one, first use `feishu_message` with `action: "list"` to fetch recent messages and find the target `message_id`, then use `feishu_reaction` with that `message_id`.
+
+## Actions
+
+### Add Reaction
+
+```json
+{
+  "action": "add",
+  "message_id": "om_xxx",
+  "emoji_type": "THUMBSUP"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "action": "add",
+  "message_id": "om_xxx",
+  "emoji_type": "THUMBSUP",
+  "reaction_id": "ZCaCIjUBVVWSrm5L-3ZTw"
+}
+```
+
+### Remove Reaction
+
+```json
+{
+  "action": "remove",
+  "message_id": "om_xxx",
+  "reaction_id": "ZCaCIjUBVVWSrm5L-3ZTw"
+}
+```
+
+### List Reactions
+
+List all reactions on a message:
+
+```json
+{
+  "action": "list",
+  "message_id": "om_xxx"
+}
+```
+
+Filter by emoji type:
+
+```json
+{
+  "action": "list",
+  "message_id": "om_xxx",
+  "emoji_type": "THUMBSUP"
+}
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "action": "list",
+  "message_id": "om_xxx",
+  "emoji_type_filter": "THUMBSUP",
+  "total": 2,
+  "reactions": [
+    {
+      "reaction_id": "ZCaCIjUBVVWSrm5L-3ZTw",
+      "emoji_type": "THUMBSUP",
+      "operator_type": "user",
+      "operator_id": "ou_xxx"
+    }
+  ]
+}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | Yes | `add`, `remove`, or `list` |
+| `message_id` | Yes | Feishu message ID (e.g., `om_xxx`) |
+| `emoji_type` | add: Yes, list: Optional | Emoji type (e.g., `THUMBSUP`, `HEART`, `SMILE`) |
+| `reaction_id` | remove: Yes | Reaction ID from add or list results |
+
+## Common Emoji Types
+
+| Emoji | Type |
+|-------|------|
+| THUMBSUP | THUMBSDOWN | HEART | SMILE | GRINNING |
+| FIRE | CLAP | OK | CHECK | CROSS |
+| PARTY | PRAY | CRY | ANGRY | THINKING |
+| SURPRISED | LAUGHING | FIST | QUESTION | EXCLAMATION |
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      reaction: true  # default: true
+```
+
+## Permissions
+
+- `im:message.reactions:write_only` — add and remove reactions
+- `im:message.reactions:read` — list reactions on messages

package/src/bot.ts

@@ -1488,6 +1488,8 @@ export async function handleFeishuMessage(params: {
           channel: "feishu",
           accountId: account.accountId,
           sessionKey: route.sessionKey,
+          senderOpenId: ctx.senderOpenId,
+          chatId: ctx.chatId,
         },
         // Keep account context available while the agent executes plugin tools.
         () =>
@@ -1574,6 +1576,8 @@ export async function handleFeishuMessage(params: {
         channel: "feishu",
         accountId: account.accountId,
         sessionKey: route.sessionKey,
+        senderOpenId: ctx.senderOpenId,
+        chatId: ctx.chatId,
       },
       // Tool calls produced by this turn should resolve to the same inbound account.
       () =>

package/src/channel.ts

@@ -60,6 +60,8 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
     messageToolHints: () => [
       "- Feishu targeting: omit `target` to reply to the current conversation (auto-inferred). Explicit targets: `user:open_id` or `chat:chat_id`.",
       "- Feishu supports interactive cards for rich messages.",
+      "- To send a file from the OpenClaw agent's local filesystem workspace (or another allowed local path) as a Feishu attachment, reply with a standalone `MEDIA:<absolute-path-or-url>` line.",
+      "- `feishu_drive` is for Feishu cloud Drive content, not for the OpenClaw agent's local filesystem workspace.",
     ],
   },
   groups: {

package/src/chat-tools/actions.ts

@@ -2,6 +2,23 @@ import type { ChatClient } from "./common.js";
 import type { FeishuChatParams } from "./schemas.js";
 import { runChatApiCall } from "./common.js";
 
+type UserIdType = "open_id" | "user_id" | "union_id";
+type MemberIdType = UserIdType | "app_id";
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} is required`);
+  }
+  return value;
+}
+
+function requireStringArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${field} must be a non-empty string array`);
+  }
+  return value;
+}
+
 const BLOCK_TYPE_NAMES: Record<number, string> = {
   1: "Page",
   2: "Text",
@@ -117,15 +134,35 @@ async function writeDocAnnouncement(client: ChatClient, chatId: string, content:
     }),
   );
 
-  const res = await runChatApiCall("im.chatAnnouncement.patch", () =>
-    (client as any).im.chatAnnouncement.patch({
-      path: { chat_id: chatId },
-      data: {
-        content,
-        revision: (current as any).data?.revision,
-      },
-    }),
-  );
+  const revision = (current as any).data?.revision;
+  if (!revision) {
+    throw new Error("Failed to load current announcement revision");
+  }
+
+  let res: unknown;
+  try {
+    // Prefer SDK current payload shape (revision + requests[]).
+    res = await runChatApiCall("im.chatAnnouncement.patch", () =>
+      (client as any).im.chatAnnouncement.patch({
+        path: { chat_id: chatId },
+        data: {
+          revision,
+          requests: [content],
+        },
+      }),
+    );
+  } catch {
+    // Backward compatibility for tenants still accepting legacy content payload.
+    res = await runChatApiCall("im.chatAnnouncement.patch", () =>
+      (client as any).im.chatAnnouncement.patch({
+        path: { chat_id: chatId },
+        data: {
+          content,
+          revision,
+        },
+      }),
+    );
+  }
 
   return {
     success: true,
@@ -210,7 +247,13 @@ async function batchUpdateAnnouncementBlocks(
 
 // ============== New Chat Management Functions ==============
 
-async function createChat(client: ChatClient, name: string, userIds?: string[], description?: string) {
+async function createChat(
+  client: ChatClient,
+  name: string,
+  userIds?: string[],
+  description?: string,
+  userIdType: UserIdType = "open_id",
+) {
   const data: any = { name };
   if (userIds && userIds.length > 0) {
     data.user_id_list = userIds;
@@ -222,7 +265,7 @@ async function createChat(client: ChatClient, name: string, userIds?: string[],
   const res = await runChatApiCall("im.chat.create", () =>
     (client as any).im.chat.create({
       data,
-      params: { user_id_type: "open_id" },
+      params: { user_id_type: userIdType },
     }),
   );
 
@@ -233,11 +276,16 @@ async function createChat(client: ChatClient, name: string, userIds?: string[],
   };
 }
 
-async function addMembers(client: ChatClient, chatId: string, userIds: string[]) {
+async function addMembers(
+  client: ChatClient,
+  chatId: string,
+  userIds: string[],
+  memberIdType: MemberIdType = "open_id",
+) {
   const res = await runChatApiCall("im.chatMembers.create", () =>
     (client as any).im.chatMembers.create({
       path: { chat_id: chatId },
-      params: { member_id_type: "open_id" },
+      params: { member_id_type: memberIdType },
       data: { id_list: userIds },
     }),
   );
@@ -300,9 +348,10 @@ async function createSessionChat(
   userIds: string[],
   greeting?: string,
   description?: string,
+  userIdType: UserIdType = "open_id",
 ) {
   // Step 1: Create the chat
-  const createResult = await createChat(client, name, userIds, description);
+  const createResult = await createChat(client, name, userIds, description, userIdType);
   const chatId = createResult.chat_id;
   
   if (!chatId) {
@@ -358,15 +407,21 @@ export async function runChatAction(client: ChatClient, params: FeishuChatParams
   switch (params.action) {
     case "get_announcement_info":
     case "get_announcement":
-      return getAnnouncement(client, params.chat_id);
+      return getAnnouncement(client, requireString(params.chat_id, "chat_id"));
     case "list_announcement_blocks":
-      return listAnnouncementBlocks(client, params.chat_id);
+      return listAnnouncementBlocks(client, requireString(params.chat_id, "chat_id"));
     case "get_announcement_block":
-      return getAnnouncementBlock(client, params.chat_id, params.block_id);
+      return getAnnouncementBlock(
+        client,
+        requireString(params.chat_id, "chat_id"),
+        requireString(params.block_id, "block_id"),
+      );
     case "write_announcement": {
-      const current = await getAnnouncement(client, params.chat_id);
+      const chatId = requireString(params.chat_id, "chat_id");
+      const content = requireString(params.content, "content");
+      const current = await getAnnouncement(client, chatId);
       if (current.announcement_type === "doc") {
-        return writeDocAnnouncement(client, params.chat_id, params.content);
+        return writeDocAnnouncement(client, chatId, content);
       } else {
         // For docx announcements, append a text block under the Page root block.
         // Full replacement is not supported via API; use update_announcement_block to edit existing blocks.
@@ -375,15 +430,17 @@ export async function runChatAction(client: ChatClient, params: FeishuChatParams
         if (!pageBlock?.block_id) {
           return { error: "Could not find the Page root block for docx announcement. Use list_announcement_blocks to inspect the structure." };
         }
-        return createTextBlock(client, params.chat_id, pageBlock.block_id, params.content);
+        return createTextBlock(client, chatId, pageBlock.block_id, content);
       }
     }
     case "append_announcement": {
-      const current = await getAnnouncement(client, params.chat_id);
+      const chatId = requireString(params.chat_id, "chat_id");
+      const content = requireString(params.content, "content");
+      const current = await getAnnouncement(client, chatId);
       if (current.announcement_type === "doc") {
         const existingContent = (current as any).content || "";
-        const newContent = existingContent + "\n" + params.content;
-        return writeDocAnnouncement(client, params.chat_id, newContent);
+        const newContent = existingContent + "\n" + content;
+        return writeDocAnnouncement(client, chatId, newContent);
       } else {
         // For docx format, the parent block must be the Page root block (block_type: 1)
         const blocks: any[] = (current as any).blocks ?? [];
@@ -391,40 +448,52 @@ export async function runChatAction(client: ChatClient, params: FeishuChatParams
         if (!pageBlock?.block_id) {
           return { error: "Could not find the Page root block for docx announcement. Use list_announcement_blocks to inspect the structure." };
         }
-        return createTextBlock(client, params.chat_id, pageBlock.block_id, params.content);
+        return createTextBlock(client, chatId, pageBlock.block_id, content);
       }
     }
     case "update_announcement_block": {
       const requests = [
         {
-          block_id: params.block_id,
+          block_id: requireString(params.block_id, "block_id"),
           update_text_elements: {
-            elements: [{ text_run: { content: params.content } }],
+            elements: [{ text_run: { content: requireString(params.content, "content") } }],
           },
         },
       ];
-      return batchUpdateAnnouncementBlocks(client, params.chat_id, requests);
+      return batchUpdateAnnouncementBlocks(client, requireString(params.chat_id, "chat_id"), requests);
     }
     // ============== New Chat Management Actions ==============
     case "create_chat": {
-      return createChat(client, params.name, params.user_ids, params.description);
+      return createChat(
+        client,
+        requireString(params.name, "name"),
+        params.user_ids,
+        params.description,
+        params.user_id_type,
+      );
     }
     case "add_members": {
-      return addMembers(client, params.chat_id, params.user_ids);
+      return addMembers(
+        client,
+        requireString(params.chat_id, "chat_id"),
+        requireStringArray(params.user_ids, "user_ids"),
+        params.member_id_type,
+      );
     }
     case "check_bot_in_chat": {
-      return checkBotInChat(client, params.chat_id);
+      return checkBotInChat(client, requireString(params.chat_id, "chat_id"));
     }
     case "delete_chat": {
-      return deleteChat(client, params.chat_id);
+      return deleteChat(client, requireString(params.chat_id, "chat_id"));
     }
     case "create_session_chat": {
       return createSessionChat(
         client,
-        params.name,
-        params.user_ids,
+        requireString(params.name, "name"),
+        requireStringArray(params.user_ids, "user_ids"),
         params.greeting,
         params.description,
+        params.user_id_type,
       );
     }
     default: