飞书多维表格 API 操作

为 AI 大模型提供处理飞书多维表格的完整能力，支持操作数据表、记录、字段和素材。

技能开发者的环境

node --version v24.13.0

⚠️ 重要：关于代码混淆

本技能的 scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理。

AI 行为准则

✅ 可以执行：直接调用和执行这些脚本，使用 --parameter-file-path 传递参数

❌ 不要读取：不要读取或分析 scripts/ 目录下的 .js 文件内容，原因：

混淆代码可读性极差，无实际意义
避免浪费 token 和时间
所有功能说明已在本文档和 references/ 目录中完整描述

遇到问题时

参考 references/ 目录下的文档
查看脚本输出的错误信息和错误码
不要尝试阅读混淆代码

🎯 触发映射：用户说 → AI 做

用户输入触发词	AI 执行动作	对应脚本
"查看记录"/"获取记录"/"列出记录"	运行 `record/get.js` 查询记录列表	`scripts/record/get.js`
"添加记录"/"创建记录"/"插入记录"	运行 `record/create.js` 创建单条记录	`scripts/record/create.js`
"修改记录"/"更新记录"/"编辑记录"	运行 `record/update.js` 更新单条记录	`scripts/record/update.js`
"删除记录"/"移除记录"	运行 `record/delete.js` 删除单条记录	`scripts/record/delete.js`
"批量添加记录"/"添加多条记录"	运行 `record/batch-create.js` 批量创建记录	`scripts/record/batch-create.js`
"批量修改记录"/"更新多条记录"	运行 `record/batch-update.js` 批量更新记录	`scripts/record/batch-update.js`
"批量删除记录"/"清空记录"	运行 `record/batch-delete.js` 批量删除记录	`scripts/record/batch-delete.js`
"查看表格"/"数据表列表"	运行 `table/list.js` 列出所有数据表	`scripts/table/list.js`
"创建表格"/"添加数据表"	运行 `table/create-single.js` 创建单个数据表	`scripts/table/create-single.js`
"修改表格名称"/"重命名表格"	运行 `table/update.js` 更新数据表名称	`scripts/table/update.js`
"删除表格"/"移除数据表"	运行 `table/delete-one.js` 删除单个数据表	`scripts/table/delete-one.js`
"查看字段"/"列信息"	运行 `field/list.js` 列出所有字段	`scripts/field/list.js`
"添加字段"/"新列"	运行 `field/create.js` 创建字段	`scripts/field/create.js`
"修改字段"/"修改列"	运行 `field/update.js` 更新字段	`scripts/field/update.js`
"删除字段"/"移除列"	运行 `field/delete.js` 删除字段	`scripts/field/delete.js`
"上传文件"/"上传图片"/"上传附件"	运行 `media/upload.js` 上传素材	`scripts/media/upload.js`
"获取下载链接"/"获取直链"	运行 `media/file-token-to-url.js` 获取文件URL	`scripts/media/file-token-to-url.js`

决策流程

用户请求涉及飞书多维表格？
    │
    ├─ 是 → 检查具体操作类型
    │       │
    │       ├─ 需要访问凭证？
    │       │   └─ 运行 get-tenant-access-token.js
    │       │
    │       ├─ 需要从URL解析信息？
    │       │   └─ 运行 parse-bitable-url.js
    │       │
    │       └─ 执行具体操作
    │           ├─ 数据表操作 → table/ 脚本
    │           ├─ 记录操作 → record/ 脚本
    │           ├─ 字段操作 → field/ 脚本
    │           └─ 素材操作 → media/ 脚本
    │
    └─ 否 → 不使用此 Skill

如何使用这个 Skill

功能概述

本 Skill 提供完整的飞书多维表格 API 操作能力：

功能模块	支持的操作
数据表管理	创建、更新、删除数据表（支持批量操作）
记录操作	增删改查记录，支持批量操作（单次最多 1000 条）
字段管理	创建、更新、删除字段，列出所有字段
素材上传	上传文件、图片等素材，获取临时下载链接

输出格式

执行完成后，Skill 会输出：

成功：返回操作结果数据（JSON 格式），包含完整的 API 响应
失败：返回错误信息，包含错误码和解决建议

前置要求

有效的 tenant_access_token：所有 API 操作都需要
app_token：标识要操作的多维表格
table_id：标识要操作的数据表（部分操作需要）

参数传递方式

注意：本 Skill 所有脚本均使用 --parameter-file-path 参数传递配置，必须通过参数文件方式调用。

AI 调用规范：本 Skill 专为 AI 设计，AI 自动处理临时文件的创建和清理，人类用户只需用自然语言描述需求。

AI 自动处理临时文件流程

AI 调用本 Skill 时，必须遵循以下流程自动管理临时文件：

