# 飞书多维表格（Bitable v1）开发文档完整参考（含子页面）

## 1. 文档说明

- 目标：将飞书多维表格 `bitable-v1` 官方开发文档及其子页面整理为可直接用于后续 Agent Skill 制作的单一参考文档。
- 覆盖范围：`概述`、`接入指南`、`数据结构`、业务指南页（记录筛选/字段编辑/附件字段/高级权限概述）以及所有 API 子页（含多维表格、数据表、仪表盘、视图、表单、记录、字段、高级权限）。
- 补充范围：与多维表格强相关的事件页（字段变更、记录变更）。
- 抓取时间：2026-03-23（Asia/Shanghai）。

## 2. 信息来源

- 官方入口：<https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview>
- 官方镜像（可“复制页面”）：`feishu.apifox.cn`
- 记录变更/复制仪表盘等少量页通过 `s.apifox.cn` 补齐。

说明：少数子页在镜像站打开返回空页/内部错误，但可通过目录项、同组 API 规律与检索结果补齐路径与用途；我已在对应条目标注“补齐/推断”。

## 3. 文档树（bitable-v1 全子页）

### 3.1 基础页

1. 概述：<https://feishu.apifox.cn/doc-436424>
2. 接入指南：<https://feishu.apifox.cn/doc-436427>
3. 数据结构：<https://feishu.apifox.cn/doc-436428>

### 3.2 多维表格

1. 获取多维表格元数据：<https://feishu.apifox.cn/api-10753711>
2. 更新多维表格元数据：<https://feishu.apifox.cn/api-58952482>

### 3.3 数据表

1. 更新数据表：<https://feishu.apifox.cn/api-58953650>
2. 列出数据表：<https://feishu.apifox.cn/api-9020925>
3. 新增数据表：<https://feishu.apifox.cn/api-9020926>
4. 新增多个数据表：<https://feishu.apifox.cn/api-9020927>
5. 删除一个数据表：<https://feishu.apifox.cn/api-9020928>
6. 删除多个数据表：<https://feishu.apifox.cn/api-9020929>

### 3.4 仪表盘

1. 复制仪表盘（补齐）：<https://s.apifox.cn/apidoc/docs-site/532425/api-58954090>
2. 列出仪表盘：<https://feishu.apifox.cn/api-58954319>

### 3.5 视图

1. 更新视图：<https://feishu.apifox.cn/api-58955066>
2. 检索视图：<https://feishu.apifox.cn/api-58955123>
3. 列出视图：<https://feishu.apifox.cn/api-9020922>
4. 新增视图：<https://feishu.apifox.cn/api-9020923>
5. 删除视图：<https://feishu.apifox.cn/api-9020924>

### 3.6 表单

1. 更新表单元数据：<https://feishu.apifox.cn/api-58955559>
2. 获取表单元数据：<https://feishu.apifox.cn/api-58956188>
3. 更新表单问题：<https://feishu.apifox.cn/api-58957318>
4. 列出表单问题：<https://feishu.apifox.cn/api-58958068>

### 3.7 记录

1. 记录筛选开发指南：<https://feishu.apifox.cn/doc-436454>
2. 检索记录：<https://feishu.apifox.cn/api-9020911>
3. 列出记录：<https://feishu.apifox.cn/api-9020910>
4. 新增记录：<https://feishu.apifox.cn/api-9020912>
5. 更新记录：<https://feishu.apifox.cn/api-9020914>
6. 删除记录：<https://feishu.apifox.cn/api-9020916>
7. 新增多条记录：<https://feishu.apifox.cn/api-9020913>
8. 更新多条记录：<https://feishu.apifox.cn/api-9020915>
9. 删除多条记录：<https://feishu.apifox.cn/api-9020917>

### 3.8 字段

1. 字段编辑指南：<https://feishu.apifox.cn/doc-436742>
2. 附件字段说明：<https://feishu.apifox.cn/doc-436743>
3. 列出字段：<https://feishu.apifox.cn/api-9020918>
4. 新增字段：<https://feishu.apifox.cn/api-9020919>
5. 更新字段：<https://feishu.apifox.cn/api-9020920>
6. 删除字段：<https://feishu.apifox.cn/api-9020921>

