Feishu Bitable

Feishu Bitable (多维表格) SKILL

🚨 执行前必读

• ✅ 创建数据表：支持两种模式 — ① 明确需求时，在 create 时通过 table.fields 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）
• ⚠️ 默认表的空行坑：app.create 自带的默认表中会有空记录（空行）！插入数据前建议先调用 feishu_bitable_app_table_record.list + batch_delete 删除空行，避免数据污染
• ✅ 写记录前：先调用 feishu_bitable_app_table_field.list 获取字段 type/ui_type
• ✅ 人员字段：默认 open_id（ou_...），值必须是 [{id:"ou_xxx"}]（数组对象）
• ✅ 日期字段：毫秒时间戳（例如 1674206443000），不是秒
• ✅ 单选字段：字符串（例如 "选项1"），不是数组
• ✅ 多选字段：字符串数组（例如 ["选项1", "选项2"]）
• ✅ 附件字段：必须先上传到当前多维表格，使用返回的 file_token
• ✅ 批量上限：单次 ≤ 500 条，超过需分批（批量操作是原子性的）
• ✅ 并发限制：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒

---

📋 快速索引：意图 → 工具 → 必填参数

---

🎯 核心约束（Schema 未透露的知识）

📚 详细参考文档

当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档：

• [字段 Property 配置详解](references/field-properties.md) - 每种字段类型创建/更新时需要的 property 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）
• [记录值数据结构详解](references/record-values.md) - 每种字段类型在记录中对应的 fields 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）
• [使用场景完整示例](references/examples.md) - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）

何时查阅:

• 创建/更新字段时收到 125408X 错误码（property 结构错误）→ 查 field-properties.md
• 写入记录时收到 125406X 错误码（字段值转换失败）→ 查 record-values.md
• 需要完整的操作流程和参数示例 → 查 examples.md

---

1. 字段类型与值格式必须严格匹配

Bitable 最大的坑：不同字段类型对 value 的数据结构要求完全不同。

最易错的字段类型（完整列表见 record-values.md）

强制流程： 1. 先调用 feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type 2. 根据上表或 record-values.md 构造正确格式 3. 错误码 125406X 或 1254015 → 检查字段值格式

人员字段特别注意：

• 默认使用 open_id（ou_...），与 calendar/task 一致
• 格式：[{id: "ou_xxx"}]（数组对象）
• 只能传 id 字段，不能传 name/email 等

📌 核心使用场景

完整示例: 查阅 examples.md 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）

场景 1: 查字段类型（必做第一步）

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl..."
}

返回：包含每个字段的 field_id、field_name、type、ui_type、property

场景 2: 批量导入客户数据

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "客户名称": "Bytedance",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1674206443000,
        "状态": "进行中"
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_yyy"}],
        "签约日期": 1675416243000,
        "状态": "已完成"
      }
    }
  ]
}

字段值格式：

• 人员：[{id: "ou_xxx"}]（数组对象）
• 日期：毫秒时间戳
• 单选：字符串
• 多选：字符串数组

限制: 最多 500 条记录

场景 3: 筛选查询（高级筛选）

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "截止日期",
      "desc": false
    }
  ]
}

filter 说明：

• 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）
• ⚠️ isEmpty/isNotEmpty 必须传 `value: []`（虽然逻辑上不需要值，但 API 要求必须传空数组）
• 日期筛选可使用 ["Today"]、["ExactDate", "时间戳"] 等
• sort 可指定多个排序字段

---

🔍 常见错误与排查

---

📚 附录：背景知识

A. 资源层级关系

App (多维表格应用)
 ├── Table (数据表) ×100
 │    ├── Record (记录/行) ×20,000
 │    ├── Field (字段/列) ×300
 │    └── View (视图) ×200
 └── Dashboard (仪表盘)

B. 筛选条件 operator 列表

日期字段特殊值: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"] 等（完整列表见 examples.md）

C. 使用限制

D. 其他约束

• 从其他数据源同步的数据表，不支持增删改记录
• 公式字段、查看引用字段是只读的
• 删除操作无法恢复
• 视图筛选条件使用 field_id，需先调用 field.list 获取

飞书多维表格使用场景完整示例

本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。

基础参考: 先查阅 字段 Property 配置详解 和 记录值数据结构详解

---

📋 目录

1. 场景 0: 创建数据表（两种模式对比） 2. 场景 1: 查字段类型（必做第一步） 3. 场景 2: 批量导入客户数据 4. 场景 2.5: 创建表并插入数据（含空行处理） 5. 场景 3: 筛选查询（高级筛选） 6. 场景 4: 更新单条记录 7. 场景 5: 创建带选项的单选字段 8. 场景 6: 创建复杂字段（进度、货币、评分） 9. 场景 7: 处理附件字段 10. 场景 8: 双向关联字段

---

场景 0: 创建数据表（两种模式对比）

模式 A：一次性定义所有字段

适用场景：字段类型、配置都已明确，需要快速创建表结构。

优势：一次 API 调用，原子性操作。

工具: feishu_bitable_app_table

{
  "action": "create",
  "app_token": "S404b...",
  "table": {
    "name": "客户管理表",
    "default_view_name": "所有客户",
    "fields": [
      {
        "field_name": "客户名称",
        "type": 1
      },
      {
        "field_name": "负责人",
        "type": 11,
        "property": {
          "multiple": false
        }
      },
      {
        "field_name": "签约日期",
        "type": 5,
        "property": {
          "date_formatter": "yyyy-MM-dd"
        }
      },
      {
        "field_name": "状态",
        "type": 3,
        "property": {
          "options": [
            {"name": "进行中", "color": 0},
            {"name": "已完成", "color": 10}
          ]
        }
      },
      {
        "field_name": "金额",
        "type": 2,
        "ui_type": "Currency",
        "property": {
          "currency_code": "CNY",
          "formatter": "0.00"
        }
      }
    ]
  }
}

