@dsh-enhanced/lark-channel 0.1.17 → 0.1.18

package/lib/adapter.js

@@ -7,10 +7,14 @@ import { LarkPermissionPickerError, parseLarkPermissionPickerCallback, signLarkP
 import { LarkProgressPresenter } from './progress.js';
 import { LARK_APPROVAL_CARD_MAX_BYTES, renderLarkMessage } from './sdk.js';
 import { LarkToolApprovalError, signLarkToolApprovalAction, verifyLarkToolApprovalAction, } from './tool-approval.js';
+import { LarkUserQuestionError, parseLarkUserQuestionCallback, signLarkUserQuestionAction, verifyLarkUserQuestionAction, } from './user-question.js';
 import { LarkTransportError, } from './types.js';
 const LARK_TOOL_APPROVAL_REASON_MAX_BYTES = 2 * 1_024;
 const LARK_TOOL_APPROVAL_ARGUMENTS_MAX_BYTES = 16 * 1_024;
 const LARK_TOOL_APPROVAL_MAX_TIMER_MS = 2_147_483_647;
+const LARK_USER_QUESTION_MAX_QUESTIONS = 16;
+const LARK_USER_QUESTION_MAX_OPTIONS = 20;
+const LARK_USER_QUESTION_MAX_TEXT_BYTES = 16 * 1_024;
 const larkCallbackIdentifier = /^[A-Za-z0-9][A-Za-z0-9._@:-]{0,255}$/u;
 const larkProviderMessageIdentifier = /^[A-Za-z0-9][A-Za-z0-9._@/-]{0,255}$/u;
 function hasUsableApprovalSecret(secret) {
@@ -20,6 +24,61 @@ function boundedReviewText(value, maxBytes) {
     return value === undefined || (Buffer.byteLength(value, 'utf8') <= maxBytes
         && !/(?:\p{Cc}|\p{Bidi_Control})/u.test(value.replaceAll('\n', '').replaceAll('\r', '').replaceAll('\t', '')));
 }
+function samePrincipal(left, right) {
+    return left.channel === right.channel
+        && left.account === right.account
+        && left.tenant === right.tenant
+        && left.user === right.user;
+}
+function sameConversation(left, right) {
+    return left.channel === right.channel
+        && left.account === right.account
+        && left.tenant === right.tenant
+        && left.kind === right.kind
+        && left.chat === right.chat
+        && left.thread === right.thread;
+}
+function validUserQuestionRequest(input) {
+    if (!larkCallbackIdentifier.test(input.operationId)
+        || !larkCallbackIdentifier.test(input.bindingId)
+        || !larkCallbackIdentifier.test(input.sessionId)
+        || !Number.isSafeInteger(input.bindingVersion) || input.bindingVersion < 1
+        || !Number.isSafeInteger(input.bindingGeneration) || input.bindingGeneration < 1
+        || input.questions.length < 1 || input.questions.length > LARK_USER_QUESTION_MAX_QUESTIONS) {
+        return false;
+    }
+    const ids = new Set();
+    for (const question of input.questions) {
+        if (typeof question.id !== 'string' || question.id.length === 0 || ids.has(question.id)
+            || typeof question.question !== 'string' || question.question.trim().length === 0
+            || !boundedReviewText(question.question, LARK_USER_QUESTION_MAX_TEXT_BYTES)
+            || !boundedReviewText(question.detail, LARK_USER_QUESTION_MAX_TEXT_BYTES)
+            || !boundedReviewText(question.header, 1_024)) {
+            return false;
+        }
+        ids.add(question.id);
+        const options = question.options ?? [];
+        if (options.length > LARK_USER_QUESTION_MAX_OPTIONS)
+            return false;
+        const labels = new Set();
+        for (const option of options) {
+            if (typeof option.label !== 'string' || option.label.trim().length === 0
+                || labels.has(option.label)
+                || !boundedReviewText(option.label, 1_024)
+                || !boundedReviewText(option.description, 4_096)) {
+                return false;
+            }
+            labels.add(option.label);
+        }
+    }
+    return true;
+}
+function displayOptionLabel(label) {
+    const recommended = /(?:\s*\(Recommended\)|\s*（推荐）)\s*$/u;
+    return recommended.test(label)
+        ? { label: label.replace(recommended, '').trim() || label, recommended: true }
+        : { label, recommended: false };
+}
 function sameToolApprovalPayload(left, right) {
     return left.version === right.version
         && left.channel === right.channel
@@ -246,8 +305,11 @@ export class LarkDeliveryAdapter {
     loadModelPicker;
     advanceModelPicker;
     statusReactions;
+    userQuestionTtlMs;
     progressPresenter;
     pendingToolApprovals = new Map();
+    pendingUserQuestions = new Map();
+    userQuestionAnswerEvents = new Map();
     toolApprovalTombstones = new Map();
     modelSelectionUpdates = new Map();
     state = 'disconnected';
@@ -267,6 +329,7 @@ export class LarkDeliveryAdapter {
                 : ['plain', 'markdown', 'approval', 'model-picker'],
             inboundImages: typeof transport.downloadMessageImage === 'function',
             toolApprovals: hasUsableApprovalSecret(options.approvalSecret),
+            userQuestions: hasUsableApprovalSecret(options.approvalSecret),
         });
         this.now = options.now ?? Date.now;
         this.approvalSecret = options.approvalSecret;
@@ -278,15 +341,32 @@ export class LarkDeliveryAdapter {
         this.loadModelPicker = options.loadModelPicker;
         this.advanceModelPicker = options.advanceModelPicker;
         this.statusReactions = options.statusReactions ?? true;
+        this.userQuestionTtlMs = options.userQuestionTtlMs ?? 24 * 60 * 60 * 1_000;
         this.progressPresenter = new LarkProgressPresenter(transport, options.showProgress ?? true, options.progressDetails ?? 'direct', error => this.recordPresentationFailure(error));
     }
     async start(context) {
         this.state = 'connecting';
         const unsubscribe = this.transport.subscribe({
             message: async (message) => {
-                const normalized = normalizeLarkMessage(this.config, message, this.now());
+                // A reply to a live question card is already an explicit interaction
+                // with the bot. Lark does not necessarily mark that reply as an @mention,
+                // so let only this narrowly identified candidate pass normalization's
+                // group mention gate. If the full owner/route/message fences below do
+                // not accept it as an answer, ignore it instead of enqueueing a turn.
+                const unmentionedQuestionReply = message.chatType === 'group'
+                    && this.config.requireMentionInGroups
+                    && !message.mentionedBot
+                    && message.replyToMessageId !== undefined
+                    && [...this.pendingUserQuestions.values()].some(pending => pending.providerMessageId === message.replyToMessageId);
+                const normalized = normalizeLarkMessage(unmentionedQuestionReply
+                    ? { ...this.config, requireMentionInGroups: false }
+                    : this.config, message, this.now());
                 if (normalized.outcome !== 'accept')
                     return;
+                if (await this.tryAnswerUserQuestion(normalized.envelope, message.messageId))
+                    return;
+                if (unmentionedQuestionReply)
+                    return;
                 const accepted = await context.accept(normalized.envelope);
                 if (this.statusReactions && !accepted.duplicate && accepted.status === 'queued') {
                     // The durable Inbox acknowledgement is the critical path. A slow or
@@ -317,6 +397,7 @@ export class LarkDeliveryAdapter {
             unsubscribe();
             this.state = 'disconnected';
             this.cancelPendingToolApprovals('unavailable', true);
+            this.cancelPendingUserQuestions();
             await this.transport.disconnect().catch(() => { });
             throw error;
         }
@@ -328,6 +409,8 @@ export class LarkDeliveryAdapter {
             unsubscribe();
             this.state = 'disconnected';
             this.cancelPendingToolApprovals('unavailable', true);
+            this.cancelPendingUserQuestions();
+            this.clearUserQuestionAnswerEvents();
             this.cancelModelSelectionUpdates();
             await this.transport.disconnect();
         };
@@ -458,6 +541,117 @@ export class LarkDeliveryAdapter {
         });
         return outcome;
     }
+    async requestUserQuestion(input, signal) {
+        if (signal.aborted
+            || !hasUsableApprovalSecret(this.approvalSecret)
+            || (this.state !== 'connected' && this.state !== 'connected-with-gap')
+            || !this.matchesTarget(input.target)
+            || !larkCallbackIdentifier.test(input.target.conversation.chat)
+            || !larkCallbackIdentifier.test(input.target.principal.user)
+            || !validUserQuestionRequest(input)) {
+            return { outcome: 'unavailable' };
+        }
+        let now;
+        try {
+            now = this.now();
+        }
+        catch {
+            return { outcome: 'unavailable' };
+        }
+        const expiresAt = now + this.userQuestionTtlMs;
+        if (!Number.isSafeInteger(now) || now < 0
+            || !Number.isSafeInteger(this.userQuestionTtlMs) || this.userQuestionTtlMs < 1
+            || !Number.isSafeInteger(expiresAt)) {
+            return { outcome: 'unavailable' };
+        }
+        const requestHash = createHash('sha256')
+            .update(JSON.stringify(input.questions), 'utf8')
+            .digest('hex');
+        const existing = this.pendingUserQuestions.get(input.operationId);
+        if (existing !== undefined) {
+            return existing.requestHash === requestHash
+                && existing.input.sessionId === input.sessionId
+                && existing.input.bindingId === input.bindingId
+                && existing.input.bindingVersion === input.bindingVersion
+                && existing.input.bindingGeneration === input.bindingGeneration
+                && samePrincipal(existing.input.target.principal, input.target.principal)
+                && sameConversation(existing.input.target.conversation, input.target.conversation)
+                ? existing.outcome
+                : { outcome: 'unavailable' };
+        }
+        let resolve;
+        const outcome = new Promise(settle => { resolve = settle; });
+        let pending;
+        const abort = () => {
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+        };
+        pending = {
+            input,
+            payload: {
+                version: 1,
+                channel: this.channel,
+                account: this.account,
+                tenant: this.config.tenant,
+                rpcId: input.operationId,
+                sessionId: input.sessionId,
+                bindingId: input.bindingId,
+                bindingVersion: input.bindingVersion,
+                bindingGeneration: input.bindingGeneration,
+                chatId: input.target.conversation.chat,
+                ownerUser: input.target.principal.user,
+                requestHash,
+                expiresAt,
+            },
+            requestHash,
+            signal,
+            abort,
+            resolve,
+            outcome,
+            answers: [],
+            selectedOptionIndexes: new Set(),
+            questionIndex: 0,
+            revision: 0,
+        };
+        let card;
+        try {
+            card = { userQuestion: this.userQuestionCard(pending) };
+            if (Buffer.byteLength(renderLarkMessage(card).content, 'utf8') > LARK_APPROVAL_CARD_MAX_BYTES) {
+                return { outcome: 'unavailable' };
+            }
+        }
+        catch {
+            return { outcome: 'unavailable' };
+        }
+        this.pendingUserQuestions.set(input.operationId, pending);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) {
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', false);
+            return outcome;
+        }
+        this.armUserQuestionExpiry(pending);
+        let sending;
+        try {
+            sending = Promise.resolve(this.transport.send(input.target.conversation.chat, card, this.userQuestionSendOptions(pending)));
+        }
+        catch (error) {
+            this.recordPresentationFailure(error);
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', false);
+            return outcome;
+        }
+        void sending.then(result => {
+            if (this.pendingUserQuestions.get(input.operationId) !== pending)
+                return;
+            if (!larkProviderMessageIdentifier.test(result.messageId)) {
+                this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', false);
+                return;
+            }
+            pending.providerMessageId = result.messageId;
+        }, error => {
+            this.recordPresentationFailure(error);
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', false);
+        });
+        return outcome;
+    }
     async readInboundImage(input, signal) {
         if (input.attachment.resourceType !== 'image') {
             return { outcome: 'not-downloaded', failureCode: 'lark-image-type-unsupported', retryable: false };
@@ -676,6 +870,237 @@ export class LarkDeliveryAdapter {
             && conversation.tenant === this.config.tenant
             && principal.tenant === this.config.tenant;
     }
+    userQuestionCard(pending) {
+        if (!hasUsableApprovalSecret(this.approvalSecret)) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question signing is unavailable');
+        }
+        const question = pending.input.questions[pending.questionIndex];
+        if (question === undefined) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question index is invalid');
+        }
+        const callbackValue = (action, optionIndex) => ({
+            userQuestion: signLarkUserQuestionAction(this.approvalSecret, {
+                ...pending.payload,
+                questionIndex: pending.questionIndex,
+                optionIndex,
+                action,
+                revision: pending.revision,
+            }),
+        });
+        const options = (question.options ?? []).map((option, optionIndex) => {
+            const display = displayOptionLabel(option.label);
+            return {
+                label: display.label,
+                ...(option.description === undefined ? {} : { description: option.description }),
+                recommended: display.recommended,
+                selected: pending.selectedOptionIndexes.has(optionIndex),
+                value: callbackValue(question.multiSelect === true ? 'toggle' : 'select', optionIndex),
+            };
+        });
+        return {
+            title: question.header?.trim() || '需要你的回答',
+            question: question.question.trim(),
+            ...(question.detail === undefined ? {} : { detail: question.detail }),
+            position: pending.questionIndex + 1,
+            total: pending.input.questions.length,
+            multiSelect: question.multiSelect === true,
+            expectsText: options.length === 0,
+            options,
+            ...(question.multiSelect === true && pending.selectedOptionIndexes.size > 0
+                ? { submitValue: callbackValue('submit', null) }
+                : {}),
+            cancelValue: callbackValue('cancel', null),
+            answered: pending.answers.map((answer, index) => ({
+                title: pending.input.questions[index]?.header?.trim() || `问题 ${index + 1}`,
+                answer: this.userQuestionAnswerSummary(answer),
+            })),
+        };
+    }
+    userQuestionAnswerSummary(answer) {
+        const parts = [...answer.selected, ...(answer.custom === undefined ? [] : [answer.custom])];
+        const value = parts.join('；');
+        return value.length <= 240 ? value : `${value.slice(0, 237)}...`;
+    }
+    userQuestionSendOptions(pending) {
+        const conversation = pending.input.target.conversation;
+        const providerReplyTarget = conversation.kind === 'group'
+            && !isLarkTopLevelSenderThread(conversation.thread)
+            ? conversation.thread
+            : undefined;
+        return {
+            requestKey: `user-question:${pending.input.operationId}:${pending.requestHash}:${pending.revision}`,
+            ...(providerReplyTarget === undefined ? {} : { replyTo: providerReplyTarget, replyInThread: true }),
+        };
+    }
+    async refreshUserQuestionCard(pending) {
+        if (this.pendingUserQuestions.get(pending.input.operationId) !== pending)
+            return;
+        const card = { userQuestion: this.userQuestionCard(pending) };
+        if (Buffer.byteLength(renderLarkMessage(card).content, 'utf8') > LARK_APPROVAL_CARD_MAX_BYTES) {
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+            return;
+        }
+        const update = this.transport.updateRawCard;
+        if (pending.providerMessageId !== undefined && update !== undefined) {
+            try {
+                await update.call(this.transport, pending.providerMessageId, rawCard(card), new AbortController().signal);
+                return;
+            }
+            catch (error) {
+                this.recordPresentationFailure(error);
+            }
+        }
+        try {
+            const result = await this.transport.send(pending.input.target.conversation.chat, card, this.userQuestionSendOptions(pending));
+            if (this.pendingUserQuestions.get(pending.input.operationId) !== pending)
+                return;
+            if (!larkProviderMessageIdentifier.test(result.messageId)) {
+                this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+                return;
+            }
+            pending.providerMessageId = result.messageId;
+        }
+        catch (error) {
+            this.recordPresentationFailure(error);
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+        }
+    }
+    userQuestionResult(status, answerCount) {
+        if (status === 'answered') {
+            return { status, summary: `已提交 ${answerCount} 个回答，智能体正在继续处理。` };
+        }
+        if (status === 'cancelled') {
+            return { status, summary: '问题已取消，智能体将停止等待本次回答。' };
+        }
+        return { status, summary: '问题已在其他界面处理，或当前会话已经结束。' };
+    }
+    updateUserQuestionResult(pending, status) {
+        const update = this.transport.updateRawCard;
+        if (pending.providerMessageId === undefined || update === undefined)
+            return;
+        const card = rawCard({ userQuestionResult: this.userQuestionResult(status, pending.answers.length) });
+        void update.call(this.transport, pending.providerMessageId, card, new AbortController().signal).catch(error => this.recordPresentationFailure(error));
+    }
+    settleUserQuestion(pending, outcome, status, updatePresentation) {
+        if (this.pendingUserQuestions.get(pending.input.operationId) !== pending)
+            return false;
+        this.pendingUserQuestions.delete(pending.input.operationId);
+        pending.signal.removeEventListener('abort', pending.abort);
+        if (pending.timer !== undefined)
+            clearTimeout(pending.timer);
+        pending.resolve(outcome);
+        if (updatePresentation)
+            this.updateUserQuestionResult(pending, status);
+        return true;
+    }
+    armUserQuestionExpiry(pending) {
+        const expire = () => {
+            if (this.pendingUserQuestions.get(pending.input.operationId) !== pending)
+                return;
+            let remaining;
+            try {
+                remaining = pending.payload.expiresAt - this.now();
+            }
+            catch {
+                this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+                return;
+            }
+            if (!Number.isSafeInteger(remaining)) {
+                this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+                return;
+            }
+            if (remaining <= 0) {
+                this.settleUserQuestion(pending, { outcome: 'cancelled' }, 'cancelled', true);
+                return;
+            }
+            pending.timer = setTimeout(expire, Math.min(remaining, LARK_TOOL_APPROVAL_MAX_TIMER_MS));
+            pending.timer.unref();
+        };
+        expire();
+    }
+    cancelPendingUserQuestions() {
+        for (const pending of this.pendingUserQuestions.values()) {
+            this.settleUserQuestion(pending, { outcome: 'unavailable' }, 'resolved', true);
+        }
+    }
+    recordUserQuestionAnswer(pending, answer) {
+        pending.answers.push(answer);
+        pending.selectedOptionIndexes.clear();
+        if (pending.questionIndex + 1 < pending.input.questions.length) {
+            pending.questionIndex += 1;
+            pending.revision += 1;
+            return undefined;
+        }
+        return { outcome: 'answered', answer: { answers: [...pending.answers] } };
+    }
+    rememberUserQuestionAnswerEvent(eventId) {
+        if (this.userQuestionAnswerEvents.has(eventId))
+            return;
+        const timer = setTimeout(() => {
+            this.userQuestionAnswerEvents.delete(eventId);
+        }, Math.max(this.config.staleAfterMs, 60_000));
+        timer.unref();
+        this.userQuestionAnswerEvents.set(eventId, timer);
+    }
+    clearUserQuestionAnswerEvents() {
+        for (const timer of this.userQuestionAnswerEvents.values())
+            clearTimeout(timer);
+        this.userQuestionAnswerEvents.clear();
+    }
+    async tryAnswerUserQuestion(envelope, providerMessageId) {
+        if (this.userQuestionAnswerEvents.has(providerMessageId))
+            return true;
+        if (envelope.kind !== 'text' || envelope.attachments !== undefined)
+            return false;
+        const replyTo = envelope.metadata?.replyToProviderMessageId;
+        const routeCandidates = [...this.pendingUserQuestions.values()].filter(pending => samePrincipal(pending.input.target.principal, envelope.principal)
+            && sameConversation(pending.input.target.conversation, envelope.conversation));
+        let pending;
+        if (replyTo !== undefined) {
+            pending = [...this.pendingUserQuestions.values()].find(candidate => candidate.providerMessageId === replyTo
+                && samePrincipal(candidate.input.target.principal, envelope.principal)
+                && candidate.input.target.conversation.channel === envelope.conversation.channel
+                && candidate.input.target.conversation.account === envelope.conversation.account
+                && candidate.input.target.conversation.tenant === envelope.conversation.tenant
+                && candidate.input.target.conversation.kind === envelope.conversation.kind
+                && candidate.input.target.conversation.chat === envelope.conversation.chat);
+        }
+        else if (routeCandidates.length === 1) {
+            pending = routeCandidates[0];
+        }
+        if (pending === undefined || pending.providerMessageId === undefined)
+            return false;
+        const question = pending.input.questions[pending.questionIndex];
+        if (question === undefined)
+            return false;
+        const typed = envelope.text.trim();
+        if (typed.length === 0)
+            return false;
+        const exactOption = (question.options ?? []).find(option => option.label === typed);
+        const staged = [...pending.selectedOptionIndexes].sort((left, right) => left - right)
+            .flatMap(index => question.options?.[index]?.label ?? []);
+        const selected = exactOption === undefined
+            ? staged
+            : question.multiSelect === true
+                ? [...new Set([...staged, exactOption.label])]
+                : [exactOption.label];
+        const custom = exactOption === undefined ? typed : undefined;
+        const result = this.recordUserQuestionAnswer(pending, {
+            id: question.id,
+            selected,
+            ...(custom === undefined ? {} : { custom }),
+        });
+        this.rememberUserQuestionAnswerEvent(providerMessageId);
+        if (result === undefined) {
+            await this.refreshUserQuestionCard(pending);
+        }
+        else {
+            this.settleUserQuestion(pending, result, 'answered', true);
+        }
+        if (this.statusReactions)
+            void this.addReaction(providerMessageId, 'DONE');
+        return true;
+    }
     armToolApprovalTombstone(operationId, tombstone) {
         const expire = () => {
             if (this.toolApprovalTombstones.get(operationId) !== tombstone)
@@ -825,6 +1250,9 @@ export class LarkDeliveryAdapter {
                 }
                 return this.handleToolApprovalAction(action, value.toolApproval);
             }
+            if (Object.prototype.hasOwnProperty.call(value, 'userQuestion')) {
+                return await this.handleUserQuestionAction(action, parseLarkUserQuestionCallback(value));
+            }
             if (Object.prototype.hasOwnProperty.call(value, 'permissionPicker')) {
                 return await this.handlePermissionPickerAction(action, parseLarkPermissionPickerCallback(value));
             }
@@ -895,6 +1323,11 @@ export class LarkDeliveryAdapter {
                             ? '权限卡片已过期，请重新发送 /permission'
                             : '权限卡片无效或已失效，请重新发送 /permission' } };
             }
+            if (error instanceof LarkUserQuestionError) {
+                return { toast: { type: 'warning', content: error.code === 'expired'
+                            ? '问题卡片已过期，请重新向智能体发起请求'
+                            : '问题卡片已更新或失效，请使用最新卡片' } };
+            }
             if (error instanceof LarkApprovalError || error instanceof LarkModelPickerError
                 || error instanceof LarkToolApprovalError) {
                 this.lastErrorCode = 'format_error';
@@ -979,6 +1412,101 @@ export class LarkDeliveryAdapter {
         return { toast: { type: payload.decision === 'allowed-once' ? 'success' : 'info',
                 content: payload.decision === 'allowed-once' ? '已仅允许本次工具调用' : '已拒绝工具调用' } };
     }
+    async handleUserQuestionAction(action, callback) {
+        if (!hasUsableApprovalSecret(this.approvalSecret) || action.tag !== 'button'
+            || !larkProviderMessageIdentifier.test(action.messageId)) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question callback is unavailable');
+        }
+        const payload = verifyLarkUserQuestionAction(this.approvalSecret, callback.userQuestion, this.now());
+        if (payload.channel !== this.channel || payload.account !== this.account
+            || payload.tenant !== this.config.tenant || payload.chatId !== action.chatId
+            || payload.ownerUser !== action.operatorId) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question route does not match');
+        }
+        const pending = this.pendingUserQuestions.get(payload.rpcId);
+        if (pending === undefined
+            || pending.providerMessageId !== action.messageId
+            || pending.payload.version !== payload.version
+            || pending.payload.channel !== payload.channel
+            || pending.payload.account !== payload.account
+            || pending.payload.tenant !== payload.tenant
+            || pending.payload.rpcId !== payload.rpcId
+            || pending.payload.sessionId !== payload.sessionId
+            || pending.payload.bindingId !== payload.bindingId
+            || pending.payload.bindingVersion !== payload.bindingVersion
+            || pending.payload.bindingGeneration !== payload.bindingGeneration
+            || pending.payload.chatId !== payload.chatId
+            || pending.payload.ownerUser !== payload.ownerUser
+            || pending.payload.requestHash !== payload.requestHash
+            || pending.payload.expiresAt !== payload.expiresAt
+            || pending.questionIndex !== payload.questionIndex
+            || pending.revision !== payload.revision) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question request does not match');
+        }
+        const question = pending.input.questions[pending.questionIndex];
+        if (question === undefined) {
+            throw new LarkUserQuestionError('invalid', 'Lark user question index is invalid');
+        }
+        if (payload.action === 'cancel') {
+            this.settleUserQuestion(pending, { outcome: 'cancelled' }, 'cancelled', false);
+            return {
+                toast: { type: 'info', content: '已取消本次问题' },
+                ...callbackCard({ userQuestionResult: this.userQuestionResult('cancelled', pending.answers.length) }),
+            };
+        }
+        const options = question.options ?? [];
+        if (payload.action === 'toggle') {
+            if (question.multiSelect !== true || payload.optionIndex === null
+                || options[payload.optionIndex] === undefined) {
+                throw new LarkUserQuestionError('invalid', 'Lark user question option is invalid');
+            }
+            if (pending.selectedOptionIndexes.has(payload.optionIndex)) {
+                pending.selectedOptionIndexes.delete(payload.optionIndex);
+            }
+            else {
+                pending.selectedOptionIndexes.add(payload.optionIndex);
+            }
+            pending.revision += 1;
+            return {
+                toast: { type: 'info', content: pending.selectedOptionIndexes.size === 0
+                        ? '已清空选择'
+                        : `已选择 ${pending.selectedOptionIndexes.size} 项` },
+                ...callbackCard({ userQuestion: this.userQuestionCard(pending) }),
+            };
+        }
+        let answer;
+        if (payload.action === 'select') {
+            if (question.multiSelect === true || payload.optionIndex === null
+                || options[payload.optionIndex] === undefined) {
+                throw new LarkUserQuestionError('invalid', 'Lark user question option is invalid');
+            }
+            answer = { id: question.id, selected: [options[payload.optionIndex].label] };
+        }
+        else {
+            if (question.multiSelect !== true || payload.optionIndex !== null
+                || pending.selectedOptionIndexes.size === 0) {
+                throw new LarkUserQuestionError('invalid', 'Lark user question selection is empty');
+            }
+            answer = {
+                id: question.id,
+                selected: [...pending.selectedOptionIndexes]
+                    .sort((left, right) => left - right)
+                    .map(index => options[index].label),
+            };
+        }
+        const result = this.recordUserQuestionAnswer(pending, answer);
+        if (result === undefined) {
+            return {
+                toast: { type: 'success', content: '回答已记录，请继续下一题' },
+                ...callbackCard({ userQuestion: this.userQuestionCard(pending) }),
+            };
+        }
+        this.settleUserQuestion(pending, result, 'answered', false);
+        return {
+            toast: { type: 'success', content: '回答已提交，智能体将继续处理' },
+            ...callbackCard({ userQuestionResult: this.userQuestionResult('answered', pending.answers.length) }),
+        };
+    }
     async handleModelPickerAction(action, callback) {
         if (this.approvalSecret === undefined || this.settleModelSelection === undefined
             || !larkProviderMessageIdentifier.test(action.messageId)) {