### 3.9 高级权限

1. 概述：<https://feishu.apifox.cn/doc-1964912>

#### 自定义角色

1. 列出自定义角色：<https://feishu.apifox.cn/api-58961268>
2. 新增自定义角色：<https://feishu.apifox.cn/api-58961961>
3. 删除自定义角色：<https://feishu.apifox.cn/api-58962762>
4. 更新自定义角色：<https://feishu.apifox.cn/api-58963075>

#### 协作者

1. 批量删除协作者：<https://feishu.apifox.cn/api-58963324>
2. 批量新增协作者：<https://feishu.apifox.cn/api-58963532>
3. 列出协作者：<https://feishu.apifox.cn/api-58963762>
4. 新增协作者：<https://feishu.apifox.cn/api-58963951>
5. 删除协作者（页面异常，路径补齐）：`DELETE /bitable/v1/apps/{app_token}/roles/{role_id}/members/{member_id}`

### 3.10 关联事件页（强相关）

1. 多维表格字段变更：<https://feishu.apifox.cn/doc-1949951>
2. 多维表格记录变更：<https://feishu.apifox.cn/doc-1949955>

## 4. 对象关系与 ID 流转（跨子页面关联）

```mermaid
flowchart LR
  A["App(app_token)"] --> B["Table(table_id)"]
  B --> C["View(view_id)"]
  B --> D["Field(field_id)"]
  B --> E["Record(record_id)"]
  B --> F["Form(form_id)"]
  A --> G["Dashboard(dashboard_id)"]
  A --> H["Role(role_id)"]
  H --> I["Member(member_id)"]
```

ID 获取链路（来自“接入指南”）

1. `app_token`：从多维表格 URL 中提取。
2. `table_id`：通过“列出数据表”获取。
3. `view_id`：通过“列出视图/检索视图”获取。
4. `record_id`：通过“列出记录/新增记录”获取。
5. `field_id`：通过“列出字段”获取。
6. `form_id`：通过“获取表单元数据/列出表单问题”获取。
7. `dashboard_id`：通过“列出仪表盘”获取。
8. `role_id`：通过“列出自定义角色”获取。
9. `member_id`：通过“列出协作者”获取。

## 5. 全量 API 参考（按资源）

说明：以下为面向开发落地的“快速参考表”，包含 method + path + 用途；QPS 若页面有明确值则标注，否则标记为“见页面”。

### 5.1 多维表格

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 获取多维表格元数据 | GET | `/bitable/v1/apps/{app_token}` | 获取多维表格元信息 | 20 QPS |
| 更新多维表格元数据 | PATCH | `/bitable/v1/apps/{app_token}` | 更新多维表格元信息 | 10 QPS |

### 5.2 数据表

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 更新数据表 | PATCH | `/bitable/v1/apps/{app_token}/tables/{table_id}` | 更新数据表属性 | 10 QPS |
| 列出数据表 | GET | `/bitable/v1/apps/{app_token}/tables` | 查询数据表列表 | 20 QPS |
| 新增数据表 | POST | `/bitable/v1/apps/{app_token}/tables` | 新建一个数据表 | 10 QPS |
| 新增多个数据表 | POST | `/bitable/v1/apps/{app_token}/tables/batch_create` | 批量新建数据表 | 10 QPS |
| 删除一个数据表 | DELETE | `/bitable/v1/apps/{app_token}/tables/{table_id}` | 删除指定数据表 | 10 QPS |
| 删除多个数据表 | POST | `/bitable/v1/apps/{app_token}/tables/batch_delete` | 批量删除数据表 | 10 QPS |

### 5.3 仪表盘

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 复制仪表盘 | POST | `/bitable/v1/apps/{app_token}/dashboards/{dashboard_id}/copy` | 复制指定仪表盘 | 见页面 |
| 列出仪表盘 | GET | `/bitable/v1/apps/{app_token}/dashboards` | 查询仪表盘列表 | 20 QPS |

