@openclaw/feishu 2026.2.2 → 2026.2.9

package/src/config-schema.ts

@@ -1,46 +1,172 @@
-import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
+export { z };
 
-const allowFromEntry = z.union([z.string(), z.number()]);
-const toolsBySenderSchema = z.record(z.string(), ToolPolicySchema).optional();
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+const FeishuDomainSchema = z.union([
+  z.enum(["feishu", "lark"]),
+  z.string().url().startsWith("https://"),
+]);
+const FeishuConnectionModeSchema = z.enum(["websocket", "webhook"]);
 
-const FeishuGroupSchema = z
+const ToolPolicySchema = z
+  .object({
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+  })
+  .strict()
+  .optional();
+
+const DmConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+const MarkdownConfigSchema = z
+  .object({
+    mode: z.enum(["native", "escape", "strip"]).optional(),
+    tableMode: z.enum(["native", "ascii", "simple"]).optional(),
+  })
+  .strict()
+  .optional();
+
+// Message render mode: auto (default) = detect markdown, raw = plain text, card = always card
+const RenderModeSchema = z.enum(["auto", "raw", "card"]).optional();
+
+const BlockStreamingCoalesceSchema = z
   .object({
     enabled: z.boolean().optional(),
+    minDelayMs: z.number().int().positive().optional(),
+    maxDelayMs: z.number().int().positive().optional(),
+  })
+  .strict()
+  .optional();
+
+const ChannelHeartbeatVisibilitySchema = z
+  .object({
+    visibility: z.enum(["visible", "hidden"]).optional(),
+    intervalMs: z.number().int().positive().optional(),
+  })
+  .strict()
+  .optional();
+
+/**
+ * Feishu tools configuration.
+ * Controls which tool categories are enabled.
+ *
+ * Dependencies:
+ * - wiki requires doc (wiki content is edited via doc tools)
+ * - perm can work independently but is typically used with drive
+ */
+const FeishuToolsConfigSchema = z
+  .object({
+    doc: z.boolean().optional(), // Document operations (default: true)
+    wiki: z.boolean().optional(), // Knowledge base operations (default: true, requires doc)
+    drive: z.boolean().optional(), // Cloud storage operations (default: true)
+    perm: z.boolean().optional(), // Permission management (default: false, sensitive)
+    scopes: z.boolean().optional(), // App scopes diagnostic (default: true)
+  })
+  .strict()
+  .optional();
+
+export const FeishuGroupSchema = z
+  .object({
     requireMention: z.boolean().optional(),
-    allowFrom: z.array(allowFromEntry).optional(),
     tools: ToolPolicySchema,
-    toolsBySender: toolsBySenderSchema,
-    systemPrompt: z.string().optional(),
     skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
   })
   .strict();
 
-const FeishuAccountSchema = z
+/**
+ * Per-account configuration.
+ * All fields are optional - missing fields inherit from top-level config.
+ */
+export const FeishuAccountConfigSchema = z
   .object({
-    name: z.string().optional(),
     enabled: z.boolean().optional(),
+    name: z.string().optional(), // Display name for this account
     appId: z.string().optional(),
     appSecret: z.string().optional(),
-    appSecretFile: z.string().optional(),
-    domain: z.string().optional(),
-    botName: z.string().optional(),
+    encryptKey: z.string().optional(),
+    verificationToken: z.string().optional(),
+    domain: FeishuDomainSchema.optional(),
+    connectionMode: FeishuConnectionModeSchema.optional(),
+    webhookPath: z.string().optional(),
+    webhookPort: z.number().int().positive().optional(),
+    capabilities: z.array(z.string()).optional(),
     markdown: MarkdownConfigSchema,
-    dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
-    groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional(),
-    allowFrom: z.array(allowFromEntry).optional(),
-    groupAllowFrom: z.array(allowFromEntry).optional(),
-    historyLimit: z.number().optional(),
-    dmHistoryLimit: z.number().optional(),
-    textChunkLimit: z.number().optional(),
-    chunkMode: z.enum(["length", "newline"]).optional(),
-    blockStreaming: z.boolean().optional(),
-    streaming: z.boolean().optional(),
-    mediaMaxMb: z.number().optional(),
+    configWrites: z.boolean().optional(),
+    dmPolicy: DmPolicySchema.optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional(),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    requireMention: z.boolean().optional(),
     groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    chunkMode: z.enum(["length", "newline"]).optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema,
+    mediaMaxMb: z.number().positive().optional(),
+    heartbeat: ChannelHeartbeatVisibilitySchema,
+    renderMode: RenderModeSchema,
+    tools: FeishuToolsConfigSchema,
   })
   .strict();
 
