@zxh126/pi-qqbot 2.4.0 → 2.6.0

package/progress.ts

@@ -1,176 +1,176 @@
-/**
- * 任务进度摘要：把 run 期间的事件（轮次、工具调用、流式文本、token）压成一条
- * 适合发到 QQ 的短消息。纯本地字符串拼接，不产生任何模型调用。
- */
-
-import { redactSecrets, shortRedacted } from "./redact";
-
-export interface ProgressSettings {
-  /** 是否自动推送进度 */
-  enabled: boolean;
-  /** 推送间隔（毫秒） */
-  intervalMs: number;
-}
-
-const MAX_PROGRESS_CHARS = 320;
-const TOOL_PREVIEW_CHARS = 60;
-const TAIL_CHARS = 120;
-
-/** 把工具参数压成一句人能看懂的话（已脱敏、已截断） */
-export function toolPreview(toolName: string, args: any): string {
-  const input = args ?? {};
-  switch (toolName) {
-    case "bash":
-    case "powershell":
-      return shortRedacted(input.command ?? "");
-    case "write":
-    case "edit":
-    case "read":
-      return shortRedacted(input.path ?? input.file ?? input.filePath ?? "");
-    case "grep":
-    case "bgrep":
-      return shortRedacted(input.pattern ?? "");
-    case "glob":
-    case "find":
-      return shortRedacted(input.pattern ?? input.path ?? "");
-    default:
-      try {
-        return shortRedacted(JSON.stringify(input));
-      } catch {
-        return shortRedacted(String(input));
-      }
-  }
-}
-
-const fmtDuration = (ms: number): string => {
-  const total = Math.max(0, Math.round(ms / 1000));
-  const h = Math.floor(total / 3600);
-  const m = Math.floor((total % 3600) / 60);
-  const s = total % 60;
-  if (h > 0) return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
-  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
-};
-
-const fmtTokens = (n: number): string =>
-  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(2)}M` : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n);
-
-interface OpenTool {
-  name: string;
-  preview: string;
-  startedAt: number;
-}
-
-export class ProgressTracker {
-  running = false;
-  private startedAt = 0;
-  private turns = 0;
-  private counts = new Map<string, number>();
-  private failures = 0;
-  private tokens = 0;
-  private tail = "";
-  private open = new Map<string, OpenTool>();
-  private last: { name: string; preview: string; ms?: number; ok?: boolean } | null = null;
-
-  start(now = Date.now()): void {
-    this.running = true;
-    this.startedAt = now;
-    this.turns = 0;
-    this.counts.clear();
-    this.failures = 0;
-    this.tokens = 0;
-    this.tail = "";
-    this.open.clear();
-    this.last = null;
-  }
-
-  stop(): void {
-    this.running = false;
-    this.open.clear();
-    this.tail = "";
-  }
-
-  toolStart(callId: string, toolName: string, args: any, now = Date.now()): void {
-    if (!this.running) return;
-    const name = toolName || "tool";
-    this.open.set(callId, { name, preview: toolPreview(name, args), startedAt: now });
-    this.counts.set(name, (this.counts.get(name) ?? 0) + 1);
-    this.tail = "";
-  }
-
-  toolEnd(callId: string, toolName: string, isError: boolean, durationMs?: number, now = Date.now()): void {
-    if (!this.running) return;
-    const open = this.open.get(callId);
-    this.open.delete(callId);
-    if (isError) this.failures += 1;
-    this.last = {
-      name: open?.name ?? toolName ?? "tool",
-      preview: open?.preview ?? "",
-      ms: typeof durationMs === "number" ? durationMs : open ? now - open.startedAt : undefined,
-      ok: !isError,
-    };
-  }
-
-  turn(): void {
-    if (this.running) this.turns += 1;
-  }
-
-  addUsage(usage: any): void {
-    if (!this.running) return;
-    const total = Number(usage?.totalTokens ?? 0);
-    if (Number.isFinite(total) && total > 0) this.tokens += total;
-  }
-
-  appendText(delta: string): void {
-    if (!this.running || !delta) return;
-    this.tail = `${this.tail}${delta}`.slice(-TAIL_CHARS * 2);
-  }
-
-  /** 当前正在执行的工具（如果卡在某个长命令上，这比「正在写」有用） */
-  private runningTool(): OpenTool | null {
-    let newest: OpenTool | null = null;
-    for (const tool of this.open.values()) {
-      if (!newest || tool.startedAt > newest.startedAt) newest = tool;
-    }
-    return newest;
-  }
-
-  /** 一条可直接发到 QQ 的摘要；没有可说的内容时返回空串 */
-  summary(now = Date.now()): string {
-    if (!this.running) return "";
-    const head: string[] = [`[进度 ${fmtDuration(now - this.startedAt)}]`];
-    if (this.turns > 0) head.push(`第 ${this.turns} 轮`);
-
-    const totalCalls = [...this.counts.values()].reduce((sum, n) => sum + n, 0);
-    if (totalCalls > 0) {
-      const top = [...this.counts.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 3)
-        .map(([name, n]) => `${name} ${n}`)
-        .join(" / ");
-      head.push(`工具 ${totalCalls} 次（${top}）`);
-    }
-    if (this.failures > 0) head.push(`失败 ${this.failures}`);
-
-    const lines: string[] = [head.join(" · ")];
-
-    if (this.last) {
-      const timing = this.last.ms !== undefined ? ` · ${(this.last.ms / 1000).toFixed(1)}s` : "";
-      const status = this.last.ok === false ? " · 失败" : "";
-      const preview = this.last.preview ? ` "${this.last.preview}"` : "";
-      lines.push(`最近: ${this.last.name}${preview}${timing}${status}`);
-    }
-
-    const active = this.runningTool();
-    if (active) {
-      lines.push(`正在: ${active.name}${active.preview ? ` "${active.preview}"` : ""}（已 ${(Math.max(0, now - active.startedAt) / 1000).toFixed(0)}s）`);
-    } else {
-      const tail = shortRedacted(this.tail.slice(-TAIL_CHARS), TAIL_CHARS);
-      if (tail) lines.push(`正在: ${tail}`);
-    }
-
-    if (this.tokens > 0) lines.push(`已用 ${fmtTokens(this.tokens)} tok`);
-
-    const text = redactSecrets(lines.join("\n"));
-    return text.length > MAX_PROGRESS_CHARS ? `${text.slice(0, MAX_PROGRESS_CHARS)}…` : text;
-  }
-}
+/**
+ * 任务进度摘要：把 run 期间的事件（轮次、工具调用、流式文本、token）压成一条
+ * 适合发到 QQ 的短消息。纯本地字符串拼接，不产生任何模型调用。
+ */
+
+import { redactSecrets, shortRedacted } from "./redact";
+
+export interface ProgressSettings {
+  /** 是否自动推送进度 */
+  enabled: boolean;
+  /** 推送间隔（毫秒） */
+  intervalMs: number;
+}
+
+const MAX_PROGRESS_CHARS = 320;
+const TOOL_PREVIEW_CHARS = 60;
+const TAIL_CHARS = 120;
+
+/** 把工具参数压成一句人能看懂的话（已脱敏、已截断） */
+export function toolPreview(toolName: string, args: any): string {
+  const input = args ?? {};
+  switch (toolName) {
+    case "bash":
+    case "powershell":
+      return shortRedacted(input.command ?? "");
+    case "write":
+    case "edit":
+    case "read":
+      return shortRedacted(input.path ?? input.file ?? input.filePath ?? "");
+    case "grep":
+    case "bgrep":
+      return shortRedacted(input.pattern ?? "");
+    case "glob":
+    case "find":
+      return shortRedacted(input.pattern ?? input.path ?? "");
+    default:
+      try {
+        return shortRedacted(JSON.stringify(input));
+      } catch {
+        return shortRedacted(String(input));
+      }
+  }
+}
+
+const fmtDuration = (ms: number): string => {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  if (h > 0) return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+};
+
+const fmtTokens = (n: number): string =>
+  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(2)}M` : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n);
+
+interface OpenTool {
+  name: string;
+  preview: string;
+  startedAt: number;
+}
+
+export class ProgressTracker {
+  running = false;
+  private startedAt = 0;
+  private turns = 0;
+  private counts = new Map<string, number>();
+  private failures = 0;
+  private tokens = 0;
+  private tail = "";
+  private open = new Map<string, OpenTool>();
+  private last: { name: string; preview: string; ms?: number; ok?: boolean } | null = null;
+
+  start(now = Date.now()): void {
+    this.running = true;
+    this.startedAt = now;
+    this.turns = 0;
+    this.counts.clear();
+    this.failures = 0;
+    this.tokens = 0;
+    this.tail = "";
+    this.open.clear();
+    this.last = null;
+  }
+
+  stop(): void {
+    this.running = false;
+    this.open.clear();
+    this.tail = "";
+  }
+
+  toolStart(callId: string, toolName: string, args: any, now = Date.now()): void {
+    if (!this.running) return;
+    const name = toolName || "tool";
+    this.open.set(callId, { name, preview: toolPreview(name, args), startedAt: now });
+    this.counts.set(name, (this.counts.get(name) ?? 0) + 1);
+    this.tail = "";
+  }
+
+  toolEnd(callId: string, toolName: string, isError: boolean, durationMs?: number, now = Date.now()): void {
+    if (!this.running) return;
+    const open = this.open.get(callId);
+    this.open.delete(callId);
+    if (isError) this.failures += 1;
+    this.last = {
+      name: open?.name ?? toolName ?? "tool",
+      preview: open?.preview ?? "",
+      ms: typeof durationMs === "number" ? durationMs : open ? now - open.startedAt : undefined,
+      ok: !isError,
+    };
+  }
+
+  turn(): void {
+    if (this.running) this.turns += 1;
+  }
+
+  addUsage(usage: any): void {
+    if (!this.running) return;
+    const total = Number(usage?.totalTokens ?? 0);
+    if (Number.isFinite(total) && total > 0) this.tokens += total;
+  }
+
+  appendText(delta: string): void {
+    if (!this.running || !delta) return;
+    this.tail = `${this.tail}${delta}`.slice(-TAIL_CHARS * 2);
+  }
+
+  /** 当前正在执行的工具（如果卡在某个长命令上，这比「正在写」有用） */
+  private runningTool(): OpenTool | null {
+    let newest: OpenTool | null = null;
+    for (const tool of this.open.values()) {
+      if (!newest || tool.startedAt > newest.startedAt) newest = tool;
+    }
+    return newest;
+  }
+
+  /** 一条可直接发到 QQ 的摘要；没有可说的内容时返回空串 */
+  summary(now = Date.now()): string {
+    if (!this.running) return "";
+    const head: string[] = [`[进度 ${fmtDuration(now - this.startedAt)}]`];
+    if (this.turns > 0) head.push(`第 ${this.turns} 轮`);
+
+    const totalCalls = [...this.counts.values()].reduce((sum, n) => sum + n, 0);
+    if (totalCalls > 0) {
+      const top = [...this.counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([name, n]) => `${name} ${n}`)
+        .join(" / ");
+      head.push(`工具 ${totalCalls} 次（${top}）`);
+    }
+    if (this.failures > 0) head.push(`失败 ${this.failures}`);
+
+    const lines: string[] = [head.join(" · ")];
+
+    if (this.last) {
+      const timing = this.last.ms !== undefined ? ` · ${(this.last.ms / 1000).toFixed(1)}s` : "";
+      const status = this.last.ok === false ? " · 失败" : "";
+      const preview = this.last.preview ? ` "${this.last.preview}"` : "";
+      lines.push(`最近: ${this.last.name}${preview}${timing}${status}`);
+    }
+
+    const active = this.runningTool();
+    if (active) {
+      lines.push(`正在: ${active.name}${active.preview ? ` "${active.preview}"` : ""}（已 ${(Math.max(0, now - active.startedAt) / 1000).toFixed(0)}s）`);
+    } else {
+      const tail = shortRedacted(this.tail.slice(-TAIL_CHARS), TAIL_CHARS);
+      if (tail) lines.push(`正在: ${tail}`);
+    }
+
+    if (this.tokens > 0) lines.push(`已用 ${fmtTokens(this.tokens)} tok`);
+
+    const text = redactSecrets(lines.join("\n"));
+    return text.length > MAX_PROGRESS_CHARS ? `${text.slice(0, MAX_PROGRESS_CHARS)}…` : text;
+  }
+}