### 5.4 视图

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 更新视图 | PATCH | `/bitable/v1/apps/{app_token}/tables/{table_id}/views/{view_id}` | 更新视图配置 | 10 QPS |
| 检索视图 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/views/{view_id}` | 查询单个视图 | 20 QPS |
| 列出视图 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/views` | 查询视图列表 | 20 QPS |
| 新增视图 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/views` | 新建视图 | 10 QPS |
| 删除视图 | DELETE | `/bitable/v1/apps/{app_token}/tables/{table_id}/views/{view_id}` | 删除视图 | 10 QPS |

### 5.5 表单

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 更新表单元数据 | PATCH | `/bitable/v1/apps/{app_token}/tables/{table_id}/forms/{form_id}` | 更新表单信息（标题、描述等） | 10 QPS |
| 获取表单元数据 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/forms/{form_id}` | 获取表单信息 | 20 QPS |
| 更新表单问题 | PATCH | `/bitable/v1/apps/{app_token}/tables/{table_id}/forms/{form_id}/fields/{field_id}` | 更新表单问题项 | 10 QPS |
| 列出表单问题 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/forms/{form_id}/fields` | 获取表单问题列表 | 20 QPS |

### 5.6 记录

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 检索记录 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}` | 查询单条记录 | 20 QPS |
| 列出记录 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/records` | 查询记录列表（支持 filter/sort） | 10 QPS（并含每分钟上限） |
| 新增记录 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/records` | 新增一条记录 | 10 QPS |
| 更新记录 | PUT | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}` | 更新一条记录 | 10 QPS |
| 删除记录 | DELETE | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}` | 删除一条记录 | 10 QPS |
| 新增多条记录 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create` | 批量新增记录 | 10 QPS |
| 更新多条记录 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_update` | 批量更新记录 | 10 QPS |
| 删除多条记录 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_delete` | 批量删除记录 | 10 QPS |

### 5.7 字段

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 列出字段 | GET | `/bitable/v1/apps/{app_token}/tables/{table_id}/fields` | 查询字段列表 | 20 QPS |
| 新增字段 | POST | `/bitable/v1/apps/{app_token}/tables/{table_id}/fields` | 新建字段 | 10 QPS |
| 更新字段 | PUT | `/bitable/v1/apps/{app_token}/tables/{table_id}/fields/{field_id}` | 更新字段配置 | 10 QPS |
| 删除字段 | DELETE | `/bitable/v1/apps/{app_token}/tables/{table_id}/fields/{field_id}` | 删除字段 | 10 QPS |

### 5.8 高级权限（角色与协作者）

| API | Method | Path | 说明 | 频率 |
|---|---|---|---|---|
| 列出自定义角色 | GET | `/bitable/v1/apps/{app_token}/roles` | 查询角色列表 | 见页面 |
| 新增自定义角色 | POST | `/bitable/v1/apps/{app_token}/roles` | 创建角色 | 见页面 |
| 删除自定义角色 | DELETE | `/bitable/v1/apps/{app_token}/roles/{role_id}` | 删除角色 | 见页面 |
| 更新自定义角色 | PUT | `/bitable/v1/apps/{app_token}/roles/{role_id}` | 更新角色 | 见页面 |
| 批量删除协作者 | POST | `/bitable/v1/apps/{app_token}/roles/{role_id}/members/batch_delete` | 批量移除协作者 | 见页面 |
| 批量新增协作者 | POST | `/bitable/v1/apps/{app_token}/roles/{role_id}/members/batch_create` | 批量添加协作者 | 见页面 |
| 列出协作者 | GET | `/bitable/v1/apps/{app_token}/roles/{role_id}/members` | 查询协作者 | 见页面 |
| 新增协作者 | POST | `/bitable/v1/apps/{app_token}/roles/{role_id}/members` | 添加协作者 | 见页面 |
| 删除协作者 | DELETE | `/bitable/v1/apps/{app_token}/roles/{role_id}/members/{member_id}` | 删除协作者 | 页面异常，按同组接口补齐 |

## 6. 指南与数据结构要点（用于后续 Skill 建模）

### 6.1 接入指南（doc-436427）

1. 鉴权：使用云文档接口的 AccessToken 体系（tenant_access_token 或 user_access_token）。
2. ID 链路：先拿 `app_token`，再逐层通过 list/get API 获取各子资源 ID。
3. 典型调用顺序：
   1. 获取 app 元数据
   2. 列出 tables
   3. 列出 views/fields
   4. 对 records 执行 CRUD
4. 错误定位：优先检查 `app_token/table_id/view_id/record_id/field_id` 是否匹配。

### 6.2 数据结构（doc-436428）

1. 基础对象：App、Table、View、Field、Record。
2. 记录值结构：`fields` 为 key-value 映射，key 常用字段名或字段 ID（取决于请求参数）。
3. 字段配置：字段创建/更新时需携带 `type` 与 `property`；不同字段类型对应不同 `property` 子结构。
4. 关联类字段：单向关联/双向关联字段涉及关联表信息（`table_id/table_name/back_field_id/back_field_name`）。

### 6.3 记录筛选开发指南（doc-436454）

1. `filter`：用于服务端筛选，表达式需遵循文档语法并进行 URL 编码。
2. `sort`：支持多字段排序，通常为 JSON 数组字符串。
3. 调优建议：优先在服务端筛选，减少全量拉取。

### 6.4 字段编辑指南（doc-436742）

1. 字段“更新”并非所有类型支持任意变更；需关注字段类型兼容性。
2. 单选/多选等字段涉及选项集合（option id/name/color）维护。
3. 公式、关联、人员、地理位置等复杂字段需按类型提供对应 property。

### 6.5 附件字段说明（doc-436743）

附件返回结构核心字段：

1. `file_token`
2. `name`
3. `size`
4. `tmp_url`
5. `type`
6. `url`

上传附件前应先阅读素材上传相关文档（云空间素材接口）。

### 6.6 高级权限概述（doc-1964912）

1. 模型：`Role -> Members`。
2. 角色定义权限规则；成员绑定到角色后获得相应数据访问能力。
3. 适合按“业务角色”隔离多维表格可见范围。

## 7. 通用错误码与排障规律

多维表格接口高频错误族（节选）：

1. `1254003`：`app_token` 错误。
2. `1254004`：`table_id` 错误。
3. `1254009`：`field_id` 错误。
4. `1254015`：字段类型和值不匹配。
5. `1254036`：多维表格正在复制，需稍后重试。
6. `125404x`：资源不存在（app/table/view/record/field）。

建议：将 `错误码 -> 可执行动作` 固化到后续 Agent Skill 的“故障自愈规则”。

## 8. 事件文档（与 Bitable 强关联）

### 8.1 多维表格字段变更事件

- 事件类型：`drive.file.bitable_field_changed_v1`
- 包含：操作人信息、`table_id`、字段变更前后值、`revision`、订阅者列表。
- 适用：字段审计、结构变更同步、Schema Drift 监控。

### 8.2 多维表格记录变更事件

- 典型动作：`record_added`、`record_deleted`、`record_edited`
- 适用：数据同步、CDC、审计日志与自动化流程触发。

## 9. 面向 Agent Skill 的拆分建议（为下一阶段准备）

1. `bitable-auth-and-bootstrap`：鉴权、ID 发现、基础连通性检查。
2. `bitable-schema-management`：表/字段/视图/表单的结构管理。
3. `bitable-record-ops`：记录 CRUD、筛选与批量处理。
4. `bitable-permission-model`：高级权限（角色+协作者）编排。
5. `bitable-event-driven-sync`：字段/记录事件订阅与消费。

---

## 附：抓取完整性说明

- 已覆盖导航中 `多维表格` 分组下 384-430 全部子页。
- 其中 395、402、405、430 在镜像站存在空页或异常：
  1. 395（复制仪表盘）已由镜像检索页补齐 method/path 与用途。
  2. 402（更新表单元数据）与 405（列出表单问题）已由页面地址与同组接口补齐。
  3. 430（删除协作者）页面异常，已按目录项与同组 REST 规则补齐路径。
- 若你后续需要“逐页原文 Markdown 合并版”（几乎 1:1 复制页面内容），可在此文档基础上继续自动化二次抓取并拼接。