@downcity/plugins 1.0.4

package/src/chat/channels/feishu/FeishuPlatformMessaging.ts

@@ -0,0 +1,219 @@
+/**
+ * Feishu 平台发送与附件上传辅助函数。
+ *
+ * 关键点（中文）
+ * - 发送消息、上传图片/文件、解析本地附件路径属于“写入型平台能力”。
+ * - `FeishuPlatformClient` 只保留统一入口和状态，不再直接承载全部细节。
+ */
+
+import * as Lark from "@larksuiteoapi/node-sdk";
+import fs from "fs-extra";
+import path from "path";
+import type {
+  FeishuMessagePayloadType,
+} from "@/chat/channels/feishu/types/FeishuChannel.js";
+import type { ParsedFeishuAttachmentCommand } from "@/chat/types/FeishuAttachment.js";
+
+/**
+ * Feishu 发送类依赖。
+ */
+export interface FeishuMessagingDeps {
+  /**
+   * 项目根目录。
+   */
+  rootPath: string;
+  /**
+   * 日志器。
+   */
+  logger: {
+    /**
+     * 记录 error 日志。
+     */
+    error(message: string, data?: Record<string, unknown>): void;
+  };
+  /**
+   * Feishu SDK client。
+   */
+  client: Lark.Client | null;
+  /**
+   * 获取 tenant_access_token 的回调。
+   */
+  getAppAccessToken: () => Promise<string | undefined>;
+  /**
+   * 归一化 domain 的回调。
+   */
+  getNormalizedDomain: () => string;
+}
+
+async function resolveAttachmentLocalPath(
+  deps: FeishuMessagingDeps,
+  pathOrUrl: string,
+): Promise<string> {
+  const raw = String(pathOrUrl || "").trim();
+  if (!raw) {
+    throw new Error("Attachment path is empty");
+  }
+  if (/^https?:\/\//i.test(raw)) {
+    throw new Error("Feishu attachment currently only supports local file path");
+  }
+
+  const absPath = path.isAbsolute(raw) ? raw : path.resolve(deps.rootPath, raw);
+  const exists = await fs.pathExists(absPath);
+  if (!exists) {
+    throw new Error(`Attachment file not found: ${raw}`);
+  }
+  const stat = await fs.stat(absPath);
+  if (!stat.isFile()) {
+    throw new Error(`Attachment path is not a file: ${raw}`);
+  }
+  return absPath;
+}
+
+async function uploadFileToFeishu(
+  deps: FeishuMessagingDeps,
+  localPath: string,
+): Promise<string> {
+  const token = await deps.getAppAccessToken();
+  if (!token) {
+    throw new Error("Failed to get Feishu tenant_access_token");
+  }
+
+  const domain = deps.getNormalizedDomain();
+  const fileName = path.basename(localPath) || "attachment.bin";
+  const fileBuffer = await fs.readFile(localPath);
+  const form = new FormData();
+  form.set("file_type", "stream");
+  form.set("file_name", fileName);
+  form.set("file", new Blob([fileBuffer]), fileName);
+
+  const response = await fetch(`${domain}/open-apis/im/v1/files`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+    body: form,
+  });
+
+  const payload = (await response.json().catch(() => null)) as
+    | {
+        code?: number;
+        msg?: string;
+        data?: {
+          file_key?: string;
+        };
+      }
+    | null;
+  const fileKey = String(payload?.data?.file_key || "").trim();
+  if (!response.ok || payload?.code !== 0 || !fileKey) {
+    throw new Error(
+      `Feishu file upload failed: HTTP ${response.status}, code=${String(payload?.code ?? "")}, msg=${String(payload?.msg ?? "")}`,
+    );
+  }
+
+  return fileKey;
+}
+
+async function uploadImageToFeishu(
+  deps: FeishuMessagingDeps,
+  localPath: string,
+): Promise<string> {
+  if (!deps.client) {
+    throw new Error("Feishu client is not initialized");
+  }
+
+  const fileBuffer = await fs.readFile(localPath);
+  const payload = await deps.client.im.v1.image.create({
+    data: {
+      image_type: "message",
+      image: fileBuffer,
+    },
+  });
+  const imageKey = String(payload?.image_key || "").trim();
+  if (!imageKey) {
+    throw new Error(`Feishu image upload failed: ${localPath}`);
+  }
+  return imageKey;
+}
+
+/**
+ * 发送平台消息。
+ */
+export async function sendFeishuPlatformMessage(
+  deps: FeishuMessagingDeps,
+  chatId: string,
+  chatType: string,
+  messageId: string | undefined,
+  msgType: FeishuMessagePayloadType,
+  content: Record<string, unknown> | string,
+): Promise<void> {
+  if (!deps.client) {
+    throw new Error("Feishu client is not initialized");
+  }
+  const serializedContent =
+    typeof content === "string" ? content : JSON.stringify(content);
+  try {
+    if (chatType !== "p2p" && messageId) {
+      await deps.client.im.v1.message.reply({
+        path: {
+          message_id: messageId,
+        },
+        data: {
+          content: serializedContent,
+          msg_type: msgType,
+        },
+      });
+      return;
+    }
+
+    await deps.client.im.v1.message.create({
+      params: {
+        receive_id_type: "chat_id",
+      },
+      data: {
+        receive_id: chatId,
+        content: serializedContent,
+        msg_type: msgType,
+      },
+    });
+  } catch (error) {
+    deps.logger.error("Failed to send Feishu message", {
+      error: String(error),
+      msgType,
+      chatType,
+    });
+    throw error instanceof Error
+      ? error
+      : new Error(`Failed to send Feishu message: ${String(error)}`);
+  }
+}
+
+/**
+ * 发送附件，并在需要时补发 caption 文本。
+ */
+export async function sendFeishuAttachment(
+  deps: FeishuMessagingDeps,
+  chatId: string,
+  chatType: string,
+  messageId: string | undefined,
+  attachment: ParsedFeishuAttachmentCommand,
+): Promise<void> {
+  const localPath = await resolveAttachmentLocalPath(deps, attachment.pathOrUrl);
+  if (attachment.type === "photo") {
+    const imageKey = await uploadImageToFeishu(deps, localPath);
+    await sendFeishuPlatformMessage(deps, chatId, chatType, messageId, "image", {
+      image_key: imageKey,
+    });
+  } else {
+    const fileKey = await uploadFileToFeishu(deps, localPath);
+    await sendFeishuPlatformMessage(deps, chatId, chatType, messageId, "file", {
+      file_key: fileKey,
+    });
+  }
+
+  const caption = String(attachment.caption || "").trim();
+  if (caption) {
+    await sendFeishuPlatformMessage(deps, chatId, chatType, messageId, "text", {
+      text: caption,
+    });
+  }
+}