-export const FeishuConfigSchema = FeishuAccountSchema.extend({
-  accounts: z.object({}).catchall(FeishuAccountSchema).optional(),
-});
+export const FeishuConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    // Top-level credentials (backward compatible for single-account mode)
+    appId: z.string().optional(),
+    appSecret: z.string().optional(),
+    encryptKey: z.string().optional(),
+    verificationToken: z.string().optional(),
+    domain: FeishuDomainSchema.optional().default("feishu"),
+    connectionMode: FeishuConnectionModeSchema.optional().default("websocket"),
+    webhookPath: z.string().optional().default("/feishu/events"),
+    webhookPort: z.number().int().positive().optional(),
+    capabilities: z.array(z.string()).optional(),
+    markdown: MarkdownConfigSchema,
+    configWrites: z.boolean().optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    requireMention: z.boolean().optional().default(true),
+    groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    chunkMode: z.enum(["length", "newline"]).optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema,
+    mediaMaxMb: z.number().positive().optional(),
+    heartbeat: ChannelHeartbeatVisibilitySchema,
+    renderMode: RenderModeSchema, // raw = plain text (default), card = interactive card with markdown
+    tools: FeishuToolsConfigSchema,
+    // Multi-account configuration
+    accounts: z.record(z.string(), FeishuAccountConfigSchema.optional()).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.dmPolicy === "open") {
+      const allowFrom = value.allowFrom ?? [];
+      const hasWildcard = allowFrom.some((entry) => String(entry).trim() === "*");
+      if (!hasWildcard) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["allowFrom"],
+          message:
+            'channels.feishu.dmPolicy="open" requires channels.feishu.allowFrom to include "*"',
+        });
+      }
+    }
+  });

package/src/directory.ts

