@colinlu50/openclaw-lark-stream 2026.3.17

package/src/tools/onboarding-auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding 预授权模块。
+ *
+ * 配对后自动发起 OAuth Device Flow，引导应用 owner 完成用户授权。
+ * 仅当配对用户 === 应用 owner 时触发。
+ *
+ * 飞书限制：单次 OAuth 最多 50 个 scope。
+ * 超过 50 个时自动分批处理，每批授权完成后自动发起下一批（链式触发）。
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/**
+ * 配对后触发 onboarding OAuth 授权。
+ *
+ * 流程：
+ *   1. 检查 userOpenId === 应用 owner，不匹配则静默跳过
+ *   2. 读取 onboarding-scopes.json 中的 user scope 列表
+ *   3. 分批处理（每批最多 50 个），第一批直接发起 OAuth Device Flow
+ *   4. 每批授权完成后通过 onAuthComplete 回调自动发起下一批
+ */
+export declare function triggerOnboarding(params: {
+    cfg: ClawdbotConfig;
+    userOpenId: string;
+    accountId: string;
+}): Promise<void>;

package/src/tools/onboarding-auth.js

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding 预授权模块。
+ *
+ * 配对后自动发起 OAuth Device Flow，引导应用 owner 完成用户授权。
+ * 仅当配对用户 === 应用 owner 时触发。
+ *
+ * 飞书限制：单次 OAuth 最多 50 个 scope。
+ * 超过 50 个时自动分批处理，每批授权完成后自动发起下一批（链式触发）。
+ */
+import { getLarkAccount } from '../core/accounts';
+import { LarkClient } from '../core/lark-client';
+import { getAppGrantedScopes } from '../core/app-scope-checker';
+import { getAppOwnerFallback } from '../core/app-owner-fallback';
+import { executeAuthorize } from './oauth';
+import { larkLogger } from '../core/lark-logger';
+import { filterSensitiveScopes } from '../core/tool-scopes';
+const log = larkLogger('tools/onboarding-auth');
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_SCOPES_PER_BATCH = 100;
+// ---------------------------------------------------------------------------
+// Trigger onboarding
+// ---------------------------------------------------------------------------
+/**
+ * 配对后触发 onboarding OAuth 授权。
+ *
+ * 流程：
+ *   1. 检查 userOpenId === 应用 owner，不匹配则静默跳过
+ *   2. 读取 onboarding-scopes.json 中的 user scope 列表
+ *   3. 分批处理（每批最多 50 个），第一批直接发起 OAuth Device Flow
+ *   4. 每批授权完成后通过 onAuthComplete 回调自动发起下一批
+ */
+export async function triggerOnboarding(params) {
+    const { cfg, userOpenId, accountId } = params;
+    const acct = getLarkAccount(cfg, accountId);
+    if (!acct.configured) {
+        log.warn(`account ${accountId} not configured, skipping`);
+        return;
+    }
+    const sdk = LarkClient.fromAccount(acct).sdk;
+    const { appId } = acct;
+    // 1. 检查 userOpenId === 应用 owner（统一走 getAppOwnerFallback）
+    const ownerOpenId = await getAppOwnerFallback(acct, sdk);
+    if (!ownerOpenId) {
+        log.info(`app ${appId} has no owner info, skipping`);
+        return;
+    }
+    if (userOpenId !== ownerOpenId) {
+        log.info(`user ${userOpenId} is not app owner (${ownerOpenId}), skipping`);
+        return;
+    }
+    log.info(`user ${userOpenId} is app owner, starting OAuth`);
+    // 3. 动态获取应用已开通的 user scope 列表
+    let allUserScopes;
+    try {
+        allUserScopes = await getAppGrantedScopes(sdk, appId, 'user');
+    }
+    catch (err) {
+        log.warn(`failed to get app granted scopes: ${err}`);
+        return;
+    }
+    // 过滤掉敏感 scope
+    allUserScopes = filterSensitiveScopes(allUserScopes);
+    if (allUserScopes.length === 0) {
+        log.info('no user scopes configured, skipping');
+        return;
+    }
+    // 4. 分批
+    const batches = [];
+    for (let i = 0; i < allUserScopes.length; i += MAX_SCOPES_PER_BATCH) {
+        batches.push(allUserScopes.slice(i, i + MAX_SCOPES_PER_BATCH));
+    }
+    log.info(`${allUserScopes.length} user scopes, ${batches.length} batch(es)`);
+    // 5. 链式发起授权（第一批同步发起，后续批次由 onAuthComplete 回调触发）
+    const startBatch = async (batchIndex) => {
+        if (batchIndex >= batches.length) {
+            log.info('all batches completed');
+            return;
+        }
+        const batch = batches[batchIndex];
+        const scope = batch.join(' ');
+        let batchInfo = '';
+        if (batches.length > 1) {
+            batchInfo =
+                `\n\n📋 授权进度：第 ${batchIndex + 1}/${batches.length} 批` +
+                    `（本批 ${batch.length} 个权限，共 ${allUserScopes.length} 个）`;
+            if (batchIndex < batches.length - 1) {
+                batchInfo += `\n授权完成后将自动发起下一批。`;
+            }
+            else {
+                batchInfo += `\n这是最后一批，授权完成后即可使用所有功能。`;
+            }
+        }
+        const ticket = {
+            messageId: `onboarding:${Date.now()}`,
+            chatId: userOpenId,
+            accountId,
+            startTime: Date.now(),
+            senderOpenId: userOpenId,
+            chatType: 'p2p',
+        };
+        log.info(`starting batch ${batchIndex + 1}/${batches.length}, scopes=${batch.length}`);
+        try {
+            await executeAuthorize({
+                account: acct,
+                senderOpenId: userOpenId,
+                scope,
+                isBatchAuth: true,
+                totalAppScopes: allUserScopes.length,
+                alreadyGranted: batchIndex * MAX_SCOPES_PER_BATCH,
+                batchInfo,
+                skipSyntheticMessage: true,
+                cfg,
+                ticket,
+                onAuthComplete: async () => {
+                    log.info(`batch ${batchIndex + 1}/${batches.length} auth completed`);
+                    await startBatch(batchIndex + 1);
+                },
+            });
+        }
+        catch (err) {
+            log.error(`batch ${batchIndex + 1} failed: ${err}`);
+        }
+    };
+    await startBatch(0);
+}