import { createTempParamsFile, cleanupTempFile } from "./scripts/utils";
import { execSync } from "child_process";

// 1. 创建临时参数文件（自动存放在系统临时目录）
const tempFile = createTempParamsFile(
  {
    tenant_access_token: "xxx",
    app_token: "xxx",
    table_id: "xxx"
    // ... 其他参数
  },
  "operation-name"
);

try {
  // 2. 执行脚本
  const result = execSync(`node scripts/xxx.js --parameter-file-path "${tempFile}"`, { encoding: "utf-8" });
  const data = JSON.parse(result);

  // 3. 处理结果并返回给用户
  return formatResultForUser(data);
} finally {
  // 4. 确保清理临时文件（无论成功或失败）
  cleanupTempFile(tempFile);
}

关键原则：

✅ 临时文件必须创建在系统临时目录（os.tmpdir()）
✅ 脚本执行完成后立即清理临时文件
✅ 使用 try...finally 确保即使出错也会清理
❌ 不要将参数文件创建在技能目录或用户工作目录

标准使用流程

步骤 1：获取访问凭证

node scripts/get-tenant-access-token.js --parameter-file-path params.json

参数文件示例 (params.json):

{
  "appId": "cli_xxx",
  "appSecret": "xxx"
}

详细凭证管理规则参见认证与凭证管理指南。

步骤 2：解析多维表格 URL

从 URL 中提取 app_token 和 table_id：

node scripts/parse-bitable-url.js --parameter-file-path params.json

步骤 3：执行具体操作

根据需求选择对应的脚本：

# 查询记录
node scripts/record/get.js --parameter-file-path "params.json"

# 创建记录
node scripts/record/create.js --parameter-file-path "params.json"

# 批量创建记录
node scripts/record/batch-create.js --parameter-file-path "params.json"

核心概念

概念	说明
多维表格 (Bitable)	字节跳动的产品，结合电子表格的灵活性和数据库的结构化特性
数据表 (Table)	多维表格中的单个表格，类似 Excel 工作表
记录 (Record)	数据表中的一行数据
字段 (Field)	数据表中的一列的表头，用于设定该列的数据类型
素材 (Media)	上传的文件、图片、视频等

操作接口速查

基础操作

Action	脚本路径	说明
获取访问凭证	get-tenant-access-token.js	获取 `tenant_access_token`
解析飞书多维表格的URL	parse-bitable-url.js	从 URL 提取 `app_token`、`table_id`、`view_id`

数据表操作

Action	脚本路径	说明
新增一个数据表	create-single.js	支持指定名称、视图和字段
新增多个数据表	batch-create.js	仅可指定数据表名称
更新数据表名称	update.js	更新指定数据表的名称
列出数据表	list.js	获取所有数据表的 ID、版本号和名称
删除一个数据表	delete-one.js	通过 `app_token` 和 `table_id` 删除
删除多个数据表	batch-delete.js	批量删除多个数据表

详细参数参见 table 参考文档目录。

记录操作

Action	脚本路径	说明
新增记录	create.js	在数据表中新增一条记录
更新记录	update.js	更新数据表中的一条记录
查询记录	get.js	单次最多查询 500 行，支持分页
删除记录	delete.js	删除数据表中的一条记录
新增多条记录	batch-create.js	单次最多新增 1,000 条
更新多条记录	batch-update.js	单次最多更新 1,000 条
批量获取记录	batch-get.js	通过记录 ID 查询，最多 100 条
删除多条记录	batch-delete.js	批量删除多条记录

详细参数参见 record 参考文档目录。

字段操作

Action	脚本路径	说明
新增字段	create.js	在数据表中新增一个字段
更新字段	update.js	全量更新字段（property 会被覆盖）
列出字段	list.js	获取数据表中的所有字段
删除字段	delete.js	删除数据表中的一个字段

详细参数参见 field 参考文档目录。

素材/文件操作

Action	脚本路径	说明
素材上传	upload.js	上传文件、图片、视频等素材
获取直链	file-token-to-url.js	`file_token` 转临时下载链接（24小时有效）

详细参数参见 media 参考文档目录。

文件和目录使用说明

项目	说明
文档位置	`references/` 目录下的文档，有具体的 API 调用命令或脚本执行方式
脚本位置	`scripts/` 目录下的 Node.js 脚本直接使用
临时文件	系统临时目录 (`%TEMP%` 或 `/tmp`)，操作完成后自动删除
参数文件	系统临时目录，使用绝对路径引用
上传记录	系统临时目录 (`feishu-bitable-upload-records.json`)

临时文件管理最佳实践

本技能所有临时文件（参数文件、上传记录）均存放在系统临时目录，避免污染用户主目录和技能目录：

