Skip to content

🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.

14.7 KB
Raw Blame
import fsp from "node:fs/promises";
import path from "node:path";
import * as Lark from "@larksuiteoapi/node-sdk";
import { randomUUID } from "node:crypto";
import { logger } from "../../log.js";
import { t } from "../../i18n/index.js";

const FEISHU_IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
const FEISHU_FILE_TYPES: Record<string, string> = {
  pdf: "pdf", doc: "doc", docx: "doc", xls: "xls", xlsx: "xls", csv: "xls", ppt: "ppt", pptx: "ppt", mp4: "mp4", opus: "opus",
};

/** 归一化后的飞书 im.message.receive_v1 关键字段 */
export interface FeishuMessageEvent {
  eventId?: string;
  messageId: string;
  chatId: string;
  chatType: "p2p" | "group" | string;
  messageType: string;
  content: string; // 原始 JSON 字符串
  senderOpenId: string;
  mentions: Array<{ key: string; name?: string; openId?: string }>;
  createTime: number;
  /** 回复(或话题里的消息):回复链的根消息、直接回复的那条(message_id);不是回复时没有 */
  rootId?: string;
  parentId?: string;
}

/** im.message.receive_v1 的事件 → FeishuMessageEvent */
export function messageEventOf(data: any): FeishuMessageEvent {
  const m = data?.message ?? {};
  return {
    eventId: data?.event_id,
    messageId: m.message_id,
    chatId: m.chat_id,
    chatType: m.chat_type,
    messageType: m.message_type,
    content: m.content ?? "{}",
    senderOpenId: data?.sender?.sender_id?.open_id ?? "",
    mentions: (m.mentions ?? []).map((x: any) => ({ key: x.key, name: x.name, openId: x.id?.open_id })),
    createTime: Number(m.create_time ?? Date.now()),
    ...(m.root_id ? { rootId: String(m.root_id) } : {}),
    ...(m.parent_id ? { parentId: String(m.parent_id) } : {}),
  };
}

/** 读不了会话的历史消息(应用没开 im:message.history:readonly 这类权限、机器人不在群里、用户不在可用范围):离线补消息做不了 */
export class HistoryDenied extends Error {}

/** 飞书说的「没权限」:HTTP 403,缺权限范围(99991672 / 99991679)、缺必要权限(230027)、不在群里(230002)、不在可用范围(230013) */
export function historyDenied(status: number | undefined, code: number | undefined, msg = ""): boolean {
  if (status === 403) return true;
  if (code !== undefined && [99991672, 99991679, 230027, 230002, 230013].includes(code)) return true;
  return /scope|permission|access denied|权限/i.test(msg);
}

/** 会话历史里的一条(im.v1.message.list 的 item)→ FeishuMessageEvent;chatType 由调用方给(列表里没有) */
export function historyEvent(m: any, chatType: string): FeishuMessageEvent {
  return {
    messageId: String(m?.message_id ?? ""),
    chatId: String(m?.chat_id ?? ""),
    chatType,
    messageType: String(m?.msg_type ?? ""),
    content: m?.body?.content ?? "{}",
    senderOpenId: m?.sender?.id_type === "open_id" ? String(m.sender.id ?? "") : "",
    mentions: (m?.mentions ?? []).map((x: any) => ({ key: x.key, name: x.name, openId: x.id_type === "open_id" ? x.id : undefined })),
    createTime: Number(m?.create_time ?? 0),
  };
}

/**
 * 飞书传输层抽象(便于离线测试用 mock 替换)。
 * 真实实现:WSClient 长连接接收事件 + OpenAPI(CardKit 流式卡片 / 文本回复)。
 */
/** 卡片按钮回调(card.action.trigger):value 为按钮上携带的值 */
export interface FeishuCardAction {
  value: Record<string, string>;
  operatorOpenId: string;
  messageId?: string;
}
export type CardActionHandler = (a: FeishuCardAction) => { toast: string; ok: boolean } | Promise<{ toast: string; ok: boolean }>;

