@m1heng-clawd/feishu 0.1.13 → 0.1.15

package/README.md

@@ -91,7 +91,7 @@ openclaw plugins list | rg -i feishu
 | Permission | Scope | Description |
 |------------|-------|-------------|
 | `contact:user.base:readonly` | User info | Get basic user info (required to resolve sender display names for speaker attribution) |
-| `im:message.group_msg` | Group | Read all group messages (sensitive) |
+| `im:message.group_msg` | Group | Read all group messages (sensitive). Required when you want `requireMention: false` to work for non-@ group messages |
 | `im:message:readonly` | Read | Get message history |
 | `im:message:update` | Edit | Update/edit sent messages |
 | `im:message:recall` | Recall | Recall sent messages |
@@ -111,6 +111,8 @@ openclaw plugins list | rg -i feishu
 | `task:tasklist:read` | `feishu_tasklist_get`, `feishu_tasklist_list` | Get/list tasklists |
 | `task:comment:read` | `feishu_task_comment_list`, `feishu_task_comment_get` | List/get task comments |
 | `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 |
 
 **Read-write** (optional, for create/edit/delete operations):
 
@@ -125,6 +127,10 @@ openclaw plugins list | rg -i feishu
 | `task:tasklist:write` | `feishu_tasklist_create`, `feishu_tasklist_update`, `feishu_tasklist_delete`, `feishu_tasklist_add_members`, `feishu_tasklist_remove_members`, `feishu_task_add_tasklist`, `feishu_task_remove_tasklist` | Create/update/delete tasklists and manage membership |
 | `task:comment:write` | `feishu_task_comment_create`, `feishu_task_comment_update`, `feishu_task_comment_delete` | Create/update/delete task comments |
 | `task:attachment:write` | `feishu_task_attachment_upload`, `feishu_task_attachment_delete` | Upload/delete task attachments |
+| `im:message.urgent` | `feishu_urgent` | Send urgent (buzz) notifications via app (in-app). Use `sms` and `phone` variants (`im:message.urgent:sms`, `im:message.urgent:phone`) for SMS and voice call. |
+| `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 |
 
 > 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.
 
@@ -243,6 +249,10 @@ channels:
     groupPolicy: "allowlist"
     # Require @mention in groups
     requireMention: true
+    # Safety default for mention-free mode (`requireMention: false`):
+    # only allow non-@ messages in groups with <= 1 bot.
+    # Set true to also allow mention-free messages in multi-bot groups.
+    allowMentionlessInMultiBotGroup: false
     # Group command mention bypass: "never" | "single_bot" | "always"
     # Default "single_bot": allow authorized command-only messages without @
     # only when the group has a single bot.
@@ -343,6 +353,19 @@ Notes:
 - If any user is explicitly `@`-mentioned in the same message, bypass is disabled.
 - In DMs, this setting does not apply.
 
+#### Group Mention-Free Behavior (`requireMention: false`)
+
+When `requireMention: false`, non-@ group messages are handled with a safety default:
+
+| `allowMentionlessInMultiBotGroup` | Behavior for non-@ group messages |
+|-----------------------------------|-----------------------------------|
+| `false` (default) | Only accepted when the group has at most one bot. In multi-bot groups, explicit `@bot` is still required. |
+| `true` | Accepted even in multi-bot groups (use only if you accept duplicate-trigger risk). |
+
+Important:
+- `im:message.group_msg` is required for receiving non-@ group messages and this is a **sensitive permission** in Feishu.
+- If this scope is not approved, Feishu usually only delivers `@bot` group messages (`im:message.group_at_msg:readonly`).
+
 #### Connection Mode
 
 Two connection modes are available for receiving events from Feishu:
@@ -394,6 +417,14 @@ https://your-domain.com/feishu/events
 
 When enabled, each DM user automatically gets their own isolated agent instance with a dedicated workspace. This provides complete isolation including separate conversation history, memory (MEMORY.md), and workspace files.
 
