@larksuite/openclaw-lark 2026.4.1 → 2026.4.7

package/src/messaging/outbound/deliver.js

@@ -4,9 +4,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendTextLark = sendTextLark;
 exports.sendCardLark = sendCardLark;
 exports.sendMediaLark = sendMediaLark;
+exports.sendCommentReplyLark = sendCommentReplyLark;
 const accounts_1 = require("../../core/accounts.js");
 const lark_client_1 = require("../../core/lark-client.js");
 const targets_1 = require("../../core/targets.js");
+const comment_target_1 = require("../../core/comment-target.js");
 const markdown_style_1 = require("../../card/markdown-style.js");
 const api_error_1 = require("../../core/api-error.js");
 const lark_logger_1 = require("../../core/lark-logger.js");
@@ -307,3 +309,95 @@ async function sendMediaLark(params) {
         };
     }
 }
+/**
+ * Send a text message to a Feishu Drive comment surface.
+ *
+ * Parses the comment target from `to`, then chooses one of two delivery
+ * strategies:
+ * - `reply`        → reply in the existing comment thread
+ * - `create_whole` → create a new whole-document comment
+ *
+ * Returns a synthetic FeishuSendResult (no IM messageId).
+ *
+ * @throws {Error} When the target is not a valid comment target or API fails.
+ */
+async function sendCommentReplyLark(params) {
+    const { cfg, to, text, accountId } = params;
+    const target = (0, comment_target_1.parseFeishuCommentTarget)(to);
+    if (!target) {
+        throw new Error(`Not a valid comment target: "${to}"`);
+    }
+    log.info(`sendCommentReplyLark: mode=${target.deliveryMode}, comment=${target.commentId}, textLength=${text.length}`);
+    const client = lark_client_1.LarkClient.fromCfg(cfg, accountId);
+    const elements = [{ type: 'text_run', text_run: { text } }];
+    if (target.deliveryMode === 'create_whole') {
+        try {
+            await client.sdk.drive.v1.fileComment.create({
+                path: { file_token: target.fileToken },
+                params: {
+                    file_type: target.fileType,
+                    user_id_type: 'open_id',
+                },
+                data: {
+                    reply_list: {
+                        replies: [
+                            {
+                                content: {
+                                    elements,
+                                },
+                            },
+                        ],
+                    },
+                },
+            });
+            log.info(`whole comment created successfully`);
+            return {
+                messageId: `comment-create:${target.commentId}`,
+                chatId: to,
+            };
+        }
+        catch (err) {
+            const detail = (0, api_error_1.formatLarkError)(err);
+            log.error(`sendCommentReplyLark failed to create whole comment: ${detail}`);
+            throw new Error(`Comment create failed: ${detail}`, { cause: err });
+        }
+    }
+    // sdk.request defaults to tenant_access_token (bot identity).
+    // Dual payload format: try content.elements first, fallback to reply_elements.
+    const url = `/open-apis/drive/v1/files/${target.fileToken}/comments/${target.commentId}/replies`;
+    const queryParams = { file_type: target.fileType, user_id_type: 'open_id' };
+    try {
+        await client.sdk.request({
+            method: 'POST',
+            url,
+            params: queryParams,
+            data: { content: { elements } },
+        });
+        log.info(`comment reply sent successfully`);
+        return {
+            messageId: `comment-reply:${target.commentId}`,
+            chatId: to,
+        };
+    }
+    catch (firstErr) {
+        // Fallback: some API versions use reply_elements format
+        try {
+            await client.sdk.request({
+                method: 'POST',
+                url,
+                params: queryParams,
+                data: { reply_elements: elements },
+            });
+            log.info(`comment reply sent successfully (reply_elements fallback)`);
+            return {
+                messageId: `comment-reply:${target.commentId}`,
+                chatId: to,
+            };
+        }
+        catch (secondErr) {
+            const detail = (0, api_error_1.formatLarkError)(firstErr);
+            log.error(`sendCommentReplyLark failed: ${detail}`);
+            throw new Error(`Comment reply failed: ${detail}`, { cause: secondErr });
+        }
+    }
+}

package/src/messaging/outbound/outbound.js

