@nextclaw/channel-plugin-feishu 0.2.16 → 0.2.18

package/index.ts

@@ -1,12 +1,17 @@
 import type { OpenClawPluginApi } from "./src/nextclaw-sdk/feishu.js";
+import { registerFeishuCalendarTools } from "./src/calendar.js";
 import { emptyPluginConfigSchema } from "./src/nextclaw-sdk/feishu.js";
 import { registerFeishuBitableTools } from "./src/bitable.js";
 import { feishuPlugin } from "./src/channel.js";
 import { registerFeishuChatTools } from "./src/chat.js";
 import { registerFeishuDocTools } from "./src/docx.js";
 import { registerFeishuDriveTools } from "./src/drive.js";
+import { registerFeishuIdentityTools } from "./src/identity.js";
+import { registerFeishuOAuthTool } from "./src/oauth.js";
 import { registerFeishuPermTools } from "./src/perm.js";
 import { setFeishuRuntime } from "./src/runtime.js";
+import { registerFeishuSheetsTools } from "./src/sheets.js";
+import { registerFeishuTaskTools } from "./src/task.js";
 import { registerFeishuWikiTools } from "./src/wiki.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
@@ -59,6 +64,11 @@ const plugin = {
     registerFeishuDriveTools(api);
     registerFeishuPermTools(api);
     registerFeishuBitableTools(api);
+    registerFeishuCalendarTools(api);
+    registerFeishuTaskTools(api);
+    registerFeishuSheetsTools(api);
+    registerFeishuIdentityTools(api);
+    registerFeishuOAuthTool(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/channel-plugin-feishu",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "private": false,
   "description": "NextClaw Feishu/Lark channel plugin with doc/wiki/drive tools.",
   "type": "module",

package/src/app-scope-checker.ts

@@ -0,0 +1,75 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { AppScopeCheckFailedError } from "./auth-errors.js";
+
+type CacheEntry = {
+  rawScopes: Array<{ scope: string; token_types?: string[] }>;
+  fetchedAt: number;
+};
+
+const cache = new Map<string, CacheEntry>();
+const CACHE_TTL_MS = 30 * 1000;
+
+export function invalidateAppScopeCache(appId: string): void {
+  cache.delete(appId);
+}
+
+export async function getAppGrantedScopes(
+  sdk: Lark.Client,
+  appId: string,
+  tokenType?: "user" | "tenant",
+): Promise<string[]> {
+  const cached = cache.get(appId);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.rawScopes
+      .filter((scope) => !tokenType || !scope.token_types || scope.token_types.includes(tokenType))
+      .map((scope) => scope.scope);
+  }
+
+  try {
+    const response = await (sdk as unknown as {
+      request: (params: {
+        method: string;
+        url: string;
+        params: Record<string, string>;
+      }) => Promise<{ code?: number; data?: { app?: { scopes?: Array<{ scope?: string; token_types?: string[] }> } } }>;
+    }).request({
+      method: "GET",
+      url: `/open-apis/application/v6/applications/${appId}`,
+      params: { lang: "zh_cn" },
+    });
+
+    if (response.code !== 0) {
+      throw new AppScopeCheckFailedError(appId);
+    }
+
+    const rawScopes =
+      response.data?.app?.scopes
+        ?.filter((scope): scope is { scope: string; token_types?: string[] } =>
+          typeof scope.scope === "string" && scope.scope.length > 0,
+        ) ?? [];
+    cache.set(appId, { rawScopes, fetchedAt: Date.now() });
+
+    return rawScopes
+      .filter((scope) => !tokenType || !scope.token_types || scope.token_types.includes(tokenType))
+      .map((scope) => scope.scope);
+  } catch (error) {
+    if (error instanceof AppScopeCheckFailedError) {
+      throw error;
+    }
+
+    const statusCode =
+      (error as { response?: { status?: number }; status?: number; statusCode?: number }).response
+        ?.status ??
+      (error as { status?: number }).status ??
+      (error as { statusCode?: number }).statusCode;
+    if (statusCode === 400 || statusCode === 403) {
+      throw new AppScopeCheckFailedError(appId);
+    }
+    return [];
+  }
+}
+
+export function missingScopes(appGranted: string[], apiRequired: string[]): string[] {
+  const granted = new Set(appGranted);
+  return apiRequired.filter((scope) => !granted.has(scope));
+}

package/src/auth-errors.ts

@@ -0,0 +1,90 @@
+export const LARK_ERROR = {
+  APP_SCOPE_MISSING: 99991672,
+  USER_SCOPE_INSUFFICIENT: 99991679,
+  TOKEN_INVALID: 99991668,
+  TOKEN_EXPIRED: 99991677,
+  REFRESH_TOKEN_INVALID: 20026,
+  REFRESH_TOKEN_EXPIRED: 20037,
+  REFRESH_TOKEN_REVOKED: 20064,
+  REFRESH_TOKEN_ALREADY_USED: 20073,
+  REFRESH_SERVER_ERROR: 20050,
+} as const;
+
+export const REFRESH_TOKEN_RETRYABLE = new Set<number>([LARK_ERROR.REFRESH_SERVER_ERROR]);
+export const TOKEN_RETRY_CODES = new Set<number>([
+  LARK_ERROR.TOKEN_INVALID,
+  LARK_ERROR.TOKEN_EXPIRED,
+]);
+
+export type ScopeErrorInfo = {
+  apiName: string;
+  scopes: string[];
+  appScopeVerified?: boolean;
+  appId?: string;
+};
+
+export class NeedAuthorizationError extends Error {
+  readonly userOpenId: string;
+
+  constructor(userOpenId: string) {
+    super("need_user_authorization");
+    this.name = "NeedAuthorizationError";
+    this.userOpenId = userOpenId;
+  }
+}
+
+export class AppScopeCheckFailedError extends Error {
+  readonly appId?: string;
+
+  constructor(appId?: string) {
+    super("应用缺少 application:application:self_manage 权限，无法查询应用权限配置。");
+    this.name = "AppScopeCheckFailedError";
+    this.appId = appId;
+  }
+}
+
+export class AppScopeMissingError extends Error {
+  readonly apiName: string;
+  readonly missingScopes: string[];
+  readonly appId?: string;
+
+  constructor(info: ScopeErrorInfo) {
+    super(`应用缺少权限 [${info.scopes.join(", ")}]，请管理员在飞书开放平台开通。`);
+    this.name = "AppScopeMissingError";
+    this.apiName = info.apiName;
+    this.missingScopes = info.scopes;
+    this.appId = info.appId;
+  }
+}
+
+export class UserAuthRequiredError extends Error {
+  readonly userOpenId: string;
+  readonly apiName: string;
+  readonly requiredScopes: string[];
+  readonly appScopeVerified: boolean;
+  readonly appId?: string;
+
+  constructor(userOpenId: string, info: ScopeErrorInfo) {
+    super("need_user_authorization");
+    this.name = "UserAuthRequiredError";
+    this.userOpenId = userOpenId;
+    this.apiName = info.apiName;
+    this.requiredScopes = info.scopes;
+    this.appScopeVerified = info.appScopeVerified ?? true;
+    this.appId = info.appId;
+  }
+}
+
+export class UserScopeInsufficientError extends Error {
+  readonly userOpenId: string;
+  readonly apiName: string;
+  readonly missingScopes: string[];
+
+  constructor(userOpenId: string, info: ScopeErrorInfo) {
+    super("user_scope_insufficient");
+    this.name = "UserScopeInsufficientError";
+    this.userOpenId = userOpenId;
+    this.apiName = info.apiName;
+    this.missingScopes = info.scopes;
+  }
+}

package/src/calendar-calendar.ts

@@ -0,0 +1,72 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, registerTool } from "./user-tool-helpers.js";
+
+const CalendarCalendarSchema = Type.Union([
+  Type.Object({ action: Type.Literal("list"), page_size: Type.Optional(Type.Number()), page_token: Type.Optional(Type.String()) }),
+  Type.Object({ action: Type.Literal("get"), calendar_id: Type.String() }),
+  Type.Object({ action: Type.Literal("primary") }),
+]);
+
+export function registerFeishuCalendarCalendarTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_calendar");
+  registerTool(
+    api,
+    {
+      name: "feishu_calendar_calendar",
+      label: "Feishu Calendar",
+      description: "按本人身份查询飞书日历列表、主日历和指定日历详情。",
+      parameters: CalendarCalendarSchema,
+      async execute(_toolCallId, params) {
+        const payload = params as {
+          action: "list" | "get" | "primary";
+          page_size?: number;
+          page_token?: string;
+          calendar_id?: string;
+        };
+        try {
+          const client = toolClient();
+          if (payload.action === "list") {
+            const response = await client.invoke(
+              "feishu_calendar_calendar.list",
+              (sdk, opts) =>
+                sdk.calendar.calendar.list(
+                  { params: { page_size: payload.page_size, page_token: payload.page_token } },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({
+              calendars: (response.data as { calendar_list?: unknown[] } | undefined)?.calendar_list ?? [],
+              has_more: (response.data as { has_more?: boolean } | undefined)?.has_more ?? false,
+              page_token: (response.data as { page_token?: string } | undefined)?.page_token,
+            });
+          }
+          if (payload.action === "primary") {
+            const response = await client.invoke(
+              "feishu_calendar_calendar.primary",
+              (sdk, opts) => sdk.calendar.calendar.primary({}, opts),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({
+              calendars: (response.data as { calendars?: unknown[] } | undefined)?.calendars ?? [],
+            });
+          }
+          const response = await client.invoke(
+            "feishu_calendar_calendar.get",
+            (sdk, opts) =>
+              sdk.calendar.calendar.get({ path: { calendar_id: payload.calendar_id! } }, opts),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({ calendar: (response.data as { calendar?: unknown } | undefined)?.calendar ?? response.data });
+        } catch (error) {
+          return handleInvokeError(error, api);
+        }
+      },
+    },
+    { name: "feishu_calendar_calendar" },
+  );
+}

package/src/calendar-event-attendee.ts

@@ -0,0 +1,96 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, registerTool, StringEnum } from "./user-tool-helpers.js";
+
+const CalendarAttendeeSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("create"),
+    calendar_id: Type.String(),
+    event_id: Type.String(),
+    attendees: Type.Array(Type.Object({ type: StringEnum(["user", "chat", "resource", "third_party"]), attendee_id: Type.String() })),
+    need_notification: Type.Optional(Type.Boolean()),
+  }),
+  Type.Object({
+    action: Type.Literal("list"),
+    calendar_id: Type.String(),
+    event_id: Type.String(),
+    page_size: Type.Optional(Type.Number()),
+    page_token: Type.Optional(Type.String()),
+    user_id_type: Type.Optional(StringEnum(["open_id", "union_id", "user_id"])),
+  }),
+]);
+
+export function registerFeishuCalendarEventAttendeeTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_event_attendee");
+  registerTool(api, {
+    name: "feishu_calendar_event_attendee",
+    label: "Feishu Calendar Event Attendee",
+    description: "按本人身份添加日程参会人或查看参会人列表。",
+    parameters: CalendarAttendeeSchema,
+    async execute(_toolCallId, params) {
+      const payload = params as {
+        action: "create" | "list";
+        calendar_id: string;
+        event_id: string;
+        attendees?: Array<{ type: "user" | "chat" | "resource" | "third_party"; attendee_id: string }>;
+        need_notification?: boolean;
+        page_size?: number;
+        page_token?: string;
+        user_id_type?: "open_id" | "union_id" | "user_id";
+      };
+      try {
+        const client = toolClient();
+        if (payload.action === "create") {
+          const attendeePayload = (payload.attendees ?? []).map((attendee) => {
+            if (attendee.type === "user") return { type: attendee.type, user_id: attendee.attendee_id };
+            if (attendee.type === "chat") return { type: attendee.type, chat_id: attendee.attendee_id };
+            if (attendee.type === "resource") return { type: attendee.type, room_id: attendee.attendee_id };
+            return { type: attendee.type, third_party_email: attendee.attendee_id };
+          });
+          const response = await client.invoke(
+            "feishu_calendar_event_attendee.create",
+            (sdk, opts) =>
+              sdk.calendar.calendarEventAttendee.create(
+                {
+                  path: { calendar_id: payload.calendar_id, event_id: payload.event_id },
+                  params: { user_id_type: "open_id" as never },
+                  data: {
+                    attendees: attendeePayload,
+                    need_notification: payload.need_notification ?? true,
+                  },
+                },
+                opts,
+              ),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({ attendees: (response.data as { attendees?: unknown[] } | undefined)?.attendees ?? [] });
+        }
+        const response = await client.invoke(
+          "feishu_calendar_event_attendee.list",
+          (sdk, opts) =>
+            sdk.calendar.calendarEventAttendee.list(
+              {
+                path: { calendar_id: payload.calendar_id, event_id: payload.event_id },
+                params: {
+                  page_size: payload.page_size,
+                  page_token: payload.page_token,
+                  user_id_type: payload.user_id_type ?? "open_id",
+                },
+              },
+              opts,
+            ),
+          { as: "user" },
+        );
+        assertLarkOk(response);
+        return json({
+          attendees: (response.data as { items?: unknown[] } | undefined)?.items ?? [],
+          has_more: (response.data as { has_more?: boolean } | undefined)?.has_more ?? false,
+          page_token: (response.data as { page_token?: string } | undefined)?.page_token,
+        });
+      } catch (error) {
+        return handleInvokeError(error, api);
+      }
+    },
+  }, { name: "feishu_calendar_event_attendee" });
+}

