feishu-bitable

飞书多维表格 API 操作

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

环境检查

"node": ">=20.20.1"

⚠️ 重要：关于代码混淆

本技能的 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 响应
• 失败：返回错误信息，包含错误码和解决建议

前置要求

1. 有效的 tenant_access_token：所有 API 操作都需要
2. app_token：标识要操作的多维表格
3. 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 パラメータを指定する必要があります
ファイルトークンの形式が正しくない	Cannot read properties が発生します	file_token（文字列）ではなく file_tokens（配列）を使います
一括操作の上限超過	API が 422 エラーを返します	1 回の操作件数を減らしてください（レコードは最大 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": 1（1=テキスト、2=数値）のように type を含める必要があります

3. ファイルのダウンロードリンク取得時のパラメータエラー

エラーメッセージ：Cannot read properties of undefined (reading 'map')

原因：file_tokens ではなく file_token を使用しています

解決方法：

• ❌ 誤り："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 调用常见错误码及排查方法
参数配置示例与最佳实践	各种操作场景的参数配置示例