@@ -5,6 +5,7 @@ exports.feishuOutbound = void 0;
 const lark_client_1 = require("../../core/lark-client.js");
 const lark_logger_1 = require("../../core/lark-logger.js");
 const targets_1 = require("../../core/targets.js");
+const comment_target_1 = require("../../core/comment-target.js");
 const deliver_1 = require("./deliver.js");
 const log = (0, lark_logger_1.larkLogger)('outbound/outbound');
 /**
@@ -40,12 +41,30 @@ exports.feishuOutbound = {
     textChunkLimit: 15000,
     sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
         log.info(`sendText: target=${to}, textLength=${text.length}`);
+        // Comment thread routing — route replies through Drive comment API
+        if ((0, comment_target_1.isCommentTarget)(to)) {
+            log.info(`sendText: detected comment target, routing through Drive comment API`);
+            const result = await (0, deliver_1.sendCommentReplyLark)({ cfg, to, text, accountId: accountId ?? undefined });
+            return { channel: 'feishu', ...result };
+        }
         const ctx = resolveFeishuSendContext({ cfg, to, accountId, replyToId, threadId });
         const result = await (0, deliver_1.sendTextLark)({ ...ctx, to: ctx.to, text });
         return { channel: 'feishu', ...result };
     },
     sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId, replyToId, threadId }) => {
         log.info(`sendMedia: target=${to}, ` + `hasText=${Boolean(text?.trim())}, mediaUrl=${mediaUrl ?? '(none)'}`);
+        // Comment thread routing — send text (with media URL appended) via Drive comment API
+        if ((0, comment_target_1.isCommentTarget)(to)) {
+            log.info(`sendMedia: detected comment target, routing through Drive comment API`);
+            const parts = [];
+            if (text?.trim())
+                parts.push(text.trim());
+            if (mediaUrl)
+                parts.push(`📎 ${mediaUrl}`);
+            const combinedText = parts.join('\n') || '(media)';
+            const result = await (0, deliver_1.sendCommentReplyLark)({ cfg, to, text: combinedText, accountId: accountId ?? undefined });
+            return { channel: 'feishu', ...result };
+        }
         const ctx = resolveFeishuSendContext({ cfg, to, accountId, replyToId, threadId });
         // Feishu media messages do not support inline captions — send text first.
         if (text?.trim()) {

package/src/messaging/types.d.ts

@@ -56,6 +56,69 @@ export interface FeishuReactionCreatedEvent {
     };
     action_time?: string;
 }
+/**
+ * Raw event shape for `drive.notice.comment_add_v1`.
+ *
+ * Fired when a user adds a comment or reply on a Drive document.
+ * The SDK flattens the v2 envelope header into the handler `data` object,
+ * so `app_id` is available directly on the event.
+ *
+ * **Real event structure** (SDK-flattened):
+ * ```json
+ * {
+ *   "app_id": "cli_xxx",
+ *   "file_token": "xxx",
+ *   "file_type": "docx",
+ *   "comment_id": "xxx",
+ *   "reply_id": "xxx",          // optional, present for replies
+ *   "notice_meta": {
+ *     "from_user_id": { "open_id": "ou_xxx", "user_id": "xxx", "union_id": "xxx" },
+ *     "timestamp": "1712000000000",
+ *     "is_mentioned": true
+ *   }
+ * }
+ * ```
+ *
+ * Some fields may also appear at top-level depending on SDK version,
+ * so the parser checks both locations.
+ */
+export interface FeishuDriveCommentEvent {
+    /** App ID from the event envelope header. */
+    app_id?: string;
+    /** File token of the document where the comment was added. */
+    file_token?: string;
+    /** File type: doc, docx, sheet, file, slides, etc. */
+    file_type?: string;
+    /** Comment ID of the root comment. */
+    comment_id?: string;
+    /** Reply ID (present when the event is a reply, not a root comment). */
+    reply_id?: string;
+    /**
+     * Metadata about the notice — primary location for user info and timestamp.
+     * Present in the real event structure; not always at top level.
+     */
+    notice_meta?: {
+        from_user_id?: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        file_token?: string;
+        file_type?: string;
+        timestamp?: string;
+        is_mentioned?: boolean;
+    };
+    /** Whether the bot was @-mentioned in this comment. */
+    is_mention?: boolean;
+    /** Fallback: user ID at top level (some SDK flattening styles). */
+    user_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    /** Fallback: event timestamp at top level. */
+    action_time?: string;
+}
 export interface FeishuBotAddedEvent {
     chat_id: string;
     operator_id: {

package/src/tools/oapi/drive/doc-comments.js

@@ -27,7 +27,7 @@ const ReplyElementSchema = typebox_1.Type.Object({
     url: typebox_1.Type.Optional(typebox_1.Type.String({ description: '链接URL(type=link时必填)' })),
 });
 const DocCommentsSchema = typebox_1.Type.Object({
-    action: (0, helpers_1.StringEnum)(['list', 'create', 'patch']),
+    action: (0, helpers_1.StringEnum)(['list', 'list_replies', 'create', 'reply', 'patch']),
     file_token: typebox_1.Type.String({
         description: '云文档token或wiki节点token(可从文档URL获取)。如果是wiki token，会自动转换为实际文档的obj_token',
     }),
@@ -43,13 +43,13 @@ const DocCommentsSchema = typebox_1.Type.Object({
     })),
     page_size: typebox_1.Type.Optional(typebox_1.Type.Integer({ description: '分页大小' })),
     page_token: typebox_1.Type.Optional(typebox_1.Type.String({ description: '分页标记' })),
-    // create action参数
+    // create / reply action参数
     elements: typebox_1.Type.Optional(typebox_1.Type.Array(ReplyElementSchema, {
-        description: '评论内容元素数组(action=create时必填)。' + '支持text(纯文本)、mention(@用户)、link(超链接)三种类型',
+        description: '评论内容元素数组(action=create/reply时必填)。' + '支持text(纯文本)、mention(@用户)、link(超链接)三种类型',
     })),
-    // patch action参数
+    // list_replies / reply / patch action参数
     comment_id: typebox_1.Type.Optional(typebox_1.Type.String({
-        description: '评论ID(action=patch时必填)',
+        description: '评论ID(action=list_replies/reply/patch时必填)',
     })),
     is_solved_value: typebox_1.Type.Optional(typebox_1.Type.Boolean({
         description: '解决状态:true=解决,false=恢复(action=patch时必填)',
@@ -109,7 +109,7 @@ async function assembleCommentsWithReplies(client, file_token, file_type, commen
                             page_size: 50,
                             user_id_type,
                         },
-                    }, opts), { as: 'user' });
+                    }, opts), { as: 'tenant' });
                     const replyData = replyRes.data;
                     if (replyRes.code === 0 && replyData?.items) {
                         replies.push(...(replyData.items || []));
@@ -145,8 +145,10 @@ function registerDocCommentsTool(api) {
         label: 'Feishu: Doc Comments',
         description: '【以用户身份】管理云文档评论。支持: ' +
             '(1) list - 获取评论列表(含完整回复); ' +
-            '(2) create - 添加全文评论(支持文本、@用户、超链接); ' +
-            '(3) patch - 解决/恢复评论。' +
+            '(2) list_replies - 获取指定评论的回复列表; ' +
+            '(3) create - 添加全文评论(支持文本、@用户、超链接); ' +
+            '(4) reply - 回复已有评论; ' +
+            '(5) patch - 解决/恢复评论。' +
             '支持 wiki token。',
         parameters: DocCommentsSchema,
         async execute(_toolCallId, params) {
@@ -176,7 +178,7 @@ function registerDocCommentsTool(api) {
                         }
                         actualFileToken = node.obj_token;
                         actualFileType = node.obj_type;
-                        log.info(`doc_comments: wiki token converted: obj_token="${actualFileToken}", obj_type="${actualFileType}"`);
+                        log.info(`doc_comments: wiki token converted, obj_type="${actualFileType}"`);
                     }
                     catch (err) {
                         log.error(`doc_comments: failed to convert wiki token: ${err}`);
@@ -187,7 +189,7 @@ function registerDocCommentsTool(api) {
                 }
                 // Action: list - 获取评论列表
                 if (p.action === 'list') {
-                    log.info(`doc_comments.list: file_token="${actualFileToken}", file_type=${actualFileType}`);
+                    log.info(`doc_comments.list: file_type=${actualFileType}`);
                     const res = await client.invoke('feishu_doc_comments.list', (sdk, opts) => sdk.drive.v1.fileComment.list({
                         path: { file_token: actualFileToken },
                         params: {
@@ -198,7 +200,7 @@ function registerDocCommentsTool(api) {
                             page_token: p.page_token,
                             user_id_type: userIdType,
                         },
-                    }, opts), { as: 'user' });
+                    }, opts), { as: 'tenant' });
                     (0, helpers_1.assertLarkOk)(res);
                     const items = res.data?.items || [];
                     log.info(`doc_comments.list: found ${items.length} comments`);
@@ -210,6 +212,35 @@ function registerDocCommentsTool(api) {
                         page_token: res.data?.page_token,
                     });
                 }
