@openclaw/feishu 2026.3.12 → 2026.5.1-beta.1

package/src/conversation-id.ts

@@ -0,0 +1,199 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export type FeishuGroupSessionScope =
+  | "group"
+  | "group_sender"
+  | "group_topic"
+  | "group_topic_sender";
+
+function normalizeText(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function buildFeishuConversationId(params: {
+  chatId: string;
+  scope: FeishuGroupSessionScope;
+  senderOpenId?: string;
+  topicId?: string;
+}): string {
+  const chatId = normalizeText(params.chatId) ?? "unknown";
+  const senderOpenId = normalizeText(params.senderOpenId);
+  const topicId = normalizeText(params.topicId);
+
+  switch (params.scope) {
+    case "group_sender":
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group_topic":
+      return topicId ? `${chatId}:topic:${topicId}` : chatId;
+    case "group_topic_sender":
+      if (topicId && senderOpenId) {
+        return `${chatId}:topic:${topicId}:sender:${senderOpenId}`;
+      }
+      if (topicId) {
+        return `${chatId}:topic:${topicId}`;
+      }
+      return senderOpenId ? `${chatId}:sender:${senderOpenId}` : chatId;
+    case "group":
+    default:
+      return chatId;
+  }
+}
+
+export function parseFeishuTargetId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["chat:", "group:", "channel:", "user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  return withoutProvider;
+}
+
+export function parseFeishuDirectConversationId(raw: unknown): string | undefined {
+  const target = normalizeText(raw);
+  if (!target) {
+    return undefined;
+  }
+  const withoutProvider = target.replace(/^(feishu|lark):/i, "").trim();
+  if (!withoutProvider) {
+    return undefined;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(withoutProvider);
+  for (const prefix of ["user:", "dm:", "open_id:"]) {
+    if (lowered.startsWith(prefix)) {
+      return normalizeText(withoutProvider.slice(prefix.length));
+    }
+  }
+  const id = parseFeishuTargetId(target);
+  if (!id) {
+    return undefined;
+  }
+  if (id.startsWith("ou_") || id.startsWith("on_")) {
+    return id;
+  }
+  return undefined;
+}
+
+export function parseFeishuConversationId(params: {
+  conversationId: string;
+  parentConversationId?: string;
+}): {
+  canonicalConversationId: string;
+  chatId: string;
+  topicId?: string;
+  senderOpenId?: string;
+  scope: FeishuGroupSessionScope;
+} | null {
+  const conversationId = normalizeText(params.conversationId);
+  const parentConversationId = normalizeText(params.parentConversationId);
+  if (!conversationId) {
+    return null;
+  }
+
+  const topicSenderMatch = conversationId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const [, chatId, topicId, senderOpenId] = topicSenderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic_sender",
+        topicId,
+        senderOpenId,
+      }),
+      chatId,
+      topicId,
+      senderOpenId,
+      scope: "group_topic_sender",
+    };
+  }
+
+  const topicMatch = conversationId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const [, chatId, topicId] = topicMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_topic",
+        topicId,
+      }),
+      chatId,
+      topicId,
+      scope: "group_topic",
+    };
+  }
+
+  const senderMatch = conversationId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const [, chatId, senderOpenId] = senderMatch;
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId,
+        scope: "group_sender",
+        senderOpenId,
+      }),
+      chatId,
+      senderOpenId,
+      scope: "group_sender",
+    };
+  }
+
+  if (parentConversationId) {
+    return {
+      canonicalConversationId: buildFeishuConversationId({
+        chatId: parentConversationId,
+        scope: "group_topic",
+        topicId: conversationId,
+      }),
+      chatId: parentConversationId,
+      topicId: conversationId,
+      scope: "group_topic",
+    };
+  }
+
+  return {
+    canonicalConversationId: conversationId,
+    chatId: conversationId,
+    scope: "group",
+  };
+}
+
+export function buildFeishuModelOverrideParentCandidates(
+  parentConversationId?: string | null,
+): string[] {
+  const rawId = normalizeText(parentConversationId);
+  if (!rawId) {
+    return [];
+  }
+  const topicSenderMatch = rawId.match(/^(.+):topic:([^:]+):sender:([^:]+)$/i);
+  if (topicSenderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicSenderMatch[1]);
+    const topicId = normalizeLowercaseStringOrEmpty(topicSenderMatch[2]);
+    if (chatId && topicId) {
+      return [`${chatId}:topic:${topicId}`, chatId];
+    }
+    return [];
+  }
+  const topicMatch = rawId.match(/^(.+):topic:([^:]+)$/i);
+  if (topicMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(topicMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  const senderMatch = rawId.match(/^(.+):sender:([^:]+)$/i);
+  if (senderMatch) {
+    const chatId = normalizeLowercaseStringOrEmpty(senderMatch[1]);
+    return chatId ? [chatId] : [];
+  }
+  return [];
+}

package/src/dedup-runtime-api.ts

@@ -0,0 +1 @@
+export { createPersistentDedupe } from "openclaw/plugin-sdk/persistent-dedupe";

package/src/dedup.ts

@@ -1,21 +1,18 @@
 import os from "node:os";
 import path from "node:path";
+import { createPersistentDedupe } from "./dedup-runtime-api.js";
 import {
-  createDedupeCache,
-  createPersistentDedupe,
-  readJsonFileWithFallback,
-} from "openclaw/plugin-sdk/feishu";
+  releaseFeishuMessageProcessing,
+  tryBeginFeishuMessageProcessing,
+} from "./processing-claims.js";
 
 // Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
 const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
 const MEMORY_MAX_SIZE = 1_000;
 const FILE_MAX_ENTRIES = 10_000;
