@m1heng-clawd/feishu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m1heng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# clawd-feishu
+
+Feishu/Lark (飞书) channel plugin for [Clawdbot](https://github.com/clawdbot/clawdbot).
+
+## Installation
+
+```bash
+clawdbot plugins install @m1heng-clawd/feishu
+```
+
+Or install via npm:
+
+```bash
+npm install @m1heng-clawd/feishu
+```
+
+## Configuration
+
+1. Create a self-built app on [Feishu Open Platform](https://open.feishu.cn)
+2. Get your App ID and App Secret from the Credentials page
+3. Enable required permissions (see below)
+4. Configure the plugin:
+
+### Required Permissions
+
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `contact:user.base:readonly` | User info | Get basic user information |
+| `im:message` | Messaging | Send and receive messages |
+| `im:message.p2p_msg:readonly` | DM | Read direct messages to bot |
+| `im:message.group_at_msg:readonly` | Group | Receive @mention messages in groups |
+| `im:message:send_as_bot` | Send | Send messages as the bot |
+| `im:resource` | Media | Upload and download images/files |
+
+### Optional Permissions (for full functionality)
+
+| Permission | Scope | Description |
+|------------|-------|-------------|
+| `im:message.group_msg` | Group | Read all group messages (sensitive) |
+| `im:message:readonly` | Read | Get message history |
+| `im:message:update` | Edit | Update/edit sent messages |
+| `im:message:recall` | Recall | Recall sent messages |
+| `im:message.reactions:read` | Reactions | View message reactions |
+
+```bash
+clawdbot config set channels.feishu.appId "cli_xxxxx"
+clawdbot config set channels.feishu.appSecret "your_app_secret"
+clawdbot config set channels.feishu.enabled true
+```
+
+## Configuration Options
+
+```yaml
+channels:
+  feishu:
+    enabled: true
+    appId: "cli_xxxxx"
+    appSecret: "secret"
+    # Domain: "feishu" (China) or "lark" (International)
+    domain: "feishu"
+    # Connection mode: "websocket" (recommended) or "webhook"
+    connectionMode: "websocket"
+    # DM policy: "pairing" | "open" | "allowlist"
+    dmPolicy: "pairing"
+    # Group policy: "open" | "allowlist" | "disabled"
+    groupPolicy: "allowlist"
+    # Require @mention in groups
+    requireMention: true
+```
+
+## Features
+
+- WebSocket and Webhook connection modes
+- Direct messages and group chats
+- Message replies and quoted message context
+- Image and file uploads
+- Typing indicator (via emoji reactions)
+- Pairing flow for DM approval
+- User and group directory lookup
+
+## License
+
+MIT

package/clawdbot.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "feishu",
+  "channels": ["feishu"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/index.ts

@@ -0,0 +1,41 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+import { feishuPlugin } from "./src/channel.js";
+import { setFeishuRuntime } from "./src/runtime.js";
+
+export { monitorFeishuProvider } from "./src/monitor.js";
+export {
+  sendMessageFeishu,
+  sendCardFeishu,
+  updateCardFeishu,
+  editMessageFeishu,
+  getMessageFeishu,
+} from "./src/send.js";
+export {
+  uploadImageFeishu,
+  uploadFileFeishu,
+  sendImageFeishu,
+  sendFileFeishu,
+  sendMediaFeishu,
+} from "./src/media.js";
+export { probeFeishu } from "./src/probe.js";
+export {
+  addReactionFeishu,
+  removeReactionFeishu,
+  listReactionsFeishu,
+  FeishuEmoji,
+} from "./src/reactions.js";
+export { feishuPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "feishu",
+  name: "Feishu",
+  description: "Feishu/Lark channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setFeishuRuntime(api.runtime);
+    api.registerChannel({ plugin: feishuPlugin });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@m1heng-clawd/feishu",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Clawdbot Feishu/Lark channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "clawdbot.plugin.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m1heng/clawd-feishu"
+  },
+  "keywords": [
+    "clawdbot",
+    "feishu",
+    "lark",
+    "飞书",
+    "chatbot",
+    "ai",
+    "claude"
+  ],
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "feishu",
+      "label": "Feishu",
+      "selectionLabel": "Feishu/Lark (飞书)",
+      "docsPath": "/channels/feishu",
+      "docsLabel": "feishu",
+      "blurb": "飞书/Lark enterprise messaging.",
+      "aliases": [
+        "lark"
+      ],
+      "order": 70
+    },
+    "install": {
+      "npmSpec": "@m1heng-clawd/feishu",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.30.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "clawdbot": "2026.1.24-2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "clawdbot": ">=2026.1.24"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,53 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "clawdbot/plugin-sdk";
+import type { FeishuConfig, FeishuDomain, ResolvedFeishuAccount } from "./types.js";
+
+export function resolveFeishuCredentials(cfg?: FeishuConfig): {
+  appId: string;
+  appSecret: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  domain: FeishuDomain;
+} | null {
+  const appId = cfg?.appId?.trim();
+  const appSecret = cfg?.appSecret?.trim();
+  if (!appId || !appSecret) return null;
+  return {
+    appId,
+    appSecret,
+    encryptKey: cfg?.encryptKey?.trim() || undefined,
+    verificationToken: cfg?.verificationToken?.trim() || undefined,
+    domain: cfg?.domain ?? "feishu",
+  };
+}
+
+export function resolveFeishuAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedFeishuAccount {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  const enabled = feishuCfg?.enabled !== false;
+  const creds = resolveFeishuCredentials(feishuCfg);
+
+  return {
+    accountId: params.accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    enabled,
+    configured: Boolean(creds),
+    appId: creds?.appId,
+    domain: creds?.domain ?? "feishu",
+  };
+}
+
+export function listFeishuAccountIds(_cfg: ClawdbotConfig): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultFeishuAccountId(_cfg: ClawdbotConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function listEnabledFeishuAccounts(cfg: ClawdbotConfig): ResolvedFeishuAccount[] {
+  return listFeishuAccountIds(cfg)
+    .map((accountId) => resolveFeishuAccount({ cfg, accountId }))
+    .filter((account) => account.enabled && account.configured);
+}

package/src/bot.ts

@@ -0,0 +1,320 @@
+import type { ClawdbotConfig, RuntimeEnv } from "clawdbot/plugin-sdk";
+import {
+  buildPendingHistoryContextFromMap,
+  recordPendingHistoryEntryIfEnabled,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  type HistoryEntry,
+} from "clawdbot/plugin-sdk";
+import type { FeishuConfig, FeishuMessageContext } from "./types.js";
+import { getFeishuRuntime } from "./runtime.js";
+import {
+  resolveFeishuGroupConfig,
+  resolveFeishuReplyPolicy,
+  resolveFeishuAllowlistMatch,
+  isFeishuGroupAllowed,
+} from "./policy.js";
+import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
+import { getMessageFeishu } from "./send.js";
+
+export type FeishuMessageEvent = {
+  sender: {
+    sender_id: {
+      open_id?: string;
+      user_id?: string;
+      union_id?: string;
+    };
+    sender_type?: string;
+    tenant_key?: string;
+  };
+  message: {
+    message_id: string;
+    root_id?: string;
+    parent_id?: string;
+    chat_id: string;
+    chat_type: "p2p" | "group";
+    message_type: string;
+    content: string;
+    mentions?: Array<{
+      key: string;
+      id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+      };
+      name: string;
+      tenant_key?: string;
+    }>;
+  };
+};
+
+export type FeishuBotAddedEvent = {
+  chat_id: string;
+  operator_id: {
+    open_id?: string;
+    user_id?: string;
+    union_id?: string;
+  };
+  external: boolean;
+  operator_tenant_key?: string;
+};
+
+function parseMessageContent(content: string, messageType: string): string {
+  try {
+    const parsed = JSON.parse(content);
+    if (messageType === "text") {
+      return parsed.text || "";
+    }
+    return content;
+  } catch {
+    return content;
+  }
+}
+
+function checkBotMentioned(event: FeishuMessageEvent, botOpenId?: string): boolean {
+  const mentions = event.message.mentions ?? [];
+  if (mentions.length === 0) return false;
+  if (!botOpenId) return mentions.length > 0;
+  return mentions.some((m) => m.id.open_id === botOpenId);
+}
+
+function stripBotMention(text: string, mentions?: FeishuMessageEvent["message"]["mentions"]): string {
+  if (!mentions || mentions.length === 0) return text;
+  let result = text;
+  for (const mention of mentions) {
+    result = result.replace(new RegExp(`@${mention.name}\\s*`, "g"), "").trim();
+    result = result.replace(new RegExp(mention.key, "g"), "").trim();
+  }
+  return result;
+}
+
+export function parseFeishuMessageEvent(
+  event: FeishuMessageEvent,
+  botOpenId?: string,
+): FeishuMessageContext {
+  const rawContent = parseMessageContent(event.message.content, event.message.message_type);
+  const mentionedBot = checkBotMentioned(event, botOpenId);
+  const content = stripBotMention(rawContent, event.message.mentions);
+
+  return {
+    chatId: event.message.chat_id,
+    messageId: event.message.message_id,
+    senderId: event.sender.sender_id.user_id || event.sender.sender_id.open_id || "",
+    senderOpenId: event.sender.sender_id.open_id || "",
+    chatType: event.message.chat_type,
+    mentionedBot,
+    rootId: event.message.root_id || undefined,
+    parentId: event.message.parent_id || undefined,
+    content,
+    contentType: event.message.message_type,
+  };
+}
+
+export async function handleFeishuMessage(params: {
+  cfg: ClawdbotConfig;
+  event: FeishuMessageEvent;
+  botOpenId?: string;
+  runtime?: RuntimeEnv;
+  chatHistories?: Map<string, HistoryEntry[]>;
+}): Promise<void> {
+  const { cfg, event, botOpenId, runtime, chatHistories } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  const ctx = parseFeishuMessageEvent(event, botOpenId);
+  const isGroup = ctx.chatType === "group";
+
+  log(`feishu: received message from ${ctx.senderOpenId} in ${ctx.chatId} (${ctx.chatType})`);
+
+  const historyLimit = Math.max(
+    0,
+    feishuCfg?.historyLimit ?? cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
+  );
+
+  if (isGroup) {
+    const groupPolicy = feishuCfg?.groupPolicy ?? "open";
+    const groupAllowFrom = feishuCfg?.groupAllowFrom ?? [];
+    const groupConfig = resolveFeishuGroupConfig({ cfg: feishuCfg, groupId: ctx.chatId });
+
+    const senderAllowFrom = groupConfig?.allowFrom ?? groupAllowFrom;
+    const allowed = isFeishuGroupAllowed({
+      groupPolicy,
+      allowFrom: senderAllowFrom,
+      senderId: ctx.senderOpenId,
+      senderName: ctx.senderName,
+    });
+
+    if (!allowed) {
+      log(`feishu: sender ${ctx.senderOpenId} not in group allowlist`);
+      return;
+    }
+
+    const { requireMention } = resolveFeishuReplyPolicy({
+      isDirectMessage: false,
+      globalConfig: feishuCfg,
+      groupConfig,
+    });
+
+    if (requireMention && !ctx.mentionedBot) {
+      log(`feishu: message in group ${ctx.chatId} did not mention bot, recording to history`);
+      if (chatHistories) {
+        recordPendingHistoryEntryIfEnabled({
+          historyMap: chatHistories,
+          historyKey: ctx.chatId,
+          limit: historyLimit,
+          entry: {
+            sender: ctx.senderOpenId,
+            body: ctx.content,
+            timestamp: Date.now(),
+            messageId: ctx.messageId,
+          },
+        });
+      }
+      return;
+    }
+  } else {
+    const dmPolicy = feishuCfg?.dmPolicy ?? "pairing";
+    const allowFrom = feishuCfg?.allowFrom ?? [];
+
+    if (dmPolicy === "allowlist") {
+      const match = resolveFeishuAllowlistMatch({
+        allowFrom,
+        senderId: ctx.senderOpenId,
+      });
+      if (!match.allowed) {
+        log(`feishu: sender ${ctx.senderOpenId} not in DM allowlist`);
+        return;
+      }
+    }
+  }
+
+  try {
+    const core = getFeishuRuntime();
+
+    const feishuFrom = isGroup ? `feishu:group:${ctx.chatId}` : `feishu:${ctx.senderOpenId}`;
+    const feishuTo = isGroup ? `chat:${ctx.chatId}` : `user:${ctx.senderOpenId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "feishu",
+      peer: {
+        kind: isGroup ? "group" : "dm",
+        id: isGroup ? ctx.chatId : ctx.senderOpenId,
+      },
+    });
+
+    const preview = ctx.content.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel = isGroup
+      ? `Feishu message in group ${ctx.chatId}`
+      : `Feishu DM from ${ctx.senderOpenId}`;
+
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `feishu:message:${ctx.chatId}:${ctx.messageId}`,
+    });
+
+    // Fetch quoted/replied message content if parentId exists
+    let quotedContent: string | undefined;
+    if (ctx.parentId) {
+      try {
+        const quotedMsg = await getMessageFeishu({ cfg, messageId: ctx.parentId });
+        if (quotedMsg) {
+          quotedContent = quotedMsg.content;
+          log(`feishu: fetched quoted message: ${quotedContent?.slice(0, 100)}`);
+        }
+      } catch (err) {
+        log(`feishu: failed to fetch quoted message: ${String(err)}`);
+      }
+    }
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+
+    // Build message body with quoted content if available
+    let messageBody = ctx.content;
+    if (quotedContent) {
+      messageBody = `[Replying to: "${quotedContent}"]\n\n${ctx.content}`;
+    }
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "Feishu",
+      from: isGroup ? ctx.chatId : ctx.senderOpenId,
+      timestamp: new Date(),
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    let combinedBody = body;
+    const historyKey = isGroup ? ctx.chatId : undefined;
+
+    if (isGroup && historyKey && chatHistories) {
+      combinedBody = buildPendingHistoryContextFromMap({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatAgentEnvelope({
+            channel: "Feishu",
+            from: ctx.chatId,
+            timestamp: entry.timestamp,
+            body: `${entry.sender}: ${entry.body}`,
+            envelope: envelopeOptions,
+          }),
+      });
+    }
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: ctx.content,
+      CommandBody: ctx.content,
+      From: feishuFrom,
+      To: feishuTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: isGroup ? "group" : "direct",
+      GroupSubject: isGroup ? ctx.chatId : undefined,
+      SenderName: ctx.senderOpenId,
+      SenderId: ctx.senderOpenId,
+      Provider: "feishu" as const,
+      Surface: "feishu" as const,
+      MessageSid: ctx.messageId,
+      Timestamp: Date.now(),
+      WasMentioned: ctx.mentionedBot,
+      CommandAuthorized: true,
+      OriginatingChannel: "feishu" as const,
+      OriginatingTo: feishuTo,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createFeishuReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime: runtime as RuntimeEnv,
+      chatId: ctx.chatId,
+      replyToMessageId: ctx.messageId,
+    });
+
+    log(`feishu: dispatching to agent (session=${route.sessionKey})`);
+
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    if (isGroup && historyKey && chatHistories) {
+      clearHistoryEntriesIfEnabled({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+      });
+    }
+
+    log(`feishu: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`);
+  } catch (err) {
+    error(`feishu: failed to dispatch message: ${String(err)}`);
+  }
+}