@ycodium-ai/plugin-im 0.2.2566 → 0.2.2570

package/README.md

@@ -51,10 +51,18 @@ written as plugin facts (`ctx.events.append`) and folded back by a pure function
 archived or moved to another project is dropped on the next message.
 
 Chat commands: `/stop`, `/status`, `/new`, `/sessions`, `/resume`, `/model`,
-`/plan`, `/team`, `/thread`, `/help`. `/sessions` and `/resume` only list and
+`/plan`, `/team`, `/thread`, `/help`, `/panel`. `/sessions` and `/resume` only list and
 switch threads this plugin opened, since the host lets a plugin send only into
 its own threads.
 
+On Lark, `/panel` sends a command panel card (`/help` stays text and ends with a pointer to it; other platforms' `/help` does not mention it): every command above
+is a button, and the ones that take an argument (a thread, a team, a model) open
+a second view on the same card with a Back button. Each card keeps its own view
+stack in memory (`src/panelController.ts`), so after a restart an old card only
+answers that it has expired. A tap runs the same handler as the typed command and
+waits in the same per-group queue as typed messages. Another platform opts in by
+implementing the optional `panel` surface on its adapter (`src/adapter.ts`).
+
 The **Reply language** setting (Chinese by default, or English) picks the
 language of everything the bot says itself. The settings card follows the
 interface language instead. The copy lives in `locales/en.json` and

package/dist/index.js

@@ -126208,6 +126208,7 @@ var ZH_ALIASES = {
   \u72B6\u6001: "status",
   \u65B0\u5BF9\u8BDD: "new",
   \u5E2E\u52A9: "help",
+  \u9762\u677F: "panel",
   \u4F1A\u8BDD\u5217\u8868: "sessions"
 };
 var resolveTeam = (query, teams) => {
@@ -126225,6 +126226,7 @@ var parseChatCommand = (input) => {
   if (/^\/status$/i.test(trimmed)) return { kind: "status" };
   if (/^\/new$/i.test(trimmed)) return { kind: "new" };
   if (/^\/help$/i.test(trimmed)) return { kind: "help" };
+  if (/^\/panel$/i.test(trimmed)) return { kind: "panel" };
   if (/^\/sessions$/i.test(trimmed)) return { kind: "sessions" };
   const resume = resumeArgument(input.text, input.chinese);
   if (resume !== void 0) {
@@ -126249,7 +126251,7 @@ var parseChatCommand = (input) => {
   }
   return { kind: "message" };
 };
-var helpText = (t) => [
+var helpText = (t, options = {}) => [
   t("help.title"),
   t("help.stop"),
   t("help.status"),
@@ -126260,7 +126262,8 @@ var helpText = (t) => [
   t("help.plan"),
   t("help.team"),
   t("help.thread"),
-  t("help.aliases")
+  t("help.aliases"),
+  ...options.panel === true ? ["", t("help.panel")] : []
 ].join("\n");
 var describeTargets = (target, teams, t) => {
   const current = target.kind === "thread" ? t("targets.currentThread") : t("targets.currentTeam", {
@@ -131972,6 +131975,40 @@ var buildApprovalSettledCard = (settlement, t) => ({
     }
   ]
 });
+var PANEL_TEMPLATE = {
+  menu: "blue",
+  busy: "grey",
+  notice: "orange"
+};
+var panelButton = (button) => ({
+  tag: "button",
+  text: { tag: "plain_text", content: button.label },
+  type: button.danger === true ? "danger" : "default",
+  value: button.action.arg === void 0 ? { pn: button.action.op } : { pn: button.action.op, a: button.action.arg }
+});
+var buildPanelCard = (card) => {
+  const elements = [];
+  if (card.text !== "") elements.push({ tag: "markdown", content: stripAngleBrackets(card.text) });
+  for (const group of card.groups) {
+    if (group.buttons.length === 0) continue;
+    if (group.heading !== null) {
+      elements.push({ tag: "markdown", content: `**${stripAngleBrackets(group.heading)}**` });
+    }
+    elements.push({ tag: "action", actions: group.buttons.map(panelButton) });
+  }
+  if (card.nav.length > 0) {
+    elements.push({ tag: "hr" }, { tag: "action", actions: card.nav.map(panelButton) });
+  }
+  if (elements.length === 0) elements.push({ tag: "markdown", content: " " });
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: card.title },
+      template: PANEL_TEMPLATE[card.tone]
+    },
+    elements
+  };
+};
 
 // src/larkInbound.ts
 var import_node_sdk = __toESM(require_lib2(), 1);
@@ -132087,26 +132124,44 @@ var fetchMessageResource = async (input) => {
   }
   return new Uint8Array(await response.arrayBuffer());
 };
-var cardActionToken = (event) => {
+var cardActionValue = (event) => {
   const roots = [event, event?.event];
   for (const root of roots) {
     const value = root?.action?.value;
     if (value === void 0 || value === null) continue;
-    let record;
-    if (typeof value === "string") {
-      try {
-        record = JSON.parse(value);
-      } catch {
-        record = void 0;
-      }
-    } else {
-      record = value;
+    if (typeof value !== "string") return value;
+    try {
+      return JSON.parse(value);
+    } catch {
+      continue;
     }
-    const token = record?.["tk"];
-    if (typeof token === "string" && token.length > 0) return token;
   }
   return null;
 };
+var cardActionToken = (event) => {
+  const token = cardActionValue(event)?.["tk"];
+  return typeof token === "string" && token.length > 0 ? token : null;
+};
+var cardActionPanel = (event) => {
+  const value = cardActionValue(event);
+  const op = value?.["pn"];
+  if (typeof op !== "string" || op === "") return null;
+  const arg = value?.["a"];
+  const roots = [event, event?.event];
+  const pick = (read) => {
+    for (const root of roots) {
+      if (typeof root !== "object" || root === null) continue;
+      const candidate = read(root);
+      if (typeof candidate === "string" && candidate !== "") return candidate;
+    }
+    return null;
+  };
+  const context = (root) => typeof root["context"] === "object" && root["context"] !== null ? root["context"] : void 0;
+  const cardId = pick((root) => context(root)?.["open_message_id"] ?? root["open_message_id"]);
+  const chatId = pick((root) => context(root)?.["open_chat_id"] ?? root["open_chat_id"]);
+  if (cardId === null || chatId === null) return null;
+  return { op, arg: typeof arg === "string" ? arg : null, cardId, chatId };
+};
 var cardActionOperator = (event) => {
   const roots = [event, event?.event];
   for (const root of roots) {
@@ -132127,6 +132182,11 @@ var startLarkInbound = (input) => {
     // 卡片点击走的也是 event 帧（实测过），所以在同一个 dispatcher 上注册就行，不用开
     // webhook。这条不需要 @：点按钮直接推给应用。
     "card.action.trigger": (event) => {
+      const panel = cardActionPanel(event);
+      if (panel !== null) {
+        const notice2 = input.onPanelClick?.(panel, cardActionOperator(event)) ?? null;
+        return notice2 === null ? {} : { toast: { type: "info", content: notice2 } };
+      }
       const token = cardActionToken(event);
       if (token === null) return {};
       const notice = input.onCardAction(token, cardActionOperator(event));
@@ -132185,6 +132245,13 @@ var makeLarkAdapter = (deps) => {
         appSecret,
         onError: handlers.onError,
         onCardAction: handlers.onApproval,
+        onPanelClick: (click, operatorOpenId) => handlers.onPanelClick?.({
+          chatId: click.chatId,
+          cardId: click.cardId,
+          operatorId: operatorOpenId,
+          op: click.op,
+          arg: click.arg
+        }) ?? null,
         onMessage: (message) => {
           handlers.onMessage({
             messageId: message.messageId,
@@ -132263,6 +132330,22 @@ var makeLarkAdapter = (deps) => {
         });
       }
     },
+    panel: {
+      open: async (binding, card) => sendCard({
+        http: deps.http,
+        token: await tenantToken(binding),
+        chatId: binding.chatId,
+        card: buildPanelCard(card)
+      }),
+      update: async (binding, cardId, card) => {
+        await patchCard({
+          http: deps.http,
+          token: await tenantToken(binding),
+          messageId: cardId,
+          card: buildPanelCard(card)
+        });
+      }
+    },
     acknowledge: async (binding, messageId) => addReaction({
       http: deps.http,
       token: await tenantToken(binding),
@@ -132425,7 +132508,8 @@ var en_default = {
     sessions: "\xB7 /sessions \u2014 list the sessions this bot opened for this group's project",
     resume: "\xB7 /resume number \u2014 switch to one of them (a number from /sessions, or the start of its id)",
     model: "\xB7 /model \u2014 see the model this group uses; /model number or /model instance/model switches it",
-    plan: "\xB7 /plan \u2014 toggle plan mode (the agent proposes a plan instead of acting); /plan on, /plan off set it"
+    plan: "\xB7 /plan \u2014 toggle plan mode (the agent proposes a plan instead of acting); /plan on, /plan off set it",
+    panel: "Send /panel to open the command panel with a button for every command."
   },
   sessions: {
     title: "Sessions this bot opened for this group's project ({{count}}):",
@@ -132498,6 +132582,48 @@ var en_default = {
       chosen: "Chosen: {{label}}",
       elsewhere: "Already handled elsewhere (the web app or another client)."
     }
+  },
+  panel: {
+    title: "Command panel",
+    hint: "A button does the same as typing its command. You can still type.",
+    category: {
+      session: "Session",
+      target: "Send to",
+      system: "Settings and status"
+    },
+    cmd: {
+      new: "New session",
+      stop: "Stop this turn",
+      sessions: "Sessions",
+      team: "Send to a team",
+      thread: "Normal session",
+      model: "Model",
+      planOn: "Plan mode: on",
+      planOff: "Plan mode: off",
+      status: "Status",
+      help: "Text help"
+    },
+    back: "Back",
+    prev: "Previous",
+    next: "Next",
+    page: "Page {{page}} of {{total}}",
+    loading: "Loading\u2026",
+    working: "Working on it\u2026",
+    expired: "This panel has expired. Send /panel again.",
+    busy: "The last tap is still being handled. Give it a moment.",
+    loadFailed: "Could not read that just now. Try again in a moment.",
+    sessions: {
+      title: "Pick a session",
+      hint: "Tap one to switch to it."
+    },
+    teams: {
+      title: "Pick a team",
+      hint: "Tap a team and the next messages go to it.",
+      unavailable: "Could not read the team list."
+    },
+    models: {
+      title: "Pick a model"
+    }
   }
 };
 
@@ -132632,7 +132758,8 @@ var zh_CN_default = {
     sessions: "\xB7 /sessions \u2014\u2014 \u5217\u51FA\u672C\u673A\u5668\u4EBA\u4E3A\u8FD9\u4E2A\u7FA4\u7684\u9879\u76EE\u5F00\u8FC7\u7684\u4F1A\u8BDD",
     resume: "\xB7 /resume \u7F16\u53F7 \u2014\u2014 \u5207\u5230\u5176\u4E2D\u4E00\u6761\uFF08/sessions \u91CC\u7684\u7F16\u53F7\uFF0C\u6216\u4F1A\u8BDD id \u7684\u5F00\u5934\uFF09",
     model: "\xB7 /model \u2014\u2014 \u770B\u8FD9\u4E2A\u7FA4\u7528\u7684\u6A21\u578B\uFF1B/model \u7F16\u53F7 \u6216 /model \u5B9E\u4F8B/\u6A21\u578B \u5207\u6362",
-    plan: "\xB7 /plan \u2014\u2014 \u5F00\u5173\u8BA1\u5212\u6A21\u5F0F\uFF08agent \u5148\u51FA\u8BA1\u5212\u3001\u4E0D\u52A8\u624B\uFF09\uFF1B/plan on\u3001/plan off \u660E\u786E\u8BBE\u5B9A"
+    plan: "\xB7 /plan \u2014\u2014 \u5F00\u5173\u8BA1\u5212\u6A21\u5F0F\uFF08agent \u5148\u51FA\u8BA1\u5212\u3001\u4E0D\u52A8\u624B\uFF09\uFF1B/plan on\u3001/plan off \u660E\u786E\u8BBE\u5B9A",
+    panel: "\u53D1 /panel \u6253\u5F00\u53EF\u70B9\u7684\u547D\u4EE4\u9762\u677F\u3002"
   },
   sessions: {
     title: "\u672C\u673A\u5668\u4EBA\u4E3A\u8FD9\u4E2A\u7FA4\u7684\u9879\u76EE\u5F00\u8FC7\u7684\u4F1A\u8BDD\uFF08{{count}} \u6761\uFF09\uFF1A",
@@ -132705,6 +132832,48 @@ var zh_CN_default = {
       chosen: "\u5DF2\u9009\uFF1A{{label}}",
       elsewhere: "\u5DF2\u5728\u522B\u5904\u5904\u7406\uFF08\u7F51\u9875\u6216\u5176\u4ED6\u5BA2\u6237\u7AEF\uFF09\u3002"
     }
+  },
+  panel: {
+    title: "\u547D\u4EE4\u9762\u677F",
+    hint: "\u70B9\u6309\u94AE\u7B49\u4E8E\u6253\u51FA\u5BF9\u5E94\u7684\u547D\u4EE4\uFF0C\u4E5F\u53EF\u4EE5\u76F4\u63A5\u6253\u5B57\u3002",
+    category: {
+      session: "\u4F1A\u8BDD",
+      target: "\u6D3E\u7ED9\u8C01",
+      system: "\u8BBE\u7F6E\u4E0E\u72B6\u6001"
+    },
+    cmd: {
+      new: "\u65B0\u4F1A\u8BDD",
+      stop: "\u505C\u6B62\u672C\u8F6E",
+      sessions: "\u4F1A\u8BDD\u5217\u8868",
+      team: "\u6D3E\u7ED9\u56E2\u961F",
+      thread: "\u666E\u901A\u4F1A\u8BDD",
+      model: "\u6A21\u578B",
+      planOn: "\u8BA1\u5212\u6A21\u5F0F\uFF1A\u5F00",
+      planOff: "\u8BA1\u5212\u6A21\u5F0F\uFF1A\u5173",
+      status: "\u72B6\u6001",
+      help: "\u6587\u5B57\u8BF4\u660E"
+    },
+    back: "\u8FD4\u56DE",
+    prev: "\u4E0A\u4E00\u9875",
+    next: "\u4E0B\u4E00\u9875",
+    page: "\u7B2C {{page}} / {{total}} \u9875",
+    loading: "\u52A0\u8F7D\u4E2D\u2026",
+    working: "\u5904\u7406\u4E2D\u2026",
+    expired: "\u9762\u677F\u5DF2\u8FC7\u671F\uFF0C\u518D\u53D1\u4E00\u6B21 /panel\u3002",
+    busy: "\u4E0A\u4E00\u6B65\u8FD8\u5728\u5904\u7406\uFF0C\u7A0D\u7B49\u4E00\u4E0B\u3002",
+    loadFailed: "\u521A\u624D\u6CA1\u8BFB\u51FA\u6765\uFF0C\u7A0D\u540E\u518D\u8BD5\u3002",
+    sessions: {
+      title: "\u9009\u4E00\u6761\u4F1A\u8BDD",
+      hint: "\u70B9\u4E00\u6761\u5207\u8FC7\u53BB\u3002"
+    },
+    teams: {
+      title: "\u9009\u4E00\u652F\u961F",
+      hint: "\u70B9\u4E00\u652F\u961F\uFF0C\u63A5\u4E0B\u6765\u7684\u6D3B\u6D3E\u7ED9\u5B83\u3002",
+      unavailable: "\u8BFB\u4E0D\u5230\u56E2\u961F\u5217\u8868\u3002"
+    },
+    models: {
+      title: "\u9009\u6A21\u578B"
+    }
   }
 };
 
@@ -132845,6 +133014,385 @@ var pickSession = (arg, listed, rows) => {
   return matches.length === 1 ? matches[0]?.threadId ?? null : null;
 };
 
+// src/panelCommands.ts
+var PANEL_CATEGORIES = ["session", "target", "system"];
+var PANEL_COMMANDS = [
+  {
+    id: "new",
+    category: "session",
+    line: "/new",
+    kind: "new",
+    labelKey: "panel.cmd.new",
+    action: { op: "run", arg: "new" }
+  },
+  {
+    id: "stop",
+    category: "session",
+    line: "/stop",
+    kind: "stop",
+    labelKey: "panel.cmd.stop",
+    action: { op: "run", arg: "stop" }
+  },
+  {
+    id: "sessions",
+    category: "session",
+    line: "/sessions",
+    kind: "sessions",
+    labelKey: "panel.cmd.sessions",
+    action: { op: "open", arg: "sessions" }
+  },
+  {
+    id: "team",
+    category: "target",
+    line: "/team",
+    kind: "showTargets",
+    labelKey: "panel.cmd.team",
+    action: { op: "open", arg: "teams" }
+  },
+  {
+    id: "thread",
+    category: "target",
+    line: "/thread",
+    kind: "selectThread",
+    labelKey: "panel.cmd.thread",
+    action: { op: "run", arg: "thread" }
+  },
+  {
+    id: "model",
+    category: "system",
+    line: "/model",
+    kind: "model",
+    labelKey: "panel.cmd.model",
+    action: { op: "open", arg: "models" }
+  },
+  {
+    id: "plan",
+    category: "system",
+    line: "/plan",
+    kind: "plan",
+    // 实际标签随当前状态在「开 / 关」间翻，见控制器；这里放关着时的那个。
+    labelKey: "panel.cmd.planOff",
+    action: { op: "run", arg: "plan" }
+  },
+  {
+    id: "status",
+    category: "system",
+    line: "/status",
+    kind: "status",
+    labelKey: "panel.cmd.status",
+    action: { op: "run", arg: "status" }
+  },
+  {
+    id: "help",
+    category: "system",
+    // 这个按钮发的是文字版命令列表，不是又开一张面板。
+    line: "/help",
+    kind: "help",
+    labelKey: "panel.cmd.help",
+    action: { op: "run", arg: "help" }
+  }
+];
+var PANEL_RUN_LINES = Object.fromEntries(
+  PANEL_COMMANDS.filter((spec) => spec.action.op === "run" && spec.id !== "help").map((spec) => [
+    spec.id,
+    spec.line
+  ])
+);
+
+// src/panelController.ts
+var PANEL_PAGE_SIZE = 8;
+var PANEL_CARD_LIMIT = 200;
+var LABEL_MAX_CHARS = 60;
+var PICK_KINDS = /* @__PURE__ */ new Set(["sessions", "teams", "models"]);
+var clip = (label) => {
+  const chars = Array.from(label);
+  return chars.length <= LABEL_MAX_CHARS ? label : `${chars.slice(0, LABEL_MAX_CHARS - 1).join("")}\u2026`;
+};
+var pageCount = (total) => Math.max(1, Math.ceil(total / PANEL_PAGE_SIZE));
+var makePanelController = (deps) => {
+  const { t } = deps;
+  const cards = /* @__PURE__ */ new Map();
+  const tails = /* @__PURE__ */ new Map();
+  const post = (cardId, job) => {
+    const run = (tails.get(cardId) ?? Promise.resolve()).then(job).catch((error) => deps.warn("panel could not update a card", error)).then(() => {
+      if (tails.get(cardId) === run) tails.delete(cardId);
+    });
+    tails.set(cardId, run);
+    return run;
+  };
+  const remember = (entry) => {
+    cards.delete(entry.cardId);
+    cards.set(entry.cardId, entry);
+    if (cards.size > PANEL_CARD_LIMIT) {
+      const oldest = cards.keys().next().value;
+      if (oldest !== void 0) cards.delete(oldest);
+    }
+  };
+  const button = (label, op, arg, danger) => ({
+    label: clip(label),
+    action: { op, arg },
+    ...danger === true ? { danger } : {}
+  });
+  const busyCard = (title, text2) => ({
+    title,
+    tone: "busy",
+    text: text2,
+    groups: [],
+    nav: []
+  });
+  const viewTitle = (kind) => t(`panel.${kind}.title`);
+  const menuCard = (chatKey) => ({
+    title: t("panel.title"),
+    tone: "menu",
+    text: t("panel.hint"),
+    groups: PANEL_CATEGORIES.map(
+      (category) => ({
+        heading: t(`panel.category.${category}`),
+        buttons: PANEL_COMMANDS.filter((spec) => spec.category === category).map(
+          (spec) => button(
+            // 计划模式的按钮把当前状态写在标签上，点了之后标签跟着翻。
+            spec.id === "plan" ? t(deps.planOn(chatKey) ? "panel.cmd.planOn" : "panel.cmd.planOff") : t(spec.labelKey),
+            spec.action.op,
+            spec.action.arg,
+            spec.id === "stop"
+          )
+        )
+      })
+    ),
+    nav: []
+  });
+  const pickerCard = (input) => {
+    const total = pageCount(input.items.length);
+    const page = Math.min(Math.max(input.page, 0), total - 1);
+    const shown = input.items.slice(page * PANEL_PAGE_SIZE, (page + 1) * PANEL_PAGE_SIZE);
+    const nav = [];
+    if (input.depth > 1) nav.push(button(t("panel.back"), "back"));
+    if (page > 0) nav.push(button(t("panel.prev"), "page", String(page - 1)));
+    if (page < total - 1) nav.push(button(t("panel.next"), "page", String(page + 1)));
+    const pageNote = total > 1 ? t("panel.page", { page: page + 1, total }) : "";
+    return {
+      title: viewTitle(input.kind),
+      tone: "menu",
+      text: [input.text, pageNote].filter((part) => part !== "").join("\n"),
+      groups: shown.map((item) => ({ heading: null, buttons: [item] })),
+      nav
+    };
+  };
+  const render = (entry) => {
+    const view = entry.stack.at(-1) ?? { kind: "menu" };
+    const depth = entry.stack.length;
+    switch (view.kind) {
+      case "menu":
+        return menuCard(entry.chatKey);
+      case "notice":
+        return {
+          title: view.title,
+          tone: "notice",
+          text: view.text,
+          groups: [],
+          nav: depth > 1 ? [button(t("panel.back"), "back")] : []
+        };
+      case "sessions": {
+        const now = deps.now();
+        return pickerCard({
+          kind: "sessions",
+          page: view.page,
+          depth,
+          text: view.rows.length === 0 ? t("sessions.empty") : t("panel.sessions.hint"),
+          items: view.rows.map(
+            (row, index) => button(sessionLine(row, index + 1, now, t), "pick", `sessions:${row.threadId}`)
+          )
+        });
+      }
+      case "teams":
+        return pickerCard({
+          kind: "teams",
+          page: view.page,
+          depth,
+          text: view.teams === null ? t("panel.teams.unavailable") : view.teams.length === 0 ? t("command.noTeams") : t("panel.teams.hint"),
+          items: (view.teams ?? []).map(
+            (team) => button(team.title, "pick", `teams:${team.teamId}`)
+          )
+        });
+      case "models": {
+        const { models } = view;
+        const current = models?.current ?? null;
+        const isCurrent = (choice) => current !== null && choice.instanceId === current.instanceId && choice.model === current.model;
+        return pickerCard({
+          kind: "models",
+          page: view.page,
+          depth,
+          text: models === null || models.choices.length === 0 ? t("model.unavailable") : current === null ? t("model.currentUnknown") : t("model.current", {
+            model: modelLabel(
+              models.choices.find(isCurrent) ?? {
+                instanceName: current.instanceId,
+                modelName: current.model
+              }
+            )
+          }),
+          items: (models?.choices ?? []).map(
+            (choice) => button(
+              `${isCurrent(choice) ? "\u2605 " : ""}${modelLabel(choice)}`,
+              "pick",
+              `models:${choice.instanceId}/${choice.model}`
+            )
+          )
+        });
+      }
+    }
+  };
+  const show = (entry) => post(entry.cardId, async () => {
+    const surface = deps.surface(entry.chatKey);
+    if (surface === null) return;
+    const card = render(entry);
+    try {
+      await surface.update(entry.cardId, card);
+    } catch (error) {
+      deps.warn("panel could not update a card, posting a new one", error);
+      const replacement = await surface.open(card);
+      if (replacement !== null) {
+        cards.delete(entry.cardId);
+        entry.cardId = replacement;
+        remember(entry);
+      }
+    }
+  });
+  const placeholder = (entry, title, text2) => {
+    void post(entry.cardId, async () => {
+      await deps.surface(entry.chatKey)?.update(entry.cardId, busyCard(title, text2));
+    });
+  };
+  const loadView = async (chatKey, kind) => {
+    switch (kind) {
+      case "sessions":
+        return { kind, page: 0, rows: await deps.loadSessions(chatKey) };
+      case "teams":
+        return { kind, page: 0, teams: await deps.loadTeams(chatKey) };
+      case "models":
+        return { kind, page: 0, models: await deps.loadModels(chatKey) };
+    }
+  };
+  const backToMenu = (entry) => {
+    entry.stack = [{ kind: "menu" }];
+    return show(entry);
+  };
+  const guardBusy = (entry, work) => {
+    entry.busy = true;
+    return work().finally(() => {
+      entry.busy = false;
+    });
+  };
+  const operate = (entry, job) => {
+    entry.busy = true;
+    deps.defer(() => {
+      placeholder(entry, t("panel.title"), t("panel.working"));
+      deps.enqueue(
+        entry.chatKey,
+        () => guardBusy(entry, async () => {
+          try {
+            await job();
+          } catch (error) {
+            deps.warn("panel could not run a command", error);
+          }
+          await backToMenu(entry);
+        })
+      );
+    });
+  };
+  const enter = (entry, kind) => {
+    entry.busy = true;
+    deps.defer(() => {
+      placeholder(entry, viewTitle(kind), t("panel.loading"));
+      deps.enqueue(
+        entry.chatKey,
+        () => guardBusy(entry, async () => {
+          try {
+            entry.stack.push(await loadView(entry.chatKey, kind));
+          } catch (error) {
+            deps.warn("panel could not load a view", error);
+            entry.stack.push({
+              kind: "notice",
+              title: viewTitle(kind),
+              text: t("panel.loadFailed")
+            });
+          }
+          await show(entry);
+        })
+      );
+    });
+  };
+  const navigate = (entry, change) => {
+    change();
+    deps.defer(() => void show(entry));
+  };
+  return {
+    /** 开一张新面板卡（`/help`）。发不出就抛，调用方退回文字版。 */
+    open: async (chatKey) => {
+      const surface = deps.surface(chatKey);
+      if (surface === null) throw new Error("this chat has no panel");
+      const entry = { cardId: "", chatKey, stack: [{ kind: "menu" }], busy: false };
+      const cardId = await surface.open(menuCard(chatKey));
+      if (cardId === null) throw new Error("the panel card was sent without an id");
+      entry.cardId = cardId;
+      remember(entry);
+    },
+    /**
+     * 处理一次点击，同步回给点击者的一句提示（null 就是没话说）。取数据、跑命令、改卡都
+     * 在回调应答之后做。
+     */
+    click: (click) => {
+      const entry = cards.get(click.cardId);
+      if (entry === void 0 || entry.chatKey !== click.chatKey) return t("panel.expired");
+      if (entry.busy) return t("panel.busy");
+      const top = entry.stack.at(-1) ?? { kind: "menu" };
+      const arg = click.arg ?? "";
+      switch (click.op) {
+        case "back":
+          if (entry.stack.length > 1) navigate(entry, () => void entry.stack.pop());
+          return null;
+        case "page": {
+          const page = Number(arg);
+          if ((top.kind === "sessions" || top.kind === "teams" || top.kind === "models") && Number.isInteger(page) && page >= 0) {
+            navigate(entry, () => {
+              entry.stack[entry.stack.length - 1] = { ...top, page };
+            });
+          }
+          return null;
+        }
+        case "open":
+          if (top.kind === "menu" && PICK_KINDS.has(arg)) enter(entry, arg);
+          return null;
+        case "run": {
+          if (top.kind !== "menu") return null;
+          if (arg === "help") {
+            operate(entry, () => deps.sendHelpText(entry.chatKey));
+            return null;
+          }
+          const line = PANEL_RUN_LINES[arg];
+          if (line !== void 0) operate(entry, () => deps.runLine(entry.chatKey, line));
+          return null;
+        }
+        case "pick": {
+          const split = arg.indexOf(":");
+          const key = split < 0 ? "" : arg.slice(split + 1);
+          const line = top.kind === "sessions" && arg.startsWith("sessions:") ? top.rows.find((row) => row.threadId === key) === void 0 ? null : `/resume ${key}` : top.kind === "teams" && arg.startsWith("teams:") ? top.teams?.find((team) => team.teamId === key) === void 0 ? null : `/team ${key}` : top.kind === "models" && arg.startsWith("models:") ? top.models?.choices.find(
+            (choice) => `${choice.instanceId}/${choice.model}` === key
+          ) === void 0 ? null : `/model ${key}` : null;
+          if (line === null) {
+            deps.warn("panel ignored a pick that is not in the current view");
+            return null;
+          }
+          operate(entry, () => deps.runLine(entry.chatKey, line));
+          return null;
+        }
+        default:
+          deps.warn(`panel ignored an unknown action: ${click.op}`);
+          return null;
+      }
+    }
+  };
+};
+
 // src/telegramApi.ts
 var API_BASE = "https://api.telegram.org";
 var POLL_TIMEOUT_SECONDS = 45;
@@ -134405,9 +134953,10 @@ ${final.text}`;
       commit("chat-updated", { chatKey, plan: next });
       await deliver(binding, t(next ? "plan.on" : "plan.off"));
     };
-    const handleCommand = async (binding, message, teams) => {
+    const hasPanel = (binding) => adapterFor(binding.platform)?.panel !== void 0;
+    const handleCommand = async (binding, text2, teams) => {
       const command = parseChatCommand({
-        text: message.text,
+        text: text2,
         teams,
         // 中文别名只在回话语言是中文时认，免得英文用户打一个「停」就被当成命令。
         chinese: t.language === "zh-CN"
@@ -134451,7 +135000,20 @@ ${final.text}`;
           await deliver(binding, t("command.noTeams"));
           return true;
         case "help":
-          await deliver(binding, helpText(t));
+          await deliver(binding, helpText(t, { panel: hasPanel(binding) }));
+          return true;
+        case "panel":
+          if (hasPanel(binding)) {
+            try {
+              await panel.open(chatKey);
+              return true;
+            } catch (error) {
+              ctx.log.warn("chat could not open the command panel", {
+                error: describeError(error)
+              });
+            }
+          }
+          await deliver(binding, helpText(t, { panel: false }));
           return true;
         case "sessions":
           await showSessions(binding);
@@ -134640,9 +135202,75 @@ ${final.text}`;
       });
       chatQueues.set(chatKey, run);
     };
+    const panel = makePanelController({
+      t,
+      surface: (chatKey) => {
+        const binding = bindingOfChat(chatKey);
+        const surface = binding === void 0 ? void 0 : adapterFor(binding.platform)?.panel;
+        if (binding === void 0 || surface === void 0) return null;
+        return {
+          open: (card) => surface.open(binding, card),
+          update: (cardId, card) => surface.update(binding, cardId, card)
+        };
+      },
+      planOn: (chatKey) => chatOf(state, chatKey).plan,
+      loadSessions: async (chatKey) => {
+        const binding = bindingOfChat(chatKey);
+        if (binding === void 0) return [];
+        const rows = await sessionRowsFor(binding);
+        listedByChat.set(chatKey, listedThreadIds(rows));
+        return rows;
+      },
+      loadTeams: async (chatKey) => {
+        const binding = bindingOfChat(chatKey);
+        return binding === void 0 ? null : fetchTeams(binding);
+      },
+      loadModels: async (chatKey) => {
+        const binding = bindingOfChat(chatKey);
+        const instances = await ctx.providers.listInstances().catch(() => null);
+        if (binding === void 0 || instances === null) return null;
+        return { current: await currentModelOf(binding), choices: modelChoices(instances) };
+      },
+      runLine: async (chatKey, line) => {
+        const binding = bindingOfChat(chatKey);
+        if (binding === void 0) return;
+        await handleCommand(binding, line, await fetchTeams(binding) ?? []);
+      },
+      sendHelpText: async (chatKey) => {
+        const binding = bindingOfChat(chatKey);
+        if (binding !== void 0) await deliver(binding, helpText(t));
+      },
+      enqueue: enqueueForChat,
+      // 改卡必须排在回调应答之后：飞书在应答不带改卡时会把卡恢复成点击前的样子。
+      defer: (run) => {
+        setTimeout(run, 0);
+      },
+      now: () => Date.now(),
+      warn: (message, error) => {
+        ctx.log.warn(`chat ${message}`, error === void 0 ? {} : { error: describeError(error) });
+      }
+    });
+    const handlePanelClick = (platform, click) => {
+      const target = bindingForChat(platform, click.chatId);
+      if (target === void 0 || target.projectId === "") return null;
+      if (!isAllowedSender(target, click.operatorId)) {
+        ctx.log.warn("chat ignored a panel click from someone not on the allow list", {
+          group: target.displayName,
+          operator: click.operatorId
+        });
+        return t("reply.notAllowed");
+      }
+      return panel.click({
+        chatKey: chatKeyOf(target),
+        cardId: click.cardId,
+        op: click.op,
+        arg: click.arg
+      });
+    };
     const inboundHandlersFor = (platform) => ({
       onError: (message) => ctx.log.warn("chat inbound connection failed", { platform, message }),
       onApproval: handleApprovalClick,
+      onPanelClick: (click) => handlePanelClick(platform, click),
       onMessage: (message) => {
         const target = bindingForChat(platform, message.chatId);
         if (target === void 0 || target.projectId === "") return;
@@ -134668,7 +135296,7 @@ ${final.text}`;
         }
         enqueueForChat(chatKeyOf(target), async () => {
           const teams = await fetchTeams(target);
-          if (await handleCommand(target, message, teams ?? [])) return;
+          if (await handleCommand(target, message.text, teams ?? [])) return;
           const project = await ctx.projections.getProject(target.projectId);
           if (project === null || project.archivedAt != null) {
             if (project === null) {

package/locales/en.json

@@ -128,7 +128,8 @@
     "sessions": "· /sessions — list the sessions this bot opened for this group's project",
     "resume": "· /resume number — switch to one of them (a number from /sessions, or the start of its id)",
     "model": "· /model — see the model this group uses; /model number or /model instance/model switches it",
-    "plan": "· /plan — toggle plan mode (the agent proposes a plan instead of acting); /plan on, /plan off set it"
+    "plan": "· /plan — toggle plan mode (the agent proposes a plan instead of acting); /plan on, /plan off set it",
+    "panel": "Send /panel to open the command panel with a button for every command."
   },
   "sessions": {
     "title": "Sessions this bot opened for this group's project ({{count}}):",
@@ -201,5 +202,47 @@
       "chosen": "Chosen: {{label}}",
       "elsewhere": "Already handled elsewhere (the web app or another client)."
     }
+  },
+  "panel": {
+    "title": "Command panel",
+    "hint": "A button does the same as typing its command. You can still type.",
+    "category": {
+      "session": "Session",
+      "target": "Send to",
+      "system": "Settings and status"
+    },
+    "cmd": {
+      "new": "New session",
+      "stop": "Stop this turn",
+      "sessions": "Sessions",
+      "team": "Send to a team",
+      "thread": "Normal session",
+      "model": "Model",
+      "planOn": "Plan mode: on",
+      "planOff": "Plan mode: off",
+      "status": "Status",
+      "help": "Text help"
+    },
+    "back": "Back",
+    "prev": "Previous",
+    "next": "Next",
+    "page": "Page {{page}} of {{total}}",
+    "loading": "Loading…",
+    "working": "Working on it…",
+    "expired": "This panel has expired. Send /panel again.",
+    "busy": "The last tap is still being handled. Give it a moment.",
+    "loadFailed": "Could not read that just now. Try again in a moment.",
+    "sessions": {
+      "title": "Pick a session",
+      "hint": "Tap one to switch to it."
+    },
+    "teams": {
+      "title": "Pick a team",
+      "hint": "Tap a team and the next messages go to it.",
+      "unavailable": "Could not read the team list."
+    },
+    "models": {
+      "title": "Pick a model"
+    }
   }
 }

package/locales/zh-CN.json

@@ -128,7 +128,8 @@
     "sessions": "· /sessions —— 列出本机器人为这个群的项目开过的会话",
     "resume": "· /resume 编号 —— 切到其中一条（/sessions 里的编号，或会话 id 的开头）",
     "model": "· /model —— 看这个群用的模型；/model 编号 或 /model 实例/模型 切换",
-    "plan": "· /plan —— 开关计划模式（agent 先出计划、不动手）；/plan on、/plan off 明确设定"
+    "plan": "· /plan —— 开关计划模式（agent 先出计划、不动手）；/plan on、/plan off 明确设定",
+    "panel": "发 /panel 打开可点的命令面板。"
   },
   "sessions": {
     "title": "本机器人为这个群的项目开过的会话（{{count}} 条）：",
@@ -201,5 +202,47 @@
       "chosen": "已选：{{label}}",
       "elsewhere": "已在别处处理（网页或其他客户端）。"
     }
+  },
+  "panel": {
+    "title": "命令面板",
+    "hint": "点按钮等于打出对应的命令，也可以直接打字。",
+    "category": {
+      "session": "会话",
+      "target": "派给谁",
+      "system": "设置与状态"
+    },
+    "cmd": {
+      "new": "新会话",
+      "stop": "停止本轮",
+      "sessions": "会话列表",
+      "team": "派给团队",
+      "thread": "普通会话",
+      "model": "模型",
+      "planOn": "计划模式：开",
+      "planOff": "计划模式：关",
+      "status": "状态",
+      "help": "文字说明"
+    },
+    "back": "返回",
+    "prev": "上一页",
+    "next": "下一页",
+    "page": "第 {{page}} / {{total}} 页",
+    "loading": "加载中…",
+    "working": "处理中…",
+    "expired": "面板已过期，再发一次 /panel。",
+    "busy": "上一步还在处理，稍等一下。",
+    "loadFailed": "刚才没读出来，稍后再试。",
+    "sessions": {
+      "title": "选一条会话",
+      "hint": "点一条切过去。"
+    },
+    "teams": {
+      "title": "选一支队",
+      "hint": "点一支队，接下来的活派给它。",
+      "unavailable": "读不到团队列表。"
+    },
+    "models": {
+      "title": "选模型"
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/plugin-im",
-  "version": "0.2.2566",
+  "version": "0.2.2570",
   "description": "Talk to your agents from Telegram, WeCom or Lark.",
   "keywords": [
     "im",
@@ -27,7 +27,7 @@
     "esbuild": "0.28.1",
     "markdown-it": "^15.0.2",
     "vite-plus": "0.2.2",
-    "@ycodium-ai/plugin-api": "0.2.2566"
+    "@ycodium-ai/plugin-api": "0.2.2570"
   },
   "ycodium": {
     "plugin": "./dist/index.js",