feishu-bitable-yashu

name	feishu-bitable-yashu
description	操作飞书多维表格(Bitable)。激活条件：用户消息须包含以下关键词之一:`操作飞书多维表格`、`管理多维表格`、`操作飞书bitable`、`多维表格操作`、`bitable管理`。
metadata	{"author":"AI Assistant","updated":"2026-07-08 12:00:00","version":"1.0.0"}

飞书多维表格 API 操作

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

---

🚨🚨🚨 AI 调用任何脚本前必读 🚨🚨🚨

硬性规则：本文档中每一个 *.js 脚本的调用，必须先 Read 对应的 $SKILL_DIR/references/<功能>/<操作>.md 文档，再构造参数文件，最后才执行脚本。

此规则适用于本 skill 的所有 23 个脚本--包括"基础能力"的 get-tenant-access-token.js 和 parse-bitable-url.js，没有任何脚本是例外。

❌ 反面案例（真实发生，请勿重演）

2026-07-08 skill 真实测试阶段0 预检时，AI 看到 parse-bitable-url.js 是个"基础操作"，未先 Read $SKILL_DIR/references/parse_bitable_url.md 就凭类比其他脚本的经验写了参数文件：

// ❌ 错误：仅传 url，缺少 tenant_access_token
{ "url": "https://kr0lqjlbmo.feishu.cn/wiki/..." }

脚本直接返回错误：

错误: 参数文件中必须包含 tenant_access_token 和 url 字段

正确做法是 先 Read parse_bitable_url.md 第 24-26 行的参数表，明确知道两个字段都是必填。

核心教训："基础操作"不代表"可以凭直觉"。每个脚本的 schema 都是独立的、不可类推的，唯一可靠的来源是当下 Read 的文档。

✅ 调用脚本的强制三步走（每一步都不可跳过）

步骤	动作	是否可跳过	失败后果
1️⃣	Read references/<类别>/<操作>.md 完整文档	❌ 不可跳过	参数缺失/类型错误，浪费时间与 token
2️⃣	在内心或输出中声明"已读证明"：cite 出文档路径	❌ 不可跳过	无可审计性，跳过风险增大
3️⃣	严格按文档 JSON Schema 示例构造参数文件，再 cd $SKILL_DIR/scripts 执行	—	—

已读证明示例（在执行脚本前的输出中显式出现）：

> 已 Read references/record/create.md（行 22-156，JSON Schema）
> 已 Read references/record/create.md（行 162-193，文本字段格式警告）
> 准备构造参数文件并执行 record/create.js

⚠️ 触发"读文档"提示的强信号

只要你的内部推理出现以下任一信号，立即停止并去 Read 文档：

• 💭 "这个脚本我之前用过，应该用 xxx 字段" → 必须 Read
• 💭 "这是基础操作，凭经验写就行" → 必须 Read
• 💭 "和 xxx.js 应该差不多" → 必须 Read
• 💭 "参数我已经记得了" → 必须 Read

唯一可信赖的来源是当下 Read 的文档，不是过去的经验，不是其他脚本的类比。

---

功能概述

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

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

环境说明

• $SKILL_DIR：本 Skill 所在的绝对目录，即 SKILL.md 文件所在文件夹。⚠️ $SKILL_DIR 仅为文档占位符，不是环境变量：执行命令时必须替换为实际绝对路径。在 PowerShell 中直接写 $SKILL_DIR 会被当作未定义变量解析为空字符串，导致 cd $SKILL_DIR/scripts 变成 cd /scripts 而报错"找不到路径"
• Shell 类型：PowerShell 5（Windows）/ bash（Linux/Mac）。本 Skill 运行命令时采用条件执行（前一条成功才执行下一条），跨平台规则如下：
  • bash/zsh（Linux/macOS）：&&（如 cd $SKILL_DIR/scripts && node script.js）
  • PowerShell 5（Windows）：; if ($?) { }（如 cd $SKILL_DIR/scripts; if ($?) { node script.js }）
  • 禁止单 &：在 bash 中 & 表示后台执行，语义完全不同
• 脚本目录：$SKILL_DIR/scripts
• Node 版本：>=18.20.8
• 依赖安装：bash/zsh 用 cd $SKILL_DIR/scripts && npm install，PowerShell 用 cd $SKILL_DIR/scripts; if ($?) { npm install }
• 配置文件：$SKILL_DIR/config.default.json（存储 appId、appSecret、tenant_access_token，AI 可自动读写）

⚠️ 脚本已混淆，禁止读取源码

$SKILL_DIR/scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理，禁止读取或分析 .js 文件内容。混淆代码可读性极差，读取纯属浪费 token 和时间。

如需了解脚本功能和用法，请查阅下方「脚本清单」和 $SKILL_DIR/references/ 目录下的接口文档。

全局前置条件

所有 API 操作都需要以下前提：

前置条件	说明	获取方式
tenant_access_token	API 访问凭证，有效期 2 小时	运行 get-tenant-access-token.js
app_token	标识要操作的多维表格	运行 parse-bitable-url.js 从 URL 解析
table_id	标识要操作的数据表（部分操作需要）	运行 parse-bitable-url.js 或 table/list.js

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

