ProjectAGiPrompt/18-基础架构及交付部署特战队/10-飞书多维表格/飞书多维表格开发文档-完整参考.md

飞书多维表格（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 流转（跨子页面关联）

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 复制页面内容），可在此文档基础上继续自动化二次抓取并拼接。