opencode-feishu-plugin 0.2.8 → 0.2.9

package/README.en.md

@@ -21,15 +21,19 @@ Connect [OpenCode](https://opencode.ai) to Feishu/Lark: **one Feishu topic = one
 | ✅ **Card approvals** | Permission requests become cards: allow once / always / this session only / deny — signed tokens prevent forgery and replay |
 | 📊 **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 |
 | 🚫 **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 only these two scopes:
+3. **Permission management** — enable these two minimal scopes:
    - `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)
 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.
@@ -167,7 +171,7 @@ Full config (including `cardMaxTables`, `topicStatus*`, `resumeSummary*`, `keepa
 
 ## 6. Known limitations
 
-- Only **p2p text** (incl. rich text); images / files / audio-video get a text placeholder and aren't downloaded.
+- Image / file messages are **downloaded and attached to the session** (requires `im:message:readonly`); audio / video / stickers still get a text placeholder.
 - Only takes over approvals for **Feishu-originated sessions**; local TUI sessions are unaffected.
 - One main path to create a session: the `/new` / `/form` form card.
 - Forms are JSON 2.0; old clients need ≥ V3.7.0 for `select_static`.
@@ -178,7 +182,7 @@ Full config (including `cardMaxTables`, `topicStatus*`, `resumeSummary*`, `keepa
 
 Iterating from real usage feedback; current plan:
 
-- [ ] **Accept images / files**: currently only p2p text is handled — images / files get a text placeholder. Planned: download images / files and **attach them to the session** so vision / file-capable models can see the images and read the file contents.
+- [x] **Accept images / files**: done — downloaded automatically into `<configDir>/plugins/feishu-files/` and attached to the session (requires `im:message:readonly`; default max 20MB per attachment).
 - [ ] **New messages cut in by default when busy**: currently new messages queue natively while a session is busy (manual cut-in via `/steer`, `/now`). Planned: new messages default to **cutting in immediately**, interrupting the current step to run first.
 
 ## Advanced topics & development

package/README.md

@@ -21,15 +21,19 @@
 | ✅ **卡片审批** | 权限请求变飞书卡片：允许一次 / 始终允许 / 本会话内允许 / 拒绝，自签 token 防伪防重放 |
 | 📊 **实时可见** | 「思考中」回执 → 工具调用实时上卡 → 文本流式更新，页脚显示当前模型 |
 | ⏹ **可控可停** | 每张回复卡带「强制停止」；看门狗自动中断卡死会话；忙时原生排队，`/steer` `/now` 可插队 |
+| 📎 **图片 / 文件** | 飞书里的图片 / 文件自动下载并挂进会话，支持视觉 / 文件的模型直接看图、读文件 |
 | 🚫 **无端口** | 全程长连接，服务器无需开放任何入站端口 |
 
 ## 一、飞书后台配置（约 3 分钟）
 
 1. 打开 [飞书开放平台](https://open.feishu.cn/app) → **创建企业自建应用**。
 2. **添加应用能力 → 机器人**。
-3. **权限管理**，只开通这两个 scope：
+3. **权限管理**，开通这两个最小 scope：
    - `im:message.p2p_msg:readonly` —— 读取用户发给机器人的单聊消息
    - `im:message:send_as_bot` —— 以应用身份发消息（也用于更新卡片）
+
+   如需**接收图片 / 文件**（下载后挂进会话），再加开一个：
+   - `im:message:readonly` —— 获取消息中的资源文件（图片 / 文件下载的必要条件）
 4. **事件与回调 → 事件配置**：订阅方式选**「使用长连接接收事件」**（不要选 Webhook），添加事件 `im.message.receive_v1`。
 5. **事件与回调 → 回调配置**：订阅方式同样选**长连接**，添加回调 `card.action.trigger`（零权限要求）。
 6. **版本管理与发布**：可用范围 = **仅本人**，创建版本并**发布**。⚠️ 不发布就是开发态，长连接连不上，机器人不会有任何反应。
@@ -167,7 +171,7 @@ agent 反问时表单会变成飞书卡片，**点按钮或在话题里直接发
 
 ## 六、已知限制
 
-- 只处理**单聊文本**（含富文本）；图片 / 文件 / 音视频只给文字占位，不下载。
+- 图片 / 文件消息会**下载到本地并挂进会话**（需开 `im:message:readonly`）；音频 / 视频 / 表情包仍只给文字占位。
 - 只接管**从飞书发起的会话**的审批；本地 TUI 会话不受影响。
 - 建会话只有一条主路径：`/new` 与 `/form` 等价的表单卡。
 - 表单为 JSON 2.0，老客户端对 `select_static` 有最低版本要求（≥ V3.7.0）。
@@ -178,7 +182,7 @@ agent 反问时表单会变成飞书卡片，**点按钮或在话题里直接发
 
 按真实使用反馈迭代，当前规划：
 
-- [ ] **接收图片 / 文件**：目前只处理单聊文本，图片 / 文件仅显示文字占位。规划：下载图片 / 文件并作为**附件挂进会话**，让支持视觉 / 文件的模型直接看图、读文件内容。
+- [x] **接收图片 / 文件**：已支持——自动下载到 `<configDir>/plugins/feishu-files/` 并作为附件挂进会话（需开 `im:message:readonly`；单附件默认 ≤20MB）。
 - [ ] **忙时新消息默认插队**：目前会话忙时新消息默认排队（可用 `/steer`、`/now` 手动插队）。规划：忙时你发的新消息**默认直接插队**，立即打断当前步骤优先执行。
 
 ## 高级主题与开发

package/dist/index.js

@@ -1,17 +1,17 @@
 import crypto3, { randomBytes, createHash, createHmac, timingSafeEqual } from 'crypto';
-import url from 'url';
+import url, { pathToFileURL } from 'url';
 import http from 'http';
 import https from 'https';
 import http2 from 'http2';
 import util from 'util';
-import path, { dirname, isAbsolute, sep, resolve as resolve$1, join, basename } from 'path';
+import path, { dirname, isAbsolute, join, sep, resolve as resolve$1, basename } from 'path';
 import zlib from 'zlib';
 import stream3, { Readable } from 'stream';
 import { EventEmitter } from 'events';
 import fs, { mkdirSync, createWriteStream, readFileSync, realpathSync, statSync } from 'fs';
 import qs from 'querystring';
 import { homedir } from 'os';
-import { readFile, readdir } from 'fs/promises';
+import { mkdir, stat, rm, readFile, readdir } from 'fs/promises';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -8845,7 +8845,7 @@ var require_mime_db = __commonJS({
 var require_mime_types = __commonJS({
   "node_modules/form-data/node_modules/mime-types/index.js"(exports) {
     var db = require_mime_db();
-    var extname = __require("path").extname;
+    var extname2 = __require("path").extname;
     var EXTRACT_TYPE_REGEXP = /^\s*([^;\s]*)(?:;|\s|$)/;
     var TEXT_TYPE_REGEXP = /^text\//i;
     exports.charset = charset;
@@ -8899,7 +8899,7 @@ var require_mime_types = __commonJS({
       if (!path2 || typeof path2 !== "string") {
         return false;
       }
-      var extension3 = extname("x." + path2).toLowerCase().substr(1);
+      var extension3 = extname2("x." + path2).toLowerCase().substr(1);
       if (!extension3) {
         return false;
       }
@@ -10040,12 +10040,12 @@ var require_form_data = __commonJS({
         if (value3.end != void 0 && value3.end != Infinity && value3.start != void 0) {
           callback3(null, value3.end + 1 - (value3.start ? value3.start : 0));
         } else {
-          fs2.stat(value3.path, function(err2, stat) {
+          fs2.stat(value3.path, function(err2, stat2) {
             if (err2) {
               callback3(err2);
               return;
             }
-            var fileSize = stat.size - (value3.start ? value3.start : 0);
+            var fileSize = stat2.size - (value3.start ? value3.start : 0);
             callback3(null, fileSize);
           });
         }
@@ -144029,6 +144029,15 @@ function resolveConfig2(raw, env = process.env, deps = {}) {
   const runnerCardTextMax = clamp4(asNumber(merged.runnerCardTextMax, 2048), 512, 8192);
   const finalAnswerMinChars = clamp4(asNumber(merged.finalAnswerMinChars, 600), 0, 2e4);
   const finalAnswerFileMinBytes = clamp4(asNumber(merged.finalAnswerFileMinBytes, 20 * 1024), 8192, 102400);
+  const acceptAttachments = asBoolean(merged.acceptAttachments, true);
+  const attachmentMaxBytes = clamp4(
+    asNumber(merged.attachmentMaxBytes, 20 * 1024 * 1024),
+    1024 * 1024,
+    100 * 1024 * 1024
+  );
+  const attachmentTimeoutMs = clamp4(asNumber(merged.attachmentTimeoutMs, 3e4), 5e3, 12e4);
+  const attachmentsDirRaw = asString(merged.attachmentsDir).trim();
+  const attachmentsDir = attachmentsDirRaw ? attachmentsDirRaw : join(resolveConfigDir(env, deps.configDir), "plugins", "feishu-files");
   const keepaliveIntervalMs = clamp4(
     asNumber(merged.keepaliveIntervalMs, 20 * 60 * 1e3),
     5 * 60 * 1e3,
@@ -144089,7 +144098,11 @@ function resolveConfig2(raw, env = process.env, deps = {}) {
     runnerCardMaxTools,
     runnerCardTextMax,
     finalAnswerMinChars,
-    finalAnswerFileMinBytes
+    finalAnswerFileMinBytes,
+    acceptAttachments,
+    attachmentMaxBytes,
+    attachmentTimeoutMs,
+    attachmentsDir
   };
 }
 function loadConfigFile(env, deps, warnings) {
@@ -144706,6 +144719,27 @@ function extractPostText(rawContent) {
     return "";
   }
 }
+function parseIncomingAttachment(messageType, rawContent) {
+  if (messageType !== "image" && messageType !== "file") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(rawContent);
+  } catch {
+    return void 0;
+  }
+  if (!isRecordLike(parsed)) return void 0;
+  if (messageType === "image") {
+    const imageKey = str(parsed.image_key);
+    return imageKey ? { kind: "image", fileKey: imageKey } : void 0;
+  }
+  const fileKey = str(parsed.file_key);
+  if (!fileKey) return void 0;
+  const fileName = str(parsed.file_name);
+  return { kind: "file", fileKey, ...fileName ? { fileName } : {} };
+}
+function isRecordLike(value3) {
+  return typeof value3 === "object" && value3 !== null && !Array.isArray(value3);
+}
 function parseIncomingMessage(data) {
   if (!isRecord2(data)) return void 0;
   const message = data.message;
@@ -144718,6 +144752,7 @@ function parseIncomingMessage(data) {
   if (!rawContent) return void 0;
   const sender = data.sender;
   const senderOpenId = isRecord2(sender) && isRecord2(sender.sender_id) ? str(sender.sender_id.open_id) : "";
+  const attachment = parseIncomingAttachment(messageType, rawContent);
   return {
     eventId: str(data.event_id),
     messageId,
@@ -144725,6 +144760,7 @@ function parseIncomingMessage(data) {
     chatType: str(message.chat_type) || "p2p",
     messageType,
     text: extractMessageText(messageType, rawContent),
+    ...attachment ? { attachment } : {},
     senderOpenId,
     ...str(message.create_time) ? { createTime: str(message.create_time) } : {},
     ...str(message.thread_id) ? { threadId: str(message.thread_id) } : {},
@@ -145221,6 +145257,114 @@ function createFeishuSender(client, log2, options2 = {}) {
     }
   };
 }
+var AttachmentTimeoutError = class extends Error {
+  constructor() {
+    super("attachment-timeout");
+    this.name = "AttachmentTimeoutError";
+  }
+};
+function withTimeout(promise3, ms) {
+  return new Promise((resolve4, reject) => {
+    const timer = setTimeout(() => reject(new AttachmentTimeoutError()), Math.max(1, ms));
+    timer.unref?.();
+    promise3.then(
+      (value3) => {
+        clearTimeout(timer);
+        resolve4(value3);
+      },
+      (err2) => {
+        clearTimeout(timer);
+        reject(err2);
+      }
+    );
+  });
+}
+function sanitizeAttachmentName(raw, fallback = "attachment") {
+  const base2 = (raw ?? "").trim();
+  const cleaned = base2.replace(/[\\/]/g, "_").replace(/[\u0000-\u001f\u007f]/g, "").replace(/^\.+/, "").slice(0, 120);
+  return cleaned || fallback;
+}
+var IMAGE_EXT_BY_MIME = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/bmp": ".bmp",
+  "image/tiff": ".tiff"
+};
+function imageExtFromHeaders(headers) {
+  const raw = headers?.["content-type"] ?? headers?.["Content-Type"];
+  const mime = typeof raw === "string" ? raw.split(";")[0].trim().toLowerCase() : "";
+  return IMAGE_EXT_BY_MIME[mime] ?? ".png";
+}
+function buildAttachmentFileName(attachment, headers) {
+  if (attachment.kind === "image") {
+    return sanitizeAttachmentName(`image${imageExtFromHeaders(headers)}`, "image.png");
+  }
+  const raw = sanitizeAttachmentName(attachment.fileName, "file");
+  return raw;
+}
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function attachmentSavedPrompt(input) {
+  const size6 = formatBytes(input.size);
+  return input.kind === "image" ? `[\u9644\u4EF6] \u56FE\u7247\u300C${input.name}\u300D\u5DF2\u4FDD\u5B58\u5230 ${input.path}\uFF08${size6}\uFF09\uFF0C\u53EF\u76F4\u63A5\u67E5\u770B\u3002` : `[\u9644\u4EF6] \u6587\u4EF6\u300C${input.name}\u300D\u5DF2\u4FDD\u5B58\u5230 ${input.path}\uFF08${size6}\uFF09\u3002`;
+}
+async function downloadAttachment(input) {
+  const { client, messageId, attachment, dir, maxBytes, timeoutMs, log: log2 } = input;
+  const startedAt = Date.now();
+  let target;
+  try {
+    await mkdir(dir, { recursive: true });
+    const res = await withTimeout(
+      client.im.messageResource.get({
+        params: { type: attachment.kind },
+        path: { message_id: messageId, file_key: attachment.fileKey }
+      }),
+      timeoutMs
+    );
+    if (!res || typeof res.writeFile !== "function") {
+      return { ok: false, reason: "\u8D44\u6E90\u63A5\u53E3\u672A\u8FD4\u56DE\u6587\u4EF6\u6D41" };
+    }
+    const name = buildAttachmentFileName(attachment, res.headers);
+    target = join(dir, `${messageId}-${name}`);
+    await res.writeFile(target);
+    const info = await stat(target);
+    if (info.size > maxBytes) {
+      await rm(target, { force: true });
+      return {
+        ok: false,
+        reason: `\u9644\u4EF6\u8D85\u8FC7\u5927\u5C0F\u4E0A\u9650\uFF08${formatBytes(info.size)} > ${formatBytes(maxBytes)}\uFF09`
+      };
+    }
+    log2.info("\u9644\u4EF6\u5DF2\u4E0B\u8F7D", {
+      messageId,
+      kind: attachment.kind,
+      name,
+      size: info.size,
+      ms: Date.now() - startedAt
+    });
+    return { ok: true, path: target, name, size: info.size };
+  } catch (err2) {
+    if (target) await rm(target, { force: true }).catch(() => void 0);
+    const reason = err2 instanceof AttachmentTimeoutError ? `\u4E0B\u8F7D\u8D85\u65F6\uFF08>${Math.round(timeoutMs / 1e3)}s\uFF09` : errorMessage(err2);
+    log2.warn("\u9644\u4EF6\u4E0B\u8F7D\u5931\u8D25", { messageId, kind: attachment.kind, error: reason });
+    return { ok: false, reason };
+  }
+}
+function downloadedAttachmentPrompt(attachment, outcome) {
+  return attachmentSavedPrompt({
+    kind: attachment.kind,
+    name: outcome.name,
+    path: outcome.path,
+    size: outcome.size
+  });
+}
 
 // src/feishu/session-map.ts
 var CHAT_KEY_PREFIX = "feishu:v2:chat:";
@@ -148237,9 +148381,9 @@ function validateDirectory(rawPath, allowedRoots, deps = {}) {
     if (!isAbsolute(raw)) return err("not_absolute", "\u76EE\u5F55\u5FC5\u987B\u662F**\u7EDD\u5BF9\u8DEF\u5F84**\uFF08\u4EE5 `/` \u5F00\u5934\uFF09\u3002");
     target = resolve$1(raw);
   }
-  const stat = deps.statSync ?? statSync;
+  const stat2 = deps.statSync ?? statSync;
   const realpath = deps.realpathSync ?? realpathSync;
-  const mkdir = deps.mkdirSync ?? mkdirSync;
+  const mkdir2 = deps.mkdirSync ?? mkdirSync;
   const blocked = forbiddenReason(target);
   if (blocked) return blocked;
   if (!roots.some((root) => isUnder(target, root))) {
@@ -148247,13 +148391,13 @@ function validateDirectory(rawPath, allowedRoots, deps = {}) {
   }
   let exists2 = true;
   try {
-    if (!stat(target).isDirectory()) return err("not_dir", `\u4E0D\u662F\u76EE\u5F55\uFF1A\`${target}\``);
+    if (!stat2(target).isDirectory()) return err("not_dir", `\u4E0D\u662F\u76EE\u5F55\uFF1A\`${target}\``);
   } catch {
     exists2 = false;
   }
   if (!exists2) {
     try {
-      mkdir(target, { recursive: true });
+      mkdir2(target, { recursive: true });
     } catch {
       return err("create_failed", `\u76EE\u5F55\u4E0D\u5B58\u5728\u4E14\u65E0\u6CD5\u521B\u5EFA\uFF1A\`${target}\`\u3002\u8BF7\u68C0\u67E5\u8DEF\u5F84\u4E0E\u6743\u9650\u3002`);
     }
@@ -150731,7 +150875,7 @@ var SummaryTimeoutError = class extends Error {
     this.name = "SummaryTimeoutError";
   }
 };