Windows 示例：

C:\Users\xxx\AppData\Local\Temp\feishu-create-record-1740374400000-a7x9k2.json
C:\Users\xxx\AppData\Local\Temp\feishu-bitable-upload-records.json

Linux/Mac 示例：

/tmp/feishu-create-record-1740374400000-a7x9k2.json
/tmp/feishu-bitable-upload-records.json

工具函数使用示例

import { createTempParamsFile, cleanupTempFile, cleanupAllTempFiles } from './utils';

// 1. 创建临时参数文件（自动存放在系统临时目录）
const params = {
  tenant_access_token: 'xxx',
  app_token: 'xxx',
  table_id: 'xxx',
  fields: { ... }
};
const tempFilePath = createTempParamsFile(params, 'create-record');

// 2. 执行脚本
const result = await executeScript(tempFilePath);

// 3. 立即清理临时文件
cleanupTempFile(tempFilePath);

// 4. 清理所有过期的临时文件（24小时前的）
cleanupAllTempFiles();

临时文件命名规范：

格式：feishu-{operation}-{timestamp}-{random}.json
示例：feishu-batch-create-1740374400000-a7x9k2.json

清理策略：

成功或失败都立即尝试删除参数文件
删除失败不影响主流程
系统临时目录自动定期清理
运行 cleanupAllTempFiles() 批量清理过期文件（24小时前）

AI 处理示例

用户说："帮我在飞书表格 https://xxx.feishu.cn/wiki/xxx 里添加一条记录，任务名称是'完成报告'，进度50%"

AI 执行步骤：

步骤	执行动作	脚本/命令
1	检查 tenant_access_token	如无则运行 `get-tenant-access-token.js`
2	解析 URL 获取 app_token 和 table_id	运行 `parse-bitable-url.js`
3	创建临时参数文件	运行 `createTempParamsFile()`，存放在系统临时目录
4	创建记录	运行 `record/create.js`
5	清理临时参数文件	运行 `cleanupTempFile()`
6	返回结果	向用户返回："已成功创建记录！记录ID: recxxx"

用户感知：完全不需要知道临时文件的存在，只需自然语言交互。

错误处理

错误场景	错误表现	处理方式
缺少访问凭证	API 返回 401/403 错误	运行 `get-tenant-access-token.js` 获取凭证
访问凭证过期	API 返回错误代码: 99991663, 错误信息: Invalid access token for authorization	运行 `get-tenant-access-token.js` 获取凭证
URL 解析失败	无法提取 app_token/table_id	检查 URL 格式是否正确，或手动提供参数
记录不存在	API 返回 404 错误	检查 record_id 是否正确，或先运行 `record/get.js` 查询
字段类型不匹配	API 返回 400 错误	运行 `field/list.js` 查看字段类型，调整参数后重试
文本字段格式错误	`TextFieldConvFail` 错误	文本字段使用字符串格式，不要用富文本数组格式
字段更新缺少参数	`field validation failed`	更新字段时必须提供 `type` 参数
文件token格式错	`Cannot read properties`	使用 `file_tokens`（数组）而非 `file_token`（字符串）
批量操作超限	API 返回 422 错误	减少单次操作数量（记录最多1000条，批量获取最多100条）
临时文件创建失败	磁盘空间不足或权限问题	检查系统临时目录权限和磁盘空间
网络超时	请求无响应	检查网络连接，稍后重试

常见错误详解

1. 文本字段格式错误 (TextFieldConvFail)

错误信息：the value of 'Multiline' must be a string

原因：创建/更新记录时，文本字段使用了查询返回的富文本数组格式

解决：

❌ 错误："字段名": [{"text": "内容", "type": "text"}]
✅ 正确："字段名": "内容"

2. 字段更新缺少 type 参数

错误信息：field validation failed - type is required

原因：更新字段时未提供 type 参数

解决：更新字段时必须包含 type，如 "type": 1（1=文本, 2=数字）

3. 获取文件下载链接参数错误

错误信息：Cannot read properties of undefined (reading 'map')

原因：使用了 file_token 而不是 file_tokens

解决：

❌ 错误："file_token": "xxx"
✅ 正确："file_tokens": ["xxx"]

参考文档

文档	说明
认证与凭证管理指南	详细的凭证管理说明，包括 App ID/App Secret 获取、tenant_access_token 自动获取流程
获取访问凭证 API	获取 tenant_access_token 的具体 API 调用说明和脚本使用方法
解析飞书 URL 工具	从飞书多维表格 URL 中提取 app_token、table_id、view_id 的工具使用说明
常见错误及解决方案	API 调用常见错误码及排查方法
参数配置示例与最佳实践	各种操作场景的参数配置示例