package/src/chat/channels/feishu/InboundAttachment.ts

@@ -0,0 +1,261 @@
+import path from "path";
+import type {
+  FeishuInboundAttachmentPayload,
+  FeishuInboundMessageType,
+  FeishuIncomingAttachmentDescriptor,
+} from "@/chat/types/FeishuInboundAttachment.js";
+import { parseFeishuPostMessageContent } from "./PostMessage.js";
+
+/**
+ * Feishu 入站附件工具。
+ *
+ * 关键点（中文）
+ * - 负责把飞书原始 `message_type + content` 归一化成可下载的附件描述。
+ * - 负责生成本地缓存文件名与 `<file>` 标签展示名，避免这些细节继续堆在主 channel 文件里。
+ */
+
+function asObject(content: string): Record<string, unknown> {
+  const parsed = JSON.parse(content) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Feishu message content must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function normalizeMessageType(value: string): FeishuInboundMessageType | undefined {
+  const text = String(value || "").trim().toLowerCase();
+  if (
+    text === "text" ||
+    text === "post" ||
+    text === "image" ||
+    text === "file" ||
+    text === "audio" ||
+    text === "media" ||
+    text === "video"
+  ) {
+    return text;
+  }
+  return undefined;
+}
+
+function readString(
+  payload: Record<string, unknown>,
+  keys: string[],
+): string | undefined {
+  for (const key of keys) {
+    const value = payload[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+function readNumber(
+  payload: Record<string, unknown>,
+  keys: string[],
+): number | undefined {
+  for (const key of keys) {
+    const value = payload[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function buildDescriptor(
+  messageType: Exclude<FeishuInboundMessageType, "text">,
+  payload: Record<string, unknown>,
+): FeishuIncomingAttachmentDescriptor | undefined {
+  const fileKey = readString(payload, ["file_key"]);
+  const imageKey = readString(payload, ["image_key"]);
+  const fileName = readString(payload, ["file_name", "name", "title"]);
+  const duration = readNumber(payload, ["duration"]);
+
+  const raw: FeishuInboundAttachmentPayload = {
+    resourceKey:
+      messageType === "image" ? String(imageKey || "") : String(fileKey || ""),
+    ...(fileName ? { fileName } : {}),
+    ...(typeof duration === "number" ? { duration } : {}),
+    ...(imageKey ? { imageKey } : {}),
+  };
+
+  if (messageType === "image" && imageKey) {
+    return {
+      type: "photo",
+      resourceType: "image",
+      resourceKey: imageKey,
+      fileName: fileName || "image",
+      description: fileName || "image",
+      raw,
+    };
+  }
+
+  if (messageType === "file" && fileKey) {
+    return {
+      type: "document",
+      resourceType: "file",
+      resourceKey: fileKey,
+      ...(fileName ? { fileName } : {}),
+      ...(fileName ? { description: fileName } : {}),
+      raw,
+    };
+  }
+
+  if (messageType === "audio" && fileKey) {
+    return {
+      type: "audio",
+      resourceType: "audio",
+      resourceKey: fileKey,
+      fileName: fileName || "audio",
+      description: fileName || "audio",
+      raw,
+    };
+  }
+
+  if ((messageType === "media" || messageType === "video") && fileKey) {
+    return {
+      type: "video",
+      resourceType: messageType,
+      resourceKey: fileKey,
+      fileName: fileName || "video.mp4",
+      description: fileName || "video",
+      raw,
+    };
+  }
+
+  return undefined;
+}
+
+function sanitizeBaseName(value: string): string {
+  const normalized = String(value || "").trim();
+  const base = path.basename(normalized);
+  return (
+    base.replace(/[^\w.\-()@\u4e00-\u9fff]+/g, "_").slice(0, 160) || "attachment"
+  );
+}
+
+function decodeContentDispositionName(headerValue: string): string | undefined {
+  const raw = String(headerValue || "").trim();
+  if (!raw) return undefined;
+
+  const utf8Match = raw.match(/filename\*\s*=\s*UTF-8''([^;]+)/i);
+  if (utf8Match?.[1]) {
+    try {
+      return decodeURIComponent(utf8Match[1].trim());
+    } catch {
+      return utf8Match[1].trim();
+    }
+  }
+
+  const quotedMatch = raw.match(/filename\s*=\s*"([^"]+)"/i);
+  if (quotedMatch?.[1]) return quotedMatch[1].trim();
+
+  const plainMatch = raw.match(/filename\s*=\s*([^;]+)/i);
+  if (plainMatch?.[1]) return plainMatch[1].trim();
+
+  return undefined;
+}
+
+function extFromMimeType(mimeType: string): string | undefined {
+  const value = String(mimeType || "").trim().toLowerCase().split(";")[0];
+  if (!value) return undefined;
+  if (value === "image/jpeg") return ".jpg";
+  if (value === "image/png") return ".png";
+  if (value === "image/webp") return ".webp";
+  if (value === "image/gif") return ".gif";
+  if (value === "video/mp4") return ".mp4";
+  if (value === "video/quicktime") return ".mov";
+  if (value === "video/webm") return ".webm";
+  if (value === "audio/ogg") return ".ogg";
+  if (value === "audio/mpeg") return ".mp3";
+  if (value === "audio/mp4") return ".m4a";
+  if (value === "application/pdf") return ".pdf";
+  if (value === "text/plain") return ".txt";
+  return undefined;
+}
+
+function defaultExtByAttachmentType(
+  attachment: FeishuIncomingAttachmentDescriptor,
+): string {
+  if (attachment.type === "photo") return ".jpg";
+  if (attachment.type === "video") return ".mp4";
+  if (attachment.type === "audio" || attachment.type === "voice") return ".ogg";
+  return ".bin";
+}
+
+/**
+ * 解析飞书入站消息。
+ *
+ * 说明（中文）
+ * - 文本消息返回正文。
+ * - `post` 消息会降级成“纯文本 + 附件占位”。
+ * - 附件消息返回归一化附件描述；正文通常为空。
+ * - 不支持的 `message_type` 会返回 `unsupportedType`，由上层决定是否提示用户。
+ */
+export function parseFeishuInboundMessage(params: {
+  messageType: string;
+  content: string;
+}): {
+  text: string;
+  attachments: FeishuIncomingAttachmentDescriptor[];
+  unsupportedType?: string;
+} {
+  const messageType = normalizeMessageType(params.messageType);
+  if (!messageType) {
+    return {
+      text: "",
+      attachments: [],
+      unsupportedType: String(params.messageType || "").trim() || "unknown",
+    };
+  }
+
+  const payload = asObject(params.content);
+  if (messageType === "text") {
+    const text = typeof payload.text === "string" ? payload.text : "";
+    return { text, attachments: [] };
+  }
+
+  if (messageType === "post") {
+    return parseFeishuPostMessageContent({
+      content: params.content,
+    });
+  }
+
+  const descriptor = buildDescriptor(messageType, payload);
+  return {
+    text: "",
+    attachments: descriptor ? [descriptor] : [],
+  };
+}
+
+/**
+ * 生成飞书入站附件的本地缓存文件名。
+ *
+ * 关键点（中文）
+ * - 优先使用服务端返回的 `Content-Disposition` 文件名。
+ * - 若无文件名，则回退到附件原始文件名，再根据 MIME 或类型补扩展名。
+ */
+export function buildFeishuInboundCacheFileName(params: {
+  attachment: FeishuIncomingAttachmentDescriptor;
+  messageId: string;
+  headers?: Record<string, unknown>;
+}): string {
+  const headers = params.headers || {};
+  const contentDisposition = String(
+    headers["content-disposition"] || headers["Content-Disposition"] || "",
+  );
+  const contentType = String(headers["content-type"] || headers["Content-Type"] || "");
+  const headerName = decodeContentDispositionName(contentDisposition);
+  const sourceName = headerName || params.attachment.fileName || params.attachment.description || "attachment";
+  const safeBase = sanitizeBaseName(sourceName);
+  const currentExt = path.extname(safeBase);
+  const ext =
+    currentExt ||
+    extFromMimeType(contentType) ||
+    defaultExtByAttachmentType(params.attachment);
+  const baseWithoutExt = currentExt ? safeBase.slice(0, -currentExt.length) : safeBase;
+  const uniq = `${Date.now()}-${String(params.messageId || "").slice(0, 12) || "feishu"}`;
+  return `${uniq}-${baseWithoutExt}${ext}`;
+}

package/src/chat/channels/feishu/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/chat/channels/feishu/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "# Feishu Channel\n\n## 使用约束\n\n- 你的直接输出自动发送到当前飞书会话。\n";
+
+export default TEXT_MODULE_CONTENT;

package/src/chat/channels/feishu/PROMPT.direct.ts.txt

@@ -0,0 +1,5 @@
+# Feishu Channel
+
+## 使用约束
+
+- 你的直接输出自动发送到当前飞书会话。