@xwang152/claw-lark 0.1.1 → 0.1.2

package/README.md

@@ -1,24 +1,21 @@
-# Lark Plugin for OpenClaw
+# OpenClaw Feishu/Lark Plugin
 
-[中文文档](./README_zh.md)
-
-A channel plugin that enables OpenClaw to communicate via Lark (Larksuite) messaging platform.
+A channel plugin for OpenClaw that enables communication through the Feishu or Lark platform.
 
 ## Features
 
-- **Direct Messages**: Chat with your bot one-on-one
-- **Group Chats**: Add your bot to group conversations
-- **Text Messages**: Send and receive text messages
-- **Image Support**: Bot can send images generated by agents
-- **Webhook Mode**: For individual Lark accounts (tested)
-- **WebSocket Mode**: For enterprise accounts (tested, recommended)
-- **Auto-Recovery**: WebSocket and Webhook servers automatically reconnect/restart on crashes
-
-## Requirements
-
-- OpenClaw installed and configured
-- A Lark Developer account
-- A Lark app with Bot capability enabled
+- **Dual Platform Support**: Full compatibility with Feishu (China) and Lark (International).
+- **WebSocket (Long Connection)**: Recommended for custom apps, low latency, no public IP required.
+- **Webhook Mode**: For traditional deployments, supports event verification and encryption.
+- **Multi-Mode Rendering**: Supports `auto` / `raw` / `card`, with Interactive Cards for Markdown, tables, and highlighting.
+- **Media Support**:
+  - **Inbound**: AI can receive images and files (PDF, Excel, Word, etc.).
+  - **Outbound**: Support for sending images and files.
+- **Advanced Interaction**:
+  - **Typing Indicator**: Simulated via message reactions.
+  - **@ Forwarding**: Automatic handling of @mentions in group chats.
+  - **Contextual Replies**: Support for message threading and replies.
+- **Auto-Recovery**: Automatic reconnection for WebSocket and server restarts for Webhooks.
 
 ## Installation
 
@@ -30,25 +27,9 @@ Install directly via the OpenClaw CLI:
 openclaw plugins install @xwang152/claw-lark
 ```
 
-### 2. Developer Installation (From Source)
+### 2. Restart Gateway
 
-If you want to contribute or modify the code:
-
-```bash
-# Clone the repository
-git clone https://github.com/xwang152-jack/claw-lark.git
-cd claw-lark
-
-# Install dependencies
-npm install
-
-# Install plugin in link mode
-openclaw plugins install --link .
-```
-
-### 3. Restart Gateway
-
-After installation, restart the Gateway to load the plugin:
+Restart the Gateway to load the plugin:
 
 ```bash
 openclaw gateway restart
