fix: explain missing Feishu image permission

src/channels/feishu/message-utils.mjs

@@ -1,5 +1,11 @@
 import { ImagePromptError } from '../shared/image-prompt.mjs';
 
+const FEISHU_MISSING_MESSAGE_SCOPE_CODE = 99991672;
+const FEISHU_ERROR_BODY_LIMIT = 64 * 1024;
+const FEISHU_ERROR_BODY_TIMEOUT_MS = 1_000;
+const FEISHU_IMAGE_PERMISSION_MESSAGE =
+  '飞书机器人缺少图片读取权限。请在飞书开放平台为该应用添加 im:message:readonly，发布新版本并完成必要的管理员审批后，再重新发送图片。';
+
 export function conversationKey(event) {
   const chatType = event?.message?.chat_type;
   if (chatType === 'p2p') {
@@ -119,17 +125,98 @@ async function readBoundedStream(stream, { signal, maxBytes }) {
   }
 }
 
+function providerCode(value) {
+  if (!value || typeof value !== 'object') return null;
+  const code = value.code ?? value.error?.code;
+  return Number.isSafeInteger(Number(code)) ? Number(code) : null;
+}
+
+async function readFeishuErrorBody(stream, signal) {
+  if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') return null;
+  signal?.throwIfAborted();
+  const timeout = AbortSignal.timeout(FEISHU_ERROR_BODY_TIMEOUT_MS);
+  const readSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const abort = () => stream.destroy?.(readSignal.reason);
+  readSignal.addEventListener('abort', abort, { once: true });
+  const chunks = [];
+  let size = 0;
+  try {
+    for await (const chunk of stream) {
+      const data = Buffer.from(chunk);
+      size += data.length;
+      if (size > FEISHU_ERROR_BODY_LIMIT) {
+        stream.destroy?.();
+        return null;
+      }
+      chunks.push(data);
+    }
+    return Buffer.concat(chunks, size).toString('utf8');
+  } catch {
+    signal?.throwIfAborted();
+    return null;
+  } finally {
+    readSignal.removeEventListener('abort', abort);
+  }
+}
+
+async function feishuProviderCode(error, signal) {
+  const pending = [error];
+  const seen = new Set();
+  while (pending.length > 0 && seen.size < 8) {
+    const value = pending.shift();
+    if (!value || (typeof value !== 'object' && typeof value !== 'function') || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    const directCode = providerCode(value);
+    const data = value.response?.data ?? value.data;
+    if (directCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) {
+      data?.destroy?.();
+      return directCode;
+    }
+    if (data && typeof data[Symbol.asyncIterator] === 'function') {
+      const body = await readFeishuErrorBody(data, signal);
+      try {
+        const parsedCode = providerCode(JSON.parse(body));
+        if (parsedCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return parsedCode;
+      } catch {
+        // Non-JSON provider failures keep the generic image download message.
+      }
+    } else {
+      const dataCode = providerCode(data);
+      if (dataCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return dataCode;
+    }
+    pending.push(value.cause);
+  }
+  return null;
+}
+
+async function feishuImageDownloadError(error, signal) {
+  if (await feishuProviderCode(error, signal) !== FEISHU_MISSING_MESSAGE_SCOPE_CODE) return error;
+  return new ImagePromptError(
+    'feishu-image-permission-required',
+    'Feishu image download requires the im:message:readonly tenant scope',
+    FEISHU_IMAGE_PERMISSION_MESSAGE,
+    { cause: error },
+  );
+}
+
 function feishuImageSource(event, client, key) {
   return {
     async load({ signal, maxBytes }) {
       signal?.throwIfAborted();
-      const resource = await client?.im?.v1?.messageResource?.get?.({
-        path: {
-          message_id: event.message.message_id,
-          file_key: key,
-        },
-        params: { type: 'image' },
-      });
+      let resource;
+      try {
+        resource = await client?.im?.v1?.messageResource?.get?.({
+          path: {
+            message_id: event.message.message_id,
+            file_key: key,
+          },
+          params: { type: 'image' },
+        });
+      } catch (error) {
+        throw await feishuImageDownloadError(error, signal);
+      }
       signal?.throwIfAborted();
       const size = declaredSize(resource?.headers);
       if (size !== null && size > maxBytes) {