返回示例:

{
  "table_id": "tblXXXXXXXX",
  "name": "客户管理表",
  "default_view_id": "vewXXXXXXXX"
}

---

模式 B：使用默认表 + 逐步修改字段

适用场景：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。

优势：

• app.create 自带默认表和默认字段，可在此基础上调整
• 复杂字段（单选 options、URL 格式等）分步确认，减少出错
• 踩坑后容易回退（比如 URL 字段改为文本字段）

完整流程：

步骤 1: 创建 App（工具: feishu_bitable_app）

{
  "action": "create",
  "name": "客户管理系统",
  "folder_token": "fldXXXXXXXX"
}

返回: 包含 app_token 和默认表的 default_table_id

---

步骤 2: 查看默认字段（工具: feishu_bitable_app_table_field）

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}

返回示例:

{
  "fields": [
    {
      "field_id": "fld001",
      "field_name": "文本",
      "type": 1,
      "ui_type": "Text"
    },
    {
      "field_id": "fld002",
      "field_name": "数字",
      "type": 2,
      "ui_type": "Number"
    }
  ]
}

---

步骤 3: 修改默认字段名称（工具: feishu_bitable_app_table_field）

{
  "action": "update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_id": "fld001",
  "field_name": "客户名称"
}

---

步骤 4: 补充缺失字段（工具: feishu_bitable_app_table_field）

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "负责人",
  "type": 11,
  "property": {
    "multiple": false
  }
}

---

步骤 5: 查看空记录（工具: feishu_bitable_app_table_record）

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}

返回: 可能包含空记录 [{"record_id": "recxxx", "fields": {}}, ...]

---

步骤 6: 删除空行（工具: feishu_bitable_app_table_record）

{
  "action": "batch_delete",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": ["recxxx", "recyyy"]
}

---

步骤 7: 批量插入数据（工具: feishu_bitable_app_table_record）

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "fields": {
        "客户名称": "Bytedance",
        "负责人": [{"id": "ou_xxx"}],
        "状态": "进行中"
      }
    }
  ]
}

---

⚠️ 模式 B 的关键注意事项:

• 默认表中通常已有空记录，必须先删除，否则会有数据污染
• 步骤 5-6 是必需的，不能跳过
• 适合不确定字段配置的探索式场景

---

场景 1: 查字段类型（必做第一步）

为什么必做: 不同字段类型的值格式完全不同，必须先查询再写入。

工具: feishu_bitable_app_table_field

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}

返回示例:

{
  "fields": [
    {
      "field_id": "fld001",
      "field_name": "任务名称",
      "type": 1,
      "ui_type": "Text",
      "property": {}
    },
    {
      "field_id": "fld002",
      "field_name": "负责人",
      "type": 11,
      "ui_type": "User",
      "property": {
        "multiple": true
      }
    },
    {
      "field_id": "fld003",
      "field_name": "截止日期",
      "type": 5,
      "ui_type": "DateTime",
      "property": {
        "date_formatter": "yyyy-MM-dd HH:mm"
      }
    },
    {
      "field_id": "fld004",
      "field_name": "状态",
      "type": 3,
      "ui_type": "SingleSelect",
      "property": {
        "options": [
          {"id": "optXXX", "name": "进行中", "color": 0},
          {"id": "optYYY", "name": "已完成", "color": 10}
        ]
      }
    }
  ]
}

关键信息:

• type: 字段基础类型（1=文本, 2=数字, 3=单选...）
• ui_type: UI 展示类型（区分进度、货币、评分等）
• property: 字段配置（单选的 options、日期的 formatter 等）

---

场景 2: 批量导入客户数据

工具: feishu_bitable_app_table_record

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "fields": {
        "客户名称": "某某",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1674206443000,
        "状态": "进行中",
        "金额": 1000000,
        "标签": ["重要客户", "战略合作"],
        "联系电话": "17899870000",
        "官网": {
          "text": "某某官网",
          "link": "https://www.xxxx.com"
        }
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1675416243000,
        "状态": "已完成",
        "金额": 500000,
        "标签": ["核心产品"],
        "联系电话": "13800138000"
      }
    }
  ]
}

字段值格式说明:

• 文本: 字符串 "客户名称"
• 人员: 对象数组 [{"id": "ou_xxx"}]（只能传 id）
• 日期: 毫秒时间戳 1674206443000
• 单选: 字符串 "进行中"
• 多选: 字符串数组 ["重要客户", "战略合作"]
• 数字: 数字 1000000
• 电话: 字符串 "17899870000"
• 超链接: 对象 {"text": "显示文本", "link": "URL"}

返回示例:

{
  "records": [
    {
      "record_id": "rec001",
      "fields": {...}
    },
    {
      "record_id": "rec002",
      "fields": {...}
    }
  ]
}

限制:

• 单次最多 500 条记录
• 超过需分批调用

---

场景 2.5: 创建表并插入数据（含空行处理）

问题: app.create 创建的默认表中会自带空记录（空行），直接插入数据会导致数据污染。

正确流程: 见场景 0 的模式 B

核心步骤: 1. 创建 App → 获取 app_token 和 default_table_id 2. 查看默认表记录 (list action) 3. 删除空行 (batch_delete action) 4. 批量插入数据 (batch_create action)

错误示例（跳过步骤 2-3）:

表格最终状态：
| 客户名称 | 负责人 | 状态 |
|---------|--------|------|
|         |        |      | ← 空行（原有）
| Bytedance | 张三   | 进行中 | ← 新插入
| 飞书    | 李四   | 已完成 | ← 新插入

正确示例（执行步骤 2-3）:

表格最终状态：
| 客户名称 | 负责人 | 状态 |
|---------|--------|------|
| Bytedance | 张三   | 进行中 |
| 飞书    | 李四   | 已完成 |

---

场景 3: 筛选查询（高级筛选）

工具: feishu_bitable_app_table_record

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      },
      {
        "field_name": "优先级",
        "operator": "isGreater",
        "value": ["3"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "截止日期",
      "desc": false
    },
    {
      "field_name": "优先级",
      "desc": true
    }
  ],
  "field_names": ["任务名称", "负责人", "截止日期", "状态"],
  "page_size": 100
}

参数说明:

filter 结构

• conjunction: 条件组合方式（"and" 或 "or"）
• conditions: 条件数组

operator 类型（10 种）

日期字段特殊值

// 具体日期
{"operator": "is", "value": ["ExactDate", "1702449755000"]}

// 相对日期
{"operator": "is", "value": ["Today"]}      // 今天
{"operator": "is", "value": ["Tomorrow"]}   // 明天
{"operator": "is", "value": ["Yesterday"]}  // 昨天
{"operator": "is", "value": ["CurrentWeek"]} // 本周
{"operator": "is", "value": ["LastWeek"]}   // 上周
{"operator": "is", "value": ["TheLastWeek"]} // 过去七天
{"operator": "is", "value": ["TheNextWeek"]} // 未来七天

sort 结构

• field_name: 排序字段
• desc: true 降序，false 升序
• 支持多字段排序（按数组顺序）

---

场景 4: 更新单条记录

工具: feishu_bitable_app_table_record

{
  "action": "update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "record_id": "recusyQbB0fVL5",
  "fields": {
    "状态": "已完成",
    "完成时间": 1674206443000,
    "备注": "客户已签约"
  }
}

说明:

• 只传需要更新的字段
• 不传的字段保持不变
• 支持部分字段更新

批量更新（最多 500 条）:

{
  "action": "batch_update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "record_id": "rec001",
      "fields": {
        "状态": "已完成"
      }
    },
    {
      "record_id": "rec002",
      "fields": {
        "状态": "已完成"
      }
    }
  ]
}

---

场景 5: 创建带选项的单选字段

工具: feishu_bitable_app_table_field

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "优先级",
  "type": 3,
  "property": {
    "options": [
      {"name": "高", "color": 0},
      {"name": "中", "color": 1},
      {"name": "低", "color": 2}
    ]
  }
}

颜色编号（color 范围 0-54）:

• 0: 红色
• 1: 橙色
• 10: 绿色
• 20: 蓝色

多选字段（type=4）格式相同:

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "标签",
  "type": 4,
  "property": {
    "options": [
      {"name": "重要", "color": 0},
      {"name": "紧急", "color": 1},
      {"name": "长期", "color": 10}
    ]
  }
}

注意:

• 创建时不能指定选项 ID（id 字段），系统自动生成
• 选项总数不超过 20,000

---

场景 6: 创建复杂字段（进度、货币、评分）

进度字段 (type=2, ui_type="Progress")

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "完成进度",
  "type": 2,
  "ui_type": "Progress",
  "property": {
    "min": 0,
    "max": 100,
    "range_customize": true
  }
}

写入值: 0.75 表示 75%

---

货币字段 (type=2, ui_type="Currency")

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "预算",
  "type": 2,
  "ui_type": "Currency",
  "property": {
    "currency_code": "CNY",
    "formatter": "0,000.00"
  }
}

currency_code 可选值:

• "CNY": 人民币 (¥)
• "USD": 美元 ($)
• "EUR": 欧元 (€)
• "JPY": 日元 (¥)

写入值: 5000.50（普通数字）

---

评分字段 (type=2, ui_type="Rating")

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "客户满意度",
  "type": 2,
  "ui_type": "Rating",
  "property": {
    "min": 1,
    "max": 5,
    "rating": {
      "symbol": "star"
    }
  }
}

symbol 可选值:

• "star": ⭐ 星星
• "heart": ❤️ 爱心
• "fire": 🔥 火焰
• "thumbsup": 👍 赞

写入值: 4（整数）

---

场景 7: 处理附件字段

步骤 1: 上传附件到多维表格

工具: feishu_drive_media（上传素材接口）

{
  "action": "upload",
  "file_path": "/path/to/file.pdf",
  "parent_type": "bitable_image",
  "parent_node": "S404b..."  // app_token
}

返回:

{
  "file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"
}

---

步骤 2: 创建附件字段（可选）

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "合同文件",
  "type": 17
}

---

步骤 3: 写入附件记录

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "fields": {
    "客户名称": "Bytedance",
    "合同文件": [
      {"file_token": "DRiFxxxxxxxxxxxxxxxxxxCccoe"},
      {"file_token": "BZk3bxxxxxxxxxxxxxxxxeKqcLe"}
    ]
  }
}

限制:

• 单个单元格附件数不超过 100
• 必须先上传到当前多维表格，不能用外部 file_token

---

场景 8: 双向关联字段

步骤 1: 创建双向关联字段

在"任务表"中创建关联到"项目表"的字段:

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "field_name": "所属项目",
  "type": 21,
  "property": {
    "table_id": "tbl_project",
    "back_field_name": "关联的任务",
    "multiple": true
  }
}

结果:

• 在"任务表"中创建字段"所属项目"
• 在"项目表"中自动创建字段"关联的任务"

---

步骤 2: 写入关联记录

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "fields": {
    "任务名称": "开发新功能",
    "所属项目": {
      "link_record_ids": ["rec_project_001"]
    }
  }
}

级联更新:

• 在"任务表"中设置"所属项目"为 rec_project_001
• "项目表"的 rec_project_001 记录的"关联的任务"字段会自动添加当前任务的 record_id

---

单向关联 (type=18)

区别: 只影响当前表，不会自动更新对方表

{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "field_name": "参考任务",
  "type": 18,
  "property": {
    "table_id": "tbl_task",  // 可以关联自己
    "multiple": true
  }
}

---

🔗 参考链接

• 字段 Property 配置详解
• 记录值数据结构详解
• 飞书开放平台 - 多维表格文档

飞书多维表格字段 Property 配置详解

本文档详细说明每种字段类型创建或更新时需要的 property 参数结构。

来源: 基于飞书开放平台文档 字段编辑指南

📋 目录

• 基础字段
• 1. 文本 (type=1)
• 2. 数字 (type=2)
• 5. 日期 (type=5)
• 7. 复选框 (type=7)
• 13. 电话号码 (type=13)
• 选择字段
• 3. 单选 (type=3)
• 4. 多选 (type=4)
• 特殊显示字段
• 进度 (type=2, ui_type="Progress")
• 货币 (type=2, ui_type="Currency")
• 评分 (type=2, ui_type="Rating")
• 条码 (type=1, ui_type="Barcode")
• 邮箱 (type=1, ui_type="Email")
• 关系字段
• 11. 人员 (type=11)
• 15. 超链接 (type=15)
• 17. 附件 (type=17)
• 18. 单向关联 (type=18)
• 21. 双向关联 (type=21)
• 22. 地理位置 (type=22)
• 23. 群组 (type=23)
• 高级字段
• 20. 公式 (type=20)
• 1001. 创建时间 (type=1001)
• 1002. 最后更新时间 (type=1002)
• 1005. 自动编号 (type=1005)

---

基础字段

1. 文本 (type=1)

Property 结构: 空对象或省略

{
  "type": 1,
  "field_name": "任务描述",
  "property": {}
}

注意:

• 默认 ui_type 为 "Text"
• 单个单元格最多 10 万字符
• 支持富文本格式（提及人、超链接等）

---

2. 数字 (type=2)

Property 结构:

{
  "formatter": "0"  // 可选，数字显示格式
}

formatter 可选值:

• "0": 整数（默认）
• "0.0": 一位小数
• "0.00": 两位小数
• "0,000": 千分位
• "0.00%": 百分比

示例:

{
  "type": 2,
  "field_name": "工时",
  "property": {
    "formatter": "0.00"
  }
}

---

5. 日期 (type=5)

Property 结构:

{
  "date_formatter": "yyyy/MM/dd",  // 可选，默认 "yyyy/MM/dd"
  "auto_fill": false               // 可选，是否自动填充创建时间
}

date_formatter 可选值:

• "yyyy/MM/dd": 2021/1/30
• "yyyy-MM-dd HH:mm": 2021/1/30 14:00
• "MM-dd": 1月30日
• "MM/dd/yyyy": 01/30/2021
• "dd/MM/yyyy": 30/01/2021

示例:

{
  "type": 5,
  "field_name": "截止日期",
  "property": {
    "date_formatter": "yyyy-MM-dd HH:mm",
    "auto_fill": false
  }
}

---

7. 复选框 (type=7)

Property 结构: 空对象或省略

{
  "type": 7,
  "field_name": "是否完成",
  "property": {}
}

---

13. 电话号码 (type=13)

Property 结构: 空对象或省略

{
  "type": 13,
  "field_name": "联系电话",
  "property": {}
}

注意:

• 电话号码格式：符合正则 (\+)?\d*
• 最大长度 64 字符

---

选择字段

3. 单选 (type=3)

Property 结构:

{
  "options": [
    {
      "name": "进行中",   // 必填，选项名称
      "color": 0         // 可选，颜色编号 (0-54)
    },
    {
      "name": "已完成",
      "color": 10
    }
  ]
}

颜色编号 (color):

• 范围: 0-54
• 0: 红色
• 10: 绿色
• 20: 蓝色
• ... (详见飞书官方文档)

示例:

{
  "type": 3,
  "field_name": "任务状态",
  "property": {
    "options": [
      {"name": "待开始", "color": 0},
      {"name": "进行中", "color": 20},
      {"name": "已完成", "color": 10}
    ]
  }
}

注意:

• 选项总数不超过 20,000 个
• 创建时不能指定选项 ID（id 字段），系统自动生成
• 更新时需保留已有选项的 id

---

4. 多选 (type=4)

Property 结构: 与单选相同

{
  "options": [
    {"name": "紧急", "color": 0},
    {"name": "重要", "color": 10}
  ]
}

注意:

• 选项总数不超过 20,000 个
• 单个单元格选项数不超过 1,000 个

---

特殊显示字段

进度 (type=2, ui_type="Progress")

Property 结构:

{
  "min": 0,                  // 必填，最小值
  "max": 100,                // 必填，最大值
  "range_customize": false   // 可选，是否允许自定义进度值
}

示例:

{
  "type": 2,
  "field_name": "完成进度",
  "ui_type": "Progress",
  "property": {
    "min": 0,
    "max": 100,
    "range_customize": true
  }
}

注意:

• min 取值范围: 0-1
• max 取值范围: 1-100
• range_customize 为 true 时用户可输入超出范围的值