-type PersistentDedupeData = Record<string, number>;
-
-const memoryDedupe = createDedupeCache({ ttlMs: DEDUP_TTL_MS, maxSize: MEMORY_MAX_SIZE });
 
 function resolveStateDirFromEnv(env: NodeJS.ProcessEnv = process.env): string {
-  const stateOverride = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  const stateOverride = env.OPENCLAW_STATE_DIR?.trim();
   if (stateOverride) {
     return stateOverride;
   }
@@ -37,20 +34,75 @@ const persistentDedupe = createPersistentDedupe({
   resolveFilePath: resolveNamespaceFilePath,
 });
 
-/**
- * Synchronous dedup — memory only.
- * Kept for backward compatibility; prefer {@link tryRecordMessagePersistent}.
- */
-export function tryRecordMessage(messageId: string): boolean {
-  return !memoryDedupe.check(messageId);
+function normalizeMessageId(messageId: string | undefined | null): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? trimmed : null;
 }
 
-export function hasRecordedMessage(messageId: string): boolean {
-  const trimmed = messageId.trim();
-  if (!trimmed) {
+export { releaseFeishuMessageProcessing, tryBeginFeishuMessageProcessing };
+
+export async function claimUnprocessedFeishuMessage(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+}): Promise<"claimed" | "duplicate" | "inflight" | "invalid"> {
+  const { messageId, namespace = "global", log } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return "invalid";
+  }
+  if (await hasProcessedFeishuMessage(normalizedMessageId, namespace, log)) {
+    return "duplicate";
+  }
+  if (!tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
+    return "inflight";
+  }
+  return "claimed";
+}
+
+export async function finalizeFeishuMessageProcessing(params: {
+  messageId: string | undefined | null;
+  namespace?: string;
+  log?: (...args: unknown[]) => void;
+  claimHeld?: boolean;
+}): Promise<boolean> {
+  const { messageId, namespace = "global", log, claimHeld = false } = params;
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  if (!claimHeld && !tryBeginFeishuMessageProcessing(normalizedMessageId, namespace)) {
     return false;
   }
-  return memoryDedupe.peek(trimmed);
+  if (!(await tryRecordMessagePersistent(normalizedMessageId, namespace, log))) {
+    releaseFeishuMessageProcessing(normalizedMessageId, namespace);
+    return false;
+  }
+  return true;
+}
+
+export async function recordProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  return await tryRecordMessagePersistent(normalizedMessageId, namespace, log);
+}
+
+export async function hasProcessedFeishuMessage(
+  messageId: string | undefined | null,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const normalizedMessageId = normalizeMessageId(messageId);
+  if (!normalizedMessageId) {
+    return false;
+  }
+  return hasRecordedMessagePersistent(normalizedMessageId, namespace, log);
 }
 
 export async function tryRecordMessagePersistent(
@@ -71,23 +123,12 @@ export async function hasRecordedMessagePersistent(
   namespace = "global",
   log?: (...args: unknown[]) => void,
 ): Promise<boolean> {
-  const trimmed = messageId.trim();
-  if (!trimmed) {
-    return false;
-  }
-  const now = Date.now();
-  const filePath = resolveNamespaceFilePath(namespace);
-  try {
-    const { value } = await readJsonFileWithFallback<PersistentDedupeData>(filePath, {});
-    const seenAt = value[trimmed];
-    if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) {
-      return false;
-    }
-    return DEDUP_TTL_MS <= 0 || now - seenAt < DEDUP_TTL_MS;
-  } catch (error) {
-    log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
-    return false;
-  }
+  return persistentDedupe.hasRecent(messageId, {
+    namespace,
+    onDiskError: (error) => {
+      log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    },
+  });
 }
 
 export async function warmupDedupFromDisk(

package/src/directory.static.ts

@@ -0,0 +1,61 @@
+import {
+  listDirectoryGroupEntriesFromMapKeysAndAllowFrom,
+  listDirectoryUserEntriesFromAllowFromAndMapKeys,
+} from "openclaw/plugin-sdk/directory-runtime";
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuAccount } from "./accounts.js";
+import { normalizeFeishuTarget } from "./targets.js";
+
+export type FeishuDirectoryPeer = {
+  kind: "user";
+  id: string;
+  name?: string;
+};
+
+export type FeishuDirectoryGroup = {
+  kind: "group";
+  id: string;
+  name?: string;
+};
+
+function toFeishuDirectoryPeers(ids: string[]): FeishuDirectoryPeer[] {
+  return ids.map((id) => ({ kind: "user", id }));
+}
+
+function toFeishuDirectoryGroups(ids: string[]): FeishuDirectoryGroup[] {
+  return ids.map((id) => ({ kind: "group", id }));
+}
+
+export async function listFeishuDirectoryPeers(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryPeer[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  const entries = listDirectoryUserEntriesFromAllowFromAndMapKeys({
+    allowFrom: account.config.allowFrom,
+    map: account.config.dms,
+    query: params.query,
+    limit: params.limit,
+    normalizeAllowFromId: (entry) => normalizeFeishuTarget(entry) ?? entry,
+    normalizeMapKeyId: (entry) => normalizeFeishuTarget(entry) ?? entry,
+  });
+  return toFeishuDirectoryPeers(entries.map((entry) => entry.id));
+}
+
+export async function listFeishuDirectoryGroups(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryGroup[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  const entries = listDirectoryGroupEntriesFromMapKeysAndAllowFrom({
+    groups: account.config.groups,
+    allowFrom: account.config.groupAllowFrom,
+    query: params.query,
+    limit: params.limit,
+  });
+  return toFeishuDirectoryGroups(entries.map((entry) => entry.id));
+}

package/src/directory.test.ts

@@ -1,40 +1,139 @@
-import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
-import { describe, expect, it, vi } from "vitest";
-
-vi.mock("./accounts.js", () => ({
-  resolveFeishuAccount: vi.fn(() => ({
-    configured: false,
-    config: {
-      allowFrom: ["user:alice", "user:bob"],
-      dms: {
-        "user:carla": {},
-      },
-      groups: {
-        "chat-1": {},
+import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClawdbotConfig } from "../runtime-api.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+const {
+  listFeishuDirectoryGroups,
+  listFeishuDirectoryGroupsLive,
+  listFeishuDirectoryPeers,
+  listFeishuDirectoryPeersLive,
+} = await importFreshModule<typeof import("./directory.js")>(
+  import.meta.url,
+  "./directory.js?directory-test",
+);
+
+function makeStaticCfg(): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        allowFrom: ["user:alice", "user:bob"],
+        dms: {
+          "user:carla": {},
+        },
+        groups: {
+          "chat-1": {},
+        },
+        groupAllowFrom: ["chat-2"],
       },
-      groupAllowFrom: ["chat-2"],
     },
-  })),
-}));
+  } as ClawdbotConfig;
+}
 