@@ -60,202 +41,67 @@ Verify installation:
 openclaw plugins list
 ```
 
-You should see `lark` with status `loaded`.
-
-## Lark App Setup
-
-1. Go to [Lark Developer Console](https://open.larksuite.com/app)
-
-2. Create a new app or use an existing one
-
-3. Enable **Bot** capability under App Features
-
-4. Add the following permissions under Permissions & Scopes:
-
-| Permission | Scope | Description |
-| :--- | :--- | :--- |
-| `im:message` | Message | Send and receive messages |
-| `im:message.p2p_msg:readonly` | P2P Message | Read direct messages sent to the bot |
-| `im:message.group_at_msg:readonly` | Group Message | Receive messages where the bot is @mentioned in groups |
-| `im:message:send_as_bot` | Send | Send messages as the bot |
-| `im:resource` | Resource | Upload/download images and files |
-
-**Optional Permissions (add as needed):**
-
-| Permission | Scope | Description |
-| :--- | :--- | :--- |
-| `im:message.group_msg` | Group | Read all group messages (Sensitive permission) |
-| `im:message:readonly` | Read | Get historical messages |
-| `im:message:update` | Edit | Update/edit sent messages |
-| `im:message:recall` | Recall | Recall sent messages |
-| `im:message.reactions:read` | Reaction | View message emoji reactions |
-
-5. Note your **App ID** and **App Secret** from Credentials & Basic Info (you'll need these for configuration)
-
-6. Publish your app under Version Management
+You should see the `feishu` plugin with a `loaded` status.
 
 ## Configuration
 
-### Using Config Commands
-
-```bash
-# Required settings
-openclaw config set channels.lark.accounts.default.appId 'cli_xxxxx'
-openclaw config set channels.lark.accounts.default.appSecret 'your-app-secret'
-openclaw config set channels.lark.accounts.default.connectionMode 'webhook'
-
-# Optional settings
-openclaw config set channels.lark.accounts.default.webhookPort 3000
-openclaw config set channels.lark.accounts.default.domain 'lark'
-openclaw config set channels.lark.accounts.default.dmPolicy 'open'
-openclaw config set channels.lark.accounts.default.groupPolicy 'open'
-openclaw config set channels.lark.accounts.default.groupMentionGated false
-
-# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
-openclaw config set channels.lark.accounts.default.encryptKey 'your-encrypt-key'
-openclaw config set channels.lark.accounts.default.verificationToken 'your-verification-token'
-```
-
-### Using Environment Variables
-
-For the default account, you can use environment variables:
-
-```bash
-LARK_APP_ID=cli_xxxxx
-LARK_APP_SECRET=your-app-secret
-
-# Security settings (from Lark Developer Console > Events & Callbacks > Encryption Strategy)
-LARK_ENCRYPT_KEY=your-encrypt-key          # Optional, for decrypting event payloads
-LARK_VERIFICATION_TOKEN=your-token         # Optional, for verifying request authenticity
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `appId` | string | - | Lark App ID (required) |
-| `appSecret` | string | - | Lark App Secret (required) |
-| `connectionMode` | string | `websocket` | `webhook` or `websocket` |
-| `webhookPort` | number | `3000` | Port for webhook server |
-| `domain` | string | `feishu` | `feishu` (China) or `lark` (international) |
-| `encryptKey` | string | - | Encrypt key for decrypting event payloads (from Events & Callbacks > Encryption Strategy) |
-| `verificationToken` | string | - | Token for verifying request authenticity (from Events & Callbacks > Encryption Strategy) |
-| `dmPolicy` | string | `pairing` | `open`, `pairing`, or `allowlist` |
-| `groupPolicy` | string | `open` | `open`, `allowlist`, or `disabled` |
-| `groupMentionGated` | boolean | `true` | Require @mention in groups |
-
-## Webhook Mode Setup
-
-Choose the setup method based on your deployment environment.
-
-### 1. Development (Using ngrok)
-
-Recommended for local development and testing.
-
-> **Security & Privacy Notice**: ngrok exposes your local server to the internet. Keep the following in mind:
-> - Never share your ngrok URL publicly — anyone with the URL can send requests to your local machine
-> - Use a paid ngrok plan with authentication or IP restrictions for production use
-> - Stop ngrok when not in use to close the tunnel
-> - Consider using Lark's `encryptKey` and `verificationToken` for additional request validation
-
-1. Start ngrok to expose your local webhook server:
-
-```bash
-ngrok http 3000
-```
-
-2. Copy the HTTPS URL from ngrok (e.g., `https://abc123.ngrok.io`)
-
-3. Configure Events & Callbacks in Lark Developer Console:
-   - Add event subscription: `im.message.receive_v1`
-   - Set Request URL to your ngrok HTTPS URL (e.g., `https://abc123.ngrok.io`)
-
-### 2. Production (Server Deployment)
-
-When deploying on a server, ngrok is **not** required.
-
-1. **Open Port**: Ensure your server's firewall (Security Group) allows traffic on the port used by the plugin (default is `3000`).
-2. **Configure URL**: In Lark Developer Console, configure "Events & Callbacks":
-   - Set the "Request URL" to your server's public address: `http://your-server-ip:3000`.
-3. **(Recommended) Reverse Proxy**: Use Nginx or Caddy to set up a reverse proxy with SSL (HTTPS) and forward traffic to port `3000`.
-
-### 3. Start the Plugin
-
-1. Start OpenClaw:
-
-```bash
-openclaw start
-```
-
-2. The webhook server will start automatically and handle URL verification.
-
-## WebSocket Mode
-
-WebSocket mode is available for enterprise Lark accounts (Custom Apps) that support long connections. Set `connectionMode` to `websocket`:
-
-```bash
-openclaw config set channels.lark.accounts.default.connectionMode 'websocket'
-```
-
-**Advantages:**
-- **No Public IP Needed**: No need for ngrok or reverse proxy, suitable for local or intranet environments.
-- **Easy Setup**: Simply enable the "Receive events through persistent connection" toggle in the Lark Developer Console.
-- **High Stability**: The plugin supports automatic reconnection.
-
-**Configuration Steps:**
-1. Go to **Events & Callbacks** in the Lark Developer Console.
-2. Select **Receive events through persistent connection** under "Subscription Mode".
-3. Ensure the `im.message.receive_v1` event is added.
-
-## Multiple Accounts
-
-You can configure multiple Lark accounts:
-
-```bash
-openclaw config set channels.lark.accounts.work.appId 'cli_work_app'
-openclaw config set channels.lark.accounts.work.appSecret 'work-secret'
-openclaw config set channels.lark.accounts.personal.appId 'cli_personal_app'
-openclaw config set channels.lark.accounts.personal.appSecret 'personal-secret'
+### Example Configuration (`openclaw.yaml`)
+
+```yaml
+channels:
+  feishu:
+    accounts:
+      default:
+        enabled: true
+        appId: "cli_a9f722ad2cb9dccb"
+        appSecret: "********"
+        # Domain: "feishu" (China) or "lark" (International)
+        domain: "feishu"
+        # Mode: "websocket" (recommended) or "webhook"
+        connectionMode: "websocket"
+        # Webhook settings (required only for webhook mode)
+        # verificationToken: "********"
+        # encryptKey: "********"
+        # webhookPort: 3000
+        # DM Policy: "pairing" | "open" | "allowlist"
+        dmPolicy: "pairing"
+        # DM allowlist (only when dmPolicy=allowlist, OpenID)
+        # dmAllowlist:
+        #   - "ou_xxx"
+        # Group Policy: "open" | "allowlist" | "disabled"
+        groupPolicy: "allowlist"
+        # Group allowlist (only when groupPolicy=allowlist, ChatID)
+        # groupAllowlist:
+        #   - "oc_xxx"
+        # Require @mention in groups
+        requireMention: true
+        # Max media size (MB, default 30)
+        mediaMaxMb: 30
+        # Rendering mode: "auto" | "raw" | "card"
+        renderMode: "auto"
+        # History limit (default 10)
+        # historyLimit: 10
 ```
 
-## Troubleshooting
-
-### Bot not receiving messages
+### Rendering Modes
 
-1. Verify the event subscription `im.message.receive_v1` is added
-2. Check that the callback URL is correctly configured
-3. Ensure the required permissions are enabled
-4. Make sure the app is published (not just saved as draft)
+| Mode | Description |
+| :--- | :--- |
+| **auto** | (Default) Automatic detection: Use cards for code blocks, lists, or tables, otherwise use plain text. |
+| **raw** | Always use plain text. Tables are converted to ASCII text. |
+| **card** | Always use Feishu Interactive Cards with Markdown syntax highlighting. |
 
-### Permission errors when sending images
-
-Add the `im:resource` permission in Lark Developer Console and republish your app.
-
-### Webhook server not starting
-
-Check if port 3000 is already in use. Change the port:
+## Development
 
 ```bash
