opencode-feishu-plugin 0.2.10 → 0.2.11

package/README.en.md

@@ -22,22 +22,29 @@ Connect [OpenCode](https://opencode.ai) to Feishu/Lark: **one Feishu topic = one
 | 📊 **Real-time visible** | "Thinking" receipt → live tool-call cards → streaming text updates; footer shows the current model |
 | ⏹ **Controllable** | Every reply card has a "force stop" button; a watchdog auto-interrupts stuck sessions; native queue with `/steer` `/now` to cut in |
 | 📎 **Images / files** | Images and files sent in Feishu are downloaded and attached to the session, so vision/file-capable models can see and read them |
+| 🖱 **Main-window menu** | Two fixed quick buttons above the chat input — "New session" and "Session list" (bot custom menu) — one tap to fire them |
 | 🚫 **No ports** | Full long-connection; no inbound port needed on the server |
 
 ## 1. Feishu app setup (~3 minutes)
 
 1. Open the [Feishu Open Platform](https://open.feishu.cn/app) → **Create an enterprise self-built app**.
 2. **Add app capability → Bot**.
-3. **Permission management** — enable these two minimal scopes:
+3. **Permission management → API permissions**: enable these two **required** scopes first:
    - `im:message.p2p_msg:readonly` — read messages users send to the bot in p2p chat
    - `im:message:send_as_bot` — send messages as the app (also used to update cards)
 
-   To **receive images / files** (downloaded and attached to sessions), add one more:
-   - `im:message:readonly` — fetch message resources (required to download images / files)
+   **To receive images / files, add one more** (skip if you don't need it):
+   - `im:message:readonly` — fetch message resources (**required** to download images / files)
+
+   > ⚠️ Without `im:message:readonly`: images/files are **not downloaded** — the message still reaches the AI, but with placeholder text ("…download failed…"). After enabling it, **re-create and publish an app version** for it to take effect.
 4. **Events & Callbacks → Event configuration**: subscription method **"Use long connection to receive events"** (do **not** pick Webhook), add event `im.message.receive_v1`.
 5. **Events & Callbacks → Callback configuration**: same long-connection method, add callback `card.action.trigger` (zero permission requirement).
-6. **Version management & release**: availability = **only yourself**, create a version and **publish**. ⚠️ Without publishing the app stays in "development" state and the long connection cannot connect — the bot will never respond.
-7. Note down the **App ID** (`cli_…`) and **App Secret**.
+6. **Bot menu (optional, recommended)**: **App capabilities → Bot → Bot custom menu** — enable the menu, pick the **floating menu** style, and add two items (any name/icon, **action = push event**):
+   - "➕ New session" → `event_key` = `new`
+   - "📋 Session list" → `event_key` = `sessions`
+   Then add the event `application.bot.menu_v6` under **Event configuration** (zero permission requirement). Result: two quick buttons above the chat input that act like sending `/new` / `/sessions`.
+7. **Version management & release**: availability = **only yourself**, create a version and **publish**. ⚠️ Without publishing the app stays in "development" state and the long connection cannot connect — the bot will never respond.
+8. Note down the **App ID** (`cli_…`) and **App Secret**.
 
 > **Why no group permission?** This plugin is a "single-user remote control". Without group permission the bot **physically cannot receive group messages** — the single-user boundary is guaranteed by the platform scope layer, not only by code.
 
@@ -104,6 +111,22 @@ The main chat **only manages**; plain text never enters any session.
 
 ![Create-session form card: directory, model, permission](image/new.png)  ![Session list card: paginate, enter/reopen, create](image/sessions.png)
 
+### Bot menu (quick buttons above the input box)
+
+![Configure the bot custom menu in the developer console (floating menu): the phone preview shows "new" / "sessions" pinned above the input box; the right panel is the item config (action = push event)](image/btns.png)
+
+After configuring the menu (setup step 6), two quick buttons stay pinned **above the chat input** in the bot window:
+
+| Button | Equivalent command | Effect |
+|---|---|---|
+| `new` | `/new` | Opens the create-session form card |
+| `sessions` | `/sessions` | Opens the session list card |
+
+- Menu `event_key`s must be **`new` / `sessions`** (the literal `/new`, `/sessions` also accepted);
+- Clicks arrive over the long connection (`application.bot.menu_v6`, zero permission requirement); the plugin synthesizes an **equivalent command message** — allowlist, dedup and command matrix behave exactly like typed commands; unknown keys are ignored silently;
+- After changing the menu, **re-publish the app version** (per the console: takes effect within ~5 minutes after publishing);
+- Message the bot at least once before using the menu (the plugin remembers the p2p chat from messages; any normal usage satisfies this).
+
 ### Inside a topic (work)
 
 A topic = a session; sending plain text is giving the AI a command.
@@ -160,6 +183,7 @@ Full config (including `cardMaxTables`, `topicStatus*`, `resumeSummary*`, `keepa
 | Symptom | Fix |
 |---|---|
 | No response to messages | ① Is the app **published** and does availability include you? ② Is the subscription **long connection** (not Webhook)? ③ Is `im:message.p2p_msg:readonly` enabled? |
+| Images / files not received (placeholder / "download failed") | Enable `im:message:readonly` (Permission management → API permissions, search "fetch message resources") → **re-create and publish an app version**; check the `feishu.log` "附件下载失败" entry for the exact reason |
 | `feishu.json` changes don't apply | Check the path, then `opencode reload` |
 | Plugin not loaded at all | npm: confirm the package name is in the `plugins` array; directory: confirm `plugins/<name>/index.js` exists |
 | No approval cards | That session wasn't started from Feishu (no mapping); by design the plugin doesn't take it over |

package/README.md

@@ -22,22 +22,29 @@
 | 📊 **实时可见** | 「思考中」回执 → 工具调用实时上卡 → 文本流式更新，页脚显示当前模型 |
 | ⏹ **可控可停** | 每张回复卡带「强制停止」；看门狗自动中断卡死会话；忙时原生排队，`/steer` `/now` 可插队 |
 | 📎 **图片 / 文件** | 飞书里的图片 / 文件自动下载并挂进会话，支持视觉 / 文件的模型直接看图、读文件 |
+| 🖱 **主窗口菜单** | 机器人输入框上固定「新建会话」「会话列表」快捷按钮（机器人自定义菜单），一点即用 |
 | 🚫 **无端口** | 全程长连接，服务器无需开放任何入站端口 |
 
 ## 一、飞书后台配置（约 3 分钟）
 
 1. 打开 [飞书开放平台](https://open.feishu.cn/app) → **创建企业自建应用**。
 2. **添加应用能力 → 机器人**。
-3. **权限管理**，开通这两个最小 scope：
+3. **权限管理 → API 权限**：先开这两个**必开** scope：
    - `im:message.p2p_msg:readonly` —— 读取用户发给机器人的单聊消息
    - `im:message:send_as_bot` —— 以应用身份发消息（也用于更新卡片）
 
-   如需**接收图片 / 文件**（下载后挂进会话），再加开一个：
-   - `im:message:readonly` —— 获取消息中的资源文件（图片 / 文件下载的必要条件）
+   **接收图片 / 文件需要再加开一个**（不需要该功能可跳过）：
+   - `im:message:readonly` —— 获取消息中的资源文件（图片 / 文件下载的**必要条件**）
+
+   > ⚠️ 未开通 `im:message:readonly` 时：图片/文件**不会被下载**，消息照常送达 AI，但只带占位文本（"…下载失败：…"）。开通后要**重新创建版本并发布**才生效。
 4. **事件与回调 → 事件配置**：订阅方式选**「使用长连接接收事件」**（不要选 Webhook），添加事件 `im.message.receive_v1`。
 5. **事件与回调 → 回调配置**：订阅方式同样选**长连接**，添加回调 `card.action.trigger`（零权限要求）。
-6. **版本管理与发布**：可用范围 = **仅本人**，创建版本并**发布**。⚠️ 不发布就是开发态，长连接连不上，机器人不会有任何反应。
-7. 记下 **App ID**（`cli_…`）与 **App Secret**。
+6. **机器人菜单（可选，推荐）**：**应用能力 → 机器人 → 机器人自定义菜单** 开启菜单，展示形式选**悬浮菜单**，添加两个菜单项（名称/图标随意，**响应动作=推送事件**）：
+   - 「➕ 新建会话」→ 事件 Key = `new`
+   - 「📋 会话列表」→ 事件 Key = `sessions`
+   再到 **事件配置** 添加事件 `application.bot.menu_v6`（零权限要求）。效果：机器人输入框上多两个快捷按钮，点一下等于发 `/new` / `/sessions`。
+7. **版本管理与发布**：可用范围 = **仅本人**，创建版本并**发布**。⚠️ 不发布就是开发态，长连接连不上，机器人不会有任何反应。
+8. 记下 **App ID**（`cli_…`）与 **App Secret**。
 
 > **为什么不申请群权限？** 本插件是"一个人的遥控台"。不申请群权限，机器人**物理上收不到群消息**，单人边界由平台 scope 层保证，而不是只靠代码判断。
 
@@ -104,6 +111,22 @@ tail -f ~/.config/opencode/plugins/feishu.log   # 应看到「飞书长连接已
 
 ![建会话表单卡：目录、模型、权限一次填完](image/new.png)  ![会话列表卡片：翻页、进入/再开、新建](image/sessions.png)
 
+### 机器人菜单（输入框快捷按钮）
+
+![开发者后台配置机器人自定义菜单（悬浮菜单）：手机端预览里输入框上方固定 new / sessions 两个按钮，右侧为菜单项配置（响应动作=推送事件）](image/btns.png)
+
+按「一、飞书后台配置」第 6 步配好菜单后，机器人聊天窗口的**输入框上方**会常驻两个快捷按钮：
+
+| 按钮 | 等价命令 | 效果 |
+|---|---|---|
+| `new` | `/new` | 弹出建会话表单卡 |
+| `sessions` | `/sessions` | 弹出会话列表卡 |
+
+- 菜单项的事件 Key 需配置为 **`new` / `sessions`**（也兼容直接把 `/new`、`/sessions` 填成 Key）；
+- 点击事件走长连接（`application.bot.menu_v6`，零权限要求），插件把它合成一条**等价命令消息**处理——白名单、去重、命令矩阵与手输完全一致；未知 Key 静默忽略；
+- 菜单配置修改后需**重新发布版本**（官方说明：发版成功后约 5 分钟内生效）；
+- 首次使用菜单前，先给机器人发过至少一条消息（插件据消息记住单聊会话；正常使用必然满足）。
+
 ### 话题内（干活）
 
 一个话题 = 一个会话，发普通文本就是给 AI 下指令。
@@ -160,6 +183,7 @@ agent 反问时表单会变成飞书卡片，**点按钮或在话题里直接发
 | 现象 | 处理 |
 |---|---|
 | 发消息没反应 | ① 应用是否**已发布**、可用范围是否勾了你；② 订阅是否选了**长连接**（不是 Webhook）；③ 是否开通 `im:message.p2p_msg:readonly` |
+| 图片 / 文件收不到（只显示占位 / “下载失败”） | 开通 `im:message:readonly`（权限管理 → API 权限，搜“获取消息中的资源文件”）→ **重新创建版本并发布**；具体失败原因看 `feishu.log` 的「附件下载失败」 |
 | 改了 `feishu.json` 不生效 | 确认路径，然后 `opencode reload` |
 | 插件完全没被加载 | npm 方式确认包名在 `plugins` 数组；目录方式确认 `plugins/<名>/index.js` 存在 |
 | 审批卡收不到 | 该会话不是从飞书发起的（无映射），插件按设计不接管 |

package/dist/index.js

@@ -144767,6 +144767,17 @@ function parseIncomingMessage(data) {
     ...str(message.parent_id) ? { parentId: str(message.parent_id) } : {}
   };
 }
+function parseBotMenuEvent(data) {
+  if (!isRecord2(data)) return void 0;
+  const header = isRecord2(data.header) ? data.header : {};
+  const event = isRecord2(data.event) ? data.event : data;
+  const operator = isRecord2(event.operator) ? event.operator : {};
+  const operatorId = isRecord2(operator.operator_id) ? operator.operator_id : {};
+  const operatorOpenId = str(operatorId.open_id);
+  const eventKey = str(event.event_key);
+  if (!operatorOpenId || !eventKey) return void 0;
+  return { eventId: str(header.event_id) || str(data.event_id), eventKey, operatorOpenId };
+}
 function parseCardAction(data) {
   if (!isRecord2(data)) return void 0;
   const context3 = isRecord2(data.context) ? data.context : {};
@@ -144826,7 +144837,17 @@ function describeCardActionEvent(data) {
 // src/feishu/gateway.ts
 function startGateway(options2) {
   const { log: log2 } = options2;
-  const dispatcher = new EventDispatcher({}).register({
+  const larkLogger = (tag2) => ({
+    error: (...msg) => log2.error(tag2, { msg: safeArgs(msg) }),
+    warn: (...msg) => log2.warn(tag2, { msg: safeArgs(msg) }),
+    info: (...msg) => log2.debug(tag2, { msg: safeArgs(msg) }),
+    debug: (...msg) => log2.debug(tag2, { msg: safeArgs(msg) }),
+    trace: (...msg) => log2.debug(tag2, { msg: safeArgs(msg) })
+  });
+  const dispatcher = new EventDispatcher({
+    loggerLevel: options2.logLevel === "debug" ? LoggerLevel.debug : LoggerLevel.info,
+    logger: larkLogger("lark.dispatcher")
+  }).register({
     "im.message.receive_v1": (data) => {
       try {
         const message = parseIncomingMessage(data);
@@ -144858,6 +144879,27 @@ function startGateway(options2) {
         log2.error("\u5361\u7247\u56DE\u8C03\u5904\u7406\u5F02\u5E38", { error: errorMessage(err2) });
         return { toast: { type: "error", content: "\u5904\u7406\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5" } };
       }
+    },
+    "application.bot.menu_v6": (data) => {
+      try {
+        const click = parseBotMenuEvent(data);
+        if (!click) {
+          log2.debug("\u83DC\u5355\u4E8B\u4EF6\u89E3\u6790\u5931\u8D25", {
+            shape: typeof data === "object" && data !== null ? Object.keys(data).slice(0, 20) : typeof data
+          });
+          return;
+        }
+        log2.debug("\u6536\u5230\u673A\u5668\u4EBA\u83DC\u5355\u70B9\u51FB", {
+          eventKey: click.eventKey,
+          operator: maskId(click.operatorOpenId)
+        });
+        if (!options2.onBotMenu) return;
+        void Promise.resolve(options2.onBotMenu(click)).catch((err2) => {
+          log2.error("\u83DC\u5355\u70B9\u51FB\u5904\u7406\u5931\u8D25", { eventKey: click.eventKey, error: errorMessage(err2) });
+        });
+      } catch (err2) {
+        log2.error("\u83DC\u5355 handler \u5F02\u5E38", { error: errorMessage(err2) });
+      }
     }
   });
   const loggerLevel = options2.logLevel === "debug" ? LoggerLevel.debug : LoggerLevel.warn;
@@ -144866,13 +144908,7 @@ function startGateway(options2) {
     appSecret: options2.appSecret,
     domain: options2.domain === "lark" ? Domain.Lark : Domain.Feishu,
     loggerLevel,
-    logger: {
-      error: (...msg) => log2.error("lark.ws", { msg: safeArgs(msg) }),
-      warn: (...msg) => log2.warn("lark.ws", { msg: safeArgs(msg) }),
-      info: (...msg) => log2.debug("lark.ws", { msg: safeArgs(msg) }),
-      debug: (...msg) => log2.debug("lark.ws", { msg: safeArgs(msg) }),
-      trace: (...msg) => log2.debug("lark.ws", { msg: safeArgs(msg) })
-    }
+    logger: larkLogger("lark.ws")
   });
   void wsClient.start({ eventDispatcher: dispatcher }).catch((err2) => {
     log2.error("\u98DE\u4E66\u957F\u8FDE\u63A5\u542F\u52A8\u5931\u8D25", { error: errorMessage(err2) });
@@ -151893,6 +151929,7 @@ async function start(ctx, config, log2, logSink) {
       log2.debug("\u5FFD\u7565\u975E\u767D\u540D\u5355\u7528\u6237", { sender: maskId(message.senderOpenId) });
       return;
     }
+    void rememberMenuChat(message.senderOpenId, message.chatId);
     if (!message.text) return;
     if (!await dedup.claim(message.messageId)) {
       log2.debug("\u5FFD\u7565\u91CD\u590D\u6D88\u606F", { messageId: message.messageId });
@@ -151955,6 +151992,66 @@ async function start(ctx, config, log2, logSink) {
     log2.info("\u8BDD\u9898\u65B0\u5EFA opencode \u4F1A\u8BDD", { sessionID: created.id, threadId: message.threadId, chatId: message.chatId });
     await runInSession(message, created.id, message.messageId);
   }
+  const MENU_COMMANDS = {
+    new: { cmd: "/new", label: "\u65B0\u5EFA\u4F1A\u8BDD" },
+    sessions: { cmd: "/sessions", label: "\u4F1A\u8BDD\u5217\u8868" },
+    // 容忍把命令原文直接当 event_key 配置。
+    "/new": { cmd: "/new", label: "\u65B0\u5EFA\u4F1A\u8BDD" },
+    "/sessions": { cmd: "/sessions", label: "\u4F1A\u8BDD\u5217\u8868" }
+  };
+  const menuChatCache = /* @__PURE__ */ new Map();
+  const menuChatKey = (openId) => `feishu:v2:menu-chat:${openId}`;
+  async function rememberMenuChat(openId, chatId) {
+    if (!openId || !chatId || menuChatCache.get(openId) === chatId) return;
+    menuChatCache.set(openId, chatId);
+    try {
+      await ctx.storage.set(menuChatKey(openId), chatId);
+    } catch (err2) {
+      log2.debug("\u83DC\u5355 chatId \u6301\u4E45\u5316\u5931\u8D25", { error: errorMessage(err2) });
+    }
+  }
+  async function resolveMenuChat(openId) {
+    const cached3 = menuChatCache.get(openId);
+    if (cached3) return cached3;
+    try {
+      const stored = await ctx.storage.get(menuChatKey(openId));
+      if (typeof stored === "string" && stored) {
+        menuChatCache.set(openId, stored);
+        return stored;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  async function handleBotMenu(click) {
+    if (!await owner.admit(click.operatorOpenId)) {
+      log2.debug("\u5FFD\u7565\u975E\u767D\u540D\u5355\u7528\u6237\u7684\u83DC\u5355\u70B9\u51FB", { operator: maskId(click.operatorOpenId) });
+      return;
+    }
+    const entry = MENU_COMMANDS[click.eventKey.trim()];
+    if (!entry) {
+      log2.debug("\u672A\u77E5\u83DC\u5355 event_key\uFF0C\u5FFD\u7565", { eventKey: click.eventKey });
+      return;
+    }
+    const chatId = await resolveMenuChat(click.operatorOpenId);
+    if (!chatId) {
+      log2.warn("\u83DC\u5355\u70B9\u51FB\u7F3A\u5C11\u5355\u804A\u4E0A\u4E0B\u6587\uFF1A\u8BF7\u5148\u7ED9\u673A\u5668\u4EBA\u53D1\u4E00\u6761\u6D88\u606F\u540E\u518D\u4F7F\u7528\u83DC\u5355", {
+        eventKey: click.eventKey
+      });
+      return;
+    }
+    const synthetic = {
+      eventId: click.eventId,
+      messageId: `menu_${click.eventId || Date.now()}`,
+      chatId,
+      chatType: "p2p",
+      messageType: "text",
+      text: entry.cmd,
+      senderOpenId: click.operatorOpenId
+    };
+    log2.info("\u673A\u5668\u4EBA\u83DC\u5355\u70B9\u51FB \u2192 \u6267\u884C\u547D\u4EE4", { eventKey: click.eventKey, cmd: entry.cmd, label: entry.label });
+    await handleMessage(synthetic);
+  }
   async function runInActiveSession(message) {
     let active = await sessionMap.getActive(message.chatId);
     if (!active) {
@@ -152023,6 +152120,7 @@ ${downloadedAttachmentPrompt(message.attachment, outcome)}`;
     log: log2,
     logLevel: config.logLevel,
     onMessage: (message) => handleMessage(message),
+    onBotMenu: (click) => handleBotMenu(click),
     onCardAction: (action) => routeCardAction(action, {
       log: log2,
       handleForm: (a) => formRelay.handleCardAction(a),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-feishu-plugin",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Feishu/Lark plugin for OpenCode V2 — single-user topics as sessions, in-card permission approvals, streaming cards. Minimal permissions, no public endpoint.",
   "type": "module",
   "main": "index.js",