Feishu Bitable
Wire your agent to Feishu Bitable for record CRUD, field and view management, formulas, and permissions via the open Bitable v1 API.
Overview
feishu-bitable is an agent skill for the Build phase that operates Feishu multidimensional tables via the Bitable v1 API for records, fields, views, and permissions.
Install
npx skills add https://github.com/alextangson/feishu_skills --skill feishu-bitableWhat is this skill?
- Full record lifecycle: single/batch create, update, delete, and search with filter, sort, and pagination
- Paginated search loop pattern for fetching all records (500 per page until has_more is false)
- Shared token script with cache, 5-minute early refresh, and one forced refresh retry on 401
- Field management, views, permissions, formulas, and linked records documented against bitable:app scopes
- Required permissions: bitable:app and bitable:app:readonly
- Batch create/update/delete up to 500 records per call
- Search pagination uses page_size 500 until has_more is false
- Token cache refreshes 5 minutes before expiry with one forced refresh retry on invalid token
Adoption & trust: 806 installs on skills.sh; 62 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need your coding agent to read and write Feishu Bitable data but lack a single, token-aware playbook for CRUD, batch jobs, and pagination.
Who is it for?
Solo builders on Feishu/Lark who automate ops tables, sync records from code, or extend existing feishu_skills workflows.
Skip if: Teams not on Feishu, builders who only need spreadsheet export without API access, or apps that cannot store app secrets safely.
When should I use this skill?
When automating Feishu multidimensional tables: records, fields, views, permissions, formulas, or linked data via Bitable API.
What do I get? / Deliverables
After following the skill, your agent can authenticate, call documented Bitable endpoints, and page through full datasets with a defined 401 refresh-and-retry path.
- Working Bitable API requests with Bearer auth
- Paginated record exports or sync scripts
- Batch record mutations aligned to documented endpoints
Recommended Skills
Journey fit
Bitable automation sits in Build because you connect product data and ops tables to your app or agent workflows. Integrations is the canonical shelf for third-party SaaS APIs (Feishu/Lark) rather than in-repo backend code.
How it compares
Use as a Feishu-native integration skill—not a generic SQL or Airtable MCP—and pair with sibling feishu_skills for auth at the repo root.
Common Questions / FAQ
Who is feishu-bitable for?
Indie and solo developers using Feishu multidimensional tables who want Claude Code, Cursor, or Codex agents to perform API-backed record and schema operations with documented permissions.
When should I use feishu-bitable?
Use it during Build when wiring integrations—syncing CRM rows, batch-importing records, updating fields, or searching tables—or when debugging token and pagination against open.feishu.cn Bitable v1.
Is feishu-bitable safe to install?
It requires bitable:app scopes and stores app credentials via environment variables; review the Security Audits panel on this Prism page and restrict secrets to your deployment environment before granting network access.
SKILL.md
READMESKILL.md - Feishu Bitable
# 飞书多维表格 通过 Bitable API 操作数据、字段、视图和权限。 **Base URL**: `https://open.feishu.cn/open-apis/bitable/v1` ## 认证与 Token 获取 从 `feishu_skills` 根目录执行共享脚本： ```bash TOKEN="$(./scripts/get_feishu_token.sh)" ``` 请求头统一使用 `Authorization: Bearer ${TOKEN}`。 如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求： ```bash 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 获取 --- ## 记录操作 | 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`）： ```python 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"] ``` **请求示例**: ```json { "fields": { "名称": "测试", "金额": 100, "进度": 0.75, "评分": 4, "日期": 1770508800000, "状态": "进行中", "标签": ["重要", "紧急"], "完成": true, "负责人": [{"id": "ou_xxx"}], "电话": "13800138000", "链接": {"text": "官网", "link": "https://example.com"} } } ``` ⚠️ 数值不要传字符串，日期必须是 13 位毫秒时间戳。 --- ## 字段类型格式 | type | ui_type | 中文名 | 写入格式 | 示例 | |------|---------|--------|---------|------| | 1 | Text | 多行文本 | 字符串 | `"办公用品"` | | 1 | Email | 邮箱 | 字符串 | `"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 写入**: 公式、查找引用、创建时间、修改人、自动编号 **日期格式转换**: ```python import datetime ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000) # → 1770508800000 ``` --- ## 字段管理 | API | 端点 | 说明 | |-----|------|------| | 获取字段列表 | `GET .../fields` | 返回 type 和 ui_name | | 新增字段 | `POST .../fields` | `{"field_name":"新字段","type":1}` | | 更新字段 | `PUT .../fields/{field_id}` | 修改单选需提供完整 property | | 删除字段 | `DELETE .../fields/{field_id}` | - | **公式字段示例**: ```json { "type": 20, "field_name": "利润", "property": {"formula_expression": "[营收]-[成本]"} } ``` **关联字段示例**: ```json { "type": 18, "field_name": "关联客户", "property": {"table_id": "tblXXX", "multiple": true} } ``` --- ## 数据表管理 | API | 端点 | 说明 | |-----|------|------| | 创建多维表格 | `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` --- ## 视图管理 | API | 端点 | 说明 | |-----|--