@bundy-lmw/hive-plugin-feishu 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bundy-lmw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @bundy-lmw/hive-plugin-feishu
+
+飞书消息通道插件，基于 `@larksuiteoapi/node-sdk` 实现。
+
+## 功能
+
+- ✅ 接收飞书消息事件（通过 Webhook）
+- ✅ 发送文本消息
+- ✅ 发送卡片消息
+- ✅ 发送 Markdown 消息
+- ✅ 回复消息
+- ✅ 多租户支持（多个飞书应用）
+- ✅ 签名验证
+- ✅ Challenge 响应
+
+## 安装
+
+```bash
+pnpm add @bundy-lmw/hive-plugin-feishu
+```
+
+## 配置
+
+在 `hive.config.json` 中添加插件配置：
+
+```json
+{
+  "plugins": {
+    "@bundy-lmw/hive-plugin-feishu": {
+      "apps": [
+        {
+          "appId": "${FEISHU_APP_ID}",
+          "appSecret": "${FEISHU_APP_SECRET}"
+        }
+      ]
+    }
+  }
+}
+```
+
+### 环境变量
+
+```bash
+# .env - 必需
+FEISHU_APP_ID=cli_xxxxxx
+FEISHU_APP_SECRET=xxxxxx
+
+# 可选（用于签名验证）
+# FEISHU_ENCRYPT_KEY=xxxxxx
+# FEISHU_VERIFY_TOKEN=xxxxxx
+```
+
+### 多租户配置
+
+```json
+{
+  "plugins": {
+    "@bundy-lmw/hive-plugin-feishu": {
+      "apps": [
+        {
+          "appId": "${FEISHU_APP_ID_1}",
+          "appSecret": "${FEISHU_APP_SECRET_1}"
+        },
+        {
+          "appId": "${FEISHU_APP_ID_2}",
+          "appSecret": "${FEISHU_APP_SECRET_2}"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Webhook 配置
+
+### 1. 飞书开放平台权限配置
+
+在飞书开放平台 → 应用 → 权限管理中开通以下权限：
+
+| 权限 | 说明 |
+|------|------|
+| `im:message` | 获取与发送单聊、群组消息 |
+| `im:message:send_as_bot` | 以应用身份发消息 |
+| `im:chat` | 获取群组信息 |
+| `im:chat:readonly` | 获取群组列表 |
+
+### 2. 事件订阅
+
+在飞书开放平台 → 应用 → 事件订阅中配置：
+
+```
+https://your-server.com/webhook/feishu/{appId}
+```
+
+订阅事件：
+- `im.message.receive_v1` - 接收消息
+
+### 3. 机器人能力
+
+在飞书开放平台 → 应用 → 机器人配置中：
+- 启用机器人
+- 配置消息卡片（可选）
+
+## 消息格式
+
+### 接收消息
+
+插件会将飞书消息转换为通用 `ChannelMessage` 格式：
+
+```typescript
+interface ChannelMessage {
+  id: string           // 消息 ID
+  content: string      // 消息内容
+  type: 'text' | 'image' | 'file' | 'card' | 'markdown'
+  from: {
+    id: string         // 发送者 ID
+    type: 'user'
+  }
+  to: {
+    id: string         // 群聊 ID
+    type: 'group'
+  }
+  timestamp: number    // 时间戳（毫秒）
+  raw: unknown         // 原始飞书事件
+}
+```
+
+### 发送消息
+
+```typescript
+// 获取通道
+const channel = plugin.getChannelByAppId('cli_xxxxxx')
+
+// 发送文本消息
+await channel.send({
+  to: 'oc_xxxxxx',      // 群聊 ID
+  content: 'Hello!',
+  type: 'text'
+})
+
+// 发送 Markdown 消息
+await channel.send({
+  to: 'oc_xxxxxx',
+  content: '# Title\n\n**Bold text**',
+  type: 'markdown'
+})
+
+// 发送卡片消息
+await channel.send({
+  to: 'oc_xxxxxx',
+  content: JSON.stringify({
+    type: 'template',
+    data: {
+      template_id: 'xxxxx'
+    }
+  }),
+  type: 'card'
+})
+```
+
+## 事件
+
+插件通过 MessageBus 发布以下事件：
+
+| 事件 | 描述 |
+|------|------|
+| `channel:feishu:{appId}:message:received` | 收到飞书消息 |
+
+## 开发
+
+```bash
+# 构建
+pnpm build
+
+# 监视模式
+pnpm dev
+
+# 测试
+pnpm test
+```
+
+## GitHub
+
+[https://github.com/1695365384/hive](https://github.com/1695365384/hive)
+
+## 许可证
+
+MIT

package/dist/channel.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @bundy-lmw/hive-plugin-feishu - FeishuChannel
+ *
+ * 飞书通道实现，基于 @larksuiteoapi/node-sdk。
+ * 支持 WebSocket 长连接模式（推荐）和 Webhook 模式（备用）。
+ */
+import * as lark from '@larksuiteoapi/node-sdk';
+import type { ChannelCapabilities, ChannelSendOptions, ChannelSendResult, IMessageBus, ILogger } from '@bundy-lmw/hive-core';
+import type { FeishuAppConfig, IFeishuChannel } from './types.js';
+/**
+ * 飞书通道实现
+ */
+export declare class FeishuChannel implements IFeishuChannel {
+    readonly id: string;
+    readonly name: string;
+    readonly type = "feishu";
+    readonly appId: string;
+    readonly capabilities: ChannelCapabilities;
+    /** HTTP API 客户端，用于发送消息 */
+    private client;
+    /** WebSocket 客户端，用于接收事件 */
+    private wsClient;
+    /** 事件分发器 */
+    private dispatcher;
+    private messageBus;
+    private logger;
+    private config;
+    /** 文件接收存储目录 */
+    private readonly receivedDir;
+    constructor(config: FeishuAppConfig, messageBus: IMessageBus, logger: ILogger, workspaceDir?: string | null);
+    /**
+     * 获取飞书 HTTP API Client
+     */
+    getClient(): lark.Client;
+    /**
+     * 启动通道 — 建立 WebSocket 长连接
+     */
+    start(): Promise<void>;
+    /**
+     * 停止通道 — 关闭 WebSocket 连接
+     */
+    stop(): Promise<void>;
+    /**
+     * 发送消息
+     */
+    send(options: ChannelSendOptions): Promise<ChannelSendResult>;
+    /**
+     * 回复消息
+     */
+    reply(messageId: string, options: ChannelSendOptions): Promise<ChannelSendResult>;
+    /**
+     * 处理 Webhook 请求（Webhook 模式备用）
+     */
+    handleWebhook(body: unknown, signature: string, timestamp: string, nonce: string): Promise<unknown>;
+    /**
+     * 处理 WebSocket 接收到的消息事件
+     */
+    private handleWSMessageEvent;
+    /**
+     * 转换 WebSocket 事件数据为通用消息格式
+     */
+    private convertWSMessage;
+    /**
+     * 处理 Webhook 消息事件
+     */
+    private handleWebhookMessageEvent;
+    /**
+     * 转换 Webhook 消息为通用格式
+     */
+    private convertWebhookMessage;
+    /**
+     * 从飞书 interactive card JSON 中提取纯文本
+     *
+     * 卡片结构: { header: { title: { content } }, elements: [{ tag: "div", text: { content } }] }
+     */
+    private extractCardText;
+    /**
+     * 递归提取 elements 数组中的文本内容
+     */
+    private extractElementsText;
+    /**
+     * 从飞书 post JSON 中提取纯文本
+     *
+     * Post 结构: { zh_cn: { title, content: [{ tag: "text", text: "..." }] } }
+     */
+    private extractPostText;
+    /**
+     * 将 Markdown 文本构建为飞书 interactive card JSON
+     *
+     * 使用 lark_md tag 让卡片内支持 Markdown 渲染
+     */
+    private buildCardContent;
+    /**
+     * 图片扩展名集合
+     */
+    private static readonly IMAGE_EXTENSIONS;
+    /**
+     * 根据文件扩展名推断发送类型
+     */
+    private resolveSendType;
+    /**
+     * 上传文件到飞书
+     *
+     * @returns file_key
+     */
+    private uploadFile;
+    /**
+     * 上传图片到飞书
+     *
+     * @returns image_key
+     */
+    private uploadImage;
+    /**
+     * 下载文件并保存到本地
+     *
+     * @returns 本地文件路径，失败时返回 null
+     */
+    private downloadFile;
+    /**
+     * 下载图片并保存到本地
+     *
+     * @returns 本地文件路径，失败时返回 null
+     */
+    private downloadImage;
+    /**
+     * 发送文件消息（上传 + 发送）
+     */
+    private sendFileMessage;
+    /**
+     * 发送图片消息（上传 + 发送）
+     */
+    private sendImageMessage;
+    /**
+     * 回复文件消息（上传 + 回复）
+     */
+    private replyFileMessage;
+    /**
+     * 回复图片消息（上传 + 回复）
+     */
+    private replyImageMessage;
+    /**
+     * 验证飞书签名
+     */
+    private verifySignature;
+    /**
+     * 处理接收到的图片消息，下载并返回本地路径
+     */
+    private handleReceiveImage;
+    /**
+     * 处理接收到的文件消息，下载并返回本地路径
+     */
+    private handleReceiveFile;
+    /**
+     * 构建消息内容
+     */
+    private buildContent;
+    /**
+     * 映射消息类型（发送时）
+     */
+    private mapMessageType;
+    /**
+     * 映射到通用消息类型（接收时）
+     */
+    private mapToMessageType;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAI/C,OAAO,KAAK,EAEV,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,OAAO,EAER,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EACV,eAAe,EAIf,cAAc,EACf,MAAM,YAAY,CAAA;AASnB;;GAEG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,YAAW;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CASzC;IAED,0BAA0B;IAC1B,OAAO,CAAC,MAAM,CAAa;IAC3B,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAe;IAC/B,YAAY;IACZ,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAiB;IAC/B,eAAe;IACf,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;gBAExB,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IA2C3G;;OAEG;IACH,SAAS,IAAI,IAAI,CAAC,MAAM;IAIxB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4CnE;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2CvF;;OAEG;IACG,aAAa,CACjB,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC;IA6BnB;;OAEG;YACW,oBAAoB;IAYlC;;OAEG;YACW,gBAAgB;IAqD9B;;OAEG;YACW,yBAAyB;IAYvC;;OAEG;YACW,qBAAqB;IAyCnC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2B3B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA0BvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAEtC;IAEF;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;;;OAIG;YACW,UAAU;IAwBxB;;;;OAIG;YACW,WAAW;IAoBzB;;;;OAIG;YACW,YAAY;IAoB1B;;;;OAIG;YACW,aAAa;IAmB3B;;OAEG;YACW,eAAe;IAuB7B;;OAEG;YACW,gBAAgB;IAuB9B;;OAEG;YACW,gBAAgB;IAsB9B;;OAEG;YACW,iBAAiB;IAsB/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAoBvB;;OAEG;YACW,kBAAkB;IAahC;;OAEG;YACW,iBAAiB;IAc/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAYpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAazB"}