---

货币 (type=2, ui_type="Currency")

Property 结构:

{
  "currency_code": "CNY",  // 必填，货币类型
  "formatter": "0.00"      // 可选，数字格式
}

currency_code 可选值:

• "CNY": 人民币 (¥)
• "USD": 美元 ($)
• "EUR": 欧元 (€)
• "GBP": 英镑 (£)
• "JPY": 日元 (¥)
• "HKD": 港元 ($)
• ... (支持 20+ 种货币)

示例:

{
  "type": 2,
  "field_name": "预算",
  "ui_type": "Currency",
  "property": {
    "currency_code": "USD",
    "formatter": "0,000.00"
  }
}

---

评分 (type=2, ui_type="Rating")

Property 结构:

{
  "min": 1,                 // 必填，最小值
  "max": 5,                 // 必填，最大值
  "rating": {               // 可选，评分样式
    "symbol": "star"        // 图标类型
  }
}

symbol 可选值:

• "star": ⭐ 星星（默认）
• "heart": ❤️ 爱心
• "thumbsup": 👍 赞
• "fire": 🔥 火焰
• "smile": 😊 笑脸
• "lightning": ⚡ 闪电
• "flower": 🌸 花朵
• "number": 数字

示例:

{
  "type": 2,
  "field_name": "优先级",
  "ui_type": "Rating",
  "property": {
    "min": 1,
    "max": 5,
    "rating": {
      "symbol": "fire"
    }
  }
}

---

条码 (type=1, ui_type="Barcode")

Property 结构:

{
  "allowed_edit_modes": {
    "manual": true,   // 是否允许手动录入
    "scan": true      // 是否允许扫描录入
  }
}

示例:

{
  "type": 1,
  "field_name": "商品条码",
  "ui_type": "Barcode",
  "property": {
    "allowed_edit_modes": {
      "manual": false,
      "scan": true
    }
  }
}

---

邮箱 (type=1, ui_type="Email")

Property 结构: 空对象或省略

{
  "type": 1,
  "field_name": "联系邮箱",
  "ui_type": "Email",
  "property": {}
}

---

关系字段

11. 人员 (type=11)

Property 结构:

{
  "multiple": true  // 可选，是否允许多个人员，默认 true
}

示例:

{
  "type": 11,
  "field_name": "负责人",
  "property": {
    "multiple": false  // 只允许单个人员
  }
}

注意:

• 单个单元格人员数不超过 1,000
• 记录值只支持传入 id 字段（open_id/union_id/user_id）

---

15. 超链接 (type=15)

Property 结构: 必须省略 `property` 参数，不要传递任何值（包括空对象）

{
  "type": 15,
  "field_name": "参考链接"
  // 不要传 property 参数，包括空对象 {}
}

⚠️ 重要: 超链接字段的特殊要求（经实测验证）：

• ✅ 正确: 完全省略 property 参数
• ❌ 错误: "property": {}（会报 URLFieldPropertyError）
• ❌ 错误: 传递任何 property 值

注意: 这是飞书 API 的特殊行为，超链接字段即使传空对象也会报错，必须完全省略该参数。

---

17. 附件 (type=17)

Property 结构: 空对象或省略

{
  "type": 17,
  "field_name": "附件",
  "property": {}
}

注意:

• 单个单元格附件数不超过 100
• 写入前需先调用上传素材接口

---

18. 单向关联 (type=18)

Property 结构:

{
  "table_id": "tblXXXXXXXX",  // 必填，关联的数据表 ID
  "multiple": true             // 可选，是否允许多条记录，默认 true
}

示例:

{
  "type": 18,
  "field_name": "关联任务",
  "property": {
    "table_id": "tblsRc9GRRXKqhvW",
    "multiple": true
  }
}

注意:

• 单个单元格关联数不超过 500

---

21. 双向关联 (type=21)

Property 结构:

{
  "table_id": "tblXXXXXXXX",      // 必填，关联的数据表 ID
  "back_field_name": "反向字段名",  // 必填，对方表的双向关联字段名
  "multiple": true                 // 可选，是否允许多条记录
}

示例:

{
  "type": 21,
  "field_name": "相关项目",
  "property": {
    "table_id": "tblAnotherTable",
    "back_field_name": "关联的任务",
    "multiple": true
  }
}

注意:

• 单个单元格关联数不超过 500
• 对方表会自动创建对应的双向关联字段

---

22. 地理位置 (type=22)

Property 结构:

{
  "location": {
    "input_type": "not_limit"  // 输入限制
  }
}

input_type 可选值:

• "only_mobile": 仅允许移动端实时定位
• "not_limit": 无限制（默认）

示例:

{
  "type": 22,
  "field_name": "办公地址",
  "property": {
    "location": {
      "input_type": "only_mobile"
    }
  }
}

---

23. 群组 (type=23)

Property 结构: 空对象或省略

{
  "type": 23,
  "field_name": "协作群",
  "property": {}
}

注意:

• 单个单元格群组数不超过 10 个

---

高级字段

20. 公式 (type=20)

Property 结构:

{
  "formula_expression": "bitable::$table[tblXXX].$field[fldYYY]*2"  // 可选
}

示例:

{
  "type": 20,
  "field_name": "总价",
  "property": {
    "formula_expression": "bitable::$table[tblMain].$field[fldQty] * $field[fldPrice]"
  }
}

注意:

• 创建字段时不支持设置公式表达式
• 参考飞书帮助中心 - 公式字段

对于某些多维表格，公式字段需要额外设置 `type` 参数（通过获取多维表格元数据接口的 formula_type 判断）:

{
  "type": 20,
  "field_name": "计算字段",
  "property": {
    "type": {
      "data_type": 2,           // 公式结果的数据类型 (1=文本, 2=数字, 5=日期...)
      "ui_property": {          // UI 展示属性
        "formatter": "0.00",
        "currency_code": "CNY"
      },
      "ui_type": "Currency"     // UI 类型 (Number/Progress/Currency/Rating/DateTime)
    }
  }
}

---

1001. 创建时间 (type=1001)

Property 结构:

{
  "date_formatter": "yyyy/MM/dd"  // 可选，日期格式
}

示例:

{
  "type": 1001,
  "field_name": "创建于",
  "property": {
    "date_formatter": "yyyy-MM-dd HH:mm"
  }
}

---

1002. 最后更新时间 (type=1002)

Property 结构: 与创建时间相同

{
  "date_formatter": "yyyy-MM-dd HH:mm"
}

---

1005. 自动编号 (type=1005)

Property 结构:

{
  "auto_serial": {
    "type": "auto_increment_number",  // 或 "custom"
    "options": [                      // 自定义编号规则（仅 type="custom" 时需要）
      {
        "type": "fixed_text",
        "value": "TASK-"
      },
      {
        "type": "created_time",
        "value": "yyyyMMdd"
      },
      {
        "type": "system_number",
        "value": "5"
      }
    ]
  }
}

auto_serial.type 可选值:

• "auto_increment_number": 纯自增数字
• "custom": 自定义编号规则

options 中的规则类型:

• "system_number": 自增数字位数（value: 1-9）
• "fixed_text": 固定字符（value: 最多 20 字符）
• "created_time": 创建时间（value: "yyyyMMdd"/"yyyyMM"/"yyyy"/"MMdd"/"MM"/"dd"）

示例 1: 纯自增:

{
  "type": 1005,
  "field_name": "编号",
  "property": {
    "auto_serial": {
      "type": "auto_increment_number"
    }
  }
}

示例 2: 自定义编号:

{
  "type": 1005,
  "field_name": "工单号",
  "property": {
    "auto_serial": {
      "type": "custom",
      "options": [
        {"type": "fixed_text", "value": "WO-"},
        {"type": "created_time", "value": "yyyyMMdd"},
        {"type": "system_number", "value": "4"}
      ]
    }
  }
}
// 生成示例: WO-20240226-0001

---

🔍 常见错误码

---

📌 更新字段时的特殊规则

调用 update action 更新字段时：

1. 必须保持字段类型一致: type 和 ui_type 不能变更 2. 单选/多选更新选项:

• 已有选项必须保留 id
• 新增选项只传 name 和 color，不传 id

3. 如果只改字段名:

• 可以只传 field_name，工具会自动查询当前 type 和 property

4. 关联字段的 table_id: 不能修改为不同的表

---

🔗 参考链接

• 飞书开放平台 - 字段编辑指南
• 新增字段接口文档
• 更新字段接口文档

飞书多维表格记录值数据结构详解

本文档详细说明每种字段类型在记录中对应的 fields 值格式。

来源: 基于飞书开放平台文档 多维表格记录数据结构

📋 快速索引

---

文本 (type=1)

基础文本 (ui_type="Text")

写入格式: 字符串

{
  "fields": {
    "任务描述": "维护客户关系"
  }
}

返回格式: 对象数组

{
  "任务描述": [
    {
      "text": "维护客户关系",
      "type": "text"
    }
  ]
}

富文本格式 (提及人、超链接):

{
  "任务描述": [
    {
      "text": "请 ",
      "type": "text"
    },
    {
      "text": "@张三",
      "type": "mention",
      "token": "ou_user123",
      "mentionType": "User",
      "mentionNotify": true,
      "name": "张三"
    },
    {
      "text": " 查看 ",
      "type": "text"
    },
    {
      "text": "飞书官网",
      "type": "url",
      "link": "https://www.feishu.cn"
    }
  ]
}

富文本元素类型:

mentionType 可选值:

• "User": 提及用户
• "Docx": 提及文档
• "Sheet": 提及电子表格
• "Bitable": 提及多维表格

---

条码 (ui_type="Barcode")

写入格式: 字符串

{
  "fields": {
    "商品条码": "FS0001"
  }
}

返回格式:

{
  "商品条码": [
    {
      "text": "FS0001",
      "type": "text"
    }
  ]
}

---

邮箱 (ui_type="Email")

写入格式: 字符串

{
  "fields": {
    "联系邮箱": "zhangmin@xxxgmail.com"
  }
}

返回格式:

{
  "联系邮箱": [
    {
      "text": "zhangmin@xxxgmail.com",
      "type": "url",
      "link": "mailto:zhangmin@xxxgmail.com"
    }
  ]
}

---

数字 (type=2)

写入/返回格式: 数字

{
  "fields": {
    "工时": 10,
    "完成率": 0.75,
    "预算": 5000.50
  }
}

注意:

• 进度 (ui_type="Progress"): 0-1 范围的小数
• 货币 (ui_type="Currency"): 普通数字
• 评分 (ui_type="Rating"): 整数

---

单选 (type=3)

写入格式: 选项名称字符串

{
  "fields": {
    "任务状态": "进行中"
  }
}

新选项: 传入不存在的选项名会自动创建新选项

{
  "fields": {
    "任务状态": "已暂停"  // 如果不存在，会自动创建
  }
}

返回格式: 与写入相同

{
  "任务状态": "进行中"
}

限制:

• 选项总数不超过 20,000

---

多选 (type=4)

写入格式: 字符串数组

