@lark-project/openclaw-lark-project 2026.3.131

package/dist/src/tools/oapi/sheets/sheet.js

@@ -0,0 +1,652 @@
+import { Type } from "@sinclair/typebox";
+import {
+  json,
+  createToolContext,
+  assertLarkOk,
+  handleInvokeErrorWithAutoAuth
+} from "../helpers";
+import * as fs from "fs/promises";
+import * as path from "path";
+const MAX_READ_ROWS = 200;
+const MAX_WRITE_ROWS = 5e3;
+const MAX_WRITE_COLS = 100;
+const EXPORT_POLL_INTERVAL_MS = 1e3;
+const EXPORT_POLL_MAX_RETRIES = 30;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseSheetUrl(url) {
+  try {
+    const u = new URL(url);
+    const match = u.pathname.match(/\/(?:sheets|wiki)\/([^/?#]+)/);
+    if (!match) return null;
+    return {
+      token: match[1],
+      sheetId: u.searchParams.get("sheet") || void 0
+    };
+  } catch {
+    return null;
+  }
+}
+const KNOWN_TOKEN_TYPES = /* @__PURE__ */ new Set([
+  "dox",
+  "doc",
+  "sht",
+  "bas",
+  "app",
+  "sld",
+  "bmn",
+  "fld",
+  "nod",
+  "box",
+  "jsn",
+  "img",
+  "isv",
+  "wik",
+  "wia",
+  "wib",
+  "wic",
+  "wid",
+  "wie",
+  "dsb"
+]);
+function getTokenType(token) {
+  if (token.length >= 15) {
+    const prefix = token[4] + token[9] + token[14];
+    if (KNOWN_TOKEN_TYPES.has(prefix)) return prefix;
+  }
+  if (token.length >= 3) {
+    const prefix = token.substring(0, 3);
+    if (KNOWN_TOKEN_TYPES.has(prefix)) return prefix;
+  }
+  return null;
+}
+async function resolveToken(p, client, log) {
+  let token;
+  let urlSheetId;
+  if (p.spreadsheet_token) {
+    token = p.spreadsheet_token;
+  } else if (p.url) {
+    const parsed = parseSheetUrl(p.url);
+    if (!parsed) {
+      throw new Error(`Failed to parse spreadsheet_token from URL: ${p.url}`);
+    }
+    token = parsed.token;
+    urlSheetId = parsed.sheetId;
+  } else {
+    throw new Error("url or spreadsheet_token is required");
+  }
+  const tokenType = getTokenType(token);
+  if (tokenType === "wik") {
+    log.info(`resolveToken: detected wiki token, resolving obj_token...`);
+    const wikiNodeRes = await client.invoke(
+      "feishu_sheet.info",
+      (sdk, opts) => sdk.wiki.space.getNode(
+        {
+          params: {
+            token,
+            obj_type: "wiki"
+          }
+        },
+        opts
+      ),
+      { as: "user" }
+    );
+    assertLarkOk(wikiNodeRes);
+    const objToken = wikiNodeRes.data?.node?.obj_token;
+    if (!objToken) {
+      throw new Error(`Failed to resolve spreadsheet token from wiki token: ${token}`);
+    }
+    log.info(`resolveToken: wiki resolved ${token} -> ${objToken}`);
+    token = objToken;
+  }
+  return { token, urlSheetId };
+}
+async function resolveRange(token, range, sheetId, client, apiName) {
+  if (range) return range;
+  if (sheetId) return sheetId;
+  const sheetsRes = await client.invoke(
+    apiName,
+    (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts),
+    { as: "user" }
+  );
+  assertLarkOk(sheetsRes);
+  const firstSheet = (sheetsRes.data?.sheets ?? [])[0];
+  if (!firstSheet?.sheet_id) {
+    throw new Error("spreadsheet has no worksheets");
+  }
+  return firstSheet.sheet_id;
+}
+function colLetter(n) {
+  let result = "";
+  while (n > 0) {
+    n--;
+    result = String.fromCharCode(65 + n % 26) + result;
+    n = Math.floor(n / 26);
+  }
+  return result;
+}
+function flattenCellValue(cell) {
+  if (!Array.isArray(cell)) return cell;
+  if (cell.length > 0 && cell.every((seg) => seg != null && typeof seg === "object" && "text" in seg)) {
+    return cell.map((seg) => seg.text).join("");
+  }
+  return cell;
+}
+function flattenValues(values) {
+  if (!values) return values;
+  return values.map((row) => row.map(flattenCellValue));
+}
+function truncateRows(values, maxRows) {
+  if (!values) return { values, truncated: false, total_rows: 0 };
+  const total = values.length;
+  if (total <= maxRows) return { values, truncated: false, total_rows: total };
+  return { values: values.slice(0, maxRows), truncated: true, total_rows: total };
+}
+const UrlOrToken = [
+  Type.Optional(
+    Type.String({
+      description: "\u7535\u5B50\u8868\u683C URL\uFF0C\u4F8B\u5982 https://xxx.feishu.cn/sheets/TOKEN \u6216 https://xxx.feishu.cn/wiki/TOKEN\uFF08\u4E0E spreadsheet_token \u4E8C\u9009\u4E00\uFF09"
+    })
+  ),
+  Type.Optional(
+    Type.String({
+      description: "\u7535\u5B50\u8868\u683C token\uFF08\u4E0E url \u4E8C\u9009\u4E00\uFF09"
+    })
+  )
+];
+const ValueRenderOption = Type.Optional(
+  Type.Union(
+    [
+      Type.Literal("ToString"),
+      Type.Literal("FormattedValue"),
+      Type.Literal("Formula"),
+      Type.Literal("UnformattedValue")
+    ],
+    {
+      description: "\u503C\u6E32\u67D3\u65B9\u5F0F\uFF1AToString\uFF08\u9ED8\u8BA4\uFF09\u3001FormattedValue\uFF08\u6309\u683C\u5F0F\uFF09\u3001Formula\uFF08\u516C\u5F0F\uFF09\u3001UnformattedValue\uFF08\u539F\u59CB\u503C\uFF09"
+    }
+  )
+);
+const FeishuSheetSchema = Type.Union([
+  // INFO
+  Type.Object({
+    action: Type.Literal("info"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1]
+  }),
+  // READ
+  Type.Object({
+    action: Type.Literal("read"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1],
+    range: Type.Optional(
+      Type.String({
+        description: "\u8BFB\u53D6\u8303\u56F4\uFF08\u53EF\u9009\uFF09\u3002\u683C\u5F0F\uFF1A<sheetId>!A1:D10 \u6216 <sheetId>\uFF08sheetId \u901A\u8FC7 info \u83B7\u53D6\uFF09\u3002\u4E0D\u586B\u5219\u81EA\u52A8\u8BFB\u53D6\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868\u5168\u90E8\u6570\u636E"
+      })
+    ),
+    sheet_id: Type.Optional(
+      Type.String({
+        description: "\u5DE5\u4F5C\u8868 ID\uFF08\u53EF\u9009\uFF09\u3002\u4EC5\u5F53\u4E0D\u63D0\u4F9B range \u65F6\u751F\u6548\uFF0C\u6307\u5B9A\u8981\u8BFB\u53D6\u7684\u5DE5\u4F5C\u8868\u3002\u4E0D\u586B\u5219\u8BFB\u53D6\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868"
+      })
+    ),
+    value_render_option: ValueRenderOption
+  }),
+  // WRITE
+  Type.Object({
+    action: Type.Literal("write"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1],
+    range: Type.Optional(
+      Type.String({
+        description: "\u5199\u5165\u8303\u56F4\uFF08\u53EF\u9009\uFF09\u3002\u683C\u5F0F\uFF1A<sheetId>!A1:D10\uFF08sheetId \u901A\u8FC7 info \u83B7\u53D6\uFF09\u3002\u4E0D\u586B\u5219\u5199\u5165\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868\uFF08\u4ECE A1 \u5F00\u59CB\uFF09"
+      })
+    ),
+    sheet_id: Type.Optional(
+      Type.String({
+        description: "\u5DE5\u4F5C\u8868 ID\uFF08\u53EF\u9009\uFF09\u3002\u4EC5\u5F53\u4E0D\u63D0\u4F9B range \u65F6\u751F\u6548\u3002\u4E0D\u586B\u5219\u4F7F\u7528\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868"
+      })
+    ),
+    values: Type.Array(Type.Array(Type.Any()), {
+      description: '\u4E8C\u7EF4\u6570\u7EC4\uFF0C\u6BCF\u4E2A\u5143\u7D20\u662F\u4E00\u884C\u3002\u4F8B\u5982 [["\u59D3\u540D","\u5E74\u9F84"],["\u5F20\u4E09",25]]'
+    })
+  }),
+  // APPEND
+  Type.Object({
+    action: Type.Literal("append"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1],
+    range: Type.Optional(
+      Type.String({
+        description: "\u8FFD\u52A0\u8303\u56F4\uFF08\u53EF\u9009\uFF09\u3002\u683C\u5F0F\u540C write\u3002\u4E0D\u586B\u5219\u8FFD\u52A0\u5230\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868\u672B\u5C3E"
+      })
+    ),
+    sheet_id: Type.Optional(
+      Type.String({
+        description: "\u5DE5\u4F5C\u8868 ID\uFF08\u53EF\u9009\uFF09\u3002\u4EC5\u5F53\u4E0D\u63D0\u4F9B range \u65F6\u751F\u6548"
+      })
+    ),
+    values: Type.Array(Type.Array(Type.Any()), {
+      description: "\u8981\u8FFD\u52A0\u7684\u4E8C\u7EF4\u6570\u7EC4\u6570\u636E"
+    })
+  }),
+  // FIND
+  Type.Object({
+    action: Type.Literal("find"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1],
+    sheet_id: Type.String({
+      description: "\u5DE5\u4F5C\u8868 ID\uFF08\u5FC5\u586B\uFF0C\u53EF\u901A\u8FC7 info action \u83B7\u53D6\uFF09"
+    }),
+    find: Type.String({
+      description: "\u67E5\u627E\u5185\u5BB9\uFF08\u5B57\u7B26\u4E32\u6216\u6B63\u5219\u8868\u8FBE\u5F0F\uFF09"
+    }),
+    range: Type.Optional(
+      Type.String({
+        description: "\u67E5\u627E\u8303\u56F4\u3002\u683C\u5F0F\uFF1AA1:D10\uFF08\u4E0D\u542B sheetId \u524D\u7F00\uFF09\u3002\u4E0D\u586B\u5219\u641C\u7D22\u6574\u4E2A\u5DE5\u4F5C\u8868"
+      })
+    ),
+    match_case: Type.Optional(Type.Boolean({ description: "\u662F\u5426\u533A\u5206\u5927\u5C0F\u5199\uFF08\u9ED8\u8BA4 true\uFF09" })),
+    match_entire_cell: Type.Optional(Type.Boolean({ description: "\u662F\u5426\u5B8C\u5168\u5339\u914D\u6574\u4E2A\u5355\u5143\u683C\uFF08\u9ED8\u8BA4 false\uFF09" })),
+    search_by_regex: Type.Optional(Type.Boolean({ description: "\u662F\u5426\u4F7F\u7528\u6B63\u5219\u8868\u8FBE\u5F0F\uFF08\u9ED8\u8BA4 false\uFF09" })),
+    include_formulas: Type.Optional(Type.Boolean({ description: "\u662F\u5426\u641C\u7D22\u516C\u5F0F\uFF08\u9ED8\u8BA4 false\uFF09" }))
+  }),
+  // CREATE
+  Type.Object({
+    action: Type.Literal("create"),
+    title: Type.String({
+      description: "\u7535\u5B50\u8868\u683C\u6807\u9898"
+    }),
+    folder_token: Type.Optional(
+      Type.String({
+        description: "\u6587\u4EF6\u5939 token\uFF08\u53EF\u9009\uFF09\u3002\u4E0D\u586B\u65F6\u521B\u5EFA\u5230\u300C\u6211\u7684\u7A7A\u95F4\u300D\u6839\u76EE\u5F55"
+      })
+    ),
+    headers: Type.Optional(
+      Type.Array(Type.String(), {
+        description: '\u8868\u5934\u5217\u540D\uFF08\u53EF\u9009\uFF09\u3002\u4F8B\u5982 ["\u59D3\u540D", "\u90E8\u95E8", "\u5165\u804C\u65E5\u671F"]\u3002\u63D0\u4F9B\u540E\u4F1A\u5199\u5165\u7B2C\u4E00\u884C'
+      })
+    ),
+    data: Type.Optional(
+      Type.Array(Type.Array(Type.Any()), {
+        description: '\u521D\u59CB\u6570\u636E\uFF08\u53EF\u9009\uFF09\u3002\u4E8C\u7EF4\u6570\u7EC4\uFF0C\u5199\u5728\u8868\u5934\u4E4B\u540E\u3002\u4F8B\u5982 [["\u5F20\u4E09", "\u5DE5\u7A0B", "2026-01-01"]]'
+      })
+    )
+  }),
+  // EXPORT
+  Type.Object({
+    action: Type.Literal("export"),
+    url: UrlOrToken[0],
+    spreadsheet_token: UrlOrToken[1],
+    file_extension: Type.Union([Type.Literal("xlsx"), Type.Literal("csv")], {
+      description: "\u5BFC\u51FA\u683C\u5F0F\uFF1Axlsx \u6216 csv"
+    }),
+    output_path: Type.Optional(
+      Type.String({
+        description: "\u672C\u5730\u4FDD\u5B58\u8DEF\u5F84\uFF08\u542B\u6587\u4EF6\u540D\uFF09\u3002\u4E0D\u586B\u5219\u53EA\u8FD4\u56DE\u6587\u4EF6\u4FE1\u606F"
+      })
+    ),
+    sheet_id: Type.Optional(
+      Type.String({
+        description: "\u5DE5\u4F5C\u8868 ID\u3002\u5BFC\u51FA CSV \u65F6\u5FC5\u586B\uFF08CSV \u4E00\u6B21\u53EA\u80FD\u5BFC\u51FA\u4E00\u4E2A\u5DE5\u4F5C\u8868\uFF09\uFF0C\u5BFC\u51FA xlsx \u65F6\u53EF\u9009"
+      })
+    )
+  })
+]);
+function registerFeishuSheetTool(api) {
+  if (!api.config) return;
+  const cfg = api.config;
+  const { toolClient, log } = createToolContext(api, "feishu_sheet");
+  api.registerTool(
+    {
+      name: "feishu_sheet",
+      label: "Feishu Spreadsheet",
+      description: "\u3010\u4EE5\u7528\u6237\u8EAB\u4EFD\u3011\u98DE\u4E66\u7535\u5B50\u8868\u683C\u5DE5\u5177\u3002\u652F\u6301\u521B\u5EFA\u3001\u8BFB\u5199\u3001\u67E5\u627E\u3001\u5BFC\u51FA\u7535\u5B50\u8868\u683C\u3002\n\n\u7535\u5B50\u8868\u683C\uFF08Sheets\uFF09\u7C7B\u4F3C Excel/Google Sheets\uFF0C\u4E0E\u591A\u7EF4\u8868\u683C\uFF08Bitable/Airtable\uFF09\u662F\u4E0D\u540C\u4EA7\u54C1\u3002\n\n\u6240\u6709 action\uFF08\u9664 create \u5916\uFF09\u5747\u652F\u6301\u4F20\u5165 url \u6216 spreadsheet_token\uFF0C\u5DE5\u5177\u4F1A\u81EA\u52A8\u89E3\u6790\u3002\u652F\u6301\u77E5\u8BC6\u5E93 wiki URL\uFF0C\u81EA\u52A8\u89E3\u6790\u4E3A\u7535\u5B50\u8868\u683C token\u3002\n\nActions:\n- info\uFF1A\u83B7\u53D6\u8868\u683C\u4FE1\u606F + \u5168\u90E8\u5DE5\u4F5C\u8868\u5217\u8868\uFF08\u4E00\u6B21\u8C03\u7528\u66FF\u4EE3 get_info + list_sheets\uFF09\n- read\uFF1A\u8BFB\u53D6\u6570\u636E\u3002\u4E0D\u586B range \u81EA\u52A8\u8BFB\u53D6\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868\u5168\u90E8\u6570\u636E\n- write\uFF1A\u8986\u76D6\u5199\u5165,\u9AD8\u5371,\u8BF7\u8C28\u614E\u4F7F\u7528\u8BE5\u64CD\u4F5C\u3002\u4E0D\u586B range \u81EA\u52A8\u5199\u5165\u7B2C\u4E00\u4E2A\u5DE5\u4F5C\u8868\uFF08\u4ECE A1 \u5F00\u59CB\uFF09\n- append\uFF1A\u5728\u5DF2\u6709\u6570\u636E\u672B\u5C3E\u8FFD\u52A0\u884C\n- find\uFF1A\u5728\u5DE5\u4F5C\u8868\u4E2D\u67E5\u627E\u5355\u5143\u683C\n- create\uFF1A\u521B\u5EFA\u7535\u5B50\u8868\u683C\u3002\u652F\u6301\u5E26 headers + data \u4E00\u6B65\u521B\u5EFA\u542B\u6570\u636E\u7684\u8868\u683C\n- export\uFF1A\u5BFC\u51FA\u4E3A xlsx \u6216 csv\uFF08csv \u5FC5\u987B\u6307\u5B9A sheet_id\uFF09",
+      parameters: FeishuSheetSchema,
+      async execute(_toolCallId, params) {
+        const p = params;
+        try {
+          const client = toolClient();
+          switch (p.action) {
+            // -----------------------------------------------------------------
+            // INFO — 表格信息 + 全部工作表列表
+            // -----------------------------------------------------------------
+            case "info": {
+              const { token } = await resolveToken(p, client, log);
+              log.info(`info: token=${token}`);
+              const [spreadsheetRes, sheetsRes] = await Promise.all([
+                client.invoke(
+                  "feishu_sheet.info",
+                  (sdk, opts) => sdk.sheets.spreadsheet.get({ path: { spreadsheet_token: token } }, opts),
+                  { as: "user" }
+                ),
+                client.invoke(
+                  "feishu_sheet.info",
+                  (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts),
+                  { as: "user" }
+                )
+              ]);
+              assertLarkOk(spreadsheetRes);
+              assertLarkOk(sheetsRes);
+              const spreadsheet = spreadsheetRes.data?.spreadsheet;
+              const sheets = (sheetsRes.data?.sheets ?? []).map((s) => ({
+                sheet_id: s.sheet_id,
+                title: s.title,
+                index: s.index,
+                row_count: s.grid_properties?.row_count,
+                column_count: s.grid_properties?.column_count,
+                frozen_row_count: s.grid_properties?.frozen_row_count,
+                frozen_column_count: s.grid_properties?.frozen_column_count
+              }));
+              log.info(`info: title="${spreadsheet?.title}", ${sheets.length} sheets`);
+              return json({
+                title: spreadsheet?.title,
+                spreadsheet_token: token,
+                url: `https://www.feishu.cn/sheets/${token}`,
+                sheets
+              });
+            }
+            // -----------------------------------------------------------------
+            // READ — 读取数据（支持自动探测范围）
+            // -----------------------------------------------------------------
+            case "read": {
+              const { token, urlSheetId } = await resolveToken(p, client, log);
+              const range = await resolveRange(token, p.range, p.sheet_id ?? urlSheetId, client, "feishu_sheet.read");
+              log.info(`read: token=${token}, range=${range}`);
+              const query = {
+                // 默认返回计算后的值（而非公式原文），日期转为可读字符串
+                valueRenderOption: p.value_render_option ?? "ToString",
+                dateTimeRenderOption: "FormattedString"
+              };
+              const res = await client.invokeByPath(
+                "feishu_sheet.read",
+                `/open-apis/sheets/v2/spreadsheets/${token}/values/${encodeURIComponent(range)}`,
+                { method: "GET", query, as: "user" }
+              );
+              if (res.code && res.code !== 0) {
+                return json({ error: res.msg || `API error code: ${res.code}` });
+              }
+              const valueRange = res.data?.valueRange;
+              const { values, truncated, total_rows } = truncateRows(flattenValues(valueRange?.values), MAX_READ_ROWS);
+              log.info(`read: ${total_rows} rows${truncated ? ` (truncated to ${MAX_READ_ROWS})` : ""}`);
+              return json({
+                range: valueRange?.range,
+                values,
+                ...truncated ? {
+                  truncated: true,
+                  total_rows,
+                  hint: `Data exceeds ${MAX_READ_ROWS} rows, truncated. Please narrow the range and read again.`
+                } : {}
+              });
+            }
+            // -----------------------------------------------------------------
+            // WRITE — 覆盖写入（支持自动 range）
+            // -----------------------------------------------------------------
+            case "write": {
+              const { token, urlSheetId } = await resolveToken(p, client, log);
+              if (p.values && p.values.length > MAX_WRITE_ROWS) {
+                return json({ error: `write row count ${p.values.length} exceeds limit ${MAX_WRITE_ROWS}` });
+              }
+              if (p.values && p.values.some((row) => Array.isArray(row) && row.length > MAX_WRITE_COLS)) {
+                return json({ error: `write column count exceeds limit ${MAX_WRITE_COLS}` });
+              }
+              const range = await resolveRange(token, p.range, p.sheet_id ?? urlSheetId, client, "feishu_sheet.write");
+              log.info(`write: token=${token}, range=${range}, rows=${p.values?.length}`);
+              const res = await client.invokeByPath("feishu_sheet.write", `/open-apis/sheets/v2/spreadsheets/${token}/values`, {
+                method: "PUT",
+                body: { valueRange: { range, values: p.values } },
+                as: "user"
+              });
+              if (res.code && res.code !== 0) {
+                return json({ error: res.msg || `API error code: ${res.code}` });
+              }
+              log.info(`write: updated ${res.data?.updatedCells ?? 0} cells`);
+              return json({
+                updated_range: res.data?.updatedRange,
+                updated_rows: res.data?.updatedRows,
+                updated_columns: res.data?.updatedColumns,
+                updated_cells: res.data?.updatedCells,
+                revision: res.data?.revision
+              });
+            }
+            // -----------------------------------------------------------------
+            // APPEND — 追加行
+            // -----------------------------------------------------------------
+            case "append": {
+              const { token, urlSheetId } = await resolveToken(p, client, log);
+              if (p.values && p.values.length > MAX_WRITE_ROWS) {
+                return json({ error: `append row count ${p.values.length} exceeds limit ${MAX_WRITE_ROWS}` });
+              }
+              const range = await resolveRange(token, p.range, p.sheet_id ?? urlSheetId, client, "feishu_sheet.append");
+              log.info(`append: token=${token}, range=${range}, rows=${p.values?.length}`);
+              const res = await client.invokeByPath("feishu_sheet.append", `/open-apis/sheets/v2/spreadsheets/${token}/values_append`, {
+                method: "POST",
+                body: { valueRange: { range, values: p.values } },
+                as: "user"
+              });
+              if (res.code && res.code !== 0) {
+                return json({ error: res.msg || `API error code: ${res.code}` });
+              }
+              const updates = res.data?.updates;
+              log.info(`append: updated ${updates?.updatedCells ?? 0} cells`);
+              return json({
+                table_range: res.data?.tableRange,
+                updated_range: updates?.updatedRange,
+                updated_rows: updates?.updatedRows,
+                updated_columns: updates?.updatedColumns,
+                updated_cells: updates?.updatedCells,
+                revision: updates?.revision
+              });
+            }
+            // -----------------------------------------------------------------
+            // FIND — 查找单元格
+            // -----------------------------------------------------------------
+            case "find": {
+              const { token } = await resolveToken(p, client, log);
+              log.info(`find: token=${token}, sheet_id=${p.sheet_id}, find="${p.find}"`);
+              const findCondition = {
+                range: p.range ? `${p.sheet_id}!${p.range}` : p.sheet_id
+              };
+              if (p.match_case !== void 0) findCondition.match_case = !p.match_case;
+              if (p.match_entire_cell !== void 0) findCondition.match_entire_cell = p.match_entire_cell;
+              if (p.search_by_regex !== void 0) findCondition.search_by_regex = p.search_by_regex;
+              if (p.include_formulas !== void 0) findCondition.include_formulas = p.include_formulas;
+              const res = await client.invoke(
+                "feishu_sheet.find",
+                (sdk, opts) => sdk.sheets.spreadsheetSheet.find(
+                  {
+                    path: {
+                      spreadsheet_token: token,
+                      sheet_id: p.sheet_id
+                    },
+                    data: {
+                      find_condition: findCondition,
+                      find: p.find
+                    }
+                  },
+                  opts
+                ),
+                { as: "user" }
+              );
+              assertLarkOk(res);
+              const findResult = res.data?.find_result;
+              log.info(`find: matched ${findResult?.matched_cells?.length ?? 0} cells`);
+              return json({
+                matched_cells: findResult?.matched_cells,
+                matched_formula_cells: findResult?.matched_formula_cells,
+                rows_count: findResult?.rows_count
+              });
+            }
+            // -----------------------------------------------------------------
+            // CREATE — 创建电子表格（支持带初始数据）
+            // -----------------------------------------------------------------
+            case "create": {
+              log.info(
+                `create: title="${p.title}", folder=${p.folder_token ?? "(root)"}, headers=${!!p.headers}, data=${p.data?.length ?? 0} rows`
+              );
+              const createRes = await client.invoke(
+                "feishu_sheet.create",
+                (sdk, opts) => sdk.sheets.spreadsheet.create(
+                  {
+                    data: {
+                      title: p.title,
+                      folder_token: p.folder_token
+                    }
+                  },
+                  opts
+                ),
+                { as: "user" }
+              );
+              assertLarkOk(createRes);
+              const spreadsheet = createRes.data?.spreadsheet;
+              const token = spreadsheet?.spreadsheet_token;
+              if (!token) {
+                return json({ error: "failed to create spreadsheet: no token returned" });
+              }
+              const url = `https://www.feishu.cn/sheets/${token}`;
+              log.info(`create: token=${token}`);
+              if (p.headers || p.data) {
+                const allRows = [];
+                if (p.headers) allRows.push(p.headers);
+                if (p.data) allRows.push(...p.data);
+                if (allRows.length > 0) {
+                  const sheetsRes = await client.invoke(
+                    "feishu_sheet.create",
+                    (sdk, opts) => sdk.sheets.spreadsheetSheet.query({ path: { spreadsheet_token: token } }, opts),
+                    { as: "user" }
+                  );
+                  assertLarkOk(sheetsRes);
+                  const firstSheet = (sheetsRes.data?.sheets ?? [])[0];
+                  if (firstSheet?.sheet_id) {
+                    const sheetId = firstSheet.sheet_id;
+                    const numRows = allRows.length;
+                    const numCols = Math.max(...allRows.map((r) => r.length));
+                    const range = `${sheetId}!A1:${colLetter(numCols)}${numRows}`;
+                    log.info(`create: writing ${numRows} rows to ${range}`);
+                    const writeRes = await client.invokeByPath(
+                      "feishu_sheet.create",
+                      `/open-apis/sheets/v2/spreadsheets/${token}/values`,
+                      {
+                        method: "PUT",
+                        body: { valueRange: { range, values: allRows } },
+                        as: "user"
+                      }
+                    );
+                    if (writeRes.code && writeRes.code !== 0) {
+                      log.info(`create: initial data write failed: ${writeRes.msg}`);
+                      return json({
+                        spreadsheet_token: token,
+                        url,
+                        warning: `spreadsheet created but failed to write initial data: ${writeRes.msg}`
+                      });
+                    }
+                  }
+                }
+              }
+              return json({
+                spreadsheet_token: token,
+                title: p.title,
+                url
+              });
+            }
+            // -----------------------------------------------------------------
+            // EXPORT — 导出为 xlsx/csv
+            // -----------------------------------------------------------------
+            case "export": {
+              const { token } = await resolveToken(p, client, log);
+              if (p.file_extension === "csv" && !p.sheet_id) {
+                return json({
+                  error: "sheet_id is required for CSV export (CSV can only export one worksheet at a time). Use info action to get the worksheet list."
+                });
+              }
+              log.info(`export: token=${token}, format=${p.file_extension}, output=${p.output_path ?? "(info only)"}`);
+              const createRes = await client.invoke(
+                "feishu_sheet.export",
+                (sdk, opts) => sdk.drive.exportTask.create(
+                  {
+                    data: {
+                      file_extension: p.file_extension,
+                      token,
+                      type: "sheet",
+                      sub_id: p.sheet_id
+                    }
+                  },
+                  opts
+                ),
+                { as: "user" }
+              );
+              assertLarkOk(createRes);
+              const ticket = createRes.data?.ticket;
+              if (!ticket) {
+                return json({ error: "failed to create export task: no ticket returned" });
+              }
+              log.info(`export: ticket=${ticket}`);
+              let fileToken;
+              let fileName;
+              let fileSize;
+              for (let i = 0; i < EXPORT_POLL_MAX_RETRIES; i++) {
+                await sleep(EXPORT_POLL_INTERVAL_MS);
+                const pollRes = await client.invoke(
+                  "feishu_sheet.export",
+                  (sdk, opts) => sdk.drive.exportTask.get({ path: { ticket }, params: { token } }, opts),
+                  { as: "user" }
+                );
+                assertLarkOk(pollRes);
+                const result = pollRes.data?.result;
+                const jobStatus = result?.job_status;
+                if (jobStatus === 0) {
+                  fileToken = result?.file_token;
+                  fileName = result?.file_name;
+                  fileSize = result?.file_size;
+                  log.info(`export: done, file_token=${fileToken}, size=${fileSize}`);
+                  break;
+                }
+                if (jobStatus !== void 0 && jobStatus >= 3) {
+                  return json({ error: result?.job_error_msg || `export failed (status=${jobStatus})` });
+                }
+                log.info(`export: polling ${i + 1}/${EXPORT_POLL_MAX_RETRIES}, status=${jobStatus}`);
+              }
+              if (!fileToken) {
+                return json({ error: "export timeout: task did not complete within 30 seconds" });
+              }
+              if (p.output_path) {
+                const dlRes = await client.invoke(
+                  "feishu_sheet.export",
+                  (sdk, opts) => sdk.drive.exportTask.download({ path: { file_token: fileToken } }, opts),
+                  { as: "user" }
+                );
+                const stream = dlRes.getReadableStream();
+                const chunks = [];
+                for await (const chunk of stream) {
+                  chunks.push(chunk);
+                }
+                await fs.mkdir(path.dirname(p.output_path), { recursive: true });
+                await fs.writeFile(p.output_path, Buffer.concat(chunks));
+                log.info(`export: saved to ${p.output_path}`);
+                return json({
+                  file_path: p.output_path,
+                  file_name: fileName,
+                  file_size: fileSize
+                });
+              }
+              return json({
+                file_token: fileToken,
+                file_name: fileName,
+                file_size: fileSize,
+                hint: "File exported. Provide output_path parameter to download locally."
+              });
+            }
+          }
+        } catch (err) {
+          return await handleInvokeErrorWithAutoAuth(err, cfg);
+        }
+      }
+    },
+    { name: "feishu_sheet" }
+  );
+  api.logger.info?.("feishu_sheet: Registered feishu_sheet tool");
+}
+export {
+  registerFeishuSheetTool
+};
+//# sourceMappingURL=sheet.js.map