-import { listFeishuDirectoryGroups, listFeishuDirectoryPeers } from "./directory.js";
+function makeConfiguredCfg(): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        ...makeStaticCfg().channels?.feishu,
+        appId: "cli_test_app_id",
+        appSecret: "cli_test_app_secret",
+      },
+    },
+  } as ClawdbotConfig;
+}
 
 describe("feishu directory (config-backed)", () => {
-  const cfg = {} as ClawdbotConfig;
+  beforeEach(() => {
+    createFeishuClientMock.mockReset();
+  });
 
   it("merges allowFrom + dms into peer entries", async () => {
-    const peers = await listFeishuDirectoryPeers({ cfg, query: "a" });
+    const peers = await listFeishuDirectoryPeers({ cfg: makeStaticCfg(), query: "a" });
     expect(peers).toEqual([
       { kind: "user", id: "alice" },
       { kind: "user", id: "carla" },
     ]);
   });
 
+  it("normalizes spaced provider-prefixed peer entries", async () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          allowFrom: [" feishu:user:ou_alice "],
+          dms: {
+            " lark:dm:ou_carla ": {},
+          },
+          groups: {},
+          groupAllowFrom: [],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const peers = await listFeishuDirectoryPeers({ cfg });
+    expect(peers).toEqual([
+      { kind: "user", id: "ou_alice" },
+      { kind: "user", id: "ou_carla" },
+    ]);
+  });
+
   it("merges groups map + groupAllowFrom into group entries", async () => {
-    const groups = await listFeishuDirectoryGroups({ cfg });
+    const groups = await listFeishuDirectoryGroups({ cfg: makeStaticCfg() });
     expect(groups).toEqual([
       { kind: "group", id: "chat-1" },
       { kind: "group", id: "chat-2" },
     ]);
   });
+
+  it("falls back to static peers on live lookup failure by default", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    const peers = await listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), query: "a" });
+    expect(peers).toEqual([
+      { kind: "user", id: "alice" },
+      { kind: "user", id: "carla" },
+    ]);
+  });
+
+  it("surfaces live peer lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      contact: {
+        user: {
+          list: vi.fn(async () => {
+            throw new Error("token expired");
+          }),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryPeersLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("token expired");
+  });
+
+  it("surfaces live group lookup failures when fallback is disabled", async () => {
+    createFeishuClientMock.mockReturnValueOnce({
+      im: {
+        chat: {
+          list: vi.fn(async () => ({ code: 999, msg: "forbidden" })),
+        },
+      },
+    });
+
+    await expect(
+      listFeishuDirectoryGroupsLive({ cfg: makeConfiguredCfg(), fallbackToStatic: false }),
+    ).rejects.toThrow("forbidden");
+  });
 });