package/src/calendar-event.ts

@@ -0,0 +1,236 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { normalizeEventTimes, resolveCalendarId } from "./calendar-shared.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, parseTimeToTimestamp, registerTool, StringEnum } from "./user-tool-helpers.js";
+
+const CalendarEventSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("create"),
+    start_time: Type.String(),
+    end_time: Type.String(),
+    summary: Type.Optional(Type.String()),
+    calendar_id: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    attendees: Type.Optional(Type.Array(Type.Object({ type: StringEnum(["user", "chat", "resource", "third_party"]), id: Type.String() }))),
+    user_open_id: Type.Optional(Type.String()),
+    need_notification: Type.Optional(Type.Boolean()),
+    location: Type.Optional(Type.String()),
+  }),
+  Type.Object({
+    action: Type.Literal("list"),
+    start_time: Type.String(),
+    end_time: Type.String(),
+    calendar_id: Type.Optional(Type.String()),
+    page_size: Type.Optional(Type.Number()),
+    page_token: Type.Optional(Type.String()),
+  }),
+  Type.Object({ action: Type.Literal("get"), event_id: Type.String(), calendar_id: Type.Optional(Type.String()) }),
+  Type.Object({
+    action: Type.Literal("patch"),
+    event_id: Type.String(),
+    calendar_id: Type.Optional(Type.String()),
+    summary: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    start_time: Type.Optional(Type.String()),
+    end_time: Type.Optional(Type.String()),
+    location: Type.Optional(Type.String()),
+  }),
+  Type.Object({ action: Type.Literal("delete"), event_id: Type.String(), calendar_id: Type.Optional(Type.String()), need_notification: Type.Optional(Type.Boolean()) }),
+]);
+
+function buildAttendees(payload: {
+  attendees?: Array<{ type: "user" | "chat" | "resource" | "third_party"; id: string }>;
+  user_open_id?: string;
+}) {
+  const attendees = [
+    ...(payload.user_open_id ? [{ type: "user" as const, id: payload.user_open_id }] : []),
+    ...(payload.attendees ?? []),
+  ];
+  return attendees.map((attendee) => {
+    if (attendee.type === "user") return { type: attendee.type, user_id: attendee.id };
+    if (attendee.type === "chat") return { type: attendee.type, chat_id: attendee.id };
+    if (attendee.type === "resource") return { type: attendee.type, room_id: attendee.id };
+    return { type: attendee.type, third_party_email: attendee.id };
+  });
+}
+
+export function registerFeishuCalendarEventTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_event");
+  registerTool(
+    api,
+    {
+      name: "feishu_calendar_event",
+      label: "Feishu Calendar Event",
+      description: "按本人身份创建、查询、修改、删除飞书日程。",
+      parameters: CalendarEventSchema,
+      async execute(_toolCallId, params) {
+        const payload = params as {
+          action: "create" | "list" | "get" | "patch" | "delete";
+          calendar_id?: string;
+          event_id?: string;
+          start_time?: string;
+          end_time?: string;
+          summary?: string;
+          description?: string;
+          attendees?: Array<{ type: "user" | "chat" | "resource" | "third_party"; id: string }>;
+          user_open_id?: string;
+          need_notification?: boolean;
+          location?: string;
+          page_size?: number;
+          page_token?: string;
+        };
+        try {
+          const client = toolClient();
+          const calendarId = await resolveCalendarId(client, payload.calendar_id);
+
+          if (payload.action === "create") {
+            const startTs = payload.start_time ? parseTimeToTimestamp(payload.start_time) : null;
+            const endTs = payload.end_time ? parseTimeToTimestamp(payload.end_time) : null;
+            if (!startTs || !endTs) {
+              return json({ error: "start_time 和 end_time 必须为带时区的 ISO 8601 / RFC 3339 时间。" });
+            }
+            const response = await client.invoke(
+              "feishu_calendar_event.create",
+              (sdk, opts) =>
+                sdk.calendar.calendarEvent.create(
+                  {
+                    path: { calendar_id: calendarId },
+                    data: {
+                      summary: payload.summary,
+                      description: payload.description,
+                      start_time: { timestamp: startTs },
+                      end_time: { timestamp: endTs },
+                      ...(payload.location ? { location: { name: payload.location } } : {}),
+                    },
+                  },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            const event = (response.data as { event?: { event_id?: string } } | undefined)?.event;
+            const attendeePayload = buildAttendees(payload);
+            if (event?.event_id && attendeePayload.length > 0) {
+              await client.invoke(
+                "feishu_calendar_event.create",
+                (sdk, opts) =>
+                  sdk.calendar.calendarEventAttendee.create(
+                    {
+                      path: { calendar_id: calendarId, event_id: event.event_id! },
+                      params: { user_id_type: "open_id" as never },
+                      data: {
+                        attendees: attendeePayload,
+                        need_notification: payload.need_notification ?? true,
+                      },
+                    },
+                    opts,
+                  ),
+                { as: "user" },
+              );
+            }
+            return json({ event: normalizeEventTimes((response.data as { event?: Record<string, unknown> } | undefined)?.event) });
+          }
+
+          if (payload.action === "list") {
+            const startTs = payload.start_time ? parseTimeToTimestamp(payload.start_time) : null;
+            const endTs = payload.end_time ? parseTimeToTimestamp(payload.end_time) : null;
+            if (!startTs || !endTs) {
+              return json({ error: "start_time 和 end_time 必须为带时区的 ISO 8601 / RFC 3339 时间。" });
+            }
+            const response = await client.invoke(
+              "feishu_calendar_event.instance_view",
+              (sdk, opts) =>
+                sdk.calendar.calendarEvent.instanceView(
+                  {
+                    path: { calendar_id: calendarId },
+                    params: {
+                      start_time: startTs,
+                      end_time: endTs,
+                      page_size: payload.page_size,
+                      page_token: payload.page_token,
+                      user_id_type: "open_id" as never,
+                    },
+                  },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            const items =
+              ((response.data as { items?: Array<Record<string, unknown>> } | undefined)?.items ?? []).map(
+                normalizeEventTimes,
+              );
+            return json({
+              events: items,
+              has_more: (response.data as { has_more?: boolean } | undefined)?.has_more ?? false,
+              page_token: (response.data as { page_token?: string } | undefined)?.page_token,
+            });
+          }
+
+          if (payload.action === "get") {
+            const response = await client.invoke(
+              "feishu_calendar_event.get",
+              (sdk, opts) =>
+                sdk.calendar.calendarEvent.get(
+                  { path: { calendar_id: calendarId, event_id: payload.event_id! } },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({ event: normalizeEventTimes((response.data as { event?: Record<string, unknown> } | undefined)?.event) });
+          }
+
+          if (payload.action === "patch") {
+            const updateData: Record<string, unknown> = {};
+            if (payload.summary) updateData.summary = payload.summary;
+            if (payload.description) updateData.description = payload.description;
+            if (payload.location) updateData.location = { name: payload.location };
+            if (payload.start_time) {
+              const startTs = parseTimeToTimestamp(payload.start_time);
+              if (!startTs) return json({ error: "start_time 必须为带时区的 ISO 8601 / RFC 3339 时间。" });
+              updateData.start_time = { timestamp: startTs };
+            }
+            if (payload.end_time) {
+              const endTs = parseTimeToTimestamp(payload.end_time);
+              if (!endTs) return json({ error: "end_time 必须为带时区的 ISO 8601 / RFC 3339 时间。" });
+              updateData.end_time = { timestamp: endTs };
+            }
+            const response = await client.invoke(
+              "feishu_calendar_event.patch",
+              (sdk, opts) =>
+                sdk.calendar.calendarEvent.patch(
+                  {
+                    path: { calendar_id: calendarId, event_id: payload.event_id! },
+                    data: updateData,
+                  },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({ event: normalizeEventTimes((response.data as { event?: Record<string, unknown> } | undefined)?.event) });
+          }
+
+          const response = await client.invoke(
+            "feishu_calendar_event.delete",
+            (sdk, opts) =>
+              sdk.calendar.calendarEvent.delete(
+                {
+                  path: { calendar_id: calendarId, event_id: payload.event_id! },
+                  params: { need_notification: payload.need_notification ?? true },
+                },
+                opts,
+              ),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({ success: true, event_id: payload.event_id });
+        } catch (error) {
+          return handleInvokeError(error, api);
+        }
+      },
+    },
+    { name: "feishu_calendar_event" },
+  );
+}

package/src/calendar-freebusy.ts

@@ -0,0 +1,58 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, parseTimeToRFC3339, registerTool } from "./user-tool-helpers.js";
+
+const CalendarFreebusySchema = Type.Object({
+  action: Type.Literal("list"),
+  user_ids: Type.Array(Type.String()),
+  time_min: Type.String(),
+  time_max: Type.String(),
+});
+
+export function registerFeishuCalendarFreebusyTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_freebusy");
+  registerTool(api, {
+    name: "feishu_calendar_freebusy",
+    label: "Feishu Calendar Freebusy",
+    description: "按本人身份查询 1-10 位用户在一段时间内的忙闲状态。",
+    parameters: CalendarFreebusySchema,
+    async execute(_toolCallId, params) {
+      const payload = params as { action: "list"; user_ids: string[]; time_min: string; time_max: string };
+      try {
+        if (!payload.user_ids?.length || payload.user_ids.length > 10) {
+          return json({ error: "user_ids 必须是 1-10 个用户 open_id。" });
+        }
+        const timeMin = parseTimeToRFC3339(payload.time_min);
+        const timeMax = parseTimeToRFC3339(payload.time_max);
+        if (!timeMin || !timeMax) {
+          return json({ error: "time_min 和 time_max 必须是带时区的 RFC 3339 时间。" });
+        }
+        const client = toolClient();
+        const response = await client.invoke(
+          "feishu_calendar_freebusy.list",
+          (sdk, opts) =>
+            sdk.calendar.freebusy.batch(
+              {
+                data: {
+                  time_min: timeMin,
+                  time_max: timeMax,
+                  user_ids: payload.user_ids,
+                  include_external_calendar: true,
+                  only_busy: true,
+                } as never,
+              },
+              opts,
+            ),
+          { as: "user" },
+        );
+        assertLarkOk(response);
+        return json({
+          freebusy_lists:
+            (response.data as { freebusy_lists?: unknown[] } | undefined)?.freebusy_lists ?? [],
+        });
+      } catch (error) {
+        return handleInvokeError(error, api);
+      }
+    },
+  }, { name: "feishu_calendar_freebusy" });
+}