koishi-plugin-dew-bot 1.0.262 → 1.0.263

package/lib/index.js

@@ -67,7 +67,7 @@ var serviceProto;
 var init_serviceProto = __esm({
   "src/shared/bot/serviceProto.ts"() {
     serviceProto = {
-      "version": 38,
+      "version": 39,
       "services": [
         {
           "id": 0,
@@ -295,6 +295,18 @@ var init_serviceProto = __esm({
                 "target": "messageFace/TitleCardData"
               },
               "optional": true
+            },
+            {
+              "id": 17,
+              "name": "buttons",
+              "type": {
+                "type": "Array",
+                "elementType": {
+                  "type": "Reference",
+                  "target": "messageFace/MessageButtonRow"
+                }
+              },
+              "optional": true
             }
           ]
         },
@@ -1899,6 +1911,65 @@ var init_serviceProto = __esm({
             }
           ]
         },
+        "messageFace/MessageButtonRow": {
+          "type": "Interface",
+          "properties": [
+            {
+              "id": 0,
+              "name": "buttons",
+              "type": {
+                "type": "Array",
+                "elementType": {
+                  "type": "Reference",
+                  "target": "messageFace/MessageButton"
+                }
+              }
+            }
+          ]
+        },
+        "messageFace/MessageButton": {
+          "type": "Interface",
+          "properties": [
+            {
+              "id": 0,
+              "name": "label",
+              "type": {
+                "type": "String"
+              }
+            },
+            {
+              "id": 1,
+              "name": "command",
+              "type": {
+                "type": "String"
+              }
+            },
+            {
+              "id": 2,
+              "name": "style",
+              "type": {
+                "type": "Union",
+                "members": [
+                  {
+                    "id": 0,
+                    "type": {
+                      "type": "Literal",
+                      "literal": "primary"
+                    }
+                  },
+                  {
+                    "id": 1,
+                    "type": {
+                      "type": "Literal",
+                      "literal": "secondary"
+                    }
+                  }
+                ]
+              },
+              "optional": true
+            }
+          ]
+        },
         "PtlMessage/ReqMessage": {
           "type": "Interface",
           "extends": [
@@ -3151,6 +3222,18 @@ var import_node_crypto = require("node:crypto");
 // src/plugin/cardLayout.ts
 async function layoutCard(document2 = globalThis.document) {
   await document2.fonts.ready;
+  for (const name3 of document2.querySelectorAll("#character-name,#companion-name")) {
+    const style = document2.defaultView.getComputedStyle(name3);
+    const maximum = parseFloat(style.fontSize);
+    const spacing = parseFloat(style.letterSpacing) || 0;
+    name3.style.whiteSpace = "nowrap";
+    for (let size = maximum; size >= 18; size--) {
+      name3.style.fontSize = size + "px";
+      name3.style.letterSpacing = spacing * size / maximum + "px";
+      if (name3.scrollWidth <= name3.clientWidth) break;
+    }
+    if (name3.scrollWidth > name3.clientWidth) name3.style.whiteSpace = "normal";
+  }
   const titleBanner = document2.querySelector(".title-banner-artwork");
   if (titleBanner) {
     try {
@@ -3944,6 +4027,143 @@ var handel_base = class {
 // src/plugin/serverHandel/text.ts
 init_sessions();
 
+// src/shared/bot/inlineCommands.ts
+function inlineCommandSpans(content) {
+  const spans = [];
+  let depth = 0, start = 0, labelStart = 0;
+  for (let index = 0; index < content.length; index++) {
+    if (content[index] === "[") {
+      if (depth === 0) {
+        start = index > 0 && content[index - 1] === "\\" ? index - 1 : index;
+        labelStart = index + 1;
+      }
+      depth++;
+    } else if (content[index] === "]" && depth > 0 && --depth === 0) {
+      const label = content.slice(labelStart, index).replace(/\\$/, "");
+      if (!label.trim() || /[\[\]\r\n]/.test(label) || /^\d+$/.test(label.trim())) continue;
+      const alias = /^\(command:([^()[\]\r\n]+)\)/.exec(content.slice(index + 1));
+      const command = alias ? alias[1].trim() : label.split(/[+＋]/, 1)[0].trim().replace(/^🔄\s*/u, "");
+      if (!command) continue;
+      const end = index + 1 + (alias?.[0].length ?? 0);
+      spans.push({ start, end, label, command, ...alias ? { aliased: true } : {} });
+      if (alias) index = end - 1;
+    }
+  }
+  return spans;
+}
+__name(inlineCommandSpans, "inlineCommandSpans");
+function renderPlainInlineCommandAliases(content) {
+  let result = "", offset = 0;
+  for (const span of inlineCommandSpans(content)) {
+    if (!span.aliased) continue;
+    result += content.slice(offset, span.start) + (span.label.trim() === span.command ? `[${span.command}]` : `${span.label}[${span.command}]`);
+    offset = span.end;
+  }
+  return result + content.slice(offset);
+}
+__name(renderPlainInlineCommandAliases, "renderPlainInlineCommandAliases");
+
+// src/shared/bot/analysisMsg.ts
+function messageButtonFallbackLines(data) {
+  return [...new Set((data.buttons ?? []).flatMap((row) => row.buttons.map((button) => "[" + button.command + "]" + button.label)))];
+}
+__name(messageButtonFallbackLines, "messageButtonFallbackLines");
+function matchesButtonFallback(content, fallback) {
+  const bracket = fallback.indexOf("]");
+  const prefix = fallback.slice(0, bracket + 1);
+  const line = content.trim();
+  return line.startsWith(prefix) && line.slice(prefix.length).trim() === fallback.slice(prefix.length).trim();
+}
+__name(matchesButtonFallback, "matchesButtonFallback");
+function appendMessageButtonFallbacks(content, data) {
+  const lines = content.replace(/\r\n?/g, "\n").split("\n");
+  const missing = messageButtonFallbackLines(data).filter((fallback) => !lines.some((line) => matchesButtonFallback(line, fallback)));
+  if (!missing.length) return content;
+  return content + (content && !content.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n";
+}
+__name(appendMessageButtonFallbacks, "appendMessageButtonFallbacks");
+function withoutMessageButtonFallbacks(data) {
+  const fallbacks = messageButtonFallbackLines(data);
+  if (!fallbacks.length) return data;
+  return { ...data, line: data.line.map((item) => {
+    if (item.type !== 1 /* line */ || item.codeBlock || item.reward || item.mailPart !== void 0) return item;
+    const lines = item.content.replace(/\r\n?/g, "\n").split("\n");
+    const kept = lines.filter((line) => !fallbacks.some((fallback) => matchesButtonFallback(line, fallback)));
+    return kept.length === lines.length ? item : { ...item, content: kept.join("\n") };
+  }) };
+}
+__name(withoutMessageButtonFallbacks, "withoutMessageButtonFallbacks");
+var AnalysisMsg = class {
+  static {
+    __name(this, "AnalysisMsg");
+  }
+  parse(data) {
+    let msg = "";
+    let haveTitle = false;
+    const commands = new Map(data.pageNav?.entries?.map((entry) => [entry.lineIndex, entry.viewCommand]) ?? []);
+    const labeledEntries = /* @__PURE__ */ new Map();
+    for (const entry of data.pageNav?.entries ?? []) {
+      if (entry.label === void 0) continue;
+      const row = labeledEntries.get(entry.lineIndex) ?? [];
+      row.push(entry);
+      labeledEntries.set(entry.lineIndex, row);
+    }
+    const withCommandHint = /* @__PURE__ */ __name((content, command) => {
+      const hint = command && !content.includes(`[${command}]`) && content.trim() !== command ? ` [${command}]` : "";
+      return content + hint;
+    }, "withCommandHint");
+    for (const [lineIndex, item] of data.line.entries()) {
+      switch (item.type) {
+        case 0 /* title */:
+          haveTitle = true;
+          msg += `┄━═${item.content}═━┄
+`;
+          break;
+        case 1 /* line */:
+          const labeledRow = labeledEntries.get(lineIndex);
+          const content = labeledRow ? labeledRow.map((entry) => entry.label + (entry.description ? " · " + entry.description : "") + ` [${entry.viewCommand}]`).join("") : withCommandHint(item.content, commands.get(lineIndex));
+          const plainContent = item.codeBlock || item.mailPart === "body" || labeledRow ? content : renderPlainInlineCommandAliases(content);
+          msg += `${plainContent}
+`;
+          break;
+        case 2 /* error */:
+          msg += `❌出错了!错误原因:${item.content},请反馈至联系开发者
+`;
+          break;
+        default:
+          break;
+      }
+    }
+    msg = appendMessageButtonFallbacks(msg, data);
+    if (haveTitle) {
+      msg += "┄━════════━┄";
+    }
+    return msg;
+  }
+};
+
+// src/plugin/serverHandel/qqMessageButtons.ts
+function renderQQKeyboard(data) {
+  const rows = data.buttons;
+  if (!rows?.length) return void 0;
+  if (rows.length > 5 || rows.some((row) => !row.buttons.length || row.buttons.length > 5)) {
+    throw new Error("QQ 按钮最多 5 行，每行必须有 1–5 个按钮");
+  }
+  return { content: { rows: rows.map((row, rowIndex) => ({
+    buttons: row.buttons.map((button, buttonIndex) => {
+      if (!button.label.trim() || !button.command.trim() || /[\r\n\0]/.test(button.label + button.command) || button.command.length > 4e3 || button.style !== void 0 && button.style !== "primary" && button.style !== "secondary") {
+        throw new Error("QQ 按钮文案和指令必须是非空单行文本，样式必须为 primary 或 secondary");
+      }
+      return {
+        id: "action-" + rowIndex + "-" + buttonIndex,
+        render_data: { label: button.label, visited_label: button.label, style: button.style === "primary" ? 1 : 0 },
+        action: { type: 2, permission: { type: 2 }, data: button.command, enter: true, reply: false, unsupport_tips: "请发送：" + button.command }
+      };
+    })
+  })) } };
+}
+__name(renderQQKeyboard, "renderQQKeyboard");
+
 // src/plugin/serverHandel/qqMarkdownHelpers.ts
 function escapeMarkdown(value) {
   return value.replace(/[\\`*_{}\[\]()#+\-.!|>~<&]/g, "\\$&");
@@ -4066,6 +4286,7 @@ function renderQQMailMarkdown(data) {
 }
 __name(renderQQMailMarkdown, "renderQQMailMarkdown");
 function renderQQRewardMarkdown(data, showGreeting) {
+  data = withoutMessageButtonFallbacks(data);
   if (data.mail) return appendMissingBattleLogLinks(renderQQMailMarkdown(data), data);
   const rewards = data.line.filter((item) => item.type === 1 /* line */ && item.reward).map((item) => renderRewardLine(item.content)).filter(Boolean);
   if (rewards.length && !data.mail) return appendMissingBattleLogLinks("🎁获得奖励\n\n" + rewards.join("  \n"), data);
@@ -4095,42 +4316,6 @@ function renderQQRewardMarkdown(data, showGreeting) {
 }
 __name(renderQQRewardMarkdown, "renderQQRewardMarkdown");
 
-// src/shared/bot/inlineCommands.ts
-function inlineCommandSpans(content) {
-  const spans = [];
-  let depth = 0, start = 0, labelStart = 0;
-  for (let index = 0; index < content.length; index++) {
-    if (content[index] === "[") {
-      if (depth === 0) {
-        start = index > 0 && content[index - 1] === "\\" ? index - 1 : index;
-        labelStart = index + 1;
-      }
-      depth++;
-    } else if (content[index] === "]" && depth > 0 && --depth === 0) {
-      const label = content.slice(labelStart, index).replace(/\\$/, "");
-      if (!label.trim() || /[\[\]\r\n]/.test(label) || /^\d+$/.test(label.trim())) continue;
-      const alias = /^\(command:([^()[\]\r\n]+)\)/.exec(content.slice(index + 1));
-      const command = alias ? alias[1].trim() : label.split(/[+＋]/, 1)[0].trim().replace(/^🔄\s*/u, "");
-      if (!command) continue;
-      const end = index + 1 + (alias?.[0].length ?? 0);
-      spans.push({ start, end, label, command, ...alias ? { aliased: true } : {} });
-      if (alias) index = end - 1;
-    }
-  }
-  return spans;
-}
-__name(inlineCommandSpans, "inlineCommandSpans");
-function renderPlainInlineCommandAliases(content) {
-  let result = "", offset = 0;
-  for (const span of inlineCommandSpans(content)) {
-    if (!span.aliased) continue;
-    result += content.slice(offset, span.start) + (span.label.trim() === span.command ? `[${span.command}]` : `${span.label}[${span.command}]`);
-    offset = span.end;
-  }
-  return result + content.slice(offset);
-}
-__name(renderPlainInlineCommandAliases, "renderPlainInlineCommandAliases");
-
 // src/plugin/serverHandel/qqPageMessage.ts
 function compactListLabel(value) {
   const label = compactDisplayText(value);
@@ -4291,6 +4476,7 @@ function renderQQInventoryMarkdown(data, showGreeting) {
 }
 __name(renderQQInventoryMarkdown, "renderQQInventoryMarkdown");
 function renderQQPageMarkdown(data, showGreeting) {
+  data = withoutMessageButtonFallbacks(data);
   const hasEntryLabels = data.pageNav?.entries?.some((entry) => entry.label !== void 0) ?? false;
   if (data.task && !hasEntryLabels) return renderQQTaskMarkdown(data);
   if (!hasEntryLabels && data.pageNav && data.line.some((item) => item.type === 0 /* title */ && /^(?:💼)?我的背包$/u.test(compactDisplayText(item.content))))
@@ -4416,7 +4602,7 @@ function canSendQQPage(session, data) {
   return !!internal?.sendMessage && !!internal.sendPrivateMessage;
 }
 __name(canSendQQPage, "canSendQQPage");
-async function sendQQMarkdown(session, markdown) {
+async function sendQQMarkdown(session, markdown, keyboard) {
   const internal = session.bot.internal;
   const request = {
     // With msg_type=2, QQ requires the ordinary content field to be empty.
@@ -4424,6 +4610,7 @@ async function sendQQMarkdown(session, markdown) {
     msg_type: 2,
     markdown: { content: markdown }
   };
+  if (keyboard) request.keyboard = keyboard;
   const age = Date.now() - session.timestamp;
   if (session.messageId && Number.isFinite(age) && age >= 0 && age < 5 * 60 * 1e3 - 2e3) {
     const sequenced = session;
@@ -4437,57 +4624,9 @@ async function sendQQMarkdown(session, markdown) {
 }
 __name(sendQQMarkdown, "sendQQMarkdown");
 
-// src/shared/bot/analysisMsg.ts
-var AnalysisMsg = class {
-  static {
-    __name(this, "AnalysisMsg");
-  }
-  parse(data) {
-    let msg = "";
-    let haveTitle = false;
-    const commands = new Map(data.pageNav?.entries?.map((entry) => [entry.lineIndex, entry.viewCommand]) ?? []);
-    const labeledEntries = /* @__PURE__ */ new Map();
-    for (const entry of data.pageNav?.entries ?? []) {
-      if (entry.label === void 0) continue;
-      const row = labeledEntries.get(entry.lineIndex) ?? [];
-      row.push(entry);
-      labeledEntries.set(entry.lineIndex, row);
-    }
-    const withCommandHint = /* @__PURE__ */ __name((content, command) => {
-      const hint = command && !content.includes(`[${command}]`) && content.trim() !== command ? ` [${command}]` : "";
-      return content + hint;
-    }, "withCommandHint");
-    for (const [lineIndex, item] of data.line.entries()) {
-      switch (item.type) {
-        case 0 /* title */:
-          haveTitle = true;
-          msg += `┄━═${item.content}═━┄
-`;
-          break;
-        case 1 /* line */:
-          const labeledRow = labeledEntries.get(lineIndex);
-          const content = labeledRow ? labeledRow.map((entry) => entry.label + (entry.description ? " · " + entry.description : "") + ` [${entry.viewCommand}]`).join("") : withCommandHint(item.content, commands.get(lineIndex));
-          const plainContent = item.codeBlock || item.mailPart === "body" || labeledRow ? content : renderPlainInlineCommandAliases(content);
-          msg += `${plainContent}
-`;
-          break;
-        case 2 /* error */:
-          msg += `❌出错了!错误原因:${item.content},请反馈至联系开发者
-`;
-          break;
-        default:
-          break;
-      }
-    }
-    if (haveTitle) {
-      msg += "┄━════════━┄";
-    }
-    return msg;
-  }
-};
-
 // src/plugin/serverHandel/qqCommandMessage.ts
 function renderQQCommandMarkdown(data, showGreeting) {
+  data = withoutMessageButtonFallbacks(data);
   if (data.notification) {
     const onlyLine = data.line.length === 1 ? data.line[0] : void 0;
     if (onlyLine?.type === 1 /* line */ && /^🔔系统提示：[^\r\n]+$/.test(onlyLine.content)) {
@@ -4551,6 +4690,7 @@ __name(renderQQCommandMarkdown, "renderQQCommandMarkdown");
 
 // src/plugin/serverHandel/qqTransactionMessage.ts
 function renderQQTransactionMarkdown(data, showGreeting) {
+  data = withoutMessageButtonFallbacks(data);
   const rewardMessage = isRewardMessage(data);
   const shortageMessage = data.transaction === true && data.line.some((item) => item.type === 0 /* title */ && item.content === "❌材料不足");
   const sections = [];
@@ -4644,6 +4784,7 @@ function fencedStory(content) {
 }
 __name(fencedStory, "fencedStory");
 function renderQQStoryMarkdown(data, showGreeting) {
+  data = withoutMessageButtonFallbacks(data);
   if (data.reward === true && data.line.some((item) => item.type === 1 /* line */ && item.reward === true && item.content.trim())) {
     const stories = data.line.filter((item) => item.type === 1 /* line */ && item.codeBlock === true).map((item) => fencedStory(item.content));
     return [...stories, renderQQRewardMarkdown(data, false)].join("\n\n");
@@ -4702,15 +4843,29 @@ __name(renderQQStoryMarkdown, "renderQQStoryMarkdown");
 function renderQQMessagePreview(data, showGreeting = false) {
   const plain = new AnalysisMsg().parse(data);
   const text = data.notification ? plain.trimEnd() : plain;
-  if (data.notification) return { kind: "command", markdown: renderQQCommandMarkdown(data, false), text };
-  if (hasStoryCodeBlock(data)) return { kind: "story", markdown: renderQQStoryMarkdown(data, showGreeting), text };
-  if (data.commandHelp) return { kind: "command", markdown: renderQQCommandMarkdown(data, showGreeting), text };
-  if (data.transaction) return { kind: "transaction", markdown: renderQQTransactionMarkdown(data, showGreeting), text };
-  if (data.pageNav) return { kind: "page", markdown: renderQQPageMarkdown(data, showGreeting), text };
-  if (isRewardMessage(data)) return { kind: "reward", markdown: renderQQRewardMarkdown(data, showGreeting), text };
+  let keyboard;
+  try {
+    keyboard = renderQQKeyboard(data);
+  } catch {
+    return { kind: "text", text };
+  }
+  data = withoutMessageButtonFallbacks(data);
+  const native = /* @__PURE__ */ __name((kind, markdown) => ({
+    kind,
+    markdown,
+    text,
+    ...keyboard ? { keyboard } : {}
+  }), "native");
+  if (data.notification) return native("command", renderQQCommandMarkdown(data, false));
+  if (hasStoryCodeBlock(data)) return native("story", renderQQStoryMarkdown(data, showGreeting));
+  if (data.commandHelp) return native("command", renderQQCommandMarkdown(data, showGreeting));
+  if (data.transaction) return native("transaction", renderQQTransactionMarkdown(data, showGreeting));
+  if (data.pageNav) return native("page", renderQQPageMarkdown(data, showGreeting));
+  if (isRewardMessage(data)) return native("reward", renderQQRewardMarkdown(data, showGreeting));
   if (battleLogMessageLinks(data).length || data.line.some((item) => (item.type === 1 /* line */ || item.type === 2 /* error */) && hasInlineCommands(item.content))) {
-    return { kind: "command", markdown: renderQQCommandMarkdown(data, showGreeting), text };
+    return native("command", renderQQCommandMarkdown(data, showGreeting));
   }
+  if (keyboard) return native("command", renderQQCommandMarkdown(data, showGreeting));
   return { kind: "text", text };
 }
 __name(renderQQMessagePreview, "renderQQMessagePreview");
@@ -4727,7 +4882,7 @@ var handelr_text = class extends handel_base {
     if (preview.markdown !== void 0 && canSendQQPage(session, data)) {
       const sendStartedAt = this.timing ? performance.now() : 0;
       try {
-        await sendQQMarkdown(session, preview.markdown);
+        await sendQQMarkdown(session, preview.markdown, preview.keyboard);
         if (this.timing) {
           this.timing.delivery = "qq-markdown";
           this.timing.sendMs = performance.now() - sendStartedAt;
@@ -4772,6 +4927,23 @@ function titleCardFollowup(data) {
 }
 __name(titleCardFollowup, "titleCardFollowup");
 
+// src/plugin/serverHandel/imageMessageFollowup.ts
+function renderQQImageFollowup(data) {
+  const title = titleCardFollowup(data);
+  const actionLines = messageButtonFallbackLines(data);
+  if (!title && !actionLines.length) return void 0;
+  const text = appendMessageButtonFallbacks(title?.text ?? "", data).trimEnd();
+  let keyboard;
+  try {
+    keyboard = renderQQKeyboard(data);
+  } catch {
+    return { text };
+  }
+  const markdown = titleCardFollowup(withoutMessageButtonFallbacks(data))?.markdown ?? " ";
+  return { text, markdown, ...keyboard ? { keyboard } : {} };
+}
+__name(renderQQImageFollowup, "renderQQImageFollowup");
+
 // src/plugin/serverHandel/image.ts
 var ImageHandler = class extends handel_base {
   static {
@@ -4802,16 +4974,16 @@ var ImageHandler = class extends handel_base {
     }
     const sendStartedAt = this.timing ? performance.now() : 0;
     await this.send(data, content, "image");
-    const followup = titleCardFollowup(data);
+    const followup = renderQQImageFollowup(data);
     if (!followup) return;
     const session = sessions_default.get(sessionKey(data.botId, data.userId, data.channelId));
     let sentMarkdown = false;
-    if (canSendQQPage(session, data)) {
+    if (followup.markdown !== void 0 && canSendQQPage(session, data)) {
       try {
-        await sendQQMarkdown(session, followup.markdown);
+        await sendQQMarkdown(session, followup.markdown, followup.keyboard);
         sentMarkdown = true;
       } catch (error) {
-        this.ctx.logger.warn("称号操作 Markdown 发送失败，改用普通文字", error instanceof Error ? error.message : error);
+        this.ctx.logger.warn("图片操作 Markdown 发送失败，改用普通文字", error instanceof Error ? error.message : error);
       }
     }
     if (!sentMarkdown) await this.send({ ...data, notification: true }, followup.text);

package/lib/plugin/serverHandel/imageMessageFollowup.d.ts

@@ -0,0 +1,9 @@
+import type { IMessage } from '../../shared/face';
+import { type QQKeyboard } from './qqMessageButtons';
+export interface QQImageFollowup {
+    text: string;
+    markdown?: string;
+    keyboard?: QQKeyboard;
+}
+/** Images are sent first; actions stay outside the image and retain a plain fallback. */
+export declare function renderQQImageFollowup(data: IMessage): QQImageFollowup | undefined;

package/lib/plugin/serverHandel/qqMessageButtons.d.ts

@@ -0,0 +1,27 @@
+import type { IMessage } from '../../shared/face';
+export interface QQKeyboard {
+    content: {
+        rows: Array<{
+            buttons: Array<{
+                id: string;
+                render_data: {
+                    label: string;
+                    visited_label: string;
+                    style: 0 | 1;
+                };
+                action: {
+                    type: 2;
+                    permission: {
+                        type: 2;
+                    };
+                    data: string;
+                    enter: true;
+                    reply: false;
+                    unsupport_tips: string;
+                };
+            }>;
+        }>;
+    };
+}
+/** Explicit actions use QQ's native keyboard; ordinary command links stay inline. */
+export declare function renderQQKeyboard(data: Pick<IMessage, 'buttons'>): QQKeyboard | undefined;

package/lib/plugin/serverHandel/qqMessagePreview.d.ts

@@ -1,9 +1,12 @@
 import { type IMessage } from '../../shared/face';
+import { type QQKeyboard } from './qqMessageButtons';
 export type QQMessageKind = 'text' | 'story' | 'command' | 'transaction' | 'page' | 'reward';
 export interface QQMessagePreview {
     kind: QQMessageKind;
     /** Exact native QQ Markdown payload; absent when the bot sends plain text. */
     markdown?: string;
+    /** Native buttons accompany the same Markdown in bot delivery and editor preview. */
+    keyboard?: QQKeyboard;
     /** Plain fallback before the transport adds its QQ group greeting. */
     text: string;
 }

package/lib/plugin/serverHandel/qqPageMessage.d.ts

@@ -1,6 +1,7 @@
 import type { Session } from 'koishi';
 import { type IMessage, type PageNavData } from '../../shared/face';
 import type { MsgMessage } from '../../shared/bot/MsgMessage';
+import { type QQKeyboard } from './qqMessageButtons';
 export { escapeMarkdown, renderQQTitle } from './qqMarkdownHelpers';
 export declare function inlineCommandUrl(command: string): string;
 export declare function hasInlineCommands(content: string): boolean;
@@ -13,4 +14,4 @@ export declare function canSendQQPage(session: Session | undefined, data: MsgMes
 /** Send a native QQ Markdown page with inline command links. */
 export declare function sendQQPage(session: Session, data: MsgMessage): Promise<void>;
 /** Reuse the adapter's native reply API for structured Markdown messages. */
-export declare function sendQQMarkdown(session: Session, markdown: string): Promise<void>;
+export declare function sendQQMarkdown(session: Session, markdown: string, keyboard?: QQKeyboard): Promise<void>;

package/lib/shared/bot/analysisMsg.d.ts

@@ -1,4 +1,9 @@
 import { IMessage } from '../face';
+/** Platform-neutral button hints also work when Markdown or keyboards are unavailable. */
+export declare function messageButtonFallbackLines(data: Pick<IMessage, 'buttons'>): string[];
+export declare function appendMessageButtonFallbacks(content: string, data: Pick<IMessage, 'buttons'>): string;
+/** Remove only complete action hints; keep source line indexes used by page metadata. */
+export declare function withoutMessageButtonFallbacks<T extends IMessage>(data: T): T;
 /** 把服务器下发的结构化行拼成纯文本；第一阶段只处理 title / line / error **/
 export declare class AnalysisMsg {
     parse(data: IMessage): string;

package/lib/shared/face/index.d.ts

@@ -267,6 +267,17 @@ export interface PageNavData {
         command: string;
     }>;
 }
+/** 平台无关的消息按钮；点击后发送普通指令，业务仍负责权限与状态校验。 */
+export interface MessageButton {
+    label: string;
+    command: string;
+    /** 主操作蓝色线框，次操作灰色线框；缺省为次操作。 */
+    style?: 'primary' | 'secondary';
+}
+/** 同一行的按钮；QQ 原生键盘最多五行，每行最多五个。 */
+export interface MessageButtonRow {
+    buttons: MessageButton[];
+}
 /** 下发给客户端的消息主体 **/
 export interface IMessage {
     handleType: MessageHandleType;
@@ -293,4 +304,6 @@ export interface IMessage {
     line: IMessageItem[];
     companionCard?: CompanionCardData;
     titleCard?: TitleCardData;
+    /** 通用指令按钮；不支持原生按钮的平台保留文字指令。 */
+    buttons?: MessageButtonRow[];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-dew-bot",
   "description": "基于《无限恐怖》小说改编的 RPG 机器人。踏入主神空间，与伙伴迎接轮回试炼，书写属于你的无限冒险。",
-  "version": "1.0.262",
+  "version": "1.0.263",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/src/plugin/cardLayout.ts

@@ -2,6 +2,20 @@
 export async function layoutCard(document: Document = globalThis.document) {
 
         await document.fonts.ready
+        // Measure names in one line before the flow-layout cards return below.
+        for (const name of document.querySelectorAll<HTMLElement>('#character-name,#companion-name')) {
+          const style = document.defaultView!.getComputedStyle(name)
+          const maximum = parseFloat(style.fontSize)
+          const spacing = parseFloat(style.letterSpacing) || 0
+          name.style.whiteSpace = 'nowrap'
+          for (let size = maximum; size >= 18; size--) {
+            name.style.fontSize = size + 'px'
+            name.style.letterSpacing = spacing * size / maximum + 'px'
+            if (name.scrollWidth <= name.clientWidth) break
+          }
+          // Preserve the complete name when even the readable minimum cannot fit.
+          if (name.scrollWidth > name.clientWidth) name.style.whiteSpace = 'normal'
+        }
         const titleBanner = document.querySelector<HTMLImageElement>('.title-banner-artwork')
         if (titleBanner) {
           try { await titleBanner.decode() } catch {

package/src/plugin/serverHandel/image.ts

@@ -5,7 +5,7 @@ import handel_base from './handel_base'
 import TextHandler from './text'
 import sessions, { sessionKey } from '../sessions'
 import { canSendQQPage, sendQQMarkdown } from './qqPageMessage'
-import { titleCardFollowup } from './titleCardMessage'
+import { renderQQImageFollowup } from './imageMessageFollowup'
 export default class ImageHandler extends handel_base {
   async start(data: MsgMessage) {
     let content = ''
@@ -32,16 +32,16 @@ export default class ImageHandler extends handel_base {
     }
     const sendStartedAt = this.timing ? performance.now() : 0
     await this.send(data, content, 'image')
-    const followup = titleCardFollowup(data)
+    const followup = renderQQImageFollowup(data)
     if (!followup) return
     const session = sessions.get(sessionKey(data.botId, data.userId, data.channelId))
     let sentMarkdown = false
-    if (canSendQQPage(session, data)) {
+    if (followup.markdown !== undefined && canSendQQPage(session, data)) {
       try {
-        await sendQQMarkdown(session, followup.markdown)
+        await sendQQMarkdown(session, followup.markdown, followup.keyboard)
         sentMarkdown = true
       } catch (error) {
-        this.ctx.logger.warn('称号操作 Markdown 发送失败，改用普通文字', error instanceof Error ? error.message : error)
+        this.ctx.logger.warn('图片操作 Markdown 发送失败，改用普通文字', error instanceof Error ? error.message : error)
       }
     }
     if (!sentMarkdown) await this.send({ ...data, notification: true }, followup.text)

package/src/plugin/serverHandel/imageMessageFollowup.ts

@@ -0,0 +1,23 @@
+import type { IMessage } from '../../shared/face'
+import { appendMessageButtonFallbacks, messageButtonFallbackLines, withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { titleCardFollowup } from './titleCardMessage'
+import { renderQQKeyboard, type QQKeyboard } from './qqMessageButtons'
+
+export interface QQImageFollowup {
+  text: string
+  markdown?: string
+  keyboard?: QQKeyboard
+}
+
+/** Images are sent first; actions stay outside the image and retain a plain fallback. */
+export function renderQQImageFollowup(data: IMessage): QQImageFollowup | undefined {
+  const title = titleCardFollowup(data)
+  const actionLines = messageButtonFallbackLines(data)
+  if (!title && !actionLines.length) return undefined
+  const text = appendMessageButtonFallbacks(title?.text ?? '', data).trimEnd()
+  let keyboard: QQKeyboard | undefined
+  try { keyboard = renderQQKeyboard(data) }
+  catch { return { text } }
+  const markdown = titleCardFollowup(withoutMessageButtonFallbacks(data))?.markdown ?? ' '
+  return { text, markdown, ...(keyboard ? { keyboard } : {}) }
+}

package/src/plugin/serverHandel/qqCommandMessage.ts

@@ -1,3 +1,5 @@
+import { withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { renderQQKeyboard } from './qqMessageButtons'
 import type { Session } from 'koishi'
 import { MessageType, type IMessage } from '../../shared/face'
 import type { MsgMessage } from '../../shared/bot/MsgMessage'
@@ -6,6 +8,7 @@ import { isRewardMessage, renderRewardLine, renderRewardTitle } from './qqReward
 
 /** Render command help and ordinary prose with clickable bracketed commands. */
 export function renderQQCommandMarkdown(data: IMessage, showGreeting: boolean): string {
+  data = withoutMessageButtonFallbacks(data)
   if (data.notification) {
     const onlyLine = data.line.length === 1 ? data.line[0] : undefined
     if (onlyLine?.type === MessageType.line && /^🔔系统提示：[^\r\n]+$/.test(onlyLine.content)) {
@@ -72,5 +75,5 @@ export function renderQQCommandMarkdown(data: IMessage, showGreeting: boolean):
 }
 
 export async function sendQQCommand(session: Session, data: MsgMessage): Promise<void> {
-  await sendQQMarkdown(session, renderQQCommandMarkdown(data, session.event?.channel?.type === 0))
+  await sendQQMarkdown(session, renderQQCommandMarkdown(data, session.event?.channel?.type === 0), renderQQKeyboard(data))
 }

package/src/plugin/serverHandel/qqMessageButtons.ts

@@ -0,0 +1,38 @@
+import type { IMessage } from '../../shared/face'
+
+export interface QQKeyboard {
+  content: { rows: Array<{ buttons: Array<{
+    id: string
+    render_data: { label: string; visited_label: string; style: 0 | 1 }
+    action: {
+      type: 2
+      permission: { type: 2 }
+      data: string
+      enter: true
+      reply: false
+      unsupport_tips: string
+    }
+  }> }> }
+}
+
+/** Explicit actions use QQ's native keyboard; ordinary command links stay inline. */
+export function renderQQKeyboard(data: Pick<IMessage, 'buttons'>): QQKeyboard | undefined {
+  const rows = data.buttons
+  if (!rows?.length) return undefined
+  if (rows.length > 5 || rows.some(row => !row.buttons.length || row.buttons.length > 5)) {
+    throw new Error('QQ 按钮最多 5 行，每行必须有 1–5 个按钮')
+  }
+  return { content: { rows: rows.map((row, rowIndex) => ({
+    buttons: row.buttons.map((button, buttonIndex) => {
+      if (!button.label.trim() || !button.command.trim() || /[\r\n\0]/.test(button.label + button.command)
+        || button.command.length > 4000 || (button.style !== undefined && button.style !== 'primary' && button.style !== 'secondary')) {
+        throw new Error('QQ 按钮文案和指令必须是非空单行文本，样式必须为 primary 或 secondary')
+      }
+      return {
+        id: 'action-' + rowIndex + '-' + buttonIndex,
+        render_data: { label: button.label, visited_label: button.label, style: button.style === 'primary' ? 1 : 0 },
+        action: { type: 2, permission: { type: 2 }, data: button.command, enter: true, reply: false, unsupport_tips: '请发送：' + button.command },
+      }
+    }),
+  })) } }
+}

package/src/plugin/serverHandel/qqMessagePreview.ts

@@ -1,5 +1,6 @@
 import { type IMessage, MessageType } from '../../shared/face'
-import { AnalysisMsg } from '../../shared/bot/analysisMsg'
+import { AnalysisMsg, withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { renderQQKeyboard, type QQKeyboard } from './qqMessageButtons'
 import { hasInlineCommands, renderQQPageMarkdown } from './qqPageMessage'
 import { renderQQCommandMarkdown } from './qqCommandMessage'
 import { renderQQTransactionMarkdown } from './qqTransactionMessage'
@@ -13,6 +14,8 @@ export interface QQMessagePreview {
   kind: QQMessageKind
   /** Exact native QQ Markdown payload; absent when the bot sends plain text. */
   markdown?: string
+  /** Native buttons accompany the same Markdown in bot delivery and editor preview. */
+  keyboard?: QQKeyboard
   /** Plain fallback before the transport adds its QQ group greeting. */
   text: string
 }
@@ -21,14 +24,22 @@ export interface QQMessagePreview {
 export function renderQQMessagePreview(data: IMessage, showGreeting = false): QQMessagePreview {
   const plain = new AnalysisMsg().parse(data)
   const text = data.notification ? plain.trimEnd() : plain
-  if (data.notification) return { kind: 'command', markdown: renderQQCommandMarkdown(data, false), text }
-  if (hasStoryCodeBlock(data)) return { kind: 'story', markdown: renderQQStoryMarkdown(data, showGreeting), text }
-  if (data.commandHelp) return { kind: 'command', markdown: renderQQCommandMarkdown(data, showGreeting), text }
-  if (data.transaction) return { kind: 'transaction', markdown: renderQQTransactionMarkdown(data, showGreeting), text }
-  if (data.pageNav) return { kind: 'page', markdown: renderQQPageMarkdown(data, showGreeting), text }
-  if (isRewardMessage(data)) return { kind: 'reward', markdown: renderQQRewardMarkdown(data, showGreeting), text }
+  let keyboard: QQKeyboard | undefined
+  try { keyboard = renderQQKeyboard(data) }
+  catch { return { kind: 'text', text } }
+  data = withoutMessageButtonFallbacks(data)
+  const native = (kind: QQMessageKind, markdown: string): QQMessagePreview => ({
+    kind, markdown, text, ...(keyboard ? { keyboard } : {}),
+  })
+  if (data.notification) return native('command', renderQQCommandMarkdown(data, false))
+  if (hasStoryCodeBlock(data)) return native('story', renderQQStoryMarkdown(data, showGreeting))
+  if (data.commandHelp) return native('command', renderQQCommandMarkdown(data, showGreeting))
+  if (data.transaction) return native('transaction', renderQQTransactionMarkdown(data, showGreeting))
+  if (data.pageNav) return native('page', renderQQPageMarkdown(data, showGreeting))
+  if (isRewardMessage(data)) return native('reward', renderQQRewardMarkdown(data, showGreeting))
   if (battleLogMessageLinks(data).length || data.line.some(item => (item.type === MessageType.line || item.type === MessageType.error) && hasInlineCommands(item.content))) {
-    return { kind: 'command', markdown: renderQQCommandMarkdown(data, showGreeting), text }
+    return native('command', renderQQCommandMarkdown(data, showGreeting))
   }
+  if (keyboard) return native('command', renderQQCommandMarkdown(data, showGreeting))
   return { kind: 'text', text }
 }

package/src/plugin/serverHandel/qqPageMessage.ts

@@ -1,6 +1,8 @@
 import type { Session } from 'koishi'
 import { MessageType, type IMessage, type PageNavData } from '../../shared/face'
 import type { MsgMessage } from '../../shared/bot/MsgMessage'
+import { withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { renderQQKeyboard, type QQKeyboard } from './qqMessageButtons'
 import { compactDisplayText, escapeMarkdown, renderQQTitle } from './qqMarkdownHelpers'
 import { isRewardMessage, renderRewardLine, renderRewardTitle } from './qqRewardMessage'
 import { artworkIdentity } from '../skillArtwork'
@@ -13,6 +15,7 @@ type QQRequest = {
   content: string
   msg_type: 2
   markdown: { content: string }
+  keyboard?: QQKeyboard
   msg_id?: string
   msg_seq?: number
 }
@@ -216,6 +219,7 @@ function renderQQInventoryMarkdown(data: IMessage, showGreeting: boolean): strin
 }
 
 export function renderQQPageMarkdown(data: IMessage, showGreeting: boolean): string {
+  data = withoutMessageButtonFallbacks(data)
   const hasEntryLabels = data.pageNav?.entries?.some(entry => entry.label !== undefined) ?? false
   if (data.task && !hasEntryLabels) return renderQQTaskMarkdown(data)
   if (!hasEntryLabels && data.pageNav && data.line.some(item => item.type === MessageType.title
@@ -358,11 +362,11 @@ export function canSendQQPage(session: Session | undefined, data: MsgMessage): s
 /** Send a native QQ Markdown page with inline command links. */
 export async function sendQQPage(session: Session, data: MsgMessage): Promise<void> {
   const markdown = renderQQPageMarkdown(data, session.event?.channel?.type === 0)
-  await sendQQMarkdown(session, markdown)
+  await sendQQMarkdown(session, markdown, renderQQKeyboard(data))
 }
 
 /** Reuse the adapter's native reply API for structured Markdown messages. */
-export async function sendQQMarkdown(session: Session, markdown: string): Promise<void> {
+export async function sendQQMarkdown(session: Session, markdown: string, keyboard?: QQKeyboard): Promise<void> {
   const internal = (session.bot as typeof session.bot & { internal: QQInternal }).internal
   const request: QQRequest = {
     // With msg_type=2, QQ requires the ordinary content field to be empty.
@@ -370,6 +374,7 @@ export async function sendQQMarkdown(session: Session, markdown: string): Promis
     msg_type: 2,
     markdown: { content: markdown },
   }
+  if (keyboard) request.keyboard = keyboard
   // Match the QQ adapter's passive-reply sequence.
   const age = Date.now() - session.timestamp
   if (session.messageId && Number.isFinite(age) && age >= 0 && age < 5 * 60 * 1000 - 2000) {

package/src/plugin/serverHandel/qqRewardMessage.ts

@@ -1,3 +1,4 @@
+import { withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
 import { MessageType, type IMessage } from '../../shared/face'
 import { compactDisplayText, escapeMarkdown } from './qqMarkdownHelpers'
 import { appendMissingBattleLogLinks, renderBattleLogLinkText } from './qqBattleLogLinks'
@@ -68,6 +69,7 @@ function renderQQMailMarkdown(data: IMessage): string {
 
 /** Reward cards stay compact; mail keeps its content before the attachment quote. */
 export function renderQQRewardMarkdown(data: IMessage, showGreeting: boolean): string {
+  data = withoutMessageButtonFallbacks(data)
   if (data.mail) return appendMissingBattleLogLinks(renderQQMailMarkdown(data), data)
   const rewards = data.line.filter(item => item.type === MessageType.line && item.reward)
     .map(item => renderRewardLine(item.content)).filter(Boolean)

package/src/plugin/serverHandel/qqStoryMessage.ts

@@ -1,3 +1,5 @@
+import { withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { renderQQKeyboard } from './qqMessageButtons'
 import type { Session } from 'koishi'
 import { MessageType, type IMessage } from '../../shared/face'
 import type { MsgMessage } from '../../shared/bot/MsgMessage'
@@ -20,6 +22,7 @@ function fencedStory(content: string): string {
 
 /** Marked stories keep their complete text; settled rewards use the shared reward card. */
 export function renderQQStoryMarkdown(data: IMessage, showGreeting: boolean): string {
+  data = withoutMessageButtonFallbacks(data)
   if (data.reward === true && data.line.some(item => item.type === MessageType.line && item.reward === true && item.content.trim())) {
     const stories = data.line.filter(item => item.type === MessageType.line && item.codeBlock === true)
       .map(item => fencedStory(item.content))
@@ -75,5 +78,5 @@ export function renderQQStoryMarkdown(data: IMessage, showGreeting: boolean): st
 }
 
 export async function sendQQStory(session: Session, data: MsgMessage): Promise<void> {
-  await sendQQMarkdown(session, renderQQStoryMarkdown(data, session.event?.channel?.type === 0))
+  await sendQQMarkdown(session, renderQQStoryMarkdown(data, session.event?.channel?.type === 0), renderQQKeyboard(data))
 }

package/src/plugin/serverHandel/qqTransactionMessage.ts

@@ -1,3 +1,5 @@
+import { withoutMessageButtonFallbacks } from '../../shared/bot/analysisMsg'
+import { renderQQKeyboard } from './qqMessageButtons'
 import type { Session } from 'koishi'
 import { MessageType, type IMessage } from '../../shared/face'
 import type { MsgMessage } from '../../shared/bot/MsgMessage'
@@ -6,6 +8,7 @@ import { isRewardMessage, renderRewardLine, renderRewardTitle } from './qqReward
 
 /** Render only explicitly marked transactions; line content never enables this channel. */
 export function renderQQTransactionMarkdown(data: IMessage, showGreeting: boolean): string {
+  data = withoutMessageButtonFallbacks(data)
   const rewardMessage = isRewardMessage(data)
   const shortageMessage = data.transaction === true && data.line.some(item =>
     item.type === MessageType.title && item.content === '❌材料不足')
@@ -90,5 +93,5 @@ export function renderQQTransactionMarkdown(data: IMessage, showGreeting: boolea
 }
 
 export async function sendQQTransaction(session: Session, data: MsgMessage): Promise<void> {
-  await sendQQMarkdown(session, renderQQTransactionMarkdown(data, session.event?.channel?.type === 0))
+  await sendQQMarkdown(session, renderQQTransactionMarkdown(data, session.event?.channel?.type === 0), renderQQKeyboard(data))
 }

package/src/plugin/serverHandel/text.ts

@@ -12,7 +12,7 @@ export default class handelr_text extends handel_base {
     if (preview.markdown !== undefined && canSendQQPage(session, data)) {
       const sendStartedAt = this.timing ? performance.now() : 0
       try {
-        await sendQQMarkdown(session, preview.markdown)
+        await sendQQMarkdown(session, preview.markdown, preview.keyboard)
         if (this.timing) {
           this.timing.delivery = 'qq-markdown'
           this.timing.sendMs = performance.now() - sendStartedAt

package/src/shared/bot/analysisMsg.ts

@@ -1,6 +1,39 @@
 import { IMessage, MessageType, type PageNavData } from '../face'
 import { renderPlainInlineCommandAliases } from './inlineCommands'
 
+/** Platform-neutral button hints also work when Markdown or keyboards are unavailable. */
+export function messageButtonFallbackLines(data: Pick<IMessage, 'buttons'>): string[] {
+  return [...new Set((data.buttons ?? []).flatMap(row => row.buttons.map(button =>
+    '[' + button.command + ']' + button.label)))]
+}
+
+function matchesButtonFallback(content: string, fallback: string): boolean {
+  const bracket = fallback.indexOf(']')
+  const prefix = fallback.slice(0, bracket + 1)
+  const line = content.trim()
+  return line.startsWith(prefix) && line.slice(prefix.length).trim() === fallback.slice(prefix.length).trim()
+}
+
+export function appendMessageButtonFallbacks(content: string, data: Pick<IMessage, 'buttons'>): string {
+  const lines = content.replace(/\r\n?/g, '\n').split('\n')
+  const missing = messageButtonFallbackLines(data).filter(fallback =>
+    !lines.some(line => matchesButtonFallback(line, fallback)))
+  if (!missing.length) return content
+  return content + (content && !content.endsWith('\n') ? '\n' : '') + missing.join('\n') + '\n'
+}
+
+/** Remove only complete action hints; keep source line indexes used by page metadata. */
+export function withoutMessageButtonFallbacks<T extends IMessage>(data: T): T {
+  const fallbacks = messageButtonFallbackLines(data)
+  if (!fallbacks.length) return data
+  return { ...data, line: data.line.map(item => {
+    if (item.type !== MessageType.line || item.codeBlock || item.reward || item.mailPart !== undefined) return item
+    const lines = item.content.replace(/\r\n?/g, '\n').split('\n')
+    const kept = lines.filter(line => !fallbacks.some(fallback => matchesButtonFallback(line, fallback)))
+    return kept.length === lines.length ? item : { ...item, content: kept.join('\n') }
+  }) }
+}
+
 /** 把服务器下发的结构化行拼成纯文本；第一阶段只处理 title / line / error **/
 export class AnalysisMsg {
   parse(data: IMessage) {
@@ -43,6 +76,7 @@ export class AnalysisMsg {
           break
       }
     }
+    msg = appendMessageButtonFallbacks(msg, data)
     if (haveTitle) {
       msg += '┄━════════━┄'
     }

package/src/shared/bot/serviceProto.ts

@@ -25,7 +25,7 @@ export interface ServiceType {
 }
 
 export const serviceProto: ServiceProto<ServiceType> = {
-    "version": 38,
+    "version": 39,
     "services": [
         {
             "id": 0,
@@ -253,6 +253,18 @@ export const serviceProto: ServiceProto<ServiceType> = {
                         "target": "messageFace/TitleCardData"
                     },
                     "optional": true
+                },
+                {
+                    "id": 17,
+                    "name": "buttons",
+                    "type": {
+                        "type": "Array",
+                        "elementType": {
+                            "type": "Reference",
+                            "target": "messageFace/MessageButtonRow"
+                        }
+                    },
+                    "optional": true
                 }
             ]
         },
@@ -1857,6 +1869,65 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
+        "messageFace/MessageButtonRow": {
+            "type": "Interface",
+            "properties": [
+                {
+                    "id": 0,
+                    "name": "buttons",
+                    "type": {
+                        "type": "Array",
+                        "elementType": {
+                            "type": "Reference",
+                            "target": "messageFace/MessageButton"
+                        }
+                    }
+                }
+            ]
+        },
+        "messageFace/MessageButton": {
+            "type": "Interface",
+            "properties": [
+                {
+                    "id": 0,
+                    "name": "label",
+                    "type": {
+                        "type": "String"
+                    }
+                },
+                {
+                    "id": 1,
+                    "name": "command",
+                    "type": {
+                        "type": "String"
+                    }
+                },
+                {
+                    "id": 2,
+                    "name": "style",
+                    "type": {
+                        "type": "Union",
+                        "members": [
+                            {
+                                "id": 0,
+                                "type": {
+                                    "type": "Literal",
+                                    "literal": "primary"
+                                }
+                            },
+                            {
+                                "id": 1,
+                                "type": {
+                                    "type": "Literal",
+                                    "literal": "secondary"
+                                }
+                            }
+                        ]
+                    },
+                    "optional": true
+                }
+            ]
+        },
         "PtlMessage/ReqMessage": {
             "type": "Interface",
             "extends": [

package/src/shared/face/index.ts

@@ -198,6 +198,19 @@ export interface PageNavData {
     filters?: Array<{ name: string; emoji?: string; command: string }>;
 }
 
+/** 平台无关的消息按钮；点击后发送普通指令，业务仍负责权限与状态校验。 */
+export interface MessageButton {
+    label: string;
+    command: string;
+    /** 主操作蓝色线框，次操作灰色线框；缺省为次操作。 */
+    style?: 'primary' | 'secondary';
+}
+
+/** 同一行的按钮；QQ 原生键盘最多五行，每行最多五个。 */
+export interface MessageButtonRow {
+    buttons: MessageButton[];
+}
+
 /** 下发给客户端的消息主体 **/
 export interface IMessage {
     handleType: MessageHandleType;
@@ -224,4 +237,6 @@ export interface IMessage {
     line: IMessageItem[];
     companionCard?: CompanionCardData;
     titleCard?: TitleCardData;
+    /** 通用指令按钮；不支持原生按钮的平台保留文字指令。 */
+    buttons?: MessageButtonRow[];
 }