用途
本技能用于通过飞书开放平台的多维表格（Bitable）API 操作多维表格，覆盖数据记录、字段、数据表、视图和权限等管理场景。接口基础地址为 https://open.feishu.cn/open-apis/bitable/v1。
认证与 Token 获取
从 feishu_skills 根目录执行共享脚本获取 Token：
TOKEN="$(./scripts/get_feishu_token.sh)"
请求头统一使用 Authorization: Bearer ${TOKEN}。
如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：
TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"
环境变量：
- FEISHU_APP_ID
- FEISHU_APP_SECRET
本地缓存：./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）。
关键参数：
- app_token：多维表格 URL 中 /base/ 后的字符串
- table_id：调用列表 API 获取
主要能力
记录操作
- 新增单条：POST /apps/{app_token}/tables/{table_id}/records
- 批量新增：POST .../records/batch_create（最多 500 条，支持 Upsert）
- 更新：PUT .../records/{record_id}
- 批量更新：POST .../records/batch_update（最多 500 条）
- 批量删除：POST .../records/batch_delete（最多 500 条）
- 查询：POST .../records/search（支持 filter/sort/分页）
分页查询全部记录（单次最多 500 条，循环直到 has_more: false）：
page_token = None all_records = [] while True: body = {"page_size": 500} if page_token: body["page_token"] = page_token resp = post(".../records/search", json=body) all_records.extend(resp["data"]["items"]) if not resp["data"].get("has_more"): break page_token = resp["data"]["page_token"]
请求示例：
{ "fields": { "名称": "测试", "金额": 100, "进度": 0.75, "评分": 4, "日期": 1770508800000, "状态": "进行中", "标签": ["重要", "紧急"], "完成": true, "负责人": [{"id": "ou_xxx"}], "电话": "13800138000", "链接": {"text": "官网", "link": "https://example.com"} } }
注意：数值不要传字符串，日期必须是 13 位毫秒时间戳。
字段类型格式
| type | ui_type | 中文名 | 写入格式 | 示例 |
|---|---|---|---|---|
| 1 | Text | 多行文本 | 字符串 | "办公用品" |
| 1 | 邮箱 | 字符串 | "test@example.com" | |
| 2 | Number | 数字 | 数值 | 100 |
| 2 | Currency | 货币 | 数值 | 1280.50 |
| 2 | Progress | 进度 | 数值(0~1) | 0.25 (25%) |
| 2 | Rating | 评分 | 数值(1~5) | 3 |
| 3 | SingleSelect | 单选 | 字符串 | "支出" (自动创建选项) |
| 4 | MultiSelect | 多选 | 字符串数组 | ["餐饮","交通"] |
| 5 | DateTime | 日期 | 毫秒时间戳 | 1770508800000 |
| 7 | Checkbox | 复选框 | 布尔值 | true |
| 11 | User | 人员 | 对象数组 | [{"id":"ou_xxx"}] |
| 13 | Phone | 电话 | 字符串 | "13800138000" |
| 15 | Url | 超链接 | 对象 | {"text":"名称","link":"https://..."} |
| 17 | Attachment | 附件 | 对象数组 | [{"file_token":"xxx"}] |
| 18 | SingleLink | 单向关联 | 字符串数组 | ["recuxxx"] |
| 21 | DuplexLink | 双向关联 | 字符串数组 | ["recuxxx"] |
| 22 | Location | 地理位置 | 字符串 | "116.397,39.903" |
不支持 API 写入：公式、查找引用、创建时间、修改人、自动编号。
日期格式转换：
import datetime ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)
→ 1770508800000
字段管理
- 获取字段列表：GET .../fields（返回 type 和 ui_name）
- 新增字段：POST .../fields，如 {"field_name":"新字段","type":1}
- 更新字段：PUT .../fields/{field_id}（修改单选需提供完整 property）
- 删除字段：DELETE .../fields/{field_id}
公式字段示例：
{ "type": 20, "field_name": "利润", "property": {"formula_expression": "[营收]-[成本]"} }
关联字段示例：
{ "type": 18, "field_name": "关联客户", "property": {"table_id": "tblXXX", "multiple": true} }
数据表管理
- 创建多维表格：POST /apps，如 {"name":"数据库名称"}
- 列出数据表：GET /apps/{app_token}/tables
- 新增数据表：POST /apps/{app_token}/tables，如 {"table":{"name":"表名"}}
- 批量新增表：POST .../tables/batch_create（最多 10 张表）
- 删除数据表：DELETE .../tables/{table_id}
- 复制数据表：POST .../tables/{table_id}/copy
权限管理（重要）：通过 API 创建的表格默认只对机器人可见，创建后需添加用户为协作者：
POST /permissions/{app_token}/members { "member_type": "user", "member_id": "ou_xxx", "perm": "full_access" }
权限类型：view / edit / full_access。
视图管理
- 列出视图：GET .../tables/{table_id}/views
- 创建视图：POST .../tables/{table_id}/views，如 {"view_name":"新视图","view_type":"grid"}
- 删除视图：DELETE .../views/{view_id}
视图类型：grid(表格) / kanban(看板) / gallery(画册) / gantt(甘特图)。
权限管理
- 创建协作者：POST /apps/{app_token}/roles/{role_id}/members/batch_create
- 删除协作者：POST .../members/batch_delete
- 更新权限：PUT /apps/{app_token}/roles/{role_id}
角色类型：owner / editor / reader。
使用方式
- 配置 FEISHU_APP_ID 与 FEISHU_APP_SECRET 环境变量。
- 通过共享脚本获取 Token，并在请求头中携带 Authorization: Bearer ${TOKEN}。
- 依据上述端点调用对应 API 完成记录、字段、数据表、视图和权限操作。
- 批量操作优先，减少 API 调用次数。
适用场景
- 通过程序批量写入、更新、删除多维表格记录。
- 动态创建数据表、字段、视图。
- 配置表格协作者与权限。
- 使用关联字段实现关系型数据能力。
限制与注意事项
- 不存在的接口：/apps/:app_token/tables/:table_id/statistics 该接口不存在，飞书官方文档中未提供统计汇总 API。如需统计数据（如求和、计数），建议用 POST .../records/search 拉取全量记录后在客户端计算，或在多维表格中创建公式字段（如 SUM、COUNT）后通过 API 读取字段值。
- 公式、查找引用、创建时间、修改人、自动编号等字段不支持 API 写入。
- 数值不要传字符串，日期必须是 13 位毫秒时间戳。
- 字段类型需严格匹配，避免写入失败。
- 通过 API 创建的表格默认只对机器人可见，创建后需立即添加用户为协作者。
- 单选字段会自动创建选项，直接写入选项文本即可。
测试验证
已通过实测验证的 15 种字段类型：文本、进度、多选、单选、日期、复选框、电话、人员、超链接、邮箱、货币、评分、地理位置、单向关联、双向关联。
测试表格：https://jvbmlo28x0.feishu.cn/base/YdOpb47PvalSbQsHPyXc7LrNnUh