+#### Chat Management Limitations ⚠️
+
+> **Important:** `delete_chat` requires the bot to be the **group owner**. If the bot was added to an existing chat as a member (not the owner), it cannot disband it.
+>
+> If you need to disband a chat that the bot does not own:
+> 1. The **group owner** transfers ownership to the bot first, or
+> 2. The group owner disbands the group directly in the Feishu app.
+
 ```yaml
 channels:
   feishu:
@@ -446,6 +477,8 @@ session:
 - **Drive tools**: List folders, get file info, create folders, move/delete files
 - **Bitable tools**: Manage bitable (多维表格) fields and records (read/create/update/delete), supports both `/base/` and `/wiki/` URLs
 - **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`
 - **@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)
@@ -472,6 +505,13 @@ Check the following:
 4. Are the permissions approved?
 5. For webhook mode: is your server running and the URL publicly accessible?
 
+#### `requireMention: false` but group still needs @
+
+Check the following:
+1. Is `im:message.group_msg` approved? (sensitive permission, required for non-@ group messages)
+2. If the group has multiple bots, do you explicitly set `allowMentionlessInMultiBotGroup: true`?
+3. Is `requireMention: false` configured on the effective account/group?
+
 #### 403 error when sending messages
 
 Ensure `im:message:send_as_bot` permission is approved.
@@ -567,7 +607,7 @@ openclaw plugins list | rg -i feishu
 | 权限 | 范围 | 说明 |
 |------|------|------|
 | `contact:user.base:readonly` | 用户信息 | 获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者） |
-| `im:message.group_msg` | 群聊 | 读取所有群消息（敏感） |
+| `im:message.group_msg` | 群聊 | 读取所有群消息（敏感权限）。当你希望 `requireMention: false` 对“未 @ 的群消息”生效时必需 |
 | `im:message:readonly` | 读取 | 获取历史消息 |
 | `im:message:update` | 编辑 | 更新/编辑已发送消息 |
 | `im:message:recall` | 撤回 | 撤回已发送消息 |
@@ -587,6 +627,8 @@ openclaw plugins list | rg -i feishu
 | `task:tasklist:read` | `feishu_tasklist_get`, `feishu_tasklist_list` | 获取/列出任务清单（tasklists） |
 | `task:comment:read` | `feishu_task_comment_list`, `feishu_task_comment_get` | 列出/获取任务评论 |
 | `task:attachment:read` | `feishu_task_attachment_list`, `feishu_task_attachment_get` | 列出/获取任务附件 |
+| `im:chat.announcement:read` | `feishu_chat` | 读取群公告 |
+| `im:chat:readonly` | `feishu_chat` | 获取群信息、检查机器人是否在群内 |
 
 **读写权限**（可选，用于创建/编辑/删除操作）：
 
@@ -601,6 +643,10 @@ openclaw plugins list | rg -i feishu
 | `task:tasklist:write` | `feishu_tasklist_create`, `feishu_tasklist_update`, `feishu_tasklist_delete`, `feishu_tasklist_add_members`, `feishu_tasklist_remove_members`, `feishu_task_add_tasklist`, `feishu_task_remove_tasklist` | 创建/更新/删除任务清单并管理成员/关联任务 |
 | `task:comment:write` | `feishu_task_comment_create`, `feishu_task_comment_update`, `feishu_task_comment_delete` | 创建/更新/删除任务评论 |
 | `task:attachment:write` | `feishu_task_attachment_upload`, `feishu_task_attachment_delete` | 上传/删除任务附件 |
+| `im:message.urgent` | `feishu_urgent` | 发送应用内加急（buzz）通知。使用 `sms` 和 `phone` 变体（`im:message.urgent:sms`、`im:message.urgent:phone`）可发送短信和语音电话加急。 |
+| `im:chat.announcement` | `feishu_chat` | 写入/更新群公告 |
+| `im:chat` | `feishu_chat` | 创建和删除群聊 |
+| `im:chat.members` | `feishu_chat` | 向群聊添加成员 |
 
 > 飞书控制台中任务权限的显示名称可能略有差异，必要时可按关键字 `task` / `tasklist` / `comment` / `attachment` 搜索并授予对应读写权限。
 
@@ -719,6 +765,10 @@ channels:
     groupPolicy: "allowlist"
     # 群聊是否需要 @机器人
     requireMention: true
+    # 免 @ 安全默认策略（requireMention=false 时）：
+    # 仅在群内机器人数量 <= 1 时处理未 @ 的群消息。
+    # 设为 true 可在多 bot 群也放开免 @（需自行承担重复触发风险）。
+    allowMentionlessInMultiBotGroup: false
     # 群聊命令绕过 @ 策略: "never" | "single_bot" | "always"
     # 默认 "single_bot"：仅当群内机器人数量 <= 1 时，允许已授权命令免 @
     groupCommandMentionBypass: "single_bot"