-openclaw config set channels.lark.accounts.default.webhookPort 3001
+git clone https://github.com/xwang152-jack/claw-lark.git
+cd claw-lark
+npm install
+npm run typecheck
+openclaw plugins install --link .
 ```
 
-### Connection issues with WebSocket mode
-
-WebSocket mode requires enterprise Lark accounts. If you have an individual account, use webhook mode instead.
-
-## Contributing
-
-Issues and pull requests are welcome! If you encounter bugs or have feature requests, please open an issue at https://github.com/xwang152-jack/claw-lark/issues.
-
-## Automated Publishing (CI/CD)
-
-The project is configured with GitHub Actions. When you push code to the `main` branch, if the version in `package.json` has changed, it will be automatically published to npm.
-
-**Setup Steps:**
-1. Create an **Automation Token** on the npm website.
-2. In your GitHub repository, go to **Settings > Secrets and variables > Actions**.
-3. Add a new Repository secret named `NPM_TOKEN` with your npm token as the value.
-
-## License
-
-MIT
+### Commands
+- `npm run lint`: Lint code
+- `npm run format`: Format code
+- `npm test`: Run tests

package/README_zh.md

@@ -1,22 +1,21 @@
 # OpenClaw 飞书/Lark 插件
 
-这是一个为 OpenClaw 开发的频道插件，使 OpenClaw 能够通过飞书 (Larksuite) 平台进行通信。
+这是一个为 OpenClaw 开发的频道插件，使 OpenClaw 能够通过飞书 (Feishu) 或 Lark 平台进行通信。
 
 ## 功能特性
 
-- **私聊消息**：与您的机器人进行一对一对话
-- **群聊消息**：将机器人加入群组对话
-- **文本消息**：发送和接收文本消息
-- **图片支持**：机器人可以发送由智能体生成的图片
-- **Webhook 模式**：适用于个人飞书账号（已测试）
-- **WebSocket 模式**：适用于企业级账号（已通过测试，推荐使用）
-- **自动恢复**：WebSocket 和 Webhook 服务在崩溃时会自动重连或重启
-
-## 前置要求
-
-- 已安装并配置 OpenClaw
-- 飞书开发者账号
-- 已启用机器人能力的飞书应用
+- **双平台支持**：全面兼容飞书 (国内) 和 Lark (国际)
+- **长连接 (WebSocket)**：企业自建应用推荐使用，低延迟，无需公网 IP
+- **Webhook 模式**：适用于传统部署，支持事件验证和加密
+- **多模式渲染**：支持 `auto` / `raw` / `card` 三种模式，卡片模式支持 Markdown 语法高亮和表格
+- **多媒体支持**：
+  - **进站**：AI 可以接收图片、文件 (PDF, Excel, Word 等)
+  - **出站**：支持发送图片和文件
+- **高级交互**：
+  - **输入指示器**：通过消息表情回复模拟 "正在输入" 状态
+  - **@ 转发**：自动处理群聊中的 @ 提及
+  - **上下文引用**：支持消息引用和回复上下文
+- **自动恢复**：连接中断后自动重连，服务崩溃自动重启
 
 ## 安装步骤
 
@@ -28,23 +27,7 @@
 openclaw plugins install @xwang152/claw-lark
 ```
 
