人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载本篇技术指南基于 CodePilot 仓库中飞书 OpenClaw 插件的feishu-bitableSkill 参考文档系统讲解飞书多维表格Bitable每种字段类型在创建create与更新update时所需的property参数结构——这是调用字段管理 API 时最容易出错、报错率最高的一环。读完本文你将掌握文本、数字、日期、单选/多选、进度/货币/评分、关联、公式等全部字段类型的合法 Property 写法理解超链接字段必须省略 property的特殊规则与 125408X 系列错误码的排查方法并能直接对照源码理解feishu_bitable_app_table_field工具的真实行为。本文内容主体来自 field-properties.md并在其基础上结合 SKILL.md、record-values.md、examples.md 与 app-table-field.js 源码实现深度扩充。什么是字段 Property创建与更新字段的核心参数在飞书多维表格 API 中创建字段POST /open-apis/bitable/v1/apps/:app_token/tables/:table_id/fields或更新字段PUT .../fields/:field_id时请求体由三个关键部分组成{ field_name: 任务描述, type: 1, property: { } }field_name字段名称type字段的基础类型枚举1文本、2数字、3单选、4多选、5日期、7复选框、11人员、13电话、15超链接、17附件、18单向关联、20公式、21双向关联、22地理位置、23群组、1001创建时间、1002最后更新时间、1005自动编号等property字段的附加配置对象其内部结构因type以及部分场景下的ui_type而异——单选需要options数组数字需要formatter关联字段需要table_id这就是本文要逐一拆解的内容。在 CodePilot 仓库的 app-table-field.js 中property被定义为Type.Optional(Type.Any(...))即可选、任意结构的参数校验责任完全落在调用方——传错结构不会在工具层报 schema 错误而是直达飞书 API 并返回125408X系列property 结构错误。因此构造正确的 Property 是字段操作成功的前提。重要约定type决定字段的底层数据类型而ui_type决定展示形态。最典型的是数字字段type2它可以通过ui_type衍生出进度Progress、货币Currency、评分Rating三种特殊显示字段它们的property结构各不相同下文会分别讲解。基础字段的 Property 结构1. 文本type1文本字段的 Property 为空对象或直接省略{ type: 1, field_name: 任务描述, property: {} }使用注意默认ui_type为Text单个单元格最多10 万字符写入值支持富文本格式提及人、超链接等返回时为对象数组结构详见 record-values.md 的文本章节。2. 数字type2Property 结构仅含可选参数formatter数字显示格式{ formatter: 0 }formatter可选值与展示效果对照formatter显示效果0整数默认0.0一位小数0.00两位小数0,000千分位0.00%百分比完整示例——创建工时字段并按两位小数展示{ type: 2, field_name: 工时, property: { formatter: 0.00 } }5. 日期type5Property 结构{ date_formatter: yyyy/MM/dd, auto_fill: false }date_formatter可选日期显示格式默认yyyy/MM/ddauto_fill可选是否自动填充为创建时间。date_formatter常用格式格式串示例输出yyyy/MM/dd2021/1/30yyyy-MM-dd HH:mm2021/1/30 14:00MM-dd1月30日MM/dd/yyyy01/30/2021dd/MM/yyyy30/01/2021示例{ type: 5, field_name: 截止日期, property: { date_formatter: yyyy-MM-dd HH:mm, auto_fill: false } }配套提醒日期字段在写入记录值时必须使用毫秒时间戳如1674206443000传字符串或秒级时间戳会触发错误码 1254064详见 record-values.md。7. 复选框type7Property 为空对象或省略{ type: 7, field_name: 是否完成, property: {} }写入记录值时使用布尔值true/false。注意源码 app-table-field.js 中复选框与超链接一样被特殊处理——即使传了空对象{}也会被工具层强制移除以避免 API 报错。13. 电话号码type13Property 为空对象或省略{ type: 13, field_name: 联系电话, property: {} }使用注意电话号码格式需符合正则(\)?\d*最大长度 64 字符。选择字段单选与多选3. 单选type3Property 的核心是options数组每个选项由name和可选color组成{ options: [ { name: 进行中, color: 0 }, { name: 已完成, color: 10 } ] }颜色编号color范围 0-54其中 0 为红色、10 为绿色、20 为蓝色完整映射表见飞书官方文档使用时可参考 examples.md 中 0 红、1 橙、10 绿、20 蓝的标注。完整示例——创建任务状态字段{ type: 3, field_name: 任务状态, property: { options: [ {name: 待开始, color: 0}, {name: 进行中, color: 20}, {name: 已完成, color: 10} ] } }使用注意选项总数不超过20,000 个创建时不能指定选项 IDid字段系统会自动生成更新字段时需保留已有选项的id详见下文更新字段时的特殊规则。4. 多选type4Property 结构与单选完全相同{ options: [ {name: 紧急, color: 0}, {name: 重要, color: 10} ] }使用注意选项总数不超过20,000 个单个单元格内选项数不超过1,000 个。写入记录值时单选传字符串如进行中多选传字符串数组如[紧急, 重要]若传入不存在的选项名会自动创建新选项——这与 Property 中options的显式定义互为补充详见 record-values.md。特殊显示字段数字类型的四种皮肤以下四类字段的type均为 2数字通过ui_type区分展示形态且各有独立的 Property 结构。进度type2, ui_typeProgress{ min: 0, max: 100, range_customize: false }min必填最小值取值范围0-1max必填最大值取值范围1-100range_customize可选为true时用户可输入超出范围的值。示例——创建完成进度字段{ type: 2, field_name: 完成进度, ui_type: Progress, property: { min: 0, max: 100, range_customize: true } }进度字段写入值使用 0-1 范围的小数如0.75表示 75%见 examples.md。货币type2, ui_typeCurrency{ currency_code: CNY, formatter: 0.00 }currency_code必填货币类型formatter可选数字格式。currency_code常用值代码货币符号CNY人民币¥USD美元$EUR欧元€GBP英镑£JPY日元¥HKD港元$飞书官方支持 20 种货币。示例——创建预算字段{ type: 2, field_name: 预算, ui_type: Currency, property: { currency_code: USD, formatter: 0,000.00 } }货币字段写入值仍为普通数字如5000.50。评分type2, ui_typeRating{ min: 1, max: 5, rating: { symbol: star } }min必填最小值max必填最大值rating.symbol可选评分图标样式。symbol可选值star星星默认、heart爱心、thumbsup赞、fire火焰、smile笑脸、lightning闪电、flower花朵、number数字。示例——创建优先级字段{ type: 2, field_name: 优先级, ui_type: Rating, property: { min: 1, max: 5, rating: { symbol: fire } } }评分字段写入值为整数如4。条码type1, ui_typeBarcode条码字段的底层类型是文本type1通过ui_typeBarcode展示Property 控制录入方式{ allowed_edit_modes: { manual: true, scan: true } }manual是否允许手动录入scan是否允许扫码录入。示例——只允许扫码录入的商品条码字段{ type: 1, field_name: 商品条码, ui_type: Barcode, property: { allowed_edit_modes: { manual: false, scan: true } } }邮箱type1, ui_typeEmail邮箱字段的底层类型同样是文本type1Property 为空对象或省略{ type: 1, field_name: 联系邮箱, ui_type: Email, property: {} }关系字段的 Property 结构11. 人员type11{ multiple: true }multiple可选是否允许多个人员默认true。示例——创建只允许单个人员的负责人字段{ type: 11, field_name: 负责人, property: { multiple: false } }使用注意单个单元格人员数不超过1,000记录值只支持传入id字段open_id / union_id / user_id格式为对象数组[{id: ou_xxx}]且id类型需与请求的user_id_type一致详见 record-values.md。15. 超链接type15——最特殊的字段超链接字段必须完全省略property参数不要传递任何值包括空对象{}{ type: 15, field_name: 参考链接 }⚠️经实测验证的特殊要求✅ 正确完全省略property参数❌ 错误property: {}会报URLFieldPropertyError❌ 错误传递任何 property 值。这是飞书 API 的特殊行为超链接字段即使传空对象也会报错。在仓库源码 app-table-field.js 中可以看到工具层专门对此做了兜底——检测到type 15且传了property时会记录告警日志并强制置为undefined后再调用 API避免URLFieldPropertyError。也就是说即使调用方误传了 property通过该工具创建字段也不会报错但直接调用飞书原生 API 时必须严格遵守省略规则。17. 附件type17Property 为空对象或省略{ type: 17, field_name: 附件, property: {} }使用注意单个单元格附件数不超过100写入记录前需先调用飞书上传素材接口获取file_token且该文件必须上传到当前多维表格错误码 1254303 即附件未挂载到当前表格完整流程见 examples.md。18. 单向关联type18{ table_id: tblXXXXXXXX, multiple: true }table_id必填关联的数据表 IDmultiple可选是否允许多条记录默认true。示例——创建关联到任务表的关联任务字段{ type: 18, field_name: 关联任务, property: { table_id: tblsRc9GRRXKqhvW, multiple: true } }使用注意单个单元格关联数不超过500单向关联只影响当前表更新时不会级联更新对方表单向关联允许关联自身所在的数据表。21. 双向关联type21与单向关联相比双向关联额外要求back_field_name对方表的反向字段名{ table_id: tblXXXXXXXX, back_field_name: 反向字段名, multiple: true }table_id必填关联的数据表 IDback_field_name必填对方表的双向关联字段名multiple可选是否允许多条记录。示例——创建相关项目字段{ type: 21, field_name: 相关项目, property: { table_id: tblAnotherTable, back_field_name: 关联的任务, multiple: true } }使用注意单个单元格关联数不超过500对方表会自动创建对应的双向关联字段例如在任务表创建指向项目表的双向关联时项目表会自动生成关联的任务字段见 examples.md更新双向关联会同步更新对方表的对应字段级联更新。22. 地理位置type22{ location: { input_type: not_limit } }input_type可选值值含义only_mobile仅允许移动端实时定位not_limit无限制默认示例——创建办公地址字段{ type: 22, field_name: 办公地址, property: { location: { input_type: only_mobile } } }地理位置字段的写入值为经纬度字符串如116.397755,39.903179返回时包含省市区等详细地址信息见 record-values.md。23. 群组type23Property 为空对象或省略{ type: 23, field_name: 协作群, property: {} }使用注意单个单元格群组数不超过10 个写入值格式为对象数组[{id: oc_xxx}]仅传id字段。高级字段的 Property 结构20. 公式type20公式字段的 Property 基础结构{ formula_expression: bitable::$table[tblXXX].$field[fldYYY]*2 }formula_expression为可选参数公式语法可引用本表字段$field[fldXXX]或跨表字段bitable::$table[tblXXX].$field[fldYYY]。示例——创建总价字段{ type: 20, field_name: 总价, property: { formula_expression: bitable::$table[tblMain].$field[fldQty] * $field[fldPrice] } }使用注意创建字段时不支持设置公式表达式即create时该参数不可用只能后续更新公式字段是只读的不能通过写接口设置记录值。特殊场景对于某些多维表格公式字段还需要额外设置type参数——通过飞书获取多维表格元数据接口的formula_type字段判断是否需要{ type: 20, field_name: 计算字段, property: { type: { data_type: 2, ui_property: { formatter: 0.00, currency_code: CNY }, ui_type: Currency } } }内层type对象字段说明data_type公式结果的数据类型1文本2数字5日期……ui_propertyUI 展示属性如数字的formatter、货币的currency_codeui_typeUI 类型Number / Progress / Currency / Rating / DateTime。公式字段的读取结果格式为{type, ui_type, value}对象详见 record-values.md。1001. 创建时间type1001{ date_formatter: yyyy/MM/dd }date_formatter可选日期格式取值同日期字段见上文 type5。示例{ type: 1001, field_name: 创建于, property: { date_formatter: yyyy-MM-dd HH:mm } }创建时间字段为系统字段只读返回值为 Unix 毫秒时间戳。1002. 最后更新时间type1002Property 结构与创建时间相同{ date_formatter: yyyy-MM-dd HH:mm }同样为只读系统字段返回毫秒时间戳。1005. 自动编号type1005自动编号字段的 Property 是结构最复杂的一类核心是auto_serial对象{ auto_serial: { type: auto_increment_number, options: [] } }auto_serial.type编号规则类型auto_increment_number纯自增数字或custom自定义编号规则options仅typecustom时需要定义编号的拼接规则段。options中支持的规则类型规则类型说明value 约束system_number自增数字位数value: 1-9fixed_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自动编号字段只读读取值为字符串如WO-20240226-0001。常见错误码速查表125408XProperty 结构错误当调用字段创建/更新接口收到下表错误码时优先检查对应字段类型的property结构错误码字段类型说明1254080文本property 结构错误1254081数字property 结构错误检查 formatter1254082单选property 结构错误检查 options 数组1254083多选property 结构错误检查 options 数组1254084日期property 结构错误检查 date_formatter1254085复选框property 结构错误1254086人员property 结构错误检查 multiple1254087超链接必须省略 property 参数传空对象也会报错1254088附件property 结构错误1254089单向关联property 结构错误检查 table_id1254090查找引用property 结构错误1254091公式property 结构错误1254092双向关联property 结构错误检查 table_id 和 back_field_name1254093创建时间property 结构错误1254094最后更新时间property 结构错误排查方法论对应 SKILL.md 的指引创建/更新字段时收到125408X错误码property 结构错误→ 对照本表定位字段类型检查对应 Property 参数写入记录时收到125406X错误码字段值转换失败→ 对照 record-values.md 检查记录值格式日期毫秒时间戳、人员[{id}]、超链接对象等需要完整操作流程与参数示例 → 查阅 examples.md。更新字段时的特殊规则调用updateaction 更新字段时需要遵守以下规则原文档 源码交叉印证必须保持字段类型一致type和ui_type不能变更更新请求会携带原type见 app-table-field.js 的合并逻辑单选/多选更新选项已有选项必须保留id新增选项只传name和color不传id如果只改字段名可以只传field_name——工具会自动查询当前字段的type和property并合并提交源码中finalType、finalProperty的自动补齐逻辑即对应此规则用户传值优先否则用查询结果兜底关联字段的 table_id不能修改为不同的表。超链接/复选框字段的更新提醒源码中 create 分支对 type15 与 type7 强制移除 property更新分支则遵循用户传的 property 优先否则使用查询到的当前 property的合并策略因此更新这两类字段时同样建议不传 property避免把空对象写回导致报错。结合源码看Property 参数在工具层的处理链路在 CodePilot 仓库中feishu_bitable_app_table_field工具对应 app-table-field.js底层调用飞书 Bitable v1 的四个端点创建字段POST /open-apis/bitable/v1/apps/:app_token/tables/:table_id/fields列出字段GET .../fields更新字段PUT .../fields/:field_id删除字段DELETE .../fields/:field_id其对 Property 的处理有两个值得注意的实现细节create 分支的防错兜底当type 15超链接或type 7复选框且调用方传入了property时工具会记录warn日志并强制propertyToSend undefined后提交避免URLFieldPropertyError等错误——这从源码层面印证了原文档中超链接字段必须省略 property的结论update 分支的自动补齐当调用方只传field_name改名场景而未传type/property时工具会先list查询当前字段信息再按用户传值优先、查询结果兜底的规则合并出完整的field_name、type、property后调用更新接口——这正是原文档如果只改字段名可以只传 field_name规则背后的实现机制。同时SKILL.md 还给出了一条强制流程建议写记录前先调用feishu_bitable_app_table_field的listaction 获取字段的type/ui_type再据此构造记录值格式可有效规避1254015字段类型不匹配类错误。结语与使用建议飞书多维表格的字段系统覆盖面广、Property 结构差异大是自动化操作中错误率最高的环节。总结三条核心经验先查后写无论是创建表结构还是写记录先list字段拿到准确的type/ui_type/property再构造请求能规避大部分格式错误按类型对表本文的字段分类基础/选择/特殊显示/关系/高级与错误码表1254080-1254094可直接作为排查手册使用超链接type15的省略 property规则是最易踩的特殊点善用配套文档record-values.md 解决值怎么写Property 之外的另一半examples.md 提供 8 个端到端场景示例含创建表两种模式、空行处理、附件上传、双向关联等三者配合即可覆盖多维表格字段管理的完整闭环。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐django-htmx模板标签实战Django与Jinja2两种引擎的完整配置教程django htmx模板标签实战Django与Jinja2两种引擎的完整配置教程 想要为你的Django项目添加现代化的交互体验 django htmxpip 安装 IsaacLab 报错找不到 rsl-rl3 条修法 3 分钟跑通pip 安装 IsaacLab 报错找不到 rsl rl3 条修法 3 分钟跑通 在终端执行 pip 安装 IsaacLab 时进度条走到一半突然提示找不人工智能强化学习机器人具身智能深度学习NocoBase数据表字段类型全解析从基础类型到自定义字段NocoBase数据表字段类型全解析从基础类型到自定义字段 NocoBase作为一款极易扩展的无代码/低代码开发平台其数据表字段类型系统为用户提供了从基础数低代码后端前端人工智能AI 应用工作流自动化上一篇Winlator版本兼容性不同Wine版本适配方案下一篇Xberg C 批量 URI 文档提取实战ExtractBatchAsync 与按输入粒度覆盖配置Per-Input Config深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考