@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/comment-shared.ts

@@ -0,0 +1,406 @@
+import {
+  isRecord as sharedIsRecord,
+  normalizeOptionalString,
+  readStringValue,
+} from "openclaw/plugin-sdk/text-runtime";
+import { FEISHU_COMMENT_FILE_TYPES, type CommentFileType } from "./comment-target.js";
+
+export function encodeQuery(params: Record<string, string | undefined>): string {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    const trimmed = value?.trim();
+    if (trimmed) {
+      query.set(key, trimmed);
+    }
+  }
+  const queryString = query.toString();
+  return queryString ? `?${queryString}` : "";
+}
+
+export const readString = readStringValue;
+
+export const normalizeString = normalizeOptionalString;
+
+export const isRecord = sharedIsRecord;
+
+export function formatFeishuApiError(
+  error: unknown,
+  options: {
+    includeConfigParams?: boolean;
+    includeNestedErrorLogId?: boolean;
+  } = {},
+): string {
+  if (!isRecord(error)) {
+    return typeof error === "string" ? error : JSON.stringify(error);
+  }
+  const config = isRecord(error.config) ? error.config : undefined;
+  const response = isRecord(error.response) ? error.response : undefined;
+  const responseData = isRecord(response?.data) ? response?.data : undefined;
+  const feishuLogId =
+    readString(responseData?.log_id) ||
+    (options.includeNestedErrorLogId
+      ? readString(isRecord(responseData?.error) ? responseData.error.log_id : undefined)
+      : undefined);
+  const nestedError = isRecord(responseData?.error) ? responseData.error : undefined;
+
+  return JSON.stringify({
+    message:
+      typeof error.message === "string"
+        ? error.message
+        : typeof error === "string"
+          ? error
+          : JSON.stringify(error),
+    code: readString(error.code),
+    method: readString(config?.method),
+    url: readString(config?.url),
+    ...(options.includeConfigParams ? { params: config?.params } : {}),
+    http_status: typeof response?.status === "number" ? response.status : undefined,
+    feishu_code:
+      typeof responseData?.code === "number" ? responseData.code : readString(responseData?.code),
+    feishu_msg: readString(responseData?.msg),
+    feishu_log_id: feishuLogId,
+    feishu_troubleshooter:
+      readString(responseData?.troubleshooter) || readString(nestedError?.troubleshooter),
+  });
+}
+
+function formatFeishuApiFailure(
+  error: unknown,
+  errorPrefix: string,
+  options: {
+    includeConfigParams?: boolean;
+    includeNestedErrorLogId?: boolean;
+  } = {},
+): string {
+  const details = formatFeishuApiError(error, options);
+  return `${errorPrefix}: ${details || "unknown error"}`;
+}
+
+export function createFeishuApiError(
+  error: unknown,
+  errorPrefix: string,
+  options: {
+    includeConfigParams?: boolean;
+    includeNestedErrorLogId?: boolean;
+  } = {},
+): Error {
+  return new Error(formatFeishuApiFailure(error, errorPrefix, options), { cause: error });
+}
+
+export async function requestFeishuApi<T>(
+  request: () => Promise<T>,
+  errorPrefix: string,
+  options: {
+    includeConfigParams?: boolean;
+    includeNestedErrorLogId?: boolean;
+  } = {},
+): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    throw createFeishuApiError(error, errorPrefix, options);
+  }
+}
+
+type ParsedCommentDocumentRef = {
+  fileType?: CommentFileType;
+  fileToken?: string;
+};
+
+type ParsedCommentMention = {
+  userId: string;
+  displayText: string;
+  isBotMention: boolean;
+};
+
+type ParsedCommentLinkedDocumentKind =
+  | CommentFileType
+  | "wiki"
+  | "mindnote"
+  | "bitable"
+  | "base"
+  | "unknown";
+
+type ParsedCommentResolvedDocumentType = Exclude<
+  ParsedCommentLinkedDocumentKind,
+  "wiki" | "unknown"
+>;
+
+export type ParsedCommentLinkedDocument = {
+  rawUrl: string;
+  urlKind: ParsedCommentLinkedDocumentKind;
+  wikiNodeToken?: string;
+  resolvedObjType?: ParsedCommentResolvedDocumentType;
+  resolvedObjToken?: string;
+  isCurrentDocument?: boolean;
+};
+
+export type ParsedCommentContent = {
+  plainText?: string;
+  semanticText?: string;
+  mentions: ParsedCommentMention[];
+  linkedDocuments: ParsedCommentLinkedDocument[];
+  botMentioned: boolean;
+};
+
+function readDocsLinkUrl(element: Record<string, unknown>): string | undefined {
+  const docsLink = isRecord(element.docs_link) ? element.docs_link : undefined;
+  return (
+    normalizeString(docsLink?.url) ||
+    normalizeString(docsLink?.link) ||
+    normalizeString(element.url) ||
+    normalizeString(element.link) ||
+    undefined
+  );
+}
+
+function readMentionUserId(element: Record<string, unknown>): string | undefined {
+  const mention = isRecord(element.mention) ? element.mention : undefined;
+  const person = isRecord(element.person) ? element.person : undefined;
+  return (
+    normalizeString(person?.user_id) ||
+    normalizeString(mention?.user_id) ||
+    normalizeString(mention?.open_id) ||
+    normalizeString(element.mention_user) ||
+    normalizeString(element.user_id) ||
+    undefined
+  );
+}
+
+function readMentionDisplayText(element: Record<string, unknown>, userId: string): string {
+  const mention = isRecord(element.mention) ? element.mention : undefined;
+  const mentionName =
+    normalizeString(mention?.name) ||
+    normalizeString(mention?.display_name) ||
+    normalizeString(element.name);
+  return mentionName ? `@${mentionName}` : `@${userId}`;
+}
+
+function normalizeCommentText(parts: string[]): string | undefined {
+  const text = parts.join("").trim();
+  return text || undefined;
+}
+
+function normalizeCommentSemanticText(parts: string[]): string | undefined {
+  const text = parts.join("").replace(/\s+/g, " ").trim();
+  return text || undefined;
+}
+
+function readElementTextPreservingWhitespace(element: Record<string, unknown>): string | undefined {
+  return (
+    (isRecord(element.text_run)
+      ? readString(element.text_run.content) || readString(element.text_run.text)
+      : undefined) ||
+    readString(element.text) ||
+    readString(element.content) ||
+    readString(element.name) ||
+    undefined
+  );
+}
+
+const FEISHU_LINK_TOKEN_MIN_LENGTH = 22;
+const FEISHU_LINK_TOKEN_MAX_LENGTH = 28;
+const COMMENT_LINK_KIND_ALIASES = new Map<string, ParsedCommentResolvedDocumentType | "wiki">([
+  ["doc", "doc"],
+  ["docs", "doc"],
+  ["docx", "docx"],
+  ["sheet", "sheet"],
+  ["sheets", "sheet"],
+  ["slide", "slides"],
+  ["slides", "slides"],
+  ["file", "file"],
+  ["files", "file"],
+  ["wiki", "wiki"],
+  ["mindnote", "mindnote"],
+  ["mindnotes", "mindnote"],
+  ["bitable", "bitable"],
+  ["base", "base"],
+]);
+
+function isCommentFileType(
+  value: ParsedCommentResolvedDocumentType | "wiki" | undefined,
+): value is CommentFileType {
+  return (
+    typeof value === "string" && (FEISHU_COMMENT_FILE_TYPES as readonly string[]).includes(value)
+  );
+}
+
+function isReasonableFeishuLinkToken(token: string | undefined): token is string {
+  return (
+    typeof token === "string" &&
+    token.length >= FEISHU_LINK_TOKEN_MIN_LENGTH &&
+    token.length <= FEISHU_LINK_TOKEN_MAX_LENGTH
+  );
+}
+
+function parseCommentLinkedDocumentPath(pathname: string): {
+  urlKind: ParsedCommentResolvedDocumentType | "wiki";
+  token: string;
+} | null {
+  const segments = pathname
+    .split("/")
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+  const offset = segments[0]?.toLowerCase() === "space" ? 1 : 0;
+  const kind = COMMENT_LINK_KIND_ALIASES.get(segments[offset]?.toLowerCase() ?? "");
+  const token = normalizeString(segments[offset + 1]);
+  if (!kind || !isReasonableFeishuLinkToken(token)) {
+    return null;
+  }
+  return { urlKind: kind, token };
+}
+
+function hasResolvedLinkedDocumentReference(link: ParsedCommentLinkedDocument): boolean {
+  return (
+    link.urlKind !== "unknown" && (Boolean(link.resolvedObjToken) || Boolean(link.wikiNodeToken))
+  );
+}
+
+export function resolveCommentLinkedDocumentFromUrl(params: {
+  rawUrl: string;
+  currentDocument?: ParsedCommentDocumentRef;
+}): ParsedCommentLinkedDocument {
+  const link: ParsedCommentLinkedDocument = {
+    rawUrl: params.rawUrl,
+    urlKind: "unknown",
+  };
+  try {
+    const parsed = new URL(params.rawUrl);
+    const parsedPath = parseCommentLinkedDocumentPath(parsed.pathname);
+    if (!parsedPath) {
+      return link;
+    }
+    const { urlKind, token } = parsedPath;
+    link.urlKind = urlKind;
+    if (urlKind === "wiki") {
+      link.urlKind = "wiki";
+      link.wikiNodeToken = token;
+    } else {
+      link.resolvedObjType = urlKind;
+      link.resolvedObjToken = token;
+    }
+    if (
+      link.resolvedObjType &&
+      link.resolvedObjToken &&
+      isCommentFileType(link.resolvedObjType) &&
+      params.currentDocument?.fileType === link.resolvedObjType &&
+      params.currentDocument.fileToken === link.resolvedObjToken
+    ) {
+      link.isCurrentDocument = true;
+    } else if (
+      link.resolvedObjType &&
+      link.resolvedObjToken &&
+      isCommentFileType(link.resolvedObjType)
+    ) {
+      link.isCurrentDocument = false;
+    }
+  } catch {
+    return link;
+  }
+  return link;
+}
+
+export function parseCommentContentElements(params: {
+  elements?: unknown[];
+  botOpenIds?: Iterable<string | undefined>;
+  currentDocument?: ParsedCommentDocumentRef;
+}): ParsedCommentContent {
+  const elements = Array.isArray(params.elements) ? params.elements : [];
+  const plainTextParts: string[] = [];
+  const semanticTextParts: string[] = [];
+  const mentions: ParsedCommentMention[] = [];
+  const linkedDocuments: ParsedCommentLinkedDocument[] = [];
+  const botIds = new Set(
+    Array.from(params.botOpenIds ?? [])
+      .map((value) => normalizeString(value))
+      .filter((value): value is string => Boolean(value)),
+  );
+  const linkedDocumentKeys = new Set<string>();
+  let botMentioned = false;
+
+  for (const rawElement of elements) {
+    if (!isRecord(rawElement)) {
+      continue;
+    }
+    const element = rawElement;
+    const type = normalizeString(element.type);
+    const text =
+      (type === "text_run" ? readElementTextPreservingWhitespace(element) : undefined) ||
+      (type === "text" ? readElementTextPreservingWhitespace(element) : undefined) ||
+      (type === "docs_link" || type === "link" ? readDocsLinkUrl(element) : undefined) ||
+      (type === "mention" || type === "mention_user" || type === "person"
+        ? (() => {
+            const userId = readMentionUserId(element);
+            return userId ? readMentionDisplayText(element, userId) : undefined;
+          })()
+        : undefined) ||
+      readElementTextPreservingWhitespace(element) ||
+      undefined;
+
+    if (type === "mention" || type === "mention_user" || type === "person") {
+      const userId = readMentionUserId(element);
+      if (userId) {
+        const displayText = readMentionDisplayText(element, userId);
+        const isBotMention = botIds.has(userId);
+        mentions.push({ userId, displayText, isBotMention });
+        plainTextParts.push(displayText);
+        if (!isBotMention) {
+          semanticTextParts.push(displayText);
+        } else {
+          botMentioned = true;
+        }
+        continue;
+      }
+    }
+
+    if (type === "docs_link" || type === "link") {
+      const rawUrl = readDocsLinkUrl(element);
+      if (rawUrl) {
+        plainTextParts.push(rawUrl);
+        semanticTextParts.push(rawUrl);
+        const linkedDocument = resolveCommentLinkedDocumentFromUrl({
+          rawUrl,
+          currentDocument: params.currentDocument,
+        });
+        if (hasResolvedLinkedDocumentReference(linkedDocument)) {
+          const key = [
+            linkedDocument.rawUrl,
+            linkedDocument.urlKind,
+            linkedDocument.resolvedObjType,
+            linkedDocument.resolvedObjToken,
+            linkedDocument.wikiNodeToken,
+          ].join(":");
+          if (!linkedDocumentKeys.has(key)) {
+            linkedDocumentKeys.add(key);
+            linkedDocuments.push(linkedDocument);
+          }
+        }
+        continue;
+      }
+    }
+
+    if (text) {
+      plainTextParts.push(text);
+      semanticTextParts.push(text);
+    }
+  }
+
+  return {
+    plainText: normalizeCommentText(plainTextParts),
+    semanticText: normalizeCommentSemanticText(semanticTextParts),
+    mentions,
+    linkedDocuments,
+    botMentioned,
+  };
+}
+
+export function extractReplyText(
+  reply: { content?: { elements?: unknown[] } } | undefined,
+): string | undefined {
+  if (!reply || !isRecord(reply.content)) {
+    return undefined;
+  }
+  return parseCommentContentElements({
+    elements: Array.isArray(reply.content.elements) ? reply.content.elements : [],
+  }).plainText;
+}

