@colinlu50/openclaw-lark-stream 2026.3.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lark Technologies Pte. Ltd.
+
+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,141 @@
+[English](#english) | [中文](#中文)
+
+---
+
+<a id="english"></a>
+
+# OpenClaw Lark/Feishu Plugin — Stream Card Fork
+
+Fork of the official [openclaw-larksuite](https://github.com/larksuite/openclaw-larksuite) plugin with **streaming block output** and **tool call indicators**.
+
+## What's Changed
+
+The official plugin delivers LLM block results all at once after completion. This fork enables:
+
+- **Real-time block streaming** — each block's content is progressively appended to the streaming card as it's generated
+- **Tool call indicators** — when the agent calls a tool, the card shows tool call status in real-time
+
+### Modified Files
+
+- `src/card/reply-dispatcher.ts` — enable block streaming in streaming card mode; wire `onToolStart` callback
+- `src/card/streaming-card-controller.ts` — append each delivered block to the card in real-time; add `onToolStart()` to display tool call status
+- `src/card/builder.ts` — collapsible panel for tool call summary in completed cards
+
+## Installation
+
+Requires [OpenClaw](https://openclaw.ai) (>= 2026.2.26) and Node.js (>= v22).
+
+### Option A: npm install (recommended)
+
+If you've never installed the official Feishu plugin, install the official one first to complete the guided setup:
+
+```bash
+npx -y @larksuite/openclaw-lark install
+```
+
+Then replace with the stream fork:
+
+```bash
+npx -y @colinlu50/openclaw-lark-stream install
+```
+
+If you already have the official plugin installed, just run the second command directly.
+
+### Option B: From source (for development)
+
+```bash
+cd ~/.openclaw/extensions
+rm -rf openclaw-lark
+git clone git@github.com:ColinLu50/openclaw-lark-stream.git openclaw-lark
+cd openclaw-lark && npm install
+```
+
+Restart OpenClaw.
+
+## Configuration
+
+Enable optional card footer metadata:
+
+```bash
+openclaw config set channels.feishu.footer.elapsed true  # show elapsed time
+openclaw config set channels.feishu.footer.status true   # show completion status
+```
+
+- **elapsed** — displays total response time (e.g. `Elapsed 3.2s`) in the card footer
+- **status** — displays completion state (`Completed` / `Error` / `Stopped`) in the card footer
+
+Both default to `false` (hidden).
+
+## License
+
+MIT — same as the upstream project.
+
+---
+
+<a id="中文"></a>
+
+# OpenClaw 飞书插件 — 流式卡片 Fork
+
+基于官方 [openclaw-larksuite](https://github.com/larksuite/openclaw-larksuite) 插件的 Fork，支持**流式分块输出**和**工具调用状态展示**。
+
+## 改动说明
+
+官方插件在 LLM 生成完一个 block 后才一次性推送结果。本 Fork 实现了：
+
+- **实时流式追加** — 每个 block 的内容在生成过程中逐步追加到流式卡片，让用户获得即时的视觉反馈
+- **工具调用状态** — 当 agent 调用工具时，卡片实时显示工具调用状态
+
+### 改动文件
+
+- `src/card/reply-dispatcher.ts` — 在流式卡片模式下启用 block 流式输出；接入 `onToolStart` 回调
+- `src/card/streaming-card-controller.ts` — 将每个已交付的 block 实时追加到卡片；添加 `onToolStart()` 显示工具调用状态
+- `src/card/builder.ts` — 完成卡片中工具调用摘要的折叠面板
+
+## 安装
+
+需要 [OpenClaw](https://openclaw.ai)（>= 2026.2.26）和 Node.js（>= v22）。
+
+### 方式 A：npm 安装（推荐）
+
+如果从未安装过官方飞书插件，先安装官方版本完成引导配置：
+
+```bash
+npx -y @larksuite/openclaw-lark install
+```
+
+然后用流式 Fork 替换：
+
+```bash
+npx -y @colinlu50/openclaw-lark-stream install
+```
+
+如果已安装过官方插件，直接运行第二条命令即可。
+
+### 方式 B：从源码安装（用于开发）
+
+```bash
+cd ~/.openclaw/extensions
+rm -rf openclaw-lark
+git clone git@github.com:ColinLu50/openclaw-lark-stream.git openclaw-lark
+cd openclaw-lark && npm install
+```
+
+重启 OpenClaw。
+
+## 配置
+
+开启可选的卡片底栏元信息：
+
+```bash
+openclaw config set channels.feishu.footer.elapsed true  # 开启耗时
+openclaw config set channels.feishu.footer.status true   # 开启状态展示
+```
+
+- **elapsed** — 在卡片底栏显示总响应耗时（如 `耗时 3.2s`）
+- **status** — 在卡片底栏显示完成状态（`已完成` / `出错` / `已停止`）
+
+两者默认为 `false`（不显示）。
+
+## 许可证
+
+MIT — 与上游项目相同。

package/README.zh.md

@@ -0,0 +1,70 @@
+# OpenClaw  Lark/飞书 插件
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@larksuite/openclaw-lark.svg)](https://www.npmjs.com/package/@larksuite/openclaw-lark)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-blue.svg)](https://nodejs.org/)
+
+[English](./README.md) | 中文版
+
+这是 OpenClaw 的官方  Lark/飞书 插件，由 Lark/飞书开放平台团队开发和维护。它将你的 OpenClaw Agent 无缝对接到  Lark/飞书 工作区，赋予其直接读写消息、文档、多维表格、日历、任务等应用的能力。
+
+## 特性
+
+本插件为 OpenClaw 提供了全面的 Lark/飞书集成能力，主要包括：
+
+| 类别 | 能力 |
+|------|------|
+| 💬 消息 | 消息读取（群聊/单聊历史、话题回复）、消息发送、消息回复、消息搜索、图片/文件下载 |
+| 📄 文档 | 创建云文档、更新云文档、读取云文档内容 |
+| 📊 多维表格 | 创建/管理多维表格、数据表、字段、记录（增删改查、批量操作、高级筛选）、视图 |
+| 📈 电子表格 | 创建、编辑、查看电子表格 |
+| 📅 日历日程 | 日历管理、日程管理（创建/查询/修改/删除/搜索）、参会人管理、忙闲查询 |
+| ✅ 任务 | 任务管理（创建/查询/更新/完成）、清单管理、子任务、评论 |
+
+此外，插件还支持：
+- **📱 交互式卡片**：实时状态更新（思考中/生成中/完成状态），提供敏感操作的确认按钮
+- **🌊 流式回复**：在消息卡片中提供实时的流式响应
+- **🔒 权限策略**：为私聊和群聊提供灵活的访问控制策略
+- **⚙️ 高级群组配置**：每个群聊的独立设置，包括白名单、技能绑定和自定义系统提示词
+
+## 安全与风险提示（使用前必读）
+本插件对接 OpenClaw AI 自动化能力，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，OpenClaw 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。
+为降低上述风险，插件已在多个层面启用默认安全保护以降低上述风险，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。
+我们建议您将接入 OpenClaw 的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
+请您充分知悉全部使用风险，使用本插件即视为您自愿承担相关所有责任。
+
+**免责声明：** 
+
+本软件的代码采用MIT许可证。
+该软件运行时会调用Lark/飞书开放平台的API，使用这些API需要遵守如下协议和隐私政策：
+
+- [飞书用户服务协议](https://www.feishu.cn/terms)
+- [飞书隐私政策](https://www.feishu.cn/privacy)
+- [飞书开放平台独立软件服务商安全管理运营规范](https://open.larkoffice.com/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+- [Lark用户服务协议](https://www.larksuite.com/user-terms-of-service)
+- [Lark隐私政策](https://www.larksuite.com/privacy-policy)
+
+## 安装与要求
+
+在开始之前，请确保你已准备好以下各项：
+
+- **Node.js**: `v22` 或更高版本。
+- **OpenClaw**: OpenClaw 已成功安装并可运行。详情请访问 [OpenClaw 官方网站](https://openclaw.ai)。
+
+> **注意**：OpenClaw 版本需在 **2026.2.26** 及以上，可通过 `openclaw -v` 命令查看。如果低于该版本可能出现异常，执行以下命令升级：
+> ```bash
+> npm install -g openclaw
+> ```
+
+## 使用说明
+[OpenClaw  Lark/飞书官方插件使用指南](https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh)
+
+## 贡献
+
+我们欢迎社区的贡献！如果你发现 Bug 或有功能建议，请随时提交 [Issue](https://github.com/larksuite/openclaw-larksuite/issues) 或 [Pull Request](https://github.com/larksuite/openclaw-larksuite/pulls)。
+
+对于较大的改动，我们建议你先通过 Issue 与我们讨论。
+
+## 许可证
+
+本项目基于 **MIT 许可证**。详情请参阅 [LICENSE](./LICENSE.md) 文件。

package/bin/openclaw-lark.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+
+// --tools-version <ver> lets the user pin a specific version
+const args = process.argv.slice(2);
+let version = "latest";
+
+const vIdx = args.indexOf("--tools-version");
+if (vIdx !== -1) {
+  version = args[vIdx + 1];
+  // Remove --tools-version <ver> from forwarded args
+  args.splice(vIdx, 2);
+}
+
+const allArgs = ["--yes", `@larksuite/openclaw-lark-tools@${version}`, ...args];
+
+try {
+  if (process.platform === "win32") {
+    // On Windows, npx is a .cmd shim that can be broken or trigger
+    // DEP0190. Bypass it entirely: run node with the npx-cli.js
+    // script located next to the running node binary.
+    const npxCli = join(
+      dirname(process.execPath),
+      "node_modules",
+      "npm",
+      "bin",
+      "npx-cli.js",
+    );
+    execFileSync(process.execPath, [npxCli, ...allArgs], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        NODE_OPTIONS: [
+          process.env.NODE_OPTIONS,
+          "--disable-warning=DEP0190",
+        ]
+          .filter(Boolean)
+          .join(" "),
+      },
+    });
+  } else {
+    execFileSync("npx", allArgs, { stdio: "inherit" });
+  }
+} catch (error) {
+  process.exit(error.status ?? 1);
+}

package/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OpenClaw Lark/Feishu plugin entry point.
+ *
+ * Registers the Feishu channel and all tool families:
+ * doc, wiki, drive, perm, bitable, task, calendar.
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export { monitorFeishuProvider } from './src/channel/monitor';
+export { sendMessageFeishu, sendCardFeishu, updateCardFeishu, editMessageFeishu } from './src/messaging/outbound/send';
+export { getMessageFeishu } from './src/messaging/outbound/fetch';
+export { uploadImageLark, uploadFileLark, sendImageLark, sendFileLark, sendAudioLark, uploadAndSendMediaLark, } from './src/messaging/outbound/media';
+export { sendTextLark, sendCardLark, sendMediaLark, type SendTextLarkParams, type SendCardLarkParams, type SendMediaLarkParams, } from './src/messaging/outbound/deliver';
+export { type FeishuChannelData } from './src/messaging/outbound/outbound';
+export { probeFeishu } from './src/channel/probe';
+export { addReactionFeishu, removeReactionFeishu, listReactionsFeishu, FeishuEmoji, VALID_FEISHU_EMOJI_TYPES, } from './src/messaging/outbound/reactions';
+export { forwardMessageFeishu } from './src/messaging/outbound/forward';
+export { updateChatFeishu, addChatMembersFeishu, removeChatMembersFeishu, listChatMembersFeishu, } from './src/messaging/outbound/chat-manage';
+export { feishuMessageActions } from './src/messaging/outbound/actions';
+export { mentionedBot, nonBotMentions, extractMessageBody, formatMentionForText, formatMentionForCard, formatMentionAllForText, formatMentionAllForCard, buildMentionedMessage, buildMentionedCardContent, type MentionInfo, } from './src/messaging/inbound/mention';
+export { feishuPlugin } from './src/channel/plugin';
+export type { MessageContext, RawMessage, RawSender, FeishuMessageContext, FeishuReactionCreatedEvent, } from './src/messaging/types';
+export { handleFeishuReaction } from './src/messaging/inbound/reaction-handler';
+export { parseMessageEvent } from './src/messaging/inbound/parse';
+export { checkMessageGate } from './src/messaging/inbound/gate';
+export { isMessageExpired } from './src/messaging/inbound/dedup';
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/index.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OpenClaw Lark/Feishu plugin entry point.
+ *
+ * Registers the Feishu channel and all tool families:
+ * doc, wiki, drive, perm, bitable, task, calendar.
+ */
+import { emptyPluginConfigSchema } from 'openclaw/plugin-sdk';
+import { feishuPlugin } from './src/channel/plugin';
+import { LarkClient } from './src/core/lark-client';
+import { registerOapiTools } from './src/tools/oapi/index';
+import { registerFeishuMcpDocTools } from './src/tools/mcp/doc/index';
+import { registerFeishuOAuthTool } from './src/tools/oauth';
+import { registerFeishuOAuthBatchAuthTool } from './src/tools/oauth-batch-auth';
+import { runDiagnosis, formatDiagReportCli, traceByMessageId, formatTraceOutput, analyzeTrace, } from './src/commands/diagnose';
+import { registerCommands } from './src/commands/index';
+import { larkLogger } from './src/core/lark-logger';
+import { emitSecurityWarnings } from './src/core/security-check';
+const log = larkLogger('plugin');
+// ---------------------------------------------------------------------------
+// Re-exports for external consumers
+// ---------------------------------------------------------------------------
+export { monitorFeishuProvider } from './src/channel/monitor';
+export { sendMessageFeishu, sendCardFeishu, updateCardFeishu, editMessageFeishu } from './src/messaging/outbound/send';
+export { getMessageFeishu } from './src/messaging/outbound/fetch';
+export { uploadImageLark, uploadFileLark, sendImageLark, sendFileLark, sendAudioLark, uploadAndSendMediaLark, } from './src/messaging/outbound/media';
+export { sendTextLark, sendCardLark, sendMediaLark, } from './src/messaging/outbound/deliver';
+export { probeFeishu } from './src/channel/probe';
+export { addReactionFeishu, removeReactionFeishu, listReactionsFeishu, FeishuEmoji, VALID_FEISHU_EMOJI_TYPES, } from './src/messaging/outbound/reactions';
+export { forwardMessageFeishu } from './src/messaging/outbound/forward';
+export { updateChatFeishu, addChatMembersFeishu, removeChatMembersFeishu, listChatMembersFeishu, } from './src/messaging/outbound/chat-manage';
+export { feishuMessageActions } from './src/messaging/outbound/actions';
+export { mentionedBot, nonBotMentions, extractMessageBody, formatMentionForText, formatMentionForCard, formatMentionAllForText, formatMentionAllForCard, buildMentionedMessage, buildMentionedCardContent, } from './src/messaging/inbound/mention';
+export { feishuPlugin } from './src/channel/plugin';
+export { handleFeishuReaction } from './src/messaging/inbound/reaction-handler';
+export { parseMessageEvent } from './src/messaging/inbound/parse';
+export { checkMessageGate } from './src/messaging/inbound/gate';
+export { isMessageExpired } from './src/messaging/inbound/dedup';
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+const plugin = {
+    id: 'openclaw-lark',
+    name: 'Feishu',
+    description: 'Lark/Feishu channel plugin with im/doc/wiki/drive/task/calendar tools',
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        LarkClient.setRuntime(api.runtime);
+        api.registerChannel({ plugin: feishuPlugin });
+        // ========================================
+        // Register OAPI tools (calendar, task - using Feishu Open API directly)
+        registerOapiTools(api);
+        // Register MCP doc tools (using Model Context Protocol)
+        registerFeishuMcpDocTools(api);
+        // Register OAuth tool (UAT device flow authorization)
+        registerFeishuOAuthTool(api);
+        // Register OAuth batch auth tool (batch authorization for all app scopes)
+        registerFeishuOAuthBatchAuthTool(api);
+        // ---- Tool call hooks (auto-trace AI tool invocations) ----
+        api.on('before_tool_call', (event) => {
+            log.info(`tool call: ${event.toolName} params=${JSON.stringify(event.params)}`);
+        });
+        api.on('after_tool_call', (event) => {
+            if (event.error) {
+                log.error(`tool fail: ${event.toolName} ${event.error} (${event.durationMs ?? 0}ms)`);
+            }
+            else {
+                log.info(`tool done: ${event.toolName} ok (${event.durationMs ?? 0}ms)`);
+            }
+        });
+        // ---- Diagnostic commands ----
+        // CLI: openclaw feishu-diagnose [--trace <messageId>]
+        api.registerCli((ctx) => {
+            ctx.program
+                .command('feishu-diagnose')
+                .description('运行飞书插件诊断，检查配置、连通性和权限状态')
+                .option('--trace <messageId>', '按 message_id 追踪完整处理链路')
+                .option('--analyze', '分析追踪日志（需配合 --trace 使用）')
+                .action(async (opts) => {
+                try {
+                    if (opts.trace) {
+                        const lines = await traceByMessageId(opts.trace);
+                        // eslint-disable-next-line no-console -- CLI 命令直接输出到终端
+                        console.log(formatTraceOutput(lines, opts.trace));
+                        if (opts.analyze && lines.length > 0) {
+                            // eslint-disable-next-line no-console -- CLI 命令直接输出到终端
+                            console.log(analyzeTrace(lines, opts.trace));
+                        }
+                    }
+                    else {
+                        const report = await runDiagnosis({
+                            config: ctx.config,
+                            logger: ctx.logger,
+                        });
+                        // eslint-disable-next-line no-console -- CLI 命令直接输出到终端
+                        console.log(formatDiagReportCli(report));
+                        if (report.overallStatus === 'unhealthy') {
+                            process.exitCode = 1;
+                        }
+                    }
+                }
+                catch (err) {
+                    ctx.logger.error(`诊断命令执行失败: ${err}`);
+                    process.exitCode = 1;
+                }
+            });
+        }, { commands: ['feishu-diagnose'] });
+        // Chat commands: /feishu_diagnose, /feishu_doctor, /feishu_auth, /feishu
+        registerCommands(api);
+        // ---- Multi-account security checks ----
+        if (api.config) {
+            emitSecurityWarnings(api.config, api.logger);
+        }
+    },
+};
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "openclaw-lark",
+  "channels": ["feishu"],
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@colinlu50/openclaw-lark-stream",
+  "version": "2026.3.17",
+  "description": "OpenClaw Lark/Feishu channel plugin",
+  "type": "module",
+  "bin": {
+    "openclaw-lark": "bin/openclaw-lark.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "bin/",
+    "skills/",
+    "openclaw.plugin.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "release": "node scripts/release.mjs",
+    "lint": "eslint src/ index.ts",
+    "lint:fix": "eslint src/ index.ts --fix",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check src/**/*.ts"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "@sinclair/typebox": "0.34.48",
+    "image-size": "^2.0.2",
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "channel": {
+      "id": "openclaw-lark",
+      "label": "Feishu",
+      "selectionLabel": "Lark/Feishu (飞书)",
+      "docsPath": "/channels/feishu",
+      "docsLabel": "feishu",
+      "blurb": "飞书/Lark enterprise messaging with doc/wiki/drive/task/calendar tools.",
+      "aliases": [
+        "lark"
+      ],
+      "order": 35,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@colinlu50/openclaw-lark-stream",
+      "localPath": "extensions/feishu",
+      "defaultChoice": "npm"
+    }
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  }
+}