@colin3191/feishu 0.1.2

package/src/channel.ts

@@ -0,0 +1,224 @@
+import type { ChannelPlugin, ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, PAIRING_APPROVED_MESSAGE } from "clawdbot/plugin-sdk";
+import type { ResolvedFeishuAccount, FeishuConfig } from "./types.js";
+import { resolveFeishuAccount, resolveFeishuCredentials } from "./accounts.js";
+import { feishuOutbound } from "./outbound.js";
+import { probeFeishu } from "./probe.js";
+import { resolveFeishuGroupToolPolicy } from "./policy.js";
+import { normalizeFeishuTarget, looksLikeFeishuId, formatFeishuTarget } from "./targets.js";
+import { sendMessageFeishu } from "./send.js";
+import {
+  listFeishuDirectoryPeers,
+  listFeishuDirectoryGroups,
+  listFeishuDirectoryPeersLive,
+  listFeishuDirectoryGroupsLive,
+} from "./directory.js";
+import { feishuOnboardingAdapter } from "./onboarding.js";
+
+const meta = {
+  id: "feishu",
+  label: "Feishu",
+  selectionLabel: "Feishu/Lark (飞书)",
+  docsPath: "/channels/feishu",
+  docsLabel: "feishu",
+  blurb: "飞书/Lark enterprise messaging.",
+  aliases: ["lark"],
+  order: 70,
+} as const;
+
+export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
+  id: "feishu",
+  meta: {
+    ...meta,
+  },
+  pairing: {
+    idLabel: "feishuUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(feishu|user|open_id):/i, ""),
+    notifyApproval: async ({ cfg, id }) => {
+      await sendMessageFeishu({
+        cfg,
+        to: id,
+        text: PAIRING_APPROVED_MESSAGE,
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel"],
+    polls: false,
+    threads: true,
+    media: true,
+    reactions: true,
+    edit: true,
+    reply: true,
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- Feishu targeting: omit `target` to reply to the current conversation (auto-inferred). Explicit targets: `user:open_id` or `chat:chat_id`.",
+      "- Feishu supports interactive cards for rich messages.",
+    ],
+  },
+  groups: {
+    resolveToolPolicy: resolveFeishuGroupToolPolicy,
+  },
+  reload: { configPrefixes: ["channels.feishu"] },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        appId: { type: "string" },
+        appSecret: { type: "string" },
+        encryptKey: { type: "string" },
+        verificationToken: { type: "string" },
+        domain: { type: "string", enum: ["feishu", "lark"] },
+        connectionMode: { type: "string", enum: ["websocket", "webhook"] },
+        webhookPath: { type: "string" },
+        webhookPort: { type: "integer", minimum: 1 },
+        dmPolicy: { type: "string", enum: ["open", "pairing", "allowlist"] },
+        allowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+        groupPolicy: { type: "string", enum: ["open", "allowlist", "disabled"] },
+        groupAllowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+        requireMention: { type: "boolean" },
+        historyLimit: { type: "integer", minimum: 0 },
+        dmHistoryLimit: { type: "integer", minimum: 0 },
+        textChunkLimit: { type: "integer", minimum: 1 },
+        chunkMode: { type: "string", enum: ["length", "newline"] },
+        mediaMaxMb: { type: "number", minimum: 0 },
+        renderMode: { type: "string", enum: ["auto", "raw", "card"] },
+      },
+    },
+  },
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolveFeishuAccount({ cfg }),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, enabled }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        feishu: {
+          ...cfg.channels?.feishu,
+          enabled,
+        },
+      },
+    }),
+    deleteAccount: ({ cfg }) => {
+      const next = { ...cfg } as ClawdbotConfig;
+      const nextChannels = { ...cfg.channels };
+      delete (nextChannels as Record<string, unknown>).feishu;
+      if (Object.keys(nextChannels).length > 0) {
+        next.channels = nextChannels;
+      } else {
+        delete next.channels;
+      }
+      return next;
+    },
+    isConfigured: (_account, cfg) =>
+      Boolean(resolveFeishuCredentials(cfg.channels?.feishu as FeishuConfig | undefined)),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+    resolveAllowFrom: ({ cfg }) =>
+      (cfg.channels?.feishu as FeishuConfig | undefined)?.allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    collectWarnings: ({ cfg }) => {
+      const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+      const defaultGroupPolicy = (cfg.channels as Record<string, { groupPolicy?: string }> | undefined)?.defaults?.groupPolicy;
+      const groupPolicy = feishuCfg?.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- Feishu groups: groupPolicy="open" allows any member to trigger (mention-gated). Set channels.feishu.groupPolicy="allowlist" + channels.feishu.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+    applyAccountConfig: ({ cfg }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        feishu: {
+          ...cfg.channels?.feishu,
+          enabled: true,
+        },
+      },
+    }),
+  },
+  onboarding: feishuOnboardingAdapter,
+  messaging: {
+    normalizeTarget: normalizeFeishuTarget,
+    targetResolver: {
+      looksLikeId: looksLikeFeishuId,
+      hint: "<chatId|user:openId|chat:chatId>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, query, limit }) =>
+      listFeishuDirectoryPeers({ cfg, query, limit }),
+    listGroups: async ({ cfg, query, limit }) =>
+      listFeishuDirectoryGroups({ cfg, query, limit }),
+    listPeersLive: async ({ cfg, query, limit }) =>
+      listFeishuDirectoryPeersLive({ cfg, query, limit }),
+    listGroupsLive: async ({ cfg, query, limit }) =>
+      listFeishuDirectoryGroupsLive({ cfg, query, limit }),
+  },
+  outbound: feishuOutbound,
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      port: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      port: snapshot.port ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ cfg }) =>
+      await probeFeishu(cfg.channels?.feishu as FeishuConfig | undefined),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      port: runtime?.port ?? null,
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const { monitorFeishuProvider } = await import("./monitor.js");
+      const feishuCfg = ctx.cfg.channels?.feishu as FeishuConfig | undefined;
+      const port = feishuCfg?.webhookPort ?? null;
+      ctx.setStatus({ accountId: ctx.accountId, port });
+      ctx.log?.info(`starting feishu provider (mode: ${feishuCfg?.connectionMode ?? "websocket"})`);
+      return monitorFeishuProvider({
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: ctx.accountId,
+      });
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,66 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import type { FeishuConfig, FeishuDomain } from "./types.js";
+import { resolveFeishuCredentials } from "./accounts.js";
+
+let cachedClient: Lark.Client | null = null;
+let cachedConfig: { appId: string; appSecret: string; domain: FeishuDomain } | null = null;
+
+function resolveDomain(domain: FeishuDomain) {
+  return domain === "lark" ? Lark.Domain.Lark : Lark.Domain.Feishu;
+}
+
+export function createFeishuClient(cfg: FeishuConfig): Lark.Client {
+  const creds = resolveFeishuCredentials(cfg);
+  if (!creds) {
+    throw new Error("Feishu credentials not configured (appId, appSecret required)");
+  }
+
+  if (
+    cachedClient &&
+    cachedConfig &&
+    cachedConfig.appId === creds.appId &&
+    cachedConfig.appSecret === creds.appSecret &&
+    cachedConfig.domain === creds.domain
+  ) {
+    return cachedClient;
+  }
+
+  const client = new Lark.Client({
+    appId: creds.appId,
+    appSecret: creds.appSecret,
+    appType: Lark.AppType.SelfBuild,
+    domain: resolveDomain(creds.domain),
+  });
+
+  cachedClient = client;
+  cachedConfig = { appId: creds.appId, appSecret: creds.appSecret, domain: creds.domain };
+
+  return client;
+}
+
+export function createFeishuWSClient(cfg: FeishuConfig): Lark.WSClient {
+  const creds = resolveFeishuCredentials(cfg);
+  if (!creds) {
+    throw new Error("Feishu credentials not configured (appId, appSecret required)");
+  }
+
+  return new Lark.WSClient({
+    appId: creds.appId,
+    appSecret: creds.appSecret,
+    domain: resolveDomain(creds.domain),
+    loggerLevel: Lark.LoggerLevel.info,
+  });
+}
+
+export function createEventDispatcher(cfg: FeishuConfig): Lark.EventDispatcher {
+  const creds = resolveFeishuCredentials(cfg);
+  return new Lark.EventDispatcher({
+    encryptKey: creds?.encryptKey,
+    verificationToken: creds?.verificationToken,
+  });
+}
+
+export function clearClientCache() {
+  cachedClient = null;
+  cachedConfig = null;
+}

package/src/config-schema.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+export { z };
+
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+const FeishuDomainSchema = z.enum(["feishu", "lark"]);
+const FeishuConnectionModeSchema = z.enum(["websocket", "webhook"]);
+
+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();
+
+export const FeishuGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    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();
+
+export const FeishuConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    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
+  })
+  .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,159 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import type { FeishuConfig } from "./types.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;
+}): Promise<FeishuDirectoryPeer[]> {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  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;
+}): Promise<FeishuDirectoryGroup[]> {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  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;
+}): Promise<FeishuDirectoryPeer[]> {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg?.appId || !feishuCfg?.appSecret) {
+    return listFeishuDirectoryPeers(params);
+  }
+
+  try {
+    const client = createFeishuClient(feishuCfg);
+    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;
+}): Promise<FeishuDirectoryGroup[]> {
+  const feishuCfg = params.cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg?.appId || !feishuCfg?.appSecret) {
+    return listFeishuDirectoryGroups(params);
+  }
+
+  try {
+    const client = createFeishuClient(feishuCfg);
+    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);
+  }
+}