npm - @superbenxxxh/feishu - Versions diffs - 2.0.0 → 3.0.0 - Mend

@superbenxxxh/feishu 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md CHANGED Viewed

@@ -1,339 +1,440 @@
-# clawd-feishu
-Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
-[English](#english) | [中文](#中文)
----
-## English
-### Installation
-```bash
-openclaw plugins install @m1heng-clawd/feishu
-```
-Or install via npm:
-```bash
-npm install @m1heng-clawd/feishu
-```
-### 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 event subscriptions** (see below) ⚠️ Important
-5. Configure the plugin:
-#### Required Permissions
-| Permission | Scope | Description |
-|------------|-------|-------------|
-| `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
-| Permission | Scope | Description |
-|------------|-------|-------------|
-| `im:message.group_msg` | Group | Read all group messages (sensitive) |
-| `im:message:readonly` | Read | Get message history |
-| `im:message:update` | Edit | Update/edit sent messages |
-| `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
-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
-```yaml
-channels:
-  feishu:
-    enabled: true
-    appId: "cli_xxxxx"
-    appSecret: "secret"
-    # Domain: "feishu" (China) or "lark" (International)
-    domain: "feishu"
-    # Connection mode: "websocket" (recommended) or "webhook"
-    connectionMode: "websocket"
-    # DM policy: "pairing" | "open" | "allowlist"
-    dmPolicy: "pairing"
-    # Group policy: "open" | "allowlist" | "disabled"
-    groupPolicy: "allowlist"
-    # Require @mention in groups
-    requireMention: true
-    # Max media size in MB (default: 30)
-    mediaMaxMb: 30
+# clawdbot-feishu
+Feishu/Lark (飞书) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw).
+This fork adds:
+- Better Markdown rendering (post/card modes + auto detection)
+- Feishu Docs / Drive / Wiki / Permission tools
+- Built-in skills to guide tool usage
+[English](#english) | [中文](#中文)
+---
+## English
+### Installation
+```bash
+openclaw plugins install @superbenxxxh/feishu
+```
+Or install via npm:
+```bash
+npm install @superbenxxxh/feishu
+```
+Local dev install:
+```bash
+openclaw plugins install .
+```
+### 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 event subscriptions** (see below) ⚠️ Important
+5. Configure the plugin
+#### Required Permissions (Messaging)
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `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 (Messaging)
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `im:message.group_msg` | Group | Read all group messages (sensitive) |
+| `im:message:readonly` | Read | Get message history |
+| `im:message:update` | Edit | Update/edit sent messages |
+| `im:message:recall` | Recall | Recall sent messages |
+| `im:message.reactions:read` | Reactions | View message reactions |
+#### Optional Permissions (Docs / Drive / Wiki)
+| Feature | Required Permissions |
+|---------|----------------------|
+| Feishu Docs (`feishu_doc`) | `docx:document`, `docx:document:readonly`, `docx:document.block:convert`, `drive:drive` |
+| Feishu Drive (`feishu_drive`) | `drive:drive` (full) or `drive:drive:readonly` (read only) |
+| Feishu Wiki (`feishu_wiki`) | `wiki:wiki` or `wiki:wiki:readonly` |
+| Permissions tool (`feishu_perm`) | `drive:permission` |
+#### 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
+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
+```yaml
+channels:
+  feishu:
+    enabled: true
+    appId: "cli_xxxxx"
+    appSecret: "secret"
+    # Domain: "feishu" (China) or "lark" (International)
+    domain: "feishu"
+    # Connection mode: "websocket" (recommended) or "webhook"
+    connectionMode: "websocket"
+    # DM policy: "pairing" | "open" | "allowlist"
+    dmPolicy: "pairing"
+    # Group policy: "open" | "allowlist" | "disabled"
+    groupPolicy: "allowlist"
+    # Require @mention in groups
+    requireMention: true
+    # Max media size in MB (default: 30)
+    mediaMaxMb: 30
     # Render mode for bot replies: "post" | "auto" | "raw" | "card"
     renderMode: "post"
-```
-#### Render Mode
+    # Tool toggles
+    tools:
+      doc: true
+      wiki: true
+      drive: true
+      perm: false
+      scopes: true
+```
+#### Render Mode
 | Mode | Description |
 |------|-------------|
 | `post` | (Default) Send replies as rich text posts using `msg_type=post` + `tag=md`. |
 | `auto` | Automatically detect: use card for messages with code blocks or tables, plain text otherwise. |
 | `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
-- WebSocket and Webhook connection modes
-- Direct messages and group chats
-- Message replies and quoted message context
-- **Inbound media support**: AI can see images, read files (PDF, Excel, etc.), and process rich text with embedded images
-- Image and file uploads (outbound)
-- Typing indicator (via emoji reactions)
-- Pairing flow for DM approval
-- User and group directory lookup
-- **Card render mode**: Optional markdown rendering with syntax highlighting
-- **@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
-#### 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 `openclaw plugins install` fails, install manually:
-```bash
-# 1. Download the package
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
-# 2. Install from local file
-openclaw plugins install ./feishu-0.1.3.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
-openclaw 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
-openclaw config set channels.feishu.appId "cli_xxxxx"
-openclaw config set channels.feishu.appSecret "your_app_secret"
-openclaw 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
+### Tools & Skills
+This plugin registers tools and ships built-in skills (loaded via `openclaw.plugin.json`) so the model can use them reliably:
+| Tool | Purpose |
+|------|---------|
+| `feishu_doc` | Read/write Feishu Docs (docx), append content, list/update/delete blocks |
+| `feishu_drive` | List/move/delete files and folders in Feishu Drive |
+| `feishu_wiki` | Browse and manage wiki spaces/nodes |
+| `feishu_perm` | Manage file/document permissions (disabled by default) |
+| `feishu_app_scopes` | Inspect granted app scopes |
+Notes:
+- Wiki content is edited via `feishu_doc` (wiki → get node → use `obj_token` as doc token).
+- Feishu Docs do **not** support Markdown tables via the convert API.
+- Drive root folder may be unavailable to bots; share a folder with the bot first, then operate inside it.
+### Features
+- WebSocket and Webhook connection modes
+- Direct messages and group chats
+- Message replies and quoted message context
+- **Inbound media support**: AI can see images, read files (PDF, Excel, etc.), and process rich text with embedded images
+- Image and file uploads (outbound)
+- Typing indicator (via emoji reactions)
+- Pairing flow for DM approval
+- User and group directory lookup
+- **Card render mode**: Optional markdown rendering with syntax highlighting
+- **@mention forwarding**: When you @mention someone in your message, the bot's reply will automatically @mention them too
+- **Cloud docs & wiki tools**: Read/write docx, navigate wiki, manage drive
+#### @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
+#### 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.
+#### Drive actions fail with 400 or empty root
+Bots do not have a personal root folder. Share a folder with the bot, then operate inside that folder.
+#### Docx write cannot create tables
+The docx convert API does not support Markdown tables. Use plain lists or manual tables instead.
+#### 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 `openclaw plugins install` fails, install manually:
+```bash
+# 1. Download the package
+curl -O https://registry.npmjs.org/@superbenxxxh/feishu/-/feishu-VERSION.tgz
+# 2. Install from local file
+openclaw plugins install ./feishu-VERSION.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
+openclaw plugins install @superbenxxxh/feishu
+```
+或通过 npm 安装：
+```bash
+npm install @superbenxxxh/feishu
+```
+本地开发安装：
+```bash
+openclaw plugins install .
+```
+### 配置
+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` | 表情 | 查看消息表情回复 |
+#### 可选权限（文档 / 云盘 / 知识库）
+| 功能 | 所需权限 |
+|------|-----------|
+| 文档工具 `feishu_doc` | `docx:document`, `docx:document:readonly`, `docx:document.block:convert`, `drive:drive` |
+| 云盘工具 `feishu_drive` | `drive:drive`（读写）或 `drive:drive:readonly`（只读） |
+| 知识库工具 `feishu_wiki` | `wiki:wiki` 或 `wiki:wiki:readonly` |
+| 权限工具 `feishu_perm` | `drive:permission` |
+#### 事件订阅 ⚠️
+> **这是最容易遗漏的配置！** 如果机器人能发消息但收不到消息，请检查此项。
+在飞书开放平台的应用后台，进入 **事件与回调** 页面：
+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
+openclaw config set channels.feishu.appId "cli_xxxxx"
+openclaw config set channels.feishu.appSecret "your_app_secret"
+openclaw 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
     # 回复渲染模式: "post" | "auto" | "raw" | "card"
     renderMode: "post"
-```
-#### 渲染模式
+    # 工具开关
+    tools:
+      doc: true
+      wiki: true
+      drive: true
+      perm: false
+      scopes: true
+```
+#### 渲染模式
 | 模式 | 说明 |
 |------|------|
 | `post` | （默认）使用富文本 post（`msg_type=post` + `tag=md`）。 |
 | `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`
-如果 `openclaw plugins install` 失败，可以手动安装：
-```bash
-# 1. 下载插件包
-curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
-# 2. 从本地安装
-openclaw plugins install ./feishu-0.1.3.tgz
-```
-#### 在飞书里找不到机器人
-1. 确保应用已发布（至少发布到测试版本）
-2. 在飞书搜索框中搜索机器人名称
-3. 检查应用可用范围是否包含你的账号
----
-## License
+### 工具与技能
+插件注册了工具，并自带技能说明（通过 `openclaw.plugin.json` 加载），模型可更稳定调用：
+| 工具 | 作用 |
+|------|------|
+| `feishu_doc` | 读写飞书文档（docx），追加内容，列出/更新/删除块 |
+| `feishu_drive` | 云盘文件/文件夹浏览、移动、删除 |
+| `feishu_wiki` | 知识库空间与节点管理 |
+| `feishu_perm` | 文件/文档权限管理（默认关闭） |
+| `feishu_app_scopes` | 查看应用权限范围 |
+说明：
+- 知识库页面内容通过 `feishu_doc` 读写（先 wiki get 获取 `obj_token`）。
+- docx 转换 API **不支持 Markdown 表格**。
+- 机器人没有“我的空间”根目录，需要先共享一个文件夹给机器人。
+### 功能
+- WebSocket 和 Webhook 连接模式
+- 私聊和群聊
+- 消息回复和引用上下文
+- **入站媒体支持**：AI 可以看到图片、读取文件（PDF、Excel 等）、处理富文本中的嵌入图片
+- 图片和文件上传（出站）
+- 输入指示器（通过表情回复实现）
+- 私聊配对审批流程
+- 用户和群组目录查询
+- **卡片渲染模式**：支持语法高亮的 Markdown 渲染
+- **@ 转发功能**：在消息中 @ 某人，机器人的回复会自动 @ 该用户
+- **文档 / 云盘 / 知识库工具**：读写 docx、浏览知识库、管理云盘
+#### @ 转发功能
+如果你希望机器人的回复中 @ 某人，只需在你的消息中 @ 他们：
+- **私聊**：`@张三 跟他问好` → 机器人回复 `@张三 你好！`
+- **群聊**：`@机器人 @张三 跟他问好` → 机器人回复 `@张三 你好！`
+机器人会自动检测消息中的 @ 并在回复时带上。无需额外权限。
+### 常见问题
+#### 机器人收不到消息
+检查以下配置：
+1. 是否配置了 **事件订阅**？（见上方事件订阅章节）
+2. 事件配置方式是否选择了 **长连接**？
+3. 是否添加了 `im.message.receive_v1` 事件？
+4. 相关权限是否已申请并审核通过？
+#### 返回消息时 403 错误
+确保已申请 `im:message:send_as_bot` 权限，并且权限已审核通过。
+#### 云盘操作 400 或根目录为空
+机器人没有个人根目录。请先共享一个文件夹给机器人，再在该文件夹内操作。
+#### 文档写入不支持表格
+docx 转换 API 不支持 Markdown 表格。请使用列表或手动表格。
+#### 如何清理历史会话 / 开启新对话
+在聊天中发送 `/new` 命令即可开启新对话。
+#### 消息为什么不是流式输出
+飞书 API 有请求频率限制，流式更新消息很容易触发限流。当前采用完整回复后一次性发送的方式，以保证稳定性。
+#### Windows 安装报错 `spawn npm ENOENT`
+如果 `openclaw plugins install` 失败，可以手动安装：
+```bash
+# 1. 下载插件包
+curl -O https://registry.npmjs.org/@superbenxxxh/feishu/-/feishu-VERSION.tgz
+# 2. 从本地安装
+openclaw plugins install ./feishu-VERSION.tgz
+```
+#### 在飞书里找不到机器人
+1. 确保应用已发布（至少发布到测试版本）
+2. 在飞书搜索框中搜索机器人名称
+3. 检查应用可用范围是否包含你的账号
+---
+## License
 MIT