---
name: feishu-bitable-yashu
description: 操作飞书多维表格(Bitable)。激活条件：用户消息须包含以下关键词之一:`操作飞书多维表格`、`管理多维表格`、`操作飞书bitable`、`多维表格操作`、`bitable管理`。
metadata:
  author: "AI Assistant"
  updated: "2026-08-07 00:00:00"
  version: "1.1.0"
title: feishu-bitable-yashu
canonical_url: https://skilld.dev/gh/steelan9199/wechat-publisher/feishu-bitable-yashu
last_updated: 2026-10-07T07:20:50.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 53 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install steelan9199/wechat-publisher/feishu-bitable-yashu`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/feishu-bitable-yashu`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/steelan9199/wechat-publisher/feishu-bitable-yashu) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/feishu-bitable-yashu`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/feishu-bitable-yashu --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/feishu-bitable-yashu --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 飞书多维表格 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` 就凭类比其他脚本的经验**写了参数文件：

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

脚本直接返回错误：

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

正确做法是 **先 Read** [parse_bitable_url.md](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/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` 仅为文档占位符，不是环境变量**：执行命令时必须替换为实际绝对路径，否则 bash 会将其解析为空字符串，导致 `cd $SKILL_DIR/scripts` 变成 `cd /scripts` 而报错"找不到路径"
- **Shell 类型**：bash。本 Skill 运行命令时采用 **bash `&&` 链式依赖执行**（前一条成功才执行下一条），规则如下：
  - **条件执行**：`cmd1 && cmd2`（如 `cd $SKILL_DIR/scripts && node script.js`）
- **脚本目录**：`$SKILL_DIR/scripts`
- **Node 版本**：>=18.20.8
- **依赖安装**：`cd $SKILL_DIR/scripts && npm install`
- **配置文件 `config.default.json`**（集中说明，全文不再重复）：
  - 路径：`$SKILL_DIR/config.default.json`
  - 默认存储字段：`appId`、`appSecret`、`tenant_access_token`
  - AI 可自动读写；脚本会自动将新令牌回写到该文件
  - 可手动修改 `tenant_access_token` 字段的**值**（键名保持不变）以切换为 `user_access_token` 身份，详见「如何切换身份」

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

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

如需了解脚本功能和用法，请查阅下方「脚本与触发词总表」和 `$SKILL_DIR/references/` 目录下的接口文档。

## 全局前置条件

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

| 前置条件              | 说明                               | 获取方式                                       |
| --------------------- | ---------------------------------- | ---------------------------------------------- |
| `tenant_access_token` | API 访问凭证，有效期 2 小时        | 按下方「令牌使用策略」执行                     |
| `app_token`           | 标识要操作的多维表格               | 运行 `parse-bitable-url.js` 从 URL 解析        |
| `table_id`            | 标识要操作的数据表（部分操作需要） | 运行 `parse-bitable-url.js` 或 `table/list.js` |

凭证管理详细规则参见 [认证与凭证管理指南](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/authentication.md)。

## 身份与访问令牌

> 💡 **飞书多维表格也是一种文档**：在飞书产品的概念中，飞书多维表格（Bitable）本质上是飞书云文档的一种，存放于用户的云空间中。因此下文关于"两个独立身份/两个独立空间/access_token 鉴权/身份切换"的说明，同样完全适用于多维表格的操作。

### 两个独立身份与两个独立空间（核心定义）

在使用飞书云文档 API 时，需要先理解一个关键概念：**飞书企业自建应用**和**飞书用户（使用飞书产品的真人）**在飞书中被视为两个完全独立的"用户"，各自拥有独立的云空间。

- **飞书企业自建应用**：本身在飞书中就是一个独立的"用户"，拥有自己的云空间（应用自身空间）
- **飞书用户（个人）**：是另一个独立的"用户"，拥有自己的云空间（用户个人空间）
- **两个空间相互独立**：各自存放各自的文档（包括多维表格），谁也看不到谁、谁也影响不了谁
- **可见性隔离**：用户在飞书客户端中打开自己的「云文档」时，看到的是**用户个人空间**的文档（含多维表格），**看不到**飞书企业自建应用空间中的文档；反之，应用也看不到用户个人空间中的文档

本 Skill 默认使用飞书企业自建应用身份操作，因此默认操作的是**应用自身空间**中的多维表格，而非用户个人空间中的多维表格。

### 凭证对比总表

下表汇总两种访问凭证的全部差异（合并身份、作用、有效期、获取方式、是否自动、默认身份）：

| 凭证类型              | 归属身份         | 作用                                                                                     | 有效期    | 获取依据                           | 获取方式                                                                               | 是否可自动获取    | 默认 |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------- | --------- | ---------------------------------- | -------------------------------------------------------------------------------------- | ----------------- | ---- |
| `tenant_access_token` | 飞书企业自建应用 | 飞书企业自建应用的临时令牌，以**应用身份**调用 OpenAPI，操作应用自身云空间的多维表格     | 约 2 小时 | `appId` + `appSecret`（应用凭证）  | 本 Skill 调用 `get-tenant-access-token.js` 脚本，凭 `appId`+`appSecret` 自动向飞书换取 | ✅ 可自动获取     | ✅   |
| `user_access_token`   | 飞书用户（个人） | 飞书用户的令牌，以**用户身份**调用 OpenAPI，可直接操作用户个人云空间中的所有可见多维表格 | 约 2 小时 | 飞书用户账号（需用户本人登录授权） | 用户自行打开飞书开放平台 API 调试台网页，登录授权后复制 token 值（步骤见下文）         | ❌ 需用户手动获取 | -    |

> 💡 **关键区别**：`appId` + `appSecret` 是飞书企业自建应用的凭证，本 Skill 可以凭它**自动换取** `tenant_access_token`（应用身份）；但 `user_access_token` 必须由**飞书用户本人**登录网页授权才能获取，本 Skill 无法代为自动获取。两种 token 均约 2 小时过期。

### 协作者机制：让应用访问用户文档的另一种路径

由于两个空间相互隔离，如果飞书企业自建应用希望直接操作**飞书用户个人空间**里的某个多维表格，需要先将该应用**添加为该多维表格文档的"协作者"**，授予相应权限（查看/编辑/管理）。配置入口：在飞书客户端打开目标多维表格 → 右上角「分享」→ 添加协作者 → 搜索应用名并授予权限。

> 协作者方式适合"只操作个别多维表格"的场景；若需批量操作用户空间中的多个多维表格，推荐改用 `user_access_token` 方式直接以用户身份操作。

### 如何切换身份：以飞书用户身份操作用户空间文档

如果用户希望本 Skill 操作**用户个人空间**里的多维表格（而非应用自身空间的多维表格），操作非常简单 —— **所有脚本无需任何修改**，只需修改凭证文件 `$SKILL_DIR/config.default.json`：

1. 打开 `$SKILL_DIR/config.default.json`
2. 找到 `"tenant_access_token"` 字段（注意：**键名 `tenant_access_token` 保持不变，不要修改键名**）
3. 将该字段的**值**替换为用户提供的 `user_access_token` 的值
4. 保存文件，后续所有脚本调用将自动以**飞书用户身份**操作用户个人空间的多维表格

修改示例（只改值，不改键名）：

```json
{
  "appId": "cli_xxx",
  "appSecret": "xxx",
  "tenant_access_token": "u-xxxxxxxxxxxxxxxxxxxx",
  ...
}
```

> 💡 脚本内部统一通过该字段读取 token，并不关心其实际是 tenant 还是 user 类型 —— 飞书 API 服务端会根据 token 本身识别身份。因此只需替换值即可完成身份切换。

### user_access_token 的获取方式

`user_access_token` 权限较高，且自动化获取流程复杂（需 OAuth 授权），因此本 Skill **不存储、不自动获取** `user_access_token`。若用户需以用户身份操作自己的多维表格，请按以下步骤获取：

1. 打开飞书开放平台 API 调试台：[获取文件元数据](https://open.feishu.cn/document/server-docs/docs/drive-v1/file/batch_query)
2. 页面右侧为 API 调试台，在请求头区域可切换 Token 类型（`user_access_token` / `tenant_access_token`）
3. 选择 `user_access_token` 并登录授权后，即可复制获取到的 `user_access_token` 值
4. 将该值提供给 AI，AI 会按上文「如何切换身份」中的方式写入 `config.default.json` 后执行脚本

> ⚠️ **安全提示**：`user_access_token` 具有用户级别的完整权限，请妥善保管。本 Skill 仅临时使用，不做任何持久化存储，执行完毕后临时文件会自动清理。

### tenant_access_token 的获取与刷新（令牌使用策略，全文唯一权威定义）

> ⚠️ **令牌使用策略（重要）**：本 Skill **优先复用** `config.default.json` 中的 `tenant_access_token`，**默认不主动刷新**，以避免不必要的换取请求。仅当**其他业务脚本**返回信息中出现"token 不合法"、"token 已过期"、"token 失效"等类似描述时，才运行 `cd $SKILL_DIR/scripts && node get-tenant-access-token.js --parameter-file-path <参数文件绝对路径>` 刷新令牌（脚本会自动将新令牌回写到配置文件，无需手动处理）。

获取方式参考 [认证与凭证管理指南](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/authentication.md) 或 [获取访问凭证 API](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/get_tenant_access_token.md)。

## 跨功能公共规则

> 以下规则适用于本 Skill 所有脚本调用，必须严格遵守。「先 Read 文档」规则已在顶部「AI 调用任何脚本前必读」集中定义，此处不重复。

### 1. 执行前必须进入 scripts 目录（命令模板，全文唯一权威定义）

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

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

| 写法                                              | 是否允许 |
| ------------------------------------------------- | -------- |
| `cd $SKILL_DIR/scripts && node record/get.js ...` | ✅ 正确  |
| `node $SKILL_DIR/scripts/record/get.js ...`       | ❌ 禁止  |
| `node scripts/record/get.js ...`                  | ❌ 禁止  |

### 2. 参数通过文件传递

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

### 3. 临时文件管理

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

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

详细临时文件管理流程、工具函数用法与参数配置示例参见 [参数配置示例与最佳实践](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/examples.md)。

### 4. 🚨 禁止用 Shell 命令写文件

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

> **原因**：部分 Shell 写入命令会在文件中添加 UTF-8 BOM（`EF BB BF`），这个不可见字符会导致：
>
> - **JSON**：`JSON.parse()` 抛出 `Unexpected token` 异常
> - **JS**：Node.js 无法加载带 BOM 的模块，报语法错误
> - **Markdown**：frontmatter 解析失败，metadata 字段读取为 undefined
>
> **Write 工具**不产生 BOM，是唯一安全的文件写入方式。

### 5. 输出格式

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

## 脚本日志输出机制

`$SKILL_DIR/scripts/` 目录下的 JS 脚本的**所有日志均通过 `console.error` 输出至标准错误流（stderr）**

据此，脚本运行期间产生的所有输出（含进度日志与结构化结果数据 JSON）均经由 stderr 输出，标准输出流（stdout）为空。AI 在调用脚本、捕获输出时应知晓此特性。

## 脚本与触发词总表

> 🚨 **执行任何脚本前，先 Read 对应参考文档（最右列链接），再 `cd $SKILL_DIR/scripts`，最后才运行脚本。** 没有例外。本表合并原「触发映射」与「全业务脚本索引清单」两张表。

### 基础能力

| 用户输入触发词              | 脚本                         | 功能                                           | 参考文档                                                         |
| --------------------------- | ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
| "获取访问凭证"/"刷新 token" | `get-tenant-access-token.js` | 获取 `tenant_access_token`                     | [获取访问凭证](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/get_tenant_access_token.md) |
| "解析飞书链接"              | `parse-bitable-url.js`       | 从 URL 提取 `app_token`、`table_id`、`view_id` | [解析飞书链接](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/parse_bitable_url.md)       |
| （清理临时文件）            | `clear_temp.js`              | 清理 `$SKILL_DIR/temp` 下的临时文件            | [参数配置示例与最佳实践](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/examples.md)      |

### 数据表操作（table/）

| 用户输入触发词              | 脚本               | 功能                                     | 参考文档                                                       |
| --------------------------- | ------------------ | ---------------------------------------- | -------------------------------------------------------------- |
| "创建表格"/"添加数据表"     | `create-single.js` | 新增一个数据表，支持指定名称、视图和字段 | [创建单个数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/create_single.md) |
| "批量创建表格"              | `batch-create.js`  | 新增多个数据表，仅可指定名称             | [批量创建数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/batch_create.md)  |
| "修改表格名称"/"重命名表格" | `update.js`        | 更新指定数据表的名称                     | [更新数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/update.md)            |
| "查看表格"/"数据表列表"     | `list.js`          | 获取所有数据表的 ID、版本号和名称        | [列出数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/list.md)              |
| "删除表格"/"移除数据表"     | `delete-one.js`    | 通过 `app_token` 和 `table_id` 删除      | [删除单个数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/delete_one.md)    |
| "批量删除表格"              | `batch-delete.js`  | 批量删除多个数据表                       | [批量删除数据表](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/table/batch_delete.md)  |

### 记录操作（record/）

| 用户输入触发词                   | 脚本              | 功能                                | 参考文档                                                     |
| -------------------------------- | ----------------- | ----------------------------------- | ------------------------------------------------------------ |
| "添加记录"/"创建记录"/"插入记录" | `create.js`       | 在数据表中新增一条记录              | [创建记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/create.md)           |
| "修改记录"/"更新记录"/"编辑记录" | `update.js`       | 更新数据表中的一条记录              | [更新记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/update.md)           |
| "查看记录"/"获取记录"/"列出记录" | `get.js`          | 查询记录，单次最多 500 行，支持分页 | [获取记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/get.md)              |
| "删除记录"/"移除记录"            | `delete.js`       | 删除数据表中的一条记录              | [删除记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/delete.md)           |
| "批量添加记录"/"添加多条记录"    | `batch-create.js` | 批量新增记录，单次最多 1,000 条     | [批量创建记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/batch_create.md) |
| "批量修改记录"/"更新多条记录"    | `batch-update.js` | 批量更新记录，单次最多 1,000 条     | [批量更新记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/batch_update.md) |
| "批量获取记录"                   | `batch-get.js`    | 通过记录 ID 查询，最多 100 条       | [批量获取记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/batch_get.md)    |
| "批量删除记录"/"清空记录"        | `batch-delete.js` | 批量删除多条记录                    | [批量删除记录](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/record/batch_delete.md) |

### 字段操作（field/）

| 用户输入触发词      | 脚本        | 功能                              | 参考文档                                          |
| ------------------- | ----------- | --------------------------------- | ------------------------------------------------- |
| "添加字段"/"新列"   | `create.js` | 在数据表中新增一个字段            | [创建字段](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/field/create.md) |
| "修改字段"/"修改列" | `update.js` | 全量更新字段（property 会被覆盖） | [更新字段](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/field/update.md) |
| "查看字段"/"列信息" | `list.js`   | 获取数据表中的所有字段            | [列出字段](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/field/list.md)   |
| "删除字段"/"移除列" | `delete.js` | 删除数据表中的一个字段            | [删除字段](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/field/delete.md) |

### 素材/文件操作（media/）

| 用户输入触发词                   | 脚本                   | 功能                                                                    | 参考文档                                                         |
| -------------------------------- | ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
| "上传文件"/"上传图片"/"上传附件" | `upload.js`            | 上传文件、图片、视频等素材（无大小限制，脚本内部自动区分直传/分片上传） | [上传素材](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/media/upload.md)                |
| "获取下载链接"/"获取直链"        | `file-token-to-url.js` | `file_token` 转临时下载链接（24小时有效）                               | [获取文件链接](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/media/file_token_to_url.md) |

## 决策流程（权威调用流程，全文唯一）

> **流程图的核心**：原流程是"想调用 → 直接调用"，现改为"想调用 → **先 Read 文档** → 再调用"。`Read doc` 是流程中的**第一个必经节点**，不可绕过。本节为权威流程，「强制三步走」「跨功能公共规则」均指向本节。

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

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

**第3步：准备访问凭证（如需要）**
按令牌使用策略执行（见「tenant_access_token 的获取与刷新」）
进入第4步

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

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

**关键约束**：

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

## 核心概念

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

## 索引列约束

### 字段基本结构

数据表中的字段对象包含以下属性：

```json
{
  "field_id": "fldYWaldeW", // 字段的 ID
  "field_name": "文本", // 字段名称
  "type": 1, // 字段的类型
  "description": "字段的描述", // 对字段的更多说明
  "is_primary": true, // 该字段是否是初始的索引字段
  "property": null, // 字段的属性
  "ui_type": "Text", // 字段在界面上的展示类型，例如进度字段是数字的一种展示形态
  "is_hidden": false // 字段是否是隐藏字段
}
```

### 索引列（is_primary）

数据表中第一列为索引列，即 `is_primary: true` 的字段。索引列有以下限制：

| 约束项   | 说明                                                           |
| -------- | -------------------------------------------------------------- |
| 不可删除 | 索引列不能被删除（调用 `field/delete.js` 会失败）              |
| 不可移动 | 索引列的位置固定为第一列，不能移动                             |
| 不可隐藏 | 索引列不能被设置为隐藏字段                                     |
| 可修改   | 索引列可以修改字段名称等属性，但修改字段类型时仅限以下几种类型 |

索引列修改字段类型时，仅支持以下类型：

| type 值 | 字段类型 |
| ------- | -------- |
| 1       | 多行文本 |
| 2       | 数字     |
| 5       | 日期     |
| 13      | 电话号码 |
| 15      | 超链接   |

## AI 处理示例

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

**AI 执行步骤**（按「决策流程」执行，下表"已读证明"列需在输出中显式呈现）：

| 步骤 | 执行动作                            | 已读证明（必须显式 cite）                                                                 | 命令                                                                                                                                          |
| ---- | ----------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | 检查 tenant_access_token            | `已 Read references/get_tenant_access_token.md`                                           | 按令牌使用策略：**优先复用** config 中已有 token；仅当业务脚本返回失效描述时才 `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"                                                                                                  |

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

## 全局错误处理

| 错误场景                                                                      | 错误表现                        | 处理方式                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |
| 令牌失效（业务脚本返回"token 不合法/已过期/失效"等描述，含 401/403/99991663） | API 返回 token 失效相关错误信息 | 运行 `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` 目录权限和磁盘空间                                     |
| 网络超时                                                                      | 请求无响应                      | 检查网络连接，稍后重试                                                        |

> 字段读写格式差异、常见错误详解及测试记录参见 [常见错误及解决方案](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/errors.md) 与 [参数配置示例与最佳实践](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/examples.md)。

## 参考文档

| 文档                                                                 | 说明                                                                              |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [认证与凭证管理指南](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/authentication.md)        | 详细的凭证管理说明，包括 App ID/App Secret 获取、tenant_access_token 自动获取流程 |
| [获取访问凭证 API](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/get_tenant_access_token.md) | 获取 tenant_access_token 的具体 API 调用说明和脚本使用方法                        |
| [解析飞书 URL 工具](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/parse_bitable_url.md)      | 从飞书多维表格 URL 中提取 app_token、table_id、view_id 的工具使用说明             |
| [常见错误及解决方案](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/errors.md)                | API 调用常见错误码及排查方法                                                      |
| [参数配置示例与最佳实践](https://skilld.dev/api/skills-raw/steelan9199/wechat-publisher/feishu-bitable-yashu/$SKILL_DIR/references/examples.md)          | 各种操作场景的参数配置示例、字段格式差异、临时文件管理详细流程                    |
