@larksuite/openclaw-lark 2026.4.1 → 2026.4.7

package/src/messaging/inbound/comment-handler.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Drive comment event handler for the Lark/Feishu channel plugin.
+ *
+ * Handles `drive.notice.comment_add_v1` events by resolving comment
+ * context, enforcing access policies, building a synthetic
+ * {@link MessageContext}, and dispatching to the agent.
+ *
+ * Modeled after the reaction handler pattern (reaction-handler.ts):
+ * bypasses the 7-stage message pipeline and dispatches directly.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleFeishuCommentEvent = handleFeishuCommentEvent;
+const crypto = __importStar(require("node:crypto"));
+const reply_history_1 = require("openclaw/plugin-sdk/reply-history");
+const accounts_1 = require("../../core/accounts.js");
+const comment_target_1 = require("../../core/comment-target.js");
+const lark_client_1 = require("../../core/lark-client.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const user_name_cache_1 = require("./user-name-cache.js");
+const dispatch_1 = require("./dispatch.js");
+const gate_1 = require("./gate.js");
+const policy_1 = require("./policy.js");
+const gate_effects_1 = require("./gate-effects.js");
+const comment_context_1 = require("./comment-context.js");
+const logger = (0, lark_logger_1.larkLogger)('inbound/comment-handler');
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Handle a Drive comment event.
+ *
+ * Resolves the comment context, checks access policies, builds a
+ * synthetic MessageContext, and dispatches to the agent.
+ */
+async function handleFeishuCommentEvent(params) {
+    const { cfg, event, botOpenId, runtime, chatHistories, accountId } = params;
+    const log = runtime?.log ?? ((...args) => logger.info(args.map(String).join(' ')));
+    const error = runtime?.error ?? ((...args) => logger.error(args.map(String).join(' ')));
+    // The parser has already normalized all fields from notice_meta into
+    // canonical top-level fields, so we just read the canonical shape.
+    const senderOpenId = event.user_id?.open_id ?? '';
+    const senderUserId = event.user_id?.user_id;
+    const senderUnionId = event.user_id?.union_id;
+    const fileToken = event.file_token ?? '';
+    const fileType = (event.file_type ?? 'docx');
+    const commentId = event.comment_id ?? '';
+    if (!senderOpenId || !fileToken || !commentId) {
+        log(`feishu[${accountId}]: comment event missing required fields, skipping`);
+        return;
+    }
+    // ---- Self-comment filter ----
+    // Ignore comments/replies authored by the bot itself.
+    if (senderOpenId === botOpenId) {
+        log(`feishu[${accountId}]: ignoring self-authored comment on ${fileToken}`);
+        return;
+    }
+    // ---- Account resolution ----
+    const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    const accountFeishuCfg = account.config;
+    const accountScopedCfg = {
+        ...cfg,
+        channels: { ...cfg.channels, feishu: accountFeishuCfg },
+    };
+    // ---- Access policy enforcement (DM-style) ----
+    // Comment events are user-to-bot interactions outside of IM, so we apply
+    // the same dmPolicy (open/allowlist/pairing) as DM messages.
+    // This mirrors the logic in gate.ts:checkDmGate.
+    const dmPolicy = accountFeishuCfg?.dmPolicy ?? 'pairing';
+    if (dmPolicy === 'disabled') {
+        log(`feishu[${accountId}]: comment event rejected (dmPolicy=disabled)`);
+        return;
+    }
+    if (dmPolicy !== 'open') {
+        // Read both config allowlist and pairing store (matches gate.ts behavior)
+        const configAllowFrom = accountFeishuCfg?.allowFrom ?? [];
+        const storeAllowFrom = await (0, gate_1.readFeishuAllowFromStore)(account.accountId).catch(() => []);
+        const combinedAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+        const match = (0, policy_1.resolveFeishuAllowlistMatch)({
+            allowFrom: combinedAllowFrom,
+            senderId: senderOpenId,
+        });
+        // Also check user_id if available
+        const userIdMatch = senderUserId
+            ? (0, policy_1.resolveFeishuAllowlistMatch)({
+                allowFrom: combinedAllowFrom,
+                senderId: senderUserId,
+            })
+            : { allowed: false };
+        if (!match.allowed && !userIdMatch.allowed) {
+            if (dmPolicy === 'pairing') {
+                // Create pairing request and send challenge (mirrors gate.ts:334).
+                // Prefer replying in the comment thread so the user sees the
+                // challenge in context; fall back to DM if comment reply fails.
+                log(`feishu[${accountId}]: comment sender not paired, creating pairing request`);
+                try {
+                    const core = lark_client_1.LarkClient.runtime;
+                    const { code } = await core.channel.pairing.upsertPairingRequest({
+                        channel: 'feishu',
+                        id: senderOpenId,
+                        accountId: account.accountId,
+                    });
+                    const pairingText = core.channel.pairing.buildPairingReply({
+                        channel: 'feishu',
+                        idLine: senderOpenId,
+                        code,
+                    });
+                    // Try comment thread reply first
+                    let sentInThread = false;
+                    try {
+                        const client = lark_client_1.LarkClient.fromCfg(accountScopedCfg, accountId);
+                        await client.sdk.request({
+                            method: 'POST',
+                            url: `/open-apis/drive/v1/files/${fileToken}/comments/${commentId}/replies`,
+                            params: { file_type: fileType, user_id_type: 'open_id' },
+                            data: {
+                                content: {
+                                    elements: [{ type: 'text_run', text_run: { text: pairingText } }],
+                                },
+                            },
+                        });
+                        sentInThread = true;
+                    }
+                    catch {
+                        // Comment reply failed — fall through to DM
+                    }
+                    // Fallback: send to DM
+                    if (!sentInThread) {
+                        await (0, gate_effects_1.sendPairingReply)({
+                            senderId: senderOpenId,
+                            chatId: senderOpenId,
+                            accountId: account.accountId,
+                            accountScopedCfg,
+                        });
+                    }
+                }
+                catch (pairingErr) {
+                    log(`feishu[${accountId}]: pairing request failed: ${String(pairingErr)}`);
+                }
+            }
+            else {
+                log(`feishu[${accountId}]: comment event rejected (dmPolicy=${dmPolicy}, not in allowlist)`);
+            }
+            return;
+        }
+    }
+    // ---- Resolve comment context ----
+    const turn = await (0, comment_context_1.resolveDriveCommentEventTurn)({ cfg, event, accountId });
+    if (!turn) {
+        log(`feishu[${accountId}]: failed to resolve comment context, skipping`);
+        return;
+    }
+    // ---- Mention filter ----
+    // The event-level is_mentioned flag is not stable for Drive comments.
+    // Fall back to the resolved comment text, where @mentions are normalized
+    // into "@<open_id>" by extractElementText().
+    const eventMentioned = event.notice_meta?.is_mentioned ?? event.is_mention;
+    const textMentioned = Boolean(botOpenId) && Boolean(turn.commentText?.includes(`@${botOpenId}`));
+    if (eventMentioned !== true && !textMentioned) {
+        log(`feishu[${accountId}]: comment event not mentioning bot, skipping` +
+            ` (eventFlag=${String(eventMentioned)}, textMention=${textMentioned})`);
+        return;
+    }
+    // ---- Build synthetic MessageContext ----
+    const commentTarget = (0, comment_target_1.buildFeishuCommentTarget)({
+        // Whole-document comment threads do not support in-thread replies
+        // through the replies API. For any event in that thread, fall back
+        // to creating a new whole-document comment instead.
+        deliveryMode: turn.isWholeComment ? 'create_whole' : 'reply',
+        fileType,
+        fileToken,
+        commentId,
+    });
+    const syntheticMessageId = `comment:${commentId}:${event.reply_id ?? 'root'}:${crypto.randomUUID()}`;
+    const syntheticText = turn.prompt;
+    let ctx = {
+        chatId: commentTarget, // Use comment target as the "chat" identifier
+        messageId: syntheticMessageId,
+        senderId: senderOpenId,
+        chatType: 'p2p', // Comment events are treated as direct interactions
+        content: syntheticText,
+        contentType: 'text',
+        resources: [],
+        mentions: [],
+        mentionAll: false,
+        rawMessage: {
+            message_id: syntheticMessageId,
+            chat_id: commentTarget,
+            chat_type: 'p2p',
+            message_type: 'text',
+            content: JSON.stringify({ text: syntheticText }),
+            create_time: event.action_time ?? String(Date.now()),
+        },
+        rawSender: {
+            sender_id: {
+                open_id: senderOpenId,
+                user_id: senderUserId,
+                union_id: senderUnionId,
+            },
+            sender_type: 'user',
+        },
+    };
+    // ---- Sender name resolution ----
+    const senderResult = await (0, user_name_cache_1.resolveUserName)({ account, openId: senderOpenId, log });
+    if (senderResult.name) {
+        ctx = { ...ctx, senderName: senderResult.name };
+    }
+    log(`feishu[${accountId}]: comment event on ${commentId}` +
+        `${event.reply_id ? ` (reply ${event.reply_id})` : ''}, dispatching to agent`);
+    logger.info(`comment event on ${commentId}` +
+        `${event.reply_id ? ` (reply ${event.reply_id})` : ''}`);
+    const historyLimit = Math.max(0, accountFeishuCfg?.historyLimit ?? accountScopedCfg.messages?.groupChat?.historyLimit ?? reply_history_1.DEFAULT_GROUP_HISTORY_LIMIT);
+    // ---- Dispatch to agent ----
+    try {
+        await (0, dispatch_1.dispatchToAgent)({
+            ctx,
+            permissionError: undefined,
+            mediaPayload: {},
+            quotedContent: undefined,
+            account,
+            accountScopedCfg,
+            runtime,
+            chatHistories,
+            historyLimit,
+            replyToMessageId: undefined, // No IM message to reply to
+            commandAuthorized: false,
+            skipTyping: true, // No IM typing indicator for comment events
+        });
+    }
+    catch (err) {
+        error(`feishu[${accountId}]: error dispatching comment event: ${String(err)}`);
+    }
+}

package/src/messaging/inbound/dispatch-commands.js

@@ -14,6 +14,7 @@ exports.dispatchSystemCommand = dispatchSystemCommand;
 const lark_logger_1 = require("../../core/lark-logger.js");
 const lark_ticket_1 = require("../../core/lark-ticket.js");
 const reply_dispatcher_1 = require("../../card/reply-dispatcher.js");
+const tool_use_trace_store_1 = require("../../card/tool-use-trace-store.js");
 const send_1 = require("../outbound/send.js");
 const dispatch_builders_1 = require("./dispatch-builders.js");
 const log = (0, lark_logger_1.larkLogger)('inbound/dispatch-commands');
@@ -44,15 +45,22 @@ async function dispatchPermissionNotification(dc, permissionError, replyToMessag
         messageSid: `${dc.ctx.messageId}:permission-error`,
         wasMentioned: false,
     });
