npm - @xwang152/claw-lark - Versions diffs - 0.1.0 → 0.1.2 - Mend

@xwang152/claw-lark 0.1.0 → 0.1.2

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 (10) hide show

package/.eslintrc.json +18 -0
package/.github/workflows/npm-publish.yml +39 -0
package/.prettierrc +7 -0
package/README.md +74 -209
package/README_zh.md +84 -201
package/eslint.config.js +34 -0
package/index.ts +3 -3
package/openclaw.plugin.json +35 -14
package/package.json +16 -3
package/src/__tests__/sample.test.ts +7 -0

package/.eslintrc.json ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "plugins": ["@typescript-eslint", "prettier"],
+  "rules": {
+    "prettier/prettier": "error",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  }
+}

package/.github/workflows/npm-publish.yml ADDED Viewed

@@ -0,0 +1,39 @@
+name: Node.js Package Publish
+on:
+  push:
+    branches:
+      - main
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm install
+      - name: Check if version exists on npm
+        id: check_version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          NAME=$(node -p "require('./package.json').name")
+          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
+            echo "Version $VERSION already exists on npm. Skipping publish."
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version $VERSION is new. Proceeding to publish."
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+      - name: Publish to npm
+        if: steps.check_version.outputs.exists == 'false'
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc ADDED Viewed

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/README.md CHANGED Viewed

@@ -1,46 +1,37 @@
-# 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
-```bash
-# Clone the repository
-git clone https://github.com/xwang152-jack/claw-lark.git
-cd claw-lark
-# Install dependencies
-npm install
-# Install plugin into OpenClaw
-openclaw plugins install --link .
-```
+### 1. Automatic Installation (Recommended)
-Or install directly via npm:
+Install directly via the OpenClaw CLI:
 ```bash
 openclaw plugins install @xwang152/claw-lark
 ```
-Verify installation:Restart Gateway to load the plugin
+### 2. Restart Gateway
+Restart the Gateway to load the plugin:
+```bash
 openclaw gateway restart
 ```
@@ -50,193 +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
+### 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
 ```
-### 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.
+### Rendering Modes
-### 1. Development (Using ngrok)
+| 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. |
-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:
+## Development
 ```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'
-```
-## Troubleshooting
-### Bot not receiving messages
-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)
-### 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:
-```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.
-## License
-MIT
+### Commands
+- `npm run lint`: Lint code
+- `npm run format`: Format code
+- `npm test`: Run tests

package/README_zh.md CHANGED Viewed

@@ -1,44 +1,37 @@
 # 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 等)
+  - **出站**：支持发送图片和文件
+- **高级交互**：
+  - **输入指示器**：通过消息表情回复模拟 "正在输入" 状态
+  - **@ 转发**：自动处理群聊中的 @ 提及
+  - **上下文引用**：支持消息引用和回复上下文
+- **自动恢复**：连接中断后自动重连，服务崩溃自动重启
 ## 安装步骤
-```bash
-# 克隆仓库
-git clone https://github.com/xwang152-jack/claw-lark.git
-cd claw-lark
-# 安装依赖
-npm install
-# 将插件安装到 OpenClaw
-openclaw plugins install --link .
-```
+### 1. 自动安装（推荐）
-或者直接通过 npm 安装：
+直接通过 OpenClaw 命令行工具安装：
 ```bash
 openclaw plugins install @xwang152/claw-lark
 ```
-验证安装：# 重启 Gateway 以加载插件
+### 2. 重启 Gateway
+安装完成后，重启 Gateway 以加载插件：
+```bash
 openclaw gateway restart
 ```
@@ -48,193 +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         # 可选，用于验证请求真实性
+### 配置文件示例 (`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
 ```
-### 配置项详情
+### 渲染模式说明
-| 选项 | 类型 | 默认值 | 描述 |
-|--------|------|---------|-------------|
-| `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` | 是否要求在群聊中 @机器人 |
+| 模式 | 说明 |
+| :--- | :--- |
+| **auto** | (默认) 自动检测：检测到代码块、列表或表格时使用卡片渲染，否则使用纯文本 |
+| **raw** | 始终使用纯文本渲染，表格会被转换为 ASCII 文本 |
+| **card** | 始终使用飞书交互式卡片渲染，支持 Markdown 语法高亮和高级布局 |
-## 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'
-```
-## 故障排除
-### 机器人收不到消息
-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 提交。
-## 开源协议
-MIT
+### 常用命令
+- `npm run lint`: 代码风格检查
+- `npm run format`: 自动格式化代码
+- `npm test`: 运行自动化测试

package/eslint.config.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@xwang152/claw-lark",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Lark/Feishu channel plugin for OpenClaw with WebSocket and Webhook support",
   "license": "MIT",
@@ -26,7 +26,12 @@
     ]
   },
   "scripts": {
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src/**/*.ts index.ts --no-warn-ignored",
+    "format": "prettier --write src/**/*.ts index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.37.0"
@@ -36,7 +41,15 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
     "openclaw": "^2026.1.29",
-    "typescript": "^5.0.0"
+    "prettier": "^3.8.1",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
   }
 }

package/src/__tests__/sample.test.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import { describe, it, expect } from "vitest";
+describe("Sample Test", () => {
+  it("should work", () => {
+    expect(1 + 1).toBe(2);
+  });
+});