跨功能公共规则

以下规则适用于本 Skill 所有脚本调用，必须严格遵守。

1. 执行前必须进入 scripts 目录

执行任何脚本前，必须先 cd 到 $SKILL_DIR/scripts 目录，再运行命令：

# bash/zsh
cd $SKILL_DIR/scripts && node record/get.js --parameter-file-path "参数文件绝对路径"

# PowerShell 5
cd $SKILL_DIR/scripts; if ($?) { node record/get.js --parameter-file-path "参数文件绝对路径" }

写法	是否允许
cd $SKILL_DIR/scripts && node record/get.js ... (bash) / cd $SKILL_DIR/scripts; if ($?) { node record/get.js ... } (PowerShell)	✅ 正确
node $SKILL_DIR/scripts/record/get.js ...	❌ 禁止
node scripts/record/get.js ...	❌ 禁止

2. 🚨 执行前必须读取对应参考文档（强制流程，不可跳过）

这是硬性要求，不是建议。 任何脚本调用前，必须先 Read 对应的参考文档，再构造参数文件。

强制执行流程：

步骤	动作	是否可跳过
1	Read 对应的参考文档（如 references/record/create.md）	❌ 不可跳过
2	复制文档中提供的完整 JSON Schema 示例	❌ 不可跳过
3	仅替换示例中的占位值为实际值，不增删任何字段	❌ 不可跳过
4	Write 参数文件到 $SKILL_DIR/temp/ 目录	—
5	执行脚本	—

禁止行为：

• ❌ 禁止凭记忆/直觉编写参数：例如「上次用过 record_ids，这次也用」是严重错误
• ❌ 禁止跳过步骤1直接编写参数：即使你"记得"参数格式，也必须先 Read 文档
• ❌ 禁止类比其他脚本推断字段：批量创建/更新/删除/获取的 records 字段格式各不相同，必须看文档

为什么必须这样做：

不同脚本的参数字段差异巨大，记忆不可靠：

脚本	关键参数	格式
record/batch-create.js	records	对象数组 [{"fields": {...}}]
record/batch-update.js	records	对象数组 [{"record_id": "x", "fields": {...}}]
record/batch-delete.js	records	字符串数组 ["recx", "recy"]
record/batch-get.js	record_ids	字符串数组 ["recx", "recy"]

仅凭记忆很容易把 record_ids、record_id 等搞错，唯一可靠的来源是当下 Read 的文档。

自检清单（执行每个脚本前在内心过一遍）：

• 我刚才 Read 了对应的参考文档吗？
• 我使用的字段名（不是 record_ids，而是 records）是否与文档 Schema 一致？
• 我使用的字段格式（字符串数组 vs 对象数组）是否与文档示例一致？

3. 参数通过文件传递

所有脚本均使用 --parameter-file-path 参数传递配置。参数文件必须使用绝对路径，路径分隔符使用正斜杠 /，包含空格时用双引号包裹。各脚本所需的参数字段不同，请阅读对应的参考文档获取字段说明。

4. 临时文件管理

AI 调用脚本时自动管理临时参数文件：

• 临时文件创建在 $SKILL_DIR/temp 目录
• 清理时机：调用技能完成用户需求后，或调用技能因报错终止后，运行 clear_temp.js 清理 temp 目录
• ❌ 不要将参数文件创建在 $SKILL_DIR/temp 以外的目录

详细临时文件管理流程、工具函数用法与参数配置示例参见 参数配置示例与最佳实践。

5. 🚨 禁止 PowerShell 写文件

AI 在执行本 Skill 过程中创建或修改任何文件（包括参数文件、配置文件等），必须使用 Write 工具。禁止使用任何 PowerShell 文件写入命令（Set-Content、Out-File、> 重定向、[System.IO.File]::WriteAllText() 等）。

原因：PowerShell 默认会在文件中添加 UTF-8 BOM（EF BB BF），这个不可见字符会导致：

• JSON：JSON.parse() 抛出 Unexpected token 异常
• JS：Node.js 无法加载带 BOM 的模块，报语法错误
• Markdown：frontmatter 解析失败，metadata 字段读取为 undefined

Write 工具不产生 BOM，是唯一安全的文件写入方式。

6. 输出格式

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

触发映射：用户说 → AI 做

⚠️ 执行任意一条前必须先 Read 表格最右列的文档——这是强制流程，不可跳过。

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

决策流程

流程图的核心改动：原流程是"想调用 → 直接调用"，现改为"想调用 → 先 Read 文档 → 再调用"。Read doc 是流程中的第一个必经节点，不可绕过。

第1步：判断是否涉及飞书多维表格 → 否 → 不使用此 Skill → 是 → 确定要调用的脚本名（如 record/create.js），进入第2步

第2步：【必经节点 1】Read 对应参考文档 → 运行 Read 读取 $SKILL_DIR/references/<类别>/<操作>.md → 已 Read？→ 在输出中 cite 文档路径，进入第3步 → 未 Read？→ 立即 Read，不要继续