+    (0, tool_use_trace_store_1.startToolUseTraceRun)(dc.threadSessionKey ?? dc.route.sessionKey);
     const { dispatcher: permDispatcher, replyOptions: permReplyOptions, markDispatchIdle: markPermIdle, markFullyComplete: markPermComplete, } = (0, reply_dispatcher_1.createFeishuReplyDispatcher)({
         cfg: dc.accountScopedCfg,
         agentId: dc.route.agentId,
-        sessionKey: dc.threadSessionKey ?? dc.route.sessionKey,
         chatId: dc.ctx.chatId,
+        sessionKey: dc.threadSessionKey ?? dc.route.sessionKey,
         replyToMessageId: replyToMessageId ?? dc.ctx.messageId,
         accountId: dc.account.accountId,
         chatType: dc.ctx.chatType,
         replyInThread: dc.isThread,
+        toolUseDisplay: {
+            mode: 'off',
+            showToolUse: false,
+            showToolResultDetails: false,
+            showFullPaths: false,
+        },
     });
     dc.log(`feishu[${dc.account.accountId}]: dispatching permission error notification to agent`);
     await dc.core.channel.reply.dispatchReplyFromConfig({
@@ -74,13 +82,17 @@ async function dispatchPermissionNotification(dc, permissionError, replyToMessag
  */
 async function dispatchSystemCommand(dc, ctxPayload, replyToMessageId) {
     let delivered = false;
+    const suppressToolDetails = isLifecycleSessionCommand(dc.ctx.content);
     dc.log(`feishu[${dc.account.accountId}]: detected system command, using plain-text dispatch`);
     log.info('system command detected, plain-text dispatch');
     await dc.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
         ctx: ctxPayload,
         cfg: dc.accountScopedCfg,
         dispatcherOptions: {
-            deliver: async (payload) => {
+            deliver: async (payload, info) => {
+                if (suppressToolDetails && info.kind === 'tool') {
+                    return;
+                }
                 const text = payload.text?.trim() ?? '';
                 if (!text)
                     return;
@@ -108,3 +120,12 @@ async function dispatchSystemCommand(dc, ctxPayload, replyToMessageId) {
     dc.log(`feishu[${dc.account.accountId}]: system command dispatched (delivered=${delivered})`);
     log.info(`system command dispatched (delivered=${delivered}, elapsed=${(0, lark_ticket_1.ticketElapsed)()}ms)`);
 }
+function isLifecycleSessionCommand(text) {
+    if (!text)
+        return false;
+    const match = text.trim().match(/^\/([^\s@]+)/);
+    if (!match)
+        return false;
+    const command = match[1]?.toLowerCase();
+    return command === 'new' || command === 'reset';
+}

package/src/messaging/inbound/dispatch-context.js

@@ -17,6 +17,7 @@ const routing_1 = require("openclaw/plugin-sdk/routing");
 const lark_client_1 = require("../../core/lark-client.js");
 const lark_logger_1 = require("../../core/lark-logger.js");
 const chat_info_cache_1 = require("../../core/chat-info-cache.js");
+const comment_target_1 = require("../../core/comment-target.js");
 const log = (0, lark_logger_1.larkLogger)('inbound/dispatch-context');
 // ---------------------------------------------------------------------------
 // RuntimeEnv fallback
@@ -46,26 +47,37 @@ function buildDispatchContext(params) {
     const runtime = ensureRuntime(params.runtime);
     const log = runtime.log;
     const error = runtime.error;
-    const isGroup = ctx.chatType === 'group';
+    const isComment = (0, comment_target_1.isCommentTarget)(ctx.chatId);
+    const isGroup = !isComment && ctx.chatType === 'group';
     const isThread = isGroup && Boolean(ctx.threadId);
     const core = lark_client_1.LarkClient.runtime;
     const feishuFrom = `feishu:${ctx.senderId}`;
-    const feishuTo = isGroup ? `chat:${ctx.chatId}` : `user:${ctx.senderId}`;
+    // Comment targets use the comment target string directly as the "To"
+    // so the outbound routing layer can detect it and route through Drive API.
+    const feishuTo = isComment
+        ? ctx.chatId
+        : isGroup
+            ? `chat:${ctx.chatId}`
+            : `user:${ctx.senderId}`;
     const envelopeFrom = isGroup ? `${ctx.chatId}:${ctx.senderId}` : ctx.senderId;
     const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(accountScopedCfg);
     // ---- Route resolution ----
+    // Comment targets use the comment target as the peer ID so each
+    // comment thread gets its own session key.
     const route = core.channel.routing.resolveAgentRoute({
         cfg: accountScopedCfg,
         channel: 'feishu',
         accountId: account.accountId,
-        peer: {
-            kind: isGroup ? 'group' : 'direct',
-            id: isGroup ? ctx.chatId : ctx.senderId,
-        },
+        peer: isComment
+            ? { kind: 'direct', id: ctx.chatId }
+            : {
+                kind: isGroup ? 'group' : 'direct',
+                id: isGroup ? ctx.chatId : ctx.senderId,
+            },
     });
     // ---- System event ----
     const sender = ctx.senderName ? `${ctx.senderName} (${ctx.senderId})` : ctx.senderId;
-    const location = isGroup ? `group ${ctx.chatId}` : 'DM';
+    const location = isComment ? `comment ${ctx.chatId}` : isGroup ? `group ${ctx.chatId}` : 'DM';
     const tags = [];
     tags.push(`msg:${ctx.messageId}`);
     if (ctx.parentId)

package/src/messaging/inbound/dispatch.js

@@ -21,9 +21,13 @@ const lark_logger_1 = require("../../core/lark-logger.js");
 const lark_ticket_1 = require("../../core/lark-ticket.js");
 const reply_dispatcher_1 = require("../../card/reply-dispatcher.js");
 const chat_queue_1 = require("../../channel/chat-queue.js");
+const tool_use_config_1 = require("../../card/tool-use-config.js");
+const tool_use_trace_store_1 = require("../../card/tool-use-trace-store.js");
 const abort_detect_1 = require("../../channel/abort-detect.js");
 const chat_info_cache_1 = require("../../core/chat-info-cache.js");
+const comment_target_1 = require("../../core/comment-target.js");
 const targets_1 = require("../../core/targets.js");
+const deliver_1 = require("../outbound/deliver.js");
 const doctor_1 = require("../../commands/doctor.js");
 const auth_1 = require("../../commands/auth.js");
 const index_1 = require("../../commands/index.js");
@@ -45,7 +49,58 @@ const log = (0, lark_logger_1.larkLogger)('inbound/dispatch');
  * system-command path — command handlers don't consume history context,
  * so the entries should be preserved for the next normal message.
  */
+/**
+ * Dispatch a comment-target message via the buffered block dispatcher.
+ *
+ * Comment targets cannot use the streaming card flow (IM APIs don't
+ * understand comment:... targets). Instead we use the SDK's buffered
+ * block dispatcher with a deliver callback that sends via the Drive
+ * comment reply API.
+ */
+async function dispatchCommentMessage(dc, ctxPayload, skillFilter) {
+    const effectiveSessionKey = dc.threadSessionKey ?? dc.route.sessionKey;
+    dc.log(`feishu[${dc.account.accountId}]: dispatching comment reply (session=${effectiveSessionKey})`);
+    log.info(`dispatching comment reply (session=${effectiveSessionKey})`);
+    let delivered = false;
+    await dc.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg: dc.accountScopedCfg,
+        dispatcherOptions: {
+            deliver: async (payload) => {
+                const text = payload.text?.trim() ?? '';
+                if (!text || text === 'NO_REPLY')
+                    return;
+                await (0, deliver_1.sendCommentReplyLark)({
+                    cfg: dc.accountScopedCfg,
+                    to: dc.ctx.chatId,
+                    text,
+                    accountId: dc.account.accountId,
+                });
+                delivered = true;
+            },
+            onSkip: (_payload, info) => {
+                if (info.reason !== 'silent') {
+                    dc.log(`feishu[${dc.account.accountId}]: comment reply skipped (reason=${info.reason})`);
+                }
+            },
+            onError: (err, info) => {
+                dc.error(`feishu[${dc.account.accountId}]: comment ${info.kind} reply failed: ${String(err)}`);
+            },
+        },
+        replyOptions: {
+            ...(skillFilter ? { skillFilter } : {}),
+        },
+    });
+    dc.log(`feishu[${dc.account.accountId}]: comment dispatch complete (delivered=${delivered})`);
+    log.info(`comment dispatch complete (delivered=${delivered}, elapsed=${(0, lark_ticket_1.ticketElapsed)()}ms)`);
+}
 async function dispatchNormalMessage(dc, ctxPayload, chatHistories, historyKey, historyLimit, replyToMessageId, skillFilter, skipTyping) {
+    // Comment targets bypass the streaming card / IM flow entirely —
+    // route through the Drive comment reply API.
+    if ((0, comment_target_1.isCommentTarget)(dc.ctx.chatId)) {
+        await dispatchCommentMessage(dc, ctxPayload, skillFilter);
+        return;
+    }
     // Abort messages should never create streaming cards — dispatch via the
     // plain-text system-command path so the SDK's abort handler can reply
     // without touching CardKit.
@@ -55,16 +110,31 @@ async function dispatchNormalMessage(dc, ctxPayload, chatHistories, historyKey,
         await (0, dispatch_commands_1.dispatchSystemCommand)(dc, ctxPayload, replyToMessageId);
         return;
     }
+    const effectiveSessionKey = dc.threadSessionKey ?? dc.route.sessionKey;
+    const toolUseDisplay = (0, tool_use_config_1.resolveToolUseDisplayConfig)({
+        cfg: dc.accountScopedCfg,
+        feishuCfg: dc.account.config,
+        agentId: dc.route.agentId,
+        sessionKey: effectiveSessionKey,
+        body: dc.ctx.content,
+    });
+    if (toolUseDisplay.showToolUse) {
+        (0, tool_use_trace_store_1.startToolUseTraceRun)(effectiveSessionKey);
+    }
+    else {
+        (0, tool_use_trace_store_1.clearToolUseTraceRun)(effectiveSessionKey);
+    }
     const { dispatcher, replyOptions, markDispatchIdle, markFullyComplete, abortCard } = (0, reply_dispatcher_1.createFeishuReplyDispatcher)({
         cfg: dc.accountScopedCfg,
         agentId: dc.route.agentId,
-        sessionKey: dc.threadSessionKey ?? dc.route.sessionKey,
         chatId: dc.ctx.chatId,
+        sessionKey: effectiveSessionKey,
         replyToMessageId: replyToMessageId ?? dc.ctx.messageId,
         accountId: dc.account.accountId,
         chatType: dc.ctx.chatType,
         skipTyping,
         replyInThread: dc.isThread,
+        toolUseDisplay,
     });
     // Create an AbortController so the abort fast-path can cancel the
     // underlying LLM request (not just the streaming card UI).
@@ -73,7 +143,6 @@ async function dispatchNormalMessage(dc, ctxPayload, chatHistories, historyKey,
     // terminate the streaming card before this task completes.
     const queueKey = (0, chat_queue_1.buildQueueKey)(dc.account.accountId, dc.ctx.chatId, dc.ctx.threadId);
     (0, chat_queue_1.registerActiveDispatcher)(queueKey, { abortCard, abortController });
-    const effectiveSessionKey = dc.threadSessionKey ?? dc.route.sessionKey;
     dc.log(`feishu[${dc.account.accountId}]: dispatching to agent (session=${effectiveSessionKey})`);
     log.info(`dispatching to agent (session=${effectiveSessionKey})`);
     try {
@@ -148,7 +217,10 @@ async function dispatchToAgent(params) {
     const messageBody = (0, dispatch_builders_1.buildMessageBody)(params.ctx, params.quotedContent);
     // 3. Permission-error notification (optional side-effect).
     //    Isolated so a failure here does not block the main message dispatch.
-    if (params.permissionError) {
+    //    Skipped for comment targets: the streaming card dispatcher inside
+    //    dispatchPermissionNotification sends via IM APIs which don't
+    //    understand comment:... targets.
+    if (params.permissionError && !(0, comment_target_1.isCommentTarget)(dc.ctx.chatId)) {
         try {
             await (0, dispatch_commands_1.dispatchPermissionNotification)(dc, params.permissionError, params.replyToMessageId);
         }
@@ -213,11 +285,15 @@ async function dispatchToAgent(params) {
     //     Must run BEFORE the SDK command check — the SDK does not recognise
     //     plugin-registered commands via isControlCommandMessage, so
     //     /feishu_* falls through to the AI agent otherwise.
+    //     Skipped for comment targets: comment text won't match /feishu_*
+    //     patterns in practice, and sendCardFeishu/sendMessageFeishu can't
+    //     deliver to comment:... targets.
     const contentTrimmed = (params.ctx.content ?? '').trim();
-    const isDoctorCommand = /^\/feishu[_ ]doctor\s*$/i.test(contentTrimmed);
-    const isAuthCommand = /^\/feishu[_ ](?:auth|onboarding)\s*$/i.test(contentTrimmed);
-    const isStartCommand = /^\/feishu[_ ]start\s*$/i.test(contentTrimmed);
-    const isHelpCommand = /^\/feishu(?:[_ ]help)?\s*$/i.test(contentTrimmed);
+    const isCommentFlow = (0, comment_target_1.isCommentTarget)(dc.ctx.chatId);
+    const isDoctorCommand = !isCommentFlow && /^\/feishu[_ ]doctor\s*$/i.test(contentTrimmed);
+    const isAuthCommand = !isCommentFlow && /^\/feishu[_ ](?:auth|onboarding)\s*$/i.test(contentTrimmed);
+    const isStartCommand = !isCommentFlow && /^\/feishu[_ ]start\s*$/i.test(contentTrimmed);
+    const isHelpCommand = !isCommentFlow && /^\/feishu(?:[_ ]help)?\s*$/i.test(contentTrimmed);
     const i18nCommandName = isDoctorCommand
         ? 'doctor'
         : isAuthCommand
@@ -269,7 +345,10 @@ async function dispatchToAgent(params) {
         return;
     }
     // 8. Dispatch: system command vs. normal message
-    const isCommand = dc.core.channel.commands.isControlCommandMessage(params.ctx.content, params.accountScopedCfg);
+    //    Comment targets always go to normal dispatch — system command
+    //    delivery uses sendMessageFeishu which can't reach comment threads.
+    const isCommand = !isCommentFlow &&
+        dc.core.channel.commands.isControlCommandMessage(params.ctx.content, params.accountScopedCfg);
     // Resolve per-group skill filter (per-group > default "*")
     const skillFilter = dc.isGroup ? (params.groupConfig?.skills ?? params.defaultGroupConfig?.skills) : undefined;
     if (isCommand) {

package/src/messaging/outbound/deliver.d.ts

@@ -153,3 +153,32 @@ export interface SendMediaLarkParams {
  * ```
  */
 export declare function sendMediaLark(params: SendMediaLarkParams): Promise<FeishuSendResult>;
+/**
+ * Parameters for sending a reply to a Drive comment thread.
+ */
+export interface SendCommentReplyLarkParams {
+    /** Plugin configuration. */
+    cfg: ClawdbotConfig;
+    /**
+     * Target in comment format: `comment:<fileType>:<fileToken>:<commentId>`.
+     * Parsed via `parseFeishuCommentTarget`.
+     */
+    to: string;
+    /** Reply text content. */
+    text: string;
+    /** Optional account identifier for multi-account setups. */
+    accountId?: string;
+}
+/**
+ * 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.
+ */
+export declare function sendCommentReplyLark(params: SendCommentReplyLarkParams): Promise<FeishuSendResult>;