+                // Action: list_replies - 获取指定评论的回复列表
+                if (p.action === 'list_replies') {
+                    if (!p.comment_id) {
+                        return (0, helpers_1.json)({ error: 'comment_id 参数必填' });
+                    }
+                    log.info(`doc_comments.list_replies: comment_id="${p.comment_id}"`);
+                    // Single-page fetch — return items + pagination metadata,
+                    // consistent with the list action's API semantics.
+                    const replyRes = await client.invoke('feishu_doc_comments.list_replies', (sdk, opts) => sdk.drive.v1.fileCommentReply.list({
+                        path: {
+                            file_token: actualFileToken,
+                            comment_id: p.comment_id,
+                        },
+                        params: {
+                            file_type: actualFileType,
+                            page_token: p.page_token,
+                            page_size: p.page_size || 50,
+                            user_id_type: userIdType,
+                        },
+                    }, opts), { as: 'tenant' });
+                    (0, helpers_1.assertLarkOk)(replyRes);
+                    const replyData = replyRes.data;
+                    log.info(`doc_comments.list_replies: found ${replyData?.items?.length ?? 0} replies`);
+                    return (0, helpers_1.json)({
+                        items: replyData?.items ?? [],
+                        has_more: replyData?.has_more ?? false,
+                        page_token: replyData?.page_token,
+                    });
+                }
                 // Action: create - 创建评论
                 if (p.action === 'create') {
                     if (!p.elements || p.elements.length === 0) {
@@ -217,30 +248,68 @@ function registerDocCommentsTool(api) {
                             error: 'elements 参数必填且不能为空',
                         });
                     }
