@tencent-connect/dsh-qqbot 0.4.0 → 0.5.1

package/dist/features/button-utils.js

@@ -0,0 +1,27 @@
+/** QQ 按钮 label 有长度限制，超长截断（正文保留完整文本；多列布局下阈值更短） */
+export const BUTTON_LABEL_MAX = 10;
+/** 单选按钮每行个数（多列布局，减少选项多时的刷屏） */
+export const BUTTONS_PER_ROW = 2;
+/** 截断按钮 label，超长补省略号 */
+export function buttonLabel(text) {
+    const s = String(text ?? '').trim();
+    return s.length > BUTTON_LABEL_MAX ? s.slice(0, BUTTON_LABEL_MAX - 1) + '…' : s;
+}
+/** 编码 button_data（JSON 字符串） */
+export function encodeButtonData(data) {
+    return JSON.stringify(data);
+}
+/** 解码 button_data；非法 JSON 或缺少合法 `t` 时返回 undefined */
+export function decodeButtonData(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object' && (parsed.t === 'question' || parsed.t === 'approval')) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+//# sourceMappingURL=button-utils.js.map

package/dist/features/button-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button-utils.js","sourceRoot":"","sources":["../../src/features/button-utils.ts"],"names":[],"mappings":"AASA,iDAAiD;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAEnC,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,wBAAwB;AACxB,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,OAAO,CAAC,CAAC,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAmBD,+BAA+B;AAC/B,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QACtD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,UAAU,IAAI,MAAM,CAAC,CAAC,KAAK,UAAU,CAAC,EAAE,CAAC;YAC1G,OAAO,MAAoB,CAAC;QAC9B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/features/history-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history-store.d.ts","sourceRoot":"","sources":["../../src/features/history-store.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,mBAAmB;AACnB,wBAAgB,eAAe,IAAI,YAAY,CAG9C;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtE"}
+{"version":3,"file":"history-store.d.ts","sourceRoot":"","sources":["../../src/features/history-store.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,mBAAmB;AACnB,wBAAgB,eAAe,IAAI,YAAY,CAG9C;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtE"}

package/dist/features/history-store.js

@@ -3,7 +3,6 @@
  *
  * historyBuffer 中间件需要一个跨调用可访问的 HistoryStore 实例，
  * 以便在回复完成后清空某群的历史缓存（避免下次 @ 时重复组包）。
- * 对齐 openclaw-qqbot 的 features/history-store。
  */
 import { MemoryHistoryStore } from '@tencent-connect/qqbot-nodejs';
 let _store = null;

package/dist/features/history-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"history-store.js","sourceRoot":"","sources":["../../src/features/history-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAGnE,IAAI,MAAM,GAAwB,IAAI,CAAC;AAEvC,mBAAmB;AACnB,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,MAAM;QAAE,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,OAAe;IAC5D,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,OAAe;IAC9D,MAAM,EAAE,KAAK,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"history-store.js","sourceRoot":"","sources":["../../src/features/history-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAGnE,IAAI,MAAM,GAAwB,IAAI,CAAC;AAEvC,mBAAmB;AACnB,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,MAAM;QAAE,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,OAAe;IAC5D,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,OAAe;IAC9D,MAAM,EAAE,KAAK,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/features/question-channel.d.ts

@@ -0,0 +1,96 @@
+/**
+ * QuestionChannel — 把 dsh 的 ask_user_question 桥接到 QQ 通道。
+ *
+ * 接入方式：包装 `userQuestions.ask`（而非 registerProvider），按 `request.agent.id`
+ * 路由到 QQ 会话；非 QQ 会话委托宿主默认 provider（如 Web 弹出框），多通道共存。
+ *
+ * 每会话一个显式状态机，三态语义：
+ *   - 待答（pending 中）：等待当前题的回答
+ *   - 逐题推进：多问题时一次问一题，答完一题再问下一题
+ *   - 完成 / 中断（abort / 超时 / 会话回收）：reject(ASK_ABORTED)
+ */
+import type { InlineKeyboard, InteractionEvent } from '@tencent-connect/qqbot-nodejs';
+import type { ChatScope, Logger, ReplyTarget } from '../types.ts';
+export interface UserQuestionOption {
+    label: string;
+    description?: string;
+}
+export interface UserQuestion {
+    id: string;
+    header?: string;
+    question: string;
+    options?: UserQuestionOption[];
+    multiSelect?: boolean;
+}
+export interface UserQuestionAnswer {
+    id: string;
+    selected: string[];
+    custom?: string;
+}
+export interface UserQuestionRequest {
+    questions: UserQuestion[];
+    agent?: {
+        id?: string;
+    };
+    signal?: AbortSignal;
+}
+export interface UserQuestionResult {
+    answers: UserQuestionAnswer[];
+}
+export interface UserQuestionsServiceLike {
+    ask: (request: UserQuestionRequest) => Promise<UserQuestionResult>;
+    __qqQuestionPatched?: boolean;
+}
+export interface QuestionSessionRecordLike {
+    sessionKey: string;
+    scope: ChatScope;
+    replyTarget: ReplyTarget;
+}
+export interface QuestionChannelManagerLike {
+    findBySessionId(sessionId: string): QuestionSessionRecordLike | undefined;
+    getSessionRecord(scope: ChatScope, peerId: string): QuestionSessionRecordLike | undefined;
+}
+export interface QuestionChannelSenderLike {
+    sendMarkdown(target: ReplyTarget, content: string, opts?: {
+        keyboard?: InlineKeyboard;
+    }): Promise<unknown>;
+}
+export interface QuestionChannelConfigLike {
+    requireMention: boolean;
+    askTimeoutMs: number;
+}
+export declare class QuestionChannel {
+    private readonly pending;
+    private uq?;
+    private origAsk?;
+    private readonly manager;
+    private readonly sender;
+    private readonly config;
+    private readonly logger;
+    constructor(manager: QuestionChannelManagerLike, sender: QuestionChannelSenderLike, config: QuestionChannelConfigLike, logger: Logger);
+    /**
+     * 包装 userQuestions.ask：QQ 会话走 QQ 通道，其余委托原实现。
+     * 幂等（已 patch 则跳过）；服务缺失或 ask 非函数时优雅禁用。
+     */
+    install(ctx: {
+        get(name: string): unknown;
+    }): void;
+    uninstall(): void;
+    /** 会话回收时清理其待答问题，避免 pending 悬挂导致 Promise 与闭包泄漏 */
+    cancelPending(sessionKey: string): void;
+    /** 入站文本作答：该会话若有待答问题且本条消息有文本，解析为答案并推进 */
+    tryAnswer(scope: ChatScope, peerId: string, text: string): boolean;
+    /** 按钮点击作答：解码 button_data 选项下标，推进状态机 */
+    handleInteraction(event: InteractionEvent): boolean;
+    /** 走 QQ 通道：发送首题 + 挂起 Promise，等待逐题作答 */
+    private askViaQQ;
+    /** 推进状态机：收集答案 → 有下一题则发送，否则 resolve 全部答案 */
+    private advance;
+    /** 发送单个问题：优先带按钮，按钮发送失败降级纯文本 */
+    private sendQuestion;
+    private onTimeout;
+    private resetTimer;
+    private clearTimer;
+    private removeAbort;
+}
+//# sourceMappingURL=question-channel.d.ts.map

package/dist/features/question-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-channel.d.ts","sourceRoot":"","sources":["../../src/features/question-channel.ts"],"names":[],"mappings":"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"}

package/dist/features/question-channel.js

@@ -0,0 +1,234 @@
+import { parseAnswer } from "./answer-parser.js";
+import { buildKeyboard, formatQuestion } from "./question-renderer.js";
+import { decodeButtonData } from "./button-utils.js";
+// ── 错误语义（对齐 dsh-user-questions 的 UserQuestionError code 约定） ──
+/** 问答中断错误码：上层（如 plan-mode）按 code 区分「用户未作答」与普通发送/网络错误 */
+const ASK_ABORTED = 'ASK_ABORTED';
+class QuestionChannelError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'QuestionChannelError';
+    }
+}
+export class QuestionChannel {
+    pending = new Map();
+    uq;
+    origAsk;
+    manager;
+    sender;
+    config;
+    logger;
+    constructor(manager, sender, config, logger) {
+        this.manager = manager;
+        this.sender = sender;
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * 包装 userQuestions.ask：QQ 会话走 QQ 通道，其余委托原实现。
+     * 幂等（已 patch 则跳过）；服务缺失或 ask 非函数时优雅禁用。
+     */
+    install(ctx) {
+        const uq = ctx.get('userQuestions');
+        if (!uq || uq.__qqQuestionPatched)
+            return;
+        if (typeof uq.ask !== 'function') {
+            this.logger.warn('im-qqbot: userQuestions service lacks ask() — QQ question channel disabled');
+            return;
+        }
+        const self = this;
+        this.origAsk = uq.ask.bind(uq);
+        uq.ask = async function qqRoutedAsk(request) {
+            const sessionId = request?.agent?.id;
+            const record = sessionId ? self.manager.findBySessionId(sessionId) : undefined;
+            if (record)
+                return self.askViaQQ(record, request);
+            return self.origAsk(request);
+        };
+        Object.defineProperty(uq, '__qqQuestionPatched', { value: true, configurable: true, enumerable: false });
+        this.uq = uq;
+        this.logger.info('im-qqbot: QQ question channel installed');
+    }
+    uninstall() {
+        if (this.uq && this.origAsk) {
+            this.uq.ask = this.origAsk;
+            delete this.uq.__qqQuestionPatched;
+            this.uq = undefined;
+            this.origAsk = undefined;
+        }
+        for (const [, entry] of this.pending) {
+            this.clearTimer(entry);
+            this.removeAbort(entry);
+            entry.reject(new QuestionChannelError('QQ question channel was unloaded before the user answered', ASK_ABORTED));
+        }
+        this.pending.clear();
+    }
+    /** 会话回收时清理其待答问题，避免 pending 悬挂导致 Promise 与闭包泄漏 */
+    cancelPending(sessionKey) {
+        const entry = this.pending.get(sessionKey);
+        if (!entry)
+            return;
+        this.pending.delete(sessionKey);
+        this.clearTimer(entry);
+        this.removeAbort(entry);
+        entry.reject(new QuestionChannelError('ask_user_question was cancelled before the user answered', ASK_ABORTED));
+    }
+    /** 入站文本作答：该会话若有待答问题且本条消息有文本，解析为答案并推进 */
+    tryAnswer(scope, peerId, text) {
+        const record = this.manager.getSessionRecord(scope, peerId);
+        if (!record)
+            return false;
+        const key = record.sessionKey;
+        const entry = this.pending.get(key);
+        if (!entry)
+            return false;
+        if (!text)
+            return false; // 纯图片/表情等：继续等待，消息走常规流程
+        const current = entry.request.questions[entry.index];
+        if (!current)
+            return false;
+        const answer = parseAnswer(current, text);
+        this.advance(entry, key, answer);
+        return true;
+    }
+    /** 按钮点击作答：解码 button_data 选项下标，推进状态机 */
+    handleInteraction(event) {
+        const peerId = event.group_openid ?? event.user_openid;
+        if (!peerId)
+            return false;
+        const scope = event.group_openid ? 'group' : 'c2c';
+        const record = this.manager.getSessionRecord(scope, peerId);
+        if (!record)
+            return false;
+        const entry = this.pending.get(record.sessionKey);
+        if (!entry)
+            return false;
+        const data = event.data?.resolved?.button_data;
+        if (!data)
+            return false;
+        const button = decodeButtonData(data);
+        if (!button || button.t !== 'question')
+            return false;
+        const current = entry.request.questions[entry.index];
+        if (!current)
+            return false;
+        // 校验按钮归属题：旧题按钮在新题推进后被点击（误点/延迟事件），
+        // 其 q 不等于当前题 id，直接忽略，避免错位映射到当前题选项。
+        if (button.q !== current.id)
+            return false;
+        const idx = button.i;
+        const opts = current.options ?? [];
+        if (idx < 0 || idx >= opts.length)
+            return false;
+        this.advance(entry, record.sessionKey, { id: current.id, selected: [opts[idx].label] });
+        return true;
+    }
+    /** 走 QQ 通道：发送首题 + 挂起 Promise，等待逐题作答 */
+    async askViaQQ(record, request) {
+        const key = record.sessionKey;
+        // 会话回收/取消可能在发送前发生：signal 已 abort 则直接失败，避免悬挂
+        if (request.signal?.aborted) {
+            throw new QuestionChannelError('ask_user_question was aborted before delivery', ASK_ABORTED);
+        }
+        // 同会话已有待答问题（理论上不会发生：回合阻塞在第一个问题上）→ 拒绝旧的
+        const prev = this.pending.get(key);
+        if (prev) {
+            this.pending.delete(key);
+            this.clearTimer(prev);
+            this.removeAbort(prev);
+            prev.reject(new QuestionChannelError('superseded by a new question', ASK_ABORTED));
+        }
+        const first = request.questions[0];
+        if (!first)
+            throw new Error('ask_user_question with empty questions');
+        await this.sendQuestion(record, first);
+        return new Promise((resolve, reject) => {
+            const entry = { record, request, resolve, reject, index: 0, collected: [] };
+            if (request.signal) {
+                const onAbort = () => {
+                    if (this.pending.get(key) !== entry)
+                        return;
+                    this.pending.delete(key);
+                    this.clearTimer(entry);
+                    reject(new QuestionChannelError('ask_user_question was aborted before the user answered', ASK_ABORTED));
+                };
+                entry.onAbort = onAbort;
+                request.signal.addEventListener('abort', onAbort, { once: true });
+            }
+            entry.timer = setTimeout(() => this.onTimeout(key), this.config.askTimeoutMs);
+            this.pending.set(key, entry);
+            this.logger.info(`im-qqbot: question sent to QQ, waiting for answer key=${key}`);
+        });
+    }
+    /** 推进状态机：收集答案 → 有下一题则发送，否则 resolve 全部答案 */
+    advance(entry, key, answer) {
+        entry.collected.push(answer);
+        entry.index += 1;
+        if (entry.index < entry.request.questions.length) {
+            const next = entry.request.questions[entry.index];
+            this.resetTimer(entry, key);
+            void this.sendQuestion(entry.record, next).catch((err) => {
+                this.pending.delete(key);
+                this.clearTimer(entry);
+                this.removeAbort(entry);
+                entry.reject(err instanceof Error ? err : new Error(String(err)));
+            });
+            return;
+        }
+        this.pending.delete(key);
+        this.clearTimer(entry);
+        this.removeAbort(entry);
+        this.logger.info(`im-qqbot: question answered via QQ key=${key}`);
+        entry.resolve({ answers: entry.collected });
+    }
+    /** 发送单个问题：优先带按钮，按钮发送失败降级纯文本 */
+    async sendQuestion(record, question) {
+        const hint = record.scope === 'group' && this.config.requireMention === true;
+        const keyboard = buildKeyboard(question);
+        try {
+            if (keyboard) {
+                try {
+                    await this.sender.sendMarkdown(record.replyTarget, formatQuestion(question, hint, true), { keyboard });
+                    return;
+                }
+                catch (err) {
+                    this.logger.warn(`im-qqbot: keyboard send failed, fallback to text: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            await this.sender.sendMarkdown(record.replyTarget, formatQuestion(question, hint, false));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.error(`im-qqbot: question send failed key=${record.sessionKey}: ${msg}`);
+            throw new Error(`failed to deliver question to QQ: ${msg}`);
+        }
+    }
+    onTimeout(key) {
+        const entry = this.pending.get(key);
+        if (!entry)
+            return;
+        this.pending.delete(key);
+        this.removeAbort(entry);
+        entry.timer = undefined;
+        void this.sender.sendMarkdown(entry.record.replyTarget, '⚠️ 提问已超时，未收到回答。').catch(() => { });
+        entry.reject(new QuestionChannelError('ask_user_question timed out before the user answered', ASK_ABORTED));
+    }
+    resetTimer(entry, key) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = setTimeout(() => this.onTimeout(key), this.config.askTimeoutMs);
+    }
+    clearTimer(entry) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = undefined;
+    }
+    removeAbort(entry) {
+        if (entry.onAbort && entry.request.signal) {
+            entry.request.signal.removeEventListener('abort', entry.onAbort);
+        }
+    }
+}
+//# sourceMappingURL=question-channel.js.map

package/dist/features/question-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-channel.js","sourceRoot":"","sources":["../../src/features/question-channel.ts"],"names":[],"mappings":"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"}

package/dist/features/question-renderer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * QQ 问答的文本渲染与按钮键盘构建（纯函数，便于单测）。
+ *
+ * 逐题渲染：一次只渲染一个问题（多题时由状态机逐题推进）。
+ */
+import type { InlineKeyboard } from '@tencent-connect/qqbot-nodejs';
+import type { UserQuestion } from './question-channel.ts';
+/**
+ * 为「单选、带选项」的问题构建内联键盘；不适用时返回 undefined。
+ *
+ * 多行多列布局：每行 BUTTONS_PER_ROW 个按钮，减少选项多时的刷屏。
+ *
+ * button_data 编码 `{"t":"question","q":<问题id>,"i":<选项下标>}`，由分发器解码。
+ * `t` 顶层判别字段供 interaction 统一路由；`q` 关联「当前正在问的题」：逐题
+ * 推进时旧题按钮在新题发出后被点击，其 q 不等于当前题 id，可被识别并忽略。
+ */
+export declare function buildKeyboard(question: UserQuestion): InlineKeyboard | undefined;
+/** 把单个问题渲染成 QQ 文本 */
+export declare function formatQuestion(question: UserQuestion, requireMentionHint: boolean, withButtons: boolean): string;
+//# sourceMappingURL=question-renderer.d.ts.map

package/dist/features/question-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-renderer.d.ts","sourceRoot":"","sources":["../../src/features/question-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,CA6BhF;AAED,qBAAqB;AACrB,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EACtB,kBAAkB,EAAE,OAAO,EAC3B,WAAW,EAAE,OAAO,GACnB,MAAM,CA6BR"}

package/dist/features/question-renderer.js

@@ -0,0 +1,70 @@
+import { BUTTONS_PER_ROW, buttonLabel, encodeButtonData } from "./button-utils.js";
+/**
+ * 为「单选、带选项」的问题构建内联键盘；不适用时返回 undefined。
+ *
+ * 多行多列布局：每行 BUTTONS_PER_ROW 个按钮，减少选项多时的刷屏。
+ *
+ * button_data 编码 `{"t":"question","q":<问题id>,"i":<选项下标>}`，由分发器解码。
+ * `t` 顶层判别字段供 interaction 统一路由；`q` 关联「当前正在问的题」：逐题
+ * 推进时旧题按钮在新题发出后被点击，其 q 不等于当前题 id，可被识别并忽略。
+ */
+export function buildKeyboard(question) {
+    const opts = question.options ?? [];
+    if (opts.length === 0 || question.multiSelect)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < opts.length; i += BUTTONS_PER_ROW) {
+        rows.push({
+            buttons: opts.slice(i, i + BUTTONS_PER_ROW).map((o, offset) => {
+                const idx = i + offset;
+                return {
+                    id: `q-${question.id}-opt-${idx}`,
+                    render_data: {
+                        label: buttonLabel(o.label),
+                        visited_label: '✓ 已选',
+                        style: 1,
+                    },
+                    action: {
+                        type: 1,
+                        permission: { type: 2 },
+                        click_limit: 1,
+                        data: encodeButtonData({ t: 'question', q: question.id, i: idx }),
+                    },
+                    // 同一题的选项共享分组：点一个后其余变灰（单选互斥）
+                    group_id: `q-${question.id}`,
+                };
+            }),
+        });
+    }
+    return { content: { rows } };
+}
+/** 把单个问题渲染成 QQ 文本 */
+export function formatQuestion(question, requireMentionHint, withButtons) {
+    const lines = [];
+    if (question.header)
+        lines.push(`**${question.header}**`);
+    const opts = question.options ?? [];
+    const multi = question.multiSelect === true;
+    // 问题行：多选标记前置，用户第一眼就知道作答方式
+    lines.push(multi ? `${question.question}（可多选）` : question.question);
+    // 选项列表：保留完整 label + description（按钮 label 截断时 description 靠正文展示）
+    opts.forEach((o, i) => {
+        lines.push(`${i + 1}. ${o.label}${o.description ? ` · ${o.description}` : ''}`);
+    });
+    // 底部引导：用引用块（>）与正文区分；mention 放在「回复」动作后（点按钮无需 @）
+    if (opts.length > 0) {
+        lines.push('');
+        const mention = requireMentionHint ? '（需 @机器人）' : '';
+        if (withButtons) {
+            lines.push(`> 👇 点击下方按钮选择，或回复编号${mention}`);
+        }
+        else if (multi) {
+            lines.push(`> 💡 回复多个编号即可多选（如 1,3）${mention}，或直接输入你的想法`);
+        }
+        else {
+            lines.push(`> 💡 回复编号选择${mention}，或直接输入你的想法`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=question-renderer.js.map

package/dist/features/question-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-renderer.js","sourceRoot":"","sources":["../../src/features/question-renderer.ts"],"names":[],"mappings":"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"}

package/dist/gateway/bootstrap.d.ts

@@ -5,8 +5,8 @@
  * dsh session/event → createOutboundHandler → QQ 出站。
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type DshAgentRegistry } from '../session/index.js';
-import type { ImQQBotConfig } from '../config.js';
-import type { Logger } from '../types.js';
+import { type DshAgentRegistry } from '../session/index.ts';
+import type { ImQQBotConfig } from '../config.ts';
+import type { Logger } from '../types.ts';
 export declare function bootstrapGateway(ctx: Context, agents: DshAgentRegistry, config: ImQQBotConfig, logger: Logger): Promise<void>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/gateway/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/gateway/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA2Ef"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/gateway/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,aAAa,CAAC;AAqBrD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmIf"}