export interface FeishuTransport {
  start(
    onMessage: (ev: FeishuMessageEvent) => void,
    onState: (state: "connecting" | "connected" | "error", detail?: string) => void,
    onCardAction?: CardActionHandler,
  ): Promise<void>;
  /** 发送带按钮的交互卡片(审批/提问);未实现时降级为文本 */
  replyActionCard?(replyToMessageId: string, card: Record<string, unknown>, uuid?: string): Promise<void>;
  stop(): Promise<void>;
  createStreamingCard(initial: string): Promise<string>;
  sendCardReply(replyToMessageId: string, cardId: string): Promise<void>;
  updateCardText(cardId: string, elementId: string, text: string, sequence: number): Promise<void>;
  finishCard(cardId: string, sequence: number, summary: string): Promise<void>;
  /** uuid:出站队列给的确定 id,飞书 1 小时内对同一 uuid 只发一次(去重) */
  replyText(replyToMessageId: string, text: string, uuid?: string): Promise<void>;
  /** 上传本地文件并作为图片/文件消息回复(present 交付物) */
  replyFile?(replyToMessageId: string, filePath: string, uuid?: string): Promise<void>;
  /** 主动发一条文本到会话(不是回复某条消息;用于余额提醒、使用请求通知) */
  sendText?(chatId: string, text: string, uuid?: string): Promise<void>;
  /**
   * 离线时漏掉的消息(长连接不补推离线时的事件):会话里 since(毫秒)之后用户发的消息,旧的在前,最多 limit 条(最新的那几条);
   * 机器人自己发的、撤回的不算。读不了历史消息时抛 HistoryDenied
   */
  listMessages?(chatId: string, o: { since: number; limit: number; chatType: string }): Promise<FeishuMessageEvent[]>;
}

export const CARD_ELEMENT_ID = "md";

export function streamingCardSpec(initial: string) {
  return {
    schema: "2.0",
    config: {
      streaming_mode: true,
      summary: { content: t("channel.card_generating") },
      streaming_config: {
        print_frequency_ms: { default: 50 },
        print_step: { default: 2 },
        print_strategy: "fast",
      },
    },
    body: { elements: [{ tag: "markdown", element_id: CARD_ELEMENT_ID, content: initial }] },
  };
}

/** 审批/提问卡片:说明 + 一排回调按钮(schema 2.0)。 */
export function actionCardSpec(title: string, text: string, buttons: Array<{ label: string; value: Record<string, string>; style?: string }>) {
  return {
    schema: "2.0",
    config: { summary: { content: title } },
    header: { title: { tag: "plain_text", content: title }, template: "orange" },
    body: {
      elements: [
        { tag: "markdown", content: text },
        {
          tag: "column_set",
          columns: buttons.map((b) => ({
            tag: "column",
            width: "auto",
            elements: [
              {
                tag: "button",
                text: { tag: "plain_text", content: b.label },
                type: b.style === "danger" ? "danger" : b.style === "primary" ? "primary" : "default",
                behaviors: [{ type: "callback", value: b.value }],
              },
            ],
          })),
        },
      ],
    },
  };
}

/** 飞书返回了错误码:出站队列把它当作"平台拒绝"(试几次就放弃),网络错误则一直重试到过期 */
function check(res: { code?: number; msg?: string } | undefined, what: string): void {
  if (res && typeof res.code === "number" && res.code !== 0) throw Object.assign(new Error(`${what} failed: code=${res.code} msg=${res.msg}`), { rejected: true, code: res.code });
}

export class LarkTransport implements FeishuTransport {
  private client: Lark.Client;
  private ws: Lark.WSClient | undefined;
  private log = logger("feishu");