-### 2. 开发者安装（从源码）
-
-如果你想进行二次开发或修改代码：
-
-```bash
-# 克隆仓库
-git clone https://github.com/xwang152-jack/claw-lark.git
-cd claw-lark
-
-# 安装依赖
-npm install
-
-# 以链接模式安装插件
-openclaw plugins install --link .
-```
-
-### 3. 重启 Gateway
+### 2. 重启 Gateway
 
 安装完成后，重启 Gateway 以加载插件：
 
@@ -58,202 +41,83 @@ openclaw gateway restart
 openclaw plugins list
 ```
 
-您应该能看到 `lark` 插件且状态为 `loaded`。
+您应该能看到 `feishu` 插件且状态为 `loaded`。
 
 ## 飞书应用设置
 
 1. 前往 [飞书开放平台](https://open.feishu.cn/app) (国内) 或 [Lark Developer Console](https://open.larksuite.com/app) (国际)
-
-2. 创建新应用或使用现有应用
-
-3. 在“应用能力”中启用 **机器人** 能力
-
-4. 在“权限管理”中添加以下权限：
-
-| 权限 | 范围 | 说明 |
-| :--- | :--- | :--- |
-| `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` | 表情 | 查看消息表情回复 |
-
-5. 从“凭证与基础信息”中获取 **App ID** 和 **App Secret**（配置时需要用到）
-
-6. 在“版本管理与发布”中发布您的应用
+2. 创建新应用，在“应用能力”中启用 **机器人** 能力
+3. 在“权限管理”中添加以下权限：
+   - `im:message` (消息)
+   - `im:message.p2p_msg:readonly` (读取私聊)
+   - `im:message.group_at_msg:readonly` (读取群聊 @ 提及)
+   - `im:message:send_as_bot` (以机器人身份发送消息)
+   - `im:resource` (媒体文件权限)
+   - `im:chat` (群组管理，用于获取群列表)
+   - `contact:user.employee:readonly` (通讯录读取，可选)
+4. 在“版本管理与发布”中发布应用。
 
 ## 配置说明
 
-### 使用配置命令
-
-```bash
-# 必要设置
-openclaw config set channels.lark.accounts.default.appId 'cli_xxxxx'
-openclaw config set channels.lark.accounts.default.appSecret 'your-app-secret'
-openclaw config set channels.lark.accounts.default.connectionMode 'webhook'
-
-# 可选设置
-openclaw config set channels.lark.accounts.default.webhookPort 3000
-openclaw config set channels.lark.accounts.default.domain 'feishu' # 'feishu' (国内) 或 'lark' (国际)
-openclaw config set channels.lark.accounts.default.dmPolicy 'open'
-openclaw config set channels.lark.accounts.default.groupPolicy 'open'
-openclaw config set channels.lark.accounts.default.groupMentionGated false
-
-# 安全设置（从飞书开发者后台 > 事件订阅 > 加密策略获取）
-openclaw config set channels.lark.accounts.default.encryptKey 'your-encrypt-key'
-openclaw config set channels.lark.accounts.default.verificationToken 'your-verification-token'
-```
-
-### 使用环境变量
-
-对于默认账号，您可以使用环境变量：
-
-```bash
-LARK_APP_ID=cli_xxxxx
-LARK_APP_SECRET=your-app-secret
-
-# 安全设置（从飞书开发者后台 > 事件订阅 > 加密策略获取）
-LARK_ENCRYPT_KEY=your-encrypt-key          # 可选，用于解密事件数据
-LARK_VERIFICATION_TOKEN=your-token         # 可选，用于验证请求真实性
-```
-
-### 配置项详情
-
-| 选项 | 类型 | 默认值 | 描述 |
-|--------|------|---------|-------------|
-| `appId` | string | - | 飞书 App ID (必填) |
-| `appSecret` | string | - | 飞书 App Secret (必填) |
-| `connectionMode` | string | `websocket` | `webhook` 或 `websocket` |
-| `webhookPort` | number | `3000` | Webhook 服务器端口 |
-| `domain` | string | `feishu` | `feishu` (国内版) 或 `lark` (国际版) |
-| `encryptKey` | string | - | 加密密钥（从事件订阅 > 加密策略获取） |
-| `verificationToken` | string | - | 验证令牌（从事件订阅 > 加密策略获取） |
-| `dmPolicy` | string | `pairing` | 私聊策略：`open`, `pairing`, 或 `allowlist` |
-| `groupPolicy` | string | `open` | 群聊策略：`open`, `allowlist`, 或 `disabled` |
-| `groupMentionGated` | boolean | `true` | 是否要求在群聊中 @机器人 |
-
-## Webhook 模式设置
-
-根据您的部署环境，选择相应的配置方式。
-
-### 1. 开发环境（使用 ngrok）
-
-推荐在本地开发调试时使用。
-
-> **安全与隐私提示**：ngrok 会将您的本地服务器暴露到公网。请注意：
-> - 不要公开分享您的 ngrok URL
-> - 生产环境建议使用付费版 ngrok 或自建反向代理
-> - 不使用时请关闭 ngrok 隧道
-> - 建议配置飞书的 `encryptKey` 和 `verificationToken` 以增强安全性
-
-1. 启动 ngrok 暴露本地 Webhook 端口：
-
-```bash
-ngrok http 3000
-```
-
-2. 从 ngrok 复制 HTTPS URL（例如：`https://abc123.ngrok.io`）
-
-3. 在飞书开发者后台配置“事件订阅”：
-   - 添加事件：`im.message.receive_v1` (接收消息 v1.0)
-   - 将“请求地址”设置为您的 ngrok HTTPS URL（例如：`https://abc123.ngrok.io`）
-
-### 2. 生产环境（服务器部署）
-
-在服务器上部署时，**不需要**使用 ngrok。
-
-1. **开放端口**：确保您的服务器防火墙（安全组）已开放插件使用的端口（默认是 `3000`）。
-2. **配置地址**：在飞书开发者后台配置“事件订阅”：
-   - 将“请求地址”设置为您的服务器公网地址：`http://您的服务器IP:3000`。
-3. **（推荐）反向代理**：建议使用 Nginx 或 Caddy 配置反向代理和 SSL 证书（HTTPS），然后将流量转发到 `3000` 端口。
-
-### 3. 启动插件
-
-1. 启动 OpenClaw：
-
-```bash
-openclaw start
-```
-
-2. Webhook 服务器会自动启动并处理 URL 验证。
-
-## WebSocket 模式
-
-WebSocket 模式适用于支持长连接的企业级飞书账号（自建应用）。将 `connectionMode` 设置为 `websocket`：
-
-```bash
-openclaw config set channels.lark.accounts.default.connectionMode 'websocket'
-```
-
-**优势：**
-- **无需公网 IP**：不需要配置 ngrok 或反向代理，适合本地或内网环境。
-- **配置简单**：只需在飞书后台开启“使用长连接接收事件”开关即可。
-- **稳定性高**：插件支持自动重连。
-
-**配置步骤：**
-1. 在飞书开发者后台 -> **事件订阅**。
-2. 在“订阅方式”中选择 **使用长连接接收事件**。
-3. 确保已添加 `im.message.receive_v1` 事件。
-
-## 多账号配置
-
-您可以配置多个飞书账号：
-
-```bash
-openclaw config set channels.lark.accounts.work.appId 'cli_work_app'
-openclaw config set channels.lark.accounts.work.appSecret 'work-secret'
-openclaw config set channels.lark.accounts.personal.appId 'cli_personal_app'
-openclaw config set channels.lark.accounts.personal.appSecret 'personal-secret'
+### 配置文件示例 (`openclaw.yaml`)
+
+```yaml
+channels:
+  feishu:
+    accounts:
+      default:
+        enabled: true
+        appId: "cli_a9f722ad2cb9dccb"
+        appSecret: "********"
+        # 域名: "feishu" (国内) 或 "lark" (国际)
+        domain: "feishu"
+        # 连接模式: "websocket" (推荐) 或 "webhook"
+        connectionMode: "websocket"
+        # Webhook 相关 (仅在 webhook 模式需要)
+        # verificationToken: "********"
+        # encryptKey: "********"
+        # webhookPort: 3000
+        # 私聊策略: "pairing" | "open" | "allowlist"
+        dmPolicy: "pairing"
+        # 私聊白名单 (仅 dmPolicy=allowlist 时生效，填写 OpenID)
+        # dmAllowlist:
+        #   - "ou_xxx"
+        # 群聊策略: "open" | "allowlist" | "disabled"
+        groupPolicy: "allowlist"
+        # 群聊白名单 (仅 groupPolicy=allowlist 时生效，填写 ChatID)
+        # groupAllowlist:
+        #   - "oc_xxx"
+        # 群聊是否需要 @机器人
+        requireMention: true
+        # 媒体文件最大大小 (MB, 默认 30)
+        mediaMaxMb: 30
+        # 回复渲染模式: "auto" | "raw" | "card"
+        renderMode: "auto"
+        # 历史消息读取条数 (默认 10)
+        # historyLimit: 10
 ```
 
-## 故障排除
+### 渲染模式说明
 
-### 机器人收不到消息
+| 模式 | 说明 |
+| :--- | :--- |
+| **auto** | (默认) 自动检测：检测到代码块、列表或表格时使用卡片渲染，否则使用纯文本 |
+| **raw** | 始终使用纯文本渲染，表格会被转换为 ASCII 文本 |
+| **card** | 始终使用飞书交互式卡片渲染，支持 Markdown 语法高亮和高级布局 |
 
-1. 检查是否订阅了 `im.message.receive_v1` 事件
-2. 检查回调 URL 是否配置正确且公网可访问
-3. 检查权限是否已开启
-4. 确保应用已发布（不仅是保存草稿）
+## 开发者相关
 
-### 发送图片权限错误
-
-在飞书开发者后台添加 `im:resource` 权限并重新发布应用。
-
-### Webhook 服务器启动失败
-
-检查端口 3000 是否被占用。可以修改端口：
+如果您想参与开发：
 
 ```bash
