Feishu Sheet

feishu-sheet

模块兼容：所有脚本均提供 .js 和 .mjs 两个版本。优先使用 .js，若报 require is not defined 错误则改用同名 .mjs 文件。

直接用 exec 执行，不要检查文件或环境。

获取表格信息（info）

node ./sheet.js --open-id "ou_xxx" --action info --url "https://xxx.feishu.cn/sheets/TOKEN"

返回表格标题、spreadsheet_token、全部工作表列表（含 sheet_id、行列数）。支持知识库 wiki URL 自动解析。

读取数据（read）

node ./sheet.js --open-id "ou_xxx" --action read --url "https://..."
node ./sheet.js --open-id "ou_xxx" --action read --url "https://..." --sheet-id "0b4f38"
node ./sheet.js --open-id "ou_xxx" --action read --url "https://..." --range "0b4f38!A1:D20"

不填 --range 和 --sheet-id 时自动读取第一个工作表全部数据（最多 200 行）。

覆盖写入（write）⚠️ 高危

node ./sheet.js --open-id "ou_xxx" --action write --url "https://..." \
  --range "0b4f38!A1:B2" --values '[["姓名","年龄"],["张三",25]]'

会覆盖 range 内已有数据，调用前必须向用户确认写入范围和内容。

追加行（append）

node ./sheet.js --open-id "ou_xxx" --action append --url "https://..." \
  --values '[["张三","工程","2026-01-01"]]'
node ./sheet.js --open-id "ou_xxx" --action append --url "https://..." \
  --sheet-id "0b4f38" --values '[["row1col1","row1col2"]]'

在已有数据末尾追加，不覆盖原有内容。

查找单元格（find）

node ./sheet.js --open-id "ou_xxx" --action find --url "https://..." \
  --sheet-id "0b4f38" --find "关键词"
node ./sheet.js --open-id "ou_xxx" --action find --url "https://..." \
  --sheet-id "0b4f38" --find "^张" --search-by-regex true

可选：--range "A1:D100" --match-case true --match-entire-cell true --search-by-regex true --include-formulas true

创建表格（create）

node ./sheet.js --open-id "ou_xxx" --action create --title "员工花名册"
node ./sheet.js --open-id "ou_xxx" --action create --title "员工花名册" \
  --folder-token "TOKEN" \
  --headers '["姓名","部门","入职日期"]' \
  --data '[["张三","工程","2026-01-01"],["李四","产品","2026-02-01"]]'

导出文件（export）

node ./sheet.js --open-id "ou_xxx" --action export --url "https://..." --file-extension xlsx
node ./sheet.js --open-id "ou_xxx" --action export --url "https://..." \
  --file-extension csv --sheet-id "0b4f38" --output-path "data.csv"

CSV 导出时 --sheet-id 必填（一次只能导出一个工作表）。

参数总览

典型场景

• 查看表格结构 → info（先获取 sheet_id，再进行后续操作）
• 读取全表 → read（不指定 range，自动读第一个工作表）
• 批量写入 → 先 info 确认工作表，再 write 或 append
• 搜索某个值在哪行 → find
• 新建并初始化 → create + --headers + --data

授权

若返回 {"error":"auth_required"} 或 {"error":"permission_required"}，不要询问用户是否授权，直接立即执行以下命令发送授权链接：

• 若返回 JSON 中包含 required_scopes 字段，将其数组值用空格拼接后传入 --scope 参数：

node ../feishu-auth/auth.js --auth-and-poll --open-id "SENDER_OPEN_ID" --chat-id "CHAT_ID" --timeout 60 --scope "<required_scopes 用空格拼接>"

• 若返回中不包含 required_scopes，则不加 --scope 参数（使用默认权限）。

• {"status":"authorized"} → 重新执行原始命令

• {"status":"polling_timeout"} → 立即重新执行此 auth 命令（不会重复发卡片）

• CHAT_ID 不知道可省略

权限不足时（应用级）

若返回中包含 "auth_type":"tenant"，说明需要管理员在飞书开放平台开通应用权限，必须将 reply 字段内容原样发送给用户。