第3步：准备访问凭证（如需要） → 调 get-tenant-access-token.js（同样先 Read 对应文档） → 进入第4步

第4步：准备资源标识（如需要） → 调 parse-bitable-url.js（同样先 Read 对应文档） → 进入第5步

第5步：【必经节点 2】cd 到 scripts 目录后执行 → 运行 cd $SKILL_DIR/scripts && node <script-path>.js --parameter-file-path "..."（PowerShell 用 ; if ($?) { }） → 数据表操作 → table/ 脚本 → 记录操作 → record/ 脚本 → 字段操作 → field/ 脚本 → 素材操作 → media/ 脚本

关键约束：

• 任何脚本（包括 get-tenant-access-token.js、parse-bitable-url.js 这两个"基础操作"）都必须经过第2步 Read 对应 reference
• Read 文档后必须能在输出中"cite 出文档路径"，否则视为未读
• 跳过 Read 直接写参数文件 = 流程违规（参考文档顶部"反面案例"）

全业务脚本索引清单

🚨 执行任何脚本前，先 Read 对应参考文档（每个脚本的最右列链接），再 cd $SKILL_DIR/scripts，最后才运行脚本。 没有例外。

基础能力

脚本	功能	参考文档
get-tenant-access-token.js	获取 tenant_access_token	获取访问凭证
parse-bitable-url.js	从 URL 提取 app_token、table_id、view_id	解析飞书链接
clear_temp.js	清理 $SKILL_DIR/temp 下的临时文件	参数配置示例与最佳实践

数据表操作（table/）

脚本	功能	参考文档
create-single.js	新增一个数据表，支持指定名称、视图和字段	创建单个数据表
batch-create.js	新增多个数据表，仅可指定名称	批量创建数据表
update.js	更新指定数据表的名称	更新数据表
list.js	获取所有数据表的 ID、版本号和名称	列出数据表
delete-one.js	通过 app_token 和 table_id 删除	删除单个数据表
batch-delete.js	批量删除多个数据表	批量删除数据表

记录操作（record/）

脚本	功能	参考文档
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	批量删除多条记录	批量删除记录

字段操作（field/）

脚本	功能	参考文档
create.js	在数据表中新增一个字段	创建字段
update.js	全量更新字段（property 会被覆盖）	更新字段
list.js	获取数据表中的所有字段	列出字段
delete.js	删除数据表中的一个字段	删除字段

素材/文件操作（media/）

脚本	功能	参考文档
upload.js	上传文件、图片、视频等素材（无大小限制，脚本内部自动区分直传/分片上传）	上传素材
file-token-to-url.js	file_token 转临时下载链接（24小时有效）	获取文件链接

核心概念

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

AI 处理示例

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

AI 执行步骤（每个脚本调用前都必须先 Read 对应文档，下表「已读证明」列需在输出中显式呈现）：

步骤	执行动作	已读证明（必须显式 cite）	命令
1	检查 tenant_access_token	已 Read references/get_tenant_access_token.md	如无则 cd $SKILL_DIR/scripts && node get-tenant-access-token.js ...
2	解析 URL 获取 app_token 和 table_id	已 Read references/parse_bitable_url.md	cd $SKILL_DIR/scripts && node parse-bitable-url.js ...
3	读取参考文档	已 Read references/record/create.md（重点：行 22-156 Schema + 行 162-193 文本格式警告）	读取 $SKILL_DIR/references/record/create.md，按 JSON Schema 构造参数
4	创建临时参数文件	—	存放在 $SKILL_DIR/temp 目录
5	创建记录	—	cd $SKILL_DIR/scripts && node record/create.js --parameter-file-path "..."
6	清理临时参数文件	—	完成用户需求或报错终止后，运行 clear_temp.js 清理 temp 目录
7	返回结果	—	向用户返回："已成功创建记录！记录ID: recxxx"

反例对照（请勿重演，详见文档顶部"反面案例"小节）：

步骤	❌ 错误做法	后果
1	直接 cd ...; node get-tenant-access-token.js ...	可能漏传 appId/appSecret，脚本拒绝执行
2	不读 parse_bitable_url.md 直接写 {url: "..."}	漏传 tenant_access_token，脚本返回"参数文件中必须包含..."
3	不读 record/create.md 直接构造 fields	文本字段误用富文本数组格式，触发 TextFieldConvFail

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

全局错误处理

错误场景	错误表现	处理方式
缺少访问凭证	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 和 field_name 参数
文件token格式错	Cannot read properties	使用 file_tokens（数组）而非 file_token（字符串）
批量操作超限	API 返回 422 错误	减少单次操作数量（创建/更新最多1000条，批量获取最多100条，批量删除最多500条）
临时文件创建失败	磁盘空间不足或权限问题	检查 $SKILL_DIR/temp 目录权限和磁盘空间
网络超时	请求无响应	检查网络连接，稍后重试

字段读写格式差异、常见错误详解及测试记录参见 常见错误及解决方案 与 参数配置示例与最佳实践。

参考文档

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