feishu-bitable
installsforks
How to install feishu-bitable?
op7418/codepilot/feishu-bitable
$npx -y skills add op7418/CodePilot --skill feishu-bitable飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 当以下情况时使用此 Skill： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段" (5) 需要批量导入数据或批量更新多维表格
SKILL.md
| 1 | # Feishu Bitable (多维表格) SKILL |
| 2 | |
| 3 | ## 🚨 执行前必读 |
| 4 | |
| 5 | - ✅ **创建数据表**：支持两种模式 — ① 明确需求时，在 `create` 时通过 `table.fields` 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整） |
| 6 | - ⚠️ **默认表的空行坑**：`app.create` 自带的默认表中会有空记录（空行）！插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行，避免数据污染 |
| 7 | - ✅ **写记录前**：先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type |
| 8 | - ✅ **人员字段**：默认 open_id（ou_...），值必须是 `[{id:"ou_xxx"}]`（数组对象） |
| 9 | - ✅ **日期字段**：毫秒时间戳（例如 `1674206443000`），不是秒 |
| 10 | - ✅ **单选字段**：字符串（例如 `"选项1"`），不是数组 |
| 11 | - ✅ **多选字段**：字符串数组（例如 `["选项1", "选项2"]`） |
| 12 | - ✅ **附件字段**：必须先上传到当前多维表格，使用返回的 file_token |
| 13 | - ✅ **批量上限**：单次 ≤ 500 条，超过需分批（批量操作是原子性的） |
| 14 | - ✅ **并发限制**：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒 |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## 📋 快速索引：意图 → 工具 → 必填参数 |
| 19 | |
| 20 | | 用户意图 | 工具 | action | 必填参数 | 常用可选 | |
| 21 | |---------|------|--------|---------|---------| |
| 22 | | 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - | |
| 23 | | 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names | |
| 24 | | 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - | |
| 25 | | 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - | |
| 26 | | 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - | |
| 27 | | 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - | |
| 28 | | 创建多维表格 | feishu_bitable_app | create | name | folder_token | |
| 29 | | 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields | |
| 30 | | 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property | |
| 31 | | 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - | |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## 🎯 核心约束（Schema 未透露的知识） |
| 36 | |
| 37 | ### 📚 详细参考文档 |
| 38 | |
| 39 | **当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档**： |
| 40 | |
| 41 | - **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构（单选的 options、进度的 min/max、关联的 table_id 等） |
| 42 | - **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等） |
| 43 | - **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等） |
| 44 | |
| 45 | **何时查阅**: |
| 46 | - 创建/更新字段时收到 `125408X` 错误码（property 结构错误）→ 查 field-properties.md |
| 47 | - 写入记录时收到 `125406X` 错误码（字段值转换失败）→ 查 record-values.md |
| 48 | - 需要完整的操作流程和参数示例 → 查 examples.md |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ### 1. 字段类型与值格式必须严格匹配 |
| 53 | |
| 54 | **Bitable 最大的坑**：不同字段类型对 value 的数据结构要求完全不同。 |
| 55 | |
| 56 | #### 最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)） |
| 57 | |
| 58 | | type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 | |
| 59 | |------|---------|----------|---------|-----------| |
| 60 | | 11 | User | 人员 | `[{id: "ou_xxx"}]` | 传字符串 `"ou_xxx"` 或 `[{name: "张三"}]` | |
| 61 | | 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 | |
| 62 | | 3 | SingleSelect | 单选 | `"选项名"` | 传数组 `["选项名"]` | |
| 63 | | 4 | MultiSelect | 多选 | `["选项1", "选项2"]` | 传字符串 `"选项1"` | |
| 64 | | 15 | Url | 超链接 | `{link: "...", text: "..."}` | 只传字符串 URL | |
| 65 | | 17 | Attachment | 附件 | `[{file_token: "..."}]` | 传外部 URL 或本地路径 | |
| 66 | |
| 67 | **强制流程**： |
| 68 | 1. 先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type` |
| 69 | 2. 根据上表或 [record-values.md](references/record-values.md) 构造正确格式 |
| 70 | 3. 错误码 `125406X` 或 `1254015` → 检查字段值格式 |
| 71 | |
| 72 | **人员字段特别注意**： |
| 73 | - 默认使用 open_id（ou_...），与 calendar/task 一致 |
| 74 | - 格式：`[{id: "ou_xxx"}]`（数组对象） |
| 75 | - **只能传 id 字段**，不能传 name/email 等 |
| 76 | |
| 77 | |
| 78 | ## 📌 核心使用场景 |
| 79 | |
| 80 | > **完整示例**: 查阅 [examples.md](references/examples.md) 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等） |
| 81 | |
| 82 | ### 场景 1: 查字段类型（必做第一步） |
| 83 | |
| 84 | ```json |
| 85 | { |
| 86 | "action": "list", |
| 87 | "app_token": "S404b...", |
| 88 | "table_id": "tbl..." |
| 89 | } |
| 90 | ``` |
| 91 | |
| 92 | **返回**：包含每个字段的 `field_id`、`field_name`、`type`、`ui_type`、`property` |
| 93 | |
| 94 | ### 场景 2: 批量导入客户数据 |
| 95 | |
| 96 | ```json |
| 97 | { |
| 98 | "action": "batch_create", |
| 99 | "app_token": "S404b...", |
| 100 | "table_id": "tbl...", |
| 101 | "records": [ |
| 102 | { |
| 103 | "fields": { |
| 104 | "客户名称": "字节跳动", |
| 105 | "负责人": [{"id": "ou_xxx"}], |
| 106 | "签约日期": 1674206443000, |
| 107 | "状态": "进行中" |
| 108 | } |
| 109 | }, |
| 110 | { |
| 111 | "fields": { |
| 112 | "客户名称": "飞书", |
| 113 | "负责人": [{"id": "ou_yyy"}], |
| 114 | "签约日期": 1675416243000, |
| 115 | "状态": "已完成" |
| 116 | } |
| 117 | } |
| 118 | ] |
| 119 | } |
| 120 | ``` |
| 121 | |
| 122 | **字段值格式**： |
| 123 | - 人员：`[{id: "ou_xxx"}]`（数组对象） |
| 124 | - 日期：毫秒时间戳 |
| 125 | - 单选：字符串 |
| 126 | - 多选：字符串数组 |
| 127 | |
| 128 | **限制**: 最多 500 条记录 |
| 129 | |
| 130 | ### 场景 3: 筛选查询（高级筛选） |
| 131 | |
| 132 | ```json |
| 133 | { |
| 134 | "action": "list", |
| 135 | "app_token": "S404b...", |
| 136 | "table_id": "tbl...", |
| 137 | "filter": { |
| 138 | "conjunction": "and", |
| 139 | "conditions": [ |
| 140 | { |
| 141 | "field_name": "状态", |
| 142 | "operator": "is", |
| 143 | "value": ["进行中"] |
| 144 | }, |
| 145 | { |
| 146 | "field_name": "截止日期", |
| 147 | "operator": "isLess", |
| 148 | "value": ["ExactDate", "1740441600000"] |
| 149 | } |
| 150 | ] |
| 151 | }, |
| 152 | "sort": [ |
| 153 | { |
| 154 | "field_name": "截止日期", |
| 155 | "desc": false |
| 156 | } |
| 157 | ] |
| 158 | } |
| 159 | ``` |
| 160 | |
| 161 | **filter 说明**： |
| 162 | - 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C） |
| 163 | - ⚠️ **isEmpty/isNotEmpty 必须传 `value: []`**（虽然逻辑上不需要值，但 API 要求必须传空数组） |
| 164 | - 日期筛选可使用 `["Today"]`、`["ExactDate", "时间戳"]` 等 |
| 165 | - `sort` 可指定多个排序字段 |
| 166 | |
| 167 | --- |
| 168 | |
| 169 | ## 🔍 常见错误与排查 |
| 170 | |
| 171 | | 错误码 | 错误现象 | 根本原因 | 解决方案 | |
| 172 | |--------|---------|---------| |
People who liked this also viewed
6 picksType
- azure-resource-lookupList, find, and show Azure resources across subscriptions or resource groups. Handles prompts like \"list the websites in my subscription\", \"list my web apps\", \"show my app services\", \"list virtSkillsJul 2026
- azure-messagingTroubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. SkillsJul 2026
- lark-doc飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 SkillsJul 2026
- lark-im飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 FeedSkillsJul 2026
- lark-wiki飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URLSkillsJul 2026
- lark-mail飞书邮箱：Use when user mentions 起草邮件、写邮件、草稿、发送/回复/转发邮件、查阅邮件、看邮件、搜索邮件、邮件文件夹、邮件标签、邮件联系人、监听新邮件、邮件收信规则等；use for mail/email intent only. Do not use for docs/sheets/calendar/auth setup/pure contact lookup/IM chSkillsJul 2026