-                    log.info(`doc_comments.create: file_token="${actualFileToken}", elements=${p.elements.length}`);
+                    log.info(`doc_comments.create: file_type=${actualFileType}, elements=${p.elements.length}`);
                     const sdkElements = convertElementsToSDKFormat(p.elements);
+                    const commentData = {
+                        reply_list: {
+                            replies: [
+                                {
+                                    content: {
+                                        elements: sdkElements,
+                                    },
+                                },
+                            ],
+                        },
+                    };
                     const res = await client.invoke('feishu_doc_comments.create', (sdk, opts) => sdk.drive.v1.fileComment.create({
                         path: { file_token: actualFileToken },
                         params: {
                             file_type: actualFileType,
                             user_id_type: userIdType,
                         },
-                        data: {
-                            reply_list: {
-                                replies: [
-                                    {
-                                        content: {
-                                            elements: sdkElements,
-                                        },
-                                    },
-                                ],
-                            },
-                        },
-                    }, opts), { as: 'user' });
+                        data: commentData,
+                    }, opts), { as: 'tenant' });
                     (0, helpers_1.assertLarkOk)(res);
                     log.info(`doc_comments.create: created comment ${res.data?.comment_id}`);
                     return (0, helpers_1.json)(res.data);
                 }
+                // Action: reply - 回复已有评论
+                if (p.action === 'reply') {
+                    if (!p.comment_id) {
+                        return (0, helpers_1.json)({ error: 'comment_id 参数必填' });
+                    }
+                    if (!p.elements || p.elements.length === 0) {
+                        return (0, helpers_1.json)({ error: 'elements 参数必填且不能为空' });
+                    }
+                    log.info(`doc_comments.reply: comment_id="${p.comment_id}", elements=${p.elements.length}`);
+                    const sdkElements = convertElementsToSDKFormat(p.elements);
+                    // 使用 sdk.request() 发起请求（与 deliver.ts 一致），SDK 内部自动管理 TAT。
+                    // 双重 payload 格式兜底：先试 content.elements，失败再试 reply_elements。
+                    const replyUrl = `/open-apis/drive/v1/files/${actualFileToken}/comments/${p.comment_id}/replies`;
+                    const replyParams = { file_type: actualFileType, user_id_type: userIdType };
+                    let res;
+                    try {
+                        res = await client.invoke('feishu_doc_comments.reply', (sdk) => sdk.request({
+                            method: 'POST',
+                            url: replyUrl,
+                            params: replyParams,
+                            data: { content: { elements: sdkElements } },
+                        }), { as: 'tenant' });
+                    }
+                    catch (_firstErr) {
+                        // Fallback: 部分 API 版本使用 reply_elements 格式
+                        log.info(`doc_comments.reply: first attempt failed, trying reply_elements format`);
+                        res = await client.invoke('feishu_doc_comments.reply', (sdk) => sdk.request({
+                            method: 'POST',
+                            url: replyUrl,
+                            params: replyParams,
+                            data: { reply_elements: sdkElements },
+                        }), { as: 'tenant' });
+                    }
+                    (0, helpers_1.assertLarkOk)(res);
+                    log.info(`doc_comments.reply: created reply`);
+                    return (0, helpers_1.json)(res.data ?? res);
+                }
                 // Action: patch - 解决/恢复评论
                 if (p.action === 'patch') {
                     if (!p.comment_id) {

package/src/tools/oapi/index.js

@@ -39,6 +39,7 @@ function registerOapiTools(api) {
     // Task tools
     (0, index_3.registerFeishuTaskTaskTool)(api);
     (0, index_3.registerFeishuTaskTasklistTool)(api);
+    (0, index_3.registerFeishuTaskSectionTool)(api);
     (0, index_3.registerFeishuTaskCommentTool)(api);
     (0, index_3.registerFeishuTaskSubtaskTool)(api);
     // Bitable tools

package/src/tools/oapi/task/index.d.ts

@@ -6,3 +6,4 @@ export { registerFeishuTaskTaskTool } from './task';
 export { registerFeishuTaskTasklistTool } from './tasklist';
 export { registerFeishuTaskCommentTool } from './comment';
 export { registerFeishuTaskSubtaskTool } from './subtask';
+export { registerFeishuTaskSectionTool } from './section';

package/src/tools/oapi/task/index.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerFeishuTaskSubtaskTool = exports.registerFeishuTaskCommentTool = exports.registerFeishuTaskTasklistTool = exports.registerFeishuTaskTaskTool = void 0;
+exports.registerFeishuTaskSectionTool = exports.registerFeishuTaskSubtaskTool = exports.registerFeishuTaskCommentTool = exports.registerFeishuTaskTasklistTool = exports.registerFeishuTaskTaskTool = void 0;
 var task_1 = require("./task.js");
 Object.defineProperty(exports, "registerFeishuTaskTaskTool", { enumerable: true, get: function () { return task_1.registerFeishuTaskTaskTool; } });
 var tasklist_1 = require("./tasklist.js");
@@ -13,3 +13,5 @@ var comment_1 = require("./comment.js");
 Object.defineProperty(exports, "registerFeishuTaskCommentTool", { enumerable: true, get: function () { return comment_1.registerFeishuTaskCommentTool; } });
 var subtask_1 = require("./subtask.js");
 Object.defineProperty(exports, "registerFeishuTaskSubtaskTool", { enumerable: true, get: function () { return subtask_1.registerFeishuTaskSubtaskTool; } });
+var section_1 = require("./section.js");
+Object.defineProperty(exports, "registerFeishuTaskSectionTool", { enumerable: true, get: function () { return section_1.registerFeishuTaskSectionTool; } });

package/src/tools/oapi/task/section.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_task_section tool -- Manage Feishu task sections.
+ *
+ * P0 Actions: create, get, list, patch, tasks
+ *
+ * Uses the Feishu Task v2 API:
+ *   - create: POST /open-apis/task/v2/sections
+ *   - get:    GET  /open-apis/task/v2/sections/:section_guid
+ *   - patch:  PATCH /open-apis/task/v2/sections/:section_guid
+ *   - list:   GET  /open-apis/task/v2/sections
+ *   - tasks:  GET  /open-apis/task/v2/sections/:section_guid/tasks
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuTaskSectionTool(api: OpenClawPluginApi): void;