飞书多维表格 API 操作

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

技能开发者的环境

node --version v24.13.0

⚠️ 重要：关于代码混淆

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

AI 行为准则

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

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

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

遇到问题时

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

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

决策流程

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

如何使用这个 Skill

功能概述

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

输出格式

执行完成后，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"

核心概念

操作接口速查

基础操作

数据表操作

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

记录操作

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

字段操作

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

素材/文件操作

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

文件和目录使用说明

临时文件管理最佳实践

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

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. 文本字段格式错误 (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"]

参考文档