@openclaw/feishu 2026.3.13 → 2026.5.1-beta.1

package/src/policy.ts

@@ -1,13 +1,39 @@
-import type {
-  AllowlistMatch,
-  ChannelGroupContext,
-  GroupToolPolicyConfig,
-} from "openclaw/plugin-sdk/feishu";
-import { evaluateSenderGroupAccessForPolicy } from "openclaw/plugin-sdk/feishu";
-import { normalizeFeishuTarget } from "./targets.js";
-import type { FeishuConfig, FeishuGroupConfig } from "./types.js";
+import {
+  normalizeAccountId,
+  resolveMergedAccountConfig,
+} from "openclaw/plugin-sdk/account-resolution";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { evaluateSenderGroupAccessForPolicy } from "openclaw/plugin-sdk/group-access";
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import type { AllowlistMatch, ChannelGroupContext } from "../runtime-api.js";
+import { detectIdType } from "./targets.js";
+import type { FeishuConfig } from "./types.js";
+
+type FeishuAllowlistMatch = AllowlistMatch<"wildcard" | "id">;
+
+const FEISHU_PROVIDER_PREFIX_RE = /^(feishu|lark):/i;
+
+function stripRepeatedFeishuProviderPrefixes(raw: string): string {
+  let normalized = raw.trim();
+  while (FEISHU_PROVIDER_PREFIX_RE.test(normalized)) {
+    normalized = normalized.replace(FEISHU_PROVIDER_PREFIX_RE, "").trim();
+  }
+  return normalized;
+}
 
