steelan9199/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 参数 | | 文件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 调用常见错误码及排查方法 | | 参数配置示例与最佳实践 | 各种操作场景的参数配置示例 |