{
  "fields": {
    "标签": ["审批集成", "办公管理", "身份管理"]
  }
}

新选项: 传入不存在的选项名会自动创建新选项

{
  "fields": {
    "标签": ["新标签1", "新标签2"]  // 不存在的会自动创建
  }
}

返回格式: 与写入相同

{
  "标签": ["审批集成", "办公管理"]
}

限制:

• 选项总数不超过 20,000
• 单个单元格选项数不超过 1,000

---

日期 (type=5)

写入/返回格式: Unix 毫秒时间戳

{
  "fields": {
    "截止日期": 1675526400000  // 2023-02-05 00:00:00 (UTC)
  }
}

注意:

• 必须使用毫秒级时间戳（不是秒级）
• 建议使用北京时间 (UTC+8) 转换

常见错误 (错误码 1254064):

// ❌ 错误：使用 ISO 字符串
{"截止日期": "2026-02-27"}

// ❌ 错误：使用 RFC3339 格式
{"截止日期": "2026-02-27T10:00:00+08:00"}

// ❌ 错误：使用秒级时间戳
{"截止日期": 1772121600}  // 少了 3 位

// ✅ 正确：使用毫秒时间戳
{"截止日期": 1772121600000}

---

复选框 (type=7)

写入/返回格式: 布尔值

{
  "fields": {
    "是否完成": true,
    "是否延期": false
  }
}

---

人员 (type=11)

写入格式: 对象数组，仅支持 `id` 字段