@@ -818,6 +868,19 @@ channels:
 - 同一条消息里如果显式 `@` 了任意用户，则不会触发命令免 `@`。
 - 私聊场景不受该配置影响。
 
+#### 群聊免 @ 行为（`requireMention: false`）
+
+当 `requireMention: false` 时，插件对“未 @ 的群消息”采用安全默认策略：
+
+| `allowMentionlessInMultiBotGroup` | 未 @ 群消息行为 |
+|-----------------------------------|----------------|
+| `false`（默认） | 仅当群里机器人数量不超过 1 个时处理；多 bot 群仍要求显式 `@bot`。 |
+| `true` | 即使在多 bot 群也处理未 @ 消息（仅建议在可接受重复触发风险时启用）。 |
+
+重要说明：
+- 要接收未 @ 的群消息，必须申请并通过 `im:message.group_msg`，且该权限是飞书**敏感权限**。
+- 若未通过该权限，飞书通常只会推送 `@bot` 群消息（`im:message.group_at_msg:readonly`）。
+
 #### 连接模式
 
 支持两种从飞书接收事件的连接模式：
@@ -865,6 +928,14 @@ https://your-domain.com/feishu/events
 | `raw` | 始终纯文本，表格转为 ASCII |
 | `card` | 始终使用卡片，支持语法高亮、表格、链接等 |
 
+#### 群管理限制 ⚠️
+
+> **重要提示：** `delete_chat` 需要机器人是该群的**群主**。如果机器人是以成员身份加入现有群聊（非群主），则无法解散该群聊。
+>
+> 如需解散机器人不拥有的群聊：
+> 1. **群主**将群主权限转让给机器人，或
+> 2. 由群主直接在飞书客户端解散群聊。
+
 #### 动态 Agent 创建（多用户 Workspace 隔离）
 
 启用后，每个私聊用户会自动获得独立的 agent 实例和专属 workspace。这提供完整的隔离，包括独立的对话历史、记忆（MEMORY.md）和工作区文件。
@@ -921,6 +992,8 @@ session:
 - **云空间工具**：列出文件夹、获取文件信息、创建文件夹、移动/删除文件
 - **多维表格工具**：支持多维表格字段与记录的读取/创建/更新/删除，支持 `/base/` 和 `/wiki/` 两种链接格式
 - **任务工具**：基于 Task v2 API 支持任务创建、获取详情、更新和删除
+- **群聊工具**：读写群公告、创建群聊、添加成员、检查机器人是否在群内、删除群聊（`feishu_chat`）
+- **加急通知工具**：发送应用内加急（buzz）、短信、语音电话加急通知（`feishu_urgent`）
 - **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
 - **权限错误提示**：当机器人遇到飞书 API 权限错误时，会自动通知用户并提供权限授权链接
 - **动态 Agent 创建**：每个私聊用户可拥有独立的 agent 实例和专属 workspace（可选）
@@ -947,6 +1020,13 @@ session:
 4. 相关权限是否已申请并审核通过？
 5. 如果使用 webhook 模式：服务是否正在运行？URL 是否公网可访问？
 
+#### 已配置 `requireMention: false`，群里仍然必须 @
+
+请重点检查：
+1. 是否已申请并审核通过 `im:message.group_msg`（敏感权限，接收未 @ 群消息必需）
+2. 群里若有多个 bot，是否显式设置了 `allowMentionlessInMultiBotGroup: true`
+3. `requireMention: false` 是否配置在当前生效的账号/群配置上
+
 #### 返回消息时 403 错误
 
 确保已申请 `im:message:send_as_bot` 权限，并且权限已审核通过。

package/index.ts

@@ -2,12 +2,14 @@ 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 { registerFeishuBitableTools } from "./src/bitable-tools/index.js";
 import { registerFeishuDocTools } from "./src/doc-tools/index.js";
-import { registerFeishuWikiTools } from "./src/wiki-tools/index.js";
 import { registerFeishuDriveTools } from "./src/drive-tools/index.js";
 import { registerFeishuPermTools } from "./src/perm-tools/index.js";