package/src/comment-target.ts

@@ -0,0 +1,44 @@
+export const FEISHU_COMMENT_FILE_TYPES = ["doc", "docx", "file", "sheet", "slides"] as const;
+
+export type CommentFileType = (typeof FEISHU_COMMENT_FILE_TYPES)[number];
+
+export function normalizeCommentFileType(value: unknown): CommentFileType | undefined {
+  return typeof value === "string" &&
+    (FEISHU_COMMENT_FILE_TYPES as readonly string[]).includes(value)
+    ? (value as CommentFileType)
+    : undefined;
+}
+
+type FeishuCommentTarget = {
+  fileType: CommentFileType;
+  fileToken: string;
+  commentId: string;
+};
+
+export function buildFeishuCommentTarget(params: FeishuCommentTarget): string {
+  return `comment:${params.fileType}:${params.fileToken}:${params.commentId}`;
+}
+
+export function parseFeishuCommentTarget(
+  raw: string | undefined | null,
+): FeishuCommentTarget | null {
+  const trimmed = raw?.trim();
+  if (!trimmed?.startsWith("comment:")) {
+    return null;
+  }
+  const parts = trimmed.split(":");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const fileType = normalizeCommentFileType(parts[1]);
+  const fileToken = parts[2]?.trim();
+  const commentId = parts[3]?.trim();
+  if (!fileType || !fileToken || !commentId) {
+    return null;
+  }
+  return {
+    fileType,
+    fileToken,
+    commentId,
+  };
+}