package/src/tools/tat/im/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM 工具集
+ * 统一导出所有即时通讯相关工具的注册函数
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+/**
+ * 注册所有 IM 工具
+ *
+ * Note: feishu_im_message_reaction 和 feishu_im_message_recall 已移除，
+ * 其功能由 ChannelMessageActionAdapter (actions.ts) 的 react/delete action 统一覆盖。
+ */
+export declare function registerFeishuImTools(api: OpenClawPluginApi): void;

package/src/tools/tat/im/index.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM 工具集
+ * 统一导出所有即时通讯相关工具的注册函数
+ */
+import { registerFeishuImBotImageTool } from './resource';
+/**
+ * 注册所有 IM 工具
+ *
+ * Note: feishu_im_message_reaction 和 feishu_im_message_recall 已移除，
+ * 其功能由 ChannelMessageActionAdapter (actions.ts) 的 react/delete action 统一覆盖。
+ */
+export function registerFeishuImTools(api) {
+    registerFeishuImBotImageTool(api);
+    api.logger.info?.('feishu_im: Registered feishu_im_bot_image');
+}

package/src/tools/tat/im/resource.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_bot_image 工具
+ *
+ * 以机器人身份下载飞书 IM 消息中的图片/文件资源到本地。
+ *
+ * 飞书 API:
+ *   - 下载资源: GET  /open-apis/im/v1/messages/:message_id/resources/:file_key
+ * 权限: im:resource
+ * 凭证: tenant_access_token
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuImBotImageTool(api: OpenClawPluginApi): void;

package/src/tools/tat/im/resource.js

