Moltbot Feishu Plugin (飞书插件) 🚀

为 Moltbot 打造的飞书 (Feishu/Lark) 通道插件

📖 简介

这是一个 Moltbot 插件，让你可以通过飞书 (Feishu/Lark) 与 AI 对话。支持飞书机器人的所有核心功能。

✨ 特性

• ✅ 支持飞书企业自建应用
• ✅ 支持单聊和群聊
• ✅ 支持文本消息收发
• ✅ 支持图片、文件等富媒体消息
• ✅ 支持卡片消息
• ✅ 支持事件回调
• ✅ 多租户支持（可配置多个飞书应用）
• 🚧 支持飞书开放平台 API（开发中）

🚀 快速开始

前置要求

• Moltbot 已安装并配置
• 飞书开放平台账号
• 已创建飞书企业自建应用

安装

方式 1: 从 npm 安装（推荐）

moltbot plugins install @moltbot-china/feishu

方式 2: 从本地安装（开发）

git clone https://github.com/YOUR_USERNAME/moltbot-china-plugins.git
cd moltbot-china-plugins/feishu
npm install
npm run build
moltbot plugins install .

配置

1. 在飞书开放平台创建应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 获取 App ID 和 App Secret
4. 配置应用权限：
   • im:message - 获取与发送单聊、群组消息
   • im:message.group_at_msg - 获取群组中所有消息
   • im:message.p2p_msg - 读取与用户发给机器人的单聊消息
5. 配置事件订阅：
   • 添加事件：im.message.receive_v1
   • 设置请求地址：https://your-domain.com/webhook/feishu
6. 发布应用版本

2. 配置 Moltbot

编辑 Moltbot 配置文件：

{
  plugins: {
    entries: {
      "feishu": {
        enabled: true,
        config: {
          // 可选：Webhook 路径前缀
          webhookPath: "/webhook/feishu"
        }
      }
    }
  },
  channels: {
    feishu: {
      accounts: {
        default: {
          enabled: true,
          appId: "cli_xxxxxxxxxxxx",
          appSecret: "your_app_secret",
          // 可选：验证 token（用于事件回调验证）
          verificationToken: "your_verification_token",
          // 可选：加密密钥
          encryptKey: "your_encrypt_key"
        }
      }
    }
  },
  gateway: {
    // 确保 Gateway 已配置公网访问
    bind: "0.0.0.0",
    port: 18789
  }
}

3. 配置多个飞书应用（可选）

{
  channels: {
    feishu: {
      accounts: {
        // 第一个应用
        app1: {
          enabled: true,
          appId: "cli_app1_id",
          appSecret: "app1_secret"
        },
        // 第二个应用
        app2: {
          enabled: true,
          appId: "cli_app2_id",
          appSecret: "app2_secret"
        }
      }
    }
  }
}

4. 重启 Moltbot Gateway

moltbot gateway restart

验证安装

# 检查插件状态
moltbot plugins list

# 检查飞书通道状态
moltbot channels status

📚 使用方法

基本对话

在飞书中：

1. 找到你的机器人
2. 在单聊或群聊中 @机器人 发送消息
3. 机器人会使用 AI 回复你

命令

• /help - 显示帮助信息
• /status - 查看机器人状态
• /reset - 重置对话上下文

通过 CLI 发送消息

# 发送文本消息到飞书用户
moltbot message send \
  --channel feishu \
  --to "ou_xxxxxxxxxxxxxxxx" \
  --text "Hello from Moltbot!"

# 发送消息到群组
moltbot message send \
  --channel feishu \
  --to "oc_xxxxxxxxxxxxxxxx" \
  --text "Hello group!"

🔧 开发

项目结构

feishu/
├── README.md                    # 本文件
├── package.json                 # NPM 包配置
├── tsconfig.json               # TypeScript 配置
├── clawdbot.plugin.json        # 插件清单
├── index.ts                     # 插件入口
└── src/
    ├── channel.ts               # 通道实现
    ├── client.ts                # 飞书 API 客户端
    ├── events.ts                # 事件处理
    ├── webhook.ts               # Webhook 服务器
    └── types.ts                 # TypeScript 类型定义

本地开发

# 安装依赖
npm install

# 开发模式（TypeScript watch）
npm run dev

# 构建
npm run build

# 类型检查
npm run type-check

# 测试
npm test

# Lint
npm run lint

调试

启用详细日志：

{
  logging: {
    level: "debug",
    filters: {
      "feishu": "debug"
    }
  }
}

🛠️ API 文档

配置项

Plugin Config (plugins.entries.feishu.config)

| 字段 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | webhookPath | string | ❌ | /webhook/feishu | Webhook 路径 |

Channel Config (channels.feishu.accounts.<accountId>)

| 字段 | 类型 | 必填 | 默认值 | 描述 | |------|------|------|--------|------| | enabled | boolean | ✅ | - | 是否启用此账号 | | appId | string | ✅ | - | 飞书应用 ID | | appSecret | string | ✅ | - | 飞书应用密钥 | | verificationToken | string | ❌ | - | 事件验证 Token | | encryptKey | string | ❌ | - | 消息加密密钥 |

🐛 故障排查

问题：机器人收不到消息

解决方案：

1. 检查应用权限是否正确配置
2. 确认事件订阅地址正确且可访问
3. 检查 Gateway 是否有公网访问
4. 查看 Moltbot 日志：moltbot gateway logs

问题：机器人无法发送消息

解决方案：

1. 检查 appId 和 appSecret 是否正确
2. 确认应用已发布并启用
3. 检查用户 ID 或群组 ID 是否正确

问题：事件回调验证失败

解决方案：

1. 确认 verificationToken 配置正确
2. 检查 Webhook 路径是否匹配
3. 查看详细日志排查问题

📝 相关资源

• 飞书开放平台文档
• 飞书机器人开发指南
• Moltbot 官方文档
• Moltbot 插件开发文档

🤝 贡献

欢迎贡献代码！请查看 贡献指南。

📄 许可证

MIT License - 详见 LICENSE 文件

💬 支持

• 提交 Issue: GitHub Issues
• 讨论: GitHub Discussions