-export type FeishuAllowlistMatch = AllowlistMatch<"wildcard" | "id">;
+function canonicalizeFeishuAllowlistKey(params: { kind: "chat" | "user"; value: string }): string {
+  const value = params.value.trim();
+  if (!value) {
+    return "";
+  }
+  // A typed wildcard (`chat:*`, `user:*`, `open_id:*`, `dm:*`, `group:*`,
+  // `channel:*`) collapses to the bare wildcard so it keeps matching across
+  // both kinds, preserving the prior `normalizeFeishuTarget`-based behavior.
+  if (value === "*") {
+    return "*";
+  }
+  return `${params.kind}:${value}`;
+}
 
 function normalizeFeishuAllowEntry(raw: string): string {
   const trimmed = raw.trim();
@@ -17,9 +43,56 @@ function normalizeFeishuAllowEntry(raw: string): string {
   if (trimmed === "*") {
     return "*";
   }
-  const withoutProviderPrefix = trimmed.replace(/^feishu:/i, "");
-  const normalized = normalizeFeishuTarget(withoutProviderPrefix) ?? withoutProviderPrefix;
-  return normalized.trim().toLowerCase();
+
+  const withoutProviderPrefix = stripRepeatedFeishuProviderPrefixes(trimmed);
+  if (withoutProviderPrefix === "*") {
+    return "*";
+  }
+  const lowered = normalizeOptionalLowercaseString(withoutProviderPrefix) ?? "";
+  if (!lowered) {
+    return "";
+  }
+  // Lowercase for prefix detection only; preserve the original ID casing in the
+  // canonicalized key. Sender candidates pass through this same path so allowlist
+  // entries and runtime IDs stay normalized symmetrically.
+  if (
+    lowered.startsWith("chat:") ||
+    lowered.startsWith("group:") ||
+    lowered.startsWith("channel:")
+  ) {
+    return canonicalizeFeishuAllowlistKey({
+      kind: "chat",
+      value: withoutProviderPrefix.slice(withoutProviderPrefix.indexOf(":") + 1),
+    });
+  }
+  if (lowered.startsWith("user:") || lowered.startsWith("dm:")) {
+    return canonicalizeFeishuAllowlistKey({
+      kind: "user",
+      value: withoutProviderPrefix.slice(withoutProviderPrefix.indexOf(":") + 1),
+    });
+  }
+  if (lowered.startsWith("open_id:")) {
+    return canonicalizeFeishuAllowlistKey({
+      kind: "user",
+      value: withoutProviderPrefix.slice(withoutProviderPrefix.indexOf(":") + 1),
+    });
+  }
+
+  const detectedType = detectIdType(withoutProviderPrefix);
+  if (detectedType === "chat_id") {
+    return canonicalizeFeishuAllowlistKey({
+      kind: "chat",
+      value: withoutProviderPrefix,
+    });
+  }
+  if (detectedType === "open_id" || detectedType === "user_id") {
+    return canonicalizeFeishuAllowlistKey({
+      kind: "user",
+      value: withoutProviderPrefix,
+    });
+  }
+
+  return "";
 }
 
 export function resolveFeishuAllowlistMatch(params: {
@@ -40,7 +113,7 @@ export function resolveFeishuAllowlistMatch(params: {
 
   // Feishu allowlists are ID-based; mutable display names must never grant access.
   const senderCandidates = [params.senderId, ...(params.senderIds ?? [])]
-    .map((entry) => normalizeFeishuAllowEntry(String(entry ?? "")))
+    .map((entry) => normalizeFeishuAllowEntry(entry ?? ""))
     .filter(Boolean);
 
   for (const senderId of senderCandidates) {
@@ -52,10 +125,7 @@ export function resolveFeishuAllowlistMatch(params: {
   return { allowed: false };
 }
 
-export function resolveFeishuGroupConfig(params: {
-  cfg?: FeishuConfig;
-  groupId?: string | null;
-}): FeishuGroupConfig | undefined {
+export function resolveFeishuGroupConfig(params: { cfg?: FeishuConfig; groupId?: string | null }) {
   const groups = params.cfg?.groups ?? {};
   const wildcard = groups["*"];
   const groupId = params.groupId?.trim();
@@ -68,18 +138,37 @@ export function resolveFeishuGroupConfig(params: {
     return direct;
   }
 
-  const lowered = groupId.toLowerCase();
-  const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+  const lowered = normalizeOptionalLowercaseString(groupId) ?? "";
+  const matchKey = Object.keys(groups).find(
+    (key) => normalizeOptionalLowercaseString(key) === lowered,
+  );
   if (matchKey) {
     return groups[matchKey];
   }
   return wildcard;
 }
 
-export function resolveFeishuGroupToolPolicy(
-  params: ChannelGroupContext,
-): GroupToolPolicyConfig | undefined {
-  const cfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+export function hasExplicitFeishuGroupConfig(params: {
+  cfg?: FeishuConfig;
+  groupId?: string | null;
+}): boolean {
+  const groups = params.cfg?.groups ?? {};
+  const groupId = params.groupId?.trim();
+  if (!groupId) {
+    return false;
+  }
+  if (Object.prototype.hasOwnProperty.call(groups, groupId) && groupId !== "*") {
+    return true;
+  }
+
+  const lowered = normalizeOptionalLowercaseString(groupId) ?? "";
+  return Object.keys(groups).some(
+    (key) => key !== "*" && normalizeOptionalLowercaseString(key) === lowered,
+  );
+}
+
+export function resolveFeishuGroupToolPolicy(params: ChannelGroupContext) {
+  const cfg = params.cfg.channels?.feishu;
   if (!cfg) {
     return undefined;
   }
@@ -109,15 +198,39 @@ export function isFeishuGroupAllowed(params: {
 
 export function resolveFeishuReplyPolicy(params: {
   isDirectMessage: boolean;
-  globalConfig?: FeishuConfig;
-  groupConfig?: FeishuGroupConfig;
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  groupId?: string | null;
+  /**
+   * Effective group policy resolved for this chat. When "open", requireMention
+   * defaults to false so that non-text messages (e.g. images) that cannot carry
+   * @-mentions are still delivered to the agent.
+   */
+  groupPolicy?: "open" | "allowlist" | "disabled" | "allowall";
 }): { requireMention: boolean } {
   if (params.isDirectMessage) {
     return { requireMention: false };
   }
 
-  const requireMention =
-    params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true;
-
-  return { requireMention };
+  const feishuCfg = params.cfg.channels?.feishu;
+  const resolvedCfg = resolveMergedAccountConfig<FeishuConfig>({
+    channelConfig: feishuCfg,
+    accounts: feishuCfg?.accounts as Record<string, Partial<FeishuConfig>> | undefined,
+    accountId: normalizeAccountId(params.accountId),
+    normalizeAccountId,
+    omitKeys: ["defaultAccount"],
+  });
+  const groupRequireMention = resolveFeishuGroupConfig({
+    cfg: resolvedCfg,
+    groupId: params.groupId,
+  })?.requireMention;
+
+  return {
+    requireMention:
+      typeof groupRequireMention === "boolean"
+        ? groupRequireMention
+        : typeof resolvedCfg.requireMention === "boolean"
+          ? resolvedCfg.requireMention
+          : params.groupPolicy !== "open",
+  };
 }

package/src/post.ts

@@ -1,7 +1,9 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import { isRecord } from "./comment-shared.js";
 import { normalizeFeishuExternalKey } from "./external-keys.js";
 
 const FALLBACK_POST_TEXT = "[Rich text message]";
-const MARKDOWN_SPECIAL_CHARS = /([\\`*_{}\[\]()#+\-!|>~])/g;
+const MARKDOWN_SPECIAL_CHARS = /([\\`*_{}[\]()#+\-!|>~])/g;
 
 type PostParseResult = {
   textContent: string;
@@ -15,10 +17,6 @@ type PostPayload = {
   content: unknown[];
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
 function toStringOrEmpty(value: unknown): string {
   return typeof value === "string" ? value : "";
 }
@@ -136,7 +134,7 @@ function renderElement(
     return escapeMarkdownText(toStringOrEmpty(element));
   }
 
-  const tag = toStringOrEmpty(element.tag).toLowerCase();
+  const tag = normalizeLowercaseStringOrEmpty(toStringOrEmpty(element.tag));
   switch (tag) {
     case "text":
       return renderTextElement(element);
@@ -168,6 +166,9 @@ function renderElement(
     }
     case "emotion":
       return renderEmotionElement(element);
+    case "md":
+    case "lark_md":
+      return toStringOrEmpty(element.text) || toStringOrEmpty(element.content);
     case "br":
       return "\n";
     case "hr":

package/src/probe.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { clearProbeCache, FEISHU_PROBE_REQUEST_TIMEOUT_MS, probeFeishu } from "./probe.js";
 
 const createFeishuClientMock = vi.hoisted(() => vi.fn());
 
@@ -6,12 +7,10 @@ vi.mock("./client.js", () => ({
   createFeishuClient: createFeishuClientMock,
 }));
 
-import { FEISHU_PROBE_REQUEST_TIMEOUT_MS, probeFeishu, clearProbeCache } from "./probe.js";
-
 const DEFAULT_CREDS = { appId: "cli_123", appSecret: "secret" } as const; // pragma: allowlist secret
 const DEFAULT_SUCCESS_RESPONSE = {
   code: 0,
-  bot: { bot_name: "TestBot", open_id: "ou_abc123" },
+  data: { pingBotInfo: { botName: "TestBot", botID: "ou_abc123" } },
 } as const;
 const DEFAULT_SUCCESS_RESULT = {
   ok: true,
@@ -21,7 +20,7 @@ const DEFAULT_SUCCESS_RESULT = {
 } as const;
 const BOT1_RESPONSE = {
   code: 0,
-  bot: { bot_name: "Bot1", open_id: "ou_1" },
+  data: { pingBotInfo: { botName: "Bot1", botID: "ou_1" } },
 } as const;
 
 function makeRequestFn(response: Record<string, unknown>) {
@@ -40,7 +39,12 @@ function setupSuccessClient() {
 
 async function expectDefaultSuccessResult(
   creds = DEFAULT_CREDS,
-  expected: Awaited<ReturnType<typeof probeFeishu>> = DEFAULT_SUCCESS_RESULT,
+  expected: {
+    ok: true;
+    appId: string;
+    botName: string;
+    botOpenId: string;
+  } = DEFAULT_SUCCESS_RESULT,
 ) {
   const result = await probeFeishu(creds);
   expect(result).toEqual(expected);
@@ -131,8 +135,9 @@ describe("probeFeishu", () => {
 
     expect(requestFn).toHaveBeenCalledWith(
       expect.objectContaining({
-        method: "GET",
-        url: "/open-apis/bot/v3/info",
+        method: "POST",
+        url: "/open-apis/bot/v1/openclaw_bot/ping",
+        data: { needBotInfo: true },
         timeout: FEISHU_PROBE_REQUEST_TIMEOUT_MS,
       }),
     );
@@ -255,10 +260,10 @@ describe("probeFeishu", () => {
     });
   });
 
-  it("handles response.data.bot fallback path", async () => {
+  it("handles response with pingBotInfo in data", async () => {
     setupClient({
       code: 0,
-      data: { bot: { bot_name: "DataBot", open_id: "ou_data" } },
+      data: { pingBotInfo: { botName: "DataBot", botID: "ou_data" } },
     });
 
     await expectDefaultSuccessResult(DEFAULT_CREDS, {

package/src/probe.ts

@@ -1,3 +1,4 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { raceWithTimeoutAndAbort } from "./async.js";
 import { createFeishuClient, type FeishuClientCredentials } from "./client.js";
 import type { FeishuProbeResult } from "./types.js";
@@ -17,11 +18,19 @@ export type ProbeFeishuOptions = {
   abortSignal?: AbortSignal;
 };
 
-type FeishuBotInfoResponse = {
+type FeishuPingResponse = {
   code: number;
   msg?: string;
-  bot?: { bot_name?: string; open_id?: string };
-  data?: { bot?: { bot_name?: string; open_id?: string } };
+  data?: { pingBotInfo?: { botID?: string; botName?: string } };
+};
+
+type FeishuRequestClient = ReturnType<typeof createFeishuClient> & {
+  request(params: {
+    method: "POST";
+    url: string;
+    data: Record<string, unknown>;
+    timeout: number;
+  }): Promise<FeishuPingResponse>;
 };
 
 function setCachedProbeResult(
@@ -70,16 +79,17 @@ export async function probeFeishu(
   }
 
   try {
-    const client = createFeishuClient(creds);
-    // Use bot/v3/info API to get bot information
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK generic request method
-    const responseResult = await raceWithTimeoutAndAbort<FeishuBotInfoResponse>(
-      (client as any).request({
-        method: "GET",
-        url: "/open-apis/bot/v3/info",
-        data: {},
+    const client = createFeishuClient(creds) as FeishuRequestClient;
+    // Feishu-provided endpoint for OpenClaw, supported on both Feishu (CN)
+    // and Lark (international). No OAuth scopes required. Validates
+    // credentials and registers the app as an AI agent (智能体).
+    const responseResult = await raceWithTimeoutAndAbort<FeishuPingResponse>(
+      client.request({
+        method: "POST",
+        url: "/open-apis/bot/v1/openclaw_bot/ping",
+        data: { needBotInfo: true },
         timeout: timeoutMs,
-      }) as Promise<FeishuBotInfoResponse>,
+      }),
       {
         timeoutMs,
         abortSignal: options.abortSignal,
@@ -126,14 +136,14 @@ export async function probeFeishu(
       );
     }
 
-    const bot = response.bot || response.data?.bot;
+    const botInfo = response.data?.pingBotInfo;
     return setCachedProbeResult(
       cacheKey,
       {
         ok: true,
         appId: creds.appId,
-        botName: bot?.bot_name,
-        botOpenId: bot?.open_id,
+        botName: botInfo?.botName,
+        botOpenId: botInfo?.botID,
       },
       PROBE_SUCCESS_TTL_MS,
     );
@@ -143,7 +153,7 @@ export async function probeFeishu(
       {
         ok: false,
         appId: creds.appId,
-        error: err instanceof Error ? err.message : String(err),
+        error: formatErrorMessage(err),
       },
       PROBE_ERROR_TTL_MS,
     );

package/src/processing-claims.ts

@@ -0,0 +1,59 @@
+const EVENT_DEDUP_TTL_MS = 5 * 60 * 1000;
+const EVENT_MEMORY_MAX_SIZE = 2_000;
+
+const processingClaims = new Map<string, number>();
+
+function resolveEventDedupeKey(
+  namespace: string,
+  messageId: string | undefined | null,
+): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? `${namespace}:${trimmed}` : null;
+}
+
+function pruneProcessingClaims(now: number): void {
+  const cutoff = now - EVENT_DEDUP_TTL_MS;
+  for (const [key, seenAt] of processingClaims) {
+    if (seenAt < cutoff) {
+      processingClaims.delete(key);
+    }
+  }
+  while (processingClaims.size > EVENT_MEMORY_MAX_SIZE) {
+    const oldestKey = processingClaims.keys().next().value;
+    if (!oldestKey) {
+      return;
+    }
+    processingClaims.delete(oldestKey);
+  }
+}
+
+export function tryBeginFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): boolean {
+  const key = resolveEventDedupeKey(namespace, messageId);
+  if (!key) {
+    return true;
+  }
+  const now = Date.now();
+  pruneProcessingClaims(now);
+  if (processingClaims.has(key)) {
+    processingClaims.delete(key);
+    processingClaims.set(key, now);
+    pruneProcessingClaims(now);
+    return false;
+  }
+  processingClaims.set(key, now);
+  pruneProcessingClaims(now);
+  return true;
+}
+
+export function releaseFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): void {
+  const key = resolveEventDedupeKey(namespace, messageId);
+  if (key) {
+    processingClaims.delete(key);
+  }
+}

package/src/qr-terminal.ts

@@ -0,0 +1 @@
+export { renderQrTerminal } from "openclaw/plugin-sdk/media-runtime";

package/src/reactions.ts

@@ -1,8 +1,8 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
-import { resolveFeishuAccount } from "./accounts.js";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
 
-export type FeishuReaction = {
+type FeishuReaction = {
   reactionId: string;
   emojiType: string;
   operatorType: "app" | "user";
@@ -10,7 +10,7 @@ export type FeishuReaction = {
 };
 
 function resolveConfiguredFeishuClient(params: { cfg: ClawdbotConfig; accountId?: string }) {
-  const account = resolveFeishuAccount(params);
+  const account = resolveFeishuRuntimeAccount(params);
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
   }
@@ -121,33 +121,3 @@ export async function listReactionsFeishu(params: {
       item.operator_id?.open_id ?? item.operator_id?.user_id ?? item.operator_id?.union_id ?? "",
   }));
 }
-
-/**
- * Common Feishu emoji types for convenience.
- * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
- */
-export const FeishuEmoji = {
-  // Common reactions
-  THUMBSUP: "THUMBSUP",
-  THUMBSDOWN: "THUMBSDOWN",
-  HEART: "HEART",
-  SMILE: "SMILE",
-  GRINNING: "GRINNING",
-  LAUGHING: "LAUGHING",
-  CRY: "CRY",
-  ANGRY: "ANGRY",
-  SURPRISED: "SURPRISED",
-  THINKING: "THINKING",
-  CLAP: "CLAP",
-  OK: "OK",
-  FIST: "FIST",
-  PRAY: "PRAY",
-  FIRE: "FIRE",
-  PARTY: "PARTY",
-  CHECK: "CHECK",
-  CROSS: "CROSS",
-  QUESTION: "QUESTION",
-  EXCLAMATION: "EXCLAMATION",
-} as const;
-
-export type FeishuEmojiType = (typeof FeishuEmoji)[keyof typeof FeishuEmoji];

package/src/reasoning-preview.test.ts

@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveFeishuReasoningPreviewEnabled } from "./reasoning-preview.js";
+
+const { loadSessionStoreMock } = vi.hoisted(() => ({
+  loadSessionStoreMock: vi.fn(),
+}));
+
+vi.mock("./bot-runtime-api.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("./bot-runtime-api.js")>("./bot-runtime-api.js");
+  return {
+    ...actual,
+    loadSessionStore: loadSessionStoreMock,
+  };
+});
+
+describe("resolveFeishuReasoningPreviewEnabled", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("enables previews only for stream reasoning sessions", () => {
+    loadSessionStoreMock.mockReturnValue({
+      "agent:main:feishu:dm:ou_sender_1": { reasoningLevel: "stream" },
+      "agent:main:feishu:dm:ou_sender_2": { reasoningLevel: "on" },
+    });
+
+    expect(
+      resolveFeishuReasoningPreviewEnabled({
+        storePath: "/tmp/feishu-sessions.json",
+        sessionKey: "agent:main:feishu:dm:ou_sender_1",
+      }),
+    ).toBe(true);
+    expect(
+      resolveFeishuReasoningPreviewEnabled({
+        storePath: "/tmp/feishu-sessions.json",
+        sessionKey: "agent:main:feishu:dm:ou_sender_2",
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false for missing sessions or load failures", () => {
+    loadSessionStoreMock.mockImplementationOnce(() => {
+      throw new Error("disk unavailable");
+    });
+
+    expect(
+      resolveFeishuReasoningPreviewEnabled({
+        storePath: "/tmp/feishu-sessions.json",
+        sessionKey: "agent:main:feishu:dm:ou_sender_1",
+      }),
+    ).toBe(false);
+    expect(
+      resolveFeishuReasoningPreviewEnabled({
+        storePath: "/tmp/feishu-sessions.json",
+      }),
+    ).toBe(false);
+  });
+});

package/src/reasoning-preview.ts

@@ -0,0 +1,20 @@
+import { loadSessionStore, resolveSessionStoreEntry } from "./bot-runtime-api.js";
+
+export function resolveFeishuReasoningPreviewEnabled(params: {
+  storePath: string;
+  sessionKey?: string;
+}): boolean {
+  if (!params.sessionKey) {
+    return false;
+  }
+
+  try {
+    const store = loadSessionStore(params.storePath, { skipCache: true });
+    return (
+      resolveSessionStoreEntry({ store, sessionKey: params.sessionKey }).existing
+        ?.reasoningLevel === "stream"
+    );
+  } catch {
+    return false;
+  }
+}

package/src/reply-dispatcher-runtime-api.ts

@@ -0,0 +1,7 @@
+export {
+  createReplyPrefixContext,
+  type ClawdbotConfig,
+  type OutboundIdentity,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";