  constructor(private appId: string, private appSecret: string, private domain: "feishu" | "lark" = "feishu") {
    this.client = new Lark.Client({
      appId,
      appSecret,
      domain: domain === "lark" ? Lark.Domain.Lark : Lark.Domain.Feishu,
      loggerLevel: Lark.LoggerLevel.warn,
    });
  }

  async start(
    onMessage: (ev: FeishuMessageEvent) => void,
    onState: (s: "connecting" | "connected" | "error", d?: string) => void,
    onCardAction?: CardActionHandler,
  ): Promise<void> {
    onState("connecting");
    const dispatcher = new Lark.EventDispatcher({}).register({
      // 卡片按钮回调(长连接模式下以事件形式下发;需在开发者后台订阅 card.action.trigger)
      "card.action.trigger": async (data: any) => {
        if (!onCardAction) return {};
        try {
          const r = await onCardAction({
            value: (data?.action?.value ?? {}) as Record<string, string>,
            operatorOpenId: data?.operator?.open_id ?? "",
            messageId: data?.context?.open_message_id,
          });
          return { toast: { type: r.ok ? "success" : "warning", content: r.toast } };
        } catch (e) {
          this.log.warn("card action failed", { message: (e as Error).message });
          return { toast: { type: "error", content: t("channel.card_action_failed") } };
        }
      },
      "im.message.receive_v1": async (data: any) => {
        // 3 秒规则:立即返回,业务异步处理(onMessage 内只入队)
        try {
          onMessage(messageEventOf(data));
        } catch (e) {
          this.log.warn("bad event", { message: (e as Error).message });
        }
      },
    });
    this.ws = new Lark.WSClient({
      appId: this.appId,
      appSecret: this.appSecret,
      domain: this.domain === "lark" ? Lark.Domain.Lark : Lark.Domain.Feishu,
      loggerLevel: Lark.LoggerLevel.warn,
      autoReconnect: true,
      onReady: () => onState("connected"),
      onError: (err: Error) => onState("error", err?.message),
      onReconnecting: () => onState("connecting", "reconnecting"),
      onReconnected: () => onState("connected", "reconnected"),
    } as any);
    await this.ws.start({ eventDispatcher: dispatcher });
  }

  async stop(): Promise<void> {
    try {
      (this.ws as any)?.close?.({ force: true });
    } catch {
      /* ignore */
    }
    this.ws = undefined;
  }

  async createStreamingCard(initial: string): Promise<string> {
    const res: any = await this.client.cardkit.v1.card.create({
      data: { type: "card_json", data: JSON.stringify(streamingCardSpec(initial)) },
    });
    check(res, "cardkit.card.create");
    const id = res?.data?.card_id;
    if (!id) throw new Error("cardkit.card.create returned no card_id");
    return id;
  }

  async sendCardReply(replyToMessageId: string, cardId: string): Promise<void> {
    const res: any = await this.client.im.v1.message.reply({
      path: { message_id: replyToMessageId },
      data: { msg_type: "interactive", content: JSON.stringify({ type: "card", data: { card_id: cardId } }) },
    });
    check(res, "im.message.reply(card)");
  }

  async updateCardText(cardId: string, elementId: string, text: string, sequence: number): Promise<void> {
    const res: any = await this.client.cardkit.v1.cardElement.content({
      path: { card_id: cardId, element_id: elementId },
      data: { content: text, sequence, uuid: randomUUID() },
    });
    check(res, "cardkit.cardElement.content");
  }

  async finishCard(cardId: string, sequence: number, summary: string): Promise<void> {
    const res: any = await this.client.cardkit.v1.card.settings({
      path: { card_id: cardId },
      data: {
        settings: JSON.stringify({ config: { streaming_mode: false, summary: { content: summary } } }),
        sequence,
        uuid: randomUUID(),
      },
    });
    check(res, "cardkit.card.settings");
  }