package/src/config-schema.test.ts

@@ -19,7 +19,10 @@ describe("FeishuConfigSchema webhook validation", () => {
     expect(result.webhookPath).toBe("/feishu/events");
     expect(result.dmPolicy).toBe("pairing");
     expect(result.groupPolicy).toBe("allowlist");
-    expect(result.requireMention).toBe(true);
+    // requireMention has no schema-level default now — it is resolved at runtime
+    // through shared channel group-policy resolution, with an open-group override
+    // that defaults to false only when requireMention is otherwise unset.
+    expect(result.requireMention).toBeUndefined();
   });
 
   it("does not force top-level policy defaults into account config", () => {
@@ -217,6 +220,65 @@ describe("FeishuConfigSchema optimization flags", () => {
   });
 });
 
+describe("FeishuConfigSchema TTS overrides", () => {
+  it("accepts top-level and account-level TTS overrides", () => {
+    const result = FeishuConfigSchema.parse({
+      tts: {
+        auto: "always",
+        provider: "openai",
+        providers: {
+          openai: {
+            voice: "alloy",
+          },
+        },
+      },
+      accounts: {
+        english: {
+          tts: {
+            providers: {
+              openai: {
+                voice: "shimmer",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(result.tts).toMatchObject({
+      auto: "always",
+      provider: "openai",
+    });
+    expect(result.accounts?.english?.tts).toMatchObject({
+      providers: {
+        openai: {
+          voice: "shimmer",
+        },
+      },
+    });
+  });
+});
+
+describe("FeishuConfigSchema actions", () => {
+  it("accepts top-level reactions action gate", () => {
+    const result = FeishuConfigSchema.parse({
+      actions: { reactions: false },
+    });
+    expect(result.actions?.reactions).toBe(false);
+  });
+
+  it("accepts account-level reactions action gate", () => {
+    const result = FeishuConfigSchema.parse({
+      accounts: {
+        main: {
+          actions: { reactions: false },
+        },
+      },
+    });
+    expect(result.accounts?.main?.actions?.reactions).toBe(false);
+  });
+});
+
 describe("FeishuConfigSchema defaultAccount", () => {
   it("accepts defaultAccount when it matches an account key", () => {
     const result = FeishuConfigSchema.safeParse({

package/src/config-schema.ts

@@ -1,8 +1,15 @@
 import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { z } from "zod";
+import { z } from "openclaw/plugin-sdk/zod";
 export { z };
 import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
 
+const ChannelActionsSchema = z
+  .object({
+    reactions: z.boolean().optional(),
+  })
+  .strict()
+  .optional();
+
 const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
 const GroupPolicySchema = z.union([
   z.enum(["open", "allowlist", "disabled"]),
@@ -13,6 +20,23 @@ const FeishuDomainSchema = z.union([
   z.string().url().startsWith("https://"),
 ]);
 const FeishuConnectionModeSchema = z.enum(["websocket", "webhook"]);
+const TtsOverrideSchema = z
+  .object({
+    auto: z.enum(["off", "always", "inbound", "tagged"]).optional(),
+    enabled: z.boolean().optional(),
+    mode: z.enum(["final", "all"]).optional(),
+    provider: z.string().optional(),
+    persona: z.string().optional(),
+    personas: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    summaryModel: z.string().optional(),
+    modelOverrides: z.record(z.string(), z.unknown()).optional(),
+    providers: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    prefsPath: z.string().optional(),
+    maxTextLength: z.number().int().min(1).optional(),
+    timeoutMs: z.number().int().min(1000).max(120000).optional(),
+  })
+  .strict()
+  .optional();
 
 const ToolPolicySchema = z
   .object({
@@ -115,8 +139,9 @@ const GroupSessionScopeSchema = z
  * - "disabled" (default): All messages in a group share one session
  * - "enabled": Messages in different topics get separate sessions
  *
- * Topic routing uses `root_id` when present to keep session continuity and
- * falls back to `thread_id` when `root_id` is unavailable.
+ * Topic routing uses Feishu topic-group `thread_id` when the event identifies a
+ * native topic group, and keeps `root_id` precedence for normal groups so
+ * reply-created threads stay on the initiating message session.
  */
 const TopicSessionModeSchema = z.enum(["disabled", "enabled"]).optional();
 const ReactionNotificationModeSchema = z.enum(["off", "own", "all"]).optional();
@@ -170,10 +195,12 @@ const FeishuSharedConfigShape = {
   renderMode: RenderModeSchema,
   streaming: StreamingModeSchema,
   tools: FeishuToolsConfigSchema,
+  actions: ChannelActionsSchema,
   replyInThread: ReplyInThreadSchema,
   reactionNotifications: ReactionNotificationModeSchema,
   typingIndicator: z.boolean().optional(),
   resolveSenderNames: z.boolean().optional(),
+  tts: TtsOverrideSchema,
 };
 
 /**
@@ -213,7 +240,7 @@ export const FeishuConfigSchema = z
     dmPolicy: DmPolicySchema.optional().default("pairing"),
     reactionNotifications: ReactionNotificationModeSchema.optional().default("own"),
     groupPolicy: GroupPolicySchema.optional().default("allowlist"),
-    requireMention: z.boolean().optional().default(true),
+    requireMention: z.boolean().optional(),
     groupSessionScope: GroupSessionScopeSchema,
     topicSessionMode: TopicSessionModeSchema,
     // Dynamic agent creation for DM users

package/src/conversation-id.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { buildFeishuModelOverrideParentCandidates } from "./conversation-id.js";
+
+describe("buildFeishuModelOverrideParentCandidates", () => {
+  it("returns topic and chat fallback ids for sender-scoped topics", () => {
+    expect(
+      buildFeishuModelOverrideParentCandidates(
+        "oc_group_chat:Topic:om_topic_root:Sender:ou_topic_user",
+      ),
+    ).toEqual(["oc_group_chat:topic:om_topic_root", "oc_group_chat"]);
+  });
+
+  it("returns chat fallback ids for sender-scoped chats", () => {
+    expect(buildFeishuModelOverrideParentCandidates("oc_group_chat:sender:ou_topic_user")).toEqual([
+      "oc_group_chat",
+    ]);
+  });
+});