@m1heng-clawd/feishu 0.1.13 → 0.1.15

package/src/channel.ts

@@ -91,6 +91,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
         groupAllowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
         requireMention: { type: "boolean" },
         groupCommandMentionBypass: { type: "string", enum: ["never", "single_bot", "always"] },
+        allowMentionlessInMultiBotGroup: { type: "boolean" },
         topicSessionMode: { type: "string", enum: ["disabled", "enabled"] },
         historyLimit: { type: "integer", minimum: 0 },
         dmHistoryLimit: { type: "integer", minimum: 0 },
@@ -114,6 +115,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
               connectionMode: { type: "string", enum: ["websocket", "webhook"] },
               mediaLocalRoots: { type: "array", items: { type: "string" } },
               groupCommandMentionBypass: { type: "string", enum: ["never", "single_bot", "always"] },
+              allowMentionlessInMultiBotGroup: { type: "boolean" },
             },
           },
         },

package/src/chat-tools/actions.ts

@@ -0,0 +1,433 @@
+import type { ChatClient } from "./common.js";
+import type { FeishuChatParams } from "./schemas.js";
+import { runChatApiCall } from "./common.js";
+
+const BLOCK_TYPE_NAMES: Record<number, string> = {
+  1: "Page",
+  2: "Text",
+  3: "Heading1",
+  4: "Heading2",
+  5: "Heading3",
+  12: "Bullet",
+  13: "Ordered",
+  14: "Code",
+  15: "Quote",
+  17: "Todo",
+  18: "Bitable",
+  21: "Diagram",
+  22: "Divider",
+  23: "File",
+  27: "Image",
+  30: "Sheet",
+  31: "Table",
+  32: "TableCell",
+};
+
+const STRUCTURED_BLOCK_TYPES = new Set([14, 18, 21, 23, 27, 30, 31, 32]);
+
+async function getAnnouncement(client: ChatClient, chatId: string) {
+  // Use docx.chatAnnouncement.get first — it works for both doc and docx announcements
+  // and returns announcement_type in its response, avoiding the noisy 232097 error
+  // that would occur when calling the legacy im API on a docx announcement.
+  const infoRes = await runChatApiCall("docx.chatAnnouncement.get", () =>
+    (client as any).docx.chatAnnouncement.get({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  const announcementType = (infoRes as any).data?.announcement_type;
+
+  if (announcementType === "doc") {
+    // Legacy doc format: fetch actual content via the im API
+    const docRes = await runChatApiCall("im.chatAnnouncement.get", () =>
+      (client as any).im.chatAnnouncement.get({
+        path: { chat_id: chatId },
+      }),
+    );
+    return {
+      announcement_type: "doc" as const,
+      ...(docRes as any).data,
+    };
+  }
+
+  // docx format (or unrecognised new format): fetch blocks
+  const blocksRes = await runChatApiCall("docx.chatAnnouncementBlock.list", () =>
+    (client as any).docx.chatAnnouncementBlock.list({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  const blocks = (blocksRes as any).data?.items ?? [];
+  const blockCounts: Record<string, number> = {};
+  const structuredTypes: string[] = [];
+
+  for (const b of blocks) {
+    const type = b.block_type ?? 0;
+    const name = BLOCK_TYPE_NAMES[type] || `type_${type}`;
+    blockCounts[name] = (blockCounts[name] || 0) + 1;
+
+    if (STRUCTURED_BLOCK_TYPES.has(type) && !structuredTypes.includes(name)) {
+      structuredTypes.push(name);
+    }
+  }
+
+  let hint: string | undefined;
+  if (structuredTypes.length > 0) {
+    hint = `This announcement contains ${structuredTypes.join(", ")} which are NOT included in the basic info. Use action: "list_announcement_blocks" to get full content.`;
+  }
+
+  return {
+    announcement_type: "docx" as const,
+    info: (infoRes as any).data,
+    blocks,
+    block_count: blocks.length,
+    block_types: blockCounts,
+    ...(hint && { hint }),
+  };
+}
+
+async function listAnnouncementBlocks(client: ChatClient, chatId: string) {
+  const res = await runChatApiCall("docx.chatAnnouncementBlock.list", () =>
+    (client as any).docx.chatAnnouncementBlock.list({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  return {
+    blocks: (res as any).data?.items ?? [],
+  };
+}
+
+async function getAnnouncementBlock(client: ChatClient, chatId: string, blockId: string) {
+  const res = await runChatApiCall("docx.chatAnnouncementBlock.get", () =>
+    (client as any).docx.chatAnnouncementBlock.get({
+      path: { chat_id: chatId, block_id: blockId },
+    }),
+  );
+
+  return {
+    block: (res as any).data?.block,
+  };
+}
+
+async function writeDocAnnouncement(client: ChatClient, chatId: string, content: string) {
+  const current = await runChatApiCall("im.chatAnnouncement.get", () =>
+    (client as any).im.chatAnnouncement.get({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  const res = await runChatApiCall("im.chatAnnouncement.patch", () =>
+    (client as any).im.chatAnnouncement.patch({
+      path: { chat_id: chatId },
+      data: {
+        content,
+        revision: (current as any).data?.revision,
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    announcement_type: "doc",
+    ...(res as any).data,
+  };
+}
+
+async function createAnnouncementBlockChild(
+  client: ChatClient,
+  chatId: string,
+  parentBlockId: string,
+  blockData: any,
+) {
+  const res = await runChatApiCall("docx.chatAnnouncementBlockChildren.create", () =>
+    (client as any).docx.chatAnnouncementBlockChildren.create({
+      path: { chat_id: chatId, block_id: parentBlockId },
+      data: blockData,
+    }),
+  );
+
+  return {
+    success: true,
+    block: (res as any).data,
+  };
+}
+
+async function createTextBlock(
+  client: ChatClient,
+  chatId: string,
+  parentBlockId: string,
+  text: string,
+) {
+  const blockData = {
+    children: [
+      {
+        block_type: 2,
+        text: {
+          elements: [
+            {
+              text_run: {
+                content: text,
+              },
+            },
+          ],
+        },
+      },
+    ],
+  };
+
+  return createAnnouncementBlockChild(client, chatId, parentBlockId, blockData);
+}
+
+async function batchUpdateAnnouncementBlocks(
+  client: ChatClient,
+  chatId: string,
+  requests: any[],
+) {
+  const info = await runChatApiCall("docx.chatAnnouncement.get", () =>
+    (client as any).docx.chatAnnouncement.get({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  const res = await runChatApiCall("docx.chatAnnouncementBlock.batchUpdate", () =>
+    (client as any).docx.chatAnnouncementBlock.batchUpdate({
+      path: { chat_id: chatId },
+      params: {
+        revision_id: (info as any).data?.revision_id,
+      },
+      data: {
+        requests,
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    ...(res as any).data,
+  };
+}
+
+// ============== New Chat Management Functions ==============
+
+async function createChat(client: ChatClient, name: string, userIds?: string[], description?: string) {
+  const data: any = { name };
+  if (userIds && userIds.length > 0) {
+    data.user_id_list = userIds;
+  }
+  if (description) {
+    data.description = description;
+  }
+
+  const res = await runChatApiCall("im.chat.create", () =>
+    (client as any).im.chat.create({
+      data,
+      params: { user_id_type: "open_id" },
+    }),
+  );
+
+  return {
+    success: true,
+    chat_id: (res as any).data?.chat_id,
+    ...(res as any).data,
+  };
+}
+
+async function addMembers(client: ChatClient, chatId: string, userIds: string[]) {
+  const res = await runChatApiCall("im.chatMembers.create", () =>
+    (client as any).im.chatMembers.create({
+      path: { chat_id: chatId },
+      params: { member_id_type: "open_id" },
+      data: { id_list: userIds },
+    }),
+  );
+
+  return {
+    success: true,
+    chat_id: chatId,
+    added_user_ids: userIds,
+    ...(res as any).data,
+  };
+}
+
+async function checkBotInChat(client: ChatClient, chatId: string) {
+  try {
+    const res = await runChatApiCall("im.chat.get", () =>
+      (client as any).im.chat.get({ path: { chat_id: chatId } }),
+    );
+    
+    return {
+      success: true,
+      chat_id: chatId,
+      in_chat: true,
+      chat_info: (res as any).data,
+    };
+  } catch (err: any) {
+    if (err?.message?.includes("90003")) {
+      return {
+        success: true,
+        chat_id: chatId,
+        in_chat: false,
+        error: "Bot is not in this chat",
+      };
+    }
+    throw err;
+  }
+}
+
+async function sendMessage(client: ChatClient, chatId: string, content: string) {
+  const res = await runChatApiCall("im.message.create", () =>
+    (client as any).im.message.create({
+      params: { receive_id_type: "chat_id" },
+      data: {
+        receive_id: chatId,
+        msg_type: "text",
+        content: JSON.stringify({ text: content }),
+      },
+    }),
+  );
+
+  return {
+    success: true,
+    message_id: (res as any).data?.message_id,
+    ...(res as any).data,
+  };
+}
+
+async function createSessionChat(
+  client: ChatClient,
+  name: string,
+  userIds: string[],
+  greeting?: string,
+  description?: string,
+) {
+  // Step 1: Create the chat
+  const createResult = await createChat(client, name, userIds, description);
+  const chatId = createResult.chat_id;
+  
+  if (!chatId) {
+    return {
+      success: false,
+      error: "Failed to create chat - no chat_id returned",
+      create_result: createResult,
+    };
+  }
+
+  // Step 2: Send greeting message
+  const defaultGreeting = "Hello! I've created this group chat for us to collaborate.";
+  const greetingMessage = greeting || defaultGreeting;
+  
+  let messageResult;
+  try {
+    messageResult = await sendMessage(client, chatId, greetingMessage);
+  } catch (err: any) {
+    // Even if message fails, the chat was created successfully
+    return {
+      success: true,
+      chat_id: chatId,
+      create_result: createResult,
+      message_error: err?.message || "Failed to send greeting message",
+    };
+  }
+
+  return {
+    success: true,
+    chat_id: chatId,
+    create_result: createResult,
+    message_result: messageResult,
+  };
+}
+
+async function deleteChat(client: ChatClient, chatId: string) {
+  const res = await runChatApiCall("im.chat.delete", () =>
+    (client as any).im.chat.delete({
+      path: { chat_id: chatId },
+    }),
+  );
+
+  return {
+    success: true,
+    chat_id: chatId,
+    message: "Chat has been successfully disbanded/deleted",
+    ...(res as any).data,
+  };
+}
+
+// Main action handler - MUST BE EXPORTED
+export async function runChatAction(client: ChatClient, params: FeishuChatParams) {
+  switch (params.action) {
+    case "get_announcement_info":
+    case "get_announcement":
+      return getAnnouncement(client, params.chat_id);
+    case "list_announcement_blocks":
+      return listAnnouncementBlocks(client, params.chat_id);
+    case "get_announcement_block":
+      return getAnnouncementBlock(client, params.chat_id, params.block_id);
+    case "write_announcement": {
+      const current = await getAnnouncement(client, params.chat_id);
+      if (current.announcement_type === "doc") {
+        return writeDocAnnouncement(client, params.chat_id, params.content);
+      } else {
+        // For docx announcements, append a text block under the Page root block.
+        // Full replacement is not supported via API; use update_announcement_block to edit existing blocks.
+        const blocks: any[] = (current as any).blocks ?? [];
+        const pageBlock = blocks.find((b: any) => b.block_type === 1);
+        if (!pageBlock?.block_id) {
+          return { error: "Could not find the Page root block for docx announcement. Use list_announcement_blocks to inspect the structure." };
+        }
+        return createTextBlock(client, params.chat_id, pageBlock.block_id, params.content);
+      }
+    }
+    case "append_announcement": {
+      const current = await getAnnouncement(client, params.chat_id);
+      if (current.announcement_type === "doc") {
+        const existingContent = (current as any).content || "";
+        const newContent = existingContent + "\n" + params.content;
+        return writeDocAnnouncement(client, params.chat_id, newContent);
+      } else {
+        // For docx format, the parent block must be the Page root block (block_type: 1)
+        const blocks: any[] = (current as any).blocks ?? [];
+        const pageBlock = blocks.find((b: any) => b.block_type === 1);
+        if (!pageBlock?.block_id) {
+          return { error: "Could not find the Page root block for docx announcement. Use list_announcement_blocks to inspect the structure." };
+        }
+        return createTextBlock(client, params.chat_id, pageBlock.block_id, params.content);
+      }
+    }
+    case "update_announcement_block": {
+      const requests = [
+        {
+          block_id: params.block_id,
+          update_text_elements: {
+            elements: [{ text_run: { content: params.content } }],
+          },
+        },
+      ];
+      return batchUpdateAnnouncementBlocks(client, params.chat_id, requests);
+    }
+    // ============== New Chat Management Actions ==============
+    case "create_chat": {
+      return createChat(client, params.name, params.user_ids, params.description);
+    }
+    case "add_members": {
+      return addMembers(client, params.chat_id, params.user_ids);
+    }
+    case "check_bot_in_chat": {
+      return checkBotInChat(client, params.chat_id);
+    }
+    case "delete_chat": {
+      return deleteChat(client, params.chat_id);
+    }
+    case "create_session_chat": {
+      return createSessionChat(
+        client,
+        params.name,
+        params.user_ids,
+        params.greeting,
+        params.description,
+      );
+    }
+    default:
+      return { error: `Unknown action: ${(params as any).action}` };
+  }
+}

package/src/chat-tools/common.ts

@@ -0,0 +1,13 @@
+import { createFeishuClient } from "../client.js";
+import { errorResult, json, runFeishuApiCall, type FeishuApiResponse } from "../tools-common/feishu-api.js";
+
+export type ChatClient = ReturnType<typeof createFeishuClient>;
+
+export { json, errorResult };
+
+export async function runChatApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runFeishuApiCall(context, fn);
+}

package/src/chat-tools/index.ts

@@ -0,0 +1,2 @@
+export { registerFeishuChatTools } from "./register.js";
+export { FeishuChatSchema, type FeishuChatParams } from "./schemas.js";

package/src/chat-tools/register.ts

@@ -0,0 +1,72 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { ResolvedFeishuAccount } from "../types.js";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "../tools-common/tool-exec.js";
+import { runChatAction } from "./actions.js";
+import { errorResult, json, type ChatClient } from "./common.js";
+import { FeishuChatSchema, type FeishuChatParams } from "./schemas.js";
+
+type ChatToolSpec<P> = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: any;
+  requiredTool?: "chat";
+  run: (args: { client: ChatClient; account: ResolvedFeishuAccount }, params: P) => Promise<unknown>;
+};
+
+function registerChatTool<P>(api: OpenClawPluginApi, spec: ChatToolSpec<P>) {
+  api.registerTool(
+    {
+      name: spec.name,
+      label: spec.label,
+      description: spec.description,
+      parameters: spec.parameters,
+      async execute(_toolCallId, params) {
+        try {
+          return await withFeishuToolClient({
+            api,
+            toolName: spec.name,
+            requiredTool: spec.requiredTool,
+            run: async ({ client, account }) =>
+              json(await spec.run({ client: client as ChatClient, account }, params as P)),
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      },
+    },
+    { name: spec.name },
+  );
+}
+
+export function registerFeishuChatTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_chat: No config available, skipping chat tools");
+    return;
+  }
+
+  if (!hasFeishuToolEnabledForAnyAccount(api.config)) {
+    api.logger.debug?.("feishu_chat: No Feishu accounts configured, skipping chat tools");
+    return;
+  }
+
+  const chatEnabled = hasFeishuToolEnabledForAnyAccount(api.config, "chat");
+  const registered: string[] = [];
+
+  if (chatEnabled) {
+    registerChatTool<FeishuChatParams>(api, {
+      name: "feishu_chat",
+      label: "Feishu Chat",
+      description:
+        "Feishu chat operations. Actions: get_announcement, get_announcement_info, list_announcement_blocks, get_announcement_block, write_announcement, append_announcement, update_announcement_block, create_chat, add_members, check_bot_in_chat, create_session_chat, delete_chat. Use to manage group chats and announcements.",
+      parameters: FeishuChatSchema,
+      requiredTool: "chat",
+      run: async ({ client }, params) => runChatAction(client, params),
+    });
+    registered.push("feishu_chat");
+  }
+
+  if (registered.length > 0) {
+    api.logger.debug?.(`feishu_chat: Registered ${registered.join(", ")}`);
+  }
+}

package/src/chat-tools/schemas.ts

@@ -0,0 +1,66 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+export const FeishuChatSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("get_announcement_info"),
+    chat_id: Type.String({ description: "Chat ID to get announcement from" }),
+  }),
+  Type.Object({
+    action: Type.Literal("get_announcement"),
+    chat_id: Type.String({ description: "Chat ID to get announcement from" }),
+  }),
+  Type.Object({
+    action: Type.Literal("write_announcement"),
+    chat_id: Type.String({ description: "Chat ID to write announcement to" }),
+    content: Type.String({ description: "Content to write. For doc format: replaces the entire announcement. For docx format: appends a new text block under the page root." }),
+  }),
+  Type.Object({
+    action: Type.Literal("append_announcement"),
+    chat_id: Type.String({ description: "Chat ID to append announcement to" }),
+    content: Type.String({ description: "Markdown content to append to announcement" }),
+  }),
+  Type.Object({
+    action: Type.Literal("list_announcement_blocks"),
+    chat_id: Type.String({ description: "Chat ID to list announcement blocks from" }),
+  }),
+  Type.Object({
+    action: Type.Literal("get_announcement_block"),
+    chat_id: Type.String({ description: "Chat ID to get announcement block from" }),
+    block_id: Type.String({ description: "Block ID (from list_announcement_blocks)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("update_announcement_block"),
+    chat_id: Type.String({ description: "Chat ID to update announcement block in" }),
+    block_id: Type.String({ description: "Block ID (from list_announcement_blocks)" }),
+    content: Type.String({ description: "New text content" }),
+  }),
+  // ============== New Chat Management Actions ==============
+  Type.Object({
+    action: Type.Literal("create_chat"),
+    name: Type.String({ description: "Group chat name" }),
+    user_ids: Type.Optional(Type.Array(Type.String(), { description: "List of user IDs to add to the group" })),
+    description: Type.Optional(Type.String({ description: "Group chat description" })),
+  }),
+  Type.Object({
+    action: Type.Literal("add_members"),
+    chat_id: Type.String({ description: "Chat ID to add members to" }),
+    user_ids: Type.Array(Type.String(), { description: "List of user IDs to add" }),
+  }),
+  Type.Object({
+    action: Type.Literal("check_bot_in_chat"),
+    chat_id: Type.String({ description: "Chat ID to check" }),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_chat"),
+    chat_id: Type.String({ description: "Chat ID to delete/dismiss" }),
+  }),
+  Type.Object({
+    action: Type.Literal("create_session_chat"),
+    name: Type.String({ description: "Session group name" }),
+    user_ids: Type.Array(Type.String(), { description: "List of user IDs to invite" }),
+    greeting: Type.Optional(Type.String({ description: "Greeting message to send (default: Hello! I've created this group chat for us to collaborate.)" })),
+    description: Type.Optional(Type.String({ description: "Group description" })),
+  }),
+]);
+
+export type FeishuChatParams = Static<typeof FeishuChatSchema>;

package/src/client.ts

@@ -1,6 +1,17 @@
 import * as Lark from "@larksuiteoapi/node-sdk";
+import { HttpsProxyAgent } from "https-proxy-agent";
 import type { FeishuDomain, ResolvedFeishuAccount } from "./types.js";
 
+function getWsProxyAgent(): HttpsProxyAgent<string> | undefined {
+  const proxyUrl =
+    process.env.https_proxy ||
+    process.env.HTTPS_PROXY ||
+    process.env.http_proxy ||
+    process.env.HTTP_PROXY;
+  if (!proxyUrl) return undefined;
+  return new HttpsProxyAgent(proxyUrl);
+}
+
 // Multi-account client cache
 const clientCache = new Map<
   string,
@@ -77,11 +88,13 @@ export function createFeishuWSClient(account: ResolvedFeishuAccount): Lark.WSCli
     throw new Error(`Feishu credentials not configured for account "${accountId}"`);
   }
 
+  const agent = getWsProxyAgent();
   return new Lark.WSClient({
     appId,
     appSecret,
     domain: resolveDomain(domain),
     loggerLevel: Lark.LoggerLevel.info,
+    ...(agent ? { agent } : {}),
   });
 }
 

package/src/config-schema.ts

@@ -4,6 +4,7 @@ export { z };
 const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
 const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
 const GroupCommandMentionBypassSchema = z.enum(["never", "single_bot", "always"]).optional();
+const AllowMentionlessInMultiBotGroupSchema = z.boolean().optional();
 const FeishuDomainSchema = z.union([
   z.enum(["feishu", "lark"]),
   z.string().url().startsWith("https://"),
@@ -88,6 +89,8 @@ const FeishuToolsConfigSchema = z
     perm: z.boolean().optional(), // Permission management (default: false, sensitive)
     scopes: z.boolean().optional(), // App scopes diagnostic (default: true)
     task: z.boolean().optional(), // Task operations (default: true)
+    chat: z.boolean().optional(), // Chat management operations (default: true)
+    urgent: z.boolean().optional(), // Buzz/urgent notifications (default: true)
   })
   .strict()
   .optional();
@@ -106,6 +109,7 @@ export const FeishuGroupSchema = z
   .object({
     requireMention: z.boolean().optional(),
     groupCommandMentionBypass: GroupCommandMentionBypassSchema,
+    allowMentionlessInMultiBotGroup: AllowMentionlessInMultiBotGroupSchema,
     tools: ToolPolicySchema,
     skills: z.array(z.string()).optional(),
     enabled: z.boolean().optional(),
@@ -140,6 +144,7 @@ export const FeishuAccountConfigSchema = z
     groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
     requireMention: z.boolean().optional(),
     groupCommandMentionBypass: GroupCommandMentionBypassSchema,
+    allowMentionlessInMultiBotGroup: AllowMentionlessInMultiBotGroupSchema,
     groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
     historyLimit: z.number().int().min(0).optional(),
     dmHistoryLimit: z.number().int().min(0).optional(),
@@ -177,6 +182,7 @@ export const FeishuConfigSchema = z
     groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
     requireMention: z.boolean().optional().default(true),
     groupCommandMentionBypass: GroupCommandMentionBypassSchema.default("single_bot"),
+    allowMentionlessInMultiBotGroup: AllowMentionlessInMultiBotGroupSchema.default(false),
     groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
     topicSessionMode: TopicSessionModeSchema,
     historyLimit: z.number().int().min(0).optional(),