@@ -0,0 +1,177 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { normalizeFeishuTarget } from "./targets.js";
+
+export type FeishuDirectoryPeer = {
+  kind: "user";
+  id: string;
+  name?: string;
+};
+
+export type FeishuDirectoryGroup = {
+  kind: "group";
+  id: string;
+  name?: string;
+};
+
+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 feishuCfg = account.config;
+  const q = params.query?.trim().toLowerCase() || "";
+  const ids = new Set<string>();
+
+  for (const entry of feishuCfg?.allowFrom ?? []) {
+    const trimmed = String(entry).trim();
+    if (trimmed && trimmed !== "*") {
+      ids.add(trimmed);
+    }
+  }
+
+  for (const userId of Object.keys(feishuCfg?.dms ?? {})) {
+    const trimmed = userId.trim();
+    if (trimmed) {
+      ids.add(trimmed);
+    }
+  }
+
+  return Array.from(ids)
+    .map((raw) => raw.trim())
+    .filter(Boolean)
+    .map((raw) => normalizeFeishuTarget(raw) ?? raw)
+    .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+    .slice(0, params.limit && params.limit > 0 ? params.limit : undefined)
+    .map((id) => ({ kind: "user" as const, 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 feishuCfg = account.config;
+  const q = params.query?.trim().toLowerCase() || "";
+  const ids = new Set<string>();
+
+  for (const groupId of Object.keys(feishuCfg?.groups ?? {})) {
+    const trimmed = groupId.trim();
+    if (trimmed && trimmed !== "*") {
+      ids.add(trimmed);
+    }
+  }
+
+  for (const entry of feishuCfg?.groupAllowFrom ?? []) {
+    const trimmed = String(entry).trim();
+    if (trimmed && trimmed !== "*") {
+      ids.add(trimmed);
+    }
+  }
+
+  return Array.from(ids)
+    .map((raw) => raw.trim())
+    .filter(Boolean)
+    .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+    .slice(0, params.limit && params.limit > 0 ? params.limit : undefined)
+    .map((id) => ({ kind: "group" as const, id }));
+}
+
+export async function listFeishuDirectoryPeersLive(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryPeer[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    return listFeishuDirectoryPeers(params);
+  }
+
+  try {
+    const client = createFeishuClient(account);
+    const peers: FeishuDirectoryPeer[] = [];
+    const limit = params.limit ?? 50;
+
+    const response = await client.contact.user.list({
+      params: {
+        page_size: Math.min(limit, 50),
+      },
+    });
+
+    if (response.code === 0 && response.data?.items) {
+      for (const user of response.data.items) {
+        if (user.open_id) {
+          const q = params.query?.trim().toLowerCase() || "";
+          const name = user.name || "";
+          if (!q || user.open_id.toLowerCase().includes(q) || name.toLowerCase().includes(q)) {
+            peers.push({
+              kind: "user",
+              id: user.open_id,
+              name: name || undefined,
+            });
+          }
+        }
+        if (peers.length >= limit) {
+          break;
+        }
+      }
+    }
+
+    return peers;
+  } catch {
+    return listFeishuDirectoryPeers(params);
+  }
+}
+
+export async function listFeishuDirectoryGroupsLive(params: {
+  cfg: ClawdbotConfig;
+  query?: string;
+  limit?: number;
+  accountId?: string;
+}): Promise<FeishuDirectoryGroup[]> {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    return listFeishuDirectoryGroups(params);
+  }
+
+  try {
+    const client = createFeishuClient(account);
+    const groups: FeishuDirectoryGroup[] = [];
+    const limit = params.limit ?? 50;
+
+    const response = await client.im.chat.list({
+      params: {
+        page_size: Math.min(limit, 100),
+      },
+    });
+
+    if (response.code === 0 && response.data?.items) {
+      for (const chat of response.data.items) {
+        if (chat.chat_id) {
+          const q = params.query?.trim().toLowerCase() || "";
+          const name = chat.name || "";
+          if (!q || chat.chat_id.toLowerCase().includes(q) || name.toLowerCase().includes(q)) {
+            groups.push({
+              kind: "group",
+              id: chat.chat_id,
+              name: name || undefined,
+            });
+          }
+        }
+        if (groups.length >= limit) {
+          break;
+        }
+      }
+    }
+
+    return groups;
+  } catch {
+    return listFeishuDirectoryGroups(params);
+  }
+}

package/src/doc-schema.ts

@@ -0,0 +1,47 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+export const FeishuDocSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("read"),
+    doc_token: Type.String({ description: "Document token (extract from URL /docx/XXX)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("write"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({
+      description: "Markdown content to write (replaces entire document content)",
+    }),
+  }),
+  Type.Object({
+    action: Type.Literal("append"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({ description: "Markdown content to append to end of document" }),
+  }),
+  Type.Object({
+    action: Type.Literal("create"),
+    title: Type.String({ description: "Document title" }),
+    folder_token: Type.Optional(Type.String({ description: "Target folder token (optional)" })),
+  }),
+  Type.Object({
+    action: Type.Literal("list_blocks"),
+    doc_token: Type.String({ description: "Document token" }),
+  }),
+  Type.Object({
+    action: Type.Literal("get_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("update_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
+    content: Type.String({ description: "New text content" }),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID" }),
+  }),
+]);
+
+export type FeishuDocParams = Static<typeof FeishuDocSchema>;