-function withTimeout(promise3, ms) {
+function withTimeout2(promise3, ms) {
   return new Promise((resolve4, reject) => {
     const timer = setTimeout(() => reject(new SummaryTimeoutError()), Math.max(1, ms));
     timer.unref?.();
@@ -150814,7 +150958,7 @@ async function summarizeSession(deps, input) {
   let messages;
   if (deps.readMessages) {
     try {
-      messages = await withTimeout(deps.readMessages(input.sessionID, input.directory), timeoutMs);
+      messages = await withTimeout2(deps.readMessages(input.sessionID, input.directory), timeoutMs);
       const reused = extractLatestSummary(messages);
       if (reused) return { summary: reused, source: "reused" };
     } catch (err2) {
@@ -150827,7 +150971,7 @@ async function summarizeSession(deps, input) {
   if (!deps.generateText) return { source: "none" };
   try {
     const transcript = buildTranscript(messages);
-    const raw = await withTimeout(
+    const raw = await withTimeout2(
       deps.generateText(buildSummaryPrompt(transcript), input.directory),
       timeoutMs
     );
@@ -151827,8 +151971,31 @@ async function start(ctx, config, log2, logSink) {
       ...model ? { model } : {}
     });
     if (!receipt.ok) log2.warn("\u56DE\u6267\u5361\u672A\u53D1\u9001\uFF0C\u4ECD\u7EE7\u7EED prompt", { sessionID, delivery });
+    let promptText = message.text;
+    const files = [];
+    if (config.acceptAttachments && message.attachment) {
+      const outcome = await downloadAttachment({
+        client,
+        messageId: message.messageId,
+        attachment: message.attachment,
+        dir: config.attachmentsDir,
+        maxBytes: config.attachmentMaxBytes,
+        timeoutMs: config.attachmentTimeoutMs,
+        log: log2
+      });
+      if (outcome.ok) {
+        files.push({ uri: pathToFileURL(outcome.path).href });
+        promptText = `${promptText}
+
+${downloadedAttachmentPrompt(message.attachment, outcome)}`;
+      } else {
+        promptText = `${promptText}
+
+[\u9644\u4EF6] \u4E0B\u8F7D\u5931\u8D25\uFF1A${outcome.reason}`;
+      }
+    }
     try {
-      await promptSession(ctx, sessionID, message.text, delivery);
+      await promptSession(ctx, sessionID, promptText, delivery, files);
     } catch (err2) {
       log2.warn("prompt \u53D1\u9001\u5931\u8D25", { sessionID, error: errorMessage(err2) });
       runs.apply(sessionID, { type: "execution.failed", error: errorMessage(err2) });
@@ -152066,9 +152233,14 @@ async function replyPermission(ctx, input) {
     throw err2;
   }
 }
-async function promptSession(ctx, sessionID, text, delivery) {
+async function promptSession(ctx, sessionID, text, delivery, files) {
   const api = ctx.session.prompt;
-  await api({ sessionID, text, delivery });
+  await api({
+    sessionID,
+    text,
+    delivery,
+    ...files && files.length > 0 ? { files } : {}
+  });
 }
 async function readSessionMessages(ctx, sessionID, directory, log2) {
   const options2 = directory ? { headers: { "x-opencode-directory": directory } } : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-feishu-plugin",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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",