-openclaw config set channels.lark.accounts.default.webhookPort 3001
+git clone https://github.com/xwang152-jack/claw-lark.git
+cd claw-lark
+npm install
+npm run typecheck
+openclaw plugins install --link .
 ```
 
-### WebSocket 模式连接问题
-
-WebSocket 模式需要企业级飞书账号。如果是个人账号，请使用 Webhook 模式。
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！如果您发现 Bug 或有功能建议，请在 https://github.com/xwang152-jack/claw-lark/issues 提交。
-
-## 自动化发布 (CI/CD)
-
-项目已配置 GitHub Actions。当你将代码推送到 `main` 分支时，如果 `package.json` 中的版本号发生了变化，系统会自动将其发布到 npm。
-
-**配置步骤：**
-1. 在 npm 官网创建一个 **Automation Token**。
-2. 在 GitHub 仓库设置中，进入 **Settings > Secrets and variables > Actions**。
-3. 添加一个新的 Repository secret，名称为 `NPM_TOKEN`，值为你的 npm token。
-
-## 开源协议
-
-MIT
+### 常用命令
+- `npm run lint`: 代码风格检查
+- `npm run format`: 自动格式化代码
+- `npm test`: 运行自动化测试

package/eslint.config.js

@@ -0,0 +1,34 @@
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import prettierConfig from "eslint-config-prettier";
+import prettierPlugin from "eslint-plugin-prettier";
+
+export default [
+  prettierConfig,
+  {
+    files: ["**/*.ts"],
+    ignores: [
+      "**/*.test.ts",
+      "**/*.spec.ts",
+      "src/__tests__/**",
+    ],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      prettier: prettierPlugin,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "no-undef": "off",
+      "prettier/prettier": "error",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+    },
+  },
+];

package/index.ts

@@ -29,9 +29,9 @@ export type {
 } from "./src/types.js";
 
 const plugin = {
-  id: "lark",
-  name: "Lark",
-  description: "Lark (Larksuite) channel plugin for OpenClaw",
+  id: "feishu",
+  name: "Feishu",
+  description: "Feishu / Lark channel plugin for OpenClaw",
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi) {
     setLarkRuntime(api);

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
-  "id": "lark",
-  "channels": ["lark"],
+  "id": "feishu",
+  "channels": ["feishu"],
   "configSchema": {
     "type": "object",
     "properties": {
@@ -12,57 +12,78 @@
             "enabled": {
               "type": "boolean",
               "default": true,
-              "description": "Enable this account"
+              "description": "是否启用此账号"
             },
             "appId": {
               "type": "string",
-              "description": "Lark App ID (cli_xxx)"
+              "description": "飞书应用 App ID (cli_xxx)"
             },
             "appSecret": {
               "type": "string",
-              "description": "Lark App Secret"
+              "description": "飞书应用 App Secret"
             },
             "encryptKey": {
               "type": "string",
-              "description": "Encrypt key for event verification (optional)"
+              "description": "事件解密密钥 (可选)"
             },
             "domain": {
               "type": "string",
               "enum": ["lark", "feishu"],
               "default": "feishu",
-              "description": "API domain: feishu (China) or lark (international)"
+              "description": "API 域名: feishu (国内) 或 lark (国际)"
             },
             "connectionMode": {
               "type": "string",
               "enum": ["websocket", "webhook"],
               "default": "websocket",
-              "description": "Connection mode: websocket (enterprise) or webhook (individual accounts)"
+              "description": "连接模式: websocket (企业自建应用推荐) 或 webhook"
             },
             "verificationToken": {
               "type": "string",
-              "description": "Verification token for webhook events (from Lark app settings)"
+              "description": "事件校验令牌 (用于 Webhook 模式)"
             },
             "webhookPort": {
               "type": "number",
               "default": 3000,
-              "description": "Port for webhook server (webhook mode only)"
+              "description": "Webhook 服务端口"
             },
             "dmPolicy": {
               "type": "string",
               "enum": ["open", "pairing", "allowlist"],
               "default": "pairing",
-              "description": "DM access policy"
+              "description": "私聊策略"
+            },
+            "dmAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "私聊白名单 (OpenID)"
             },
             "groupPolicy": {
               "type": "string",
               "enum": ["open", "allowlist", "disabled"],
               "default": "open",
-              "description": "Group chat access policy"
+              "description": "群聊策略"
+            },
+            "groupAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "群聊白名单 (ChatID)"
             },
-            "groupMentionGated": {
+            "requireMention": {
               "type": "boolean",
               "default": true,
-              "description": "Require @mention in group chats"
+              "description": "群聊是否需要 @ 机器人"
+            },
+            "mediaMaxMb": {
+              "type": "number",
+              "default": 30,
+              "description": "媒体文件最大大小 (MB)"
+            },
+            "renderMode": {
+              "type": "string",
+              "enum": ["auto", "raw", "card"],
+              "default": "auto",
+              "description": "回复渲染模式"
             }
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xwang152/claw-lark",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Lark/Feishu channel plugin for OpenClaw with WebSocket and Webhook support",
   "license": "MIT",
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
-    "lint": "eslint src/**/*.ts index.ts",
+    "lint": "eslint src/**/*.ts index.ts --no-warn-ignored",
     "format": "prettier --write src/**/*.ts index.ts",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/__tests__/sample.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect } from "vitest";
 
 describe("Sample Test", () => {
   it("should work", () => {