{
  "fields": {
    "负责人": [
      {"id": "ou_8240099442cf5da49f04f4bf8f8abcef"}
    ],
    "协作人": [
      {"id": "ou_user1"},
      {"id": "ou_user2"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "负责人": [
    {
      "id": "ou_8240099442cf5da49f04f4bf8f8abcef",
      "name": "黄泡泡",
      "en_name": "Amanda Huang",
      "email": "amandahuang@xxxgmail.com",
      "avatar_url": "https://..."
    }
  ]
}

⚠️ 重要:

• 写入时只支持 `id`，不能传 name、email 等字段
• id 类型需与 user_id_type 参数一致（open_id/union_id/user_id）
• 单个单元格人员数不超过 1,000
• 传空: null 或 []

---

电话号码 (type=13)

写入/返回格式: 字符串

{
  "fields": {
    "联系电话": "17899870000",
    "座机": "+86-010-12345678"
  }
}

格式规则:

• 符合正则: (\+)?\d*
• 最大长度 64 字符

---

超链接 (type=15)

写入/返回格式: 对象

{
  "fields": {
    "参考链接": {
      "text": "飞书开放平台",
      "link": "https://open.feishu.cn"
    }
  }
}

字段说明:

• text: 显示的文本
• link: URL 地址

常见错误 (错误码 1254068):

// ❌ 错误：直接传字符串 URL
{
  "参考链接": "https://open.feishu.cn"
}

// ✅ 正确：使用对象格式
{
  "参考链接": {
    "text": "飞书开放平台",
    "link": "https://open.feishu.cn"
  }
}

// ✅ text 和 link 可以相同
{
  "参考链接": {
    "text": "https://open.feishu.cn",
    "link": "https://open.feishu.cn"
  }
}

---

附件 (type=17)

写入格式: 对象数组，仅传 `file_token`

{
  "fields": {
    "附件": [
      {"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"},
      {"file_token": "BZk3bL1Enoy4pzxaPL9bNeKqcLe"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "附件": [
    {
      "file_token": "J7GdbgNWWoD1fwx7oWccxdgknIe",
      "name": "58cc930b89.png",
      "type": "image/png",
      "size": 108867,
      "url": "https://open.feishu.cn/open-apis/drive/v1/medias/...",
      "tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?..."
    }
  ]
}

⚠️ 重要:

• 写入前必须先调用上传素材接口获取 file_token
• 单个单元格附件数不超过 100
• 错误码 1254303: 附件未挂载到当前多维表格

---

单向关联 (type=18)

写入格式: link_record_ids 数组

{
  "fields": {
    "关联任务": {
      "link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
    }
  }
}

简化写入 (直接数组):

{
  "fields": {
    "关联任务": ["recHTLvO7x", "recbS8zb2m"]
  }
}

返回格式:

{
  "关联任务": {
    "link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
  }
}

限制:

• 单个单元格关联数不超过 500

---

双向关联 (type=21)

写入/返回格式: 与单向关联相同

{
  "fields": {
    "相关项目": {
      "link_record_ids": ["reclzUoBLn", "rec7bYQoX1"]
    }
  }
}

注意:

• 更新双向关联会同步更新对方表的对应字段
• 单个单元格关联数不超过 500

---

地理位置 (type=22)

写入格式: 经纬度字符串

{
  "fields": {
    "办公地址": "116.397755,39.903179"
  }
}

返回格式: 对象，包含详细信息

{
  "办公地址": {
    "location": "116.352681,40.01437",
    "pname": "北京市",
    "cityname": "北京市",
    "adname": "海淀区",
    "address": "学清路10号院学清嘉创大厦",
    "name": "Bytedance",
    "full_address": "Bytedance，北京市北京市海淀区学清路10号院学清嘉创大厦"
  }
}

字段说明:

• location: 经纬度 (格式: "经度,纬度")
• pname: 省
• cityname: 市
• adname: 区
• address: 详细地址
• name: 地名
• full_address: 完整地址

---

群组 (type=23)

写入格式: 对象数组，仅传 `id`

{
  "fields": {
    "协作群": [
      {"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "协作群": [
    {
      "id": "oc_d2a947abb78bbbbb12d4cad55fbabcef",
      "name": "测试部门",
      "avatar_url": "https://..."
    }
  ]
}

限制:

• 单个单元格群组数不超过 10

---

公式/查找引用 (type=20, type=19)

格式: 对象，包含 type、ui_type 和 value

{
  "是否延期": {
    "type": 1,                    // 底层数据类型
    "ui_type": "Text",            // UI 展示类型
    "value": [                    // 计算结果
      {
        "text": "✅ 正常",
        "type": "text"
      }
    ]
  }
}

字段说明:

• type: 底层数据类型枚举（1=文本, 2=数字, 5=日期...）
• ui_type: UI 展示类型（"Text"/"Number"/"Progress"/...）
• value: 计算结果，格式由 type 决定

示例 - 数字类型公式:

{
  "总价": {
    "type": 2,
    "ui_type": "Currency",
    "value": 1250.50
  }
}

示例 - 日期类型公式:

{
  "计算日期": {
    "type": 5,
    "ui_type": "DateTime",
    "value": 1675526400000
  }
}

⚠️ 注意:

• 公式字段为只读，不能通过写接口设置
• value 的数据结构取决于 type 对应的字段类型

---

系统字段

创建时间 (type=1001)

返回格式: Unix 毫秒时间戳

{
  "创建于": 1675526400000
}

⚠️ 只读: 不能通过写接口设置

---

最后更新时间 (type=1002)

返回格式: Unix 毫秒时间戳

{
  "更新于": 1675612800000
}

⚠️ 只读: 不能通过写接口设置

---

创建人 / 修改人 (type=1003, type=1004)

返回格式: 对象数组（与人员字段相同）

{
  "创建人": [
    {
      "id": "ou_8240099442cf5da49f04f4bf8f8abcef",
      "name": "黄泡泡",
      "en_name": "Amanda Huang",
      "email": "amandahuang@xxxgmail.com",
      "avatar_url": "https://..."
    }
  ]
}

⚠️ 只读: 不能通过写接口设置

---

自动编号 (type=1005)

返回格式: 字符串

{
  "工单号": "WO-20240226-0001"
}

⚠️ 只读: 不能通过写接口设置

---

🔍 常见错误与排查

字段类型不匹配 (错误码 1254015)

错误示例:

// ❌ 错误: 日期字段传字符串
{
  "fields": {
    "截止日期": "2024-02-26"  // 应该传时间戳
  }
}

// ✅ 正确
{
  "fields": {
    "截止日期": 1708905600000
  }
}

---

人员字段格式错误 (错误码 1254066)

常见原因:

1. 传入了不支持的字段:

// ❌ 错误
{
  "负责人": [
    {"name": "张三"}  // 只能传 id
  ]
}

// ✅ 正确
{
  "负责人": [
    {"id": "ou_xxx"}
  ]
}

2. user_id_type 不匹配:

# 请求时指定了 user_id_type=open_id，但传的是 union_id

3. 跨应用传 open_id:

不同应用的 open_id 不能交叉使用，建议使用 user_id

---

附件未挂载 (错误码 1254303)

原因: 直接传入外部 file_token

解决:

1. 先调用上传素材接口上传到当前多维表格 2. 使用返回的 file_token 写入记录

---

字段名不存在 (错误码 1254045)

原因: 字段名称不完全匹配（可能有空格、换行、特殊字符）

排查:

1. 调用列出字段接口获取准确字段名 2. 检查首尾空格、换行符

---

超链接字段转换失败 (错误码 1254068)

原因: 缺少 text 或 link 字段

// ❌ 错误
{
  "参考链接": {
    "link": "https://example.com"  // 缺少 text
  }
}

// ✅ 正确
{
  "参考链接": {
    "text": "示例网站",
    "link": "https://example.com"
  }
}

---

📌 最佳实践

1. 批量写入优化

{
  "fields": {
    "任务名称": "拜访客户",
    "负责人": [{"id": "ou_xxx"}],
    "截止日期": 1708905600000,
    "标签": ["重要", "紧急"],
    "是否完成": false
  }
}

建议:

• 一次性传入所有字段，避免多次调用
• 只传需要设置的字段，不必包含所有列

---

2. 清空字段值

方法 1: 传 null

{
  "fields": {
    "负责人": null,
    "标签": null
  }
}

方法 2: 传空数组/空字符串（根据字段类型）

{
  "fields": {
    "负责人": [],
    "任务名称": ""
  }
}

---

3. 时间戳转换

JavaScript:

// 北京时间字符串 → Unix 毫秒时间戳
const timestamp = new Date("2024-02-26 14:00").getTime()  // 1708927200000

// Unix 毫秒时间戳 → 日期字符串
const date = new Date(1708927200000).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })

Python:

import datetime

# 北京时间字符串 → Unix 毫秒时间戳
dt = datetime.datetime(2024, 2, 26, 14, 0, 0)
timestamp = int(dt.timestamp() * 1000)  # 1708927200000

# Unix 毫秒时间戳 → 日期字符串
dt = datetime.datetime.fromtimestamp(1708927200000 / 1000)

---

4. 关联字段的级联更新

双向关联:

// 更新 Table A 的双向关联字段
{
  "fields": {
    "关联项目": {
      "link_record_ids": ["rec123"]
    }
  }
}
// Table B 的对应双向关联字段会自动更新

单向关联:

// 只更新当前表，不影响关联表
{
  "fields": {
    "参考任务": {
      "link_record_ids": ["rec456"]
    }
  }
}

---

🔗 参考链接

• 飞书开放平台 - 多维表格记录数据结构
• 新增记录接口文档
• 更新记录接口文档
• 上传素材接口