-import { registerFeishuBitableTools } from "./src/bitable-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 { registerFeishuWikiTools } from "./src/wiki-tools/index.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
 export {
@@ -31,6 +33,7 @@ export {
   listReactionsFeishu,
   FeishuEmoji,
 } from "./src/reactions.js";
+export { urgentMessageFeishu, type FeishuUrgentType } from "./src/urgent-tools/index.js";
 export {
   extractMentionTargets,
   extractMessageBody,
@@ -59,6 +62,8 @@ const plugin = {
     registerFeishuPermTools(api);
     registerFeishuBitableTools(api);
     registerFeishuTaskTools(api);
+    registerFeishuChatTools(api);
+    registerFeishuUrgentTools(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1heng-clawd/feishu",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "scripts": {
@@ -56,17 +56,18 @@
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.59.0",
     "@sinclair/typebox": "0.34.48",
+    "https-proxy-agent": "^7.0.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.8",
     "@types/node": "^25.0.10",
-    "openclaw": "2026.2.13",
+    "@vitest/coverage-v8": "^2.1.8",
+    "openclaw": "2026.3.1",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.2.13"
+    "openclaw": ">=2026.3.1"
   }
 }

package/skills/feishu-chat/SKILL.md

@@ -0,0 +1,139 @@
+# Feishu Chat Tool
+
+Feishu chat operations including group announcement reading/writing and group chat management.
+
+## Actions
+
+### Get Announcement Info
+
+```json
+{ "action": "get_announcement_info", "chat_id": "oc_abc123def" }
+```
+
+Returns basic announcement information including type (doc or docx) and metadata.
+
+### Get Full Announcement
+
+```json
+{ "action": "get_announcement", "chat_id": "oc_abc123def" }
+```
+
+Returns complete announcement content. Supports both old (doc) and new (docx) announcement formats.
+
+### List Announcement Blocks
+
+```json
+{ "action": "list_announcement_blocks", "chat_id": "oc_abc123def" }
+```
+
+Returns all blocks for a docx-format announcement.
+
+### Get Single Announcement Block
+
+```json
+{ "action": "get_announcement_block", "chat_id": "oc_abc123def", "block_id": "block_123" }
+```
+
+Returns a single block from the announcement.
+
+### Write Announcement
+
+```json
+{ "action": "write_announcement", "chat_id": "oc_abc123def", "content": "New announcement content" }
+```
+
+For `doc` format: replaces the entire announcement content.
+For `docx` format: appends a new text block under the page root (full replacement is not supported via API; use `update_announcement_block` to edit existing blocks).
+
+### Append Announcement
+
+```json
+{ "action": "append_announcement", "chat_id": "oc_abc123def", "content": "Additional content" }
+```
+
+Appends content to the announcement.
+
+### Update Announcement Block
+
+```json
+{ "action": "update_announcement_block", "chat_id": "oc_abc123def", "block_id": "block_123", "content": "New text content" }
+```
+
+Updates a single block's text content in a docx-format announcement.
+
+---
+
+## Group Chat Management
+
+### Create Group Chat
+
+```json
+{ "action": "create_chat", "name": "My Group", "user_ids": ["ou_123", "ou_456"], "description": "Group description" }
+```
+
+Creates a new group chat with optional initial members and description.
+
+### Add Members to Group
+
+```json
+{ "action": "add_members", "chat_id": "oc_abc123def", "user_ids": ["ou_123", "ou_456"] }
+```
+
+Adds specified users to an existing group chat.
+
+### Check Bot in Chat
+
+```json
+{ "action": "check_bot_in_chat", "chat_id": "oc_abc123def" }
+```
+
+Checks if the bot is a member of the specified chat.
+
+### Delete Chat
+
+```json
+{ "action": "delete_chat", "chat_id": "oc_abc123def" }
+```
+
+Deletes/disbands a group chat. The bot must have appropriate permissions (typically needs to be the group owner or have admin privileges).
+
+**Note**: Deleting a chat will remove all members and the chat history will no longer be accessible. Use with caution.
+
+### Create Session Chat (One-Step)
+
+```json
+{ 
+  "action": "create_session_chat", 
+  "name": "Project Discussion", 
+  "user_ids": ["ou_123", "ou_456"],
+  "greeting": "Hi everyone! Let's discuss the project here.",
+  "description": "Group for project collaboration"
+}
+```
+
+One-step operation that creates a group chat, adds users, and sends a greeting message.
+
+---
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      chat: true  # default: true
+```
+
+## Permissions
+
+Required for announcements:
+- `im:chat.announcement:read` - View group announcement information
+- `im:chat.announcement` - Edit group announcement information (for write operations)
+
+Required for group management:
+- `im:chat:readonly` - Get chat info, check bot membership (`check_bot_in_chat`)
+- `im:chat` - Create and delete group chats (`create_chat`, `delete_chat`)
+- `im:chat.members` - Add members to group chats (`add_members`)
+- `im:message:send_as_bot` - Send messages as bot (for `create_session_chat` greeting)
+
+**Note for delete_chat**: Requires the bot to be the group owner or have admin privileges to disband the chat.

package/skills/feishu-urgent/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: feishu-urgent
+description: |
+  Feishu urgent message (buzz) notifications. Activate when user mentions urgent, buzz, remind, or escalation for messages.
+---
+
+# Feishu Urgent Tool
+
+Single tool `feishu_urgent` for sending urgent (buzz) notifications to recipients for an already-sent message.
+
+## Overview
+
+Urgent notifications (also called "buzz" in Feishu) send a strong push notification to specified recipients. Use this to escalate important messages that require immediate attention.
+
+**Important**: The message must already be sent before sending an urgent notification. You need the `message_id` from a previously sent message.
+
+## Urgency Types
+
+| Type | Description | Cost |
+|------|-------------|------|
+| `app` | In-app buzz notification (popup + sound) | Free |
+| `sms` | SMS push to recipient's phone | May incur cost |
+| `phone` | Voice call to recipient's phone | May incur cost |
+
+## Send App Urgent (Default)
+
+```json
+{
+  "message_id": "om_xxx",
+  "user_ids": ["ou_xxx"],
+  "urgent_type": "app"
+}
+```
+
+## Send SMS Urgent
+
+```json
+{
+  "message_id": "om_xxx",
+  "user_ids": ["ou_xxx"],
+  "urgent_type": "sms"
+}
+```
+
+## Send Phone Call Urgent
+
+```json
+{
+  "message_id": "om_xxx",
+  "user_ids": ["ou_xxx"],
+  "urgent_type": "phone"
+}
+```
+
+## Multiple Recipients
+
+```json
+{
+  "message_id": "om_xxx",
+  "user_ids": ["ou_xxx", "ou_yyy", "ou_zzz"],
+  "urgent_type": "app"
+}
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `message_id` | Yes | Message ID to send urgent notification for (e.g., `om_xxx`). The message must already be sent. |
+| `user_ids` | Yes | List of `open_id` values to buzz. Minimum 1 recipient. Recipients must be members of the chat where the message was sent. |
+| `urgent_type` | No | Urgency delivery method: `app` (default), `sms`, or `phone`. |
+
+## Response
+
+```json
+{
+  "ok": true,
+  "message_id": "om_xxx",
+  "urgent_type": "app",
+  "invalid_user_list": []
+}
+```
+
+- `invalid_user_list`: List of user IDs that could not receive the urgent notification (e.g., not in the chat, or invalid ID).
+
+## Configuration
+
+```yaml
+channels:
+  feishu:
+    tools:
+      urgent: true  # default: true
+```
+
+## Permissions
+
+- `im:message.urgent` - Send in-app urgent notifications
+- `im:message.urgent:sms` - Send SMS urgent notifications (may incur cost)
+- `im:message.urgent:phone` - Send phone call urgent notifications (may incur cost)
+
+## Notes
+
+- **Message must exist**: The `message_id` must be from a message that has already been sent. You cannot send urgent notifications for messages being composed.
+- **Recipients must be chat members**: Users in `user_ids` must be members of the chat where the original message was sent.
+- **Quota limits**: Urgent notifications have quotas (especially `sms` and `phone`). Error `230024` ("Reach the upper limit of urgent message") indicates quota exhausted. Contact your tenant admin or check Feishu admin console > Cost Center > Quota.
+- **Invalid user IDs**: Returns HTTP 400 error if any user_id is invalid (not found or not in the chat).
+- **Cost warning**: `sms` and `phone` types may incur costs on the tenant. Use `app` (default) for free notifications.