package/qq/api.ts

@@ -1,4 +1,5 @@
 import { MAX_REPLIES_PER_MSG_ID } from "../constants";
+import type { InlineKeyboard } from "./keyboard";
 
 export interface QQApiOptions {
   restBase: string;
@@ -9,6 +10,8 @@ export interface QQApiOptions {
 export interface SendOptions {
   msgId?: string;
   format?: "text" | "markdown";
+  /** 内联键盘：仅随 markdown 消息发送（官方要求），text 格式或回退时自动丢弃 */
+  keyboard?: InlineKeyboard;
 }
 
 export interface MediaSendOptions {
@@ -78,6 +81,18 @@ export class QQApi {
     await this.postWithRetry(openid, body);
   }
 
+  /** 回应按钮互动（INTERACTION_CREATE）：平台要求 5 秒内 ACK，否则客户端一直 loading */
+  async acknowledgeInteraction(interactionId: string, code: number): Promise<void> {
+    const fetchFn = this.opts.fetchFn ?? fetch;
+    const token = await this.opts.getToken();
+    const res = await fetchFn(`${this.opts.restBase}/interactions/${interactionId}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json", Authorization: `QQBot ${token}` },
+      body: JSON.stringify({ code }),
+    });
+    if (!res.ok) throw new Error(`acknowledgeInteraction failed: HTTP ${res.status} ${await res.text()}`);
+  }
+
   private async doSend(openid: string, content: string, options: SendOptions): Promise<void> {
     const format = options.format ?? "text";
     let msgId = options.msgId;
@@ -92,6 +107,8 @@ export class QQApi {
         body.msg_id = msgId;
         body.msg_seq = seq;
       }
+      // 键盘只随 markdown 发送；回退 text 时自然不带（fmt === "text" 不挂）
+      if (fmt === "markdown" && options.keyboard) body.keyboard = options.keyboard;
       return body;
     };
     try {

package/qq/auth.ts

@@ -1,35 +1,35 @@
-import { TOKEN_URL } from "../constants";
-
-export class AuthManager {
-  private token: string | null = null;
-  private expireAt = 0;
-
-  constructor(
-    private appId: string,
-    private appSecret: string,
-    private fetchFn: typeof fetch = fetch,
-  ) {}
-
-  async getToken(): Promise<string> {
-    const now = Date.now();
-    if (this.token && now < this.expireAt - 60_000) return this.token;
-    const res = await this.fetchFn(TOKEN_URL, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ appId: this.appId, clientSecret: this.appSecret }),
-    });
-    if (!res.ok) throw new Error(`getAppAccessToken failed: HTTP ${res.status}`);
-    const data = (await res.json()) as any;
-    const token = String(data.access_token ?? "");
-    // QQ 平台对无效凭据返回 HTTP 200 + code 100016，以前只在后面拿空 token 去连网关，
-    // 表现为「锁抢到了但永远连不上」；这里直接抛，抢占阶段就能发现。
-    if (!token) {
-      const code = data?.code ?? "-";
-      const message = data?.message ?? data?.msg ?? "未返回 access_token";
-      throw new Error(`getAppAccessToken 被拒: code=${code} ${message}`);
-    }
-    this.token = token;
-    this.expireAt = Date.now() + Number(data.expires_in ?? 0) * 1000;
-    return this.token;
-  }
-}
+import { TOKEN_URL } from "../constants";
+
+export class AuthManager {
+  private token: string | null = null;
+  private expireAt = 0;
+
+  constructor(
+    private appId: string,
+    private appSecret: string,
+    private fetchFn: typeof fetch = fetch,
+  ) {}
+
+  async getToken(): Promise<string> {
+    const now = Date.now();
+    if (this.token && now < this.expireAt - 60_000) return this.token;
+    const res = await this.fetchFn(TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ appId: this.appId, clientSecret: this.appSecret }),
+    });
+    if (!res.ok) throw new Error(`getAppAccessToken failed: HTTP ${res.status}`);
+    const data = (await res.json()) as any;
+    const token = String(data.access_token ?? "");
+    // QQ 平台对无效凭据返回 HTTP 200 + code 100016，以前只在后面拿空 token 去连网关，
+    // 表现为「锁抢到了但永远连不上」；这里直接抛，抢占阶段就能发现。
+    if (!token) {
+      const code = data?.code ?? "-";
+      const message = data?.message ?? data?.msg ?? "未返回 access_token";
+      throw new Error(`getAppAccessToken 被拒: code=${code} ${message}`);
+    }
+    this.token = token;
+    this.expireAt = Date.now() + Number(data.expires_in ?? 0) * 1000;
+    return this.token;
+  }
+}

package/qq/gateway.ts

@@ -27,13 +27,24 @@ export interface QQMessage {
   quotedText?: string;
 }
 
-export interface QQGatewayOptions {
+/** 按钮点击回调（INTERACTION_CREATE）*/
+ export interface QQInteractionEvent {
+  id?: string;
+  scene?: string;
+  user_openid?: string;
+  group_openid?: string;
+  group_member_openid?: string;
+  data?: { resolved?: { button_data?: string; button_id?: string } };
+ }
+
+ export interface QQGatewayOptions {
   getGatewayUrl: () => Promise<string>;
   getToken: () => Promise<string>;
   intents: number;
   connected: () => void;
   disconnected: () => void;
   message: (msg: QQMessage) => Promise<void> | void;
+  interaction: (event: QQInteractionEvent) => void | Promise<void>;
   reconnectBaseMs?: number;
   maxSeen?: number;
 }
@@ -154,8 +165,10 @@ export class QQGateway {
       case OP_DISPATCH: {
         this.lastSeq = pkt.s ?? this.lastSeq;
         const d = pkt.d ?? {};
-        if (this.isDuplicate(pkt.id ?? String(d.msg_id ?? d.id ?? ""))) return;
-        this.handleDispatch(pkt.t ?? "", d);
+        const t = pkt.t ?? "";
+        // interaction 有 5 秒 ACK 要求：平台重投时也必须再回应，不能按消息去重
+        if (t !== "INTERACTION_CREATE" && this.isDuplicate(pkt.id ?? String(d.msg_id ?? d.id ?? ""))) return;
+        this.handleDispatch(t, d);
         break;
       }
     }
@@ -205,6 +218,10 @@ export class QQGateway {
       this.opts.connected();
       return;
     }
+    if (t === "INTERACTION_CREATE") {
+      this.opts.interaction(d as QQInteractionEvent);
+      return;
+    }
     if (t === "C2C_MESSAGE_CREATE") {
       const rawAttachments = Array.isArray(d.attachments) ? d.attachments : [];
       const attachments = rawAttachments

package/qq/keyboard.ts

@@ -0,0 +1,141 @@
+/**
+ * QQ 内联键盘（消息按钮）构建与 button_data 编解码。
+ *
+ * 官方规则（bot.q.qq.com「消息按钮」文档）：
+ * - 键盘只随 markdown 消息（msg_type=2）发送；
+ * - 最多 5 行 × 每行 5 个按钮；
+ * - action.type=1 为回调按钮：data 原样回传给后台（INTERACTION_CREATE 事件）；
+ * - 自定义按钮需平台「内邀开通」；发送失败时调用方应降级纯文本（编号回复仍可用）。
+ */
+
+export interface KeyboardButton {
+  id: string;
+  render_data: { label: string; visited_label: string; style: number };
+  action: {
+    type: 1;
+    permission: { type: 2 };
+    data: string;
+    unsupport_tips: string;
+  };
+}
+
+export interface InlineKeyboard {
+  content: { rows: { buttons: KeyboardButton[] }[] };
+}
+
+/** 按钮 label 保守上限（官方未给硬限，对齐同平台 dsh-qqbot 的 10 字符） */
+export const BUTTON_LABEL_MAX = 10;
+/** 每行按钮数（2 列布局，减少选项多时的刷屏） */
+export const BUTTONS_PER_ROW = 2;
+/** 官方上限：5 行 */
+export const BUTTON_ROW_MAX = 5;
+
+/** 截断按钮 label，超长补省略号（正文保留完整文本） */
+export function buttonLabel(text: string): string {
+  const s = String(text ?? "").trim();
+  return s.length > BUTTON_LABEL_MAX ? `${s.slice(0, BUTTON_LABEL_MAX - 1)}…` : s;
+}
+
+/** 审批按钮载荷：s = 审批编号（与 Approver.pending 的 seq 对应） */
+export interface ApprovalButtonData {
+  t: "approval";
+  d: "allow" | "deny" | "always";
+  s: number;
+}
+
+/** 选择按钮载荷：i = 1 起始的选项编号（与「回复编号」口径一致） */
+export interface PickButtonData {
+  t: "pick";
+  i: number;
+}
+
+export function encodeButtonData(data: ApprovalButtonData | PickButtonData): string {
+  return JSON.stringify(data);
+}
+
+/** 解码 button_data；非法 JSON 或缺少合法顶层判别字段时返回 undefined */
+export function decodeButtonData(raw: unknown): ApprovalButtonData | PickButtonData | undefined {
+  if (typeof raw !== "string" || !raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as Partial<ApprovalButtonData | PickButtonData> | null;
+    if (!parsed || typeof parsed !== "object") return undefined;
+    if (parsed.t === "approval" && (parsed.d === "allow" || parsed.d === "deny" || parsed.d === "always")) {
+      return parsed as ApprovalButtonData;
+    }
+    if (parsed.t === "pick" && typeof parsed.i === "number" && Number.isFinite(parsed.i)) {
+      return parsed as PickButtonData;
+    }
+  } catch {
+    // 非法 JSON → undefined
+  }
+  return undefined;
+}
+
+/**
+ * 审批键盘：允许一次 / 拒绝（非 strict 再加「以后都同意」），全部放在一行。
+ * 点击由服务端按 seq 匹配 pending：过期卡片点击不 settle（ACK 重复操作）。
+ */
+export function buildApprovalKeyboard(seq: number, opts: { strict?: boolean } = {}): InlineKeyboard {
+  const allow: KeyboardButton = {
+    id: `approval-allow-${seq}`,
+    render_data: { label: "✅ 允许一次", visited_label: "✓ 已允许", style: 1 },
+    action: {
+      type: 1,
+      permission: { type: 2 },
+      data: encodeButtonData({ t: "approval", d: "allow", s: seq }),
+      unsupport_tips: "当前客户端不支持按钮，请回复「同意」",
+    },
+  };
+  const deny: KeyboardButton = {
+    id: `approval-deny-${seq}`,
+    render_data: { label: "❌ 拒绝", visited_label: "✓ 已拒绝", style: 0 },
+    action: {
+      type: 1,
+      permission: { type: 2 },
+      data: encodeButtonData({ t: "approval", d: "deny", s: seq }),
+      unsupport_tips: "当前客户端不支持按钮，请回复「拒绝」",
+    },
+  };
+  const buttons: KeyboardButton[] = [allow, deny];
+  if (!opts.strict) {
+    buttons.push({
+      id: `approval-always-${seq}`,
+      render_data: { label: "🚀 以后都同意", visited_label: "✓ 已放行", style: 1 },
+      action: {
+        type: 1,
+        permission: { type: 2 },
+        data: encodeButtonData({ t: "approval", d: "always", s: seq }),
+        unsupport_tips: "当前客户端不支持按钮，请回复「以后都同意」",
+      },
+    });
+  }
+  return { content: { rows: [{ buttons }] } };
+}
+
+/**
+ * 选择键盘：每行 2 个按钮、最多 5 行；超出部分不生成按钮（正文编号仍可用）。
+ * i 从 1 起与「回复编号」一致。
+ */
+export function buildPickerKeyboard(items: { label: string }[]): InlineKeyboard | undefined {
+  if (items.length === 0) return undefined;
+  const rows: { buttons: KeyboardButton[] }[] = [];
+  const cap = BUTTON_ROW_MAX * BUTTONS_PER_ROW;
+  for (let i = 0; i < items.length && i < cap; i += BUTTONS_PER_ROW) {
+    rows.push({
+      buttons: items.slice(i, i + BUTTONS_PER_ROW).map((item, offset) => {
+        const idx = i + offset;
+        return {
+          id: `pick-${idx}`,
+          render_data: { label: buttonLabel(item.label), visited_label: "✓ 已选", style: 1 },
+          action: {
+            type: 1,
+            permission: { type: 2 },
+            data: encodeButtonData({ t: "pick", i: idx + 1 }),
+            unsupport_tips: "当前客户端不支持按钮，请回复编号选择",
+          },
+        };
+      }),
+    });
+  }
+  return { content: { rows } };
+}