@m1heng-clawd/feishu 0.1.1 → 0.1.2

package/README.md

@@ -2,7 +2,13 @@
 
 Feishu/Lark (飞书) channel plugin for [Clawdbot](https://github.com/clawdbot/clawdbot).
 
-## Installation
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+### Installation
 
 ```bash
 clawdbot plugins install @m1heng-clawd/feishu
@@ -14,25 +20,26 @@ Or install via npm:
 npm install @m1heng-clawd/feishu
 ```
 
-## Configuration
+### Configuration
 
 1. Create a self-built app on [Feishu Open Platform](https://open.feishu.cn)
 2. Get your App ID and App Secret from the Credentials page
 3. Enable required permissions (see below)
-4. Configure the plugin:
+4. **Configure event subscriptions** (see below) ⚠️ Important
+5. Configure the plugin:
 
-### Required Permissions
+#### Required Permissions
 
 | 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 |
 | `im:message:send_as_bot` | Send | Send messages as the bot |
 | `im:resource` | Media | Upload and download images/files |
 
-### Optional Permissions (for full functionality)
+#### Optional Permissions
 
 | Permission | Scope | Description |
 |------------|-------|-------------|
@@ -42,13 +49,31 @@ npm install @m1heng-clawd/feishu
 | `im:message:recall` | Recall | Recall sent messages |
 | `im:message.reactions:read` | Reactions | View message reactions |
 
+#### Event Subscriptions ⚠️
+
+> **This is the most commonly missed configuration!** If the bot can send messages but cannot receive them, check this section.
+
+In the Feishu Open Platform console, go to **Events & Callbacks**:
+
+1. **Event configuration**: Select **Long connection** (recommended)
+2. **Add event subscriptions**:
+
+| Event | Description |
+|-------|-------------|
+| `im.message.receive_v1` | Receive messages (required) |
+| `im.message.message_read_v1` | Message read receipts |
+| `im.chat.member.bot.added_v1` | Bot added to group |
+| `im.chat.member.bot.deleted_v1` | Bot removed from group |
+
+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
 ```
 
-## Configuration Options
+### Configuration Options
 
 ```yaml
 channels:
@@ -72,7 +97,7 @@ channels:
     renderMode: "auto"
 ```
 
-### Render Mode
+#### Render Mode
 
 | Mode | Description |
 |------|-------------|
@@ -80,7 +105,7 @@ channels:
 | `raw` | Always send replies as plain text. Markdown tables are converted to ASCII. |
 | `card` | Always send replies as interactive cards with full markdown rendering (syntax highlighting, tables, clickable links). |
 
-## Features
+### Features
 
 - WebSocket and Webhook connection modes
 - Direct messages and group chats
@@ -92,6 +117,201 @@ channels:
 - User and group directory lookup
 - **Card render mode**: Optional markdown rendering with syntax highlighting
 
+### FAQ
+
+#### Bot cannot receive messages
+
+Check the following:
+1. Have you configured **event subscriptions**? (See Event Subscriptions section)
+2. Is the event configuration set to **long connection**?
+3. Did you add the `im.message.receive_v1` event?
+4. Are the permissions approved?
+
+#### 403 error when sending messages
+
+Ensure `im:message:send_as_bot` permission is approved.
+
+#### How to clear history / start new conversation
+
+Send `/new` command in the chat.
+
+#### Why is the output not streaming
+
+Feishu API has rate limits. Streaming updates can easily trigger throttling. We use complete-then-send approach for stability.
+
+#### Windows install error `spawn npm ENOENT`
+
+If `clawdbot plugins install` fails, install manually:
+
+```bash
+# 1. Download the package
+curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
+
+# 2. Install from local file
+clawdbot plugins install ./feishu-0.1.1.tgz
+```
+
+#### Cannot find the bot in Feishu
+
+1. Ensure the app is published (at least to test version)
+2. Search for the bot name in Feishu search box
+3. Check if your account is in the app's availability scope
+
+---
+
+## 中文
+
+### 安装
+
+```bash
+clawdbot plugins install @m1heng-clawd/feishu
+```
+
+或通过 npm 安装：
+
+```bash
+npm install @m1heng-clawd/feishu
+```
+
+### 配置
+
+1. 在 [飞书开放平台](https://open.feishu.cn) 创建自建应用
+2. 在凭证页面获取 App ID 和 App Secret
+3. 开启所需权限（见下方）
+4. **配置事件订阅**（见下方）⚠️ 重要
+5. 配置插件：
+
+#### 必需权限
+
+| 权限 | 范围 | 说明 |
+|------|------|------|
+| `contact:user.base:readonly` | 用户信息 | 获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者） |
+| `im:message` | 消息 | 发送和接收消息 |
+| `im:message.p2p_msg:readonly` | 私聊 | 读取发给机器人的私聊消息 |
+| `im:message.group_at_msg:readonly` | 群聊 | 接收群内 @机器人 的消息 |
+| `im:message:send_as_bot` | 发送 | 以机器人身份发送消息 |
+| `im:resource` | 媒体 | 上传和下载图片/文件 |
+
+#### 可选权限
+
+| 权限 | 范围 | 说明 |
+|------|------|------|
+| `im:message.group_msg` | 群聊 | 读取所有群消息（敏感） |
+| `im:message:readonly` | 读取 | 获取历史消息 |
+| `im:message:update` | 编辑 | 更新/编辑已发送消息 |
+| `im:message:recall` | 撤回 | 撤回已发送消息 |
+| `im:message.reactions:read` | 表情 | 查看消息表情回复 |
+
+#### 事件订阅 ⚠️
+
+> **这是最容易遗漏的配置！** 如果机器人能发消息但收不到消息，请检查此项。
+
+在飞书开放平台的应用后台，进入 **事件与回调** 页面：
+
+1. **事件配置方式**：选择 **使用长连接接收事件**（推荐）
+2. **添加事件订阅**，勾选以下事件：
+
+| 事件 | 说明 |
+|------|------|
+| `im.message.receive_v1` | 接收消息（必需） |
+| `im.message.message_read_v1` | 消息已读回执 |
+| `im.chat.member.bot.added_v1` | 机器人进群 |
+| `im.chat.member.bot.deleted_v1` | 机器人被移出群 |
+
+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
+```
+
+### 配置选项
+
+```yaml
+channels:
+  feishu:
+    enabled: true
+    appId: "cli_xxxxx"
+    appSecret: "secret"
+    # 域名: "feishu" (国内) 或 "lark" (国际)
+    domain: "feishu"
+    # 连接模式: "websocket" (推荐) 或 "webhook"
+    connectionMode: "websocket"
+    # 私聊策略: "pairing" | "open" | "allowlist"
+    dmPolicy: "pairing"
+    # 群聊策略: "open" | "allowlist" | "disabled"
+    groupPolicy: "allowlist"
+    # 群聊是否需要 @机器人
+    requireMention: true
+    # 媒体文件最大大小 (MB, 默认 30)
+    mediaMaxMb: 30
+    # 回复渲染模式: "auto" | "raw" | "card"
+    renderMode: "auto"
+```
+
+#### 渲染模式
+
+| 模式 | 说明 |
+|------|------|
+| `auto` | （默认）自动检测：有代码块或表格时用卡片，否则纯文本 |
+| `raw` | 始终纯文本，表格转为 ASCII |
+| `card` | 始终使用卡片，支持语法高亮、表格、链接等 |
+
+### 功能
+
+- WebSocket 和 Webhook 连接模式
+- 私聊和群聊
+- 消息回复和引用上下文
+- **入站媒体支持**：AI 可以看到图片、读取文件（PDF、Excel 等）、处理富文本中的嵌入图片
+- 图片和文件上传（出站）
+- 输入指示器（通过表情回复实现）
+- 私聊配对审批流程
+- 用户和群组目录查询
+- **卡片渲染模式**：支持语法高亮的 Markdown 渲染
+
+### 常见问题
+
+#### 机器人收不到消息
+
+检查以下配置：
+1. 是否配置了 **事件订阅**？（见上方事件订阅章节）
+2. 事件配置方式是否选择了 **长连接**？
+3. 是否添加了 `im.message.receive_v1` 事件？
+4. 相关权限是否已申请并审核通过？
+
+#### 返回消息时 403 错误
+
+确保已申请 `im:message:send_as_bot` 权限，并且权限已审核通过。
+
+#### 如何清理历史会话 / 开启新对话
+
+在聊天中发送 `/new` 命令即可开启新对话。
+
+#### 消息为什么不是流式输出
+
+飞书 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。
+
+#### Windows 安装报错 `spawn npm ENOENT`
+
+如果 `clawdbot plugins install` 失败，可以手动安装：
+
+```bash
+# 1. 下载插件包
+curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
+
+# 2. 从本地安装
+clawdbot plugins install ./feishu-0.1.1.tgz
+```
+
+#### 在飞书里找不到机器人
+
+1. 确保应用已发布（至少发布到测试版本）
+2. 在飞书搜索框中搜索机器人名称
+3. 检查应用可用范围是否包含你的账号
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Clawdbot Feishu/Lark channel plugin",
   "license": "MIT",

package/src/bot.ts

@@ -8,6 +8,7 @@ import {
 } from "clawdbot/plugin-sdk";
 import type { FeishuConfig, FeishuMessageContext, FeishuMediaInfo } from "./types.js";
 import { getFeishuRuntime } from "./runtime.js";
+import { createFeishuClient } from "./client.js";
 import {
   resolveFeishuGroupConfig,
   resolveFeishuReplyPolicy,
@@ -18,6 +19,52 @@ import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
 import { getMessageFeishu } from "./send.js";
 import { downloadImageFeishu, downloadMessageResourceFeishu } from "./media.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: {
     sender_id: {
@@ -378,9 +425,17 @@ 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";
 
+  // 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})`);
 
   const historyLimit = Math.max(
@@ -421,7 +476,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 +503,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 +561,16 @@ 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}`;
+
+    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 +588,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 +607,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,