@@ -0,0 +1,157 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_bot_image 工具
+ *
+ * 以机器人身份下载飞书 IM 消息中的图片/文件资源到本地。
+ *
+ * 飞书 API:
+ *   - 下载资源: GET  /open-apis/im/v1/messages/:message_id/resources/:file_key
+ * 权限: im:resource
+ * 凭证: tenant_access_token
+ */
+import { buildRandomTempFilePath } from 'openclaw/plugin-sdk';
+import { Type } from '@sinclair/typebox';
+import { json, createToolContext, formatLarkError, registerTool, StringEnum } from '../../oapi/helpers';
+import * as fsPromises from 'node:fs/promises';
+import * as path from 'node:path';
+// ===========================================================================
+// Shared constants
+// ===========================================================================
+/** MIME type → 文件扩展名（下载时使用） */
+const MIME_TO_EXT = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'image/bmp': '.bmp',
+    'image/tiff': '.tiff',
+    'video/mp4': '.mp4',
+    'video/mpeg': '.mpeg',
+    'video/quicktime': '.mov',
+    'video/x-msvideo': '.avi',
+    'video/webm': '.webm',
+    'audio/mpeg': '.mp3',
+    'audio/wav': '.wav',
+    'audio/ogg': '.ogg',
+    'audio/mp4': '.m4a',
+    'application/pdf': '.pdf',
+    'application/msword': '.doc',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'application/vnd.ms-excel': '.xls',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.ms-powerpoint': '.ppt',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+    'application/zip': '.zip',
+    'application/x-rar-compressed': '.rar',
+    'text/plain': '.txt',
+    'application/json': '.json',
+};
+// ===========================================================================
+// Shared helpers
+// ===========================================================================
+/**
+ * 从二进制响应中提取 Buffer、Content-Type。
+ * SDK 的二进制响应可能有 getReadableStream()，也可能直接是 Buffer 等格式。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function extractBuffer(res) {
+    let chunks;
+    if (typeof res.getReadableStream === 'function') {
+        const stream = res.getReadableStream();
+        chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+    }
+    else if (Buffer.isBuffer(res)) {
+        chunks = [res];
+    }
+    else if (Buffer.isBuffer(res?.data)) {
+        chunks = [res.data];
+    }
+    else {
+        throw new Error('无法从响应中提取二进制数据');
+    }
+    const buffer = Buffer.concat(chunks);
+    const contentType = res.headers?.['content-type'] ?? '';
+    return { buffer, contentType };
+}
+/**
+ * 将 buffer 保存到临时文件，返回路径。
+ */
+async function saveToTempFile(buffer, contentType, prefix) {
+    const mimeType = contentType ? contentType.split(';')[0].trim() : '';
+    const mimeExt = mimeType ? MIME_TO_EXT[mimeType] : undefined;
+    const filePath = buildRandomTempFilePath({
+        prefix,
+        extension: mimeExt,
+    });
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, buffer);
+    return filePath;
+}
+// ===========================================================================
+// Download tool — feishu_im_bot_image
+// ===========================================================================
+const FeishuImBotImageSchema = Type.Object({
+    message_id: Type.String({
+        description: '消息 ID（om_xxx 格式），引用消息可从上下文中的 [message_id=om_xxx] 提取',
+    }),
+    file_key: Type.String({
+        description: '资源 Key，图片消息的 image_key（img_xxx）或文件消息的 file_key（file_xxx）',
+    }),
+    type: StringEnum(['image', 'file'], {
+        description: '资源类型：image（图片消息中的图片）、file（文件/音频/视频消息中的文件）',
+    }),
+});
+export function registerFeishuImBotImageTool(api) {
+    if (!api.config)
+        return;
+    const { getClient, log } = createToolContext(api, 'feishu_im_bot_image');
+    registerTool(api, {
+        name: 'feishu_im_bot_image',
+        label: 'Feishu: IM Bot Image Download',
+        description: '【以机器人身份】下载飞书 IM 消息中的图片或文件资源到本地。' +
+            '\n\n适用场景：用户直接发送给机器人的消息、用户引用的消息、机器人收到的群聊消息中的图片/文件。' +
+            '即当前对话上下文中出现的 message_id 和 image_key/file_key，应使用本工具下载。' +
+            '\n引用消息的 message_id 可从上下文中的 [message_id=om_xxx] 提取，无需向用户询问。' +
+            '\n\n文件自动保存到 /tmp/openclaw/ 下，返回值中的 saved_path 为实际保存路径。',
+        parameters: FeishuImBotImageSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = getClient();
+                log.info(`download: message_id="${p.message_id}", file_key="${p.file_key}", type="${p.type}"`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const res = await client.im.messageResource.get({
+                    path: {
+                        message_id: p.message_id,
+                        file_key: p.file_key,
+                    },
+                    params: { type: p.type },
+                });
+                const { buffer, contentType } = await extractBuffer(res);
+                log.info(`download: ${buffer.length} bytes, content-type=${contentType}`);
+                const savedPath = await saveToTempFile(buffer, contentType, 'bot-resource');
+                log.info(`download: saved to ${savedPath}`);
+                return json({
+                    message_id: p.message_id,
+                    file_key: p.file_key,
+                    type: p.type,
+                    size_bytes: buffer.length,
+                    content_type: contentType,
+                    saved_path: savedPath,
+                });
+            }
+            catch (err) {
+                log.error(`Error: ${formatLarkError(err)}`);
+                return json({ error: formatLarkError(err) });
+            }
+        },
+    }, { name: 'feishu_im_bot_image' });
+    api.logger.info?.('feishu_im_bot_image: Registered feishu_im_bot_image tool');
+}