@max1874/feishu 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # clawd-feishu
 
-Feishu/Lark (飞书) channel plugin for [Clawdbot](https://github.com/clawdbot/clawdbot).
+Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
 
 [English](#english) | [中文](#中文)
 
@@ -11,7 +11,7 @@ Feishu/Lark (飞书) channel plugin for [Clawdbot](https://github.com/clawdbot/c
 ### Installation
 
 ```bash
-clawdbot plugins install @m1heng-clawd/feishu
+openclaw plugins install @m1heng-clawd/feishu
 ```
 
 Or install via npm:
@@ -32,7 +32,7 @@ npm install @m1heng-clawd/feishu
 
 | Permission | Scope | Description |
 |------------|-------|-------------|
-| `contact:user.base:readonly` | User info | Get basic user information |
+| `contact:user.base:readonly` | User info | Get basic user info (required to resolve sender display names for speaker attribution) |
 | `im:message` | Messaging | Send and receive messages |
 | `im:message.p2p_msg:readonly` | DM | Read direct messages to bot |
 | `im:message.group_at_msg:readonly` | Group | Receive @mention messages in groups |
@@ -49,6 +49,18 @@ npm install @m1heng-clawd/feishu
 | `im:message:recall` | Recall | Recall sent messages |
 | `im:message.reactions:read` | Reactions | View message reactions |
 
+#### Document Tools Permissions
+
+Required if using Feishu document tools (`feishu_doc_*`):
+
+| Permission | Description |
+|------------|-------------|
+| `docx:document` | Create/edit documents |
+| `docx:document:readonly` | Read documents |
+| `docx:document.block:convert` | Markdown to blocks conversion (required for write/append) |
+| `drive:drive` | Upload images to documents |
+| `drive:drive:readonly` | List folders |
+
 #### Event Subscriptions ⚠️
 
 > **This is the most commonly missed configuration!** If the bot can send messages but cannot receive them, check this section.
@@ -68,9 +80,9 @@ In the Feishu Open Platform console, go to **Events & Callbacks**:
 3. Ensure the event permissions are approved
 
 ```bash
-clawdbot config set channels.feishu.appId "cli_xxxxx"
-clawdbot config set channels.feishu.appSecret "your_app_secret"
-clawdbot config set channels.feishu.enabled true
+openclaw config set channels.feishu.appId "cli_xxxxx"
+openclaw config set channels.feishu.appSecret "your_app_secret"
+openclaw config set channels.feishu.enabled true
 ```
 
 ### Configuration Options
@@ -116,6 +128,17 @@ channels:
 - Pairing flow for DM approval
 - User and group directory lookup
 - **Card render mode**: Optional markdown rendering with syntax highlighting
+- **Document tools**: Read, create, and write Feishu documents with markdown (tables not supported due to API limitations)
+- **@mention forwarding**: When you @mention someone in your message, the bot's reply will automatically @mention them too
+
+#### @Mention Forwarding
+
+When you want the bot to @mention someone in its reply, simply @mention them in your message:
+
+- **In DM**: `@张三 say hello` → Bot replies with `@张三 Hello!`
+- **In Group**: `@bot @张三 say hello` → Bot replies with `@张三 Hello!`
+
+The bot automatically detects @mentions in your message and includes them in its reply. No extra permissions required beyond the standard messaging permissions.
 
 ### FAQ
 
@@ -141,14 +164,14 @@ Feishu API has rate limits. Streaming updates can easily trigger throttling. We
 
 #### Windows install error `spawn npm ENOENT`
 
-If `clawdbot plugins install` fails, install manually:
+If `openclaw plugins install` fails, install manually:
 
 ```bash
 # 1. Download the package
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
+curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
 
 # 2. Install from local file
-clawdbot plugins install ./feishu-0.1.1.tgz
+openclaw plugins install ./feishu-0.1.3.tgz
 ```
 
 #### Cannot find the bot in Feishu
@@ -164,7 +187,7 @@ clawdbot plugins install ./feishu-0.1.1.tgz
 ### 安装
 
 ```bash
-clawdbot plugins install @m1heng-clawd/feishu
+openclaw plugins install @m1heng-clawd/feishu
 ```
 
 或通过 npm 安装：
@@ -185,7 +208,7 @@ npm install @m1heng-clawd/feishu
 
 | 权限 | 范围 | 说明 |
 |------|------|------|
-| `contact:user.base:readonly` | 用户信息 | 获取用户基本信息 |
+| `contact:user.base:readonly` | 用户信息 | 获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者） |
 | `im:message` | 消息 | 发送和接收消息 |
 | `im:message.p2p_msg:readonly` | 私聊 | 读取发给机器人的私聊消息 |
 | `im:message.group_at_msg:readonly` | 群聊 | 接收群内 @机器人 的消息 |
@@ -202,6 +225,18 @@ npm install @m1heng-clawd/feishu
 | `im:message:recall` | 撤回 | 撤回已发送消息 |
 | `im:message.reactions:read` | 表情 | 查看消息表情回复 |
 
+#### 文档工具权限
+
+使用飞书文档工具（`feishu_doc_*`）需要以下权限：
+
+| 权限 | 说明 |
+|------|------|
+| `docx:document` | 创建/编辑文档 |
+| `docx:document:readonly` | 读取文档 |
+| `docx:document.block:convert` | Markdown 转 blocks（write/append 必需） |
+| `drive:drive` | 上传图片到文档 |
+| `drive:drive:readonly` | 列出文件夹 |
+
 #### 事件订阅 ⚠️
 
 > **这是最容易遗漏的配置！** 如果机器人能发消息但收不到消息，请检查此项。
@@ -221,9 +256,9 @@ npm install @m1heng-clawd/feishu
 3. 确保事件订阅的权限已申请并通过审核
 
 ```bash
-clawdbot config set channels.feishu.appId "cli_xxxxx"
-clawdbot config set channels.feishu.appSecret "your_app_secret"
-clawdbot config set channels.feishu.enabled true
+openclaw config set channels.feishu.appId "cli_xxxxx"
+openclaw config set channels.feishu.appSecret "your_app_secret"
+openclaw config set channels.feishu.enabled true
 ```
 
 ### 配置选项
@@ -269,6 +304,17 @@ channels:
 - 私聊配对审批流程
 - 用户和群组目录查询
 - **卡片渲染模式**：支持语法高亮的 Markdown 渲染
+- **文档工具**：读取、创建、用 Markdown 写入飞书文档（表格因 API 限制不支持）
+- **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
+
+#### @ 转发功能
+
+如果你希望机器人的回复中 @ 某人，只需在你的消息中 @ 他们：
+
+- **私聊**：`@张三 跟他问好` → 机器人回复 `@张三 你好！`
+- **群聊**：`@机器人 @张三 跟他问好` → 机器人回复 `@张三 你好！`
+
+机器人会自动检测消息中的 @ 并在回复时带上。无需额外权限。
 
 ### 常见问题
 
@@ -294,14 +340,14 @@ channels:
 
 #### Windows 安装报错 `spawn npm ENOENT`
 
-如果 `clawdbot plugins install` 失败，可以手动安装：
+如果 `openclaw plugins install` 失败，可以手动安装：
 
 ```bash
 # 1. 下载插件包
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
+curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
 
 # 2. 从本地安装
-clawdbot plugins install ./feishu-0.1.1.tgz
+openclaw plugins install ./feishu-0.1.3.tgz
 ```
 
 #### 在飞书里找不到机器人

package/index.ts

@@ -1,7 +1,8 @@
-import type { ClawdbotPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { feishuPlugin } from "./src/channel.js";
 import { setFeishuRuntime } from "./src/runtime.js";
+import { registerFeishuDocTools } from "./src/docx.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
 export {
@@ -25,6 +26,18 @@ export {
   listReactionsFeishu,
   FeishuEmoji,
 } from "./src/reactions.js";
+export {
+  extractMentionTargets,
+  extractMessageBody,
+  isMentionForwardRequest,
+  formatMentionForText,
+  formatMentionForCard,
+  formatMentionAllForText,
+  formatMentionAllForCard,
+  buildMentionedMessage,
+  buildMentionedCardContent,
+  type MentionTarget,
+} from "./src/mention.js";
 export { feishuPlugin } from "./src/channel.js";
 
 const plugin = {
@@ -32,9 +45,10 @@ const plugin = {
   name: "Feishu",
   description: "Feishu/Lark channel plugin",
   configSchema: emptyPluginConfigSchema(),
-  register(api: ClawdbotPluginApi) {
+  register(api: OpenClawPluginApi) {
     setFeishuRuntime(api.runtime);
     api.registerChannel({ plugin: feishuPlugin });
+    registerFeishuDocTools(api);
   },
 };
 

package/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "feishu",
   "channels": ["feishu"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@max1874/feishu",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
-  "description": "Clawdbot Feishu/Lark channel plugin",
+  "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",
   "files": [
     "index.ts",
@@ -11,10 +11,10 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/m1heng/clawdbot-feishu.git"
+    "url": "git+https://github.com/max1874/clawdbot-feishu.git"
   },
   "keywords": [
-    "clawdbot",
+    "openclaw",
     "feishu",
     "lark",
     "飞书",
@@ -46,15 +46,16 @@
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.30.0",
+    "@sinclair/typebox": "^0.34.48",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
-    "openclaw": "2026.1.24-2",
+    "openclaw": "2026.1.29",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.24"
+    "openclaw": ">=2026.1.29"
   }
 }

package/src/bot.ts

@@ -8,6 +8,7 @@ import {
 } from "openclaw/plugin-sdk";
 import type { FeishuConfig, FeishuMessageContext, FeishuMediaInfo } from "./types.js";
 import { getFeishuRuntime } from "./runtime.js";
+import { createFeishuClient } from "./client.js";
 import {
   resolveFeishuGroupConfig,
   resolveFeishuReplyPolicy,
@@ -15,8 +16,59 @@ import {
   isFeishuGroupAllowed,
 } from "./policy.js";
 import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
-import { getMessageFeishu } from "./send.js";
+import { getMessageFeishu, getMergeForwardMessagesFeishu } from "./send.js";
 import { downloadImageFeishu, downloadMessageResourceFeishu } from "./media.js";
+import {
+  extractMentionTargets,
+  extractMessageBody,
+  isMentionForwardRequest,
+} from "./mention.js";
+
+// --- Sender name resolution (so the agent can distinguish who is speaking in group chats) ---
+// Cache display names by open_id to avoid an API call on every message.
+const SENDER_NAME_TTL_MS = 10 * 60 * 1000;
+const senderNameCache = new Map<string, { name: string; expireAt: number }>();
+
+async function resolveFeishuSenderName(params: {
+  feishuCfg?: FeishuConfig;
+  senderOpenId: string;
+  log: (...args: any[]) => void;
+}): Promise<string | undefined> {
+  const { feishuCfg, senderOpenId, log } = params;
+  if (!feishuCfg) return undefined;
+  if (!senderOpenId) return undefined;
+
+  const cached = senderNameCache.get(senderOpenId);
+  const now = Date.now();
+  if (cached && cached.expireAt > now) return cached.name;
+
+  try {
+    const client = createFeishuClient(feishuCfg);
+
+    // contact/v3/users/:user_id?user_id_type=open_id
+    const res: any = await client.contact.user.get({
+      path: { user_id: senderOpenId },
+      params: { user_id_type: "open_id" },
+    });
+
+    const name: string | undefined =
+      res?.data?.user?.name ||
+      res?.data?.user?.display_name ||
+      res?.data?.user?.nickname ||
+      res?.data?.user?.en_name;
+
+    if (name && typeof name === "string") {
+      senderNameCache.set(senderOpenId, { name, expireAt: now + SENDER_NAME_TTL_MS });
+      return name;
+    }
+
+    return undefined;
+  } catch (err) {
+    // Best-effort. Don't fail message handling if name lookup fails.
+    log(`feishu: failed to resolve sender name for ${senderOpenId}: ${String(err)}`);
+    return undefined;
+  }
+}
 
 export type FeishuMessageEvent = {
   sender: {
@@ -171,6 +223,40 @@ function parsePostContent(content: string): {
   }
 }
 
+/**
+ * Format merge_forward child messages into readable text.
+ */
+function formatMergeForwardContent(
+  messages: Array<{ content: string; contentType: string }>,
+): string {
+  if (messages.length === 0) {
+    return "[转发的聊天记录 - 无内容]";
+  }
+
+  const lines: string[] = ["[转发的聊天记录]", "---"];
+
+  for (const msg of messages) {
+    if (msg.contentType === "text" || msg.contentType === "post") {
+      lines.push(msg.content);
+    } else if (msg.contentType === "image") {
+      lines.push("[图片]");
+    } else if (msg.contentType === "file") {
+      lines.push("[文件]");
+    } else if (msg.contentType === "audio") {
+      lines.push("[语音]");
+    } else if (msg.contentType === "video") {
+      lines.push("[视频]");
+    } else if (msg.contentType === "sticker") {
+      lines.push("[表情]");
+    } else {
+      lines.push(`[${msg.contentType}]`);
+    }
+  }
+
+  lines.push("---");
+  return lines.join("\n");
+}
+
 /**
  * Infer placeholder text based on message type.
  */
@@ -352,7 +438,7 @@ export function parseFeishuMessageEvent(
   const mentionedBot = checkBotMentioned(event, botOpenId);
   const content = stripBotMention(rawContent, event.message.mentions);
 
-  return {
+  const ctx: FeishuMessageContext = {
     chatId: event.message.chat_id,
     messageId: event.message.message_id,
     senderId: event.sender.sender_id.user_id || event.sender.sender_id.open_id || "",
@@ -364,6 +450,19 @@ export function parseFeishuMessageEvent(
     content,
     contentType: event.message.message_type,
   };
+
+  // Detect mention forward request: message mentions bot + at least one other user
+  if (isMentionForwardRequest(event, botOpenId)) {
+    const mentionTargets = extractMentionTargets(event, botOpenId);
+    if (mentionTargets.length > 0) {
+      ctx.mentionTargets = mentionTargets;
+      // Extract message body (remove all @ placeholders)
+      const allMentionKeys = (event.message.mentions ?? []).map((m) => m.key);
+      ctx.mentionMessageBody = extractMessageBody(content, allMentionKeys);
+    }
+  }
+
+  return ctx;
 }
 
 export async function handleFeishuMessage(params: {
@@ -378,11 +477,42 @@ export async function handleFeishuMessage(params: {
   const log = runtime?.log ?? console.log;
   const error = runtime?.error ?? console.error;
 
-  const ctx = parseFeishuMessageEvent(event, botOpenId);
+  let ctx = parseFeishuMessageEvent(event, botOpenId);
   const isGroup = ctx.chatType === "group";
 
+  // Handle merge_forward messages: fetch child messages and format as readable text
+  if (ctx.contentType === "merge_forward") {
+    try {
+      log(`feishu: detected merge_forward message, fetching child messages...`);
+      const childMessages = await getMergeForwardMessagesFeishu({
+        cfg,
+        messageId: ctx.messageId,
+      });
+      const formattedContent = formatMergeForwardContent(childMessages);
+      ctx = { ...ctx, content: formattedContent };
+      log(`feishu: resolved merge_forward with ${childMessages.length} child message(s)`);
+    } catch (err) {
+      log(`feishu: failed to fetch merge_forward content: ${String(err)}`);
+      ctx = { ...ctx, content: "[转发的聊天记录 - 获取失败]" };
+    }
+  }
+
+  // Resolve sender display name (best-effort) so the agent can attribute messages correctly.
+  const senderName = await resolveFeishuSenderName({
+    feishuCfg,
+    senderOpenId: ctx.senderOpenId,
+    log,
+  });
+  if (senderName) ctx = { ...ctx, senderName };
+
   log(`feishu: received message from ${ctx.senderOpenId} in ${ctx.chatId} (${ctx.chatType})`);
 
+  // Log mention targets if detected
+  if (ctx.mentionTargets && ctx.mentionTargets.length > 0) {
+    const names = ctx.mentionTargets.map((t) => t.name).join(", ");
+    log(`feishu: detected @ forward request, targets: [${names}]`);
+  }
+
   const historyLimit = Math.max(
     0,
     feishuCfg?.historyLimit ?? cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
@@ -421,7 +551,7 @@ export async function handleFeishuMessage(params: {
           limit: historyLimit,
           entry: {
             sender: ctx.senderOpenId,
-            body: ctx.content,
+            body: `${ctx.senderName ?? ctx.senderOpenId}: ${ctx.content}`,
             timestamp: Date.now(),
             messageId: ctx.messageId,
           },
@@ -448,7 +578,9 @@ export async function handleFeishuMessage(params: {
   try {
     const core = getFeishuRuntime();
 
-    const feishuFrom = isGroup ? `feishu:group:${ctx.chatId}` : `feishu:${ctx.senderOpenId}`;
+    // In group chats, the session is scoped to the group, but the *speaker* is the sender.
+    // Using a group-scoped From causes the agent to treat different users as the same person.
+    const feishuFrom = `feishu:${ctx.senderOpenId}`;
     const feishuTo = isGroup ? `chat:${ctx.chatId}` : `user:${ctx.senderOpenId}`;
 
     const route = core.channel.routing.resolveAgentRoute({
@@ -504,9 +636,22 @@ export async function handleFeishuMessage(params: {
       messageBody = `[Replying to: "${quotedContent}"]\n\n${ctx.content}`;
     }
 
+    // Include a readable speaker label so the model can attribute instructions.
+    // (DMs already have per-sender sessions, but the prefix is still useful for clarity.)
+    const speaker = ctx.senderName ?? ctx.senderOpenId;
+    messageBody = `${speaker}: ${messageBody}`;
+
+    // If there are mention targets, inform the agent that replies will auto-mention them
+    if (ctx.mentionTargets && ctx.mentionTargets.length > 0) {
+      const targetNames = ctx.mentionTargets.map((t) => t.name).join(", ");
+      messageBody += `\n\n[System: Your reply will automatically @mention: ${targetNames}. Do not write @xxx yourself.]`;
+    }
+
+    const envelopeFrom = isGroup ? `${ctx.chatId}:${ctx.senderOpenId}` : ctx.senderOpenId;
+
     const body = core.channel.reply.formatAgentEnvelope({
       channel: "Feishu",
-      from: isGroup ? ctx.chatId : ctx.senderOpenId,
+      from: envelopeFrom,
       timestamp: new Date(),
       envelope: envelopeOptions,
       body: messageBody,
@@ -524,9 +669,10 @@ export async function handleFeishuMessage(params: {
         formatEntry: (entry) =>
           core.channel.reply.formatAgentEnvelope({
             channel: "Feishu",
-            from: ctx.chatId,
+            // Preserve speaker identity in group history as well.
+            from: `${ctx.chatId}:${entry.sender}`,
             timestamp: entry.timestamp,
-            body: `${entry.sender}: ${entry.body}`,
+            body: entry.body,
             envelope: envelopeOptions,
           }),
       });
@@ -542,7 +688,7 @@ export async function handleFeishuMessage(params: {
       AccountId: route.accountId,
       ChatType: isGroup ? "group" : "direct",
       GroupSubject: isGroup ? ctx.chatId : undefined,
-      SenderName: ctx.senderOpenId,
+      SenderName: ctx.senderName ?? ctx.senderOpenId,
       SenderId: ctx.senderOpenId,
       Provider: "feishu" as const,
       Surface: "feishu" as const,
@@ -561,6 +707,7 @@ export async function handleFeishuMessage(params: {
       runtime: runtime as RuntimeEnv,
       chatId: ctx.chatId,
       replyToMessageId: ctx.messageId,
+      mentionTargets: ctx.mentionTargets,
     });
 
     log(`feishu: dispatching to agent (session=${route.sessionKey})`);