  async replyActionCard(replyToMessageId: string, card: Record<string, unknown>, uuid?: string): Promise<void> {
    const res: any = await this.client.im.v1.message.reply({
      path: { message_id: replyToMessageId },
      data: { msg_type: "interactive", content: JSON.stringify(card), ...(uuid ? { uuid } : {}) },
    });
    check(res, "im.message.reply(action card)");
  }

  async replyFile(replyToMessageId: string, filePath: string, uuid?: string): Promise<void> {
    const buf = await fsp.readFile(filePath);
    const name = path.basename(filePath);
    const ext = path.extname(name).toLowerCase().slice(1);
    let msgType: "image" | "file";
    let content: string;
    if (FEISHU_IMAGE_EXT.has(ext) && buf.length <= 10 * 1024 * 1024) {
      const res: any = await this.client.im.v1.image.create({ data: { image_type: "message", image: buf } as any });
      const key = res?.image_key ?? res?.data?.image_key;
      if (!key) throw new Error(`im.image.create failed${res?.code ? ` (code ${res.code})` : ""}`);
      msgType = "image";
      content = JSON.stringify({ image_key: key });
    } else {
      if (buf.length > 30 * 1024 * 1024) throw new Error("file too large for feishu (>30MB)");
      const fileType = FEISHU_FILE_TYPES[ext] ?? "stream";
      const res: any = await this.client.im.v1.file.create({ data: { file_type: fileType, file_name: name, file: buf } as any });
      const key = res?.file_key ?? res?.data?.file_key;
      if (!key) throw new Error(`im.file.create failed${res?.code ? ` (code ${res.code})` : ""}`);
      msgType = "file";
      content = JSON.stringify({ file_key: key });
    }
    const res: any = await this.client.im.v1.message.reply({ path: { message_id: replyToMessageId }, data: { msg_type: msgType, content, ...(uuid ? { uuid } : {}) } });
    check(res, `im.message.reply(${msgType})`);
  }

  async replyText(replyToMessageId: string, text: string, uuid?: string): Promise<void> {
    const res: any = await this.client.im.v1.message.reply({
      path: { message_id: replyToMessageId },
      data: { msg_type: "text", content: JSON.stringify({ text }), ...(uuid ? { uuid } : {}) },
    });
    check(res, "im.message.reply(text)");
  }

  async listMessages(chatId: string, o: { since: number; limit: number; chatType: string }): Promise<FeishuMessageEvent[]> {
    let res: any;
    try {
      res = await this.client.im.v1.message.list({
        params: { container_id_type: "chat", container_id: chatId, start_time: String(Math.floor(o.since / 1000)), sort_type: "ByCreateTimeDesc", page_size: Math.min(50, Math.max(1, o.limit)) },
      });
    } catch (e) {
      const r = (e as { response?: { status?: number; data?: { code?: number; msg?: string } } }).response;
      if (historyDenied(r?.status, r?.data?.code, r?.data?.msg)) throw new HistoryDenied(`im.message.list denied: code=${r?.data?.code ?? r?.status} msg=${r?.data?.msg ?? ""}`);
      throw e;
    }
    if (res?.code && historyDenied(undefined, res.code, res.msg)) throw new HistoryDenied(`im.message.list denied: code=${res.code} msg=${res.msg}`);
    check(res, "im.message.list");
    const items: any[] = res?.data?.items ?? [];
    return items
      .filter((m) => m?.sender?.sender_type === "user" && !m.deleted)
      .map((m) => historyEvent(m, o.chatType))
      .filter((ev) => ev.messageId && ev.createTime > o.since)
      .reverse();
  }

  async sendText(chatId: string, text: string, uuid?: string): Promise<void> {
    const res: any = await this.client.im.v1.message.create({
      params: { receive_id_type: "chat_id" },
      data: { receive_id: chatId, msg_type: "text", content: JSON.stringify({ text }), ...(uuid ? { uuid } : {}) },
    });
    check(res, "im.message.create(text)");
  }
}