@nextclaw/channel-plugin-feishu 0.2.16 → 0.2.17

package/src/oauth.ts

@@ -0,0 +1,248 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { requestDeviceAuthorization, pollDeviceToken } from "./device-flow.js";
+import { feishuFetch } from "./feishu-fetch.js";
+import { getTicket } from "./lark-ticket.js";
+import { getStoredToken, setStoredToken, tokenStatus } from "./token-store.js";
+import { resolveAnyEnabledFeishuToolsConfig } from "./tool-account.js";
+import { revokeUAT } from "./uat-client.js";
+import { createUserToolClient } from "./user-tool-client.js";
+import { jsonToolResult } from "./tool-result.js";
+import { getAllKnownScopes } from "./tool-scopes.js";
+
+const FeishuOAuthSchema = Type.Object({
+  action: Type.Union([
+    Type.Literal("authorize"),
+    Type.Literal("status"),
+    Type.Literal("revoke"),
+  ]),
+  scope: Type.Optional(
+    Type.String({
+      description: "可选，自定义 scope 空格串；不传时默认申请当前集成能力需要的全部高价值 scope。",
+    }),
+  ),
+  wait_seconds: Type.Optional(
+    Type.Integer({
+      description: "authorize 后轮询等待秒数，默认 15，最大 60。",
+      minimum: 0,
+      maximum: 60,
+    }),
+  ),
+});
+
+function json(data: unknown) {
+  return jsonToolResult(data);
+}
+
+async function verifyTokenIdentity(
+  domain: "feishu" | "lark" | (string & {}),
+  accessToken: string,
+  expectedOpenId: string,
+): Promise<{ valid: boolean; actualOpenId?: string }> {
+  const baseUrl = domain === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn";
+  const response = await feishuFetch(`${baseUrl}/open-apis/authen/v1/user_info`, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+  const data = (await response.json()) as {
+    code?: number;
+    data?: { open_id?: string };
+  };
+  const actualOpenId = data.data?.open_id;
+  return {
+    valid: data.code === 0 && actualOpenId === expectedOpenId,
+    actualOpenId,
+  };
+}
+
+async function handleOAuthStatus(params: {
+  appId: string;
+  senderOpenId: string;
+}) {
+  const stored = await getStoredToken(params.appId, params.senderOpenId);
+  if (!stored) {
+    return json({
+      authorized: false,
+      user_open_id: params.senderOpenId,
+    });
+  }
+  return json({
+    authorized: true,
+    user_open_id: params.senderOpenId,
+    scope: stored.scope,
+    token_status: tokenStatus(stored),
+    granted_at: new Date(stored.grantedAt).toISOString(),
+    expires_at: new Date(stored.expiresAt).toISOString(),
+    refresh_expires_at: new Date(stored.refreshExpiresAt).toISOString(),
+  });
+}
+
+async function handleOAuthRevoke(params: {
+  appId: string;
+  senderOpenId: string;
+}) {
+  await revokeUAT(params.appId, params.senderOpenId);
+  return json({
+    success: true,
+    user_open_id: params.senderOpenId,
+    message: "当前用户的飞书 OAuth 授权已撤销。",
+  });
+}
+
+async function handleOAuthAuthorize(params: {
+  account: ReturnType<typeof createUserToolClient>["account"];
+  senderOpenId: string;
+  scope?: string;
+  waitSeconds?: number;
+}) {
+  const scope = params.scope?.trim() || getAllKnownScopes().join(" ");
+  const waitSeconds = Math.min(Math.max(params.waitSeconds ?? 15, 0), 60);
+  const deviceFlow = await requestDeviceAuthorization({
+    appId: params.account.appId,
+    appSecret: params.account.appSecret,
+    domain: params.account.domain,
+    scope,
+  });
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), waitSeconds * 1000);
+  try {
+    const result = await pollDeviceToken({
+      appId: params.account.appId,
+      appSecret: params.account.appSecret,
+      domain: params.account.domain,
+      deviceCode: deviceFlow.deviceCode,
+      interval: deviceFlow.interval,
+      expiresIn: deviceFlow.expiresIn,
+      signal: controller.signal,
+    });
+
+    if (!result.ok) {
+      return json({
+        authorized: false,
+        status: result.error,
+        message: result.message,
+        user_open_id: params.senderOpenId,
+        verification_uri: deviceFlow.verificationUri,
+        verification_uri_complete: deviceFlow.verificationUriComplete,
+        user_code: deviceFlow.userCode,
+        requested_scope: scope,
+      });
+    }
+
+    const verified = await verifyTokenIdentity(
+      params.account.domain,
+      result.token.accessToken,
+      params.senderOpenId,
+    );
+    if (!verified.valid) {
+      return json({
+        authorized: false,
+        status: "identity_mismatch",
+        message: "完成授权的飞书账号与当前消息发送者不一致，已拒绝写入令牌。",
+        expected_open_id: params.senderOpenId,
+        actual_open_id: verified.actualOpenId,
+      });
+    }
+
+    const now = Date.now();
+    await setStoredToken({
+      userOpenId: params.senderOpenId,
+      appId: params.account.appId,
+      accessToken: result.token.accessToken,
+      refreshToken: result.token.refreshToken,
+      expiresAt: now + result.token.expiresIn * 1000,
+      refreshExpiresAt: now + result.token.refreshExpiresIn * 1000,
+      scope: result.token.scope,
+      grantedAt: now,
+    });
+    return json({
+      authorized: true,
+      user_open_id: params.senderOpenId,
+      scope: result.token.scope,
+      expires_at: new Date(now + result.token.expiresIn * 1000).toISOString(),
+      message: "飞书 OAuth 授权成功，后续工具将按当前用户身份执行。",
+    });
+  } catch (error) {
+    if (!controller.signal.aborted) {
+      throw error;
+    }
+    return json({
+      authorized: false,
+      status: "authorization_pending",
+      message:
+        "授权请求已创建，但在等待窗口内尚未完成。请打开链接完成授权后重新调用 feishu_oauth status 或再次 authorize。",
+      user_open_id: params.senderOpenId,
+      verification_uri: deviceFlow.verificationUri,
+      verification_uri_complete: deviceFlow.verificationUriComplete,
+      user_code: deviceFlow.userCode,
+      requested_scope: scope,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function registerFeishuOAuthTool(api: OpenClawPluginApi) {
+  if (!api.config) {
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    return;
+  }
+
+  const toolsConfig = resolveAnyEnabledFeishuToolsConfig(accounts);
+  if (!toolsConfig.oauth) {
+    return;
+  }
+
+  api.registerTool(
+    {
+      name: "feishu_oauth",
+      label: "Feishu OAuth",
+      description:
+        "管理当前消息发送者的飞书 OAuth 授权。支持 authorize/status/revoke，授权后 calendar/task/sheets/identity 工具即可按本人身份执行。",
+      parameters: FeishuOAuthSchema,
+      async execute(_toolCallId, params) {
+        const payload = params as {
+          action: "authorize" | "status" | "revoke";
+          scope?: string;
+          wait_seconds?: number;
+        };
+
+        const ticket = getTicket();
+        const senderOpenId = ticket?.senderOpenId;
+        if (!senderOpenId) {
+          return json({
+            error: "missing_sender_identity",
+            message: "当前不在飞书消息上下文中，无法按本人身份管理 OAuth。",
+          });
+        }
+
+        try {
+          const client = createUserToolClient(api.config);
+          const account = client.account;
+          if (payload.action === "status") {
+            return handleOAuthStatus({ appId: account.appId, senderOpenId });
+          }
+          if (payload.action === "revoke") {
+            return handleOAuthRevoke({ appId: account.appId, senderOpenId });
+          }
+          return handleOAuthAuthorize({
+            account,
+            senderOpenId,
+            scope: payload.scope,
+            waitSeconds: payload.wait_seconds,
+          });
+        } catch (error) {
+          return json({
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      },
+    },
+    { name: "feishu_oauth" },
+  );
+}

package/src/raw-request.ts

@@ -0,0 +1,45 @@
+import { feishuFetch } from "./feishu-fetch.js";
+import { resolveDomainUrl } from "./domains.js";
+import type { FeishuDomain } from "./types.js";
+
+export async function rawLarkRequest<T>(options: {
+  domain: FeishuDomain;
+  path: string;
+  method?: string;
+  body?: unknown;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  accessToken?: string;
+}): Promise<T> {
+  const url = new URL(options.path, resolveDomainUrl(options.domain));
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    url.searchParams.set(key, value);
+  }
+
+  const headers: Record<string, string> = {
+    ...(options.headers ?? {}),
+  };
+  if (options.accessToken) {
+    headers.Authorization = `Bearer ${options.accessToken}`;
+  }
+  if (options.body !== undefined && !headers["Content-Type"]) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  const response = await feishuFetch(url.toString(), {
+    method: options.method ?? "GET",
+    headers,
+    ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+  });
+  const data = (await response.json()) as { code?: number; msg?: string };
+  if (data.code !== undefined && data.code !== 0) {
+    const error = new Error(data.msg ?? `Feishu API error: code=${data.code}`) as Error & {
+      code?: number;
+      msg?: string;
+    };
+    error.code = data.code;
+    error.msg = data.msg;
+    throw error;
+  }
+  return data as T;
+}

package/src/sheets.ts

@@ -0,0 +1,374 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { wwwDomain } from "./domains.js";
+import { resolveAnyEnabledFeishuToolsConfig } from "./tool-account.js";
+import {
+  assertLarkOk,
+  createToolContext,
+  handleInvokeError,
+  json,
+  registerTool,
+  StringEnum,
+} from "./user-tool-helpers.js";
+
+const MAX_READ_ROWS = 200;
+const MAX_WRITE_ROWS = 5000;
+const MAX_WRITE_COLS = 100;
+
+const SheetSchema = Type.Union([
+  Type.Object({ action: Type.Literal("info"), url: Type.Optional(Type.String()), spreadsheet_token: Type.Optional(Type.String()) }),
+  Type.Object({
+    action: Type.Literal("read"),
+    url: Type.Optional(Type.String()),
+    spreadsheet_token: Type.Optional(Type.String()),
+    range: Type.Optional(Type.String()),
+    sheet_id: Type.Optional(Type.String()),
+    value_render_option: Type.Optional(StringEnum(["FormattedValue", "UnformattedValue", "Formula", "ToString"])),
+  }),
+  Type.Object({
+    action: Type.Literal("write"),
+    url: Type.Optional(Type.String()),
+    spreadsheet_token: Type.Optional(Type.String()),
+    range: Type.Optional(Type.String()),
+    sheet_id: Type.Optional(Type.String()),
+    values: Type.Array(Type.Array(Type.Any())),
+  }),
+  Type.Object({
+    action: Type.Literal("append"),
+    url: Type.Optional(Type.String()),
+    spreadsheet_token: Type.Optional(Type.String()),
+    range: Type.Optional(Type.String()),
+    sheet_id: Type.Optional(Type.String()),
+    values: Type.Array(Type.Array(Type.Any())),
+  }),
+  Type.Object({
+    action: Type.Literal("find"),
+    url: Type.Optional(Type.String()),
+    spreadsheet_token: Type.Optional(Type.String()),
+    sheet_id: Type.String(),
+    range: Type.Optional(Type.String()),
+    find: Type.String(),
+    match_case: Type.Optional(Type.Boolean()),
+    match_entire_cell: Type.Optional(Type.Boolean()),
+    search_by_regex: Type.Optional(Type.Boolean()),
+    include_formulas: Type.Optional(Type.Boolean()),
+  }),
+  Type.Object({
+    action: Type.Literal("create"),
+    title: Type.String(),
+    folder_token: Type.Optional(Type.String()),
+    headers: Type.Optional(Type.Array(Type.Any())),
+    data: Type.Optional(Type.Array(Type.Array(Type.Any()))),
+  }),
+  Type.Object({
+    action: Type.Literal("export"),
+    url: Type.Optional(Type.String()),
+    spreadsheet_token: Type.Optional(Type.String()),
+    sheet_id: Type.Optional(Type.String()),
+    file_extension: StringEnum(["xlsx", "csv"]),
+  }),
+]);
+
+function parseSheetUrl(url: string): { token: string; sheetId?: string } | null {
+  try {
+    const parsed = new URL(url);
+    const match = parsed.pathname.match(/\/sheets\/([^/?#]+)/);
+    if (!match) {
+      return null;
+    }
+    return {
+      token: match[1],
+      sheetId: parsed.searchParams.get("sheet") || undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveToken(params: { url?: string; spreadsheet_token?: string }) {
+  if (params.spreadsheet_token) {
+    return { token: params.spreadsheet_token };
+  }
+  if (params.url) {
+    return parseSheetUrl(params.url);
+  }
+  return null;
+}
+
+function colLetter(n: number): string {
+  let result = "";
+  let value = n;
+  while (value > 0) {
+    value -= 1;
+    result = String.fromCharCode(65 + (value % 26)) + result;
+    value = Math.floor(value / 26);
+  }
+  return result;
+}
+
+function flattenCellValue(cell: unknown): unknown {
+  if (!Array.isArray(cell)) {
+    return cell;
+  }
+  if (cell.length > 0 && cell.every((segment) => segment && typeof segment === "object" && "text" in (segment as object))) {
+    return cell.map((segment) => String((segment as { text?: unknown }).text ?? "")).join("");
+  }
+  return cell;
+}
+
+async function resolveSheetRange(
+  client: ReturnType<typeof createToolContext>["toolClient"] extends () => infer T ? T : never,
+  token: string,
+  range?: string,
+  sheetId?: string,
+) {
+  if (range) return range;
+  if (sheetId) return sheetId;
+  const response = await client.invoke(
+    "feishu_sheet.info",
+    (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts),
+    { as: "user" },
+  );
+  assertLarkOk(response);
+  const firstSheet = (response.data as { sheets?: Array<{ sheet_id?: string }> } | undefined)?.sheets?.[0];
+  if (!firstSheet?.sheet_id) {
+    throw new Error("Spreadsheet has no worksheets.");
+  }
+  return firstSheet.sheet_id;
+}
+
+export function registerFeishuSheetsTools(api: OpenClawPluginApi) {
+  if (!api.config) return;
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) return;
+  if (!resolveAnyEnabledFeishuToolsConfig(accounts).sheets) return;
+
+  registerTool(api, {
+    name: "feishu_sheet",
+    label: "Feishu Sheet",
+    description: "按本人身份读取、写入、创建、查找和导出飞书电子表格。",
+    parameters: SheetSchema,
+    async execute(_toolCallId, params) {
+      const payload = params as any;
+      try {
+        const client = createToolContext(api, "feishu_sheet").toolClient();
+
+        if (payload.action === "create") {
+          const createResponse = await client.invoke(
+            "feishu_sheet.create",
+            (sdk, opts) =>
+              sdk.sheets.spreadsheet.create(
+                {
+                  data: {
+                    title: payload.title,
+                    folder_token: payload.folder_token,
+                  },
+                },
+                opts,
+              ),
+            { as: "user" },
+          );
+          assertLarkOk(createResponse);
+          const spreadsheet = (createResponse.data as { spreadsheet?: { spreadsheet_token?: string; title?: string } } | undefined)?.spreadsheet;
+          const token = spreadsheet?.spreadsheet_token;
+          if (!token) {
+            return json({ error: "创建电子表格失败，未返回 spreadsheet_token。" });
+          }
+          if (payload.headers || payload.data) {
+            const sheetsResponse = await client.invoke(
+              "feishu_sheet.create",
+              (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts),
+              { as: "user" },
+            );
+            assertLarkOk(sheetsResponse);
+            const firstSheet = (sheetsResponse.data as { sheets?: Array<{ sheet_id?: string }> } | undefined)?.sheets?.[0];
+            const allRows = [
+              ...(payload.headers ? [payload.headers] : []),
+              ...((payload.data as unknown[][] | undefined) ?? []),
+            ];
+            if (firstSheet?.sheet_id && allRows.length > 0) {
+              const numCols = Math.max(...allRows.map((row) => row.length), 1);
+              const range = `${firstSheet.sheet_id}!A1:${colLetter(numCols)}${allRows.length}`;
+              await client.invokeByPath("feishu_sheet.create", `/open-apis/sheets/v2/spreadsheets/${token}/values`, {
+                method: "PUT",
+                body: { valueRange: { range, values: allRows } },
+                as: "user",
+              });
+            }
+          }
+          return json({
+            spreadsheet_token: token,
+            title: spreadsheet?.title ?? payload.title,
+            url: `${wwwDomain(client.account.domain)}/sheets/${token}`,
+          });
+        }
+
+        const tokenInfo = resolveToken(payload);
+        if (!tokenInfo?.token) {
+          return json({ error: "请传 spreadsheet_token 或 /sheets/TOKEN 形式的 url。" });
+        }
+
+        if (payload.action === "info") {
+          const [spreadsheetRes, sheetsRes] = await Promise.all([
+            client.invoke(
+              "feishu_sheet.info",
+              (sdk, opts) => sdk.sheets.spreadsheet.get({ path: { spreadsheet_token: tokenInfo.token } }, opts),
+              { as: "user" },
+            ),
+            client.invoke(
+              "feishu_sheet.info",
+              (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: tokenInfo.token } }, opts),
+              { as: "user" },
+            ),
+          ]);
+          assertLarkOk(spreadsheetRes);
+          assertLarkOk(sheetsRes);
+          return json({
+            title: (spreadsheetRes.data as { spreadsheet?: { title?: string } } | undefined)?.spreadsheet?.title,
+            spreadsheet_token: tokenInfo.token,
+            url: `${wwwDomain(client.account.domain)}/sheets/${tokenInfo.token}`,
+            sheets:
+              ((sheetsRes.data as { sheets?: Array<Record<string, unknown>> } | undefined)?.sheets ?? []).map((sheet) => ({
+                sheet_id: sheet.sheet_id,
+                title: sheet.title,
+                index: sheet.index,
+                row_count: (sheet.grid_properties as { row_count?: number } | undefined)?.row_count,
+                column_count: (sheet.grid_properties as { column_count?: number } | undefined)?.column_count,
+              })),
+          });
+        }
+
+        if (payload.action === "read") {
+          const range = await resolveSheetRange(client, tokenInfo.token, payload.range, payload.sheet_id ?? tokenInfo.sheetId);
+          const response = await client.invokeByPath<{
+            data?: { valueRange?: { range?: string; values?: unknown[][] } };
+          }>("feishu_sheet.read", `/open-apis/sheets/v2/spreadsheets/${tokenInfo.token}/values/${encodeURIComponent(range)}`, {
+            method: "GET",
+            query: {
+              valueRenderOption: payload.value_render_option ?? "ToString",
+              dateTimeRenderOption: "FormattedString",
+            },
+            as: "user",
+          });
+          const values = (response.data?.valueRange?.values ?? []).map((row) => row.map(flattenCellValue));
+          return json({
+            range: response.data?.valueRange?.range,
+            values: values.slice(0, MAX_READ_ROWS),
+            ...(values.length > MAX_READ_ROWS
+              ? {
+                  truncated: true,
+                  total_rows: values.length,
+                  hint: `结果超过 ${MAX_READ_ROWS} 行，已截断。请缩小 range 后重试。`,
+                }
+              : {}),
+          });
+        }
+
+        if (payload.action === "write" || payload.action === "append") {
+          if (payload.values.length > MAX_WRITE_ROWS) {
+            return json({ error: `写入行数超过限制 ${MAX_WRITE_ROWS}` });
+          }
+          if (payload.values.some((row: unknown[]) => row.length > MAX_WRITE_COLS)) {
+            return json({ error: `写入列数超过限制 ${MAX_WRITE_COLS}` });
+          }
+          const range = await resolveSheetRange(client, tokenInfo.token, payload.range, payload.sheet_id ?? tokenInfo.sheetId);
+          const response = await client.invokeByPath<any>(
+            payload.action === "write" ? "feishu_sheet.write" : "feishu_sheet.append",
+            `/open-apis/sheets/v2/spreadsheets/${tokenInfo.token}/${payload.action === "write" ? "values" : "values_append"}`,
+            {
+              method: payload.action === "write" ? "PUT" : "POST",
+              body: { valueRange: { range, values: payload.values } },
+              as: "user",
+            },
+          );
+          const updates = response.data?.updates ?? response.data;
+          return json({
+            updated_range: updates?.updatedRange,
+            updated_rows: updates?.updatedRows,
+            updated_columns: updates?.updatedColumns,
+            updated_cells: updates?.updatedCells,
+            revision: updates?.revision,
+          });
+        }
+
+        if (payload.action === "find") {
+          const response = await client.invoke(
+            "feishu_sheet.find",
+            (sdk, opts) =>
+              sdk.sheets.spreadsheetSheet.find(
+                {
+                  path: { spreadsheet_token: tokenInfo.token, sheet_id: payload.sheet_id },
+                  data: {
+                    find: payload.find,
+                    find_condition: {
+                      range: payload.range ? `${payload.sheet_id}!${payload.range}` : payload.sheet_id,
+                      ...(payload.match_case !== undefined ? { match_case: !payload.match_case } : {}),
+                      ...(payload.match_entire_cell !== undefined ? { match_entire_cell: payload.match_entire_cell } : {}),
+                      ...(payload.search_by_regex !== undefined ? { search_by_regex: payload.search_by_regex } : {}),
+                      ...(payload.include_formulas !== undefined ? { include_formulas: payload.include_formulas } : {}),
+                    },
+                  },
+                },
+                opts,
+              ),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({
+            matched_cells: (response.data as { find_result?: { matched_cells?: unknown[] } } | undefined)?.find_result?.matched_cells ?? [],
+            matched_formula_cells:
+              (response.data as { find_result?: { matched_formula_cells?: unknown[] } } | undefined)?.find_result?.matched_formula_cells ?? [],
+          });
+        }
+
+        const exportCreate = await client.invoke(
+          "feishu_sheet.export",
+          (sdk, opts) =>
+            sdk.drive.exportTask.create(
+              {
+                data: {
+                  file_extension: payload.file_extension,
+                  token: tokenInfo.token,
+                  type: "sheet",
+                  sub_id: payload.sheet_id,
+                },
+              },
+              opts,
+            ),
+          { as: "user" },
+        );
+        assertLarkOk(exportCreate);
+        const ticket = (exportCreate.data as { ticket?: string } | undefined)?.ticket;
+        if (!ticket) {
+          return json({ error: "导出任务创建失败，未返回 ticket。" });
+        }
+        for (let i = 0; i < 30; i += 1) {
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          const exportStatus = await client.invoke(
+            "feishu_sheet.export",
+            (sdk, opts) =>
+              sdk.drive.exportTask.get({ path: { ticket }, params: { token: tokenInfo.token } }, opts),
+            { as: "user" },
+          );
+          assertLarkOk(exportStatus);
+          const result = (exportStatus.data as { result?: { job_status?: number; file_token?: string; file_name?: string; file_size?: number; job_error_msg?: string } } | undefined)?.result;
+          if (result?.job_status === 0) {
+            return json({
+              file_token: result.file_token,
+              file_name: result.file_name,
+              file_size: result.file_size,
+              file_extension: payload.file_extension,
+            });
+          }
+          if ((result?.job_status ?? 0) >= 3) {
+            return json({ error: result?.job_error_msg ?? `导出失败 (status=${result?.job_status})` });
+          }
+        }
+        return json({ error: "导出任务超时，请稍后重试。" });
+      } catch (error) {
+        return handleInvokeError(error, api);
+      }
+    },
+  }, { name: "feishu_sheet" });
+}